coord/DESIGN.md

# Agent coordination design

Status: implemented. Packaging and installation: [`README.md`](README.md). Maintainer invariants:
[`CLAUDE.md`](CLAUDE.md).

## Boundary that actually isolates work

The shared Jujutsu working copy is also `@`. Every `jj` command snapshots all peer filesystem
edits into whichever change currently owns that checkout. File leases cannot prevent this because
the absorbing session did not write those files. This caused duplicate work, foreign features
inside unrelated commits, and one temporary loss/recovery incident.

Writable main agents therefore use independent colocated `jj git clone` instances. They have
independent operation logs, working-copy commits and Git backends, and ordinary Git-aware Nix
flake discovery works in them. The canonical checkout is for read-only inspection and one
explicit integration owner.

Every managed checkout receives a unique `agent-<full-instance-id>` jj workspace name, a
namespaced `agent/<task>/<full-instance-id>` bookmark, and a working-copy description carrying
the full coordinator instance ID. These make parallel heads legible and handoffs explicit; they
remain presentation/navigation metadata, while stored full change and commit IDs are authority.
Agents do not move shared bookmarks. The integration owner alone does so under an exact resource
lease.

Native `jj workspace add` remains available behind `--native-workspace`. It is useful when sharing
one repository is intentional, but it shares the operation log/object store and is not the
default isolation boundary. In this repository its secondary directory also lacks an ordinary
`.git`, so `nix flake metadata .` does not discover the colocated Git flake normally.

The compatibility default for managed clones is `/var/tmp/fleet-audit`, the large
non-snapshotted scratch dataset in the original deployment. Other installations should select a
safe local dataset with `--scratch-root`; avoid any location whose capacity, snapshots, backup,
or mount semantics make disposable clones expensive.

## Identity

- A conversation ID is durable across resume.
- A runtime ID is a fresh UUID for one live attachment to that conversation.
- Human/LLM-facing runtime and workspace identities are exact five-word handles derived from the
  full opaque ID with a domain-separated SHA-256 mapping over 128 common words (35 display bits).
  Exact handle matches carry authority; prefixes never do, and an unlikely collision is refused
  rather than guessed.
- Full UUIDs remain canonical in SQLite, tmux metadata, launcher environments and deterministic
  audit exports. Handles are aliases, not secrets and not replacements for internal entropy.
- Managed launches export the exact workspace record as `COORD_WORK_ID`. It may default only
  low-blast-radius workspace-local operations after proving that the live runtime owns the record
  and `cwd` is inside its registered path. Resource scopes and destructive targets stay explicit.
- The launcher stores full IDs in tmux user options. Window names are presentation only:
  `<short-task>-<sid4>`.

The distinction prevents a stale pre-resume process from renewing or releasing the resumed
process's resources.

## Transactional state

Runtime state is a private SQLite WAL database at
`$XDG_STATE_HOME/fleet-agent-coord/<project-id>.sqlite3` (override with `COORD_DB`). It is outside
every agent-writable clone, directory mode 0700 and database/WAL mode 0600.

This database is deliberately host-local. It coordinates Claude and Codex processes sharing one
machine; it does not serialize work performed from different fleet nodes. Cross-host deployment
still needs an explicit human/integration owner (or a future authenticated service).

Filesystem isolation also does not isolate external mutable state. Concurrent agents must use
distinct service ports, database/schema names, containers, and temporary/output directories when
their tools would otherwise share them. Dependency download caches may be shared only when their
cache protocol is concurrency-safe; mutable build trees must remain workspace-local.

All conflict-check-plus-claim operations use `BEGIN IMMEDIATE`. Resource names are exact,
repository-relative hierarchical names. Equal names and ancestor/descendant names overlap.
The compatibility matrix is:

| Existing | Requested append | Requested exclusive |
|---|---:|---:|
| append | allowed | refused |
| exclusive | refused | refused |

Leases cover files and global operations alike, for example:

- `tests/checks.nix`
- `integration/master`
- `push/origin/master`
- `activate/home/tpp15s`
- `deploy/system/nix-control`
- `external/fleet-dotfiles`

Heartbeats renew both runtime presence and held leases. Expired/dead runtime leases are reaped
transactionally. Partial release removes only the named resources.

Messages have monotonic integer IDs. A broadcast snapshots its recipient set at send time.
Delivery transitions `queued → delivered → acked`. Delivered context repeats at hook boundaries
until the receiving agent explicitly runs `coord ack <message-id>`. The first delivery carries the
body; later boundaries carry the message ID, sender handle, kind and body digest plus an explicit
`coord inbox --peek` recovery command. A rejected/lost harness response therefore cannot silently
consume it, while a long body is not reinjected on every tool call.

Audit events remain append-like in SQLite and can be exported deterministically as JSONL with
`coord audit`.

## Action composition

`coord batch ACTION : ACTION...` reduces agent/tool round trips without inventing a second command
language: every action is parsed by the ordinary CLI parser and executed by its ordinary handler.
It runs sequentially, stops on the first nonzero result, and can return compact human output or
one JSON envelope. The separator is a standalone token, so quoted message punctuation is not
special.

A batch is intentionally not atomic and performs no rollback. Each state-changing action retains
its own transaction, validation and audit event. The allowlist excludes clone creation/removal,
tmux process replacement and integration queueing. Generic composition must not become a way to
hide destructive scope or ambiguous external side effects.

Every nested action inherits the outer batch's already-resolved exact runtime. Identity flags are
rejected inside action token streams and the resolved nested runtime is asserted equal before
dispatch, preventing one batch from mixing or impersonating audit/lease authority.

Remote publication, integration, activation and deployment need purpose-built workflows with
explicit resources and expected object IDs. In particular, a future publish workflow must acquire
the exact push lease, authoritatively read the network remote, refuse an unexpected base, avoid
force, reread the new remote head, and retain the lease with recovery instructions after an
ambiguous mutation result.

## Enforcement and degradation

The shared hook recognizes Claude `Edit`/`Write` paths and every Codex `apply_patch` source and
`Move to:` destination. It canonicalizes against the hook payload's working directory and blocks
a peer's exclusive overlapping lease.

This is scoped enforcement, not a shell parser. Shell writers, formatters, generators and VCS
operations remain advisory. Isolation is what makes that honest limitation safe. A private clone
can continue working if the coordinator is unavailable.

The hook and lifecycle bridge fail open on load, parse or database failure. A positively
recognized conflicting write fails closed. Denial and `additionalContext` are separate branches
because Codex rejects a response containing both.

Claude subagents receive their own deterministic runtime UUID, derived from the full parent
conversation ID and hook `agent_id`. They therefore conflict, message, and lease independently
instead of inheriting the parent's authority. Writable subagents should still use their own
managed clone; the distinct identity makes accidental writes in the integration checkout fail
closed unless that subagent explicitly owns the resource.

## Workspace lifecycle and cleanup

Each record contains the full task/conversation/runtime identity, source and actual path, exact
base/current Jujutsu IDs, dependencies, planned/actual resources, gate/integration/lifecycle
states, immutable tmux IDs and an ownership token.

The default CLI view deliberately omits those machine fields. It prints handles, task/state, and
only the path needed to enter a newly created clone. `--verbose`, `--json`, and audit export are
explicit diagnostic/machine surfaces. Cleanup tokens remain private by default; normal removal
requires repeating the exact work handle and then compares the registry token with the on-disk
marker.

Lifecycle states support active, parked, resumed, archived, queued/integrating/lock-released/
integrated and removed work. Lock release is not integration evidence: a separate proof verifies
that the exact source commit is an ancestor of the exact target commit. Cleanup never guesses:

The current “queue” is an integration lock plus an auditable state machine, not a fair scheduler:
enqueue order and recorded dependencies are visible but do not automatically grant the next turn.
The integration owner adjudicates readiness and stale bases.

On acquisition, coord snapshots the isolated checkout and freezes its exact change and commit IDs
as the integration candidate. Release records the same full runtime and resource that acquired the
lock. Integration proof is rejected without matching owner/resource evidence and proves the frozen
candidate—not a stale create-time record—is an ancestor of the exact target. Cleanup also refuses
a workspace changed after that candidate was integrated.

- path must remain below the recorded scratch root;
- private registry token and on-disk `.jj` marker must agree;
- working copy must be clean;
- an advanced change must be released/integrated;
- automatic cleanup requires a passed or explicitly waived gate.

Missing, dirty, ungated or identity-mismatched directories remain recovery candidates.

Known independent clones can be recovered after database loss with explicit `work adopt`. Adoption
requires both `.jj/` and `.git/`, a path beneath the configured scratch root, and a source distinct
from the candidate. It validates exact Jujutsu IDs before rotating the ownership marker. There is
deliberately no directory-name scan or automatic adoption.

If older shared-checkout work was lost, recover read-only with
`jj --at-op=<op> --ignore-working-copy file show <path>`, then merge the recovered content into a
fresh isolated clone. Never restore a whole stale file over newer work.

## Tmux rules

Managed sessions discover project ownership through tmux user options and mutate objects only by
immutable `$session`, `@window` and `%pane` IDs returned by tmux. Names are never lookup targets.
Automatic window renaming is disabled. Codex resumes with `codex-direct resume <conversation>`;
Claude resumes with `claude-direct --resume <conversation>`.

`work close` revalidates those IDs and kills the exact window. It refuses when called from any
pane in the target window, because killing that window would terminate the coordinator before its
registry update. If the operator is attached elsewhere in the target session's last window, it
first switches to another managed session and otherwise refuses, preventing the surprising drop
to a plain outer shell.

The ordinary `codex`/`claude` helper also persists interactive resume invocations and forwards
their arguments to the session runner. Automation (`codex exec`, `claude -p`, pipes and non-TTY
calls) remains direct and status-faithful.

## Proved failure modes

Behavioral checks cover:

- eight-way exclusive race: exactly one winner;
- six simultaneous messages: no loss and monotonic IDs;
- exclusive/append matrix, hierarchical conflicts, renewal/expiry and partial release;
- truncated identity refusal;
- `apply_patch` move-destination blocking;
- repeated delivery until explicit acknowledgement;
- independent clone metadata and explicit native-workspace limitations;
- dirty, ungated, advanced and ownership-mismatched cleanup refusal;
- tmux name collision handling and immutable-ID-only mutations;
- distinct Claude subagent authority, explicit orphan adoption and exact-window close;
- real disposable `jj git clone --colocate` create/inspect/remove.

## Implementation language and versioning

Each standalone release carries a semantic `VERSION`, vendored into `.coord/VERSION` and exposed
by `coord --version`. The installer doctor reports both source and installed versions but still
compares every managed byte and executable mode; equal version strings are not integrity evidence.
Legacy installations without the marker are explicitly `unversioned` and can be repaired through
the same preflighted atomic plan as any upgrade. This adds observability without coupling runtime
SQLite schema state to package release numbering.

Python plus the standard-library SQLite driver remains the current best fit: hooks can run before
a Nix activation or build bootstrap, deployment has no compiled-artifact handoff, and the
transaction boundary lives in SQLite rather than process memory. A Go rewrite would improve
single-binary distribution, startup predictability and static typing, but would not improve the
isolation or locking model by itself. Those benefits do not currently justify a second
implementation and migration surface.

## Interface and context budget

Coordinator output crosses an unusually expensive boundary: lifecycle context and command output
are repeatedly injected into model context. The interface therefore follows these rules:

- managed environments infer caller identity; ordinary commands do not repeat it;
- required operands are positional (`claim integration/master`, `work create cache-review`);
- readable long options remain for genuinely optional semantics;
- default listings use exact word handles and suppress full IDs, conversations, paths and
  workspace rows not requested by the caller;
- JSON is compact and explicit, and ownership secrets are redacted unless a private recovery
  export opts in;
- full Jujutsu/Git IDs are stored as evidence but presentation output uses a sufficient display
  prefix only where no later command consumes it as authority.

This is a larger saving than removing the two dash characters from every option. Cryptic flags
can increase correction turns and negate their tiny lexical saving.

The executable hook source is cooperative infrastructure, not a security boundary: a writable
clone contains a writable copy, and hook trust is hash-pinned by each harness. Before deploying
incompatible database schemas, add explicit versioned migrations with backup/rollback and package
one immutable coordinator runtime through Home Manager. That packaging can use Python or Go; it
does not require a language rewrite.

## Third-party adjudication

The current system is intentionally small and local. MCP Agent Mail may later add a searchable
mail UI, and `tmux-agent-status` may add an operator sidebar, but neither is authoritative for
leases. Beads adds a useful task DAG at the cost of Dolt; Gas Town and Agent of Empires are
Git-worktree-oriented and too invasive as the coordination substrate. Any pilot must compose with,
not replace, the transactional resource and isolated-clone boundary.