coordinate

Multi-session coordination. The pipeline tells you to fragment — /spec and /draft-plan recommend a fresh session per phase — so when you plan several things and spin up multiple live sessions (a /execute window per work-stream), they drift: session A doesn't know what B decided. coordinate is the shared memory those live, peer sessions coordinate through.

It is not orchestrate (which dispatches fire-and-forget subagents within one session and reconverges them). These are independent, user-driven peer sessions with no parent — so coordination is a passive shared board, read-at-action and written-on-change, no daemon or polling. (Folding this into orchestrate's deferred background-session runtime is a later increment.)

The board

<project-root>/.claude/sessions-active.md — gitignored, ephemeral live state (add .claude/sessions-active.md to .gitignore if .claude/ isn't already ignored). One row per active session:

# Active sessions
<!-- coordinator: <label or "none"> -->

| Session | Owns | Status | Updated | Hand-offs / assignments |
|---------|------|--------|---------|-------------------------|
| auth    | slug:auth-rework, src/auth/* | executing step 3 | 2026-06-11T14:20 | — |
| ui      | slug:settings-ui, src/ui/settings/* | drafting plan | 2026-06-11T14:05 | from auth: "changed the token contract — re-read before wiring" |

Session is a short stable label (the slug it's working on, or a user-given name like auth/ui). The board carries no secrets — paths + labels only.

Hidden identity block (write-authority + liveness). Below the visible table, a hidden HTML-comment block maps each label to the session that owns it:

<!-- identities
auth = { session: e3bd7da4-..., host: DESKTOP-X }
ui   = { session: 1a2b3c4d-..., host: DESKTOP-X }
-->

Two mechanisms read this block, both detailed below: a write-authority check (a row-mutating write must come from the session whose identity is recorded, else it is rejected-and-recorded — see Update) and a liveness check (a row is live only while its owning session's transcript is still being written — see Check). The block stays hidden so the visible table is unchanged; it still carries no secrets — a session_id is already on disk as a transcript filename, and host is a machine name. The transcript path is derived, not stored: ~/.claude/projects/<canonical-cwd-slug>/<session_id>.jsonl.

When to run

• /coordinate / /coordinate register — register (or update) this session on the board.
• /coordinate check — read the board: what others own, any hand-offs/assignments for me, any collisions.
• /coordinate handoff <session> <note> — leave a note for another session.
• /coordinate coordinator — claim (or release) the coordinator role.
• /coordinate done — tear down this session's row on close.
• Natural language: "what are other sessions doing", "hand this off to the UI session", "are we colliding".
• Mode A for the manual verbs. The board can also run auto — see Auto mode (opt-in, off by default).

Auto mode (opt-in, enabled:false by default)

The board is gitignored, ephemeral live state — not a memory, not a spec, not the changelog. So every board write falls outside the never-silent-write set: confirming each register/check/update/done is pure ceremony with no canonical-write risk behind it. Auto mode dials those board ops up so the user stops proc'ing every read and write.

Gated on the autonomy contract's ask field (read the effective autonomize contract) and on the hook-config enabled flag (defaults off — opt in per session) (the coordinate-autoregister.js hook, registered under hook-config.json):

• ask=forks-only / until-blocked → register (at session start), check (at the boundaries below), update (on an owned-scope change), and done (at /wrap) run auto, no per-action confirm. All write only the ephemeral board.
• ask=every-step → revert to today's behavior: every board read/write is an invoked action (the user opted into confirmation).

The one thing auto mode never does on its own: resolve a collision (see Check below). Detection is auto; the decision is always the user's.

Procedure

Register (start of a work-stream)

1. Resolve this session's label (its slug, or ask for a short one). Read the board (create it if absent).
2. Collision check before claiming: if another active row Owns an overlapping slug or file-scope, surface it — "ui already owns src/auth/* (executing step 3). Coordinate before both write there." Route the resolution to the user (serialize, re-scope, or proceed knowingly) — never auto-resolve.
3. Write/update this session's row: Owns (slug + file-scope), Status, Updated (timestamp from the environment, not invented).
4. Record this session's identity. Read this session's session_id from the environment-surfaced session path — the scratchpad path's UUID is the session_id, and it maps to the transcript ~/.claude/projects/<slug>/<session_id>.jsonl. Write { session: <session_id>, host: <hostname> } into the identity block for this label. The id is read, never invented — an invented id defeats the whole point of attribution. If the session path genuinely cannot be resolved, record host-only and mark the row unverifiable rather than fabricating an id; the write-authority and liveness checks then degrade to "unknown" for this row (never to a false match or a false "dead").

Check (at boundaries)

Read the board and surface, concisely: what each other session owns + its status; any hand-offs/assignments addressed to this session (act on them — e.g. re-read a changed contract before proceeding); any collisions; any rejection notes left by the write-authority check (a mismatched write happened — surface it, it means two sessions disagree about who owns a row); any stale rows (see liveness below — flag for the user to clear, don't delete silently).

Liveness — authoritative process check first, transcript mtime as the fallback. The Updated timestamp is self-reported: a hung session may have written it just before hanging, and a healthy session mid-long-turn may not have refreshed it. It stays in the table as a human-readable hint but is not the liveness signal.

Primary — the live-session registry (same host only). ~/.claude/sessions/<pid>.json files record {pid, sessionId, cwd, startedAt, procStart, ...} for running sessions. For each same-host row: scan the registry for an entry whose sessionId matches the row's recorded id. Entry found → verify the process: the PID exists and its start time is consistent with the registry's startedAt (within ~2 minutes — the start-time match is what defeats PID reuse). Both hold → live, verified (proof of life, not just activity). PID dead or start-time mismatched (a reused PID) → the session is gone; surface the row as possibly stale with "process gone" as the reason. This registry is undocumented and version-coupled — treat it defensively: no registry entry for the id, an unparseable file, or an unexpected shape means fall through to the mtime signal below, never "dead" and never an error. Absence from an undocumented registry is not evidence of death.

Fallback — transcript mtime. Resolve the owning session's transcript from its recorded session_id (~/.claude/projects/<slug>/<session_id>.jsonl) and stat its mtime — a single, fast, cross-platform check that rides this existing read, no background watcher:

• mtime within the threshold → live; honour the claim.
• mtime older than the threshold → surface as possibly stale ("owner may be gone") — a note, never an eviction.
• transcript not present on this host (a synced or SSH-shared home can hold another host's transcripts, whose sessions this machine cannot see) → unknown, never stale-and-reclaimable. Absence of the file here is not evidence of death there. Cross-host rows never get the registry check either — PID namespaces don't compare across machines.

Threshold: 15 minutes of no transcript write. Deliberately generous — mtime is evidence of activity, not proof of life (it cannot tell a crashed session from one thinking through a long single turn that writes nothing to the transcript for minutes), and since a stale row only ever warns (never evicts — see below), a false "possibly stale" on a slow-but-live session costs a dismissible note while a too-eager threshold would cry wolf. When in doubt, longer.

Under auto mode, check fires at exactly three boundaries — not mid-turn, not on a timer:

1. Right after auto-register (session start) — surface the current board so the session starts aware.
2. Right before this session claims a new scope — the load-bearing catch: this is the moment a collision matters (two sessions about to write the same scope). No hook channel exists mid-session, so detection rides this natural read rather than a background watcher.
3. At /wrap (session close) — surface any hand-offs this session left that the target hasn't picked up.

Collision handling — surface-and-ask, never auto-resolve. When a check (especially the before-claim one) finds another active row Owns-overlapping this session's intended scope, surface it and route the resolution to the user — serialize / re-scope / proceed-knowingly. This holds under auto mode too: detecting the collision is auto (read-only), but the resolution is a decision, not a write — it is always asked, never auto-resolved.

Update (on change)

At meaningful checkpoints (step done, a decision, a contract change other sessions depend on, finishing), update this session's Status + Updated, and leave a hand-off when a change affects another session's work.

Row ownership — the race-safety rule (auto mode). Each session writes only its own row (append its row if absent, update its own line otherwise). Concurrent auto-writes target different rows, but the board is one file: a stale read-modify-write can still drop another session's row. Re-read the board immediately before every write; if a row you didn't touch changed since your read, re-apply your edit on the fresh content. Failure mode: last-write-loses on a true simultaneous write — detectable at the next check (your row missing → re-register and note the collision). No file lock — a lock on gitignored ephemeral state buys stale-lock failure modes for no gain. (This is why auto-register/update are race-safe to run without a confirm.)

Write-authority check — identity must match before a row's OWN state is mutated. The check governs writes that change a row's own state: its Owns, Status, recorded identity, or its removal. Before such a write, compare the writer's session_id against the identity recorded for that row's label. Writing your own row matches trivially — the common path, unaffected.

• Match (your own row) → apply.
• Mismatch (another session's own-state) → reject and record. Do not apply, and do not silently drop — write a short dated rejection note onto the contested row (or a rejection line under the board): "rejected <field> write from <writer-label> — row owned by <recorded-label>." A mismatched write is evidence — a confused session, a stale board re-read, a session resumed from old context — and dropping it destroys that evidence — a rejected write is how two sessions disagreeing about board state surface that disagreement instead of silently resolving it. The rejection is read at the next Check.

Not gated — addressed communication. Leaving a hand-off/assignment in another row's Hand-offs column is addressed-to that session, not a mutation of its own state, and stays allowed for any session (the existing handoff verb) — that is how peers talk. A coordinator writing an assignment to another row is likewise allowed (it is the coordinator's purpose) and stays propose-confirm as it already is, not auto. The identity check blocks impersonating another session's ownership, never communicating with it.

Unverifiable rows (identity recorded host-only, per Register step 4) are treated as unknown, not as a free-for-all: surface the ambiguity to the user rather than either applying or hard-rejecting.

Coordinator (optional, opt-in)

A session can claim the coordinator role (set <!-- coordinator: <label> -->). The coordinator may write assignment rows / hand-offs directing other sessions ("ui: take the settings screen next"). Other sessions pick up assignments on their next check. Coordinator is advisory shared state — it cannot force another session (peers have no parent); it's a way to divide work through the board. Release it on done.

Coordinator assignment stays gated even in auto mode. Auto mode dials up a session's own board ops (register/check/update/done for its own row). But a coordinator writing an assignment row for another session is a decision affecting a different agent — closer to a fork than a self-status update — so it stays propose-confirm, not auto, regardless of the ask posture. Writing your own status is routine; assigning someone else's work is not.

Done (teardown)

On close, remove this session's row (or mark Status: done). Surface any hand-offs it left that the target hasn't picked up yet.

More in reference.md: What coordinate does NOT do, relationship to other organs.