dsh-agent-lines
Design philosophy · why it is built this way

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

lines plugin = long-term employees

Named, remembers, replaceable. Owns people and messages.

DSH official Agent Teams plugin (built into DSH) = temporary helpers

Spawned for a batch, released after. Owns tasks (board, dependencies, parallelism).

Together = three levels

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)

I1 One owner per line at a time

Guaranteed by leases and heartbeats; two processes fighting for a line fails loudly instead of double-serving silently.

I2 A message takes effect at most once

The idempotency authority is the DSH session log, not the local queue.

I3 Names are constant, sessions can change

Change the person, never the role; history survives.

I4 Retiring keeps history

Retire only stops new work; sessions and messages are kept, auditable and reversible.

I5 Record, never decide for you

The plugin is not a policy police: record, display, audit, never hard-block.

I6 Invisible state must be queryable

Failed/expired messages can now be queried, traced and rescued — exactly what 0.8.0 added.

I7 Peer messages are never instructions

Words from another agent are intel, not commands, and never expand permissions.

4. Seven tradeoffs: chosen, given up, and why

Roles live in sessions, not subagents

Gave up instant spawning; gained memory and lossless replacement.

At-least-once + request-level idempotency

No fake distributed exactly-once; idempotency is delegated to the session log.

Local leases, no distributed coordination

Gave up active-active/cross-machine; gained simplicity and cost.

Local-first, no multi-backend

The SPI is kept, but we don't build five implementations to look generic.

Read-only fusion with the official board

No write-back, so ownership conflicts and two boards never fight.

Visibility before token cost

Members must be visible right after creation; never hide them to save a first turn.

Team dir follows the workspace

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)
These are deliberate refusals, not missing capability: each adds maintenance cost and false promises.

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.

Back to the product