fleet-lifecycle

Fleet Lifecycle

When the run directory is gone

.teammates/ is gitignored, so a clean checkout or a stray delete takes a run's bookkeeping with it. Rebuild it from git rather than hand-writing JSON:

node "$CLAUDE_PLUGIN_ROOT/scripts/cli.mjs" rebuild-state --run <runId> --plan <planPath> --root <project root>

It derives every task's state from its branch — merged or contributing is done, a branch that exists and contributes nothing is orphaned, no branch is pending — and refuses to overwrite state that still exists unless you pass --force. It reconstructs no gate history: a verdict is evidence that checks ran, and git carries branches, not evidence. Every phase of a rebuilt run has to be gated again before anything is reported done.

Map notes

For what a target project's modules are for — the part git statistics cannot supply — a run may carry hand-written notes on it, verified and refreshed with:

node "$CLAUDE_PLUGIN_ROOT/scripts/cli.mjs" map-notes --run <runId> --root <project root>

Exit 0 means the stored notes declare the commit the repository is on; the header is a string the writing agent was told to copy, so this is tamper-evident provenance and not proof — nothing observes which tree that agent actually read, and nothing detects a header edited afterwards. Exit 4 means there are none, they carry no header at all, they name a different commit, they were written for a different run, or the file could not be read, and it prints the exact prompt to dispatch. Exit 2 means git could not be read, so no comparison happened at all — read that as unknown, never as current. Dispatch a read-only agent with the printed prompt; it RETURNS the map and you write it to that path yourself, with the same command and --write:

node "$CLAUDE_PLUGIN_ROOT/scripts/cli.mjs" map-notes --run <runId> --root <project root> --write <path to the agent's returned text>

That reads the returned text from <path>, checks the same header plus a body check — text must remain once the header is stripped off, so an agent that echoes back only the line it was handed writes nothing — and only then writes it to the notes file: it exits 0 on a write and exits 2 if --write is given no path. Exit 4 covers every way that read, that validation, or the write itself can fail — nothing is written in any of those cases, and the printed message names the reason, so read the message rather than parsing the exit code alone. A teammate never writes this file, and nothing enforced ever reads it. The directory names that prompt carries are filtered — anything that is not a plain path segment is dropped — because that prompt is handed to an agent that has Bash and is gated by nothing.