[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M77PKA0YG38W5D0ADNJDP3CP":3,"skill-same:01M77PKA0YG38W5D0ADNJDP3CP":258},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":14,"repositoryHtmlUrl":27,"repositoryHomepageUrl":6,"ownerHtmlUrl":28,"ownerBlogUrl":29,"ownerDescription":30,"updatedAt":31,"install":32,"resources":45},"01M77PKA0YG38W5D0ADNJDP3CP","fleet-ship",null,"Orchestrate parallel implementation across herdr panes for a backlog with independent chunks. Use when the user asks to ship multiple tasks as a fleet or run an unattended multi-agent build.","Necmttn\u002Fskills","Necmttn","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F5212808?v=4","01M77PDTX0P2888A46VQ6DREZG","Neco","01M77PDTXNATPR101437VV6H7Y",0,"MIT","https:\u002F\u002Fgithub.com\u002FNecmttn\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fengineering\u002Ffleet-ship\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: fleet-ship\ndescription: Orchestrate parallel implementation across herdr panes for a backlog with independent chunks. Use when the user asks to ship multiple tasks as a fleet or run an unattended multi-agent build.\n---\n\n# Fleet Ship - parallel herdr orchestration\n\nBefore run setup, assignment, completion, rotation, or teardown, read [Durable task delivery](..\u002Fherdr-agent-orchestration\u002Freferences\u002Fdurable-delivery.md).\nWorkers publish their assigned branches and maintain draft PRs. The coordinator owns review and merge.\nEvery saved research or exploration task uses the same delivery receipt.\n\nYou are the **orchestrator** (run on fable-5 or opus-5). Panes do the building; you plan the waves, route engines,\ngate reviews, merge, track on a kanban, and dogfood. This skill *composes* our normal ship workflow -\nit just runs it across many parallel herdr panes instead of one session.\n\n## Multi-orchestrator coordination (MANDATORY - several fleets run this repo concurrently)\nThe registry is **fleetboard** - a live board at `$FLEET_BOARD_URL` (default `http:\u002F\u002Flocalhost:7777`,\nserver + CLI in `~\u002FProjects\u002Ffleetboard`; VPS fleets set FLEET_BOARD_URL to the Mac's tailscale addr).\nDrive it with `bun ~\u002FProjects\u002Ffleetboard\u002Ffleetctl.ts \u003Cregister|heartbeat|claim|release|attn|event|events|deregister>`\n- claim returns exit 1 + holder when a resource is taken. Heartbeat each orchestrator wake. If the\nboard is unreachable, fall back to `docs\u002Fsuperpowers\u002Ffleet-runs\u002FACTIVE.md` in the target repo.\nLive lessons that forced this: a fleet rebased main under another fleet's staged merge; three merges\nlanded vitest-breaking test files; a port cleanup killed a sibling fleet's dev servers and a native\nbuild mid-compile.\n1. **Register on run start** (epic, status), **deregister on run end**, heartbeat between.\n2. **Claims are exclusive, TTL'd + FIFO** (Fleetboard v2 Durable Object alarm; #15 owns the mechanics -\n   this documents the protocol you follow, not the DO internals). A taken claim returns exit 1 + the\n   holder + your FIFO queue position; the queue position is HONORED - your turn comes in order, never\n   jump it or poll-race it. A claim whose TTL expires **auto-releases** - an expired holder has LOST the\n   claim (mid-merge expiry: see Merge under claim). **Claim discipline is REQUIRED, not nice-to-have:**\n   several gating machines merge this repo concurrently and the claim is the ONLY serialization.\n   Resources: `main-merge` (only the holder merges\u002Frebases main - the full flow is Merge under claim\n   below; others hold their gated branches and wait their queue turn), `sim:\u003Cudid>` (boot a SEPARATE\n   simulator per fleet - `xcrun simctl list devices available` then `boot`; never install\u002Flaunch on a\n   claimed sim), `ports:\u003Capp>` (better: run dev stacks from YOUR worktree so `scripts\u002Fworktree-ports.sh`\n   + portless auto-offset - then no port claim is needed), `neon:\u003Cproject>` (dev-DB migrations).\n3. **Before killing anything shared** (kill-port-listeners, `just * kill`, pkill, sim uninstall):\n   check the registry; if another fleet holds the claim, work around it or queue.\n4. **Shared merge gate**: `bun run test:vitest` from the repo root must be green before ANY merge to\n   main, whatever the fleet's own runner is (bun-runner-only gates shipped broken files three times).\n5. **The bell - single attention surface**: when blocked on a human decision or a must-see finding,\n   `fleetctl attn \u003Cfleet-id> \"\u003Cone-line ask>\"` (shows on the board + ntfy phone push) - plus\n   PushNotification when running on the user's Mac. Never ring for routine progress; the user watches\n   the board's attention list as the only inbox and expects silence otherwise. Poll `\u002Fstate` for the\n   user's typed answer on your item after ringing.\n6. **Name your orchestrator pane\u002Ftab** (`herdr tab create --label \"orchestrator:\u003Cepic>\"`) so\n   `herdr agent list` yields a truthful census.\n7. **Start the run's own herdr session + open its ledger.** One session per fleet run, named\n   `fleet-\u003Cepic>`. `herdr session list` first - reuse it if it is already running; otherwise start it\n   headless: `nohup herdr --session fleet-\u003Cepic> server \u003C\u002Fdev\u002Fnull >\u002Fdev\u002Fnull 2>&1 &` (no `setsid` - macOS\n   has none; probed 2026-09-03, the server survives the spawning shell), then poll\n   `herdr --session fleet-\u003Cepic> agent list` until it answers (~2s). YOUR orchestrator pane stays in the\n   default session (the human sees it without attaching; `session stop` can never kill it). From here on\n   EVERY command that touches a fleet resource carries the prefix `herdr --session fleet-\u003Cepic> …`\n   (remote: `ssh \u003Chost> 'herdr --session fleet-\u003Cepic> …'`; the same session name on every machine).\n   The ledger is `docs\u002Fsuperpowers\u002Ffleet-runs\u002F\u003Cepic>.jsonl` in the target repo, written ONLY through\n   the `fleet` CLI - `fleet` below means `bun ~\u002F.claude\u002Fskills\u002Ffleet-ship\u002Fscripts\u002Ffleet.ts` (TypeScript on\n   Effect 4; `bun install` once in that `scripts\u002F` dir; `alias fleet='bun ~\u002F.claude\u002Fskills\u002Ffleet-ship\u002Fscripts\u002Ffleet.ts'`\n   per shell) - see 'Ledger + state view'. First three events, in this order:\n   `fleet log \u003Cledger> fleet.run.started \u003Cepic> session=fleet-\u003Cepic> runmap=\u003Curl> kanban=\u003Curl>`,\n   `fleet log \u003Cledger> fleet.resource.minted session:fleet-\u003Cepic> label=fleet-\u003Cepic>`, and one\n   `fleet.policy.set` per routing\u002Fsteering rule in force (lane file version included).\n\n### Merge under claim - the ONLY way anything lands on main\nMerge-worthiness = the FULL fleet-ship workflow passed WHEREVER the chunk ran (plan → cheap-lane build →\nmulti-agent review → feedback traced → final smart-model review - i.e. per-chunk-loop step 6's cross-model\nconsensus gate, UNCHANGED and referenced here, not redefined). Run that gate on YOUR OWN machine BEFORE\nclaiming - a claim held while you still review starves the queue. Passing the chain on ANY machine is\nsufficient - NO central re-review. Central merge queue REJECTED (#6, verbatim): it \"re-runs suites already\nrun, idles branches on one machine's availability, recreates the single-machine dependency\" - that is why\nthe passing-workflow-on-any-machine model is used instead. The flow (ordered; no step skippable):\n1. **Claim** `main-merge` - or take your FIFO queue position and wait your turn (do other work; never\n   poll-race or jump the queue).\n2. **Rebase** the gated branch on latest main (only the holder may touch main).\n3. **Repo-root gate LOCALLY:** the repo's FULL root gate (`bun run test:vitest`-equivalent from the repo\n   root, whatever the fleet's own runner - the Shared merge gate rule above) runs green on the MERGING\n   machine, before the merge.\n4. **Re-assert the claim, then squash-merge** to main. Step 3's local root gate can outrun the TTL, so at\n   this irreversible instant re-verify the claim is STILL yours; merge + push ONLY under a live claim - if it\n   expired, do NOT merge, drop to abort + re-queue below. (#15's DO fences the push so an expired holder's\n   merge is rejected - naming the re-check point here; the enforcement is #15's.)\n5. **Emit `MERGED`** (`fleetctl event MERGED --machine \u003Cslug> --chunk \u003Cchunk-id> …` - the lifecycle\n   event; see Child→parent lifecycle events).\n6. **Release** the claim.\n**TTL expiry mid-merge: abort + re-queue, NEVER half-merge.** The expired claim auto-releases and the next\nholder may touch main - so on expiry (or on noticing you have outlived the TTL): abort the in-flight\nrebase\u002Fmerge (`git rebase --abort` \u002F `git merge --abort`; main stays untouched, your gated branch is\ndurable), re-enter the FIFO queue, and on reacquire restart from step 2 - main has moved. Steps 2-5 happen\nONLY while you verifiably hold the claim.\nHold-tagged chunks stop at GATED for the human before this flow - see Held chunks below (#33). Forward\npointers, out of scope here: chunk→machine placement stays on the Mac (#35); claim DO\u002Falarm internals are\nFleetboard v2 (#15). This protocol is E2E-verified by the tracer bullet (skills#13), not a unit suite.\n\n### Held chunks - hold:human stops at GATED (skills#33)\nAutonomous merge on workflow pass is the DEFAULT - a hold is the named exception, never a new gate on\neverything. The Mac scheduler tags `hold:human` (or `hold:central`) at ASSIGNMENT on exactly three chunk\nclasses: **reactor-subtle, security-critical, user-facing design** (tagging + placement are #35's - here\nyou only honor a tag that arrives). The tag travels in the chunk's queue entry; whoever runs the chunk\n(steward or orchestrator) honors it per chunk:\n1. Run the FULL per-chunk loop unchanged through the consensus gate → emit `GATED` (the lifecycle\n   event) → **STOP. Do NOT claim `main-merge`.**\n2. **Ring the bell:** `fleetctl attn \u003Cfleet-id> \"\u003Cslug>\u002F\u003Cchunk-id> \u003Cone-line gate verdict> \u003Clink>\"` -\n   machine-namespaced chunk id + gate verdict + a LINK the owner can open: today a PR\u002Fcompare URL or the\n   chunk's run-archive section; when the access-plane link surface lands (#11) the link upgrades to its\n   artifact URL - forward pointer only, do not block on it.\n3. Flip the pane label to `✋ \u003Cchunk-id>` (the existing needs-a-HUMAN glyph, already paired with\n   `fleetctl attn`) - mirrored on the board's attention list per the sidebar invariant.\n4. **Poll `\u002Fstate` for the owner's answer on YOUR attn item** (the bell rule's existing poll). Two\n   branches, both explicit:\n   - **approve** → proceed to Merge under claim above, UNCHANGED (claim\u002FFIFO → rebase → local root gate →\n     squash-merge → `MERGED` → release).\n   - **reject \u002F changes** → SEND-BACK: re-open the chunk with the owner's findings as the brief - a fresh\n     spawn in the SAME worktree (the Housekeeping send-back pattern), findings judged via\n     `superpowers:receiving-code-review`; the chunk re-enters the loop at build and re-rings on its next\n     `GATED`.\n\n## Skills this composes (the chain - invoke these, don't reinvent)\n- **Drive panes:** `herdr-agent-orchestration` (read FIRST - `agent list\u002Fread\u002Fprompt\u002Fwait`, `pane send-keys\u002Fwait-output`, `agent start --kind --pane`).\n- **Plan:** mechanical chunks → `superpowers:writing-plans` only. Design\u002Fambiguous chunks in *autonomous*\n  fleet mode → **parallel design-exploration** (`superpowers:dispatching-parallel-agents` \u002F `design-an-interface`:\n  N independent *lens* subagents → 1 synthesizer → an options doc + recommendation, **marked AWAITING-DECISION**).\n  Interactive `superpowers:brainstorming` interviews the user - only run it when YOU\u002Fthe user drive it live, never\n  in an unattended pane. (Parallel-explore generates options; it does NOT replace the user's decision.)\n- **Build:** `superpowers:subagent-driven-development` (runs `superpowers:test-driven-development` +\n  `superpowers:using-git-worktrees` internally). **Seam discipline:** its `testing-anti-patterns.md` is the authority — mock only non-deterministic *leaves* (model\u002FLLM, clock, net), NEVER the code path the test is named after.\n- **Review:** `\u002Freview-all` = `simplify` + `\u002Fcodex:review` + `\u002Fcodex:adversarial-review`; plus\n  `superpowers:requesting-code-review` \u002F `superpowers:receiving-code-review` for the judgment on findings.\n- **Route dispatches:** `efficient-dispatch` - every Agent-tool dispatch (orchestrator or Claude pane) is\n  classified mechanical-vs-judgment and mechanical ones carry an explicit cheap `model:`; `ax dispatches`\n  measures the inherit rate afterwards.\n- **Finish:** run the repo's CONCRETE gates by name (`bun run typecheck` 0, `verify:effect` 0, suites green)\n  → `superpowers:finishing-a-development-branch` (PR) → orchestrator merges → `commit` conventions.\n  (`superpowers:verification-before-completion` DISABLED 2026-07-29 per the Opus-5 prompting doc - frontier\n  panes self-verify; a brief naming a disabled skill silently degrades to prose. Concrete gate commands\n  stay in every brief; the meta \"verify before claiming done\" ceremony does not.)\n- **Dogfood:** `dogfood` (+ `verify` \u002F `run` to launch the app).\n- **Wrap up the run:** `wrap-up` - run-end closure AFTER teardown-verify: follow-up tickets for every\n  unresolved REPORT.md concern and gate-waived finding, UAT checklist items for what shipped, safe-only\n  residue cleanup, closed\u002Ffiled\u002Fkept report.\n\nClaude panes (fable\u002Fopus\u002Fsonnet) invoke these directly. **pigrok\u002Fcodex panes lack the Skill tool → bake the discipline\n(plan-first, red→green TDD, gates) into their brief text.** The orchestrator (fable\u002Fopus) always owns Review + Finish.\n\n## Model axes (rankings, higher = better; cost = what the user actually pays, not list price)\nIntelligence = how hard a problem the model handles unsupervised. Taste = UI\u002FUX, code quality, API design, copy.\n| model | cost | intelligence | taste | how to run |\n|---|---|---|---|---|\n| gpt-5.5 | 9 | 8 | 5 | Codex CLI ONLY - `codex exec` \u002F `codex review` (`~\u002F.codex\u002Fconfig.toml` defaults to gpt-5.5); herdr pane = codex argv below |\n| grok-4.5 | 8 | 7 | 4 | grok CLI - `grok --always-approve` (`-m` to pin model); second mechanical lane, peer of codex (2026-07-10). **BUILD lane only - grok STALLS on review workloads (live 2026-07-10): never route reviews to grok.** Cross-engine review of grok-built work → codex; review of codex-built work → fable\u002Fopus adversarial (not grok) |\n| sonnet-5 | 5 | 5 | 7 | `claude --model sonnet` \u002F Agent `model:'sonnet'` |\n| opus-5 | 3 | 8 | 8 | `claude --model opus` \u002F Agent `model:'opus'` - the alias resolves to Opus 5 now (2026-07-29 resweep); thinking ON by default, disable-thinking capped at effort `high` - lower effort instead of disabling thinking; review quality holds at low\u002Fmedium effort (Opus-5 doc) |\n| fable-5 | 2 | 9 | 9 | `claude --model fable` \u002F Agent `model:'fable'` - Mythos-class tier above Opus; same routing role as before |\n\n**How to apply (defaults, NOT limits):**\n- **Standing permission to escalate:** cheaper model's output doesn't meet the bar \u002F fails the gate ->\n  re-run or re-spawn the chunk on a smarter model in the SAME worktree, without asking. Judge the output,\n  not the price tag. Escalating costs less than shipping mediocre work.\n- **Cost is a tie-breaker only.** Anything that ships: **intelligence > taste > cost**.\n- **Bulk\u002Fmechanical** (clear-spec implementation, data analysis, migrations) -> gpt-5.5, effectively free.\n- **User-facing** (UI, copy, API design) needs **taste >= 7** -> sonnet-5\u002Fopus-5\u002Ffable-5, never gpt-5.5 solo.\n- **Reviews of plans\u002Fimplementations** -> fable-5 or opus-5, optionally gpt-5.5 (`codex review`) as an\n  extra independent perspective (`\u002Freview-all` already includes it).\n- **Subagent dispatches (Agent tool) - classify EVERY dispatch before sending, then the model field follows\n  (REQUIRED SUB-SKILL: `efficient-dispatch`).** A bare dispatch silently inherits the caller's model - from\n  the orchestrator that is fable-5, the most expensive lane (same trap as an unpinned `claude` pane; live\n  lesson 2026-07-16: fleet runs bled tokens on default-model launches for non-judgment work). Routing:\n  pure search\u002Flocate\u002Fpattern-find → `model:'haiku'`; mechanical implementer \u002F fix subagents \u002F bulk\n  reads-for-a-fact \u002F codex-exec wrappers → `model:'sonnet'`; judgment (review verdicts, design synthesis,\n  gate decisions) → keep the strong model (inherit fable\u002Fopus deliberately - cheap reviewers miss real bugs).\n  Applies to the orchestrator AND to Claude panes (their discipline block carries the same rule).\n- **NEVER use Haiku for panes, builds, or any review\u002Fjudgment.** The one sanctioned use is read-only\n  search\u002Flocate subagent dispatches per `efficient-dispatch`.\n- **gpt-5.5 inside subagents\u002FWorkflows** (the `model` param takes Claude models only): thin Claude wrapper\n  agent `model:'sonnet', effort:'low'` whose prompt writes a self-contained codex prompt, runs `codex exec`\n  via Bash, and returns the result; investigation\u002Fdata-analysis -> `codex exec -s read-only` with a\n  self-contained prompt. In herdr panes skip the wrapper - spawn the codex CLI directly.\n\n**Opus-5-class alignment (2026-07-29, from the \"Prompting Claude Opus 5\" platform doc - applies to fable-5\nand opus-5+ panes\u002Fdispatches):**\n- **Effort is the primary cost lever on Claude dispatches:** mechanical Agent dispatches carry\n  `effort:'low'` alongside `model:'sonnet'`; step up only when the gate fails. Doc: low\u002Fmedium hold quality\n  at a fraction of the tokens - mirror of the codex lanes' pinned `model_reasoning_effort=\"medium\"`.\n- **Review briefs never say \"be conservative\" \u002F \"only report high-severity\" \u002F \"must-fix only\":** an\n  Opus-5-class reviewer follows that literally and under-reports. Reviewers report EVERYTHING; severity\n  filtering is the orchestrator's triage pass, not the reviewer's self-censorship. (The gate's\n  must-fix\u002Fshould-fix tiers are triage labels applied AFTER full reporting - keep them there.)\n- **No stacked self-verification on frontier panes:** fable\u002Fopus panes self-verify and self-correct; do not\n  add \"double-check your work\" \u002F \"re-verify before responding\" \u002F verify-with-a-subagent ceremony to their\n  briefs - it compounds with native behavior and burns tokens for nothing. Concrete repo gates (typecheck,\n  vitest, verify:effect) are task spec, not ceremony - those stay. Codex\u002Fgrok\u002Fsonnet briefs KEEP the\n  spelled-out discipline; this relaxation is frontier-Claude-only. Cross-ENGINE review (consensus gate,\n  tandem) is diversity, not re-verification - unchanged.\n- **Scope pin in every brief:** one line - \"deliver what the chunk spec asks, at the scope intended; note a\n  better approach in REPORT.md in one sentence rather than widening the chunk.\" Opus-5-class panes expand\n  scope readily; unscoped improvements become review noise and merge risk.\n\n## Engine routing (default policy — USER-STEERABLE via ~\u002F.ax\u002Ffleet-routing.json)\n**At fleet start (and on any steering sentence), read `~\u002F.ax\u002Ffleet-routing.json`** — the ax-idiom lane table\n(`{lanes:[{id, match, engine, argv, enabled, reason, origin}]}`). It OVERRIDES the table below; the table is\nthe fallback when the file is absent\u002Finvalid. Route each chunk to the enabled lane whose `match` best fits;\nskip `enabled:false` lanes. The user edits the file to re-route (e.g. flip judgment→opus) without touching\nthis skill; record which lane file version a run used in the ledger. Resolution order:\n**user sentence override (ledger) > ~\u002F.ax\u002Ffleet-routing.json > table below.**\n| work class | engine | notes |\n|---|---|---|\n| mechanical (clear spec, schema\u002Fvalidator\u002Fwiring, 1-3 files, migrations, data analysis) | **codex \u002F gpt-5.5** `codex --dangerously-bypass-approvals-and-sandbox` **AND grok-4.5** `grok --always-approve` - TWO peer lanes; route each unblocked mechanical chunk to whichever has free capacity, run both in parallel when several chunks are unblocked | codex: effectively free, reads CLAUDE.md. grok: same brief discipline (no Skill tool - spell it out); escalation ladder grok\u002Fcodex → fable\u002Fopus in the SAME worktree. Keep >1 lane funded |\n| burst overflow only (both mechanical lanes saturated) | pigrok `pi --model xai-oauth\u002Fgrok-4.3 --approve` | expect convention mop-ups (bun:test\u002FcatchAll) + credit risk; gate hard |\n| judgment \u002F reactor-subtle \u002F security \u002F hard-unsupervised | **opus-5** `claude --model opus --dangerously-skip-permissions` | matches the json's judgment lane; fable BUILDS nothing - scoping\u002Fplanning\u002Freview only (user steer 2026-07-12, the json's frontier lane); always pin `--model` |\n| user-facing: UI \u002F copy \u002F API design | **opus-5** (taste 8) | never gpt-5.5 solo (taste 5); sonnet-5 acceptable floor; fable reviews the result, never builds it |\n| review + gate + merge | orchestrator (fable-5 or opus-5) + `codex review` as extra independent perspective | never delegated |\n\n**Steering:** the user can override routing at ANY time with one sentence (\"route all mechanical to codex\",\n\"no pigrok this run\", \"everything on opus tonight\"). Apply it for the remainder of the run, write the active\noverride into the run ledger (so a resumed orchestrator keeps honoring it), and ask once whether to persist\nit into this table as the new default.\n\n### Placement - after lane selection: (chunk, lane) → (machine slug, steward assignment) (skills#35)\nLane selection above picks WHAT engine runs a chunk; placement picks WHERE. The **Mac orchestrator** - and\nonly it, placement is a kept duty (#6 point 6) - composes per chunk:\n**chunk → lane (engine, resolution order above) → machine (registry match) → steward assignment.**\n- **Pinned contract (the stable interface):** inputs `(chunk, lane)` → outputs `(machine slug, steward\n  assignment incl. hold tags)`. The slug is the machine id minted by `fleetctl join --name \u003Cslug>`; the\n  assignment lands in that machine's queue on the fleetboard - the steward is the assignment TARGET\n  (Steward mode below, skills#30), or the Mac orchestrator runs the chunk itself when the target machine\n  is the Mac (a Mac-local chunk has no separate steward) - with any hold tags attached to the queue entry.\n- **Machine match = registry match (#5 schema), all tiers:** **engines-with-account** (the lane's engine\n  authed there AND its quota pool owner-consented) · **static** (capability vs the chunk's declared needs)\n  · **dynamic** (in-window now, free slot, not stale) · **policy** (owner limits honored).\n- **`~\u002F.ax\u002Ffleet-routing.json` stays engine-policy-only (#5 point 4):** lanes never name machines - NO\n  machine-qualified lanes, NO lane×machine cross-product file. Machines live in the registry; engine\n  policy lives in the lane file; the two meet only here, at placement.\n- **Hold tagging happens HERE - at assignment, on the Mac orchestrator (#6 points 5-6):** the three held\n  classes (reactor-subtle, security-critical, user-facing design) get `hold:human` (or `hold:central`)\n  attached to the assignment; whoever runs the chunk honors the tag per Held chunks above (skills#33).\n- **Placement algorithm - filter-then-priority (deliberately dumb v1, resolved in skills#10):** WHICH\n  eligible machine wins among registry-match survivors is decided by two deterministic passes over the\n  registry fields (#5 schema). **Hard filters - a machine must pass ALL:** machine `state === \"active\"`\n  (drop pending\u002Fstale) · the lane's engine is authed on the machine **AND** owner-consented per the\n  machine's per-engine consent policy (default `owner-only` on machines the operator doesn't own - see gap\n  below) · **capability match** of the chunk's declared `needs` (scheduler-declared at wave planning,\n  default none -> every machine passes) against the static tier (e.g. an Xcode-needing chunk requires\n  non-null `xcodeVersion` and\u002For the required `simRuntimes` entry) · `inWindowNow` (window FILTER only -\n  never place out-of-window; the graceful close\u002Fdrain + hard grace cap is steward RUNTIME behavior spec'd in\n  skills#10 point 3, not yet landed in Steward mode - follow-up) · `freeSlots > 0` · a chunk flagged long\u002Fjudgment is filtered OUT of\n  `preemptible === true` machines. **Priority among survivors (first differing key wins, fully\n  reproducible):** pinned (`policy.preemptible === false`) before preemptible -> warm worktree\u002Fcache for the\n  repo (**skipped when the signal is absent** - no registry field carries it today, a v1 no-op; see gap) ->\n  most `freeSlots` -> alphabetical machine slug. **No migration after placement.** Mid-chunk account-dry\n  raises the existing escalation and `BLOCKED: quota` stops further placement of that engine on that machine\n  for the run. Rejected for v1 (all learnable later from the event log): scoring, quota-remaining\n  weighting, latency-aware placement. This is the policy resolved in skills#10; like the rest of the fleet\n  protocol, placement is E2E-verified by the tracer bullet (skills#13), not a unit suite.\n- **Registry gaps this v1 degrades around (documented, not invented - follow-up candidates):** (1) the\n  policy tier carries no `enginesPolicy` per-engine consent field yet (skills#10 spells it `engines_policy`) - the authed-AND-consented filter is\n  specified but reads `owner-only` on non-owned machines until that field lands; (2) no per-repo\n  warm-worktree\u002Fcache signal exists - that priority tier is a no-op today; (3) chunks carry no declared\n  `needs` capability channel beyond the scheduler's default-none - capability match passes every machine\n  until chunks declare `needs`. All three degrade gracefully now and keep the algorithm executable from\n  today's fields.\n\n## Sidebar legibility — the herdr sidebar IS the human's status board\nThe user reads the sidebar to know *what needs me* vs *what's fine* — an unnamed pane, a duplicate\nworkspace label, or a stale label is a housekeeping DEFECT (live audit 2026-07-16: 6 of 8 agents unnamed,\ntwo workspaces both labeled \"apps\" — illegible). Two independent surfaces, verified live:\n**agent NAME = server-local addressing** (waiters\u002Fcommands target it — set once to the bare chunk id,\nNEVER rename mid-run)\nand **pane LABEL = display** (`herdr pane rename \u003Cpane_id> \"\u003Cglyph> \u003Cchunk-id>\"` — safe to change freely;\nname-addressing survives it). The slug minted by `fleetctl join --name \u003Cslug>` is the machine id: keep\nlocal herdr names\u002Flabels bare, but write `\u003Cslug>\u002F\u003Cchunk-id>` on every surface that leaves that machine.\n- **On spawn** every fleet pane gets BOTH: local agent name = `\u003Cchunk-id>` AND local pane label\n  `▶ \u003Cchunk-id>`. The enclosing tab identifies a non-primary machine: `fleet:\u003Cepic>@\u003Cslug>`; keep\n  `fleet:\u003Cepic>` on the primary machine.\n- **Status glyphs (fixed vocabulary, update the label at every transition):**\n  `▶` building · `⏳` built, queued for gate · `🔎` under review\u002Fgate · `✋` needs a HUMAN decision\n  (always paired with `fleetctl attn`) · `❌` errored\u002Fstuck (monitor caught). No ✅ glyph — a finished pane\n  is archived-then-closed, so \"done\" lives on the kanban + run archive, never as sidebar clutter.\n- **Tab label carries live counts** for at-a-glance triage: `herdr tab rename \u003Cfleet-tab>\n  \"fleet:\u003Cepic> ▶3 ⏳1 ✋1\"` on primary or `\"fleet:\u003Cepic>@\u003Cslug> ▶3 ⏳1 ✋1\"` elsewhere — refresh on\n  each wake.\n- **The invariant the user relies on:** everything visible is working or queued; `✋`\u002F`❌` means \"needs me\"\n  (mirrored on the fleetboard attention list); everything else is fine by construction.\n- **The fleet lives in its own session, so the default sidebar shows only your orchestrator tab.** The\n  human watches the run with `herdr session attach fleet-\u003Cepic>` in a second terminal (or\n  `herdr --remote \u003Chost> --session fleet-\u003Cepic>` for another machine). The sidebar keys (`prefix+.`\n  next agent), herdr-bar and `agent list` never cross sessions - which is exactly why the human's\n  interactive session stays clean. Say so in the run map so nobody hunts for panes in the wrong session.\n- **Sweep duty (every wake):** reconcile every fleet pane's label against its true state, refresh tab\n  counts, and archive+close any pane whose job ended. Unnamed\u002Fmislabeled panes in a fleet tab: fix on sight.\n\n## Tandem orchestrator — codex co-pilot watching the fable orchestrator\nFor autonomous\u002Fovernight runs (default on; skip for short attended runs), spawn ONE codex pane at max\nreasoning alongside the orchestrator as a second pair of frontier eyes:\n`herdr pane split \u003Corchestrator-pane> --direction down --no-focus` → `herdr agent start tandem:\u003Cepic>\n--kind codex --pane \u003Cnew-pane> -- --dangerously-bypass-approvals-and-sandbox -c model_reasoning_effort=\"max\"`\n(pane label `tandem:\u003Cepic>`; brief template in REFERENCE.md).\n- **Watchdog over the orchestrator itself** (~10 min cadence): read the orchestrator pane tail + ledger +\n  `herdr agent list`; catch starvation (no wake progress), context bloat past the rotation threshold,\n  parked-draft blocking, dead waiters\u002Fmonitor. Follows the hard rules: commits-alive check before flagging\n  stuck; parked-draft submit protocol; 2 same-cause blocked cycles = incident, ring the bell.\n- **Rotation trigger-holder (skills#2):** tandem computes the rotation triggers EXTERNALLY — the\n  orchestrator's own judgment degrades exactly when its window fills, so it never self-reports. Each sweep:\n  read `herdr agent get \u003Corchestrator> | jq .result.agent.tokens.context` - the structured context-fill\n  field (see Herdr backchannel primitives; fall back to grepping the pane's bottom lines for\n  \"% ... auto-compact\" \u002F \"context left\" only if the field is empty); read the ledger's last rotation stamp\n  for the 4-6h wall-clock ceiling. On ANY trigger: send the orchestrator the ONE atomic instruction — \"ROTATE\n  NOW: write the handoff doc (REFERENCE schema), commit it, park with an empty prompt\" — and ring the bell\n  if it hasn't parked within 2 sweeps (2 same-cause blocked cycles = incident).\n- **Judgment assist:** the orchestrator sends `TANDEM-JUDGE: \u003Cquestion> + pointers (plan section, diff\n  paths, both reviews)` for gate tiebreaks, risky merges, ambiguous designs; tandem returns a terse verdict\n  + reasoning. ADVISORY ONLY — the orchestrator still owns review+gate+merge (never delegated).\n- **Boundaries:** tandem is read-only on the repo — it never edits, merges, spawns, or kills panes; its only\n  outputs are `agent prompt` to the orchestrator and the bell. It is a fleet-spawned pane: archive-then-close\n  at run end like every other.\n\n## Child→parent lifecycle events — panes PUSH on stop; the signals file is only the offline fallback\nPolling alone (waiter + monitor) babysits panes but gives a child NO way to tell the parent \"done\" or\n\"stuck\" — if the waiter dies (harness reap, orchestrator compaction\u002Frotation) the pane finishes silently\nand becomes an ORPHAN (live complaint 2026-07-16). So every pane also PUSHES a durable record the\norchestrator reads on every wake, independent of any live waiter. That record is a **lifecycle event on\nthe fleetboard event log** (append-only, machine-attributed via the machine token, survives pane AND\norchestrator death); the local `\u002Ftmp\u002Ffleet-\u003Cepic>.signals` file is kept ONLY as the offline fallback for\nwhen the board is unreachable:\n- **Lifecycle vocabulary (spec-fixed 7 stages; the board rejects anything else):**\n  `ASSIGNED → PLANNED → BUILT → IN_REVIEW → GATED → MERGED → DOGFOODED`. Emit with\n  `bun ~\u002FProjects\u002Ffleetboard\u002Ffleetctl.ts event \u003CSTAGE> --machine \u003Cslug> --chunk \u003Cchunk-id> --epic \u003Cepic>\n  --gist \"\u003Cone-line>\"` — auth is the machine token minted by `fleetctl join`; the chunk id is stored\n  BARE (`--machine` is what scopes it — never prefix the id itself, or reads and waiters filtering by the\n  bare id silently match nothing); a bad stage exits non-zero listing the valid stages.\n- **At fleet start** record the event cursor in the ledger (last `seq` from `fleetctl events --since 0`,\n  or the cursor the ledger already holds) AND still set the fallback file\n  `SIGNALS=\u002Ftmp\u002Ffleet-\u003Cepic>.signals` (one per run): one event carries both -\n  `fleet log \u003Cledger> fleet.cursor.advanced fleetboard events=\u003Cseq> signals=$SIGNALS`.\n- **Every brief ends with the SIGNAL STEP** (in the discipline block): on STOP — done, blocked, OR\n  errored — the pane pushes its lifecycle event: DONE (work committed) →\n  `fleetctl event BUILT --machine \u003Cslug> --chunk \u003Cchunk-id> --gist \"\u003Cgist>\"`; BLOCKED\u002FERROR have no\n  lifecycle stage → ring `fleetctl attn \u003Cfleet-id> \"\u003Cslug>\u002F\u003Cchunk-id> BLOCKED|ERROR: \u003Cgist>\"` PLUS the\n  in-herdr toast `herdr notification show \"\u003Cslug>\u002F\u003Cchunk-id> BLOCKED\" --sound request` (works from any\n  pane - see Herdr backchannel primitives), and put the\n  detail (what's wrong, what you need) in REPORT.md at the worktree root. FALLBACK only when the board is\n  unreachable (the fleetctl command exits non-zero): append one line\n  `date-time \u003Cmachine-slug>\u002F\u003Cchunk-id> DONE|BLOCKED|ERROR \u003Cone-line gist>` to $SIGNALS. A pane that can\n  still run a shell can always signal, even when its engine can't finish the chunk.\n- **Every orchestrator wake reads the EVENT LOG first** — `fleetctl events --since \u003Ccursor>` (filter\n  `--machine \u003Cslug>` \u002F `--chunk` as needed) — and reconciles BEFORE trusting waiters: BUILT → gate it\n  (even if the waiter never fired); a BLOCKED\u002FERROR attention item → read REPORT.md, unblock or re-spawn;\n  then advance the cursor in the ledger (`fleet.cursor.advanced`). THEN read each machine's $SIGNALS (remote via\n  `ssh \u003Chost> 'cat \u003Csignals-path>'`) as the fallback path — lines from board-unreachable panes — and\n  reconcile them the same way; any evented\u002Fsignaled pane still open after its chunk closed =\n  archive+close now.\n- **Orphan sweep (every wake):** the `live` block of `fleet state --live` does the cross-check for you\n  (`orphan pane` = live pane with no chunk event; `gone` = chunk whose pane vanished before a terminal stage) -\n  a pane whose chunk is already merged\u002Fabandoned, or that appears in the event log (or fallback $SIGNALS)\n  but has no live waiter, is an orphan: archive-then-close it and re-arm whatever should have caught it.\n- Events COMPLEMENT the two spines: waiter = fast wake on done; monitor = liveness; the **event log = the\n  durable truth** that survives both dying ($SIGNALS is only its offline shadow). A chunk may only be\n  considered lost if all of these are silent AND the worktree shows no commits.\n\n### Herdr backchannel primitives - 0.8.0 delta (probed live 2026-08-15; protocol 19)\nHerdr 0.8.0 renamed the driving surface and added real child→parent primitives. Old commands in briefs or\nwaiters FAIL as unknown subcommands - use the new forms everywhere:\n| gone (0.7) | 0.8.0 replacement |\n|---|---|\n| `agent send \u003Ct> \"\u003Ctext>\"` + `pane send-keys \u003Ct> Enter` | `agent prompt \u003Ct> \"\u003Ctext>\"` - types AND submits in one call; add `--wait [--until \u003Cstatus>] --timeout \u003Cms>` to also block until the turn settles (a non-working target must show a state change within 5s or it returns `agent_prompt_stalled`) |\n| `agent start \u003Cname> --cwd .. --workspace .. --tab ..` | create the pane first (`tab create --workspace \u003Cws> --cwd \u003Cdir>` root pane, or `pane split \u003Cpane> --cwd \u003Cdir> --no-focus`), then `agent start \u003Cname> --kind \u003Cclaude\\|codex\\|grok\\|pi\\|…> --pane \u003Cpane_id> -- \u003Cextra argv>` |\n| `herdr wait output\\|agent-status` | `pane wait-output \u003Cpane> (--match TEXT\\|--regex PAT) [--timeout MS]` and `agent wait \u003Ct> [--until \u003Cstatus> …]` |\n| `agent wait --status idle` + the never-request-`done` workaround | `agent wait \u003Ct>` with NO flag matches `idle\\|done\\|blocked` - exactly the terminal set; `--until done` is first-class. The exit-code trap is gone; the commit-gate on top stays |\n| `agent read` returns JSON (extract `.result.read.text`) | `agent read` \u002F `pane read` print TEXT directly |\nVerified capabilities to build on (each probed on a live pane):\n- **Engine integrations (install once per machine+user - Setup step 0):** `herdr integration install\n  claude codex grok pi`. Each engine's own hook (SessionStart) reports its SESSION IDENTITY to the pane's\n  server - `agent get` then shows `agent_session.source: herdr:claude` + the real session id, so\n  pane→agent binding is authoritative, not guessed. The hook no-ops outside herdr panes (guarded on\n  `HERDR_ENV=1`). `herdr integration status` shows drift after engine updates; re-install on drift.\n- **Every pane knows its own address:** `HERDR_ENV=1`, `HERDR_PANE_ID`, `HERDR_SOCKET_PATH` sit in every\n  pane's env - a child (or any script it runs) can always reach the server about ITSELF, e.g.\n  `herdr notification show \"\u003Cslug>\u002F\u003Cchunk-id> BLOCKED\" --sound request` to toast the human in herdr the\n  moment it blocks (ALONGSIDE `fleetctl attn`, never instead), and `pane report-agent \"$HERDR_PANE_ID\" …`\n  for SHELL panes (dev servers, log tails, monitors) to label themselves for `agent wait`\u002Fthe sidebar.\n- **Wake = authoritative status transition; payload = REPORT.md + fleetboard event.** The waiter spine is\n  `agent wait \u003Cname> --timeout \u003Cms>` (fires on idle|done|blocked) + the commit-gate; the pane's gist\n  travels via its SIGNAL STEP (`fleetctl event`\u002F`attn`) and REPORT.md - NEVER via screen text.\n- **Screen-scraping sentinels are DEAD for claude panes (probed):** Claude Code ≥2.1.x COLLAPSES tool\n  output - a briefed `echo FLEET-SIGNAL…` ran fine but the screen showed only \"Ran 1 shell command\", and\n  the armed `pane wait-output --regex '^FLEET-SIGNAL…'` timed out. `pane wait-output` stays useful only\n  for raw shell panes (build logs, dev servers) and engines proven to print output verbatim.\n- **`pane report-agent` cannot override a live agent pane (probed):** herdr's own detection holds pane\n  authority; a foreign `--source` report neither changes `agent_status` nor surfaces its `--message`.\n  Do not design agent-pane signals on it.\n- **Per-pane telemetry - READ it, never scrape it:** `agent get \u003Cname>` exposes `.result.agent.tokens`:\n  `context` = context fill (e.g. `⛁ 7% (74k)`), `limit` = rate-limit window (e.g. `5h 71%`). Tandem's\n  rotation trigger and the monitor's quota-dry early warning (the grok `403 out of credits` class) read\n  THIS field instead of grepping pane footers.\n\n## Run map — wayfinder-inspired: ONE issue the human reads to understand the whole run\nThe kanban shows status and the archive holds detail, but neither answers \"where is this effort and what\nhas been decided?\" at a glance. Borrow the `wayfinder` skill's map (see that skill for the full pattern):\n- **One GitHub issue per epic, labeled `fleet:map`** — an INDEX, never a store: **Destination** (1-2 lines,\n  what shipped means), **Decisions so far** (one line per merged chunk: chunk name wrapping its PR link +\n  a one-line gist; detail stays in the PR\u002Farchive — the map never restates it), **Not yet specified** (the\n  fog), **Out of scope** (ruled out + why, so it never resurfaces). Update it in the same wake that merges\n  + archives a chunk.\n- **Refer by machine-qualified NAME everywhere** (extends the pane rule to chunks\u002Fcards\u002Fissues):\n  `\u003Cmachine-slug>\u002F\u003Cchunk-id>` wraps links in the run map, cards, lifecycle entries, and human-facing\n  reports; a bare chunk name or wall of bare `#42 #43` is ambiguous and illegible.\n- **Frontier discipline:** express chunk dependencies as native GitHub blocked-by relations where available\n  (falls back to a checklist on the map) so the tracker renders ready-vs-blocked visually. The frontier =\n  open + unblocked + unclaimed chunks — the ONLY things a wave may spawn. **Claim-first:** assign the chunk\n  issue\u002Fcard to this fleet BEFORE spawning its pane (complements fleetboard claims; dedups concurrent\n  orchestrators the same way wayfinder claims tickets by assignee).\n- **Fog of war:** do NOT pre-slice unclear work into chunks at backlog time — park it in Not-yet-specified\n  and graduate it into real chunks when merges sharpen the question (test: can you state the spec precisely\n  NOW? — not \"can you answer it\"). Design\u002Fambiguous chunks stay HITL: parallel-explore produces options\n  marked AWAITING-DECISION → `✋` + bell; the fleet NEVER answers the human's side of a decision.\n\n## Setup (once)\n0. **Engine integrations installed on EVERY fleet machine+user:** `herdr integration status` - any lane\n   engine showing `not installed` or a stale version → `herdr integration install claude codex grok pi`\n   (see Herdr backchannel primitives). Without them, pane→agent binding and the token telemetry the\n   waiters\u002Fmonitor\u002Ftandem read are heuristic guesses. Remote: `ssh \u003Chost> 'herdr integration status'`.\n   ALSO ensure the **pi.orchestrator herdr plugin** is linked + enabled (`herdr plugin list`; source\n   `~\u002FProjects\u002Fherdr-pi-orchestrator`) - it is the machine-wide event queue, the BLOCKED\u002FDONE toasts,\n   AND the transient-error **auto-retry** rung (see Liveness monitor). Tune it via\n   `$(herdr plugin config-dir pi.orchestrator)\u002F.env`.\n1. A **backlog** with a wave-graph (chunks + deps + acceptance). None? build it with `superpowers:writing-plans`\n   (after `superpowers:brainstorming` if the shape is unclear). Commit to main so every worktree pane reads it.\n2. `herdr status` up. A **GitHub Project** board (`gh project create`) - see [REFERENCE.md](REFERENCE.md).\n3. Two notification spines (REFERENCE): one **idle-waiter** background task per active pane (catches *done*)\n   AND one fleet-wide **liveness monitor** loop (catches *stuck\u002Ferrored\u002Fdead*). Start the monitor when the\n   first pane spawns; keep it running the whole fleet.\n\n## Per-chunk loop\nEach transition below emits its lifecycle stage to the event log (`fleetctl event \u003CSTAGE> …` - see\nChild→parent lifecycle events): spawn=`ASSIGNED` · plan-approved=`PLANNED` · verified-remote-receipt+report=`BUILT`\n(pane-side, via its SIGNAL STEP) · cross-review-started=`IN_REVIEW` · consensus-pass=`GATED` ·\nsquash-merge=`MERGED` · tracer-report=`DOGFOODED`. **Mirror every transition to the ledger in the same\nwake** - `fleet log \u003Cledger> fleet.chunk.\u003Cstage> \u003Cslug>\u002F\u003Cchunk-id> pane=\u003Cpane_id> engine=\u003Ckind>\npr=\u003Curl> commit=\u003Csha> gist=\"\u003Cone line>\"` (stage lowercase; only the fields that changed; in epic mode with\nsafeguards every pane event also carries the `attempt_id=` minted at `building` - see Safeguards + scheduling). The board\nis the shared truth, the ledger is the offline one - `fleet state` reads the ledger, not the board.\n1. **Map FIRST.** `fleet state \u003Cledger> --live` + `git worktree list`. Never spawn into an occupied worktree or\n   duplicate work a user\u002Fagent already started. (Live lesson: this bit us.)\n1b. **Codex weekly quota gate (2026-09-06, user rule - live lesson: two Pro weekly windows burned in 31h).**\n   Before spawning ANY codex-engine pane (mechanical, mechanical-spark, mechanical-fast, tandem, gate), read\n   the Codex weekly window from telemetry, never from a footer: `herdr agent list | jq -r '.result.agents[] |\n   select(.agent==\"codex\") | .tokens.limit'` prints `7d N%` where N is percent LEFT. If no codex pane is live,\n   read the newest rollouts instead (herdr telemetry is primary; this is the fallback and may lag): `for f in $(ls -t\n   ~\u002F.codex\u002Fsessions\u002F*\u002F*\u002F*\u002Frollout-*.jsonl | head -5); do jq -r '.payload.rate_limits? \u002F\u002F empty | [.primary,.secondary] |\n   map(select(.!=null and .window_minutes==10080)) | .[0] | select(.!=null) | 100-.used_percent' \"$f\" | tail -1; done | head -1`.\n   **N at or below `FLEET_CODEX_RESERVE` (default 20) = spawn REFUSED:** route the chunk to another funded lane\n   (judgment\u002Fopus, mechanical-grok) or hold it with `BLOCKED: quota` in the ledger. The reserve is the human's\n   interactive budget; a fleet never spends it. **An account switch is NOT fresh budget:** if the active Codex\n   account changed since the run started (`codex-auth status` \u002F registry `active_account_key`), treat the run's\n   Codex lanes as `BLOCKED: quota` until the human re-authorizes - the 2026-09-05 run chained two accounts to 100%\n   through `codex-auth` auto-switch with no human in the loop. Log the gate result every wave:\n   `fleet log \u003Cledger> fleet.quota.gate engine=codex left=\u003CN>% reserve=\u003CR>% verdict=\u003Cok|refused>`.\n2. **Worktree** (`superpowers:using-git-worktrees`): `git worktree add .claude\u002Fworktrees\u002F\u003Cchunk> -b feat\u002F\u003Cchunk> origin\u002Fmain`\n   **then `bun install` (or the repo's install) in the new worktree** - fresh worktrees don't share the root\n   `node_modules`, and a pane may skip install → `Cannot find module @workbench\u002F*` gate failures that look\n   like code bugs but aren't. Do it at the orchestrator before spawning, so the pane + your gates both resolve.\n3. **Spawn, engine-routed + NAMED, into the FLEET TAB.** At placement, bind the machine slug registered by\n   `fleetctl join --name \u003Cslug>` and keep both identities: local herdr name `\u003Cchunk-id>`; external\u002Freporting\n   name `\u003Cslug>\u002F\u003Cchunk-id>`. Spawn (0.8.0 two-step - see Herdr backchannel primitives): get a pane in the\n   fleet tab cwd'd at the worktree - the fleet tab's fresh root pane for the first chunk\n   (`tab create … --cwd \u003Cworktree>` returns the pane OBJECT `result.root_pane`; its id is `.result.root_pane.pane_id`), else `herdr pane split \u003Ca-fleet-tab-pane>\n   --direction down --cwd \u003Cworktree> --no-focus` - then `herdr agent start \u003Cchunk-id> --kind \u003Ckind>\n   --pane \u003Cpane_id> -- \u003Cengine args>` (`--kind` names the engine executable: claude|codex|grok|pi|…; the\n   argv after `--` is its flags only). For a non-primary machine, execute the same commands there:\n   `ssh \u003Chost> 'herdr pane split … && herdr agent start …'`.\n   The remote agent NAME is still the bare chunk id; append `fleet.resource.minted pane:\u003Cpane_id>` (and\n   `tab:\u003Cid>` for any tab you just created) plus `fleet.chunk.spawned` in this same wake (see 'Ledger +\n   state view'); set its local pane label too\n   (`ssh \u003Chost> 'herdr pane rename \u003Cpane_id> \"▶ \u003Cchunk-id>\"'` - see Sidebar legibility). Every later\n   remote read\u002Fprompt\u002Fwait\u002Frename\u002Fclose follows the same host-explicit SSH form. Never use `herdr --remote` for\n   driving; it is UI-attach only.\n   Placement hierarchy (once per fleet run, not per chunk) - all of it inside the run's own session, so\n   every command below is `herdr --session fleet-\u003Cepic> …` (remote: `ssh \u003Chost> 'herdr --session\n   fleet-\u003Cepic> …'`): **session = the fleet run** (Setup step 7) → **workspace = `\u003Cepic>`**: a fresh\n   session has NO workspaces, so mint one (`workspace create --cwd \u003Crepo> --label \u003Cepic>`; keep its id;\n   `fleet.resource.minted workspace:\u003Cid>`) → **one fleet tab per machine**: `tab create --workspace\n   \u003Cws-id> --cwd \u003Cworktree> --label \"fleet:\u003Cepic>\" --no-focus` on primary, `\"fleet:\u003Cepic>@\u003Cslug>\"`\n   elsewhere (`fleet.resource.minted tab:\u003Cid>`). Keep its `tab_id`, and spawn EVERY chunk pane into\n   it. The human's default session is never touched - no 'tab 1' rule applies inside the fleet\n   session. `herdr tab rename` retrofits.\n   **Tab hygiene (live lesson - user caught both):** (a) run `herdr tab list --workspace \u003Cws>` on the target\n   server (through SSH when remote) BEFORE creating; reuse the expected `fleet:\u003Cepic>` or\n   `fleet:\u003Cepic>@\u003Cslug>` tab instead of minting a duplicate; (b) `tab create` ships an empty root SHELL pane\n   (`.result.root_pane.pane_id` in the create response - `root_pane` is an object, not an id; probed 2026-09-03) - in 0.8.0 that root pane is the FIRST chunk's spawn target\n   (`agent start … --pane \u003Croot_pane>`), not waste; only close it when the tab pre-exists with agents and\n   the root shell sits empty. Sweep `herdr pane list --workspace \u003Cws>` on the same target (no stray `shell`\n   panes in fleet tabs). Note a tab dies with its last pane - re-check `tab list` before reusing a stored id.\n   Engine per the **Engine routing** table above (+ any active user steering override from the ledger).\n   **ALWAYS pin `--model` explicitly** — a bare `claude` inherits the user's CURRENT default, which can change\n   mid-fleet (live lesson: user switched their default mid-run and the next pane silently ran on it; caught\n   only by reading the pane status line). **Codex panes have an extra, bounded launch gate:** after accepting\n   the trust modal, prove the unique argv-turn token appears in the **normalized** tail and substantive Codex\n   activity follows it while status is `working|idle|done`; `working` and the echoed prompt alone are only\n   boot activity, not proof that the brief ran. If the gate reaches its deadline, emit\u002Fring `BOOT_HUNG` and\n   leave the pane intact — do not arm its waiter and never auto-kill it. Run the bundled verifier in\n   REFERENCE's “Codex pane launch protocol”. Pane spawned → emit `ASSIGNED`\n   (`fleetctl event ASSIGNED --machine \u003Cslug> --chunk \u003Cchunk-id> --epic \u003Cepic> --gist \"spawned \u003Cengine>\"`).\n4. **Brief.** For Codex, the argv pointer from the bounded verifier in step 3 is the first brief — do **not**\n   re-send it; wait for `BOOT_READY` before any later steering. For other panes, deliver with\n   `herdr agent prompt \u003Cchunk-id> \"\u003Cpointer>\"` (0.8.0: types AND submits in one call - the old\n   `agent send` + `send-keys Enter` dance is gone; verify the prompt line is EMPTY first, the append trap\n   in Hard rules still applies to a parked draft). **Brief-delivery gate (EVERY engine, not just codex -\n   live incident 2026-08-15: an orchestrator died mid-send and its freshly spawned pane sat at Ctx 0,\n   never briefed):** after delivering, confirm status flips to `working` (`agent prompt --wait --until\n   working` does this in one call); a pane still idle on an empty prompt got NO brief - re-deliver\n   (bounded, 2 tries) then ring. Never assume a sent brief arrived. A brief = **CONTEXT section** (varies per chunk:\n   spec\u002Fbug\u002Frepro\u002Ffiles\u002Fconstraints — write it as richly as you like) + DISCIPLINE BLOCK\n   (fixed — copy it VERBATIM from REFERENCE.md, never freehand it)**. The block carries the whole chain:\n   PLAN first (`superpowers:writing-plans`) → BUILD via `superpowers:subagent-driven-development` (TDD) →\n   seam rule (point at `testing-anti-patterns.md`; a behavior-bearing chunk asserts the *observable effect\n   at the real seam*, e.g. the repo's `e2e-*.test.ts` \u002Frpc pattern — the goal actually appears — NOT that a\n   mocked dispatch was called) → gates (CONCRETE commands, named: `bun run typecheck` 0,\n   `verify:effect` 0, suites green - never a meta \"verify your work\" line, see Opus-5-class alignment) →\n   **`git add -A ':!BRIEF.md' ':!REPORT.md' && git commit` before STOP, then report as\n   `\u003Cslug>\u002F\u003Cchunk-id>` with the verified remote SHA, draft PR URL, and committed recovery record; leave ready status and merge to the coordinator** (uncommitted worktree = UNFINISHED to the waiter). Claude\n   panes get the skill NAMES (they\n   have the Skill tool); codex\u002Fpi panes get the non-Claude variant with the discipline spelled out as text.\n   **Live lesson (2026-07-02): a freehanded bug-fix brief had excellent context + a TDD sentence but never\n   told the pane to plan or use subagent-driven development — rich context is NOT the discipline; ANY chunk\n   shape (build, bug fix, refactor, spike) ends with the verbatim block.**\n   **Skill availability + command triggering (2026-07-16, workbox lesson): a brief NEVER loads a skill by\n   itself.** Skills resolve from the PANE's environment — `~\u002F.claude\u002Fskills` of that machine+USER plus its\n   installed plugins — not from the orchestrator's. Before any brief names a skill: (a) **probe the target\n   env once per machine+user** (`ls ~\u002F.claude\u002Fskills\u002F\u003Cname>`; for a remote pane `ssh \u003Ctarget> 'ls\n   ~\u002F.claude\u002Fskills'` — the pane user's home, not yours) and cache the result in the ledger; (b) a named\n   skill that's absent **silently degrades to prose** — the pane \"sort of follows\" the workflow with no\n   gates loaded, which reads as compliance and isn't — so on a miss either sync skills to the box first or\n   fall back to the non-Claude discipline variant (inline text works on every engine and every machine);\n   (c) to **force-trigger** a skill\u002Fcommand in a claude pane, send the slash command as its OWN message\n   (`agent prompt \u003Cchunk-id> \"\u002Fskill-name \u003Cargs>\"`), never buried mid-paragraph, then `agent read`\n   and confirm the command\u002Fskill banner appears before sending the follow-up context; plugin-namespaced\n   skills (`superpowers:*`) additionally require that plugin installed under the pane's user — file-sync\n   alone never provides them. Plan approved (the pane's written plan lands; AWAITING-DECISION design\n   chunks: when the user's decision arrives) → emit `PLANNED`.\n5. **Arm waiter + monitor.** For Codex, do this only after the bounded past-boot launch gate succeeds. Run the\n   canonical background waiter from REFERENCE: `herdr agent wait \u003Cchunk-id> --timeout \u003Cms>` (0.8.0: no\n   flag = fires on `idle|done|blocked`, the full terminal set) supplies bounded backpressure, then\n   `herdr agent get` payloads gate on `agent_status` in `idle|done` PLUS the commit-gate (a commit beyond\n   `origin\u002Fmain` or a dirty tree - status alone is never completion); `blocked` wakes route to the\n   unblock path, not the gate. AND ensure the fleet **liveness monitor** loop is\n   running (it sweeps this pane for stuck\u002Ferrored\u002Fdead).\n6. **Gate (you, fable\u002Fopus): CROSS-MODEL CONSENSUS (2026-07-10, user rule).** On idle, read the pane (its commit+report already emitted `BUILT` via the SIGNAL STEP; on READY_UNCOMMITTED you commit the pane's work and emit `BUILT` yourself), then three passes before your judgment:\n   a. **Cross-engine review** (dispatching it = emit `IN_REVIEW`)**:** the chunk's diff is reviewed by a DIFFERENT engine than built it - grok-built → `codex review`; codex-built → fable\u002Fopus adversarial review (grok is BUILD-only, it stalls on review workloads - the model-table rule, now consistent here). Reviewer instruction: report EVERY concrete finding with evidence, no severity self-filtering - the orchestrator triages. **An engine NEVER reviews its own work; a chunk NEVER self-approves.**\n   b. **Reuse\u002Fsimplicity pass** on the same diff (either engine or fable): hand-rolled code that a shared package \u002F the repo's package index already owns = must-fix; needless complexity = should-fix.\n   c. `\u002Freview-all` → **seam check** (the\n   `superpowers:requesting-code-review` task-reviewer rubric already asks *\"tests verify real behavior, not\n   mocks?\"* — enforce it; heuristic: *delete the mock — if the test still passes, it tests the mock, not the\n   code*; a behavior-bearing chunk with only mocked-dispatch tests is NOT done → send back) →\n   `superpowers:receiving-code-review` judgment → one fix subagent (`model:'sonnet'` - mechanical, findings\n   are its spec; escalate on a failed re-gate) for Critical\u002FImportant →\n   `superpowers:finishing-a-development-branch`.\n   **Merge gate = consensus:** merge only when the cross-engine reviewer has zero unresolved must-fix AND the\n   reuse pass is clean-or-fixed AND your judgment review passes. Builder-vs-reviewer disagreement → fable\u002Fopus\n   tiebreak, never a coin flip. Consensus pass → emit `GATED`. **Hold-tagged chunk: STOP here - the\n   Held-chunks flow (bell + the owner's board answer) owns the merge decision.** Untagged (the default):\n   merge **under the `main-merge` claim** - the ordered Merge-under-claim flow (claim\u002Fqueue FIFO → rebase\n   on main → LOCAL repo-root gate → squash-merge → emit `MERGED` → release); never merge outside it.\n7. **Track + housekeep + FILE FOLLOW-UPS (2026-07-10, user rule).** Move the kanban card Todo→In Progress→Done; attach the PR. Append the chunk\\u2019s decision line to the run map (see Run map). **Follow-up capture:** any concern a builder\u002Freviewer\u002Froaster raised that is NOT resolved within the chunk (fragile spot, \"fix later\", out-of-scope bug, deferred improvement) → file a repo issue labeled `follow-up` (title `[follow-up][\u003Carea>] \u003Cgist>`; body: source chunk, agent, what+why+suggested fix, severity) AT TRIAGE TIME, not batched, and link it from the card + run archive. **UAT capture (2026-07-22, user rule - repo contract in docs\u002Fplaybooks\u002Fissue-labels.md):** any merged chunk whose behavior only a human on a real device\u002FTestFlight build can confirm (widgets, Live Activities, push, entitlements, purchase flows, camera\u002Fmic, background modes, anything the dogfood pane cannot prove in sim) -> add concrete `- [ ]` verification steps + the PR link to the app's open `uat`-labeled issue, or create one (`--label uat --label device-verify`) when none is open; ONE `uat` issue per app per build window, extended not duplicated. The pre-ship human sweep is `gh issue list --label uat --state open` - a device-check ask that is not on a `uat` issue does not exist at build time. Sweeps: at every \u002Freview-all checkpoint scan recent chunk reports for un-filed concerns; before each final PR do a full-run sweep and list all follow-ups in the PR body under \"Deferred concerns\". Then **archive-then-close** the pane (see Housekeeping — NEVER close before archiving).\n8. **Dogfood (tracer-bullet).** After a runtime-affecting merge, when test panes are quiescent, spawn a\n   **sonnet-5** `dogfood` pane (drive-app-and-report is taste-floor work; opus-5 for reactor-subtle merges;\n   never fable - scoping\u002Fplanning\u002Freview only per the 2026-07-12 steer): run the app, exercise the chunk's new\n   behavior + a core smoke, report → findings become **new kanban cards** linked to the chunk. Tracer\n   report received → emit `DOGFOODED` (the chunk's final lifecycle stage).\n9. **Fan out.** Spawn the next wave's *independent* chunks in parallel; sequence shared-file\u002Freactor chunks.\n   Re-run the Codex weekly quota gate (step 1b) before EVERY wave, not once per run - the window moves while\n   panes work. A `QUOTA_HALT:` line from the monitor closes the codex lanes for the rest of the run: finish the\n   panes already working (they may still ROTATE), spawn no new codex pane, and record `BLOCKED: quota`.\n\n## Liveness monitor - the SECOND spine (waiters catch *done*; the monitor catches *stuck\u002Ferrored\u002Fdead*)\nThe idle-waiter only fires on `idle|done`. A pane that **errors** (network drop, `403 out of credits`, crash,\nconnection-refused, rate-limit, model API 5xx), **freezes** mid-`working`, or flickers to `unknown` NEVER\nreaches idle → its waiter blocks to a **silent ~30-40 min TIMEOUT** and the chunk stalls invisibly while you\nthink it's building. Waiters alone are blind to this - so run ONE wall-clock monitor loop for the WHOLE fleet,\nin parallel with the per-pane waiters. It RINGS; it does not auto-kill (classify via tail first - never kill a\ngenuinely-`working` pane).\n1. **Sweep every ~2 min** (`run_in_background`, re-arming): `herdr agent list` → for each active fleet pane\n   snapshot `{status, normalized-tail fingerprint, commits-beyond-main, dirty, tokens}` (`tokens` from\n   `agent get` - `.limit` at or below `QUOTA_MIN` (default 10% left) = **QUOTA_LOW**: the monitor emits it\n   once and sends the pane `ROTATE NOW` while it can still write, so a handoff exists BEFORE the\n   `usage limit` error kills it; see Herdr backchannel primitives). The Codex WEEKLY window (`7d N%`) at or\n   below `FLEET_CODEX_RESERVE` (default 20% left) = **QUOTA_HALT**, emitted once per fleet: the orchestrator\n   spawns no further codex pane for the run (step 1b\u002F9) - the reserve is the human's interactive budget.\n   Rotation keeps a pane alive; it never buys the fleet more budget) and diff vs the last snapshot in a state\n   file (survives orchestrator compaction - the monitor is stateless per wake, like the waiters).\n2. **ERRORED** - tail matches an error signature (list in REFERENCE monitor script). **Rung 0 is\n   AUTOMATED and already ran before you see it:** the pi.orchestrator plugin auto-retries transient\n   errors (API stall\u002Fmid-stream drop\u002F429\u002F5xx\u002Foverloaded) up to PI_ORCH_RETRY_MAX times per pane -\n   check its `state\u002Fevents.jsonl` for `auto_retry`\u002F`retry_exhausted`\u002F`retry_fatal` records (2026-08-15,\n   built from the live 2h Opus stall + never-briefed child incident). Ring immediately ONLY for:\n   `retry_fatal` (quota\u002Fauth - needs respawn on a funded lane), `retry_exhausted`, or a signature the\n   plugin missed (`fleetctl attn \u003Cfleet-id> \"\u003Cmachine-slug>\u002F\u003Cchunk-id> errored: \u003Cline>\"` +\n   PushNotification on the user's Mac); don't wait out K sweeps.\n3. **STUCK** - status + normalized-tail fingerprint + commit-count ALL unchanged for K sweeps (~6-10 min)\n   while status ∉ `{idle,done}` → ring. The normalizer ignores only volatile terminal chrome (spinner elapsed\n   time, `esc to interrupt`, context-% footer), so a boot spinner now goes stale while real commands, logs,\n   model output, and errors still count as progress. Read the tail to classify: real long compile\u002Fsuite\n   (re-arm, leave it) vs frozen (recover). A pane legitimately on a background shell shows *changing*\n   output\u002Flogs - a frozen one is inert.\n4. **DEAD\u002Fgone** - pane vanished from `agent list` (crashed \u002F user closed) but its chunk isn't merged → ring +\n   re-spawn on the fallback engine in the SAME already-installed worktree.\n5. **Recover a caught pane** via the Hard-rules credits\u002Ffrozen path: close the dead pane → re-spawn\n   grok→codex→fable\u002Fopus (ascending intelligence) in the same worktree → re-arm BOTH its waiter and the monitor.\n   A pane that died on a usage limit WITHOUT a handoff is rebuilt from its transcript on disk - follow\n   REFERENCE 'Dead-pane rescue' (`bun scripts\u002Fsession-handoff.ts \u003Cpane>` renders the brief from the codex\n   rollout \u002F claude project jsonl; successor in the same workspace; rename the corpse's tab MOVED).\n6. **Distinct from the idle-waiter, not a replacement.** Waiter = \"did it finish?\" (git-state gate). Monitor =\n   \"is it still alive + progressing?\" (liveness gate). Both run per active pane; a chunk is advanced only by the\n   waiter's DONE\u002FREADY, rescued only by the monitor's STUCK\u002FERRORED\u002FDEAD. See REFERENCE 'Liveness monitor'.\n\n## Housekeeping — close done panes, KEEP their results (restorable)\nA pane's scrollback\u002Fresult is LOST on `herdr pane close` (herdr has no transcript export; only the *session* persists, and even that is not guaranteed re-attachable after close). So **capture before you close**, into a git-tracked run archive — the durable, restorable record of what each agent actually did.\n\nPer chunk, right after merge (step 7), BEFORE closing:\n1. **Capture the pane's final report:** `herdr agent read \u003Cname> --source recent --lines 400` → the report text (files, commit, test summary, concerns).\n2. **Append to the run archive** (git-tracked → permanent, greppable, travels with the code): `docs\u002Fsuperpowers\u002Ffleet-runs\u002F\u003Cepic>.md`, one section per chunk: `## \u003Cmachine-slug>\u002F\u003Cchunk-id>` + PR# + merge commit + gate verdict + test summary + the captured report + concerns. Commit it (part of the merge or a follow-up housekeeping commit). Link it on the kanban card.\n3. **Publish the branch** (`git push origin feat\u002F\u003Cchunk>` from the pane's worktree, log `ref=` on the `built` event) - a branch that exists on one machine only is not durable, and a pane close or host failure must never remove the only copy of gated work. Workers maintain draft PRs; the coordinator owns ready status and merge.\n4. **THEN teardown:** `herdr --session fleet-\u003Cepic> pane close \u003Cpane_id>` (resolve id from the local bare name; use SSH when remote) + `fleet log \u003Cledger> fleet.resource.closed pane:\u003Cpane_id>` → `git worktree remove` → `git branch -D` → **DerivedData sweep** (every Xcode build in a worktree mints a fresh `~\u002FLibrary\u002FDeveloper\u002FXcode\u002FDerivedData\u002F\u003CApp>-\u003Chash>` dir, 5-9GB each; 80 leaked dirs = 394GB, live lesson 2026-07-17). Match by exact `WorkspacePath` inside the removed worktree - never by app-name pattern (concurrent fleets build the same app from other worktrees). See REFERENCE 'Archive a pane result before close' for the snippet. Last chunk of the run: rename the tab `fleet:\u003Cepic> ✓done` on primary or `fleet:\u003Cepic>@\u003Cslug> ✓done` on a non-primary machine (or close it).\n5. **Restore** later: read `docs\u002Fsuperpowers\u002Ffleet-runs\u002F\u003Cepic>.md` (the authority) and render the ledger\n   (`fleet state docs\u002Fsuperpowers\u002Ffleet-runs\u002F\u003Cepic>.jsonl`); use `herdr session attach fleet-\u003Cepic>` for\n   a local live re-entry, or `herdr --remote \u003Chost> --session fleet-\u003Cepic>` for remote UI attach WHILE the\n   session still exists (teardown deletes it); never use `--remote` to drive subcommands.\n**Archive-then-close applies to ALL fleet-spawned panes: review, dogfood, fix, and supervisor panes included, not just chunk panes** (live lesson 2026-07-10: a spent cross-review pane + a gated-out chunk pane lingered unclosed; the rule read as chunk-only). A review pane's verdict goes into the run archive under the chunk it reviewed.\nDo NOT let done panes pile up (they clutter the fleet tab + hold worktrees) — but never trade the result for the cleanup.\n**Close at VERIFIED REMOTE RECEIPT+REPORT, not at merge (2026-07-13, user rule — 11 idle panes piled up waiting out a long review queue).**\nA build pane's job ends when its branch and recovery record are pushed, its draft PR is current, and its report is captured; the WORKTREE + BRANCH are the durable\nartifacts the gate\u002Fmerge needs — the pane is not. As soon as the waiter fires READY, verify the delivery receipt and archive the accepted result before closing the pane; run cross-review\u002Fgates against the worktree, and only tear down the\nworktree+branch after merge. Exception: a pane you expect to send back imminently (review already running, verdict\nminutes away) may stay for ONE gate cycle — a send-back to a closed pane costs a fresh spawn in the same worktree with\nthe findings as the brief, which is acceptable and often cleaner (fresh context) than keeping N idle panes alive.\nIdle panes with no live job are a defect: every fleet-tab pane must be `working` or awaiting an imminent send-back.\n\n### Resource ledger + deterministic teardown (2026-07-16 — structure over sweep-rules)\nEmpty tabs\u002Fpanes kept surviving runs DESPITE sweep duty + archive-then-close: those rules live in\norchestrator context and decay under compaction\u002Frotation. Cleanup is therefore LEDGER-driven, never\nmemory-driven — the same law that already governs worktrees (\"housekeep only what THIS run created,\ntracked by exact path\") extended to every herdr resource:\n- **Mint = record.** Every command that mints a herdr resource - the session, `workspace create`,\n  `tab create`, `pane split`, `agent start` - appends one event IN THE SAME wake, never batched:\n  `fleet log \u003Cledger> fleet.resource.minted \u003Csession|workspace|tab|pane|agent>:\u003Cid> label=\u003Clabel>`.\n  The empty root SHELL pane a `tab create` (and a `workspace create`) ships (`.result.root_pane.pane_id`) gets its own event until closed.\n  No minted event = not yours = you may not close it. Closing appends `fleet.resource.closed \u003Csame subject>`.\n- **Teardown reads the ledger, never the sidebar.** At run end (and before any rotation handoff):\n  `fleet teardown \u003Cledger> --epic \u003Cepic> --session fleet-\u003Cepic>` (dry-run: every open\n  resource and its action), then add `--execute`. It archives-then-closes each pane by exact id, closes\n  tabs and workspaces, verifies no recorded pane survives, THEN `session stop` + `session delete`\n  fleet-\u003Cepic> - one stop removes every remaining surface - and appends `fleet.run.teardown closed=\u003Cn>`.\n  VERIFY: `herdr session list` no longer shows `fleet-\u003Cepic>`. `fleetctl deregister` only AFTER that.\n\n### Ledger + state view (2026-09-03 - the orchestrator reads ONE view, never scans panes)\nThe ledger is `docs\u002Fsuperpowers\u002Ffleet-runs\u002F\u003Cepic>.jsonl`: JSON Lines, one **CloudEvents 1.0** record per\nline (`specversion` `id` `source` `type` `time` `subject` `data`) - `jq`, DuckDB `read_json_auto`, and ax\nall read it without a custom parser. The tooling is `scripts\u002Ffleet.ts` (Effect 4, `effect\u002Funstable\u002Fcli`);\nits `Herdr` service (`scripts\u002Fsrc\u002Fherdr\u002FHerdr.ts`) is the seam: `HerdrCli` shells out to `herdr --session …`\ntoday, a `HerdrSdk` layer over `@herdr\u002Fsdk` replaces it when the SDK ships, nothing above changes. Never hand-write a line; `fleet log \u003Cledger> \u003Ctype>\n\u003Csubject|-> [key=value …]` mints id + time (ints and true\u002Ffalse are coerced, everything else is a string).\n`source` defaults to `fleet\u002F\u003Cepic>\u002F\u003Chost>`; set `FLEET_SOURCE=fleet\u002F\u003Cepic>\u002F\u003Cslug>` once per machine.\n\n**Epic mode (2026-09-04, spec `docs\u002Fspecs\u002F2026-09-04-fleet-graph-visibility-design.md`):** every `fleet` command also accepts an\n**epic directory** `\u003CFLEET_HOME>\u002F\u003Cepic>` (default home `~\u002F.fleet\u002F\u003Crepo>`, an orphan-branch worktree created with\n`fleet init \u003Chome> \u003Cepic> --repo \u003Cowner\u002Fname> --plan \u003Cpath>`). The directory holds `graph.json` (chunks + deps +\nconflicts + lane + hold, plan-only; validate with `fleet graph check \u003Cdir>`), one `ledger.\u003Cslug>.jsonl` per machine, and\n`DECISIONS.md`. In epic mode `fleet log` REFUSES an illegal stage transition (exit 2, prints the allowed targets; `--force`\nwith `reason=` overrides and records `forced=true`), an unknown chunk id (`--adhoc` overrides), an unknown `step=` for\nthe stage (steps come from `scripts\u002Fworkflow.json`), a bad `evidence=` (`verified|reported|asserted`), and `merged` on a\nheld chunk without `hold=approved`. New views: `fleet next \u003Cdir>` (the frontier - the ONLY chunks a wave may spawn),\n`fleet status \u003Cdir> \u003Cchunk>` (put this line in every brief so the pane sees its stage, blockers, dependents, acceptance),\n`fleet stats \u003Cdir>` (dwell per lane\u002Fstage, retries, causes). `fleet state \u003Cdir>` groups chunks by depth and adds `step` and\n`blocked-by` columns. The single-file form `fleet \u003Ccmd> \u003Cledger>.jsonl` still works unchanged for runs already in flight.\n\n**Safeguards + scheduling (2026-09-05, pstack learnings - `docs\u002Fresearch\u002Fpstack-fleet-ship-learnings.md`):** `fleet init`\nwrites `\"safeguards\": true` and `\"scheduling\": {\"max_in_flight\": 4, \"max_gate_queue\": 2}` into `graph.json`; both are\nenforced by `fleet log` \u002F `fleet next`, not by prose, and `src\u002Fledger\u002Fsafety.test.ts` + `src\u002Frun\u002Fscheduling.test.ts` are the\ncrash tests. Untagged ledgers from older runs keep their old semantics.\n- **Attempt token.** `fleet log … fleet.chunk.building \u003Cslug>\u002F\u003Cchunk>` mints `attempt_id` (the orchestrator does this, then\n  puts the token in the brief). Every later pane event (`built`, `in_review`, `gated`, `merged`) MUST carry\n  `attempt_id=\u003Ctoken>`; a missing, stale, or already-ended token is rejected with exit 2 - and rejected on REPLAY too\n  (`fleet state` prints `REJECTED \u003Csubject> event \u003Cid>: \u003Creason>` in the header). A late `BUILT` from a replaced pane can no\n  longer overwrite the current attempt. A new `building` clears `hold`, `commit`, `checks`, `verdict`, `evidence`.\n- **Gate receipt bound to a commit.** `built` requires `commit=\u003Cfull 40\u002F64-hex sha>`. `gated` requires\n  `verdict=PASS evidence=verified checks=\u003Creceipt path> commit=\u003Cthe built sha>`; anything else is exit 2, `--force` cannot\n  bypass it. Any later event with a different `commit=` drops the receipt (re-review). `merged` requires\n  `input_commit=\u003Creviewed head sha>` that matches the receipt - the squash sha goes in `commit=`, the receipt attests the\n  reviewed input only. Before merging run `fleet check-gate \u003Cdir> \u003Cslug>\u002F\u003Cchunk> --worktree \u003Cwt>`: exit 0 only when the\n  worktree is clean, `HEAD` equals the receipt commit, and a held chunk carries `hold=approved`.\n- **Rolling window.** `fleet next` counts `assigned` + active chunks against `max_in_flight` and `built|in_review|gated`\n  against `max_gate_queue`; over either limit the frontier is empty and the chunk row says why (`capacity`, `gate queue`).\n  `fleet log … assigned|spawned` re-checks the same view and refuses over-capacity spawns. Refill from `fleet next` when a\n  merge frees a slot; size the window by what YOU can gate + merge per wake, not by machine slots.\n- **Pilot.** Optional `\"scheduling\": {\"pilot\": \"\u003Cchunk-id>\"}` - a dependency-free, non-question chunk. Nothing else is\n  ready until the pilot reaches `dogfooded`. Use it on every run whose brief template, verify recipe, or chunk size is new.\n- **Freeze switch.** `fleet log \u003Cdir> fleet.policy.set spawn-paused text=\"\u003Cwhy>\"` empties the frontier and blocks\n  `assigned|spawned` until `text=off`. Use it for a broken shared verifier or poisoned upstream; in-flight work finishes.\n- **Drain points.** Completion events are appended by panes and read at drain points only - after a merge, after a spawn\n  wave, after a review batch, before a human report. Never handle an arrival inline mid-merge.\n- **Publish before close.** A completed branch on one machine is not durable. Before `pane close`, push the branch\n  (`git push -u origin HEAD` from the task worktree) and log the verified remote SHA, draft PR, recovery record, and ref on the `built` event\n  (`ref=origin\u002Ffeat\u002F\u003Cchunk>`); a git bundle in shared storage is the fallback when the remote is unreachable.\n  `fleet status` shows `attempt_id`, gate commit, and checks so a pane can see what the gate will demand.\n\nType vocabulary (all `fleet.*`, the writer rejects anything else):\n| type | subject | data |\n|---|---|---|\n| `run.started` · `run.teardown` | `\u003Cepic>` | `session` `runmap` `kanban` · `closed` |\n| `policy.set` | policy name (`routing`, `steer`, `lane-file`, `spawn-paused`) | `text` (`spawn-paused`: reason, or `off`) |\n| `resource.minted` · `resource.closed` | `session:`\u002F`workspace:`\u002F`tab:`\u002F`pane:`\u002F`agent:` + id | `label` |\n| `chunk.\u003Cstage>` (assigned spawned planned building built in_review gated merged dogfooded blocked error archived closed) | `\u003Cslug>\u002F\u003Cchunk-id>` | `pane` `engine` `wt` `pr` `commit` `gist` - same keys `fleetctl event` posts; with safeguards also `attempt_id` (every pane event), `ref` (built), `verdict` `evidence` `checks` (gated), `input_commit` (merged) |\n| `attn.opened` · `attn.closed` | `\u003Cslug>\u002F\u003Cchunk-id>` | `ask` |\n| `cursor.advanced` | `fleetboard` | `events` `signals` |\n| `note` | free | `text` |\n**The view:** `fleet state \u003Cledger> --live [--session fleet-\u003Cepic>] [--tail N]`\nrenders five blocks - header (epic, session, last action, malformed count, policies, cursor) · chunks\n(stage, pane, LIVE status, engine, PR, age, gist; stage = last `chunk.*` event per subject) · checklist\n(counts per stage + a `next:` line) · open items (attn, resources still minted) · live (orphan panes,\ngone panes) · action log tail. Without `--live` it is ledger-only and works with no server up. A\nmalformed line is counted in the header and printed to stderr, never swallowed.\n**Protocol - two rules:** the FIRST command of every wake is the view with `--live`; the LAST command of\nevery wake is one `fleet log` event. Read a pane tail only for a row the view flags (`gone`, `orphan`,\n`blocked`, `error`). The rotation handoff pastes the view verbatim as its state snapshot.\n**Commit cadence:** preserve ledger checkpoints on an owned coordination branch at each completed step and before parking. Push its recovery record and update the run draft PR before rotation or a provider stop. Never wait for a merge to preserve the only run record.\n- **Run wrap-up LAST (invoke the `wrap-up` skill).** Teardown closes herdr resources and the session; wrap-up closes the\n  RUN: one `follow-up`-labeled issue per unresolved concern in the run archive's REPORT sections (linked to\n  the chunk's PR), UAT checkboxes appended to the scope's open `uat` issue (TestFlight build numbers to\n  install, shipped flows to smoke on device, regressions to confirm dead - one live UAT issue per scope),\n  then the closed\u002Ffiled\u002Fkept report into the run map's final comment. A fleet run is not done at\n  deregister - it is done when its loose ends are tickets and its human checks are queued.\n- **Exact ids only** — never pattern-match labels (`fleet:*`) to find things to close; concurrent\n  fleets share the namespace (same live lesson as the worktree cleanup regex).\n- **Rotation-safe:** the handoff doc carries the view's `open resources` block; the successor inherits the\n  teardown obligation with the resources and re-verifies them (`fleet state --live`) like every other\n  snapshot field.\n\n## Context hygiene (you, the orchestrator) - keep yourself clean + resumable\nYour state lives in the **ledger + kanban + git**, NOT your context. So you survive compaction and a fresh\norchestrator can resume from those alone.\n- **Per wake, re-derive from sources of truth** - FIRST `fleet state \u003Cledger> --live`\n  (one view: chunks, checklist, open items, orphans, action log), then `gh project item-list` and\n  `git log` only for what the view cannot answer - do NOT trust memory, and do NOT scan panes.\n- **Read pane *tails* only** (`agent read --lines 30`), never full transcripts. Never `cat` a subagent\n  `.output` transcript into context.\n- **Offload bulk to files:** diffs via `review-package`, pane reports + briefs as files, review verdicts\n  returned terse. Read the *verdict*, not the diff.\n- **Each wake is small + stateless:** render the view → gate (`\u002Freview-all`) → merge → move card → spawn\n  next → append one ledger event (`fleet log`) → done. Don't accumulate; the board + ledger are the memory.\n- **Prompt hygiene when parking (2026-07-10):** never leave unsubmitted draft text on your prompt line when\n  you yield\u002Fidle - supervisors and humans steer you through that line, and a watchdog that finds text there\n  must defer its message (live lesson: a starvation steering was correctly deferred for a full cycle because\n  the orchestrator parked with a half-typed draft). Submit or clear before yielding.\n- Spawn the *building* on panes; keep heavy reading\u002Fsearching in **subagents** (they return conclusions,\n  not file dumps), so your window holds coordination only - and those dispatches are mechanical, so they\n  carry `model:'sonnet'` (`'haiku'` for pure locate), never the inherited orchestrator model.\n\n## Orchestrator rotation — proactive, not incident-driven (2026-07-16)\nOrchestrator main-loops were ~78% of a measured 2-week fleet spend (ax cost split) — cost per wake grows\nwith window size, so cap the window by ROTATING on schedule instead of riding to auto-compact (research +\nsources: `docs\u002Fresearch\u002Forchestrator-context-reduction.md` in the apps repo).\n- **Triggers (single-condition each, never ANDed — the 954k livelock came from conjoined preconditions):**\n  (a) ~70-75% of context window (leaves room to write the handoff BEFORE auto-compact can fire mid-handoff);\n  (b) 4-6h of active wakes as a hard wall-clock ceiling; (c) any rotation-blocking cause observed 2 cycles\n  in a row = incident, rotate now; (d) user says \"rotate\" — immediate.\n- **Rotation is ONE atomic instruction:** write the handoff doc + commit + push + update the draft PR + verify the delivery receipt + park with an empty prompt — never\n  a sequence a watchdog must observe from outside.\n- **Handoff = pointers + fresh query results, never narrative summary** (schema in REFERENCE.md). The\n  successor gets the same SOURCES the predecessor had (ledger path, kanban, agent list, event-log\n  cursor + fallback signals file,\n  steering overrides), not the predecessor's interpretation; the only prose section is Known-blockers.\n- **Successor protocol:** treat every snapshot field as stale — re-run the command behind it; reconcile\n  (orphan sweep) before spawning; re-arm waiters + monitor (process-local, never inherited); register on\n  fleetboard as a new instance; only then read Known-blockers.\n- Keep the handoff REFRESHED as part of parking (existing hard rule) so an unplanned death degrades into a\n  planned rotation.\n\n## Steward mode - on-demand per-machine orchestrator (skills#30; spec #24 + #6)\nA **steward** is this skill's orchestrator run ON a non-primary machine: spawned when the Mac\norchestrator's scheduler assigns chunks to that machine (the steward is the assignment TARGET - the\nplacement interface\u002Falgorithm stays on the Mac and out of scope here), gone when its queue empties.\nIdle machines run ONLY the heartbeat daemon - no idle steward stays resident.\n- **Division of labor (spec #6, exact):** the **Mac orchestrator keeps** wave planning, chunk-to-machine\n  placement, hold tagging, kanban\u002Frun-map upkeep, dogfood triggering, and the human interface. The\n  **steward runs the FULL fleet-ship workflow locally** on its own machine: worktrees, pane spawn\u002Fbrief,\n  idle-waiters + the liveness monitor, the cross-model consensus gate (on its OWN machine, BEFORE\n  claiming), and the merge (under the `main-merge` claim like any orchestrator - the Merge-under-claim\n  flow, TTL'd + FIFO).\n- **Locality is the point:** waiters, monitor loops, and gates ALWAYS run on the steward's own machine -\n  NEVER held open over ssh (a held-open remote loop dies with the connection; that fragility is why\n  steward mode exists). ssh from the Mac stays for one-shot reads\u002Fspawns only. The monitor's \"whole\n  fleet\" scope reads per-machine in steward mode: each steward runs ONE monitor loop covering ITS panes.\n- **Events, not cards:** the steward emits the lifecycle stages it owns (`ASSIGNED → … → MERGED`, always\n  `--machine \u003Cslug>` - see Child→parent lifecycle events); `BUILT` is pane-pushed by the discipline\n  block's SIGNAL STEP, so the steward emits BUILT itself ONLY on `READY_UNCOMMITTED` (never a duplicate);\n  `DOGFOODED` stays Mac-emitted (dogfood triggering is a kept duty). The steward DOES file `follow-up`\n  issues at its own gate triage (its gate, its findings); but the Mac reconciles kanban cards + run map\n  from the event log on its wakes - a steward never edits cards or the map.\n- **Hold tags honored (skills#33):** the hold tag arrives in the chunk's queue entry at assignment. The\n  steward runs the held chunk's FULL workflow but follows Held chunks above: stop at `GATED`, bell with\n  `\u003Cslug>\u002F\u003Cchunk-id>` + verdict + link, `✋` pending the owner's answer; merge (under claim) only on\n  approve, send back on reject. A chunk still awaiting its answer at rotation\u002Fexit is listed in the handoff.\n- **Rotation - same policy, VERBATIM:** the Orchestrator-rotation triggers above apply to stewards\n  unchanged (~70-75% context, 4-6h wall clock, 2 same-cause blocked cycles, user says rotate), and the\n  same successor protocol holds - the successor steward re-derives from the board + local herdr state.\n  ONE rotation policy; steward mode does not fork a second one.\n- **Exit-on-empty:** queue empty → ledger-driven teardown-verify (Resource ledger rules) → write the\n  rotation handoff (the REFERENCE schema, extended with machine slug + held-claim state) → confirm the\n  last chunk's terminal lifecycle event is on the board → `fleetctl deregister` → park\u002Fexit.\n- **Naming (#26 rules, unchanged):** local herdr names stay bare (`\u003Cchunk-id>`; the steward's own pane is\n  `steward:\u003Cepic>`), tab `fleet:\u003Cepic>@\u003Cslug>`, and EVERY off-machine surface - events, ledgers, reports,\n  attention\u002Fbell lines, archives, handoffs - says `\u003Cslug>\u002F\u003Cchunk-id>`.\nSpawn-on-assign contract + brief template: REFERENCE.md 'Steward brief'.\n\n## Hard rules (live-dogfood lessons)\n- **One agent per worktree.** Map before spawning. **Never interrupt a `working` pane;** confirm an empty\n  prompt line before any `agent prompt`.\n- **Typed text APPENDS to whatever is on the prompt line (verified live 2026-07-17); NEVER prompt onto a\n  non-empty line.** The 2026-07-10 \"replaces\" reading was wrong: under append, steering a pane that holds\n  a parked draft CORRUPTS it by concatenation, which is what that incident actually showed. A bare\n  `send-keys Enter` on a human-typed parked draft still cannot be trusted to submit it; verify status flips\n  to `working` after EVERY submit, never assume. Correct parked-draft submit protocol (0.8.0 commands):\n  (1) `agent read` to capture + log the draft, (2) `agent send-keys \u003Ct> Ctrl+U`, then fresh-read to confirm\n  an empty prompt, (3) `agent prompt \u003Ct> \"\u003Cfull intended text>\" --wait` and (4) confirm status flipped to\n  `working`. Only then send your own steering as the next message.\n- **The fleet never spends the Codex weekly reserve (2026-09-06, user rule).** Gate every codex spawn on the\n  weekly window (`7d N%` LEFT via `herdr agent get … .tokens.limit`, or the newest rollout's `rate_limits`);\n  N at or below `FLEET_CODEX_RESERVE` (default 20) refuses the spawn and the monitor's `QUOTA_HALT` closes the\n  codex lanes for the run. Rotation and account switching (`codex-auth` auto-switch) are NOT budget: on\n  2026-09-04\u002F05 ~20 parallel codex panes plus max-effort tandem\u002Fchunk panes drained one Pro account, auto-switch\n  chained a second, and both hit 100% in 31h with no human decision. Never pin `max` effort on a fleet lane.\n- **Name everything locally; qualify everything externally.** `agent start \u003Cchunk-id>` — the herdr NAME is\n  the bare chunk id, unique only inside that server's own agent table (never generic like `codex`: detected\n  labels are also targets → ambiguous locally). ALL `herdr agent *` commands (get\u002Fread\u002Fprompt\u002Fwait\u002Frename\u002F\n  focus\u002Fattach) accept that bare local NAME. Pane id is required ONLY for `herdr pane *`\n  (send-text\u002Fsend-keys\u002Frun\u002Fclose\u002Fwait-output) — resolve on that server:\n  `herdr agent get \u003Cchunk-id> | jq -r .result.agent.pane_id`. Every reference that leaves the machine —\n  ledger, kanban card, run map, lifecycle\u002Fsignal\u002Fmonitor event, `fleetctl attn` line, run archive, rotation\n  handoff, and report to the human — MUST use `\u003Cmachine-slug>\u002F\u003Cchunk-id>`. Human reports say\n  `\u003Cmachine-slug>\u002F\u003Cchunk-id> (\u003Cpane_id>)`, never a bare name or pane id.\n- **There is no cross-host herdr namespace.** Two servers may both have a bare agent named `sdk-migrate`;\n  herdr detects no collision, so recording or driving bare `sdk-migrate` across machines can silently\n  attribute work to the wrong pane. Prevention is the pair above: qualify every off-machine reference, and\n  drive another server only as `ssh \u003Chost> 'herdr \u003Csubcommand> ...'`, with the host explicit at each call\n  site. Never point a local client at a remote socket or write `herdr --remote \u003Chost> agent ...`;\n  `--remote` only opens the interactive UI attach and is not composable with driving subcommands.\n- **Four-level placement: session=fleet run · workspace=`\u003Cepic>` · tab=machine · pane=chunk.** Every\n  fleet resource lives in the run's own herdr session `fleet-\u003Cepic>` (Setup step 7), never in the human's\n  default session - so no fleet pane can land in an interactive tab, and one `session stop` ends the run.\n  Inside it: one `\u003Cepic>` workspace, one `fleet:\u003Cepic>` tab on primary \u002F `fleet:\u003Cepic>@\u003Cslug>` per\n  non-primary machine, bare-named chunk panes in that tab. Prefix EVERY driving command with\n  `--session fleet-\u003Cepic>`; the orchestrator's own pane is the only bare `herdr` target.\n  **Retrofit\u002Fmoves (dogfooded on a LIVE working codex pane — survives untouched):** `herdr pane move \u003Cpane_id>\n  --tab \u003Ctab_id>` (existing tab) \u002F `--new-tab --workspace \u003Cws> --label TEXT` \u002F `--new-workspace --label TEXT\n  --tab-label TEXT` (creates workspace+tab+moves in one command; use `--no-focus`). CRITICAL: the pane_id\n  CHANGES on move (wV:pC → w0:p1) but the agent NAME resolves seamlessly across it — one more reason waiters\n  and every reference must target the NAME; any pane-id-addressed waiter dies silently on a move (re-arm by\n  name).\n- **Idle != done — and `done`, not `idle`, is how panes often END.** Codex chunks finish in status `done` (terminal); gate on polled `agent get` payloads in `idle|done`, never `= idle` alone (else the waiter loops past a finished pane to TIMEOUT). 0.8.0 retired the old workaround: `agent wait \u003Ct>` with no flag matches `idle|done|blocked`, and `--until done` is a first-class target - but the STATUS is still only the wake, never the gate. A pane can finish **gated-green but uncommitted** → gate on stable-idle AND (commit OR dirty tree); on idle+dirty the orchestrator commits the pane's work itself (`READY_UNCOMMITTED`). See REFERENCE 'Refinement 2'.\n- **Idle != done (background-shell flap).** A pane reports idle\u002F`done` while merely *holding on a background shell* (a test suite,\n  a forked review). Gate on a REAL signal: a **commit beyond `origin\u002Fmain`** + a final report\u002FSTOP - not bare\n  idle. Make the waiter **commit-gated** (re-arm until a commit appears). Live lesson: a pane mid `+2292\u002F-11510`\n  with the suite running flapped `idle`→`working`, storming the naive idle-waiter.\n- **Non-Claude panes miss repo conventions Claude Code auto-absorbs — point them at CLAUDE.md; the gate catches the rest.** Grok wrote\n  `import from \"bun:test\"` + `toStartWith` in a vitest repo: **typecheck + verify:effect PASSED**, but the\n  test file failed to load → 0 tests ran. So (a) name the repo's test framework + matcher set in the brief\n  (e.g. \"vitest, import from 'vitest', no bun:test\u002FtoStartWith\"); (b) the orchestrator's gate must\n  **actually run the new tests** - typecheck\u002Fverify alone pass over a non-loading or wrong-matcher test.\n- **Gate completeness: enumerate the FULL verification matrix, per chunk, from the plan (2026-07-10).** A gate\n  once ran only a boot test on a multi-scheme app and passed a chunk the plan gated on 4 schemes. The gate\n  step must LIST what the plan's phase names (every scheme, every suite, sim build, screenshots) and check\n  each off - \"some test ran green\" is not a gate.\n- **Liveness = branch commits, not board deltas (2026-07-10).** Any monitor\u002Fwaiter\u002Fwatchdog deciding\n  starved\u002Fstuck\u002Funresponsive must check recent COMMITS on the fleet's branches before flagging - gh-closed\n  deltas batch behind gate queues (a watchdog false-alarmed 6x in one night on that signal alone; adding a\n  commits-alive check eliminated them).\n- **A safety protocol must have AUTHORITY to cause its own preconditions (2026-07-10 rotation livelock).**\n  The orchestrator context-rotation protocol required (fresh handoff) AND (idle + empty prompt) - the\n  watchdog could only wait for both, they never aligned, and a human had to rotate manually at 954k ctx.\n  When designing any monitor-triggered maneuver: every precondition needs either an action that CAUSES it\n  (submit the blocking draft after logging it; order \"checkpoint + park empty\" as ONE atomic instruction)\n  or a hard-ceiling override; freshness checks compare against content (newer than last state commit),\n  never wall-clock windows; and 2 consecutive same-cause blocked cycles = an incident, not patience.\n  Orchestrators: keep the handoff refreshed as part of PARKING, not as a favor when asked.\n- **Green != correct — enforce SEAM discipline (define_view dogfood lesson).** A chunk shipped 31 green unit\n  tests yet the feature hung in prod because they **mocked the dispatch (`CreateGoal`) — the behavior under\n  test**; \"green\" meant \"called the mock.\" The rules already existed (`testing-anti-patterns.md` + both review\n  rubrics ask *\"tests verify real behavior, not mocks?\"*) — the miss was not wiring them into the fleet. So:\n  (a) every brief names the seam rule + points at `testing-anti-patterns.md`; (b) the gate runs the seam check\n  (delete-the-mock heuristic + task-reviewer rubric) and REJECTS behavior-bearing chunks whose tests mock their\n  own dispatch; (c) such chunks carry a real-seam acceptance assertion (mock only non-deterministic leaves).\n  UAT\u002Fdogfood is the backstop, not the primary catch.\n- **Never close a pane before archiving its result.** `close` is where the transcript dies (no herdr export; session-attach not guaranteed post-close). Capture `agent read --source recent` → the git-tracked run archive (`docs\u002Fsuperpowers\u002Ffleet-runs\u002F\u003Cepic>.md`) FIRST, then close. The archive — not the live pane — is the restorable record.\n- **Housekeep ONLY worktrees THIS run created — never pattern-match names.** Same law for herdr panes\u002Ftabs - close from the ledger's `fleet.resource.minted` events (see Housekeeping: Resource ledger), never by label pattern. Track each worktree you `git worktree add` (by exact path) and remove only those. A broad `grep`\u002Fregex over `git worktree list` WILL catch other sessions' parked branches (live lesson: a cleanup regex removed byo-cloudflare\u002Fchannels\u002Ffix-* worktrees from prior streams). Committed work survives on the branch (recreate with `git worktree add \u003Cpath> \u003Cbranch>`), but **uncommitted edits in someone's idle worktree are lost**. Before removing ANY worktree you didn't just create: confirm no live agent is cwd'd there AND it has no uncommitted changes (`git -C \u003Cwt> status --porcelain`).\n- **Orchestrator gates the merge** - panes never auto-merge to main (checkpoint + avoid collisions).\n- **Never brief `git add -A` while worktree-root scratch exists (live lesson - BRIEF.md\u002FREPORT.md shipped to main twice).** Pane briefs and reports live at the worktree root; `add -A` commits them, the squash-merge lands them on main, and every later worktree \"inherits\" a stale brief. Fix: gitignore the scratch names (`\u002FBRIEF.md`, `\u002FREPORT.md`) in the repo once, AND write briefs with explicit `git add \u003Cpaths>` or `git add -A ':!BRIEF.md' ':!REPORT.md'`. Gate check: the review diff must not contain the brief\u002Freport files.\n- **Long briefs travel as files, not keystrokes (2026-07-10 API-drop lessons).** Spawning\u002Fbriefing with a\n  large prompt over `agent prompt` during API instability drops mid-stream and leaves half-briefed panes +\n  stale drafts. Write the brief to the worktree as BRIEF.md and SEND A SHORT POINTER (\"read BRIEF.md and\n  execute\"); same for any steering over ~10 lines.\n- **Waiter timeout != stuck: verify liveness before acting (2026-07-10).** Commit-gated waiters time out\n  under legitimately long chunks (a pane on task 8 with 8 commits got flagged twice). On waiter exit:\n  check pane status + recent commits FIRST; alive -> re-arm with a longer timeout (or require heartbeat\n  commits in the brief); only dead\u002Fcommit-silent panes get the stuck treatment. An \"API Error: Connection\n  closed mid-response\" tail + clean worktree = RECOVERABLE mid-turn drop: nudge the same pane, don't respawn.\n- **A wrapper agent completing is NOT a review verdict (2026-07-10).** Review-wrapper subagents drop under\n  API instability and can return without a verdict; the gate must check a verdict EXISTS, and on wrapper\n  failure fall back to direct CLI (`codex review` \u002F `grok` via Bash), logging the wrapper failure. Never\n  count a wrapper's clean exit as a PASS.\n- **Event-driven, not timed.** Canonical background waiters use `herdr agent wait` only for bounded\n  backpressure; polled `agent get` status plus git state is the completion gate. `send_later`\u002F\n  `ScheduleWakeup` may be unavailable (no CCR session). If herdr can't track an engine's status, fall that\n  chunk back to one it can (codex\u002Fclaude). **Engines run out of credits\u002Fquota mid-run** (grok hit a\n  `403: run out of credits`, pane frozen) - detect via a pane read, close the dead pane, and re-spawn the\n  chunk on a fallback engine (grok→codex→fable\u002Fopus, ascending intelligence) in the SAME already-installed worktree. Keep >1 lane funded.\n  **The idle-waiter will NOT catch a frozen\u002Ferrored pane** (it never goes idle) - the **liveness monitor** (above) is the\n  proactive spine that catches it. Always run BOTH per active pane: the git-state waiter for *done*, the monitor for *stuck\u002Ferrored\u002Fdead*.\n- **Parallelize only within a wave where chunks don't share files.** **Verify \"already done\" claims**\n  against current code before building (recent merges shift things).\n\nSee [REFERENCE.md](REFERENCE.md) for brief templates, kanban `gh` commands, the waiter script, engine flags.\n","# Fleet Ship - parallel herdr orchestration\n\nBefore run setup, assignment, completion, rotation, or teardown, read [Durable task delivery](..\u002Fherdr-agent-orchestration\u002Freferences\u002Fdurable-delivery.md).\nWorkers publish their assigned branches and maintain draft PRs. The coordinator owns review and merge.\nEvery saved research or exploration task uses the same delivery receipt.\n\nYou are the **orchestrator** (run on fable-5 or opus-5). Panes do the building; you plan the waves, route engines,\ngate reviews, merge, track on a kanban, and dogfood. This skill *composes* our normal ship workflow -\nit just runs it across many parallel herdr panes instead of one session.\n\n## Multi-orchestrator coordination (MANDATORY - several fleets run this repo concurrently)\nThe registry is **fleetboard** - a live board at `$FLEET_BOARD_URL` (default `http:\u002F\u002Flocalhost:7777`,\nserver + CLI in `~\u002FProjects\u002Ffleetboard`; VPS fleets set FLEET_BOARD_URL to the Mac's tailscale addr).\nDrive it with `bun ~\u002FProjects\u002Ffleetboard\u002Ffleetctl.ts \u003Cregister|heartbeat|claim|release|attn|event|events|deregister>`\n- claim returns exit 1 + holder when a resource is taken. Heartbeat each orchestrator wake. If the\nboard is unreachable, fall back to `docs\u002Fsuperpowers\u002Ffleet-runs\u002FACTIVE.md` in the target repo.\nLive lessons that forced this: a fleet rebased main under another fleet's staged merge; three merges\nlanded vitest-breaking test files; a port cleanup killed a sibling fleet's dev servers and a native\nbuild mid-compile.\n1. **Register on run start** (epic, status), **deregister on run end**, heartbeat between.\n2. **Claims are exclusive, TTL'd + FIFO** (Fleetboard v2 Durable Object alarm; #15 owns the mechanics -\n   this documents the protocol you follow, not the DO internals). A taken claim returns exit 1 + the\n   holder + your FIFO queue position; the queue position is HONORED - your turn comes in order, never\n   jump it or poll-race it. A claim whose TTL expires **auto-releases** - an expired holder has LOST the\n   claim (mid-merge expiry: see Merge under claim). **Claim discipline is REQUIRED, not nice-to-have:**\n   several gating machines merge this repo concurrently and the claim is the ONLY serialization.\n   Resources: `main-merge` (only the holder merges\u002Frebases main - the full flow is Merge under claim\n   below; others hold their gated branches and wait their queue turn), `sim:\u003Cudid>` (boot a SEPARATE\n   simulator per fleet - `xcrun simctl list devices available` then `boot`; never install\u002Flaunch on a\n   claimed sim), `ports:\u003Capp>` (better: run dev stacks from YOUR worktree so `scripts\u002Fworktree-ports.sh`\n   + portless auto-offset - then no port claim is needed), `neon:\u003Cproject>` (dev-DB migrations).\n3. **Before killing anything shared** (kill-port-listeners, `just * kill`, pkill, sim uninstall):\n   check the registry; if another fleet holds the claim, work around it or queue.\n4. **Shared merge gate**: `bun run test:vitest` from the repo root must be green before ANY merge to\n   main, whatever the fleet's own runner is (bun-runner-only gates shipped broken files three times).\n5. **The bell - single attention surface**: when blocked on a human decision or a must-see finding,\n   `fleetctl attn \u003Cfleet-id> \"\u003Cone-line ask>\"` (shows on the board + ntfy phone push) - plus\n   PushNotification when running on the user's Mac. Never ring for routine progress; the user watches\n   the board's attention list as the only inbox and expects silence otherwise. Poll `\u002Fstate` for the\n   user's typed answer on your item after ringing.\n6. **Name your orchestrator pane\u002Ftab** (`herdr tab create --label \"orchestrator:\u003Cepic>\"`) so\n   `herdr agent list` yields a truthful census.\n7. **Start the run's own herdr session + open its ledger.** One session per fleet run, named\n   `fleet-\u003Cepic>`. `herdr session list` first - reuse it if it is already running; otherwise start it\n   headless: `nohup herdr --session fleet-\u003Cepic> server \u003C\u002Fdev\u002Fnull >\u002Fdev\u002Fnull 2>&1 &` (no `setsid` - macOS\n   has none; probed 2026-09-03, the server survives the spawning shell), then poll\n   `herdr --session fleet-\u003Cepic> agent list` until it answers (~2s). YOUR orchestrator pane stays in the\n   default session (the human sees it without attaching; `session stop` can never kill it). From here on\n   EVERY command that touches a fleet resource carries the prefix `herdr --session fleet-\u003Cepic> …`\n   (remote: `ssh \u003Chost> 'herdr --session fleet-\u003Cepic> …'`; the same session name on every machine).\n   The ledger is `docs\u002Fsuperpowers\u002Ffleet-runs\u002F\u003Cepic>.jsonl` in the target repo, written ONLY through\n   the `fleet` CLI - `fleet` below means `bun ~\u002F.claude\u002Fskills\u002Ffleet-ship\u002Fscripts\u002Ffleet.ts` (TypeScript on\n   Effect 4; `bun install` once in that `scripts\u002F` dir; `alias fleet='bun ~\u002F.claude\u002Fskills\u002Ffleet-ship\u002Fscripts\u002Ffleet.ts'`\n   per shell) - see 'Ledger + state view'. First three events, in this order:\n   `fleet log \u003Cledger> fleet.run.started \u003Cepic> session=fleet-\u003Cepic> runmap=\u003Curl> kanban=\u003Curl>`,\n   `fleet log \u003Cledger> fleet.resource.minted session:fleet-\u003Cepic> label=fleet-\u003Cepic>`, and one\n   `fleet.policy.set` per routing\u002Fsteering rule in force (lane file version included).\n\n### Merge under claim - the ONLY way anything lands on main\nMerge-worthiness = the FULL fleet-ship workflow passed WHEREVER the chunk ran (plan → cheap-lane build →\nmulti-agent review → feedback traced → final smart-model review - i.e. per-chunk-loop step 6's cross-model\nconsensus gate, UNCHANGED and referenced here, not redefined). Run that gate on YOUR OWN machine BEFORE\nclaiming - a claim held while you still review starves the queue. Passing the chain on ANY machine is\nsufficient - NO central re-review. Central merge queue REJECTED (#6, verbatim): it \"re-runs suites already\nrun, idles branches on one machine's availability, recreates the single-machine dependency\" - that is why\nthe passing-workflow-on-any-machine model is used instead. The flow (ordered; no step skippable):\n1. **Claim** `main-merge` - or take your FIFO queue position and wait your turn (do other work; never\n   poll-race or jump the queue).\n2. **Rebase** the gated branch on latest main (only the holder may touch main).\n3. **Repo-root gate LOCALLY:** the repo's FULL root gate (`bun run test:vitest`-equivalent from the repo\n   root, whatever the fleet's own runner - the Shared merge gate rule above) runs green on the MERGING\n   machine, before the merge.\n4. **Re-assert the claim, then squash-merge** to main. Step 3's local root gate can outrun the TTL, so at\n   this irreversible instant re-verify the claim is STILL yours; merge + push ONLY under a live claim - if it\n   expired, do NOT merge, drop to abort + re-queue below. (#15's DO fences the push so an expired holder's\n   merge is rejected - naming the re-check point here; the enforcement is #15's.)\n5. **Emit `MERGED`** (`fleetctl event MERGED --machine \u003Cslug> --chunk \u003Cchunk-id> …` - the lifecycle\n   event; see Child→parent lifecycle events).\n6. **Release** the claim.\n**TTL expiry mid-merge: abort + re-queue, NEVER half-merge.** The expired claim auto-releases and the next\nholder may touch main - so on expiry (or on noticing you have outlived the TTL): abort the in-flight\nrebase\u002Fmerge (`git rebase --abort` \u002F `git merge --abort`; main stays untouched, your gated branch is\ndurable), re-enter the FIFO queue, and on reacquire restart from step 2 - main has moved. Steps 2-5 happen\nONLY while you verifiably hold the claim.\nHold-tagged chunks stop at GATED for the human before this flow - see Held chunks below (#33). Forward\npointers, out of scope here: chunk→machine placement stays on the Mac (#35); claim DO\u002Falarm internals are\nFleetboard v2 (#15). This protocol is E2E-verified by the tracer bullet (skills#13), not a unit suite.\n\n### Held chunks - hold:human stops at GATED (skills#33)\nAutonomous merge on workflow pass is the DEFAULT - a hold is the named exception, never a new gate on\neverything. The Mac scheduler tags `hold:human` (or `hold:central`) at ASSIGNMENT on exactly three chunk\nclasses: **reactor-subtle, security-critical, user-facing design** (tagging + placement are #35's - here\nyou only honor a tag that arrives). The tag travels in the chunk's queue entry; whoever runs the chunk\n(steward or orchestrator) honors it per chunk:\n1. Run the FULL per-chunk loop unchanged through the consensus gate → emit `GATED` (the lifecycle\n   event) → **STOP. Do NOT claim `main-merge`.**\n2. **Ring the bell:** `fleetctl attn \u003Cfleet-id> \"\u003Cslug>\u002F\u003Cchunk-id> \u003Cone-line gate verdict> \u003Clink>\"` -\n   machine-namespaced chunk id + gate verdict + a LINK the owner can open: today a PR\u002Fcompare URL or the\n   chunk's run-archive section; when the access-plane link surface lands (#11) the link upgrades to its\n   artifact URL - forward pointer only, do not block on it.\n3. Flip the pane label to `✋ \u003Cchunk-id>` (the existing needs-a-HUMAN glyph, already paired with\n   `fleetctl attn`) - mirrored on the board's attention list per the sidebar invariant.\n4. **Poll `\u002Fstate` for the owner's answer on YOUR attn item** (the bell rule's existing poll). Two\n   branches, both explicit:\n   - **approve** → proceed to Merge under claim above, UNCHANGED (claim\u002FFIFO → rebase → local root gate →\n     squash-merge → `MERGED` → release).\n   - **reject \u002F changes** → SEND-BACK: re-open the chunk with the owner's findings as the brief - a fresh\n     spawn in the SAME worktree (the Housekeeping send-back pattern), findings judged via\n     `superpowers:receiving-code-review`; the chunk re-enters the loop at build and re-rings on its next\n     `GATED`.\n\n## Skills this composes (the chain - invoke these, don't reinvent)\n- **Drive panes:** `herdr-agent-orchestration` (read FIRST - `agent list\u002Fread\u002Fprompt\u002Fwait`, `pane send-keys\u002Fwait-output`, `agent start --kind --pane`).\n- **Plan:** mechanical chunks → `superpowers:writing-plans` only. Design\u002Fambiguous chunks in *autonomous*\n  fleet mode → **parallel design-exploration** (`superpowers:dispatching-parallel-agents` \u002F `design-an-interface`:\n  N independent *lens* subagents → 1 synthesizer → an options doc + recommendation, **marked AWAITING-DECISION**).\n  Interactive `superpowers:brainstorming` interviews the user - only run it when YOU\u002Fthe user drive it live, never\n  in an unattended pane. (Parallel-explore generates options; it does NOT replace the user's decision.)\n- **Build:** `superpowers:subagent-driven-development` (runs `superpowers:test-driven-development` +\n  `superpowers:using-git-worktrees` internally). **Seam discipline:** its `testing-anti-patterns.md` is the authority — mock only non-deterministic *leaves* (model\u002FLLM, clock, net), NEVER the code path the test is named after.\n- **Review:** `\u002Freview-all` = `simplify` + `\u002Fcodex:review` + `\u002Fcodex:adversarial-review`; plus\n  `superpowers:requesting-code-review` \u002F `superpowers:receiving-code-review` for the judgment on findings.\n- **Route dispatches:** `efficient-dispatch` - every Agent-tool dispatch (orchestrator or Claude pane) is\n  classified mechanical-vs-judgment and mechanical ones carry an explicit cheap `model:`; `ax dispatches`\n  measures the inherit rate afterwards.\n- **Finish:** run the repo's CONCRETE gates by name (`bun run typecheck` 0, `verify:effect` 0, suites green)\n  → `superpowers:finishing-a-development-branch` (PR) → orchestrator merges → `commit` conventions.\n  (`superpowers:verification-before-completion` DISABLED 2026-07-29 per the Opus-5 prompting doc - frontier\n  panes self-verify; a brief naming a disabled skill silently degrades to prose. Concrete gate commands\n  stay in every brief; the meta \"verify before claiming done\" ceremony does not.)\n- **Dogfood:** `dogfood` (+ `verify` \u002F `run` to launch the app).\n- **Wrap up the run:** `wrap-up` - run-end closure AFTER teardown-verify: follow-up tickets for every\n  unresolved REPORT.md concern and gate-waived finding, UAT checklist items for what shipped, safe-only\n  residue cleanup, closed\u002Ffiled\u002Fkept report.\n\nClaude panes (fable\u002Fopus\u002Fsonnet) invoke these directly. **pigrok\u002Fcodex panes lack the Skill tool → bake the discipline\n(plan-first, red→green TDD, gates) into their brief text.** The orchestrator (fable\u002Fopus) always owns Review + Finish.\n\n## Model axes (rankings, higher = better; cost = what the user actually pays, not list price)\nIntelligence = how hard a problem the model handles unsupervised. Taste = UI\u002FUX, code quality, API design, copy.\n| model | cost | intelligence | taste | how to run |\n|---|---|---|---|---|\n| gpt-5.5 | 9 | 8 | 5 | Codex CLI ONLY - `codex exec` \u002F `codex review` (`~\u002F.codex\u002Fconfig.toml` defaults to gpt-5.5); herdr pane = codex argv below |\n| grok-4.5 | 8 | 7 | 4 | grok CLI - `grok --always-approve` (`-m` to pin model); second mechanical lane, peer of codex (2026-07-10). **BUILD lane only - grok STALLS on review workloads (live 2026-07-10): never route reviews to grok.** Cross-engine review of grok-built work → codex; review of codex-built work → fable\u002Fopus adversarial (not grok) |\n| sonnet-5 | 5 | 5 | 7 | `claude --model sonnet` \u002F Agent `model:'sonnet'` |\n| opus-5 | 3 | 8 | 8 | `claude --model opus` \u002F Agent `model:'opus'` - the alias resolves to Opus 5 now (2026-07-29 resweep); thinking ON by default, disable-thinking capped at effort `high` - lower effort instead of disabling thinking; review quality holds at low\u002Fmedium effort (Opus-5 doc) |\n| fable-5 | 2 | 9 | 9 | `claude --model fable` \u002F Agent `model:'fable'` - Mythos-class tier above Opus; same routing role as before |\n\n**How to apply (defaults, NOT limits):**\n- **Standing permission to escalate:** cheaper model's output doesn't meet the bar \u002F fails the gate ->\n  re-run or re-spawn the chunk on a smarter model in the SAME worktree, without asking. Judge the output,\n  not the price tag. Escalating costs less than shipping mediocre work.\n- **Cost is a tie-breaker only.** Anything that ships: **intelligence > taste > cost**.\n- **Bulk\u002Fmechanical** (clear-spec implementation, data analysis, migrations) -> gpt-5.5, effectively free.\n- **User-facing** (UI, copy, API design) needs **taste >= 7** -> sonnet-5\u002Fopus-5\u002Ffable-5, never gpt-5.5 solo.\n- **Reviews of plans\u002Fimplementations** -> fable-5 or opus-5, optionally gpt-5.5 (`codex review`) as an\n  extra independent perspective (`\u002Freview-all` already includes it).\n- **Subagent dispatches (Agent tool) - classify EVERY dispatch before sending, then the model field follows\n  (REQUIRED SUB-SKILL: `efficient-dispatch`).** A bare dispatch silently inherits the caller's model - from\n  the orchestrator that is fable-5, the most expensive lane (same trap as an unpinned `claude` pane; live\n  lesson 2026-07-16: fleet runs bled tokens on default-model launches for non-judgment work). Routing:\n  pure search\u002Flocate\u002Fpattern-find → `model:'haiku'`; mechanical implementer \u002F fix subagents \u002F bulk\n  reads-for-a-fact \u002F codex-exec wrappers → `model:'sonnet'`; judgment (review verdicts, design synthesis,\n  gate decisions) → keep the strong model (inherit fable\u002Fopus deliberately - cheap reviewers miss real bugs).\n  Applies to the orchestrator AND to Claude panes (their discipline block carries the same rule).\n- **NEVER use Haiku for panes, builds, or any review\u002Fjudgment.** The one sanctioned use is read-only\n  search\u002Flocate subagent dispatches per `efficient-dispatch`.\n- **gpt-5.5 inside subagents\u002FWorkflows** (the `model` param takes Claude models only): thin Claude wrapper\n  agent `model:'sonnet', effort:'low'` whose prompt writes a self-contained codex prompt, runs `codex exec`\n  via Bash, and returns the result; investigation\u002Fdata-analysis -> `codex exec -s read-only` with a\n  self-contained prompt. In herdr panes skip the wrapper - spawn the codex CLI directly.\n\n**Opus-5-class alignment (2026-07-29, from the \"Prompting Claude Opus 5\" platform doc - applies to fable-5\nand opus-5+ panes\u002Fdispatches):**\n- **Effort is the primary cost lever on Claude dispatches:** mechanical Agent dispatches carry\n  `effort:'low'` alongside `model:'sonnet'`; step up only when the gate fails. Doc: low\u002Fmedium hold quality\n  at a fraction of the tokens - mirror of the codex lanes' pinned `model_reasoning_effort=\"medium\"`.\n- **Review briefs never say \"be conservative\" \u002F \"only report high-severity\" \u002F \"must-fix only\":** an\n  Opus-5-class reviewer follows that literally and under-reports. Reviewers report EVERYTHING; severity\n  filtering is the orchestrator's triage pass, not the reviewer's self-censorship. (The gate's\n  must-fix\u002Fshould-fix tiers are triage labels applied AFTER full reporting - keep them there.)\n- **No stacked self-verification on frontier panes:** fable\u002Fopus panes self-verify and self-correct; do not\n  add \"double-check your work\" \u002F \"re-verify before responding\" \u002F verify-with-a-subagent ceremony to their\n  briefs - it compounds with native behavior and burns tokens for nothing. Concrete repo gates (typecheck,\n  vitest, verify:effect) are task spec, not ceremony - those stay. Codex\u002Fgrok\u002Fsonnet briefs KEEP the\n  spelled-out discipline; this relaxation is frontier-Claude-only. Cross-ENGINE review (consensus gate,\n  tandem) is diversity, not re-verification - unchanged.\n- **Scope pin in every brief:** one line - \"deliver what the chunk spec asks, at the scope intended; note a\n  better approach in REPORT.md in one sentence rather than widening the chunk.\" Opus-5-class panes expand\n  scope readily; unscoped improvements become review noise and merge risk.\n\n## Engine routing (default policy — USER-STEERABLE via ~\u002F.ax\u002Ffleet-routing.json)\n**At fleet start (and on any steering sentence), read `~\u002F.ax\u002Ffleet-routing.json`** — the ax-idiom lane table\n(`{lanes:[{id, match, engine, argv, enabled, reason, origin}]}`). It OVERRIDES the table below; the table is\nthe fallback when the file is absent\u002Finvalid. Route each chunk to the enabled lane whose `match` best fits;\nskip `enabled:false` lanes. The user edits the file to re-route (e.g. flip judgment→opus) without touching\nthis skill; record which lane file version a run used in the ledger. Resolution order:\n**user sentence override (ledger) > ~\u002F.ax\u002Ffleet-routing.json > table below.**\n| work class | engine | notes |\n|---|---|---|\n| mechanical (clear spec, schema\u002Fvalidator\u002Fwiring, 1-3 files, migrations, data analysis) | **codex \u002F gpt-5.5** `codex --dangerously-bypass-approvals-and-sandbox` **AND grok-4.5** `grok --always-approve` - TWO peer lanes; route each unblocked mechanical chunk to whichever has free capacity, run both in parallel when several chunks are unblocked | codex: effectively free, reads CLAUDE.md. grok: same brief discipline (no Skill tool - spell it out); escalation ladder grok\u002Fcodex → fable\u002Fopus in the SAME worktree. Keep >1 lane funded |\n| burst overflow only (both mechanical lanes saturated) | pigrok `pi --model xai-oauth\u002Fgrok-4.3 --approve` | expect convention mop-ups (bun:test\u002FcatchAll) + credit risk; gate hard |\n| judgment \u002F reactor-subtle \u002F security \u002F hard-unsupervised | **opus-5** `claude --model opus --dangerously-skip-permissions` | matches the json's judgment lane; fable BUILDS nothing - scoping\u002Fplanning\u002Freview only (user steer 2026-07-12, the json's frontier lane); always pin `--model` |\n| user-facing: UI \u002F copy \u002F API design | **opus-5** (taste 8) | never gpt-5.5 solo (taste 5); sonnet-5 acceptable floor; fable reviews the result, never builds it |\n| review + gate + merge | orchestrator (fable-5 or opus-5) + `codex review` as extra independent perspective | never delegated |\n\n**Steering:** the user can override routing at ANY time with one sentence (\"route all mechanical to codex\",\n\"no pigrok this run\", \"everything on opus tonight\"). Apply it for the remainder of the run, write the active\noverride into the run ledger (so a resumed orchestrator keeps honoring it), and ask once whether to persist\nit into this table as the new default.\n\n### Placement - after lane selection: (chunk, lane) → (machine slug, steward assignment) (skills#35)\nLane selection above picks WHAT engine runs a chunk; placement picks WHERE. The **Mac orchestrator** - and\nonly it, placement is a kept duty (#6 point 6) - composes per chunk:\n**chunk → lane (engine, resolution order above) → machine (registry match) → steward assignment.**\n- **Pinned contract (the stable interface):** inputs `(chunk, lane)` → outputs `(machine slug, steward\n  assignment incl. hold tags)`. The slug is the machine id minted by `fleetctl join --name \u003Cslug>`; the\n  assignment lands in that machine's queue on the fleetboard - the steward is the assignment TARGET\n  (Steward mode below, skills#30), or the Mac orchestrator runs the chunk itself when the target machine\n  is the Mac (a Mac-local chunk has no separate steward) - with any hold tags attached to the queue entry.\n- **Machine match = registry match (#5 schema), all tiers:** **engines-with-account** (the lane's engine\n  authed there AND its quota pool owner-consented) · **static** (capability vs the chunk's declared needs)\n  · **dynamic** (in-window now, free slot, not stale) · **policy** (owner limits honored).\n- **`~\u002F.ax\u002Ffleet-routing.json` stays engine-policy-only (#5 point 4):** lanes never name machines - NO\n  machine-qualified lanes, NO lane×machine cross-product file. Machines live in the registry; engine\n  policy lives in the lane file; the two meet only here, at placement.\n- **Hold tagging happens HERE - at assignment, on the Mac orchestrator (#6 points 5-6):** the three held\n  classes (reactor-subtle, security-critical, user-facing design) get `hold:human` (or `hold:central`)\n  attached to the assignment; whoever runs the chunk honors the tag per Held chunks above (skills#33).\n- **Placement algorithm - filter-then-priority (deliberately dumb v1, resolved in skills#10):** WHICH\n  eligible machine wins among registry-match survivors is decided by two deterministic passes over the\n  registry fields (#5 schema). **Hard filters - a machine must pass ALL:** machine `state === \"active\"`\n  (drop pending\u002Fstale) · the lane's engine is authed on the machine **AND** owner-consented per the\n  machine's per-engine consent policy (default `owner-only` on machines the operator doesn't own - see gap\n  below) · **capability match** of the chunk's declared `needs` (scheduler-declared at wave planning,\n  default none -> every machine passes) against the static tier (e.g. an Xcode-needing chunk requires\n  non-null `xcodeVersion` and\u002For the required `simRuntimes` entry) · `inWindowNow` (window FILTER only -\n  never place out-of-window; the graceful close\u002Fdrain + hard grace cap is steward RUNTIME behavior spec'd in\n  skills#10 point 3, not yet landed in Steward mode - follow-up) · `freeSlots > 0` · a chunk flagged long\u002Fjudgment is filtered OUT of\n  `preemptible === true` machines. **Priority among survivors (first differing key wins, fully\n  reproducible):** pinned (`policy.preemptible === false`) before preemptible -> warm worktree\u002Fcache for the\n  repo (**skipped when the signal is absent** - no registry field carries it today, a v1 no-op; see gap) ->\n  most `freeSlots` -> alphabetical machine slug. **No migration after placement.** Mid-chunk account-dry\n  raises the existing escalation and `BLOCKED: quota` stops further placement of that engine on that machine\n  for the run. Rejected for v1 (all learnable later from the event log): scoring, quota-remaining\n  weighting, latency-aware placement. This is the policy resolved in skills#10; like the rest of the fleet\n  protocol, placement is E2E-verified by the tracer bullet (skills#13), not a unit suite.\n- **Registry gaps this v1 degrades around (documented, not invented - follow-up candidates):** (1) the\n  policy tier carries no `enginesPolicy` per-engine consent field yet (skills#10 spells it `engines_policy`) - the authed-AND-consented filter is\n  specified but reads `owner-only` on non-owned machines until that field lands; (2) no per-repo\n  warm-worktree\u002Fcache signal exists - that priority tier is a no-op today; (3) chunks carry no declared\n  `needs` capability channel beyond the scheduler's default-none - capability match passes every machine\n  until chunks declare `needs`. All three degrade gracefully now and keep the algorithm executable from\n  today's fields.\n\n## Sidebar legibility — the herdr sidebar IS the human's status board\nThe user reads the sidebar to know *what needs me* vs *what's fine* — an unnamed pane, a duplicate\nworkspace label, or a stale label is a housekeeping DEFECT (live audit 2026-07-16: 6 of 8 agents unnamed,\ntwo workspaces both labeled \"apps\" — illegible). Two independent surfaces, verified live:\n**agent NAME = server-local addressing** (waiters\u002Fcommands target it — set once to the bare chunk id,\nNEVER rename mid-run)\nand **pane LABEL = display** (`herdr pane rename \u003Cpane_id> \"\u003Cglyph> \u003Cchunk-id>\"` — safe to change freely;\nname-addressing survives it). The slug minted by `fleetctl join --name \u003Cslug>` is the machine id: keep\nlocal herdr names\u002Flabels bare, but write `\u003Cslug>\u002F\u003Cchunk-id>` on every surface that leaves that machine.\n- **On spawn** every fleet pane gets BOTH: local agent name = `\u003Cchunk-id>` AND local pane label\n  `▶ \u003Cchunk-id>`. The enclosing tab identifies a non-primary machine: `fleet:\u003Cepic>@\u003Cslug>`; keep\n  `fleet:\u003Cepic>` on the primary machine.\n- **Status glyphs (fixed vocabulary, update the label at every transition):**\n  `▶` building · `⏳` built, queued for gate · `🔎` under review\u002Fgate · `✋` needs a HUMAN decision\n  (always paired with `fleetctl attn`) · `❌` errored\u002Fstuck (monitor caught). No ✅ glyph — a finished pane\n  is archived-then-closed, so \"done\" lives on the kanban + run archive, never as sidebar clutter.\n- **Tab label carries live counts** for at-a-glance triage: `herdr tab rename \u003Cfleet-tab>\n  \"fleet:\u003Cepic> ▶3 ⏳1 ✋1\"` on primary or `\"fleet:\u003Cepic>@\u003Cslug> ▶3 ⏳1 ✋1\"` elsewhere — refresh on\n  each wake.\n- **The invariant the user relies on:** everything visible is working or queued; `✋`\u002F`❌` means \"needs me\"\n  (mirrored on the fleetboard attention list); everything else is fine by construction.\n- **The fleet lives in its own session, so the default sidebar shows only your orchestrator tab.** The\n  human watches the run with `herdr session attach fleet-\u003Cepic>` in a second terminal (or\n  `herdr --remote \u003Chost> --session fleet-\u003Cepic>` for another machine). The sidebar keys (`prefix+.`\n  next agent), herdr-bar and `agent list` never cross sessions - which is exactly why the human's\n  interactive session stays clean. Say so in the run map so nobody hunts for panes in the wrong session.\n- **Sweep duty (every wake):** reconcile every fleet pane's label against its true state, refresh tab\n  counts, and archive+close any pane whose job ended. Unnamed\u002Fmislabeled panes in a fleet tab: fix on sight.\n\n## Tandem orchestrator — codex co-pilot watching the fable orchestrator\nFor autonomous\u002Fovernight runs (default on; skip for short attended runs), spawn ONE codex pane at max\nreasoning alongside the orchestrator as a second pair of frontier eyes:\n`herdr pane split \u003Corchestrator-pane> --direction down --no-focus` → `herdr agent start tandem:\u003Cepic>\n--kind codex --pane \u003Cnew-pane> -- --dangerously-bypass-approvals-and-sandbox -c model_reasoning_effort=\"max\"`\n(pane label `tandem:\u003Cepic>`; brief template in REFERENCE.md).\n- **Watchdog over the orchestrator itself** (~10 min cadence): read the orchestrator pane tail + ledger +\n  `herdr agent list`; catch starvation (no wake progress), context bloat past the rotation threshold,\n  parked-draft blocking, dead waiters\u002Fmonitor. Follows the hard rules: commits-alive check before flagging\n  stuck; parked-draft submit protocol; 2 same-cause blocked cycles = incident, ring the bell.\n- **Rotation trigger-holder (skills#2):** tandem computes the rotation triggers EXTERNALLY — the\n  orchestrator's own judgment degrades exactly when its window fills, so it never self-reports. Each sweep:\n  read `herdr agent get \u003Corchestrator> | jq .result.agent.tokens.context` - the structured context-fill\n  field (see Herdr backchannel primitives; fall back to grepping the pane's bottom lines for\n  \"% ... auto-compact\" \u002F \"context left\" only if the field is empty); read the ledger's last rotation stamp\n  for the 4-6h wall-clock ceiling. On ANY trigger: send the orchestrator the ONE atomic instruction — \"ROTATE\n  NOW: write the handoff doc (REFERENCE schema), commit it, park with an empty prompt\" — and ring the bell\n  if it hasn't parked within 2 sweeps (2 same-cause blocked cycles = incident).\n- **Judgment assist:** the orchestrator sends `TANDEM-JUDGE: \u003Cquestion> + pointers (plan section, diff\n  paths, both reviews)` for gate tiebreaks, risky merges, ambiguous designs; tandem returns a terse verdict\n  + reasoning. ADVISORY ONLY — the orchestrator still owns review+gate+merge (never delegated).\n- **Boundaries:** tandem is read-only on the repo — it never edits, merges, spawns, or kills panes; its only\n  outputs are `agent prompt` to the orchestrator and the bell. It is a fleet-spawned pane: archive-then-close\n  at run end like every other.\n\n## Child→parent lifecycle events — panes PUSH on stop; the signals file is only the offline fallback\nPolling alone (waiter + monitor) babysits panes but gives a child NO way to tell the parent \"done\" or\n\"stuck\" — if the waiter dies (harness reap, orchestrator compaction\u002Frotation) the pane finishes silently\nand becomes an ORPHAN (live complaint 2026-07-16). So every pane also PUSHES a durable record the\norchestrator reads on every wake, independent of any live waiter. That record is a **lifecycle event on\nthe fleetboard event log** (append-only, machine-attributed via the machine token, survives pane AND\norchestrator death); the local `\u002Ftmp\u002Ffleet-\u003Cepic>.signals` file is kept ONLY as the offline fallback for\nwhen the board is unreachable:\n- **Lifecycle vocabulary (spec-fixed 7 stages; the board rejects anything else):**\n  `ASSIGNED → PLANNED → BUILT → IN_REVIEW → GATED → MERGED → DOGFOODED`. Emit with\n  `bun ~\u002FProjects\u002Ffleetboard\u002Ffleetctl.ts event \u003CSTAGE> --machine \u003Cslug> --chunk \u003Cchunk-id> --epic \u003Cepic>\n  --gist \"\u003Cone-line>\"` — auth is the machine token minted by `fleetctl join`; the chunk id is stored\n  BARE (`--machine` is what scopes it — never prefix the id itself, or reads and waiters filtering by the\n  bare id silently match nothing); a bad stage exits non-zero listing the valid stages.\n- **At fleet start** record the event cursor in the ledger (last `seq` from `fleetctl events --since 0`,\n  or the cursor the ledger already holds) AND still set the fallback file\n  `SIGNALS=\u002Ftmp\u002Ffleet-\u003Cepic>.signals` (one per run): one event carries both -\n  `fleet log \u003Cledger> fleet.cursor.advanced fleetboard events=\u003Cseq> signals=$SIGNALS`.\n- **Every brief ends with the SIGNAL STEP** (in the discipline block): on STOP — done, blocked, OR\n  errored — the pane pushes its lifecycle event: DONE (work committed) →\n  `fleetctl event BUILT --machine \u003Cslug> --chunk \u003Cchunk-id> --gist \"\u003Cgist>\"`; BLOCKED\u002FERROR have no\n  lifecycle stage → ring `fleetctl attn \u003Cfleet-id> \"\u003Cslug>\u002F\u003Cchunk-id> BLOCKED|ERROR: \u003Cgist>\"` PLUS the\n  in-herdr toast `herdr notification show \"\u003Cslug>\u002F\u003Cchunk-id> BLOCKED\" --sound request` (works from any\n  pane - see Herdr backchannel primitives), and put the\n  detail (what's wrong, what you need) in REPORT.md at the worktree root. FALLBACK only when the board is\n  unreachable (the fleetctl command exits non-zero): append one line\n  `date-time \u003Cmachine-slug>\u002F\u003Cchunk-id> DONE|BLOCKED|ERROR \u003Cone-line gist>` to $SIGNALS. A pane that can\n  still run a shell can always signal, even when its engine can't finish the chunk.\n- **Every orchestrator wake reads the EVENT LOG first** — `fleetctl events --since \u003Ccursor>` (filter\n  `--machine \u003Cslug>` \u002F `--chunk` as needed) — and reconciles BEFORE trusting waiters: BUILT → gate it\n  (even if the waiter never fired); a BLOCKED\u002FERROR attention item → read REPORT.md, unblock or re-spawn;\n  then advance the cursor in the ledger (`fleet.cursor.advanced`). THEN read each machine's $SIGNALS (remote via\n  `ssh \u003Chost> 'cat \u003Csignals-path>'`) as the fallback path — lines from board-unreachable panes — and\n  reconcile them the same way; any evented\u002Fsignaled pane still open after its chunk closed =\n  archive+close now.\n- **Orphan sweep (every wake):** the `live` block of `fleet state --live` does the cross-check for you\n  (`orphan pane` = live pane with no chunk event; `gone` = chunk whose pane vanished before a terminal stage) -\n  a pane whose chunk is already merged\u002Fabandoned, or that appears in the event log (or fallback $SIGNALS)\n  but has no live waiter, is an orphan: archive-then-close it and re-arm whatever should have caught it.\n- Events COMPLEMENT the two spines: waiter = fast wake on done; monitor = liveness; the **event log = the\n  durable truth** that survives both dying ($SIGNALS is only its offline shadow). A chunk may only be\n  considered lost if all of these are silent AND the worktree shows no commits.\n\n### Herdr backchannel primitives - 0.8.0 delta (probed live 2026-08-15; protocol 19)\nHerdr 0.8.0 renamed the driving surface and added real child→parent primitives. Old commands in briefs or\nwaiters FAIL as unknown subcommands - use the new forms everywhere:\n| gone (0.7) | 0.8.0 replacement |\n|---|---|\n| `agent send \u003Ct> \"\u003Ctext>\"` + `pane send-keys \u003Ct> Enter` | `agent prompt \u003Ct> \"\u003Ctext>\"` - types AND submits in one call; add `--wait [--until \u003Cstatus>] --timeout \u003Cms>` to also block until the turn settles (a non-working target must show a state change within 5s or it returns `agent_prompt_stalled`) |\n| `agent start \u003Cname> --cwd .. --workspace .. --tab ..` | create the pane first (`tab create --workspace \u003Cws> --cwd \u003Cdir>` root pane, or `pane split \u003Cpane> --cwd \u003Cdir> --no-focus`), then `agent start \u003Cname> --kind \u003Cclaude\\|codex\\|grok\\|pi\\|…> --pane \u003Cpane_id> -- \u003Cextra argv>` |\n| `herdr wait output\\|agent-status` | `pane wait-output \u003Cpane> (--match TEXT\\|--regex PAT) [--timeout MS]` and `agent wait \u003Ct> [--until \u003Cstatus> …]` |\n| `agent wait --status idle` + the never-request-`done` workaround | `agent wait \u003Ct>` with NO flag matches `idle\\|done\\|blocked` - exactly the terminal set; `--until done` is first-class. The exit-code trap is gone; the commit-gate on top stays |\n| `agent read` returns JSON (extract `.result.read.text`) | `agent read` \u002F `pane read` print TEXT directly |\nVerified capabilities to build on (each probed on a live pane):\n- **Engine integrations (install once per machine+user - Setup step 0):** `herdr integration install\n  claude codex grok pi`. Each engine's own hook (SessionStart) reports its SESSION IDENTITY to the pane's\n  server - `agent get` then shows `agent_session.source: herdr:claude` + the real session id, so\n  pane→agent binding is authoritative, not guessed. The hook no-ops outside herdr panes (guarded on\n  `HERDR_ENV=1`). `herdr integration status` shows drift after engine updates; re-install on drift.\n- **Every pane knows its own address:** `HERDR_ENV=1`, `HERDR_PANE_ID`, `HERDR_SOCKET_PATH` sit in every\n  pane's env - a child (or any script it runs) can always reach the server about ITSELF, e.g.\n  `herdr notification show \"\u003Cslug>\u002F\u003Cchunk-id> BLOCKED\" --sound request` to toast the human in herdr the\n  moment it blocks (ALONGSIDE `fleetctl attn`, never instead), and `pane report-agent \"$HERDR_PANE_ID\" …`\n  for SHELL panes (dev servers, log tails, monitors) to label themselves for `agent wait`\u002Fthe sidebar.\n- **Wake = authoritative status transition; payload = REPORT.md + fleetboard event.** The waiter spine is\n  `agent wait \u003Cname> --timeout \u003Cms>` (fires on idle|done|blocked) + the commit-gate; the pane's gist\n  travels via its SIGNAL STEP (`fleetctl event`\u002F`attn`) and REPORT.md - NEVER via screen text.\n- **Screen-scraping sentinels are DEAD for claude panes (probed):** Claude Code ≥2.1.x COLLAPSES tool\n  output - a briefed `echo FLEET-SIGNAL…` ran fine but the screen showed only \"Ran 1 shell command\", and\n  the armed `pane wait-output --regex '^FLEET-SIGNAL…'` timed out. `pane wait-output` stays useful only\n  for raw shell panes (build logs, dev servers) and engines proven to print output verbatim.\n- **`pane report-agent` cannot override a live agent pane (probed):** herdr's own detection holds pane\n  authority; a foreign `--source` report neither changes `agent_status` nor surfaces its `--message`.\n  Do not design agent-pane signals on it.\n- **Per-pane telemetry - READ it, never scrape it:** `agent get \u003Cname>` exposes `.result.agent.tokens`:\n  `context` = context fill (e.g. `⛁ 7% (74k)`), `limit` = rate-limit window (e.g. `5h 71%`). Tandem's\n  rotation trigger and the monitor's quota-dry early warning (the grok `403 out of credits` class) read\n  THIS field instead of grepping pane footers.\n\n## Run map — wayfinder-inspired: ONE issue the human reads to understand the whole run\nThe kanban shows status and the archive holds detail, but neither answers \"where is this effort and what\nhas been decided?\" at a glance. Borrow the `wayfinder` skill's map (see that skill for the full pattern):\n- **One GitHub issue per epic, labeled `fleet:map`** — an INDEX, never a store: **Destination** (1-2 lines,\n  what shipped means), **Decisions so far** (one line per merged chunk: chunk name wrapping its PR link +\n  a one-line gist; detail stays in the PR\u002Farchive — the map never restates it), **Not yet specified** (the\n  fog), **Out of scope** (ruled out + why, so it never resurfaces). Update it in the same wake that merges\n  + archives a chunk.\n- **Refer by machine-qualified NAME everywhere** (extends the pane rule to chunks\u002Fcards\u002Fissues):\n  `\u003Cmachine-slug>\u002F\u003Cchunk-id>` wraps links in the run map, cards, lifecycle entries, and human-facing\n  reports; a bare chunk name or wall of bare `#42 #43` is ambiguous and illegible.\n- **Frontier discipline:** express chunk dependencies as native GitHub blocked-by relations where available\n  (falls back to a checklist on the map) so the tracker renders ready-vs-blocked visually. The frontier =\n  open + unblocked + unclaimed chunks — the ONLY things a wave may spawn. **Claim-first:** assign the chunk\n  issue\u002Fcard to this fleet BEFORE spawning its pane (complements fleetboard claims; dedups concurrent\n  orchestrators the same way wayfinder claims tickets by assignee).\n- **Fog of war:** do NOT pre-slice unclear work into chunks at backlog time — park it in Not-yet-specified\n  and graduate it into real chunks when merges sharpen the question (test: can you state the spec precisely\n  NOW? — not \"can you answer it\"). Design\u002Fambiguous chunks stay HITL: parallel-explore produces options\n  marked AWAITING-DECISION → `✋` + bell; the fleet NEVER answers the human's side of a decision.\n\n## Setup (once)\n0. **Engine integrations installed on EVERY fleet machine+user:** `herdr integration status` - any lane\n   engine showing `not installed` or a stale version → `herdr integration install claude codex grok pi`\n   (see Herdr backchannel primitives). Without them, pane→agent binding and the token telemetry the\n   waiters\u002Fmonitor\u002Ftandem read are heuristic guesses. Remote: `ssh \u003Chost> 'herdr integration status'`.\n   ALSO ensure the **pi.orchestrator herdr plugin** is linked + enabled (`herdr plugin list`; source\n   `~\u002FProjects\u002Fherdr-pi-orchestrator`) - it is the machine-wide event queue, the BLOCKED\u002FDONE toasts,\n   AND the transient-error **auto-retry** rung (see Liveness monitor). Tune it via\n   `$(herdr plugin config-dir pi.orchestrator)\u002F.env`.\n1. A **backlog** with a wave-graph (chunks + deps + acceptance). None? build it with `superpowers:writing-plans`\n   (after `superpowers:brainstorming` if the shape is unclear). Commit to main so every worktree pane reads it.\n2. `herdr status` up. A **GitHub Project** board (`gh project create`) - see [REFERENCE.md](REFERENCE.md).\n3. Two notification spines (REFERENCE): one **idle-waiter** background task per active pane (catches *done*)\n   AND one fleet-wide **liveness monitor** loop (catches *stuck\u002Ferrored\u002Fdead*). Start the monitor when the\n   first pane spawns; keep it running the whole fleet.\n\n## Per-chunk loop\nEach transition below emits its lifecycle stage to the event log (`fleetctl event \u003CSTAGE> …` - see\nChild→parent lifecycle events): spawn=`ASSIGNED` · plan-approved=`PLANNED` · verified-remote-receipt+report=`BUILT`\n(pane-side, via its SIGNAL STEP) · cross-review-started=`IN_REVIEW` · consensus-pass=`GATED` ·\nsquash-merge=`MERGED` · tracer-report=`DOGFOODED`. **Mirror every transition to the ledger in the same\nwake** - `fleet log \u003Cledger> fleet.chunk.\u003Cstage> \u003Cslug>\u002F\u003Cchunk-id> pane=\u003Cpane_id> engine=\u003Ckind>\npr=\u003Curl> commit=\u003Csha> gist=\"\u003Cone line>\"` (stage lowercase; only the fields that changed; in epic mode with\nsafeguards every pane event also carries the `attempt_id=` minted at `building` - see Safeguards + scheduling). The board\nis the shared truth, the ledger is the offline one - `fleet state` reads the ledger, not the board.\n1. **Map FIRST.** `fleet state \u003Cledger> --live` + `git worktree list`. Never spawn into an occupied worktree or\n   duplicate work a user\u002Fagent already started. (Live lesson: this bit us.)\n1b. **Codex weekly quota gate (2026-09-06, user rule - live lesson: two Pro weekly windows burned in 31h).**\n   Before spawning ANY codex-engine pane (mechanical, mechanical-spark, mechanical-fast, tandem, gate), read\n   the Codex weekly window from telemetry, never from a footer: `herdr agent list | jq -r '.result.agents[] |\n   select(.agent==\"codex\") | .tokens.limit'` prints `7d N%` where N is percent LEFT. If no codex pane is live,\n   read the newest rollouts instead (herdr telemetry is primary; this is the fallback and may lag): `for f in $(ls -t\n   ~\u002F.codex\u002Fsessions\u002F*\u002F*\u002F*\u002Frollout-*.jsonl | head -5); do jq -r '.payload.rate_limits? \u002F\u002F empty | [.primary,.secondary] |\n   map(select(.!=null and .window_minutes==10080)) | .[0] | select(.!=null) | 100-.used_percent' \"$f\" | tail -1; done | head -1`.\n   **N at or below `FLEET_CODEX_RESERVE` (default 20) = spawn REFUSED:** route the chunk to another funded lane\n   (judgment\u002Fopus, mechanical-grok) or hold it with `BLOCKED: quota` in the ledger. The reserve is the human's\n   interactive budget; a fleet never spends it. **An account switch is NOT fresh budget:** if the active Codex\n   account changed since the run started (`codex-auth status` \u002F registry `active_account_key`), treat the run's\n   Codex lanes as `BLOCKED: quota` until the human re-authorizes - the 2026-09-05 run chained two accounts to 100%\n   through `codex-auth` auto-switch with no human in the loop. Log the gate result every wave:\n   `fleet log \u003Cledger> fleet.quota.gate engine=codex left=\u003CN>% reserve=\u003CR>% verdict=\u003Cok|refused>`.\n2. **Worktree** (`superpowers:using-git-worktrees`): `git worktree add .claude\u002Fworktrees\u002F\u003Cchunk> -b feat\u002F\u003Cchunk> origin\u002Fmain`\n   **then `bun install` (or the repo's install) in the new worktree** - fresh worktrees don't share the root\n   `node_modules`, and a pane may skip install → `Cannot find module @workbench\u002F*` gate failures that look\n   like code bugs but aren't. Do it at the orchestrator before spawning, so the pane + your gates both resolve.\n3. **Spawn, engine-routed + NAMED, into the FLEET TAB.** At placement, bind the machine slug registered by\n   `fleetctl join --name \u003Cslug>` and keep both identities: local herdr name `\u003Cchunk-id>`; external\u002Freporting\n   name `\u003Cslug>\u002F\u003Cchunk-id>`. Spawn (0.8.0 two-step - see Herdr backchannel primitives): get a pane in the\n   fleet tab cwd'd at the worktree - the fleet tab's fresh root pane for the first chunk\n   (`tab create … --cwd \u003Cworktree>` returns the pane OBJECT `result.root_pane`; its id is `.result.root_pane.pane_id`), else `herdr pane split \u003Ca-fleet-tab-pane>\n   --direction down --cwd \u003Cworktree> --no-focus` - then `herdr agent start \u003Cchunk-id> --kind \u003Ckind>\n   --pane \u003Cpane_id> -- \u003Cengine args>` (`--kind` names the engine executable: claude|codex|grok|pi|…; the\n   argv after `--` is its flags only). For a non-primary machine, execute the same commands there:\n   `ssh \u003Chost> 'herdr pane split … && herdr agent start …'`.\n   The remote agent NAME is still the bare chunk id; append `fleet.resource.minted pane:\u003Cpane_id>` (and\n   `tab:\u003Cid>` for any tab you just created) plus `fleet.chunk.spawned` in this same wake (see 'Ledger +\n   state view'); set its local pane label too\n   (`ssh \u003Chost> 'herdr pane rename \u003Cpane_id> \"▶ \u003Cchunk-id>\"'` - see Sidebar legibility). Every later\n   remote read\u002Fprompt\u002Fwait\u002Frename\u002Fclose follows the same host-explicit SSH form. Never use `herdr --remote` for\n   driving; it is UI-attach only.\n   Placement hierarchy (once per fleet run, not per chunk) - all of it inside the run's own session, so\n   every command below is `herdr --session fleet-\u003Cepic> …` (remote: `ssh \u003Chost> 'herdr --session\n   fleet-\u003Cepic> …'`): **session = the fleet run** (Setup step 7) → **workspace = `\u003Cepic>`**: a fresh\n   session has NO workspaces, so mint one (`workspace create --cwd \u003Crepo> --label \u003Cepic>`; keep its id;\n   `fleet.resource.minted workspace:\u003Cid>`) → **one fleet tab per machine**: `tab create --workspace\n   \u003Cws-id> --cwd \u003Cworktree> --label \"fleet:\u003Cepic>\" --no-focus` on primary, `\"fleet:\u003Cepic>@\u003Cslug>\"`\n   elsewhere (`fleet.resource.minted tab:\u003Cid>`). Keep its `tab_id`, and spawn EVERY chunk pane into\n   it. The human's default session is never touched - no 'tab 1' rule applies inside the fleet\n   session. `herdr tab rename` retrofits.\n   **Tab hygiene (live lesson - user caught both):** (a) run `herdr tab list --workspace \u003Cws>` on the target\n   server (through SSH when remote) BEFORE creating; reuse the expected `fleet:\u003Cepic>` or\n   `fleet:\u003Cepic>@\u003Cslug>` tab instead of minting a duplicate; (b) `tab create` ships an empty root SHELL pane\n   (`.result.root_pane.pane_id` in the create response - `root_pane` is an object, not an id; probed 2026-09-03) - in 0.8.0 that root pane is the FIRST chunk's spawn target\n   (`agent start … --pane \u003Croot_pane>`), not waste; only close it when the tab pre-exists with agents and\n   the root shell sits empty. Sweep `herdr pane list --workspace \u003Cws>` on the same target (no stray `shell`\n   panes in fleet tabs). Note a tab dies with its last pane - re-check `tab list` before reusing a stored id.\n   Engine per the **Engine routing** table above (+ any active user steering override from the ledger).\n   **ALWAYS pin `--model` explicitly** — a bare `claude` inherits the user's CURRENT default, which can change\n   mid-fleet (live lesson: user switched their default mid-run and the next pane silently ran on it; caught\n   only by reading the pane status line). **Codex panes have an extra, bounded launch gate:** after accepting\n   the trust modal, prove the unique argv-turn token appears in the **normalized** tail and substantive Codex\n   activity follows it while status is `working|idle|done`; `working` and the echoed prompt alone are only\n   boot activity, not proof that the brief ran. If the gate reaches its deadline, emit\u002Fring `BOOT_HUNG` and\n   leave the pane intact — do not arm its waiter and never auto-kill it. Run the bundled verifier in\n   REFERENCE's “Codex pane launch protocol”. Pane spawned → emit `ASSIGNED`\n   (`fleetctl event ASSIGNED --machine \u003Cslug> --chunk \u003Cchunk-id> --epic \u003Cepic> --gist \"spawned \u003Cengine>\"`).\n4. **Brief.** For Codex, the argv pointer from the bounded verifier in step 3 is the first brief — do **not**\n   re-send it; wait for `BOOT_READY` before any later steering. For other panes, deliver with\n   `herdr agent prompt \u003Cchunk-id> \"\u003Cpointer>\"` (0.8.0: types AND submits in one call - the old\n   `agent send` + `send-keys Enter` dance is gone; verify the prompt line is EMPTY first, the append trap\n   in Hard rules still applies to a parked draft). **Brief-delivery gate (EVERY engine, not just codex -\n   live incident 2026-08-15: an orchestrator died mid-send and its freshly spawned pane sat at Ctx 0,\n   never briefed):** after delivering, confirm status flips to `working` (`agent prompt --wait --until\n   working` does this in one call); a pane still idle on an empty prompt got NO brief - re-deliver\n   (bounded, 2 tries) then ring. Never assume a sent brief arrived. A brief = **CONTEXT section** (varies per chunk:\n   spec\u002Fbug\u002Frepro\u002Ffiles\u002Fconstraints — write it as richly as you like) + DISCIPLINE BLOCK\n   (fixed — copy it VERBATIM from REFERENCE.md, never freehand it)**. The block carries the whole chain:\n   PLAN first (`superpowers:writing-plans`) → BUILD via `superpowers:subagent-driven-development` (TDD) →\n   seam rule (point at `testing-anti-patterns.md`; a behavior-bearing chunk asserts the *observable effect\n   at the real seam*, e.g. the repo's `e2e-*.test.ts` \u002Frpc pattern — the goal actually appears — NOT that a\n   mocked dispatch was called) → gates (CONCRETE commands, named: `bun run typecheck` 0,\n   `verify:effect` 0, suites green - never a meta \"verify your work\" line, see Opus-5-class alignment) →\n   **`git add -A ':!BRIEF.md' ':!REPORT.md' && git commit` before STOP, then report as\n   `\u003Cslug>\u002F\u003Cchunk-id>` with the verified remote SHA, draft PR URL, and committed recovery record; leave ready status and merge to the coordinator** (uncommitted worktree = UNFINISHED to the waiter). Claude\n   panes get the skill NAMES (they\n   have the Skill tool); codex\u002Fpi panes get the non-Claude variant with the discipline spelled out as text.\n   **Live lesson (2026-07-02): a freehanded bug-fix brief had excellent context + a TDD sentence but never\n   told the pane to plan or use subagent-driven development — rich context is NOT the discipline; ANY chunk\n   shape (build, bug fix, refactor, spike) ends with the verbatim block.**\n   **Skill availability + command triggering (2026-07-16, workbox lesson): a brief NEVER loads a skill by\n   itself.** Skills resolve from the PANE's environment — `~\u002F.claude\u002Fskills` of that machine+USER plus its\n   installed plugins — not from the orchestrator's. Before any brief names a skill: (a) **probe the target\n   env once per machine+user** (`ls ~\u002F.claude\u002Fskills\u002F\u003Cname>`; for a remote pane `ssh \u003Ctarget> 'ls\n   ~\u002F.claude\u002Fskills'` — the pane user's home, not yours) and cache the result in the ledger; (b) a named\n   skill that's absent **silently degrades to prose** — the pane \"sort of follows\" the workflow with no\n   gates loaded, which reads as compliance and isn't — so on a miss either sync skills to the box first or\n   fall back to the non-Claude discipline variant (inline text works on every engine and every machine);\n   (c) to **force-trigger** a skill\u002Fcommand in a claude pane, send the slash command as its OWN message\n   (`agent prompt \u003Cchunk-id> \"\u002Fskill-name \u003Cargs>\"`), never buried mid-paragraph, then `agent read`\n   and confirm the command\u002Fskill banner appears before sending the follow-up context; plugin-namespaced\n   skills (`superpowers:*`) additionally require that plugin installed under the pane's user — file-sync\n   alone never provides them. Plan approved (the pane's written plan lands; AWAITING-DECISION design\n   chunks: when the user's decision arrives) → emit `PLANNED`.\n5. **Arm waiter + monitor.** For Codex, do this only after the bounded past-boot launch gate succeeds. Run the\n   canonical background waiter from REFERENCE: `herdr agent wait \u003Cchunk-id> --timeout \u003Cms>` (0.8.0: no\n   flag = fires on `idle|done|blocked`, the full terminal set) supplies bounded backpressure, then\n   `herdr agent get` payloads gate on `agent_status` in `idle|done` PLUS the commit-gate (a commit beyond\n   `origin\u002Fmain` or a dirty tree - status alone is never completion); `blocked` wakes route to the\n   unblock path, not the gate. AND ensure the fleet **liveness monitor** loop is\n   running (it sweeps this pane for stuck\u002Ferrored\u002Fdead).\n6. **Gate (you, fable\u002Fopus): CROSS-MODEL CONSENSUS (2026-07-10, user rule).** On idle, read the pane (its commit+report already emitted `BUILT` via the SIGNAL STEP; on READY_UNCOMMITTED you commit the pane's work and emit `BUILT` yourself), then three passes before your judgment:\n   a. **Cross-engine review** (dispatching it = emit `IN_REVIEW`)**:** the chunk's diff is reviewed by a DIFFERENT engine than built it - grok-built → `codex review`; codex-built → fable\u002Fopus adversarial review (grok is BUILD-only, it stalls on review workloads - the model-table rule, now consistent here). Reviewer instruction: report EVERY concrete finding with evidence, no severity self-filtering - the orchestrator triages. **An engine NEVER reviews its own work; a chunk NEVER self-approves.**\n   b. **Reuse\u002Fsimplicity pass** on the same diff (either engine or fable): hand-rolled code that a shared package \u002F the repo's package index already owns = must-fix; needless complexity = should-fix.\n   c. `\u002Freview-all` → **seam check** (the\n   `superpowers:requesting-code-review` task-reviewer rubric already asks *\"tests verify real behavior, not\n   mocks?\"* — enforce it; heuristic: *delete the mock — if the test still passes, it tests the mock, not the\n   code*; a behavior-bearing chunk with only mocked-dispatch tests is NOT done → send back) →\n   `superpowers:receiving-code-review` judgment → one fix subagent (`model:'sonnet'` - mechanical, findings\n   are its spec; escalate on a failed re-gate) for Critical\u002FImportant →\n   `superpowers:finishing-a-development-branch`.\n   **Merge gate = consensus:** merge only when the cross-engine reviewer has zero unresolved must-fix AND the\n   reuse pass is clean-or-fixed AND your judgment review passes. Builder-vs-reviewer disagreement → fable\u002Fopus\n   tiebreak, never a coin flip. Consensus pass → emit `GATED`. **Hold-tagged chunk: STOP here - the\n   Held-chunks flow (bell + the owner's board answer) owns the merge decision.** Untagged (the default):\n   merge **under the `main-merge` claim** - the ordered Merge-under-claim flow (claim\u002Fqueue FIFO → rebase\n   on main → LOCAL repo-root gate → squash-merge → emit `MERGED` → release); never merge outside it.\n7. **Track + housekeep + FILE FOLLOW-UPS (2026-07-10, user rule).** Move the kanban card Todo→In Progress→Done; attach the PR. Append the chunk\\u2019s decision line to the run map (see Run map). **Follow-up capture:** any concern a builder\u002Freviewer\u002Froaster raised that is NOT resolved within the chunk (fragile spot, \"fix later\", out-of-scope bug, deferred improvement) → file a repo issue labeled `follow-up` (title `[follow-up][\u003Carea>] \u003Cgist>`; body: source chunk, agent, what+why+suggested fix, severity) AT TRIAGE TIME, not batched, and link it from the card + run archive. **UAT capture (2026-07-22, user rule - repo contract in docs\u002Fplaybooks\u002Fissue-labels.md):** any merged chunk whose behavior only a human on a real device\u002FTestFlight build can confirm (widgets, Live Activities, push, entitlements, purchase flows, camera\u002Fmic, background modes, anything the dogfood pane cannot prove in sim) -> add concrete `- [ ]` verification steps + the PR link to the app's open `uat`-labeled issue, or create one (`--label uat --label device-verify`) when none is open; ONE `uat` issue per app per build window, extended not duplicated. The pre-ship human sweep is `gh issue list --label uat --state open` - a device-check ask that is not on a `uat` issue does not exist at build time. Sweeps: at every \u002Freview-all checkpoint scan recent chunk reports for un-filed concerns; before each final PR do a full-run sweep and list all follow-ups in the PR body under \"Deferred concerns\". Then **archive-then-close** the pane (see Housekeeping — NEVER close before archiving).\n8. **Dogfood (tracer-bullet).** After a runtime-affecting merge, when test panes are quiescent, spawn a\n   **sonnet-5** `dogfood` pane (drive-app-and-report is taste-floor work; opus-5 for reactor-subtle merges;\n   never fable - scoping\u002Fplanning\u002Freview only per the 2026-07-12 steer): run the app, exercise the chunk's new\n   behavior + a core smoke, report → findings become **new kanban cards** linked to the chunk. Tracer\n   report received → emit `DOGFOODED` (the chunk's final lifecycle stage).\n9. **Fan out.** Spawn the next wave's *independent* chunks in parallel; sequence shared-file\u002Freactor chunks.\n   Re-run the Codex weekly quota gate (step 1b) before EVERY wave, not once per run - the window moves while\n   panes work. A `QUOTA_HALT:` line from the monitor closes the codex lanes for the rest of the run: finish the\n   panes already working (they may still ROTATE), spawn no new codex pane, and record `BLOCKED: quota`.\n\n## Liveness monitor - the SECOND spine (waiters catch *done*; the monitor catches *stuck\u002Ferrored\u002Fdead*)\nThe idle-waiter only fires on `idle|done`. A pane that **errors** (network drop, `403 out of credits`, crash,\nconnection-refused, rate-limit, model API 5xx), **freezes** mid-`working`, or flickers to `unknown` NEVER\nreaches idle → its waiter blocks to a **silent ~30-40 min TIMEOUT** and the chunk stalls invisibly while you\nthink it's building. Waiters alone are blind to this - so run ONE wall-clock monitor loop for the WHOLE fleet,\nin parallel with the per-pane waiters. It RINGS; it does not auto-kill (classify via tail first - never kill a\ngenuinely-`working` pane).\n1. **Sweep every ~2 min** (`run_in_background`, re-arming): `herdr agent list` → for each active fleet pane\n   snapshot `{status, normalized-tail fingerprint, commits-beyond-main, dirty, tokens}` (`tokens` from\n   `agent get` - `.limit` at or below `QUOTA_MIN` (default 10% left) = **QUOTA_LOW**: the monitor emits it\n   once and sends the pane `ROTATE NOW` while it can still write, so a handoff exists BEFORE the\n   `usage limit` error kills it; see Herdr backchannel primitives). The Codex WEEKLY window (`7d N%`) at or\n   below `FLEET_CODEX_RESERVE` (default 20% left) = **QUOTA_HALT**, emitted once per fleet: the orchestrator\n   spawns no further codex pane for the run (step 1b\u002F9) - the reserve is the human's interactive budget.\n   Rotation keeps a pane alive; it never buys the fleet more budget) and diff vs the last snapshot in a state\n   file (survives orchestrator compaction - the monitor is stateless per wake, like the waiters).\n2. **ERRORED** - tail matches an error signature (list in REFERENCE monitor script). **Rung 0 is\n   AUTOMATED and already ran before you see it:** the pi.orchestrator plugin auto-retries transient\n   errors (API stall\u002Fmid-stream drop\u002F429\u002F5xx\u002Foverloaded) up to PI_ORCH_RETRY_MAX times per pane -\n   check its `state\u002Fevents.jsonl` for `auto_retry`\u002F`retry_exhausted`\u002F`retry_fatal` records (2026-08-15,\n   built from the live 2h Opus stall + never-briefed child incident). Ring immediately ONLY for:\n   `retry_fatal` (quota\u002Fauth - needs respawn on a funded lane), `retry_exhausted`, or a signature the\n   plugin missed (`fleetctl attn \u003Cfleet-id> \"\u003Cmachine-slug>\u002F\u003Cchunk-id> errored: \u003Cline>\"` +\n   PushNotification on the user's Mac); don't wait out K sweeps.\n3. **STUCK** - status + normalized-tail fingerprint + commit-count ALL unchanged for K sweeps (~6-10 min)\n   while status ∉ `{idle,done}` → ring. The normalizer ignores only volatile terminal chrome (spinner elapsed\n   time, `esc to interrupt`, context-% footer), so a boot spinner now goes stale while real commands, logs,\n   model output, and errors still count as progress. Read the tail to classify: real long compile\u002Fsuite\n   (re-arm, leave it) vs frozen (recover). A pane legitimately on a background shell shows *changing*\n   output\u002Flogs - a frozen one is inert.\n4. **DEAD\u002Fgone** - pane vanished from `agent list` (crashed \u002F user closed) but its chunk isn't merged → ring +\n   re-spawn on the fallback engine in the SAME already-installed worktree.\n5. **Recover a caught pane** via the Hard-rules credits\u002Ffrozen path: close the dead pane → re-spawn\n   grok→codex→fable\u002Fopus (ascending intelligence) in the same worktree → re-arm BOTH its waiter and the monitor.\n   A pane that died on a usage limit WITHOUT a handoff is rebuilt from its transcript on disk - follow\n   REFERENCE 'Dead-pane rescue' (`bun scripts\u002Fsession-handoff.ts \u003Cpane>` renders the brief from the codex\n   rollout \u002F claude project jsonl; successor in the same workspace; rename the corpse's tab MOVED).\n6. **Distinct from the idle-waiter, not a replacement.** Waiter = \"did it finish?\" (git-state gate). Monitor =\n   \"is it still alive + progressing?\" (liveness gate). Both run per active pane; a chunk is advanced only by the\n   waiter's DONE\u002FREADY, rescued only by the monitor's STUCK\u002FERRORED\u002FDEAD. See REFERENCE 'Liveness monitor'.\n\n## Housekeeping — close done panes, KEEP their results (restorable)\nA pane's scrollback\u002Fresult is LOST on `herdr pane close` (herdr has no transcript export; only the *session* persists, and even that is not guaranteed re-attachable after close). So **capture before you close**, into a git-tracked run archive — the durable, restorable record of what each agent actually did.\n\nPer chunk, right after merge (step 7), BEFORE closing:\n1. **Capture the pane's final report:** `herdr agent read \u003Cname> --source recent --lines 400` → the report text (files, commit, test summary, concerns).\n2. **Append to the run archive** (git-tracked → permanent, greppable, travels with the code): `docs\u002Fsuperpowers\u002Ffleet-runs\u002F\u003Cepic>.md`, one section per chunk: `## \u003Cmachine-slug>\u002F\u003Cchunk-id>` + PR# + merge commit + gate verdict + test summary + the captured report + concerns. Commit it (part of the merge or a follow-up housekeeping commit). Link it on the kanban card.\n3. **Publish the branch** (`git push origin feat\u002F\u003Cchunk>` from the pane's worktree, log `ref=` on the `built` event) - a branch that exists on one machine only is not durable, and a pane close or host failure must never remove the only copy of gated work. Workers maintain draft PRs; the coordinator owns ready status and merge.\n4. **THEN teardown:** `herdr --session fleet-\u003Cepic> pane close \u003Cpane_id>` (resolve id from the local bare name; use SSH when remote) + `fleet log \u003Cledger> fleet.resource.closed pane:\u003Cpane_id>` → `git worktree remove` → `git branch -D` → **DerivedData sweep** (every Xcode build in a worktree mints a fresh `~\u002FLibrary\u002FDeveloper\u002FXcode\u002FDerivedData\u002F\u003CApp>-\u003Chash>` dir, 5-9GB each; 80 leaked dirs = 394GB, live lesson 2026-07-17). Match by exact `WorkspacePath` inside the removed worktree - never by app-name pattern (concurrent fleets build the same app from other worktrees). See REFERENCE 'Archive a pane result before close' for the snippet. Last chunk of the run: rename the tab `fleet:\u003Cepic> ✓done` on primary or `fleet:\u003Cepic>@\u003Cslug> ✓done` on a non-primary machine (or close it).\n5. **Restore** later: read `docs\u002Fsuperpowers\u002Ffleet-runs\u002F\u003Cepic>.md` (the authority) and render the ledger\n   (`fleet state docs\u002Fsuperpowers\u002Ffleet-runs\u002F\u003Cepic>.jsonl`); use `herdr session attach fleet-\u003Cepic>` for\n   a local live re-entry, or `herdr --remote \u003Chost> --session fleet-\u003Cepic>` for remote UI attach WHILE the\n   session still exists (teardown deletes it); never use `--remote` to drive subcommands.\n**Archive-then-close applies to ALL fleet-spawned panes: review, dogfood, fix, and supervisor panes included, not just chunk panes** (live lesson 2026-07-10: a spent cross-review pane + a gated-out chunk pane lingered unclosed; the rule read as chunk-only). A review pane's verdict goes into the run archive under the chunk it reviewed.\nDo NOT let done panes pile up (they clutter the fleet tab + hold worktrees) — but never trade the result for the cleanup.\n**Close at VERIFIED REMOTE RECEIPT+REPORT, not at merge (2026-07-13, user rule — 11 idle panes piled up waiting out a long review queue).**\nA build pane's job ends when its branch and recovery record are pushed, its draft PR is current, and its report is captured; the WORKTREE + BRANCH are the durable\nartifacts the gate\u002Fmerge needs — the pane is not. As soon as the waiter fires READY, verify the delivery receipt and archive the accepted result before closing the pane; run cross-review\u002Fgates against the worktree, and only tear down the\nworktree+branch after merge. Exception: a pane you expect to send back imminently (review already running, verdict\nminutes away) may stay for ONE gate cycle — a send-back to a closed pane costs a fresh spawn in the same worktree with\nthe findings as the brief, which is acceptable and often cleaner (fresh context) than keeping N idle panes alive.\nIdle panes with no live job are a defect: every fleet-tab pane must be `working` or awaiting an imminent send-back.\n\n### Resource ledger + deterministic teardown (2026-07-16 — structure over sweep-rules)\nEmpty tabs\u002Fpanes kept surviving runs DESPITE sweep duty + archive-then-close: those rules live in\norchestrator context and decay under compaction\u002Frotation. Cleanup is therefore LEDGER-driven, never\nmemory-driven — the same law that already governs worktrees (\"housekeep only what THIS run created,\ntracked by exact path\") extended to every herdr resource:\n- **Mint = record.** Every command that mints a herdr resource - the session, `workspace create`,\n  `tab create`, `pane split`, `agent start` - appends one event IN THE SAME wake, never batched:\n  `fleet log \u003Cledger> fleet.resource.minted \u003Csession|workspace|tab|pane|agent>:\u003Cid> label=\u003Clabel>`.\n  The empty root SHELL pane a `tab create` (and a `workspace create`) ships (`.result.root_pane.pane_id`) gets its own event until closed.\n  No minted event = not yours = you may not close it. Closing appends `fleet.resource.closed \u003Csame subject>`.\n- **Teardown reads the ledger, never the sidebar.** At run end (and before any rotation handoff):\n  `fleet teardown \u003Cledger> --epic \u003Cepic> --session fleet-\u003Cepic>` (dry-run: every open\n  resource and its action), then add `--execute`. It archives-then-closes each pane by exact id, closes\n  tabs and workspaces, verifies no recorded pane survives, THEN `session stop` + `session delete`\n  fleet-\u003Cepic> - one stop removes every remaining surface - and appends `fleet.run.teardown closed=\u003Cn>`.\n  VERIFY: `herdr session list` no longer shows `fleet-\u003Cepic>`. `fleetctl deregister` only AFTER that.\n\n### Ledger + state view (2026-09-03 - the orchestrator reads ONE view, never scans panes)\nThe ledger is `docs\u002Fsuperpowers\u002Ffleet-runs\u002F\u003Cepic>.jsonl`: JSON Lines, one **CloudEvents 1.0** record per\nline (`specversion` `id` `source` `type` `time` `subject` `data`) - `jq`, DuckDB `read_json_auto`, and ax\nall read it without a custom parser. The tooling is `scripts\u002Ffleet.ts` (Effect 4, `effect\u002Funstable\u002Fcli`);\nits `Herdr` service (`scripts\u002Fsrc\u002Fherdr\u002FHerdr.ts`) is the seam: `HerdrCli` shells out to `herdr --session …`\ntoday, a `HerdrSdk` layer over `@herdr\u002Fsdk` replaces it when the SDK ships, nothing above changes. Never hand-write a line; `fleet log \u003Cledger> \u003Ctype>\n\u003Csubject|-> [key=value …]` mints id + time (ints and true\u002Ffalse are coerced, everything else is a string).\n`source` defaults to `fleet\u002F\u003Cepic>\u002F\u003Chost>`; set `FLEET_SOURCE=fleet\u002F\u003Cepic>\u002F\u003Cslug>` once per machine.\n\n**Epic mode (2026-09-04, spec `docs\u002Fspecs\u002F2026-09-04-fleet-graph-visibility-design.md`):** every `fleet` command also accepts an\n**epic directory** `\u003CFLEET_HOME>\u002F\u003Cepic>` (default home `~\u002F.fleet\u002F\u003Crepo>`, an orphan-branch worktree created with\n`fleet init \u003Chome> \u003Cepic> --repo \u003Cowner\u002Fname> --plan \u003Cpath>`). The directory holds `graph.json` (chunks + deps +\nconflicts + lane + hold, plan-only; validate with `fleet graph check \u003Cdir>`), one `ledger.\u003Cslug>.jsonl` per machine, and\n`DECISIONS.md`. In epic mode `fleet log` REFUSES an illegal stage transition (exit 2, prints the allowed targets; `--force`\nwith `reason=` overrides and records `forced=true`), an unknown chunk id (`--adhoc` overrides), an unknown `step=` for\nthe stage (steps come from `scripts\u002Fworkflow.json`), a bad `evidence=` (`verified|reported|asserted`), and `merged` on a\nheld chunk without `hold=approved`. New views: `fleet next \u003Cdir>` (the frontier - the ONLY chunks a wave may spawn),\n`fleet status \u003Cdir> \u003Cchunk>` (put this line in every brief so the pane sees its stage, blockers, dependents, acceptance),\n`fleet stats \u003Cdir>` (dwell per lane\u002Fstage, retries, causes). `fleet state \u003Cdir>` groups chunks by depth and adds `step` and\n`blocked-by` columns. The single-file form `fleet \u003Ccmd> \u003Cledger>.jsonl` still works unchanged for runs already in flight.\n\n**Safeguards + scheduling (2026-09-05, pstack learnings - `docs\u002Fresearch\u002Fpstack-fleet-ship-learnings.md`):** `fleet init`\nwrites `\"safeguards\": true` and `\"scheduling\": {\"max_in_flight\": 4, \"max_gate_queue\": 2}` into `graph.json`; both are\nenforced by `fleet log` \u002F `fleet next`, not by prose, and `src\u002Fledger\u002Fsafety.test.ts` + `src\u002Frun\u002Fscheduling.test.ts` are the\ncrash tests. Untagged ledgers from older runs keep their old semantics.\n- **Attempt token.** `fleet log … fleet.chunk.building \u003Cslug>\u002F\u003Cchunk>` mints `attempt_id` (the orchestrator does this, then\n  puts the token in the brief). Every later pane event (`built`, `in_review`, `gated`, `merged`) MUST carry\n  `attempt_id=\u003Ctoken>`; a missing, stale, or already-ended token is rejected with exit 2 - and rejected on REPLAY too\n  (`fleet state` prints `REJECTED \u003Csubject> event \u003Cid>: \u003Creason>` in the header). A late `BUILT` from a replaced pane can no\n  longer overwrite the current attempt. A new `building` clears `hold`, `commit`, `checks`, `verdict`, `evidence`.\n- **Gate receipt bound to a commit.** `built` requires `commit=\u003Cfull 40\u002F64-hex sha>`. `gated` requires\n  `verdict=PASS evidence=verified checks=\u003Creceipt path> commit=\u003Cthe built sha>`; anything else is exit 2, `--force` cannot\n  bypass it. Any later event with a different `commit=` drops the receipt (re-review). `merged` requires\n  `input_commit=\u003Creviewed head sha>` that matches the receipt - the squash sha goes in `commit=`, the receipt attests the\n  reviewed input only. Before merging run `fleet check-gate \u003Cdir> \u003Cslug>\u002F\u003Cchunk> --worktree \u003Cwt>`: exit 0 only when the\n  worktree is clean, `HEAD` equals the receipt commit, and a held chunk carries `hold=approved`.\n- **Rolling window.** `fleet next` counts `assigned` + active chunks against `max_in_flight` and `built|in_review|gated`\n  against `max_gate_queue`; over either limit the frontier is empty and the chunk row says why (`capacity`, `gate queue`).\n  `fleet log … assigned|spawned` re-checks the same view and refuses over-capacity spawns. Refill from `fleet next` when a\n  merge frees a slot; size the window by what YOU can gate + merge per wake, not by machine slots.\n- **Pilot.** Optional `\"scheduling\": {\"pilot\": \"\u003Cchunk-id>\"}` - a dependency-free, non-question chunk. Nothing else is\n  ready until the pilot reaches `dogfooded`. Use it on every run whose brief template, verify recipe, or chunk size is new.\n- **Freeze switch.** `fleet log \u003Cdir> fleet.policy.set spawn-paused text=\"\u003Cwhy>\"` empties the frontier and blocks\n  `assigned|spawned` until `text=off`. Use it for a broken shared verifier or poisoned upstream; in-flight work finishes.\n- **Drain points.** Completion events are appended by panes and read at drain points only - after a merge, after a spawn\n  wave, after a review batch, before a human report. Never handle an arrival inline mid-merge.\n- **Publish before close.** A completed branch on one machine is not durable. Before `pane close`, push the branch\n  (`git push -u origin HEAD` from the task worktree) and log the verified remote SHA, draft PR, recovery record, and ref on the `built` event\n  (`ref=origin\u002Ffeat\u002F\u003Cchunk>`); a git bundle in shared storage is the fallback when the remote is unreachable.\n  `fleet status` shows `attempt_id`, gate commit, and checks so a pane can see what the gate will demand.\n\nType vocabulary (all `fleet.*`, the writer rejects anything else):\n| type | subject | data |\n|---|---|---|\n| `run.started` · `run.teardown` | `\u003Cepic>` | `session` `runmap` `kanban` · `closed` |\n| `policy.set` | policy name (`routing`, `steer`, `lane-file`, `spawn-paused`) | `text` (`spawn-paused`: reason, or `off`) |\n| `resource.minted` · `resource.closed` | `session:`\u002F`workspace:`\u002F`tab:`\u002F`pane:`\u002F`agent:` + id | `label` |\n| `chunk.\u003Cstage>` (assigned spawned planned building built in_review gated merged dogfooded blocked error archived closed) | `\u003Cslug>\u002F\u003Cchunk-id>` | `pane` `engine` `wt` `pr` `commit` `gist` - same keys `fleetctl event` posts; with safeguards also `attempt_id` (every pane event), `ref` (built), `verdict` `evidence` `checks` (gated), `input_commit` (merged) |\n| `attn.opened` · `attn.closed` | `\u003Cslug>\u002F\u003Cchunk-id>` | `ask` |\n| `cursor.advanced` | `fleetboard` | `events` `signals` |\n| `note` | free | `text` |\n**The view:** `fleet state \u003Cledger> --live [--session fleet-\u003Cepic>] [--tail N]`\nrenders five blocks - header (epic, session, last action, malformed count, policies, cursor) · chunks\n(stage, pane, LIVE status, engine, PR, age, gist; stage = last `chunk.*` event per subject) · checklist\n(counts per stage + a `next:` line) · open items (attn, resources still minted) · live (orphan panes,\ngone panes) · action log tail. Without `--live` it is ledger-only and works with no server up. A\nmalformed line is counted in the header and printed to stderr, never swallowed.\n**Protocol - two rules:** the FIRST command of every wake is the view with `--live`; the LAST command of\nevery wake is one `fleet log` event. Read a pane tail only for a row the view flags (`gone`, `orphan`,\n`blocked`, `error`). The rotation handoff pastes the view verbatim as its state snapshot.\n**Commit cadence:** preserve ledger checkpoints on an owned coordination branch at each completed step and before parking. Push its recovery record and update the run draft PR before rotation or a provider stop. Never wait for a merge to preserve the only run record.\n- **Run wrap-up LAST (invoke the `wrap-up` skill).** Teardown closes herdr resources and the session; wrap-up closes the\n  RUN: one `follow-up`-labeled issue per unresolved concern in the run archive's REPORT sections (linked to\n  the chunk's PR), UAT checkboxes appended to the scope's open `uat` issue (TestFlight build numbers to\n  install, shipped flows to smoke on device, regressions to confirm dead - one live UAT issue per scope),\n  then the closed\u002Ffiled\u002Fkept report into the run map's final comment. A fleet run is not done at\n  deregister - it is done when its loose ends are tickets and its human checks are queued.\n- **Exact ids only** — never pattern-match labels (`fleet:*`) to find things to close; concurrent\n  fleets share the namespace (same live lesson as the worktree cleanup regex).\n- **Rotation-safe:** the handoff doc carries the view's `open resources` block; the successor inherits the\n  teardown obligation with the resources and re-verifies them (`fleet state --live`) like every other\n  snapshot field.\n\n## Context hygiene (you, the orchestrator) - keep yourself clean + resumable\nYour state lives in the **ledger + kanban + git**, NOT your context. So you survive compaction and a fresh\norchestrator can resume from those alone.\n- **Per wake, re-derive from sources of truth** - FIRST `fleet state \u003Cledger> --live`\n  (one view: chunks, checklist, open items, orphans, action log), then `gh project item-list` and\n  `git log` only for what the view cannot answer - do NOT trust memory, and do NOT scan panes.\n- **Read pane *tails* only** (`agent read --lines 30`), never full transcripts. Never `cat` a subagent\n  `.output` transcript into context.\n- **Offload bulk to files:** diffs via `review-package`, pane reports + briefs as files, review verdicts\n  returned terse. Read the *verdict*, not the diff.\n- **Each wake is small + stateless:** render the view → gate (`\u002Freview-all`) → merge → move card → spawn\n  next → append one ledger event (`fleet log`) → done. Don't accumulate; the board + ledger are the memory.\n- **Prompt hygiene when parking (2026-07-10):** never leave unsubmitted draft text on your prompt line when\n  you yield\u002Fidle - supervisors and humans steer you through that line, and a watchdog that finds text there\n  must defer its message (live lesson: a starvation steering was correctly deferred for a full cycle because\n  the orchestrator parked with a half-typed draft). Submit or clear before yielding.\n- Spawn the *building* on panes; keep heavy reading\u002Fsearching in **subagents** (they return conclusions,\n  not file dumps), so your window holds coordination only - and those dispatches are mechanical, so they\n  carry `model:'sonnet'` (`'haiku'` for pure locate), never the inherited orchestrator model.\n\n## Orchestrator rotation — proactive, not incident-driven (2026-07-16)\nOrchestrator main-loops were ~78% of a measured 2-week fleet spend (ax cost split) — cost per wake grows\nwith window size, so cap the window by ROTATING on schedule instead of riding to auto-compact (research +\nsources: `docs\u002Fresearch\u002Forchestrator-context-reduction.md` in the apps repo).\n- **Triggers (single-condition each, never ANDed — the 954k livelock came from conjoined preconditions):**\n  (a) ~70-75% of context window (leaves room to write the handoff BEFORE auto-compact can fire mid-handoff);\n  (b) 4-6h of active wakes as a hard wall-clock ceiling; (c) any rotation-blocking cause observed 2 cycles\n  in a row = incident, rotate now; (d) user says \"rotate\" — immediate.\n- **Rotation is ONE atomic instruction:** write the handoff doc + commit + push + update the draft PR + verify the delivery receipt + park with an empty prompt — never\n  a sequence a watchdog must observe from outside.\n- **Handoff = pointers + fresh query results, never narrative summary** (schema in REFERENCE.md). The\n  successor gets the same SOURCES the predecessor had (ledger path, kanban, agent list, event-log\n  cursor + fallback signals file,\n  steering overrides), not the predecessor's interpretation; the only prose section is Known-blockers.\n- **Successor protocol:** treat every snapshot field as stale — re-run the command behind it; reconcile\n  (orphan sweep) before spawning; re-arm waiters + monitor (process-local, never inherited); register on\n  fleetboard as a new instance; only then read Known-blockers.\n- Keep the handoff REFRESHED as part of parking (existing hard rule) so an unplanned death degrades into a\n  planned rotation.\n\n## Steward mode - on-demand per-machine orchestrator (skills#30; spec #24 + #6)\nA **steward** is this skill's orchestrator run ON a non-primary machine: spawned when the Mac\norchestrator's scheduler assigns chunks to that machine (the steward is the assignment TARGET - the\nplacement interface\u002Falgorithm stays on the Mac and out of scope here), gone when its queue empties.\nIdle machines run ONLY the heartbeat daemon - no idle steward stays resident.\n- **Division of labor (spec #6, exact):** the **Mac orchestrator keeps** wave planning, chunk-to-machine\n  placement, hold tagging, kanban\u002Frun-map upkeep, dogfood triggering, and the human interface. The\n  **steward runs the FULL fleet-ship workflow locally** on its own machine: worktrees, pane spawn\u002Fbrief,\n  idle-waiters + the liveness monitor, the cross-model consensus gate (on its OWN machine, BEFORE\n  claiming), and the merge (under the `main-merge` claim like any orchestrator - the Merge-under-claim\n  flow, TTL'd + FIFO).\n- **Locality is the point:** waiters, monitor loops, and gates ALWAYS run on the steward's own machine -\n  NEVER held open over ssh (a held-open remote loop dies with the connection; that fragility is why\n  steward mode exists). ssh from the Mac stays for one-shot reads\u002Fspawns only. The monitor's \"whole\n  fleet\" scope reads per-machine in steward mode: each steward runs ONE monitor loop covering ITS panes.\n- **Events, not cards:** the steward emits the lifecycle stages it owns (`ASSIGNED → … → MERGED`, always\n  `--machine \u003Cslug>` - see Child→parent lifecycle events); `BUILT` is pane-pushed by the discipline\n  block's SIGNAL STEP, so the steward emits BUILT itself ONLY on `READY_UNCOMMITTED` (never a duplicate);\n  `DOGFOODED` stays Mac-emitted (dogfood triggering is a kept duty). The steward DOES file `follow-up`\n  issues at its own gate triage (its gate, its findings); but the Mac reconciles kanban cards + run map\n  from the event log on its wakes - a steward never edits cards or the map.\n- **Hold tags honored (skills#33):** the hold tag arrives in the chunk's queue entry at assignment. The\n  steward runs the held chunk's FULL workflow but follows Held chunks above: stop at `GATED`, bell with\n  `\u003Cslug>\u002F\u003Cchunk-id>` + verdict + link, `✋` pending the owner's answer; merge (under claim) only on\n  approve, send back on reject. A chunk still awaiting its answer at rotation\u002Fexit is listed in the handoff.\n- **Rotation - same policy, VERBATIM:** the Orchestrator-rotation triggers above apply to stewards\n  unchanged (~70-75% context, 4-6h wall clock, 2 same-cause blocked cycles, user says rotate), and the\n  same successor protocol holds - the successor steward re-derives from the board + local herdr state.\n  ONE rotation policy; steward mode does not fork a second one.\n- **Exit-on-empty:** queue empty → ledger-driven teardown-verify (Resource ledger rules) → write the\n  rotation handoff (the REFERENCE schema, extended with machine slug + held-claim state) → confirm the\n  last chunk's terminal lifecycle event is on the board → `fleetctl deregister` → park\u002Fexit.\n- **Naming (#26 rules, unchanged):** local herdr names stay bare (`\u003Cchunk-id>`; the steward's own pane is\n  `steward:\u003Cepic>`), tab `fleet:\u003Cepic>@\u003Cslug>`, and EVERY off-machine surface - events, ledgers, reports,\n  attention\u002Fbell lines, archives, handoffs - says `\u003Cslug>\u002F\u003Cchunk-id>`.\nSpawn-on-assign contract + brief template: REFERENCE.md 'Steward brief'.\n\n## Hard rules (live-dogfood lessons)\n- **One agent per worktree.** Map before spawning. **Never interrupt a `working` pane;** confirm an empty\n  prompt line before any `agent prompt`.\n- **Typed text APPENDS to whatever is on the prompt line (verified live 2026-07-17); NEVER prompt onto a\n  non-empty line.** The 2026-07-10 \"replaces\" reading was wrong: under append, steering a pane that holds\n  a parked draft CORRUPTS it by concatenation, which is what that incident actually showed. A bare\n  `send-keys Enter` on a human-typed parked draft still cannot be trusted to submit it; verify status flips\n  to `working` after EVERY submit, never assume. Correct parked-draft submit protocol (0.8.0 commands):\n  (1) `agent read` to capture + log the draft, (2) `agent send-keys \u003Ct> Ctrl+U`, then fresh-read to confirm\n  an empty prompt, (3) `agent prompt \u003Ct> \"\u003Cfull intended text>\" --wait` and (4) confirm status flipped to\n  `working`. Only then send your own steering as the next message.\n- **The fleet never spends the Codex weekly reserve (2026-09-06, user rule).** Gate every codex spawn on the\n  weekly window (`7d N%` LEFT via `herdr agent get … .tokens.limit`, or the newest rollout's `rate_limits`);\n  N at or below `FLEET_CODEX_RESERVE` (default 20) refuses the spawn and the monitor's `QUOTA_HALT` closes the\n  codex lanes for the run. Rotation and account switching (`codex-auth` auto-switch) are NOT budget: on\n  2026-09-04\u002F05 ~20 parallel codex panes plus max-effort tandem\u002Fchunk panes drained one Pro account, auto-switch\n  chained a second, and both hit 100% in 31h with no human decision. Never pin `max` effort on a fleet lane.\n- **Name everything locally; qualify everything externally.** `agent start \u003Cchunk-id>` — the herdr NAME is\n  the bare chunk id, unique only inside that server's own agent table (never generic like `codex`: detected\n  labels are also targets → ambiguous locally). ALL `herdr agent *` commands (get\u002Fread\u002Fprompt\u002Fwait\u002Frename\u002F\n  focus\u002Fattach) accept that bare local NAME. Pane id is required ONLY for `herdr pane *`\n  (send-text\u002Fsend-keys\u002Frun\u002Fclose\u002Fwait-output) — resolve on that server:\n  `herdr agent get \u003Cchunk-id> | jq -r .result.agent.pane_id`. Every reference that leaves the machine —\n  ledger, kanban card, run map, lifecycle\u002Fsignal\u002Fmonitor event, `fleetctl attn` line, run archive, rotation\n  handoff, and report to the human — MUST use `\u003Cmachine-slug>\u002F\u003Cchunk-id>`. Human reports say\n  `\u003Cmachine-slug>\u002F\u003Cchunk-id> (\u003Cpane_id>)`, never a bare name or pane id.\n- **There is no cross-host herdr namespace.** Two servers may both have a bare agent named `sdk-migrate`;\n  herdr detects no collision, so recording or driving bare `sdk-migrate` across machines can silently\n  attribute work to the wrong pane. Prevention is the pair above: qualify every off-machine reference, and\n  drive another server only as `ssh \u003Chost> 'herdr \u003Csubcommand> ...'`, with the host explicit at each call\n  site. Never point a local client at a remote socket or write `herdr --remote \u003Chost> agent ...`;\n  `--remote` only opens the interactive UI attach and is not composable with driving subcommands.\n- **Four-level placement: session=fleet run · workspace=`\u003Cepic>` · tab=machine · pane=chunk.** Every\n  fleet resource lives in the run's own herdr session `fleet-\u003Cepic>` (Setup step 7), never in the human's\n  default session - so no fleet pane can land in an interactive tab, and one `session stop` ends the run.\n  Inside it: one `\u003Cepic>` workspace, one `fleet:\u003Cepic>` tab on primary \u002F `fleet:\u003Cepic>@\u003Cslug>` per\n  non-primary machine, bare-named chunk panes in that tab. Prefix EVERY driving command with\n  `--session fleet-\u003Cepic>`; the orchestrator's own pane is the only bare `herdr` target.\n  **Retrofit\u002Fmoves (dogfooded on a LIVE working codex pane — survives untouched):** `herdr pane move \u003Cpane_id>\n  --tab \u003Ctab_id>` (existing tab) \u002F `--new-tab --workspace \u003Cws> --label TEXT` \u002F `--new-workspace --label TEXT\n  --tab-label TEXT` (creates workspace+tab+moves in one command; use `--no-focus`). CRITICAL: the pane_id\n  CHANGES on move (wV:pC → w0:p1) but the agent NAME resolves seamlessly across it — one more reason waiters\n  and every reference must target the NAME; any pane-id-addressed waiter dies silently on a move (re-arm by\n  name).\n- **Idle != done — and `done`, not `idle`, is how panes often END.** Codex chunks finish in status `done` (terminal); gate on polled `agent get` payloads in `idle|done`, never `= idle` alone (else the waiter loops past a finished pane to TIMEOUT). 0.8.0 retired the old workaround: `agent wait \u003Ct>` with no flag matches `idle|done|blocked`, and `--until done` is a first-class target - but the STATUS is still only the wake, never the gate. A pane can finish **gated-green but uncommitted** → gate on stable-idle AND (commit OR dirty tree); on idle+dirty the orchestrator commits the pane's work itself (`READY_UNCOMMITTED`). See REFERENCE 'Refinement 2'.\n- **Idle != done (background-shell flap).** A pane reports idle\u002F`done` while merely *holding on a background shell* (a test suite,\n  a forked review). Gate on a REAL signal: a **commit beyond `origin\u002Fmain`** + a final report\u002FSTOP - not bare\n  idle. Make the waiter **commit-gated** (re-arm until a commit appears). Live lesson: a pane mid `+2292\u002F-11510`\n  with the suite running flapped `idle`→`working`, storming the naive idle-waiter.\n- **Non-Claude panes miss repo conventions Claude Code auto-absorbs — point them at CLAUDE.md; the gate catches the rest.** Grok wrote\n  `import from \"bun:test\"` + `toStartWith` in a vitest repo: **typecheck + verify:effect PASSED**, but the\n  test file failed to load → 0 tests ran. So (a) name the repo's test framework + matcher set in the brief\n  (e.g. \"vitest, import from 'vitest', no bun:test\u002FtoStartWith\"); (b) the orchestrator's gate must\n  **actually run the new tests** - typecheck\u002Fverify alone pass over a non-loading or wrong-matcher test.\n- **Gate completeness: enumerate the FULL verification matrix, per chunk, from the plan (2026-07-10).** A gate\n  once ran only a boot test on a multi-scheme app and passed a chunk the plan gated on 4 schemes. The gate\n  step must LIST what the plan's phase names (every scheme, every suite, sim build, screenshots) and check\n  each off - \"some test ran green\" is not a gate.\n- **Liveness = branch commits, not board deltas (2026-07-10).** Any monitor\u002Fwaiter\u002Fwatchdog deciding\n  starved\u002Fstuck\u002Funresponsive must check recent COMMITS on the fleet's branches before flagging - gh-closed\n  deltas batch behind gate queues (a watchdog false-alarmed 6x in one night on that signal alone; adding a\n  commits-alive check eliminated them).\n- **A safety protocol must have AUTHORITY to cause its own preconditions (2026-07-10 rotation livelock).**\n  The orchestrator context-rotation protocol required (fresh handoff) AND (idle + empty prompt) - the\n  watchdog could only wait for both, they never aligned, and a human had to rotate manually at 954k ctx.\n  When designing any monitor-triggered maneuver: every precondition needs either an action that CAUSES it\n  (submit the blocking draft after logging it; order \"checkpoint + park empty\" as ONE atomic instruction)\n  or a hard-ceiling override; freshness checks compare against content (newer than last state commit),\n  never wall-clock windows; and 2 consecutive same-cause blocked cycles = an incident, not patience.\n  Orchestrators: keep the handoff refreshed as part of PARKING, not as a favor when asked.\n- **Green != correct — enforce SEAM discipline (define_view dogfood lesson).** A chunk shipped 31 green unit\n  tests yet the feature hung in prod because they **mocked the dispatch (`CreateGoal`) — the behavior under\n  test**; \"green\" meant \"called the mock.\" The rules already existed (`testing-anti-patterns.md` + both review\n  rubrics ask *\"tests verify real behavior, not mocks?\"*) — the miss was not wiring them into the fleet. So:\n  (a) every brief names the seam rule + points at `testing-anti-patterns.md`; (b) the gate runs the seam check\n  (delete-the-mock heuristic + task-reviewer rubric) and REJECTS behavior-bearing chunks whose tests mock their\n  own dispatch; (c) such chunks carry a real-seam acceptance assertion (mock only non-deterministic leaves).\n  UAT\u002Fdogfood is the backstop, not the primary catch.\n- **Never close a pane before archiving its result.** `close` is where the transcript dies (no herdr export; session-attach not guaranteed post-close). Capture `agent read --source recent` → the git-tracked run archive (`docs\u002Fsuperpowers\u002Ffleet-runs\u002F\u003Cepic>.md`) FIRST, then close. The archive — not the live pane — is the restorable record.\n- **Housekeep ONLY worktrees THIS run created — never pattern-match names.** Same law for herdr panes\u002Ftabs - close from the ledger's `fleet.resource.minted` events (see Housekeeping: Resource ledger), never by label pattern. Track each worktree you `git worktree add` (by exact path) and remove only those. A broad `grep`\u002Fregex over `git worktree list` WILL catch other sessions' parked branches (live lesson: a cleanup regex removed byo-cloudflare\u002Fchannels\u002Ffix-* worktrees from prior streams). Committed work survives on the branch (recreate with `git worktree add \u003Cpath> \u003Cbranch>`), but **uncommitted edits in someone's idle worktree are lost**. Before removing ANY worktree you didn't just create: confirm no live agent is cwd'd there AND it has no uncommitted changes (`git -C \u003Cwt> status --porcelain`).\n- **Orchestrator gates the merge** - panes never auto-merge to main (checkpoint + avoid collisions).\n- **Never brief `git add -A` while worktree-root scratch exists (live lesson - BRIEF.md\u002FREPORT.md shipped to main twice).** Pane briefs and reports live at the worktree root; `add -A` commits them, the squash-merge lands them on main, and every later worktree \"inherits\" a stale brief. Fix: gitignore the scratch names (`\u002FBRIEF.md`, `\u002FREPORT.md`) in the repo once, AND write briefs with explicit `git add \u003Cpaths>` or `git add -A ':!BRIEF.md' ':!REPORT.md'`. Gate check: the review diff must not contain the brief\u002Freport files.\n- **Long briefs travel as files, not keystrokes (2026-07-10 API-drop lessons).** Spawning\u002Fbriefing with a\n  large prompt over `agent prompt` during API instability drops mid-stream and leaves half-briefed panes +\n  stale drafts. Write the brief to the worktree as BRIEF.md and SEND A SHORT POINTER (\"read BRIEF.md and\n  execute\"); same for any steering over ~10 lines.\n- **Waiter timeout != stuck: verify liveness before acting (2026-07-10).** Commit-gated waiters time out\n  under legitimately long chunks (a pane on task 8 with 8 commits got flagged twice). On waiter exit:\n  check pane status + recent commits FIRST; alive -> re-arm with a longer timeout (or require heartbeat\n  commits in the brief); only dead\u002Fcommit-silent panes get the stuck treatment. An \"API Error: Connection\n  closed mid-response\" tail + clean worktree = RECOVERABLE mid-turn drop: nudge the same pane, don't respawn.\n- **A wrapper agent completing is NOT a review verdict (2026-07-10).** Review-wrapper subagents drop under\n  API instability and can return without a verdict; the gate must check a verdict EXISTS, and on wrapper\n  failure fall back to direct CLI (`codex review` \u002F `grok` via Bash), logging the wrapper failure. Never\n  count a wrapper's clean exit as a PASS.\n- **Event-driven, not timed.** Canonical background waiters use `herdr agent wait` only for bounded\n  backpressure; polled `agent get` status plus git state is the completion gate. `send_later`\u002F\n  `ScheduleWakeup` may be unavailable (no CCR session). If herdr can't track an engine's status, fall that\n  chunk back to one it can (codex\u002Fclaude). **Engines run out of credits\u002Fquota mid-run** (grok hit a\n  `403: run out of credits`, pane frozen) - detect via a pane read, close the dead pane, and re-spawn the\n  chunk on a fallback engine (grok→codex→fable\u002Fopus, ascending intelligence) in the SAME already-installed worktree. Keep >1 lane funded.\n  **The idle-waiter will NOT catch a frozen\u002Ferrored pane** (it never goes idle) - the **liveness monitor** (above) is the\n  proactive spine that catches it. Always run BOTH per active pane: the git-state waiter for *done*, the monitor for *stuck\u002Ferrored\u002Fdead*.\n- **Parallelize only within a wave where chunks don't share files.** **Verify \"already done\" claims**\n  against current code before building (recent merges shift things).\n\nSee [REFERENCE.md](REFERENCE.md) for brief templates, kanban `gh` commands, the waiter script, engine flags.\n",{"name":5,"description":7},"main","b321807e50f72ccb0df5da9aaeba42088271907e","skills\u002Fengineering\u002Ffleet-ship","https:\u002F\u002Fgithub.com\u002FNecmttn\u002Fskills","https:\u002F\u002Fgithub.com\u002FNecmttn","https:\u002F\u002Fnecmttn.com","Fractional CTO - \r\nAI Solution Architect","2026-11-07 08:05:35",{"source":8,"skillName":5,"commands":33,"prompt":43,"zipAvailable":44},[34,37,40],{"tool":35,"command":36},"npx","npx skills add Necmttn\u002Fskills --skill fleet-ship",{"tool":38,"command":39},"bunx","bunx skills add Necmttn\u002Fskills --skill fleet-ship",{"tool":41,"command":42},"pnpm","pnpm dlx skills add Necmttn\u002Fskills --skill fleet-ship","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FNecmttn\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fengineering\u002Ffleet-ship\u002FSKILL.md",true,[46,52,56,62,66,70,74,78,82,86,90,94,98,102,106,110,114,118,122,126,130,134,138,142,146,150,154,158,162,166,170,174,178,182,186,190,194,198,202,206,210,214,218,222,226,230,234,238,242,246,250,254],{"path":47,"resourceType":48,"resourceTypeDesc":49,"sizeBytes":50,"sourceHtmlUrl":51},"fleet-routing.json","REFERENCE","参考文档",6424,"https:\u002F\u002Fgithub.com\u002FNecmttn\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fengineering\u002Ffleet-ship\u002Ffleet-routing.json",{"path":53,"resourceType":48,"resourceTypeDesc":49,"sizeBytes":54,"sourceHtmlUrl":55},"REFERENCE.md",49831,"https:\u002F\u002Fgithub.com\u002FNecmttn\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fengineering\u002Ffleet-ship\u002FREFERENCE.md",{"path":57,"resourceType":58,"resourceTypeDesc":59,"sizeBytes":60,"sourceHtmlUrl":61},"scripts\u002F.gitignore","SCRIPT","脚本",14,"https:\u002F\u002Fgithub.com\u002FNecmttn\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fengineering\u002Ffleet-ship\u002Fscripts\u002F.gitignore",{"path":63,"resourceType":58,"resourceTypeDesc":59,"sizeBytes":64,"sourceHtmlUrl":65},"scripts\u002Fbun.lock",5810,"https:\u002F\u002Fgithub.com\u002FNecmttn\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fengineering\u002Ffleet-ship\u002Fscripts\u002Fbun.lock",{"path":67,"resourceType":58,"resourceTypeDesc":59,"sizeBytes":68,"sourceHtmlUrl":69},"scripts\u002Ffleet.test.ts",15129,"https:\u002F\u002Fgithub.com\u002FNecmttn\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fengineering\u002Ffleet-ship\u002Fscripts\u002Ffleet.test.ts",{"path":71,"resourceType":58,"resourceTypeDesc":59,"sizeBytes":72,"sourceHtmlUrl":73},"scripts\u002Ffleet.ts",21242,"https:\u002F\u002Fgithub.com\u002FNecmttn\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fengineering\u002Ffleet-ship\u002Fscripts\u002Ffleet.ts",{"path":75,"resourceType":58,"resourceTypeDesc":59,"sizeBytes":76,"sourceHtmlUrl":77},"scripts\u002Fmonitor-tail.py",3650,"https:\u002F\u002Fgithub.com\u002FNecmttn\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fengineering\u002Ffleet-ship\u002Fscripts\u002Fmonitor-tail.py",{"path":79,"resourceType":58,"resourceTypeDesc":59,"sizeBytes":80,"sourceHtmlUrl":81},"scripts\u002Fpackage.json",331,"https:\u002F\u002Fgithub.com\u002FNecmttn\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fengineering\u002Ffleet-ship\u002Fscripts\u002Fpackage.json",{"path":83,"resourceType":58,"resourceTypeDesc":59,"sizeBytes":84,"sourceHtmlUrl":85},"scripts\u002Fsession-handoff.ts",10887,"https:\u002F\u002Fgithub.com\u002FNecmttn\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fengineering\u002Ffleet-ship\u002Fscripts\u002Fsession-handoff.ts",{"path":87,"resourceType":58,"resourceTypeDesc":59,"sizeBytes":88,"sourceHtmlUrl":89},"scripts\u002Fsrc\u002Fcli\u002Fdata.test.ts",1164,"https:\u002F\u002Fgithub.com\u002FNecmttn\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fengineering\u002Ffleet-ship\u002Fscripts\u002Fsrc\u002Fcli\u002Fdata.test.ts",{"path":91,"resourceType":58,"resourceTypeDesc":59,"sizeBytes":92,"sourceHtmlUrl":93},"scripts\u002Fsrc\u002Fcli\u002Fdata.ts",759,"https:\u002F\u002Fgithub.com\u002FNecmttn\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fengineering\u002Ffleet-ship\u002Fscripts\u002Fsrc\u002Fcli\u002Fdata.ts",{"path":95,"resourceType":58,"resourceTypeDesc":59,"sizeBytes":96,"sourceHtmlUrl":97},"scripts\u002Fsrc\u002Fcli\u002Fepic.ts",1207,"https:\u002F\u002Fgithub.com\u002FNecmttn\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fengineering\u002Ffleet-ship\u002Fscripts\u002Fsrc\u002Fcli\u002Fepic.ts",{"path":99,"resourceType":58,"resourceTypeDesc":59,"sizeBytes":100,"sourceHtmlUrl":101},"scripts\u002Fsrc\u002Fgraph\u002Fcheck.test.ts",2122,"https:\u002F\u002Fgithub.com\u002FNecmttn\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fengineering\u002Ffleet-ship\u002Fscripts\u002Fsrc\u002Fgraph\u002Fcheck.test.ts",{"path":103,"resourceType":58,"resourceTypeDesc":59,"sizeBytes":104,"sourceHtmlUrl":105},"scripts\u002Fsrc\u002Fgraph\u002Fcheck.ts",3947,"https:\u002F\u002Fgithub.com\u002FNecmttn\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fengineering\u002Ffleet-ship\u002Fscripts\u002Fsrc\u002Fgraph\u002Fcheck.ts",{"path":107,"resourceType":58,"resourceTypeDesc":59,"sizeBytes":108,"sourceHtmlUrl":109},"scripts\u002Fsrc\u002Fgraph\u002FGraph.test.ts",1628,"https:\u002F\u002Fgithub.com\u002FNecmttn\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fengineering\u002Ffleet-ship\u002Fscripts\u002Fsrc\u002Fgraph\u002FGraph.test.ts",{"path":111,"resourceType":58,"resourceTypeDesc":59,"sizeBytes":112,"sourceHtmlUrl":113},"scripts\u002Fsrc\u002Fgraph\u002FGraph.ts",2854,"https:\u002F\u002Fgithub.com\u002FNecmttn\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fengineering\u002Ffleet-ship\u002Fscripts\u002Fsrc\u002Fgraph\u002FGraph.ts",{"path":115,"resourceType":58,"resourceTypeDesc":59,"sizeBytes":116,"sourceHtmlUrl":117},"scripts\u002Fsrc\u002Fherdr\u002FHerdr.ts",1963,"https:\u002F\u002Fgithub.com\u002FNecmttn\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fengineering\u002Ffleet-ship\u002Fscripts\u002Fsrc\u002Fherdr\u002FHerdr.ts",{"path":119,"resourceType":58,"resourceTypeDesc":59,"sizeBytes":120,"sourceHtmlUrl":121},"scripts\u002Fsrc\u002Fherdr\u002FHerdrCli.test.ts",3963,"https:\u002F\u002Fgithub.com\u002FNecmttn\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fengineering\u002Ffleet-ship\u002Fscripts\u002Fsrc\u002Fherdr\u002FHerdrCli.test.ts",{"path":123,"resourceType":58,"resourceTypeDesc":59,"sizeBytes":124,"sourceHtmlUrl":125},"scripts\u002Fsrc\u002Fherdr\u002FHerdrCli.ts",3631,"https:\u002F\u002Fgithub.com\u002FNecmttn\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fengineering\u002Ffleet-ship\u002Fscripts\u002Fsrc\u002Fherdr\u002FHerdrCli.ts",{"path":127,"resourceType":58,"resourceTypeDesc":59,"sizeBytes":128,"sourceHtmlUrl":129},"scripts\u002Fsrc\u002Fherdr\u002FHerdrTest.ts",2978,"https:\u002F\u002Fgithub.com\u002FNecmttn\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fengineering\u002Ffleet-ship\u002Fscripts\u002Fsrc\u002Fherdr\u002FHerdrTest.ts",{"path":131,"resourceType":58,"resourceTypeDesc":59,"sizeBytes":132,"sourceHtmlUrl":133},"scripts\u002Fsrc\u002Fledger\u002FEvent.test.ts",1954,"https:\u002F\u002Fgithub.com\u002FNecmttn\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fengineering\u002Ffleet-ship\u002Fscripts\u002Fsrc\u002Fledger\u002FEvent.test.ts",{"path":135,"resourceType":58,"resourceTypeDesc":59,"sizeBytes":136,"sourceHtmlUrl":137},"scripts\u002Fsrc\u002Fledger\u002FEvent.ts",2270,"https:\u002F\u002Fgithub.com\u002FNecmttn\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fengineering\u002Ffleet-ship\u002Fscripts\u002Fsrc\u002Fledger\u002FEvent.ts",{"path":139,"resourceType":58,"resourceTypeDesc":59,"sizeBytes":140,"sourceHtmlUrl":141},"scripts\u002Fsrc\u002Fledger\u002Ffold.test.ts",2686,"https:\u002F\u002Fgithub.com\u002FNecmttn\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fengineering\u002Ffleet-ship\u002Fscripts\u002Fsrc\u002Fledger\u002Ffold.test.ts",{"path":143,"resourceType":58,"resourceTypeDesc":59,"sizeBytes":144,"sourceHtmlUrl":145},"scripts\u002Fsrc\u002Fledger\u002Ffold.ts",6593,"https:\u002F\u002Fgithub.com\u002FNecmttn\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fengineering\u002Ffleet-ship\u002Fscripts\u002Fsrc\u002Fledger\u002Ffold.ts",{"path":147,"resourceType":58,"resourceTypeDesc":59,"sizeBytes":148,"sourceHtmlUrl":149},"scripts\u002Fsrc\u002Fledger\u002FLedger.test.ts",4221,"https:\u002F\u002Fgithub.com\u002FNecmttn\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fengineering\u002Ffleet-ship\u002Fscripts\u002Fsrc\u002Fledger\u002FLedger.test.ts",{"path":151,"resourceType":58,"resourceTypeDesc":59,"sizeBytes":152,"sourceHtmlUrl":153},"scripts\u002Fsrc\u002Fledger\u002FLedger.ts",3594,"https:\u002F\u002Fgithub.com\u002FNecmttn\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fengineering\u002Ffleet-ship\u002Fscripts\u002Fsrc\u002Fledger\u002FLedger.ts",{"path":155,"resourceType":58,"resourceTypeDesc":59,"sizeBytes":156,"sourceHtmlUrl":157},"scripts\u002Fsrc\u002Fledger\u002Fsafety.test.ts",3374,"https:\u002F\u002Fgithub.com\u002FNecmttn\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fengineering\u002Ffleet-ship\u002Fscripts\u002Fsrc\u002Fledger\u002Fsafety.test.ts",{"path":159,"resourceType":58,"resourceTypeDesc":59,"sizeBytes":160,"sourceHtmlUrl":161},"scripts\u002Fsrc\u002Fledger\u002Fsafety.ts",2710,"https:\u002F\u002Fgithub.com\u002FNecmttn\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fengineering\u002Ffleet-ship\u002Fscripts\u002Fsrc\u002Fledger\u002Fsafety.ts",{"path":163,"resourceType":58,"resourceTypeDesc":59,"sizeBytes":164,"sourceHtmlUrl":165},"scripts\u002Fsrc\u002Fledger\u002Ftransitions.test.ts",3310,"https:\u002F\u002Fgithub.com\u002FNecmttn\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fengineering\u002Ffleet-ship\u002Fscripts\u002Fsrc\u002Fledger\u002Ftransitions.test.ts",{"path":167,"resourceType":58,"resourceTypeDesc":59,"sizeBytes":168,"sourceHtmlUrl":169},"scripts\u002Fsrc\u002Fledger\u002Ftransitions.ts",3144,"https:\u002F\u002Fgithub.com\u002FNecmttn\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fengineering\u002Ffleet-ship\u002Fscripts\u002Fsrc\u002Fledger\u002Ftransitions.ts",{"path":171,"resourceType":58,"resourceTypeDesc":59,"sizeBytes":172,"sourceHtmlUrl":173},"scripts\u002Fsrc\u002Frender\u002Fnext.test.ts",1112,"https:\u002F\u002Fgithub.com\u002FNecmttn\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fengineering\u002Ffleet-ship\u002Fscripts\u002Fsrc\u002Frender\u002Fnext.test.ts",{"path":175,"resourceType":58,"resourceTypeDesc":59,"sizeBytes":176,"sourceHtmlUrl":177},"scripts\u002Fsrc\u002Frender\u002Fnext.ts",1417,"https:\u002F\u002Fgithub.com\u002FNecmttn\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fengineering\u002Ffleet-ship\u002Fscripts\u002Fsrc\u002Frender\u002Fnext.ts",{"path":179,"resourceType":58,"resourceTypeDesc":59,"sizeBytes":180,"sourceHtmlUrl":181},"scripts\u002Fsrc\u002Frender\u002Fstate.test.ts",4313,"https:\u002F\u002Fgithub.com\u002FNecmttn\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fengineering\u002Ffleet-ship\u002Fscripts\u002Fsrc\u002Frender\u002Fstate.test.ts",{"path":183,"resourceType":58,"resourceTypeDesc":59,"sizeBytes":184,"sourceHtmlUrl":185},"scripts\u002Fsrc\u002Frender\u002Fstate.ts",7055,"https:\u002F\u002Fgithub.com\u002FNecmttn\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fengineering\u002Ffleet-ship\u002Fscripts\u002Fsrc\u002Frender\u002Fstate.ts",{"path":187,"resourceType":58,"resourceTypeDesc":59,"sizeBytes":188,"sourceHtmlUrl":189},"scripts\u002Fsrc\u002Frender\u002Fstats.ts",1203,"https:\u002F\u002Fgithub.com\u002FNecmttn\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fengineering\u002Ffleet-ship\u002Fscripts\u002Fsrc\u002Frender\u002Fstats.ts",{"path":191,"resourceType":58,"resourceTypeDesc":59,"sizeBytes":192,"sourceHtmlUrl":193},"scripts\u002Fsrc\u002Frender\u002Fstatus.test.ts",1618,"https:\u002F\u002Fgithub.com\u002FNecmttn\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fengineering\u002Ffleet-ship\u002Fscripts\u002Fsrc\u002Frender\u002Fstatus.test.ts",{"path":195,"resourceType":58,"resourceTypeDesc":59,"sizeBytes":196,"sourceHtmlUrl":197},"scripts\u002Fsrc\u002Frender\u002Fstatus.ts",2419,"https:\u002F\u002Fgithub.com\u002FNecmttn\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fengineering\u002Ffleet-ship\u002Fscripts\u002Fsrc\u002Frender\u002Fstatus.ts",{"path":199,"resourceType":58,"resourceTypeDesc":59,"sizeBytes":200,"sourceHtmlUrl":201},"scripts\u002Fsrc\u002Frun\u002FRun.test.ts",2557,"https:\u002F\u002Fgithub.com\u002FNecmttn\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fengineering\u002Ffleet-ship\u002Fscripts\u002Fsrc\u002Frun\u002FRun.test.ts",{"path":203,"resourceType":58,"resourceTypeDesc":59,"sizeBytes":204,"sourceHtmlUrl":205},"scripts\u002Fsrc\u002Frun\u002FRun.ts",5070,"https:\u002F\u002Fgithub.com\u002FNecmttn\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fengineering\u002Ffleet-ship\u002Fscripts\u002Fsrc\u002Frun\u002FRun.ts",{"path":207,"resourceType":58,"resourceTypeDesc":59,"sizeBytes":208,"sourceHtmlUrl":209},"scripts\u002Fsrc\u002Frun\u002Fscheduling.test.ts",2817,"https:\u002F\u002Fgithub.com\u002FNecmttn\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fengineering\u002Ffleet-ship\u002Fscripts\u002Fsrc\u002Frun\u002Fscheduling.test.ts",{"path":211,"resourceType":58,"resourceTypeDesc":59,"sizeBytes":212,"sourceHtmlUrl":213},"scripts\u002Fsrc\u002Frun\u002Fstats.test.ts",1515,"https:\u002F\u002Fgithub.com\u002FNecmttn\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fengineering\u002Ffleet-ship\u002Fscripts\u002Fsrc\u002Frun\u002Fstats.test.ts",{"path":215,"resourceType":58,"resourceTypeDesc":59,"sizeBytes":216,"sourceHtmlUrl":217},"scripts\u002Fsrc\u002Frun\u002Fstats.ts",3347,"https:\u002F\u002Fgithub.com\u002FNecmttn\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fengineering\u002Ffleet-ship\u002Fscripts\u002Fsrc\u002Frun\u002Fstats.ts",{"path":219,"resourceType":58,"resourceTypeDesc":59,"sizeBytes":220,"sourceHtmlUrl":221},"scripts\u002Fsrc\u002Fteardown.test.ts",4739,"https:\u002F\u002Fgithub.com\u002FNecmttn\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fengineering\u002Ffleet-ship\u002Fscripts\u002Fsrc\u002Fteardown.test.ts",{"path":223,"resourceType":58,"resourceTypeDesc":59,"sizeBytes":224,"sourceHtmlUrl":225},"scripts\u002Fsrc\u002Fteardown.ts",9602,"https:\u002F\u002Fgithub.com\u002FNecmttn\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fengineering\u002Ffleet-ship\u002Fscripts\u002Fsrc\u002Fteardown.ts",{"path":227,"resourceType":58,"resourceTypeDesc":59,"sizeBytes":228,"sourceHtmlUrl":229},"scripts\u002Fsrc\u002Ftesting\u002Ffixture.ts",3830,"https:\u002F\u002Fgithub.com\u002FNecmttn\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fengineering\u002Ffleet-ship\u002Fscripts\u002Fsrc\u002Ftesting\u002Ffixture.ts",{"path":231,"resourceType":58,"resourceTypeDesc":59,"sizeBytes":232,"sourceHtmlUrl":233},"scripts\u002Fsrc\u002Ftesting\u002FgraphFixture.ts",2166,"https:\u002F\u002Fgithub.com\u002FNecmttn\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fengineering\u002Ffleet-ship\u002Fscripts\u002Fsrc\u002Ftesting\u002FgraphFixture.ts",{"path":235,"resourceType":58,"resourceTypeDesc":59,"sizeBytes":236,"sourceHtmlUrl":237},"scripts\u002Fsrc\u002Fworkflow\u002FWorkflow.test.ts",1244,"https:\u002F\u002Fgithub.com\u002FNecmttn\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fengineering\u002Ffleet-ship\u002Fscripts\u002Fsrc\u002Fworkflow\u002FWorkflow.test.ts",{"path":239,"resourceType":58,"resourceTypeDesc":59,"sizeBytes":240,"sourceHtmlUrl":241},"scripts\u002Fsrc\u002Fworkflow\u002FWorkflow.ts",1431,"https:\u002F\u002Fgithub.com\u002FNecmttn\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fengineering\u002Ffleet-ship\u002Fscripts\u002Fsrc\u002Fworkflow\u002FWorkflow.ts",{"path":243,"resourceType":58,"resourceTypeDesc":59,"sizeBytes":244,"sourceHtmlUrl":245},"scripts\u002Ftest-monitor-tail.py",5717,"https:\u002F\u002Fgithub.com\u002FNecmttn\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fengineering\u002Ffleet-ship\u002Fscripts\u002Ftest-monitor-tail.py",{"path":247,"resourceType":58,"resourceTypeDesc":59,"sizeBytes":248,"sourceHtmlUrl":249},"scripts\u002Ftsconfig.json",357,"https:\u002F\u002Fgithub.com\u002FNecmttn\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fengineering\u002Ffleet-ship\u002Fscripts\u002Ftsconfig.json",{"path":251,"resourceType":58,"resourceTypeDesc":59,"sizeBytes":252,"sourceHtmlUrl":253},"scripts\u002Fverify-codex-launch.sh",4969,"https:\u002F\u002Fgithub.com\u002FNecmttn\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fengineering\u002Ffleet-ship\u002Fscripts\u002Fverify-codex-launch.sh",{"path":255,"resourceType":58,"resourceTypeDesc":59,"sizeBytes":256,"sourceHtmlUrl":257},"scripts\u002Fworkflow.json",380,"https:\u002F\u002Fgithub.com\u002FNecmttn\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fengineering\u002Ffleet-ship\u002Fscripts\u002Fworkflow.json",[259,266,273,280,287,295],{"skillNo":260,"name":261,"nameZh":6,"description":262,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":263,"categories":264,"keywords":265,"publishedAt":19},"01M77PNJ1JCKWHR2XJDBX8Q85P","wiki","Recall from the personal LLM wiki at ~\u002Fwiki. Use when the user asks what the wiki says, wants prior thinking\u002Fintuition on a concept, or when grounding a design or decision in previously synthesized knowledge. Read-only - never writes to the wiki.","https:\u002F\u002Fgithub.com\u002FNecmttn\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fpersonal\u002Fwiki\u002FSKILL.md",[],[],{"skillNo":267,"name":268,"nameZh":6,"description":269,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":270,"categories":271,"keywords":272,"publishedAt":19},"01M77PNERKEH3ZN11HMC6YEH9G","wiki-ingest","Curate a source into the personal LLM wiki at ~\u002Fwiki following its SCHEMA.md - a file, URL, research output, ax session, or a pending ~\u002Fwiki\u002Finbox\u002F brief. Use when the user says \"add this to the wiki\", \"ingest this\", \"promote the inbox\", or after research worth keeping long-term.","https:\u002F\u002Fgithub.com\u002FNecmttn\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fpersonal\u002Fwiki-ingest\u002FSKILL.md",[],[],{"skillNo":274,"name":275,"nameZh":6,"description":276,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":277,"categories":278,"keywords":279,"publishedAt":19},"01M77PNB9SMTTG3D80BXGCY16B","wiki-harvest","Propose-only sweep of recent coding sessions (via the ax CLI) for recurring concepts that are missing from, or should update, the personal LLM wiki at ~\u002Fwiki. Writes candidate briefs to ~\u002Fwiki\u002Finbox\u002F only - never wiki pages. Use on schedule or when the user asks \"harvest the wiki\" or \"what concepts am I repeating\".","https:\u002F\u002Fgithub.com\u002FNecmttn\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fpersonal\u002Fwiki-harvest\u002FSKILL.md",[],[],{"skillNo":281,"name":282,"nameZh":6,"description":283,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":284,"categories":285,"keywords":286,"publishedAt":19},"01M77PN73WAF08PCWBYXST9BW6","no-ai-slop","Strip AI-slop patterns from a draft while preserving the writer's voice, or detect slop without rewriting. Use as the mandatory final pass on any copy before shipping, when the user wants a draft clearer\u002Fless AI-sounding, or when asked \"is this AI slop?\", \"audit this writing\", \"does this read as AI\".","https:\u002F\u002Fgithub.com\u002FNecmttn\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fpersonal\u002Fno-ai-slop\u002FSKILL.md",[],[],{"skillNo":288,"name":289,"nameZh":6,"description":290,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":291,"sourceHtmlUrl":292,"categories":293,"keywords":294,"publishedAt":19},"01M77PN2H1QTPD9GD6VBJ3YBPN","aso-appstore-screenshots","Generate high-converting App Store screenshots by analyzing your app's codebase, discovering core benefits, and creating ASO-optimized screenshot images using Nano Banana Pro.","https:\u002F\u002Fgithub.com\u002FNecmttn\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fmisc\u002Faso-appstore-screenshots\u002FLICENSE","https:\u002F\u002Fgithub.com\u002FNecmttn\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fmisc\u002Faso-appstore-screenshots\u002FSKILL.md",[],[],{"skillNo":296,"name":297,"nameZh":6,"description":298,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":299,"categories":300,"keywords":301,"publishedAt":19},"01M77PMVGA58GA46JCFJW2JH5X","app-idea","Run a new or existing consumer\u002FAI app idea through the golden-track playbook (~\u002Fwiki\u002Fplaybook\u002Fapps.md) from intake to verdict, write a verdict card, stop for the owner, and ratchet owner overrides back into the doctrine. Use when the user shares an app idea, asks \"should I build X\", \"audit \u003Capp>\", \"re-score \u003Capp>\", or pastes an idea in a product context. Never builds; never promotes a rule on its own.","https:\u002F\u002Fgithub.com\u002FNecmttn\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fmisc\u002Fapp-idea\u002FSKILL.md",[],[]]