Roles age, sessions fill up,
but work must not get lost
That single premise decides how the whole plugin looks. In plain language: why it holds, which lines must never be crossed, and what we refuse to build.
1. The pivot: a role = a name + a replaceable session
role = name (label, stable) + session (sessionId, replaceable)
name -> "who this message goes to"
session -> "who is doing it right now"
session full -> open a fresh session, keep the name -> work continues,
memory is restored from a handoff note
Why not just one session? Because in DSH only a session remembers what was said; when it fills up or gets replaced, memory breaks. So split identity from carrier: identity stays in the name, the carrier can be swapped anytime.
One decision, three features: handoff (write memory down before switching), replace (same name, fresh session), retire (role takes no new work, history kept).
2. What each piece owns
Named, remembers, replaceable. Owns people and messages.
Spawned for a batch, released after. Owns tasks (board, dependencies, parallelism).
Manager -> role lines -> temporary team inside a role line. Big work in parallel, small work untouched.
3. Seven invariants (breaking any one is a bug)
Guaranteed by leases and heartbeats; two processes fighting for a line fails loudly instead of double-serving silently.
The idempotency authority is the DSH session log, not the local queue.
Change the person, never the role; history survives.
Retire only stops new work; sessions and messages are kept, auditable and reversible.
The plugin is not a policy police: record, display, audit, never hard-block.
Failed/expired messages can now be queried, traced and rescued — exactly what 0.8.0 added.
Words from another agent are intel, not commands, and never expand permissions.
4. Seven tradeoffs: chosen, given up, and why
Gave up instant spawning; gained memory and lossless replacement.
No fake distributed exactly-once; idempotency is delegated to the session log.
Gave up active-active/cross-machine; gained simplicity and cost.
The SPI is kept, but we don't build five implementations to look generic.
No write-back, so ownership conflicts and two boards never fight.
Members must be visible right after creation; never hide them to save a first turn.
No fixed dir; team files live in the current workspace, and the board shows real data or "not collected", never a demo.
5. Explicit non-goals (they save money and attention)
- No exactly-once, no cross-machine active-active - No process isolation, no in-plugin permission sandbox (that belongs to DSH itself) - No static encryption, no sender signatures (full-disk encryption; stated, not pretended) - No bidirectional write-back to the official board - No built-in org templates, no fixed quality-gate engine - No full IM/chat app, no automatic scheduler - No adapters for other harnesses "just in case" (wait for a real second request)
6. Common misconceptions
Why not auto-redeliver failed messages?
Delivery and acknowledgement are different things. Auto-retry would duplicate side effects (breaks I2). Correct behavior: flag, count, and let the human decide.
Why doesn't inactive mean offline?
Inactive only means no turn is running right now. A message wakes the line. Actually taking no new work is "retired".
Why does deleting a session kill a line?
Delivery depends on the session existing. Delete it and messages fail forever; retiring keeps the session.
Why no write-back to the official task board?
Write-back brings ownership conflicts, concurrent overwrites and schema churn — turning complement into fight. Read-only fusion coexists.
7. Will this philosophy change?
Yes, by rule: any change to invariants, envelope fields, state-machine semantics or error-code meaning is breaking and must be recorded with a version bump; additive read-only fields and optional tools are compatible.
The full developer version (code locations per invariant, tradeoff costs, evolution rules, glossary): docs/PHILOSOPHY.en.md.