@feigi/fleet-ctl 0.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (245) hide show
  1. package/.claude-plugin/plugin.json +9 -0
  2. package/LICENSE +202 -0
  3. package/NOTICE +18 -0
  4. package/agents/fleet-finisher.agent.md +7 -0
  5. package/agents/fleet-implementer-alt.agent.md +210 -0
  6. package/agents/fleet-implementer.agent.md +210 -0
  7. package/agents/fleet-merge-bot.agent.md +7 -0
  8. package/agents/fleet-review-comments.agent.md +40 -0
  9. package/agents/fleet-review-correctness.agent.md +43 -0
  10. package/agents/fleet-review-runner.agent.md +73 -0
  11. package/agents/fleet-review-silent-failure.agent.md +49 -0
  12. package/agents/fleet-review-simplify.agent.md +46 -0
  13. package/agents/fleet-review-snapshot.agent.md +24 -0
  14. package/agents/fleet-review-tests.agent.md +46 -0
  15. package/agents/fleet-review-types.agent.md +41 -0
  16. package/agents/fleet-review-verifier.agent.md +29 -0
  17. package/commands/review-and-fix.md +98 -0
  18. package/commands/run-merge-bot.md +357 -0
  19. package/commands/run-team-help.md +17 -0
  20. package/package.json +23 -0
  21. package/scripts/agent-test-dir-prose.test.mjs +59 -0
  22. package/scripts/agent-test.test.mjs +1636 -0
  23. package/scripts/ambient-git-vars-mjs-prose.test.mjs +354 -0
  24. package/scripts/ambient-git-vars-prose.test.mjs +192 -0
  25. package/scripts/ancestry-check-position-prose.test.mjs +175 -0
  26. package/scripts/apply-ruleset.test.mjs +420 -0
  27. package/scripts/arg-header-probes-prose.test.mjs +393 -0
  28. package/scripts/arg.mjs +600 -0
  29. package/scripts/arg.test.mjs +1354 -0
  30. package/scripts/board-cli.test.mjs +694 -0
  31. package/scripts/board-identity.test.mjs +429 -0
  32. package/scripts/board-liveness-banner.test.mjs +119 -0
  33. package/scripts/board-prev-shape.test.mjs +229 -0
  34. package/scripts/board-tryparse-null.test.mjs +119 -0
  35. package/scripts/board.html +471 -0
  36. package/scripts/board.mjs +2037 -0
  37. package/scripts/board.test.mjs +3086 -0
  38. package/scripts/brief-after-cut-prose.test.mjs +53 -0
  39. package/scripts/candidates-exit3-prose.test.mjs +302 -0
  40. package/scripts/candidates.mjs +674 -0
  41. package/scripts/candidates.test.mjs +2101 -0
  42. package/scripts/caveat-unification-prose.test.mjs +98 -0
  43. package/scripts/ci-comment-rot-prose.test.mjs +2025 -0
  44. package/scripts/ci-completes-premise-prose.test.mjs +257 -0
  45. package/scripts/ci-state-prose.test.mjs +113 -0
  46. package/scripts/ci-state.mjs +761 -0
  47. package/scripts/ci-state.test.mjs +1640 -0
  48. package/scripts/ci-vacuous-green.test.mjs +368 -0
  49. package/scripts/citation-sweep-prose.test.mjs +1572 -0
  50. package/scripts/claim-lifecycle.test.mjs +185 -0
  51. package/scripts/claim-ticket.sh +417 -0
  52. package/scripts/claim-ticket.test.mjs +1121 -0
  53. package/scripts/closing-keyword-prose.test.mjs +193 -0
  54. package/scripts/cockpit-launch-idempotent-prose.test.mjs +165 -0
  55. package/scripts/cockpit-tick-nonblocking.test.mjs +210 -0
  56. package/scripts/compute-board.mjs +579 -0
  57. package/scripts/compute-board.test.mjs +1060 -0
  58. package/scripts/compute-spend.mjs +329 -0
  59. package/scripts/compute-spend.test.mjs +451 -0
  60. package/scripts/cross-repo-citation-prose.test.mjs +156 -0
  61. package/scripts/cwd-isolation-pins.mjs +83 -0
  62. package/scripts/dedupe-guard-prose.test.mjs +243 -0
  63. package/scripts/derive-testcmd.sh +239 -0
  64. package/scripts/derive-testcmd.test.mjs +380 -0
  65. package/scripts/diff-stats.mjs +231 -0
  66. package/scripts/diff-stats.test.mjs +408 -0
  67. package/scripts/dispatch-block-golden-prose.test.mjs +1024 -0
  68. package/scripts/dispatch-block-pins-prose.test.mjs +615 -0
  69. package/scripts/drop-merged-label.sh +173 -0
  70. package/scripts/drop-merged-label.test.mjs +480 -0
  71. package/scripts/expected-jobs-prose.test.mjs +80 -0
  72. package/scripts/filing-bar-seat-prose.test.mjs +242 -0
  73. package/scripts/filing-claim-bar-prose.test.mjs +166 -0
  74. package/scripts/finisher-dispatch-premise-prose.test.mjs +312 -0
  75. package/scripts/finisher-halt-prose.test.mjs +106 -0
  76. package/scripts/finisher-name-prose.test.mjs +134 -0
  77. package/scripts/finisher-own-tree-prose.test.mjs +285 -0
  78. package/scripts/finisher-pin-race-prose.test.mjs +339 -0
  79. package/scripts/fix-applier-correction-rules-prose.test.mjs +201 -0
  80. package/scripts/fix-applier-result-file-prose.test.mjs +100 -0
  81. package/scripts/fleet-bootstrap +155 -0
  82. package/scripts/fleet-heartbeat.mjs +272 -0
  83. package/scripts/fleet-heartbeat.test.mjs +450 -0
  84. package/scripts/fleet-provenance +207 -0
  85. package/scripts/fleet-provenance.test.mjs +64 -0
  86. package/scripts/fleet-run +148 -0
  87. package/scripts/fleet-run.test.mjs +90 -0
  88. package/scripts/fleet-state.mjs +400 -0
  89. package/scripts/fleet-state.test.mjs +373 -0
  90. package/scripts/fleet-tick-prose.test.mjs +299 -0
  91. package/scripts/fleet-tick.mjs +832 -0
  92. package/scripts/fleet-tick.test.mjs +1332 -0
  93. package/scripts/force-with-lease-reason-prose.test.mjs +184 -0
  94. package/scripts/frontmatter-allowlist.json +64 -0
  95. package/scripts/frontmatter-check.mjs +256 -0
  96. package/scripts/frontmatter-check.test.mjs +436 -0
  97. package/scripts/git-env.mjs +124 -0
  98. package/scripts/git-env.test.mjs +149 -0
  99. package/scripts/git-status-untracked-mode-sweep.test.mjs +216 -0
  100. package/scripts/gone-walk.test.mjs +213 -0
  101. package/scripts/gp-sep-invariant-prose.test.mjs +188 -0
  102. package/scripts/head-moved-after-label-prose.test.mjs +233 -0
  103. package/scripts/immutable-body-claim-prose.test.mjs +413 -0
  104. package/scripts/implementer-model-tier.test.mjs +643 -0
  105. package/scripts/inflight-citation-prose.test.mjs +144 -0
  106. package/scripts/inflight-exit2-prose.test.mjs +81 -0
  107. package/scripts/inflight-probe-guard-prose.test.mjs +109 -0
  108. package/scripts/inflight-scan-scope-prose.test.mjs +57 -0
  109. package/scripts/inflight.sh +1106 -0
  110. package/scripts/inflight.test.mjs +2984 -0
  111. package/scripts/injection-control-prose.test.mjs +404 -0
  112. package/scripts/install-root-audit.test.mjs +464 -0
  113. package/scripts/instrument-check-prose.test.mjs +235 -0
  114. package/scripts/instruments.sh +394 -0
  115. package/scripts/instruments.test.mjs +787 -0
  116. package/scripts/issue-tracker-prose.test.mjs +71 -0
  117. package/scripts/json.sh +248 -0
  118. package/scripts/json.test.mjs +364 -0
  119. package/scripts/ledger-dispatch.test.mjs +516 -0
  120. package/scripts/ledger-grammar.mjs +85 -0
  121. package/scripts/ledger-grammar.test.mjs +142 -0
  122. package/scripts/ledger-read-require-file.test.mjs +197 -0
  123. package/scripts/ledger.mjs +1753 -0
  124. package/scripts/ledger.test.mjs +3554 -0
  125. package/scripts/line-distance-prose.test.mjs +245 -0
  126. package/scripts/liveness-rationale-prose.test.mjs +83 -0
  127. package/scripts/locale-pin-prose.test.mjs +189 -0
  128. package/scripts/member-outcome-prose.test.mjs +167 -0
  129. package/scripts/member-outcomes-header.test.mjs +148 -0
  130. package/scripts/member-outcomes-prose.test.mjs +63 -0
  131. package/scripts/member-outcomes.mjs +231 -0
  132. package/scripts/member-outcomes.test.mjs +507 -0
  133. package/scripts/member-prompt-prose.test.mjs +161 -0
  134. package/scripts/member-record.mjs +605 -0
  135. package/scripts/member-record.test.mjs +516 -0
  136. package/scripts/member-write-guard.mjs +279 -0
  137. package/scripts/member-write-guard.test.mjs +211 -0
  138. package/scripts/merge-commit-probe-prose.test.mjs +122 -0
  139. package/scripts/merge-gate.mjs +262 -0
  140. package/scripts/merge-gate.test.mjs +613 -0
  141. package/scripts/muted-git-guard-sweep.test.mjs +493 -0
  142. package/scripts/net-ssh-precedence-prose.test.mjs +91 -0
  143. package/scripts/net-watchdog-prose.test.mjs +79 -0
  144. package/scripts/net.sh +409 -0
  145. package/scripts/net.test.mjs +211 -0
  146. package/scripts/no-ci-gate-prose.test.mjs +108 -0
  147. package/scripts/no-undo-audit.sh +1134 -0
  148. package/scripts/no-undo-audit.test.mjs +3965 -0
  149. package/scripts/no-wave.test.mjs +138 -0
  150. package/scripts/node-floor-sweep.test.mjs +611 -0
  151. package/scripts/pointer-target-prose.test.mjs +186 -0
  152. package/scripts/pr-overlap.mjs +417 -0
  153. package/scripts/pr-overlap.test.mjs +695 -0
  154. package/scripts/printf-die-sweep.test.mjs +384 -0
  155. package/scripts/prompt-renderer.mjs +39 -0
  156. package/scripts/prompt-renderer.test.mjs +68 -0
  157. package/scripts/prose-pin.mjs +808 -0
  158. package/scripts/prose-pin.test.mjs +1034 -0
  159. package/scripts/prove-merge.sh +228 -0
  160. package/scripts/prove-merge.test.mjs +995 -0
  161. package/scripts/pull-table-relabel-prose.test.mjs +60 -0
  162. package/scripts/quiet-payload-prose.test.mjs +222 -0
  163. package/scripts/reap.sh +1768 -0
  164. package/scripts/reap.test.mjs +4395 -0
  165. package/scripts/reaping-prose.test.mjs +159 -0
  166. package/scripts/refuter-scratch-prose.test.mjs +135 -0
  167. package/scripts/release-label-required-prose.test.mjs +71 -0
  168. package/scripts/release-label-split-prose.test.mjs +169 -0
  169. package/scripts/release-ticket.sh +1716 -0
  170. package/scripts/release-ticket.test.mjs +5106 -0
  171. package/scripts/renovate-release-contract.test.mjs +379 -0
  172. package/scripts/repo-root.mjs +544 -0
  173. package/scripts/repo-root.test.mjs +873 -0
  174. package/scripts/reporter-output-rule-prose.test.mjs +208 -0
  175. package/scripts/review-agent-report-only.test.mjs +49 -0
  176. package/scripts/review-core-cwd-isolation.test.mjs +374 -0
  177. package/scripts/review-core-reads.test.mjs +478 -0
  178. package/scripts/review-core-refuter-scratch.test.mjs +148 -0
  179. package/scripts/review-core-snapshot-path.test.mjs +777 -0
  180. package/scripts/review-core-specialist-scratch.test.mjs +189 -0
  181. package/scripts/review-core-testcmd.test.mjs +288 -0
  182. package/scripts/review-core-unrun.test.mjs +530 -0
  183. package/scripts/review-core-unverified-discriminant.test.mjs +208 -0
  184. package/scripts/review-core.mjs +1028 -0
  185. package/scripts/review-eval-resolver-path.test.mjs +55 -0
  186. package/scripts/review-eval.mjs +197 -0
  187. package/scripts/review-host-fixture.mjs +73 -0
  188. package/scripts/review-in-run-retry.test.mjs +187 -0
  189. package/scripts/review-no-vendor-dispatch.test.mjs +45 -0
  190. package/scripts/review-path-default.test.mjs +796 -0
  191. package/scripts/review-runner-spawns.test.mjs +93 -0
  192. package/scripts/review-runner.test.mjs +155 -0
  193. package/scripts/review-tier-audit.test.mjs +140 -0
  194. package/scripts/run-artifact-pr-prose.test.mjs +341 -0
  195. package/scripts/run-merge-bot-prose.test.mjs +1391 -0
  196. package/scripts/scratch-partition-invariant-prose.test.mjs +74 -0
  197. package/scripts/scripts-path-citation-sweep.test.mjs +73 -0
  198. package/scripts/section-between-guard-prose.test.mjs +378 -0
  199. package/scripts/select-dimensions.test.mjs +674 -0
  200. package/scripts/shared-refusal.test.mjs +388 -0
  201. package/scripts/shell-traps-prose.test.mjs +507 -0
  202. package/scripts/shortlist.mjs +355 -0
  203. package/scripts/shortlist.test.mjs +366 -0
  204. package/scripts/slow-transport.mjs +72 -0
  205. package/scripts/snapshot-repo.test.mjs +772 -0
  206. package/scripts/snapshot-runner-audience-prose.test.mjs +129 -0
  207. package/scripts/spend-view.test.mjs +312 -0
  208. package/scripts/staleness-qualifier-prose.test.mjs +251 -0
  209. package/scripts/staleness-verdict-prose.test.mjs +142 -0
  210. package/scripts/staleness.mjs +414 -0
  211. package/scripts/staleness.test.mjs +893 -0
  212. package/scripts/stalled-member-liveness-prose.test.mjs +219 -0
  213. package/scripts/stash-prohibition-prose.test.mjs +313 -0
  214. package/scripts/strip-comments.mjs +44 -0
  215. package/scripts/tier-check.mjs +468 -0
  216. package/scripts/tier-check.test.mjs +726 -0
  217. package/scripts/tier-guard-gate-prose.test.mjs +216 -0
  218. package/scripts/tier-outcomes-header.test.mjs +586 -0
  219. package/scripts/tier-outcomes.mjs +441 -0
  220. package/scripts/tier-outcomes.test.mjs +342 -0
  221. package/scripts/tier-roles.mjs +250 -0
  222. package/scripts/tier-roles.test.mjs +316 -0
  223. package/scripts/tracker-block-copy-prose.test.mjs +288 -0
  224. package/scripts/triage-labels-gloss-prose.test.mjs +97 -0
  225. package/scripts/unattended-git-sweep.test.mjs +142 -0
  226. package/scripts/verify-sha-exit2-prose.test.mjs +269 -0
  227. package/scripts/verify-sha.sh +117 -0
  228. package/scripts/verify-sha.test.mjs +693 -0
  229. package/scripts/watcher-degraded-block.test.mjs +372 -0
  230. package/scripts/watcher-key-prose.test.mjs +106 -0
  231. package/scripts/within-run-pair-prose.test.mjs +208 -0
  232. package/scripts/worktree-audit.sh +482 -0
  233. package/scripts/worktree-audit.test.mjs +1407 -0
  234. package/scripts/worktree-head-prose.test.mjs +276 -0
  235. package/scripts/worktree-listing-sweep.test.mjs +217 -0
  236. package/scripts/worktree-model-prose.test.mjs +216 -0
  237. package/scripts/worktree.sh +470 -0
  238. package/skills/next-ticket/SKILL.md +138 -0
  239. package/skills/run-team/SKILL.md +3603 -0
  240. package/skills/run-team/references/ci-and-staleness.md +75 -0
  241. package/skills/run-team/references/correction-tickets.md +37 -0
  242. package/skills/run-team/references/isolation.md +23 -0
  243. package/skills/run-team/references/member-lifecycle.md +73 -0
  244. package/skills/run-team/references/reaping.md +73 -0
  245. package/skills/sizing-a-ticket/SKILL.md +39 -0
@@ -0,0 +1,3603 @@
1
+ ---
2
+ name: run-team
3
+ description: Run an agent fleet — implementers, reviewers (default 2 and 6), one merge bot — over the ready-for-agent queue. Invoke-only; the fleet writes to a live repo and must never start unasked.
4
+ argument-hint: "[implementers] [reviewers]"
5
+ disable-model-invocation: true
6
+ ---
7
+
8
+ Run `next-ticket`, `review-and-fix`, `run-merge-bot` as one fleet. You are the
9
+ **controller**, in the main thread, never a member.
10
+
11
+ `$ARGUMENTS` = `[implementers] [reviewers]`, both optional, default 2 and 6, no
12
+ hard cap — they become the tick's `--implementer-cap` and `--reviewer-cap`.
13
+ Merge bot is at most one, not configurable.
14
+
15
+ Rationale: `docs/specs/2026-07-22-run-team-agent-fleet-design.md`. The
16
+ war story behind a rule ending `See references/<file>` lives in that file; load
17
+ it only when a member needs the *why*. A rule without that line carries its
18
+ reasoning inline — nothing is missing.
19
+
20
+ ## Rules that fail silently
21
+
22
+ **A report is delivered, not implied by ending a turn.** Every member owes
23
+ the controller one report naming its outcome before it exits — including a
24
+ member whose prompt carries no explicit report line. The "report the SHA",
25
+ "report PR number" and "stop and report" instructions below *are* that
26
+ report, not a second obligation on top of it. A member that does the work
27
+ correctly and ends its turn has reported nothing: the controller learns the
28
+ outcome only by re-reading artifacts and pinging, and a finding held only in
29
+ that member's context is lost. Members did exactly this in one run —
30
+ finishers, a reviewer and merge bots alike, the work done and only the
31
+ delivery missing. Say it in every dispatch prompt. See
32
+ references/member-lifecycle.md.
33
+
34
+ **Say in every dispatch prompt that you do not acknowledge reports.** A
35
+ member cannot see whether its report arrived, so silence from you is
36
+ indistinguishable from loss and it re-sends — three members did in one run,
37
+ each burning a turn, and in all three the original had in fact arrived. Give
38
+ them the line verbatim: *"The controller does not acknowledge reports. Send
39
+ once and exit; never re-send unless the controller asks by name."*
40
+
41
+ **But a missing report is NOT evidence the member failed to send one — the
42
+ inbound direction drops AND delays messages.** Both were measured in one run,
43
+ and they are indistinguishable at the moment you look: one finisher's report was
44
+ accepted with a msg_id and never arrived at all, while another's arrived late —
45
+ its original and its re-send landing together, after the controller had already
46
+ concluded it was missing. Measured: a finisher completed every
47
+ duty, labelled the PR, and sent its report; the send was accepted with a msg_id
48
+ and never arrived. The controller read the silence as the member ending its turn
49
+ without reporting, said so, and was wrong. The re-send it asked for by name is
50
+ the only reason the report exists. So when a report is missing, **ask by name —
51
+ that is what the "unless the controller asks by name" clause is for — and do not
52
+ attribute the gap to the member until it answers.** A member re-sending on a
53
+ named request should state the original's msg_id and that it is a re-send, which
54
+ is what distinguishes a lost message from a member that never sent one; a
55
+ controller that skips the ask cannot tell those apart and will guess wrong in
56
+ whichever direction its expectations point.
57
+
58
+ Note this cuts against the paragraph above only in appearance: the default stays
59
+ *send once*, because unprompted re-sends were measured 2-to-1 false. The ask is
60
+ the controller's move, not the member's.
61
+
62
+ **Your OWN messages can vanish the same way, and that half is not recoverable by
63
+ a re-send.** Two controller rulings were lost in one run, both with a
64
+ `success: true` receipt: a member proceeded on its stated default and filed a
65
+ tracker issue the lost ruling had said not to file. So **never read a member's
66
+ silence as assent**, and require members to report their *confirmation state*
67
+ alongside results — "I escalated X, received no ruling, proceeded on default Y".
68
+ That sentence is the only thing that made either loss visible. After any ruling
69
+ you cannot confirm was received, re-check the artifacts it governed.
70
+
71
+ **Name every member.** The name is the ledger token and the hub address; omit
72
+ it and the ledger cannot match the member.
73
+ Names follow the unit of work: `impl-<issue#>`, `fix-pr-<pr#>`,
74
+ `review-pr-<pr#>`, `finisher-pr-<pr#>`, `merge-bot-<n>`. See
75
+ references/member-lifecycle.md.
76
+
77
+ **A depth-2 member cannot dispatch further** (`task.maxRecursionDepth: 2`):
78
+ if `task` is absent at your depth, ask the controller to dispatch the
79
+ specialists and relay their reports. Say so in a fallback reviewer's prompt,
80
+ or it silently downgrades to a solo review. See references/member-lifecycle.md.
81
+
82
+ **Fresh context per member.** One member, one unit of work, gone. Never
83
+ re-task a finished member — waking it drags the old ticket back in. Refill =
84
+ **new** member, **new** name. Sending is still right for pinging a live
85
+ member for a report it owes, or resuming a truncated reply — never for
86
+ handing a finished member the next ticket.
87
+
88
+ `hub send` to an idle peer wakes it into its old transcript the same way; re-dispatching under the same name does not reset it — omp auto-suffixes a fresh peer (`name-2`) instead.
89
+
90
+ See references/member-lifecycle.md.
91
+
92
+ **You read your instruments out of a tree every member can write to — re-check
93
+ them before every gate decision.** Per-member worktrees and `./agent-test`'s port
94
+ derivation protect members from each other; neither protects the main checkout,
95
+ which you run every gate probe out of and which any member can edit — except
96
+ through a `write`/`edit`/`ast_edit` the `member-write-guard` extension refuses
97
+ (ADR 0020); a `bash` or `eval` write still lands (#2210). Measured: a
98
+ member edited two files there instead of in its worktree while the CI monitor was
99
+ polling one of them every 120s and a live finisher was using it to decide a
100
+ label. It caught itself; nothing in the fleet would have. That is the silent
101
+ direction — a modified instrument raises no error, shows in no PR and leaves
102
+ nothing in the ledger, and it still returns a verdict, just not necessarily the
103
+ right one, so you have no reason to re-check a script you did not know had
104
+ changed.
105
+
106
+ - **Pin once**, at phase 0 step 0 below, from the main checkout you are
107
+ running this from — never from a member's worktree, which is gitignored
108
+ and carries no baseline:
109
+ `~/.fleet/bin/fleet-run instruments.sh --pin`. On a workspace that does not
110
+ track `plugin/…`, the pin names the plugin checkout once — `--pin --audit
111
+ <plugin-checkout>` — and every check after it follows the recorded tree.
112
+ - **Re-check before you act on any instrument reading** — a SHA acceptance, a CI
113
+ verdict, the reconcile, a reap, a label gate — from that same main checkout:
114
+ `~/.fleet/bin/fleet-run instruments.sh`. **Exit 0 is the only code that
115
+ lets a gate proceed. Exit 1 (the set changed) and exit 2 (the check could not
116
+ answer) both refuse: report what it printed and do NOT re-read the
117
+ instrument** — a guard that fails open on "could not look" protects nothing.
118
+ **A label gate and a CI verdict are also taken by dispatched members, not
119
+ only by you** — the finisher labels, and the merge bot merges on its own
120
+ reading — and neither is dispatched to read this file, so neither can be
121
+ reached by stating the rule here. Each carries its own copy: the finisher's
122
+ in the verbatim block at its duties below, the merge bot's inside
123
+ `merge-gate.mjs`, step 3 of `run-merge-bot.md`.
124
+ - **Re-pin only after a change you made deliberately.** The mid-run tooling fix
125
+ below is the one legitimate writer. Re-pinning to clear a refusal you cannot
126
+ explain discards the check.
127
+
128
+ It covers every tracked file under this repo's own plugin component directories
129
+ — `plugin/commands/`, `plugin/scripts/`, `plugin/skills/`, `plugin/agents/`,
130
+ `plugin/workflows/` — the probes, the libraries they source, and these runbooks,
131
+ which you also read from that tree. Not the whole repo: `docs/metrics/` is
132
+ appended by THIS run, so covering it would refuse on the run's own bookkeeping
133
+ every time. It does not cover refs, deliberately: `claim-ticket.sh` creates a
134
+ branch per ticket and `reap.sh` deletes them in the ref store every worktree
135
+ shares, so ordinary work moves refs several times a run and a per-gate
136
+ refusal on that is noise.
137
+
138
+ **A member runs its test suite in the foreground and blocks on it.**
139
+ Backgrounding a suite and polling for it makes the member's own progress
140
+ depend on a wake-up nothing in the fleet guarantees, and an idle member is
141
+ indistinguishable from a working one — you learn only by pinging. Measured
142
+ twice in one run: `fix-pr-1184` backgrounded its suite plus a Monitor and sat
143
+ idle for roughly two hours; neither ever woke it, and the only reason no work
144
+ was lost is that you pinged it by name with a concrete next action.
145
+ `finisher-pr-1184` reached for the same pattern minutes later — a proactive
146
+ warning is the only reason it did not repeat the stall. Its
147
+ `pgrep -f 'finish-finisher-pr-1184'` could never have matched any process, so
148
+ the poll it was waiting on was structurally incapable of firing. Say it in
149
+ every dispatch prompt — this file is yours, not theirs, so a member learns
150
+ it only if you write it into the prompt.
151
+
152
+ ## Shell traps
153
+
154
+ Monitor and Bash commands run under **zsh**, and the shell in this file is
155
+ prescriptive — copied verbatim into a watcher or pasted into a bot's brief. So
156
+ every trap here is a zsh-vs-bash difference that ships as a green-looking gate:
157
+ correct in the shell you tested in, silently wrong in the one it runs in. Phase
158
+ 3's monitor paragraph and the **Merge bot**'s brief both point here
159
+ instead of restating any of it; the one deliberate copy is named at the end.
160
+
161
+ **zsh word-splits an unquoted command substitution's result; it does NOT split
162
+ an unquoted parameter expansion.** That one difference is the whole rule, and the
163
+ hazard is the **assigned-variable** form, never `$(…)`. Measured on zsh 5.9
164
+ against `849`, `850`, `852` on three lines:
165
+
166
+ | Form | zsh | bash / sh |
167
+ |---|---|---|
168
+ | `prs=$(gh pr list …)` then `for pr in $prs` | **1 iteration**, all three glued into one value | 3 |
169
+ | `for pr in $(gh pr list …)` | 3 | 3 |
170
+ | `for _ in $(seq 1 60)` | 60 | 60 |
171
+
172
+ **Word the rule against the first row.** A warning spelled *never `for x in
173
+ $(…)`* names the safe form as the hazard, so a reader avoids the form that works,
174
+ keeps the one that collapses, and rewrites correct bounded polls on the way.
175
+ #854 was filed carrying that inversion in its own remedy clause and in its title,
176
+ and its filer measured both forms and retracted it; the corrected rule is this
177
+ row. `$(…)` splits. Leave it alone.
178
+
179
+ **Capture-then-loop needs `while IFS= read -r` fed by a heredoc**, which is
180
+ line-exact under every shell:
181
+
182
+ ```sh
183
+ while IFS= read -r pr; do
184
+ [ -n "$pr" ] || continue # a blank line from an empty capture, not a probe that could not look
185
+ node …/ci-state.mjs --pr "$pr" </dev/null # every inner call, per the trap below
186
+ done <<EOF
187
+ $prs
188
+ EOF
189
+ ```
190
+
191
+ The inline `$(printf '%s\n' "$prs")` form splits correctly too and is what Phase
192
+ 3's block uses, but it splits on *every* whitespace character, so it is safe only
193
+ for values that cannot contain one — PR numbers cannot, branch names and paths
194
+ can. Measured on a two-line list whose first value is `two words`: three
195
+ iterations through `$(printf …)`, two through `while IFS= read -r`. On an empty
196
+ `$prs` the counts diverge the other way: `for pr in $(printf '%s\n' "$prs")`
197
+ iterates **zero** times, but the heredoc form iterates **once** with `pr` empty —
198
+ the guard above is what stops that iteration from probing `--pr ""`.
199
+
200
+ **`</dev/null` every command inside a `while read` loop.** The loop's stdin *is*
201
+ the list, and any inner command that reads stdin eats the rest of it. Measured on
202
+ the three-line list above: one unredirected inner reader takes the loop to **1
203
+ iteration**, `</dev/null` on it restores 3 — the identical signature to the
204
+ word-split bug, so a correct heredoc fix missing this half looks exactly like no
205
+ fix at all, and reads as one.
206
+
207
+ **A probe that could not look emits an event; it never `continue`s.** Stated in
208
+ full at *A probe that cannot read is a transition event, not silence* in Phase 3,
209
+ and it binds every watcher in this file rather than that one block: the third
210
+ value beside pass and fail is what turns a broken loop into a loud failure
211
+ instead of a quiet one. A guard that drops an unreadable probe — `[ -n "$json" ]
212
+ || continue` — makes *could not look* indistinguishable from *nothing to report*.
213
+
214
+ **`$?`/`PIPESTATUS` is unconditionally-TRUE in zsh.** zsh has no `PIPESTATUS`
215
+ (its array is lowercase `pipestatus`, 1-indexed), so `${PIPESTATUS[0]}` is always
216
+ empty and `[ "" -eq 0 ]` passes. A bot's merge gate opened without ever reading
217
+ an exit code.
218
+
219
+ **`status` is a READ-ONLY variable in zsh**, an alias for `$?`. So the obvious
220
+ bash idiom for reading the payload — `status=$(jq -r '.status' ci.json)` — aborts
221
+ with `read-only variable: status`. Measured this way it fails safe (a hard abort,
222
+ no merge), but the same assignment inside an `if`, or with stderr suppressed,
223
+ reads as a check that silently did not run. Same root cause as the `PIPESTATUS`
224
+ trap, opposite failure direction — so name the variable anything else
225
+ (`ci_status`).
226
+
227
+ **The one deliberate copy is `env $cfg sh ./probe.sh`.** The first trap's
228
+ mechanism bites argv as well as loops, and that instance stays written out in the
229
+ fix-applier prompt and every refuter brief under **Reviewers** rather than here,
230
+ because the seats that inject faults are the ones that need it and a bot reads
231
+ gates without ever injecting one. Do not fold it into this block, and do not
232
+ restate this block there.
233
+
234
+ ## Phase 0 — shortlist
235
+
236
+ Once per run, at start. Supply is automatic after that (ADR 0013): the tick
237
+ refreshes the Shortlist itself, and every admission is a **Pull** — one ticket
238
+ into one free implementer slot, the moment it frees (phase 1). Nothing in this
239
+ phase, or in any later one, asks the maintainer which tickets to take.
240
+
241
+ 0. **Once per run, before anything else.**
242
+
243
+ **Fast-forward the checkout before you trust these rules — you are reading
244
+ them from it.** `git fetch origin && git rev-list --count main..origin/main`;
245
+ non-zero means the SKILL.md you are executing is superseded, so
246
+ `git merge --ff-only origin/main` and re-read what changed under
247
+ `commands/`, `scripts/` and `skills/`. The usual cause is the PREVIOUS run's own close-out PR: it
248
+ lands the rules THIS run needs and nothing pulls them. Measured twice — 57
249
+ commits stale in one run, 20 in another, the second shipping every dispatch
250
+ prompt without two rules that had merged the day before. Silent by
251
+ construction: stale text reads as authoritative, and the tier guard's own
252
+ floor is re-derived from a stale `tier-outcomes.tsv` at the same time.
253
+
254
+ **Pin the instruments, after that fast-forward and before anything reads
255
+ them, from this main checkout.** `~/.fleet/bin/fleet-run instruments.sh --pin`
256
+ records what the scripts and runbooks in this repo say right now, which is
257
+ what every later gate compares against; the rule above says what its exit
258
+ codes mean. Pinning before that fast-forward would instead pin the
259
+ superseded text and certify it for the rest of the run.
260
+ **When this workspace does not track `plugin/…`** — fleets run here on an
261
+ installed plugin rather than a vendored tree — the bare pin refuses on an
262
+ empty instrument set, because this checkout holds no instruments to certify.
263
+ Name the plugin checkout to the pin instead:
264
+ `~/.fleet/bin/fleet-run instruments.sh --pin --audit <plugin-checkout>`.
265
+ The baseline records the audited tree beside the digest, and every later
266
+ check — yours, a finisher's, the merge gate's own leg — follows that
267
+ recorded root without being told twice. Refusing the bare pin and naming
268
+ the tree once is the whole cross-workspace contract; never dispatch a
269
+ member into a run whose phase-0 pin refused.
270
+
271
+ **Check the merge gate against its spec, once the fast-forward has put the
272
+ ratified spec in front of you.** Where the workspace checks a ruleset spec
273
+ in, `.github/scripts/apply-ruleset.sh --check` compares it to the live gate
274
+ without writing anything (no spec checked in → nothing to run, skip it).
275
+ Three statuses and they are not interchangeable: **0** the gate is what the
276
+ tree says it is; **3** it is not — including the gate having been deleted
277
+ or renamed — and the diff it prints says how; **2** the question could not
278
+ be answered at all: no spec, no `gh`, a listing or read that failed
279
+ outright, or a read that succeeded but withheld `bypass_actors` because
280
+ the session lacks repository admin.
281
+
282
+ **3 does not stop the run and is not yours to fix** — reconciling is a
283
+ write to the gate protecting this repo, so it needs the maintainer.
284
+ Surface the diff and carry on. What it changes is what you may then claim:
285
+ every statement this run makes about which checks must pass before a merge
286
+ is sourced from the spec plus ADR 0007 and is true of the live gate only
287
+ while this check is green, so a 3 means saying "the gate requires X"
288
+ without naming the drift is a false claim, and a 2 means you never learned
289
+ either way. Measured 2026-09-23 (#1710): four contexts ADR 0007 had
290
+ selected were required by the spec and by nothing live, and the gap sat
291
+ there unnoticed because the only thing that ever read the live gate was a
292
+ person choosing to.
293
+
294
+ **Launch the cockpit.** On every phase-0 pass, not just the first:
295
+ `node ~/.fleet/bin/fleet-run board.mjs serve --open &` in the
296
+ background. It is a read-only mirror of `.fleet/ledger.md` + `gh` — you never
297
+ feed or update it, and it survives your own compaction. The launch is
298
+ idempotent per workspace when the running cockpit answers the identity
299
+ handshake: an already-served workspace's launch finds the running server
300
+ over HTTP, prints its URL, and exits 0 without starting a second one
301
+ (#1585) — nothing to skip. It opens nothing either: `--open` opens a tab
302
+ only from the launch that binds a port and starts the server (#1714), so a
303
+ re-shortlist leaves the board tab you already have alone. A second fleet
304
+ on another workspace collides with none of that: its own launch derives
305
+ that workspace's own port and binds it when free, or scans to the next
306
+ free port in its range when the derived one is already held by something
307
+ else — either way it gets its own board, just not always on the port its
308
+ hash predicts.
309
+
310
+ The spend panel reads this workspace's own `~/.omp/agent/sessions` tree
311
+ (#1716), and is pinned to whichever session first writes a transcript on this
312
+ cockpit's own watch (#1583/#1679): it will not follow a workspace that
313
+ already had another session's transcripts sitting there at launch. If the
314
+ panel is reading someone else's numbers, relaunch with `--spend-dir <path>`
315
+ naming this run's own session directory to override the heuristic outright —
316
+ `~/.omp/agent/sessions/<encoded-cwd>/<ISO>_<uuid>` (the directory, never
317
+ the `.jsonl` file of the same name beside it).
318
+
319
+ **Fold in every PR a prior run left open, before shortlisting.** A chore PR
320
+ carrying that run's own metrics, or ticket work whose review was deferred —
321
+ both are reviewable work no member otherwise picks up, because the Shortlist
322
+ holds ISSUES and nothing looks at inherited PRs. Queue each for review exactly as
323
+ ticket work: same review workflow, same fix-applier, same finisher. Measured
324
+ 2026-09-03 — #1222 arrived this way and its review found a defect its own PR
325
+ body called unreviewed, and #1237's review then caught two metrics rows the
326
+ controller had missed in its own close-out, so a chore PR is not exempt from
327
+ being wrong. Reviewing them next run is also what stops one pinning
328
+ `fleet-tick`'s backlog forever (#590): unreviewable AND uncounted is the state
329
+ that strands it.
330
+
331
+ 1. **Build the Shortlist** — `~/.fleet/bin/fleet-run shortlist.mjs`, then read
332
+ `.fleet/shortlist.json`. The script runs the cheap filters and nothing else
333
+ — no ticket body is read here, because a Pull reads one ticket in full at
334
+ the moment it admits it (ADR 0013 §1):
335
+
336
+ - **Candidate scan** — `candidates.mjs --require-label ready-for-agent`,
337
+ oldest-first, never re-ranked. Its row count is `scanned`, the supply.
338
+ - **Dependency scan**, `next-ticket` step 2, on each row's `d` array. Open
339
+ blocker → drop.
340
+ - **Live Exclusions** — a ticket whose ledger row reads `excluded ·
341
+ behind-pr:#M` or `excluded · behind-issue:#M` stays out while its premise
342
+ holds (phase 1, **Exclusion**).
343
+ - **In-flight check** — `inflight.sh <N>` per survivor. Exit 1 is taken, and
344
+ any other non-zero exit is a check that could not answer, which is never
345
+ free. Both drop the ticket, logged by number.
346
+
347
+ It writes the survivors, in order, to `.fleet/shortlist.json` —
348
+ `{scanned, shortlist: [{n, t}]}` — resolved against the git common dir
349
+ exactly as `ledger.mjs` resolves `.fleet/ledger.md`, so you, the tick and a
350
+ member in its own worktree all name one file. **Exit 0 is the file written,
351
+ an empty shortlist included** — the empty queue is an answer. **Exit 2 is a
352
+ refusal**: the scan, the ledger read or the write did not answer, and the
353
+ previous file stands untouched, because an empty file written then would
354
+ read as "no work". Never read 2 as empty.
355
+
356
+ Every probe fails CLOSED: an unreadable blocker counts as open, an
357
+ unreadable premise leaves its exclusion standing, an unanswered in-flight
358
+ check counts as taken. A ticket dropped wrongly waits one refresh; a ticket
359
+ admitted wrongly costs a Pull's full read at best and two members on one
360
+ ticket at worst.
361
+
362
+ **`--require-label ready-for-agent` mandatory, no fallback** — the script
363
+ fixes it, and you never run `candidates.mjs --allow-fallback` by hand to
364
+ widen the list: `ready-for-human` needs a human to brainstorm first and you
365
+ have no channel to one mid-flight.
366
+
367
+ `candidates.mjs`'s exit 3 reaches you as an empty shortlist with its to-spec
368
+ notice on stderr. **Exit 3 is not that empty queue, and never a reason to
369
+ widen the net.** It says the labeled query returned rows and the to-spec
370
+ filter took every one: what is queued is to-tickets' input rather than
371
+ claimable tickets, and a member handed one implements an entire spec as a
372
+ single ticket. Log it as
373
+ specs awaiting to-tickets, not as no work — and still do not pass
374
+ `--allow-fallback`, whose second pass is unfiltered and so reaches the
375
+ `ready-for-human` and untriaged work you have no channel for.
376
+ 2. **Refresh is the tick's from here on.** `fleet-tick.mjs` runs
377
+ `shortlist.mjs` itself when unclaimed entries fall below the implementer
378
+ cap, when the file is missing or empty, and when an `excluded` premise has
379
+ lifted, and prints `REFRESHED shortlist: <n> entries; <k> lifted`. Phase 0
380
+ runs it by hand once because a dead run's shortlist is stale by definition.
381
+
382
+ **No multi-select, no maintainer tick.** Selection and ordering are batched —
383
+ one scan, oldest first; admission never is. The invariant this replaces — one
384
+ human decision per batch of admissions, zero unilateral grabs — is retired
385
+ (ADR 0013): zero human decisions per admission, and every non-admission is a
386
+ label or a premise the maintainer can read.
387
+
388
+ ## Phase 1 — Pull: judge, then claim or relabel
389
+
390
+ Serial, main checkout, one Pull at a time. Never parallel, never inside a member —
391
+ concurrent `worktree add` and label writes race.
392
+
393
+ One free implementer slot is one Pull. The tick names the heads — `PULL #412
394
+ #415`, one per free slot — and each Pull runs this sequence on its head,
395
+ terminating in exactly one dispatch or an empty shortlist (ADR 0013 Decision 2):
396
+
397
+ 1. **Take the shortlist head** — the next `.fleet/shortlist.json` entry with no
398
+ `impl-` row and no `excluded` row whose premise still holds, which is the
399
+ ticket the tick's `PULL` row names.
400
+ 2. **In-flight check, again** — `~/.fleet/bin/fleet-run inflight.sh <N>`; any
401
+ hit = taken, drop it and take the next entry. The shortlist is as old as its
402
+ last refresh. It runs all three probes (PRs, remote heads, local
403
+ worktrees + branches) so a partial one cannot read as free. The PR probe is
404
+ two signals rather than a bare full-text match — GitHub's own closing-PR links
405
+ plus branch-segment matching — and both drop `MERGED` and `CLOSED`, so a
406
+ merged or abandoned PR the `gh pr list` window covers cannot hold a ticket
407
+ forever. A linked PR that window does *not* cover has no state to read: it
408
+ prints `?` and still counts as taken, merged or not.
409
+
410
+ **Exit 2 is not free** — the question went unanswered, so treat it as taken
411
+ and say which ticket it was in the log. A probe that could not look is
412
+ recorded rather than aborting the run, so exit 2 from one prints the same
413
+ JSON as 0 and 1 plus an `unknown[]` naming the probes that could not look:
414
+ read `unknown`, never `taken` alone, because exit 2 says `"taken": false`,
415
+ which summarizes `hits` and is not a claim the ticket is free. A hit outranks
416
+ an unknown — a payload can carry a non-empty `hits[]` and a non-empty
417
+ `unknown[]` at exit 1, which is taken. Four causes print nothing at all — a
418
+ bad argument, not inside a git repository, no such issue, a verdict that could
419
+ not be written — so never assume exit 2 parses.
420
+
421
+ **A free verdict is not evidence that nobody is editing the ticket's
422
+ target files.** All three probes ask whether a branch-shaped claim
423
+ exists — a PR, a remote head, a local branch, or a worktree — and
424
+ nothing else; work done directly against the shared checkout, by a
425
+ human or another agent session, stakes no branch-shaped claim and trips
426
+ none of them.
427
+ 3. **Read the ticket in full, once** — `gh issue view <N> --json title,body,comments,labels
428
+ --jq '.title, .body, ([.labels[].name]|join(",")), (.comments[]|.author.login + ": " + .body)'`.
429
+ One read answers every question the Pull asks. Record the ticket's real
430
+ brief — the `## Agent Brief` comment where one exists, otherwise the issue
431
+ body, which is where most tickets actually carry it (a controller probe found only 43/100 open
432
+ `ready-for-agent` issues have a separate Agent Brief comment; the rest,
433
+ this ticket included, carry the brief in the body) — plus its `Out of
434
+ scope` sequencing wherever that section is found. Then judge **decided?**
435
+ — never size.
436
+
437
+ **Still live?** A backlog ticket's claims rot. Before `decided?`, settle the
438
+ ticket's central claim against `origin/main` — never the working tree, never
439
+ the ticket's own line numbers, which drift. One `git show origin/main:<file>`
440
+ piped to `grep` does it for any ticket citing a construct, which is most of
441
+ them. **That read is fatal, not empty, when the path is untracked in
442
+ `origin/main`** — `git show origin/main:<path>` exits 128 saying the path
443
+ does not exist, and the file may still sit right there on disk, so it is a
444
+ probe that could not look rather than a clean tree. Fall back to
445
+ `git ls-tree origin/main -- <path>` (empty output at exit 0 = untracked)
446
+ before reading the failure as "unfixed". Already fixed → close it citing the
447
+ commit, do not claim it. Partly fixed → say which acceptance criteria the
448
+ tree already meets, and which the tree now **contradicts**.
449
+
450
+ **Grep for the ticket's ASKED-FOR CHANGE, not only its subject construct** —
451
+ the construct check passes on every stale pin ticket, because the construct
452
+ is what the pin is *about* and never went anywhere. So for a ticket asking
453
+ for a pin, test or assertion, grep the **test file** for the assertion it
454
+ wants; for one asking for exact wording, grep the **old** wording the ticket
455
+ quotes as wrong, never the new wording it proposes. A proposed replacement is
456
+ a suggestion the implementer is free to reword — an equivalent rewording
457
+ satisfies the ticket while failing a grep for its literal text — and the
458
+ quoted defect is the fact. Old string gone from `git show origin/main:<file>`
459
+ ⇒ the fix landed, and
460
+ `git log -S '<old string>' --oneline origin/main -- <file> | head -1` names
461
+ the commit that removed it; close citing that commit. Seconds either way,
462
+ and the construct half alone is the probe that could not look.
463
+ **No ancestry check on what that walk printed.** `origin/main` is where the
464
+ walk starts, so every commit it can print is reachable from `origin/main` by
465
+ construction, and `git merge-base --is-ancestor <sha> origin/main` is true
466
+ for all of them — true again when the sha *is* `origin/main`. A step that
467
+ cannot answer no is not evidence, and reads as evidence anyway.
468
+ **That check belongs one input over — a sha the TICKET quotes**, where it
469
+ can answer no: a rebase leaves the commit it orphaned a whole object, so
470
+ `git show` resolves it happily while nothing in `origin/main`'s history
471
+ reaches it, and a "fixed in `<sha>`" premise built on one describes a tree
472
+ that no longer exists. Separate its two non-zero answers before citing
473
+ either — exit 1 is the answer *not reachable*, while exit 128 with `Not a
474
+ valid object name` is a sha this clone does not have at all, a probe that
475
+ could not look rather than an orphan (measured: #640's comment cites
476
+ `35c0845` on a since-deleted branch, and 128 is what it exits here).
477
+
478
+ **Both halves of that command are load-bearing.** Drop the `origin/main`
479
+ argument and `git log -S` searches `HEAD`, contradicting the rule a paragraph
480
+ up — and the two searches fail differently there. On a checkout behind the
481
+ fix the prescribed **old**-string search names a *wrong* commit at exit 0,
482
+ the old string still being present in that tree: measured at #206's
483
+ `0dc39ef^`, `| head -1` names the rename `4fd2f73`, not the fix. It is the
484
+ **new**-string search the paragraph above forbids that prints nothing at exit
485
+ 0 there, indistinguishable from "the change never landed"; the old-string
486
+ search goes empty on a checkout that predates the old string's own arrival
487
+ at that path — behind that rename in #206's case, and with no rename in play
488
+ at all in this file's: measured at `647ae44^`, which already tracks this
489
+ path under this name, `git log -S 'ls-tree origin/main'` prints nothing at
490
+ exit 0.
491
+ Add `--reverse` and you get the *oldest* count-changing commit, which is the
492
+ file's last rename whenever the string predates one — measured on #206's old
493
+ wording, `--reverse` names `4fd2f73` ("move next-ticket and sizing-a-ticket
494
+ into the plugin"), a refactor that clears an ancestry gate exactly as
495
+ well as the real fix, while newest-first `| head -1` names `0dc39ef`, the
496
+ commit that actually did it.
497
+ (`--follow` fixes the rename half but is mutually destructive with
498
+ `--reverse`: the two together return empty at exit 0, and `--follow` takes
499
+ exactly one pathspec or exits 128.) So read the subject of whatever it names
500
+ before citing it in the close, and treat empty output as an answer you did
501
+ not get rather than a commit.
502
+
503
+ Measured, one run: #132's one-line remedy had shipped in `e7b11e6` ten days
504
+ earlier and #134's AC-2 asked for an exit code a later design (#64)
505
+ deliberately changed — neither commit carried a trailer back, so the tracker
506
+ showed both as open work. #132 cost a full claim, worktree and implementer
507
+ dispatch to learn this; #134 would have shipped a test asserting the opposite
508
+ of the shipped behaviour. The two probes that settled both took seconds.
509
+ **A ticket deferred from a review is a claim about a tree that has since
510
+ moved** — and the older the ticket, the more it has moved, so this bites
511
+ hardest at exactly the head of an oldest-first queue.
512
+
513
+ Measured again 2026-08-19: four stale in the 20 oldest, and the construct
514
+ probe caught **none** of the four. It **missed** #156 — the two pins and the
515
+ `contentWords()` extraction it asks for had all landed (`d016414`, `1abd6c8`)
516
+ while `overlap()`, the construct, sat right where the ticket said, so the
517
+ probe passed the ticket through as live work and it cost a claim, a worktree
518
+ and a dispatch. It **missed** #205, whose `d:` scan `candidates.test.mjs`
519
+ already pinned — `6d94451` and `43d6ac5` both added `.d` assertions, and the
520
+ ticket's own closing comment cites both. It **missed** #206, whose wording
521
+ defect `0dc39ef` had already fixed — by an **equivalent rewording**, not by
522
+ the literal string the ticket proposed, which appears nowhere in
523
+ `origin/main`; the ticket's **line number** had drifted too, `:95` → `:98`.
524
+ And #187 it could not read at all: that ticket's file is untracked in
525
+ `origin/main`, the fatal-not-empty case above.
526
+
527
+ **`staleness.mjs` runs that check for you, and answers in THREE values.**
528
+ `~/.fleet/bin/fleet-run staleness.mjs --path <path> --gone
529
+ '<string>'`, or `--present '<string>'`, once per claim the ticket makes.
530
+ It goes here and not in `shortlist.mjs` because choosing WHICH string
531
+ settles a ticket needs the ticket read, which the step above already did —
532
+ so the cost lands on the pulled ticket and never on the backlog.
533
+ `--gone` is a defect the fix must remove, the wording the ticket quotes as
534
+ wrong; `--present` is what the fix must add, the assertion a pin ticket asks
535
+ for. Give exactly one — the direction is not inferable from the string, and
536
+ the wrong one answers the opposite verdict with full confidence.
537
+
538
+ A needle that itself starts with `--` — #240's `--label ready-for-agent`
539
+ is one this backlog carries — needs the end-of-options separator: `--gone
540
+ -- '<string>'`/`--present -- '<string>'`. Given bare, with no `--`
541
+ immediately before it, the value guard still refuses it — `staleness:
542
+ --gone needs a value` — at exit 2, a could-not-check to admit and annotate,
543
+ not an invocation to retry.
544
+
545
+ | Exit | Verdict | What it does at the Pull |
546
+ |---|---|---|
547
+ | 0 | still reproduces | admit it |
548
+ | 1 | provably fixed | do not admit; close citing the payload's `commit` and `subject` |
549
+ | 2 | could not check | admit it, **and say the probe could not check** |
550
+
551
+ The third value is the one that has to survive. A probe that could not look
552
+ answers exactly like a probe that looked and found nothing, so folding it
553
+ into either neighbour retires live supply on a guess in one direction and
554
+ reports a defect as live on a spelling the tree stopped using in the other.
555
+ Exit 2 is also where every guard and every failed git call in that script
556
+ lands, so a probe that breaks keeps the ticket in the queue.
557
+
558
+ What it refuses to answer is the point of it. It reads `origin/main` and
559
+ nothing else — never the working tree, never anything on disk — so a path
560
+ this repo does not track is exit 2 rather than a clean read: that is #187's
561
+ case and the generated-artifact case together, `agent-test` being written
562
+ into a claimed worktree by `claim-ticket.sh`'s heredoc, which makes every
563
+ copy under `.worktrees/` a snapshot of whenever that worktree was claimed.
564
+ `fixed` is never read off the string's presence alone either: it carries the
565
+ commit `git log -S` names for that string at that path, reachable from
566
+ `origin/main` by construction since that is where the walk starts. A
567
+ `--gone` string absent from the file that ALSO never changed count there is
568
+ exit 2, not a fix — that is the positive control, and without it a typo in
569
+ the string closes a live ticket.
570
+
571
+ It does not run a reproduction. The general "is this still reproducible?"
572
+ oracle over the whole backlog is what #238 ruled out, and a reproduction run
573
+ without a positive and a negative control misattributes causes rather than
574
+ merely missing defects — the #230 check needed a purpose-built fixture plus
575
+ both. A ticket no single string settles is a `could not check`: admitted,
576
+ annotated in the dispatch prompt (phase 2), never quietly dropped.
577
+
578
+ **Decided?** Would two competent implementers, reading only this ticket, build
579
+ materially different things? "Material" by inventory, not feel:
580
+
581
+ | Left open | Verdict |
582
+ |---|---|
583
+ | architecture, API shape, schema, UX | **undecided** |
584
+ | new dependency, new seam | **undecided** |
585
+ | naming, file layout, ordering, test arrangement | decided — ignore |
586
+
587
+ Any undecided item → not decided. Name it; that name is the relabel comment's
588
+ missing decision or open fork. **Torn → surface, never guess**: relabel it
589
+ `ready-for-human` as a fork naming the open decision — the label is how a
590
+ Pull surfaces it to the maintainer. Opposite of
591
+ `sizing-a-ticket`'s *torn → take the heavier row*, deliberately — see that skill.
592
+
593
+ **This is a consumption gate**, priced for the seat where implementer
594
+ divergence costs a claim, a worktree and a dispatch; the filing-time
595
+ counterpart was repriced to *is the defect confirmed* and states its own bar
596
+ inline — see `docs/adr/0001-filing-label-bar-is-defect-confirmed.md`.
597
+
598
+ No sizing agent here. `sizing-a-ticket` picks the *process path*, and that is
599
+ phase 2's call, after the ticket is claimed.
600
+
601
+ **Class?** Second judgement off the same read, so it costs no extra tokens.
602
+ Stale docs, wrong comments, bad citations → `class=correction`; everything
603
+ else → `class=routine`. **Torn → correction**: a misjudged routine is a
604
+ missed saving, a misjudged correction runs the one class that demonstrably
605
+ ships new wrong claims.
606
+
607
+ **The class no longer selects a model tier** — the phase-2 guard fired on
608
+ 2026-08-16 and every class now dispatches at the session's tier. It still
609
+ earns its read: it selects the **correction-ticket discipline** phase 2
610
+ hands the implementer (settle every restated claim against the tree, keep
611
+ the diff to the ticket's stated size, no positional references, never a
612
+ count in prose, a settling command re-run and written inline for every
613
+ claim that goes into the commit or PR body, and literal text grepped with
614
+ `-F`, its zero trusted only after the same command, with the same flags,
615
+ finds a known match), it partitions
616
+ `docs/metrics/tier-outcomes.tsv`, and it is what any future tier
617
+ control would be drawn from. A row with no class is still `class=unknown`,
618
+ never a guess.
619
+
620
+ The correction exception was always a **precaution, not a measurement.**
621
+ references/correction-tickets.md records four tickets in one run each
622
+ shipping a *new* wrong claim, and blames the ticket's framing and
623
+ unasked-for prose — **not** implementer capability; it measures no tier at
624
+ all. That reasoning is why the discipline survives the tiering that used to
625
+ accompany it.
626
+
627
+ Record the class in the Pull's ledger row (step 7); phase 2 reads it for
628
+ the discipline, no longer for the tier.
629
+ 4. **Collision scan against open PRs and live branches** — the ticket is an
630
+ *un-implemented issue* with no diff, so infer its target files from the brief
631
+ (the paths it names) and compare them against each open PR's `gh pr diff <PR>
632
+ --name-only` **and** each live worktree's `git diff --name-only
633
+ origin/main...<branch>` (the branches `git worktree list` names) — a member
634
+ mid-work has a branch before it has a PR. `pr-overlap.mjs` is **PR-vs-PR
635
+ only** — it runs `gh pr diff` on *both* args and errors on an issue number,
636
+ so use it the way the merge bot does (PR vs PR), never on a ticket here.
637
+ Step 2 catches a ticket already taken, not one that *edits a file an open PR
638
+ edits*. Overlap → exclude it `behind-pr:#M`, next entry. The tracker cannot
639
+ express this, and it is what actually stalls a Pull's PR at merge.
640
+ 5. **Sequence check** — the brief's `Out of scope` names an open ticket this one
641
+ sequences after → exclude it `behind-issue:#M`, next entry. That lives in the
642
+ brief, is invisible to the dependency scan, and oldest-first order puts a
643
+ chain's members next to each other, where two consecutive numbers read as
644
+ two independent tickets.
645
+ 6. **Claim** — `~/.fleet/bin/fleet-run claim-ticket.sh <N> impl-<N> implementer
646
+ --apply` (below). Exit 2 → treat it as taken, next entry.
647
+ 7. **Row, then dispatch** — `ledger.mjs row <N> "impl-<N> · class=… [· tier=alt]"`,
648
+ then phase 2 at once: claim what you are about to dispatch;
649
+ dispatch what you have just claimed.
650
+
651
+ **The Pull table** — every verdict a Pull can reach, and the one thing each
652
+ does (ADR 0013 Decision 2 and 4):
653
+
654
+ | At the Pull | Action |
655
+ |---|---|
656
+ | in-flight hit, or an in-flight check that could not answer | drop, next entry |
657
+ | no longer labelled `ready-for-agent` | drop, next entry |
658
+ | `staleness.mjs` exit 1 — provably fixed | close citing the commit, next entry |
659
+ | brief names no *what* | relabel `needs-triage`, next entry |
660
+ | genuine fork — options named, none ruled | relabel `ready-for-human`, next entry |
661
+ | needs human hands — external access, manual testing, judgment during the work | relabel `ready-for-human`, next entry |
662
+ | target files collide with an open PR or a live branch | exclude `behind-pr:#M`, next entry |
663
+ | `Out of scope` sequences it after an open ticket | exclude `behind-issue:#M`, next entry |
664
+ | `claim-ticket.sh` exit 2 | taken, next entry |
665
+ | decided, live, free, claimed | row, then dispatch (phase 2) |
666
+
667
+ **The shortlist runs out → run `shortlist.mjs` once and Pull again; still
668
+ empty → hold the slot idle until the next refresh trigger.** Within a turn,
669
+ Pull from the current list first and refresh second — a refresh never delays a
670
+ dispatch.
671
+
672
+ **A Pull never re-admits a ticket already relabelled.** The shortlist file can
673
+ be older than a relabel — this run's own Pulls, or a demotion in phase 3 — so
674
+ read the ticket's labels in step 3's full read (`--json
675
+ title,body,comments,labels`) and drop it when `ready-for-agent` is gone. A Pull
676
+ that trusted a list built before the relabel landed would hand a ticket the
677
+ fleet has already judged unimplementable straight to the next member.
678
+
679
+ **Relabel by cause.** An unclaimed ticket is yours to reclassify at the Pull —
680
+ three causes, two labels: `ready-for-human` for hands or a fork;
681
+ `needs-triage` for a brief that names no *what*.
682
+ `gh issue edit <N> --remove-label ready-for-agent --add-label <label>` (no
683
+ `in-progress` to drop — it was never claimed), preceded by exactly one comment:
684
+
685
+ - `needs-triage`:
686
+
687
+ > *Relabelled by the fleet controller.* Pulled for implementation and
688
+ > returned: the brief does not decide what to build. Missing decision: <one
689
+ > line>. Returning to /triage; `ready-for-agent` restored once decided.
690
+
691
+ - `ready-for-human` (fork):
692
+
693
+ > *Relabelled by the fleet controller.* Pulled for implementation and
694
+ > returned: the brief leaves a decision open. Open fork: <options, verbatim
695
+ > from the brief>.
696
+
697
+ - `ready-for-human` (hands):
698
+
699
+ > *Relabelled by the fleet controller.* Pulled for implementation and
700
+ > returned: needs human hands — <external access | manual testing |
701
+ > judgment during the work>: <one line>.
702
+
703
+ Neither label invokes anything: `/triage` is maintainer-run, and both labels
704
+ only stop the ticket costing a read per scan. These comments are the only
705
+ writes the fleet makes to a ticket it did not claim.
706
+
707
+ **Exclusion is a ticket row with a premise.** `ledger.mjs row <N> "excluded ·
708
+ behind-pr:#M"` or `ledger.mjs row <N> "excluded · behind-issue:#M"` — `#M` is
709
+ the open PR, or the branch name until its PR exists, or the issue this ticket
710
+ sequences after. No new ledger section. `shortlist.mjs` probes every premise at
711
+ each refresh — MERGED or CLOSED lifts a `behind-pr`, CLOSED lifts a
712
+ `behind-issue` — and a lifted ticket re-enters the shortlist in its own
713
+ oldest-first slot; its row is rewritten to `impl-<N> …` when it is pulled,
714
+ because `row` replaces the whole line.
715
+
716
+ **Claiming.** `~/.fleet/bin/fleet-run claim-ticket.sh <N> impl-<N> implementer --apply` does
717
+ the label, worktree, branch, frozen install, lockfile-clean assertion, and the
718
+ isolation runner in one serial pass. The two arguments are always that literal
719
+ pair — `impl-<N>` as `<slug>`, `implementer` as `<type>` — so the claim is
720
+ branch `implementer/<N>-impl-<N>`, worktree `.worktrees/<N>-impl-<N>`. Never
721
+ read them off `git branch -r` or `git worktree list`: human branches on origin
722
+ (`fix/…`, `docs/…`) have another shape, and the script takes both arguments as
723
+ free text, so a pair copied from one claims under that shape at exit 0.
724
+
725
+ **Infer `<install>` — never default to `npm install`.** A lockfile-mutating
726
+ install in a throwaway worktree corrupts it for everyone; the script derives the
727
+ frozen form from the lockfile and refuses to guess.
728
+
729
+ **Materialize the isolation envelope as a file, not a briefing.** The runner is
730
+ tracked at the repo root since #55, so every checkout has one; it derives its
731
+ ports from the worktree's own `<N>-slug` directory name (so collisions stay
732
+ impossible) and materializes the current runner from the one emitter rather than
733
+ carrying a copy of it. Brief members with `./agent-test
734
+ <file-or-dir>` and nothing else — anyone who finds the worktree finds the
735
+ runner, including grandchildren you never dispatched. A directory works too and
736
+ expands to the test files under it; one holding none refuses rather than passing
737
+ vacuously, so a mistyped file or directory path cannot come back green. See
738
+ references/isolation.md.
739
+
740
+ **A reused worktree may lack the runner** — no longer here, and still can
741
+ elsewhere. `claim-ticket.sh` used to write `agent-test` only when it claimed a
742
+ *fresh* worktree, so a worktree carried over from a prior run, or an already-open
743
+ PR's worktree you sent a rebaser/resolver into, had no `./agent-test` and the
744
+ member stalled on a missing script (observed with a rebase-resolver in a
745
+ prior-run worktree). #55 tracked the runner, so any worktree checked out from
746
+ `origin/main` now carries it. A tree that is NOT a checkout — a `git archive`
747
+ snapshot, a `cp -R` subset — still has whatever was copied into it, and a repo
748
+ that tracks no runner never had one: there, tell the member the runner is absent
749
+ and to run docker-free suites directly (`npx vitest run --config
750
+ vitest.ci.config.ts <file>` — the CI unit config has no `globalSetup`, so there
751
+ is no stack to collide on).
752
+
753
+ **A reused worktree may also be on the wrong COMMIT.** `git worktree add <path>
754
+ <branch>` checks out the existing LOCAL branch and never consults the remote, so
755
+ a branch a previous run left behind wins over the rebased `origin/` ref that is
756
+ actually the PR. Measured in a scratch repo (git 2.50.1): with the branch rebased
757
+ on the remote and a stale local ref standing, `git worktree add <path> <branch>`
758
+ checked out the stale commit and printed `HEAD is now at <stale-sha> <subject>` —
759
+ the same subject the PR head carries, because a rebase preserves it. Neither
760
+ commit was an ancestor of the other, so *behind* is the wrong model; it is a
761
+ fork. Every other signal reads normal too: `git worktree list` shows the worktree
762
+ present on the expected branch, and the tree is clean. `claim-ticket.sh` never
763
+ touches this path — it claims only fresh tickets, and builds those from
764
+ `origin/main`.
765
+
766
+ **The two reuse failures are not symmetric.** A missing runner fails LOUDLY: the
767
+ member stalls on a script that is not there. A stale base fails SILENTLY and
768
+ produces confident wrong output — a review cut its immutable snapshot at the
769
+ stale commit and a fix-applier was dispatched into it, halted only before a push
770
+ that would have been a non-fast-forward.
771
+
772
+ So, when you re-create a worktree for an already-open PR:
773
+
774
+ - **Create it detached from the remote ref**, never from the bare branch name:
775
+ `git worktree add --detach <path> origin/<branch>`. Same scratch repo, same
776
+ moment: this landed on the remote's commit. It removes the mechanism rather
777
+ than catching it, and leaves no local ref for the next run to inherit.
778
+ - **Then verify against the branch REF, and refuse on mismatch.** Compare
779
+ `git -C <path> rev-parse HEAD` against
780
+ `git ls-remote origin refs/heads/<branch> | cut -f1` — the ref itself, which
781
+ is what the PR's head actually is, and **never `git rev-parse
782
+ origin/<branch>`**, which is the ref the worktree was just cut from and so
783
+ agrees with it by construction. Unequal → dispatch nothing into that
784
+ worktree, and report it naming BOTH commits, since their subjects will not
785
+ tell them apart. **An empty read is neither equal nor a mismatch**: the read
786
+ failed, or that head branch is not on `origin` at all (a fork PR, where the
787
+ creation form above cannot work either), so report the ref as unreadable
788
+ rather than the worktree as wrong — the same hole `[ -n "$pre" ]` closes on
789
+ the way into `run-merge-bot.md`'s step-1 poll.
790
+ - **Read `gh pr view <N> --json headRefOid -q .headRefOid` here too, and
791
+ record it — it is NOT the gate.** A `headRefOid` that disagrees with the ref
792
+ is the PR-object desync `run-merge-bot.md`'s step 1 says needs a controller,
793
+ so it is a fact to carry into that decision, never the operand this refusal
794
+ turns on.
795
+
796
+ **Why the ref and not `headRefOid`: during the PR object's lag both operands go
797
+ stale in the SAME direction, so that compare fails OPEN as readily as it fails
798
+ closed.** The PR object spends the lag sitting on the PRE-rebase sha — cleared
799
+ on re-poll attempt 24 (~2 min) in one merge pass and attempt 14 (~84s) in the next,
800
+ both after `gh pr update-branch --rebase` returned `rc=0`, measured in
801
+ `run-merge-bot.md`'s step 1 — and that is the very commit a clone which has not
802
+ fetched since the rebase still has `origin/<branch>` pointing at. So the false
803
+ REFUSAL (worktree current, PR object behind) is only half of it: cut the
804
+ worktree from the stale remote-tracking ref and both sides read the superseded
805
+ sha, the check reads EQUAL, and the dispatch lands on exactly the commit this
806
+ paragraph exists to catch. Measured in a scratch repo (git 2.50.1): with the
807
+ branch rebased onto an advanced `main`, force-pushed, and the clone not fetched
808
+ since, `git worktree add --detach <path> origin/<branch>` landed on the
809
+ pre-rebase `c774756` and printed its subject unchanged by the rebase, while
810
+ `git ls-remote origin refs/heads/<branch>` read the true tip `62ba798` from
811
+ that same unfetched clone. **Re-reading `headRefOid` on a settle window does
812
+ not reach that half at all** — it fires only where the two disagree — which is
813
+ why the operand changes here rather than the verdict gaining a window.
814
+
815
+ **A mismatch is usually one `git fetch origin` old, so `git worktree remove
816
+ --force <path>` first, then fetch and re-create once before reporting it.**
817
+ `git worktree add --detach <path> origin/<branch>` resolves the LOCAL
818
+ remote-tracking ref (measured above), so the ordinary cause is this clone's
819
+ own staleness, and re-creating after a fetch costs seconds where the refusal
820
+ costs a dispatch. **Bounded at one retry**: still unequal after the fetch →
821
+ refuse and report, because the second reading is a push that landed while
822
+ you worked, or a ref this clone cannot resolve, and neither gets better with
823
+ more waiting.
824
+
825
+ `review-core.mjs` refuses a snapshot whose head is not the branch ref's, so the
826
+ review path is backstopped — except when the operand comes back
827
+ empty, which skips the compare rather than refusing on it. A same-repo PR
828
+ still reads `refs/heads/<branch>` first and falls back to
829
+ `refs/pull/<number>/head` only when that comes back empty; a cross-repo PR (a
830
+ fork) skips the branch-ref read entirely and goes straight to the pull ref,
831
+ because a fork's branch NAME can collide with an unrelated branch the base
832
+ repo already carries under that name (#1616) — so a fork PR now gets this
833
+ operand populated in the ordinary case, and the skip is rare rather than the
834
+ norm for forks. Its run log names the skip: `head ref (absent): head check
835
+ SKIPPED`. A worktree you hand to an agent directly is not backstopped at all.
836
+ Verify here anyway. **That backstop now compares against the same ref this
837
+ bullet does** — #1513 moved its operand off `headRefOid` for the reason
838
+ above — so it is a second
839
+ chance to notice a stale snapshot on the one path it covers, never a reason
840
+ to skip the ref compare here.
841
+
842
+ ## Phase 2 — dispatch the Pull's implementer
843
+
844
+ **A Pull is one claim followed by one dispatch of a new member under a name no
845
+ member has held; nothing holds a queue.** The implementer cap is the fleet's
846
+ own accounting rather than anything the runtime enforces, and the member is
847
+ fresh and never a wake of one that already ran. Admission is per slot and
848
+ never batched, so there is nothing to hand a freed slot its next ticket but
849
+ the next Pull.
850
+
851
+ a Pull dispatches its member with one more `task` call — definition `fleet-implementer`, or `fleet-implementer-alt` on every 5th Pull; name `impl-<N>`; in the background, so its report arrives on its own.
852
+
853
+ **No workpool, and no kernel-resident handle.** A pool's only refill virtue —
854
+ handing a queued item to a freed worker without a controller turn — is exactly
855
+ what a Pull forbids, and its completions never arrive per member. `eval`'s
856
+ `agent()` is not the omp call either: a kernel-resident handle dies with the
857
+ kernel and needs a `wait`, while a `task` job is process-level and its report
858
+ auto-delivers on its own, like every other member's.
859
+
860
+ **No per-call tier or effort anywhere on this path**: tier stays the agent
861
+ definition's own frontmatter (ADR 0005), whichever of the two definitions the
862
+ Pull names, and a member's Resolved tier stays readable from its transcript.
863
+
864
+ **Claim what you are about to dispatch; dispatch what you have just claimed.**
865
+ Phase 1 makes the claim, serially in the main checkout — its rule is measured —
866
+ and the dispatch follows it at once. A claim that runs ahead of its dispatch is
867
+ a worktree, a branch and an `in-progress` label with no member behind them,
868
+ released by the end-of-run sweep rather than by a member that did the work.
869
+
870
+ **Record the dispatch before you make it.** `ledger.mjs row` wrote the row at
871
+ the Pull's step 7; `~/.fleet/bin/fleet-run ledger.mjs dispatch <N> impl-<N>`
872
+ then marks `impl-<N>` live on it and in `## Dispatched`, and the call follows.
873
+ Live implementers are the `impl-` tokens with no `=<outcome>` — the tick reads
874
+ that count off the ledger, and nobody states it. `dispatch` refuses once the
875
+ run is draining: drain stops supply.
876
+
877
+ **The prompt carries only what varies.** Everything shared — the
878
+ unattended-member block, the `edit`/`read` absolute-path rule (#1727), the
879
+ issue re-read and re-derive backstop, commit incrementally, no `git stash`, the
880
+ shared `eval` kernel (#1447), enumerate-and-declare, sizing and the PR steps —
881
+ is the body of `agents/fleet-implementer.agent.md`, byte-identical in
882
+ `agents/fleet-implementer-alt.agent.md`, and each harness injects it as the
883
+ member's system prompt. Never re-paste it. The prompt fills that body's
884
+ placeholders — the ticket number, the worktree abs path and branch
885
+ (`<abs-path>`, `<branch>`), the scratch path `<scratch>/impl-<N>/`, and the
886
+ distilled brief (`<distilled brief>`): the title plus the `## Agent Brief`
887
+ comment or the issue body, whichever carries the brief, and its `Out of
888
+ scope`, pasted verbatim from the Pull's own read. Beyond those it carries only
889
+ the lines **Rules that fail silently** above say every dispatch prompt
890
+ carries — the report is a message, reports are not acknowledged, the suite
891
+ runs in the foreground — the class's correction-ticket discipline when
892
+ `class=correction`, and a `staleness.mjs` **could not check** verdict with its
893
+ reason when the Pull got one, so the member's own re-derive step knows the
894
+ controller's probe could not look.
895
+
896
+ **The prompt pastes the Pull's own read of the ticket rather than telling the
897
+ member to re-fetch it, and this still costs one `gh issue view` per ticket,
898
+ never one per member.** The fresh-context design's isolation rationale — "every
899
+ implementer re-reads its Agent Brief... from scratch"
900
+ (`docs/specs/2026-07-22-run-team-agent-fleet-design.md:178-179`) — is about a member
901
+ never inheriting another ticket's context, not about where the bytes come from.
902
+ Pasting the Pull's own read into the prompt keeps that: the member still gets the
903
+ brief verbatim and re-derives nothing from a sibling. What it drops is the
904
+ unconditional re-fetch of an issue the controller already has open, on every
905
+ dispatch — the fetch the agent body still carries is the backstop for a brief
906
+ that turns out to be insufficient, not the default path.
907
+
908
+ **A member settling with nothing is not, by itself, a bail.** Each member's
909
+ outcome arrives as its own job status. Settle (CONTEXT.md § Coordination) is
910
+ three states on omp — `completed`, `failed`, `cancelled` — and reading
911
+ `failed`/`cancelled` the same as a `completed` turn that had nothing to report
912
+ is the exact collapse this line blocks: a member that died never chose to bail,
913
+ so demoting its ticket on its silence demotes a ticket its member never got the
914
+ chance to judge. Confirm death first, exactly as the Member-killed row does
915
+ (Failure handling, below) — its mtime discriminator, never silence alone.
916
+ **Only an explicit bail report — the member itself naming the cause — reaches
917
+ Implementer bails before implementing** (phase 3, below); a died or
918
+ merely-quiet member's silence never does. A confirmed-dead member recovers
919
+ exactly as the Member-killed row says — new member, new name, the SAME ticket —
920
+ never a demotion.
921
+
922
+ **Dispatch every implementer as `agent: "fleet-implementer"`, and still
923
+ omit `model` on the `task` call, whatever the class.** The tier now lives in that
924
+ definition's frontmatter (`agents/fleet-implementer.agent.md`), which is what an
925
+ omitted `model` takes first — the session's tier applies only when the definition
926
+ names none, and a member dispatched with `model` set does not get the declared
927
+ tier back. Omitting `model` is therefore still the mechanism; what changed is
928
+ that the tier it resolves to is now declared and pinned rather than inherited by
929
+ accident. Keep `name: impl-<N>`: the name is what makes a member, and both the
930
+ spend classifier and `member-outcomes.mjs` read it.
931
+
932
+ **After every Pull's dispatch, run the tier check — a scripted step, never a
933
+ prose reminder.** `~/.fleet/bin/fleet-run tier-check.mjs --batch <path-to-batch.json>`
934
+ judges the implementer just dispatched on the ledger's terms. The definition it
935
+ should have run under comes off its ticket row's `tier=` token: none means
936
+ `fleet-implementer`, `tier=<x>` means `fleet-implementer-<x>` (`tier=alt` →
937
+ `fleet-implementer-alt`). It fails the member two ways, one line each —
938
+ `member: dispatched <agent>, expected <definition>` when its transcript says
939
+ it was dispatched as anything else (a generic `task` dispatch fails even when
940
+ its model happens to match), and `member: declared <m>/<l> resolved <m>/<l>`
941
+ when the harness resolved a different model or level than that definition
942
+ declares. The verdict lands on the ledger either way, written by the check
943
+ itself: exit 0 appends `tier-ok=impl-<N>:<definition>` to the row, once
944
+ however often it runs; exit 1 runs `ledger.mjs settle impl-<N> tier-mismatch`
945
+ — or, for a member already settled another way, which `settle` will not
946
+ re-settle, appends `tier-mismatch=impl-<N>:<definition>` instead.
947
+
948
+ **The tick holds the next Pull until that verdict exists.** Dispatching the
949
+ next member on top of an unchecked or mismatched dispatch multiplies whatever
950
+ silently degraded. The tick prints `HOLD (tier unchecked impl-<N>)` for the
951
+ newest `impl-` member of a ticket whose row carries neither verdict, whether
952
+ that member is still running or already settled `bailed`, `killed` or
953
+ `released`, and `HOLD (tier mismatch impl-<N>)` for a mismatched one. Only the
954
+ newest member counts, so a replacement (`impl-<N>-b`) is what clears a
955
+ mismatch — and is then owed its own check. The tick never reads a
956
+ transcript: clear an unchecked hold by running the check on that member with
957
+ `session`, which works after it has settled too, because its
958
+ `<session>/<member>.jsonl` is written at dispatch. Clear a mismatch by fixing
959
+ the definition or the dispatch and dispatching the replacement at the right
960
+ tier.
961
+
962
+ **The batch file is a JSON array, one entry per dispatched member** — under
963
+ Pull, a batch of one, the member just dispatched: `{member, session}`.
964
+ `member` is the AgentId the dispatch returns (`impl-<N>`). `session` is the
965
+ SAME session directory `member-outcomes.mjs`/`board.mjs` are already handed
966
+ for this run; the check reads the member's own `<session>/<member>.jsonl`
967
+ directly, so a member with no assistant turn yet still resolves off its
968
+ dispatch-time record. A caller already holding the exact transcript path may
969
+ give `transcript` instead. Either one is required: the agent type an
970
+ implementer was dispatched as lives only in its transcript. `resolvedModel`
971
+ **and** `resolvedThinkingLevel` together — the dispatch's own job record —
972
+ may ride beside it and are preferred for the model and level. An `impl-`
973
+ entry carries no `agentFile`: its definition is the row's, never the
974
+ caller's. `transcript`/`session` resolve relative to `--repo` (defaults to
975
+ the plugin's own root), and the check reads and writes the run's own ledger
976
+ unless `--ledger` names another.
977
+
978
+ **The declaration is `model: "@<role>:<level>"` — a fleet tier route, never
979
+ a vendor id.** `@slow`, `@task`, `@smol` resolve through the operator's
980
+ `modelRoles`, so an install with no Anthropic model still runs the fleet
981
+ at whatever each role points at; the explicit `:<level>` suffix wins over
982
+ the role's baked one, and the tier check judges a member against the
983
+ role's own target (`modelRoles.<role>`), never a model family (ADR 0011,
984
+ ADR 0014).
985
+
986
+ Before the run's first dispatch run `~/.fleet/bin/fleet-run tier-roles.mjs
987
+ --check`; exit 1 names every definition whose `model:` is not a route,
988
+ every unset `modelRoles.<role>` a definition needs, and every
989
+ `task.agentModelOverrides` entry that would shadow a fleet definition,
990
+ prints the exact remedy, and **stops the run** before any member is
991
+ dispatched — the fleet reads that config and never writes it (ADR 0003).
992
+
993
+ **Every 5th Pull by ledger count goes at the alternate tier.** Count the `impl-`
994
+ rows in `.fleet/ledger.md` at Pull time; the Pull that creates row 5, 10, 15 …
995
+ dispatches `agent: "fleet-implementer-alt"` and records
996
+ `tier=alt` in the row, and a replacement inherits the row's tier. The
997
+ assignment rolls to the next Pull when the pulled ticket is `class=correction`
998
+ or another open ticket sequences after it — a ticket the rest of the run
999
+ depends on. Do not tell the member it is a control: a member that
1000
+ knows it is being measured is not measuring the same thing.
1001
+
1002
+ **Count the rate against the ledger, because a Pull is the dispatch unit.** One
1003
+ Pull is one member, so a rate counted per Pull is a rate counted per member —
1004
+ one implementer in five, however the Pulls fall across the run — and the
1005
+ ledger, not your memory, is what still holds the count after a compaction.
1006
+
1007
+ **Do not label it anywhere — the dispatch record already carries it.** The
1008
+ pairing is a query over `docs/metrics/member-outcomes.tsv` (the exact awk sits
1009
+ in that file's header): a `session` that ran BOTH implementer definitions at
1010
+ DIFFERENT `model`s — one member whose `subagent_type` is
1011
+ `fleet-implementer-alt`, another whose is `fleet-implementer`. That column is
1012
+ the record of what each member was dispatched AS, scraped like every other
1013
+ column, so it survives the file's regeneration and mislabels no historical row
1014
+ — a pre-rule session carries no such dispatch to find. A hand-set column would
1015
+ fail both of those tests, and one derived against today's declared tiers would
1016
+ mislabel every historical row.
1017
+
1018
+ **The query counts DELIBERATE pairs, and that is the whole of #1066.** The
1019
+ rule this replaces asked only for a `session`+`role` carrying more than one
1020
+ distinct `model`, which any session that happened to stage a routine ticket
1021
+ beside a correction one satisfies. Measured 2026-09-12 on one corpus: 198
1022
+ keys as that query is literally written, 35 sessions across 21 `run_date`s
1023
+ once restricted to implementers, against 17 real pairs across 8 — so the gate
1024
+ below read itself past its floor on sessions where nothing had been
1025
+ controlled. Dispatch alone is not enough either: both arms must actually have
1026
+ RUN different models, because a deliberate alt dispatch whose two arms resolve
1027
+ to the same model (a `modelRoles` override, measured on omp 2026-09-12)
1028
+ controls nothing.
1029
+
1030
+ **Why one in five within the run, not a week of one tier then a week of the other:**
1031
+ tier would then be confounded with calendar date and therefore with prompt
1032
+ evolution, which is exactly the state #864 documents and the reason the rows
1033
+ already on disk cannot answer the question they were collected for.
1034
+
1035
+ **`class=routine` → `sonnet` was REVERTED on 2026-08-16, by the guard below
1036
+ firing.** Both halves were met on the accumulated `docs/metrics/tier-outcomes.tsv`:
1037
+ the floor (8 `class=routine` PRs spanning 3 distinct `run_date`s) and the trigger
1038
+ (2 rows carrying `closed_own_ticket` `no` — PR #452, which regressed the exact
1039
+ defect its ticket existed to remove, and PR #466, which emitted invalid JSON in
1040
+ the very payload its three tickets existed to make truthful). Per the guard's own
1041
+ wording this reverts **`class=routine`**, never the rule wholesale: the Pull still
1042
+ records the class, it still governs the correction-ticket discipline, and it is
1043
+ still what a future control would be drawn from.
1044
+
1045
+ **Read the counter-evidence before restoring it.** Recount from the file before
1046
+ citing it — these figures are a snapshot, not a live count, and a doc-only
1047
+ append lands a row without touching this paragraph. **As of 2026-08-28, 103
1048
+ rows:** the file holds 66 `class=routine` PRs across 14 distinct `run_date`s,
1049
+ so the floor is long since met, and 6 of them carry `closed_own_ticket` `no`,
1050
+ so the trigger is met too. **Firing changes nothing: the action is "revert
1051
+ `class=routine` to top tier" and that revert already happened on 2026-08-16.**
1052
+ The guard is in its fired state and has no further move; the live question is
1053
+ the opposite one, restoring a cheaper tier, which this guard does not decide
1054
+ and which no row on file settles.
1055
+
1056
+ The raw split still favours the top tier — 3 failures in 11 `routine`/`sonnet`
1057
+ rows against 3 in 55 `routine`/`opus`. **Do not read that as a tier result.**
1058
+ Tier remains largely confounded with calendar date and therefore with prompt
1059
+ evolution: 8 of the 11 `sonnet` rows fall on 2026-08-13 to 08-17, before the
1060
+ window in which 54 of the 55 `opus` rows were run, and the dispatch prompts
1061
+ gained rules throughout. The confound is **weakened, not resolved.** Three
1062
+ `sonnet` rows now break it rather than one — **#714** (2026-08-20, a
1063
+ maintainer-authorized deliberate control) and **#750** and **#751**
1064
+ (2026-08-21) — all three run against prompts of the same vintage as the `opus`
1065
+ rows, and **all three passed**, which is the direction opposite the raw split.
1066
+ Three is still not a result. **What replaces this argument going forward is the
1067
+ within-run pairing above**: one implementer in five at the alternate tier makes
1068
+ tier orthogonal to date by construction, so the question stops depending on
1069
+ whichever rows history happened to leave. **Orthogonal to date, and to nothing
1070
+ else** — the alternate member is whichever ticket the 5th Pull draws, rolling
1071
+ past every correction and every ticket another open one sequences after, while
1072
+ the top tier absorbs all of those, so the pairing trades the calendar confound
1073
+ for a difficulty one that runs in a known direction. That is why the four covariates
1074
+ exist: condition a pair comparison on `sizing`/`profile`/`loc`/`files` before
1075
+ reading it as a tier result, never on the raw split.
1076
+
1077
+ `minted_false_claim` **discriminates and no longer reads "always yes"** — 20 of
1078
+ the 66 `routine` rows carry `no`, 18 at `opus` and 2 at `sonnet` (#714, #750).
1079
+ Read it as a property of the TICKET before the tier: a pure code simplification
1080
+ need not add prose, while a correction ticket adds prose by construction. The
1081
+ honest summary is unchanged and is the reason this paragraph exists: the guard
1082
+ fired on the criterion the maintainer chose in advance, not on a demonstration
1083
+ that the cheaper tier is worse.
1084
+
1085
+ **No class recorded → record `class=unknown`, never a guess.** Since the revert
1086
+ every class dispatches the same way, so a lost class no longer misprices a
1087
+ member — but it still costs the **correction-ticket discipline**, which phase 2
1088
+ selects on the class and which is the half that caught real defects. Every path
1089
+ that loses it lands here — a compaction, a Pull whose read did not survive
1090
+ one, a killed member replaced from inherited state. Writing the gap down is what makes it visible; re-read the issue to
1091
+ recover the class when a correction's discipline is worth one `gh issue view`.
1092
+ **Never infer the class from the tier** — that inference is what the revert
1093
+ removed, and a future control would break it again.
1094
+
1095
+ Carry the class in the ticket's ledger row, written before dispatch like every
1096
+ other field:
1097
+
1098
+ ```
1099
+ ledger.mjs row <N> "impl-<N> · class=routine"
1100
+ ledger.mjs row <N> "impl-<N> · class=correction"
1101
+ ledger.mjs row <N> "impl-<N> · class=unknown"
1102
+ ```
1103
+
1104
+ `row` **replaces the whole line**, it does not append. Re-dispatching over a row
1105
+ that already carries `KILLED`, `ports=` or `→ PR#` must repeat those tokens or
1106
+ they are gone, with only `rewrote row #N` on stderr to say so. Recover a class
1107
+ after a compaction with `ledger.mjs read` — `class=` is a raw-row field, and the
1108
+ cockpit does not parse or surface it.
1109
+
1110
+ `ledger.mjs read` is safe on a pipe as well as a redirect: its payload used to
1111
+ be abandoned at the pipe buffer and still exit 0, which is what left `board.mjs`
1112
+ reporting `ledger read parse failed` and serving a blind cockpit for a whole run
1113
+ (#246). Every use above is a recovery path, so a payload that arrives short
1114
+ lands exactly where a lost class or a settled `ruled:` is unrecoverable — which
1115
+ is why the script's own suite pins that `read`, `row`, `filed` and `ruled` each
1116
+ reach a pipe whole.
1117
+
1118
+ `check` reaches a pipe whole at both of its exits too. Its ALREADY FILED exit
1119
+ sits mid-branch, where falling through would run the near-miss ranking and the
1120
+ tracker search that exit exists to skip — so `check`'s branch is a function now,
1121
+ where `process.exitCode` carries the code and a `return` is what skips them
1122
+ (#808). No payload this script prints is abandoned to `process.exit()` any more,
1123
+ and the suite drives both of `check`'s arms through a pipe on a payload the
1124
+ ledger sizes rather than argv. So trust that payload — and read `verdict`,
1125
+ because a searched-and-clean tracker and one that was never read share exit 0.
1126
+
1127
+ The consumer side raised its cliff rather than removing it. `board.mjs` reads
1128
+ `ledger.mjs read` with an explicit `maxBuffer`, so a payload past node's
1129
+ default is carried rather than killed mid-flight and reported as an
1130
+ unreachable tool — which is how the blind cockpit came back at HTTP 200 even
1131
+ after the pipe cut was gone (#807). That cap is deliberately bounded, so a
1132
+ payload past it lands in the same blind cockpit — and so does a ledger that
1133
+ cannot be read at all, at any size. The read fails open to an empty ledger, and
1134
+ `board.json`'s `ledgerState` field now distinguishes a read that failed or
1135
+ didn't parse from one that succeeded (`unread`/`unparsed`/`read`, #816) —
1136
+ `spend` in the same payload carries its own error the same way (#874). Zeroes
1137
+ on the cockpit are not yet proof the pipeline is idle.
1138
+
1139
+ **Guard: accumulate per PR, never conclude inside one run.** The unit is the PR —
1140
+ supply is one Pull per free slot, so there are no implementer batches. **Append one row to
1141
+ `docs/metrics/tier-outcomes.tsv` when you rule each PR's review, with
1142
+ `~/.fleet/bin/fleet-run tier-outcomes.mjs append <pr> --class <class> --closed-own-ticket yes|no --minted-false-claim yes|no --note "<text>"`,
1143
+ never by hand** (that file's header carries the column meanings). The script
1144
+ fills `run_date`, `pr`, `ticket` and `tier` itself — `tier` from what actually
1145
+ ran, off the implementer's `tier-ok=` ledger verdict or else its one
1146
+ member-outcomes row, and BLANK with a WARNING naming why when neither settles
1147
+ it; never type a tier in over that. A PR that already has a row is left
1148
+ untouched, so re-running it is safe. That append is the whole duty; the guard
1149
+ fires on the accumulated file, across runs, not on the run in front of you.
1150
+
1151
+ The row's last four fields are the ticket's difficulty, and they are what lets a
1152
+ tier comparison condition on the thing that swamps it. `sizing` is the
1153
+ **member's** own `light`/`heavy` verdict from its phase-2 `sizing-a-ticket`
1154
+ run, read back off the PR body's `Sizing:` line (`gh pr view <pr> --json body`),
1155
+ which names the signal the verdict turned on beside the verdict itself;
1156
+ `profile`, `loc` and `files` all come from `diff-stats.mjs` over the merged
1157
+ diff. **Phase 0 does not size anything** — it shortlists, a Pull claims, and
1158
+ the sizing run happens inside the member after both, which is why the verdict
1159
+ has to travel in the PR body rather than being something you already hold.
1160
+
1161
+ **A verdict is a measurement only if it post-dates the run that produced it.** A
1162
+ `Sizing:` line typed in before the skill ever ran is byte-identical to one the
1163
+ skill produced, so the body cannot settle this alone and the member's report
1164
+ carries the second source: when it ran `sizing-a-ticket` relative to opening the
1165
+ PR (#1070, measured on a member that wrote the line first, caught itself, and
1166
+ corrected it). **Record `sizing` only when the report places that run before the
1167
+ PR AND the line carries its signal.** Ordering clause missing, verdict authored
1168
+ before the run with no corrected value reported, or body and report naming
1169
+ different verdicts — leave the field BLANK and say which in `note`. Do not
1170
+ re-derive the verdict from the diff to fill the gap: `sizing-a-ticket` weighs
1171
+ more than file count, and a substituted proxy reads as measured too. **A value
1172
+ not in hand is left BLANK, never estimated** — blank reads as unknown and drops
1173
+ the row from a stratified comparison, while a guess reads as measured and
1174
+ poisons one. Blank still means the field is WRITTEN and empty: omit the flag
1175
+ (`--sizing`, `--profile`, `--loc`, `--files`) and the script writes that field
1176
+ empty at full width, because a row of some in-between width cannot be told
1177
+ apart from a shifted one. The `note` field is free text and sits before those
1178
+ four, so the script refuses a tab or newline in it: one tab would shift all
1179
+ four for that row alone.
1180
+
1181
+ **Then record the run's member facts — do not author them.** Scrape EVERY session
1182
+ directory for this cwd, not one:
1183
+
1184
+ ```bash
1185
+ PROJECT_DIR="$(node -e 'import("./scripts/board.mjs").then(m => console.log(m.encodeProjectDir(process.cwd())))')"
1186
+ for d in "$HOME/.omp/agent/sessions/$PROJECT_DIR"/*/; do
1187
+ node scripts/member-outcomes.mjs "$d"
1188
+ done
1189
+ ```
1190
+
1191
+ `encodeProjectDir` (`scripts/board.mjs`) encodes the cwd the way omp's own
1192
+ session directory naming does — every non-alphanumeric character becomes
1193
+ `-`, with a leading dot segment's dot PRESERVED rather than folded into the
1194
+ dash run (`member-record.test.mjs`'s regression case: `.claude` becomes
1195
+ `-.claude`, not `--claude`) — and hand-guessing that path is why the fleet's
1196
+ own panel once rendered nothing here. The trailing `/` on the glob matters:
1197
+ the same encoded-cwd directory also holds this cwd's own top-level session
1198
+ transcripts as loose FILES sibling to the per-session directories, and a
1199
+ glob without it would try to scrape one of those as if it were a session.
1200
+
1201
+ **Do not narrow this to "this run's session" with `findSubagentsDir`.** That helper
1202
+ answers a different question — the session with the NEWEST transcript for this cwd,
1203
+ which is not the same as the one you are in. Any other session sharing this cwd —
1204
+ a second terminal, a second controller run — can hold a newer transcript than
1205
+ yours at the moment you reach this step, and a second session dispatching
1206
+ anything while you reach it wins the tie: the run then re-scrapes a stranger's
1207
+ members, prints a plausible row count and exits 0 while its own facts are
1208
+ never recorded. Looping every session dir costs a few seconds, cannot pick
1209
+ wrong, and is idempotent by construction.
1210
+
1211
+ The scraper takes the session directory itself and refuses a path it cannot
1212
+ read — a missing, unreadable or non-directory path all exit 2 — so a wrong
1213
+ path fails loudly instead of writing nothing and exiting 0. It reports the
1214
+ run's own YIELD, `scraped N of M members (D dropped)`, alongside the file's
1215
+ total: read the yield, because the total is the whole corpus and looks
1216
+ healthy even when every member of this session dropped.
1217
+
1218
+ It derives every row from the member transcripts omp already wrote — both the
1219
+ flat ones and a member's own nested fan-out one level down — so a
1220
+ second run over the same session changes nothing and a re-run after a member is
1221
+ re-dispatched picks the new transcript up. **Never hand-edit
1222
+ `docs/metrics/member-outcomes.tsv`** — it is regenerated wholesale whenever the
1223
+ role classifier changes, and a hand-entered value would not survive that. The
1224
+ verdict for a PR goes to `tier-outcomes.tsv` through `tier-outcomes.mjs
1225
+ append`, as above. Once both files hold this run's rows, and before either is
1226
+ committed, run `~/.fleet/bin/fleet-run tier-outcomes.mjs check --live`. Exit 1
1227
+ names each row whose `tier` disagrees with the one implementer the member facts
1228
+ say ran for its ticket: correct that row's `tier` to the short name it prints,
1229
+ or blank it and say why in `note`. Each WARNING names a PR this run's ledger
1230
+ marks `reviewed=` that has no row yet — append it before committing if it is
1231
+ an implementer PR.
1232
+
1233
+ Both files are the run's own artifacts and neither commits itself. Carry them to
1234
+ main the same way the run carries any other controller-authored change; leaving a
1235
+ regenerated 5,000-row corpus uncommitted in the checkout is how it gets discarded by
1236
+ the next `git checkout` with nothing to show it ever ran.
1237
+
1238
+ **Commit both to `chore/run-artifacts-<date>` and open a PR — at end of run, and
1239
+ that branch name is the convention rather than a suggestion.** Phase 0's
1240
+ fast-forward step calls this the previous run's close-out PR and says the rules
1241
+ THIS run needs arrive in it, so the next controller goes looking for it by shape;
1242
+ a name of your own invention still merges and still cannot be found. Suffix a
1243
+ letter when the date already has one (`chore/run-artifacts-2026-08-23b`).
1244
+
1245
+ **Data rows and rule-doc prose never share a PR — one branch each, and when the
1246
+ rules here compete this is the one to keep.** The two halves have opposite cost
1247
+ profiles, and bundling makes the cheap-to-strand half gate the expensive one.
1248
+ Stranding a data row loses it: the tier guard re-derives its floor from the
1249
+ undercount and re-fires, the same stale-file failure Phase 0's fast-forward step
1250
+ exists to catch, and `member-outcomes.tsv` is regenerated from harness
1251
+ transcripts this repo does not own, so re-running the scrape later is worth only
1252
+ what the harness still holds. Stranding a rule change costs the status quo, which
1253
+ is where it already was. So `chore/run-artifacts-<date>` carries the two
1254
+ `docs/metrics/` files and nothing else, and prose that wants review goes on its
1255
+ own branch with its own PR.
1256
+
1257
+ **Why not decide inside one run.** A run holds 2-3 implementer PRs, and ticket
1258
+ difficulty swamps the tier effect — a gojq parity harness and a two-statement
1259
+ shell reorder are not comparable units. Finding-counts are not comparable either:
1260
+ `selectDimensions` trims the fan-out by diff profile, so one PR fields 29 agents
1261
+ over six dimensions and its sibling fields 8 over three. And the fleet is not
1262
+ stationary — this prompt gets edited mid-run when a defect earns it. Hence a
1263
+ binary outcome per PR, accumulating, rather than a per-run verdict.
1264
+
1265
+ **Why the rows this guard fired on could not answer the tier question, and this
1266
+ is the load-bearing part.** Until the 2026-08-16 revert, `class` and `tier` were
1267
+ perfectly confounded: routine always ran `sonnet`, correction always ran top
1268
+ tier. So the comparison the file invites — routine-at-sonnet against
1269
+ correction-at-top-tier — measures **class, not tier**, because those classes fail
1270
+ in different ways by construction: corrections ship false claims in prose,
1271
+ routines ship incomplete or regressing code. A run that "mixes both" does not fix
1272
+ it. **Only a same-class comparison across tiers is informative**, and the old
1273
+ rule could not produce one, since no routine ticket ever ran at top tier.
1274
+
1275
+ **That last sentence is no longer true, and this is the part to re-read.** Since
1276
+ the revert every routine ticket runs at top tier, so the file now holds 55
1277
+ `routine`/`opus` rows against 11 `routine`/`sonnet` (as of 2026-08-28, 103 rows
1278
+ — recount before citing). The same-class comparison the paragraph above calls
1279
+ the only informative one therefore EXISTS now. It is still not clean: the two
1280
+ groups are split almost entirely by calendar date, so it measures prompt
1281
+ evolution at least as much as tier. The counter-evidence paragraph earlier in
1282
+ this section carries the split and the three rows that cut against it. Recount
1283
+ both, and every other figure in this section, with:
1284
+
1285
+ ```bash
1286
+ grep -vc '^#' docs/metrics/tier-outcomes.tsv
1287
+ awk -F'\t' '!/^#/ && $4=="routine" {n++; d[$1]=1; if($6=="no") no++} \
1288
+ END{print n, length(d), no+0}' docs/metrics/tier-outcomes.tsv
1289
+ awk -F'\t' '!/^#/ && $4=="routine" {t[$5]++; if($6=="no") f[$5]++} \
1290
+ END{for(k in t) print k, t[k], f[k]+0}' docs/metrics/tier-outcomes.tsv
1291
+ ```
1292
+
1293
+ **These rows are the historical corpus, and nothing appended to them fixes the
1294
+ confound.** What fixes it is the within-run pairing in the dispatch rule above:
1295
+ from now on one implementer in every five runs at `sonnet` beside the `opus`
1296
+ ones, against the same prompts on the same day, so the comparison stops depending on
1297
+ which tier history happened to leave in which week. Read the pairs, not the
1298
+ whole-file split, once there are enough of them.
1299
+
1300
+ **So read what the guard actually established: routine tickets sometimes fail to
1301
+ close their own ticket. Not that `sonnet` caused it.** The revert is the
1302
+ pre-committed rule being honoured, not a measurement. Restoring a cheap tier is
1303
+ still the maintainer's call and still a change to the dispatch rule — but the
1304
+ deliberate control it used to require is no longer something anyone has to
1305
+ authorize one ticket at a time: the alternate-tier dispatch above produces one
1306
+ in every five Pulls by construction. **Do not read the pairs early.** Report the count —
1307
+ the DELIBERATE count, from the query in `member-outcomes.tsv`'s header, which
1308
+ prints the pair count and its distinct `run_date`s and counts only sessions
1309
+ that ran both implementer definitions at different models — and stop until
1310
+ there are at least ten of them across five or more distinct `run_date`s; below
1311
+ that, a pair count is a number, not evidence, and the last guard fired with
1312
+ n=1 on the control side. **Report whichever number that query prints, never a
1313
+ number from any other one:** the query it replaces (#1066) counted every
1314
+ session whose implementers merely differed, so it cleared this floor by an
1315
+ order of magnitude while the controlled comparison did not exist yet.
1316
+
1317
+ The risk being priced is economic, not shipped bugs. Reviews run 3-5x *longer*
1318
+ than implementation (Red flags, below), so one extra fix-round costs an implementer slot
1319
+ and eats the saving the cheaper implementer made. The revert needs a floor AND a
1320
+ trigger, and neither alone. **Floor:** the file holds at least
1321
+ three `class=routine` PRs spanning **two or more distinct `run_date`s**.
1322
+ **Trigger, read only once the floor is met:** **two or more** of those rows carry
1323
+ `closed_own_ticket` `no`, or the implementer
1324
+ share in `board.mjs build`'s `.spend.roles` is climbing →
1325
+ revert **`class=routine`** to top tier, never the rule wholesale. That floor is
1326
+ over the accumulated file, never one run — and the `run_date` half is what makes
1327
+ that literal instead of merely asserted: a PR count alone is satisfied by a
1328
+ single run's rows, which is the state this file ships in. Without the floor a
1329
+ single noisy PR reverts a class; without a `no` count, "trending" names no
1330
+ threshold and whether the guard fires is undefined. Per-`impl-<N>`
1331
+ spend is not available from `.spend.top`: it labels agents by the member
1332
+ name, but holds only the eight largest spenders.
1333
+
1334
+ **Never read the guard's silence as a pass** — and never read a single run's rows
1335
+ as its verdict.
1336
+ Why the agent body carries what it does — read this before editing either agent
1337
+ file, and keep the two bodies byte-identical. Each rule in the body's
1338
+ enumerate-and-declare block is load-bearing, for a different reason.
1339
+ **Enumerate-and-declare** answers a signature measured four times in one run:
1340
+ each implementer fixed exactly the cases its ticket named and left an adjacent
1341
+ one of the same class broken — a CRLF body **broken by** the fix for depth and
1342
+ split headings, a symlinked worktree after fixing locked and regular-file ones,
1343
+ an unreadable `refs/heads/<type>/` after fixing `refs/heads` itself, a bracketed
1344
+ file path after fixing typos and vendored ones. **All four failed to close their
1345
+ own ticket** — #65's acceptance criterion went unmet, and the other three left
1346
+ the named defect reachable by a sibling spelling. Every one was caught by
1347
+ review, at review cost, which runs 3-5x the implementation it checks.
1348
+
1349
+ **Prose-first** and **wrongly-REFUSE** are not padding — they are the #394 case,
1350
+ which shipped with **enumerate-and-declare** already in its prompt. It missed a
1351
+ shape its own ticket named in passing, because it enumerated from the mechanism
1352
+ instead of the text; and it introduced a regression refusing every `node --test`
1353
+ flag, because it enumerated what the guard should catch and never what it could
1354
+ wrongly refuse.
1355
+
1356
+ The commit-incrementally block is not optional. A member that goes idle mid-task
1357
+ leaves its diff only in the worktree, and the controller cannot reap, replace,
1358
+ or even see it — `worktree-audit.sh`'s committed-vs-uncommitted split is exactly
1359
+ what decides whether a replacement redoes or destroys work. Observed twice in
1360
+ one run.
1361
+
1362
+ **The identity block is what makes `sizing-a-ticket`'s fleet entry reachable.**
1363
+ That skill conditions its heavy-row entry on the reader being a fleet member; a
1364
+ reader that takes itself for a solo session gets `superpowers:brainstorming`
1365
+ instead, whose `<HARD-GATE>` withholds every implementation action until a human
1366
+ partner approves — approval no unattended member can obtain, so it parks rather
1367
+ than fails. Nothing else you carry says what the member is — an incidental
1368
+ mention of the controller is not a statement that the reader is one of its
1369
+ members. That skill keeps its condition, so a solo session still runs the
1370
+ interactive path; this block is what puts a member on the fleet side of it.
1371
+
1372
+ A member that bails demotes nothing itself; demotion by cause is yours
1373
+ (**Implementer bails before implementing**).
1374
+
1375
+ ## Phase 3 — event loop
1376
+
1377
+ React to events; never block on one.
1378
+
1379
+ **React to artifacts, not agents.** `idle` means "not currently executing", not
1380
+ "done", and a finished member's finding may never arrive. Read `gh pr view`,
1381
+ `gh run view`, `git -C <worktree> status` **before** messaging; when you message,
1382
+ send the specific next action, never "what is your status".
1383
+ See references/member-lifecycle.md.
1384
+
1385
+ **Do not ask permission to run the loop.** Dispatching a reviewer, spawning a
1386
+ merge bot, Pulling a ticket, re-verifying a SHA, filing a follow-up — all proceed
1387
+ unconfirmed. Invoking the command was the opt-in. One exception: **a judgement the
1388
+ evidence cannot settle**.
1389
+
1390
+ **Rule: record, tick, act, beat.** Every wake — a member report, a review
1391
+ notification, a label, a CI run reaching a terminal state, a heartbeat — ends in
1392
+ one `fleet-tick.mjs` invocation, and you do what it prints. There are no hand-run
1393
+ refill or dispatch edges left. Record first, because the tick reads the run off
1394
+ `.fleet/ledger.md` and nothing else of yours: a wake you have not written down is
1395
+ one it cannot see, and it names the same dispatch again. Every record goes
1396
+ through `ledger.mjs` (**Run ledger**) — `settle` for a member's outcome, `row`
1397
+ for a token on a ticket's line — never a hand edit.
1398
+
1399
+ | Wake | Record, then tick |
1400
+ |---|---|
1401
+ | Implementer report | `verify-sha.sh`; `ledger.mjs settle impl-<N>=PR#<M>`, or `=bailed` and relabel by cause (**Implementer bails before implementing**, below) |
1402
+ | Review workflow notification / `review-pr-<n>` report | write `<scratch>/review-<pr>.json`; `reviewed=<head>:<survived>/<refuted>/<unverified>` on the PR's row (**Reviewers**) |
1403
+ | Fix-applier report | `ledger.mjs settle fix-pr-<M>=…`; copy the refutations it reversed to `ruled`; `ledger.mjs filed <N> "<subject>"` for each `unrecorded:` line |
1404
+ | Finisher report | `ledger.mjs settle finisher-pr-<M>=labelled`; `ledger.mjs filed <N> "<subject>"` for each `unrecorded:` line |
1405
+ | Finisher report (halted) | `ledger.mjs settle finisher-pr-<M>=halted:<cause>`; `gh pr comment <M>` with the finisher's halt report, cause and evidence; `ledger.mjs filed <N> "<subject>"` for each `unrecorded:` line; then the per-cause rule (**Resolving a finisher halt**, below) |
1406
+ | Label seen (persistent Monitor) | nothing to record |
1407
+ | CI run terminal | `ci=<run-id>:<attempt>:<conclusion>` on the row; then the finisher gate (below) |
1408
+ | Merge-bot pass report | `held-behind:#<lower>` rows; `ledger.mjs settle merge-bot-<n>=done`; `reap.sh --apply`. (The bot may also have written `conflict-hold:#<pr>` onto a held PR's own row earlier in this same pass, before reporting — that token is the bot's, never `reap.sh`'s.) |
1409
+ | Drain | `ledger.mjs drain "<reason>"`; release the claims (below); `settle impl-<N>=released` |
1410
+ | Heartbeat | nothing to record |
1411
+
1412
+ Then run the tick, act on every line it prints, and arm the beat. What a wake
1413
+ owes beyond its row:
1414
+
1415
+ - **Nothing to do right now** → **do not end your turn.** Arm the heartbeat
1416
+ below. A turn that ends on a drained queue is #3's stall itself: nothing
1417
+ external will wake you, and the level-check you are one command away from
1418
+ never runs. Listed first because it is the only wake with no trigger —
1419
+ every other row above arrives; this one is the absence of one.
1420
+ - **Implementer report** → verify the SHA is reachable on the expected branch,
1421
+ settle the member, then run the tick. The PR is owed a review from here on:
1422
+ the tick names it as `DISPATCH review PR#<M>` once a reviewer slot is free,
1423
+ and it names the next shortlist head for the slot the implementer left. Pull
1424
+ nothing the tick did not name.
1425
+ - **Implementer bails before implementing** → settle `impl-<N>=bailed`, then
1426
+ demote by cause:
1427
+
1428
+ | Cause | Label |
1429
+ |---|---|
1430
+ | brief does not decide *what* to build | `needs-triage` |
1431
+ | genuine fork — options named, none ruled | `ready-for-human` |
1432
+ | needs human hands — external access, manual testing, judgment during the work | `ready-for-human` |
1433
+
1434
+ `gh issue edit <N> --remove-label ready-for-agent --remove-label in-progress
1435
+ --add-label <label>`, comment the cause, release the worktree and branch with
1436
+ `release-ticket.sh` (below — `reap.sh` declines a claim that never became a
1437
+ PR), then run the tick: the head it names next is a *different* ticket.
1438
+ `needs-triage` routes back to `/triage`, which can return it as
1439
+ `ready-for-agent`; `ready-for-human` for hands or a fork; `needs-triage` for a
1440
+ brief that names no *what*.
1441
+
1442
+ **Dropping `in-progress` is the load-bearing half** — phase 1 applied it and
1443
+ `candidates.mjs` excludes it, so leaving it makes the ticket invisible to your
1444
+ scans *and* the maintainer's. It does not loop; it disappears. The same causes
1445
+ relabel an unclaimed ticket at the Pull (phase 1), where there is no
1446
+ `in-progress` to drop — the causes and labels are one table, applied at
1447
+ whichever point the ticket fails them.
1448
+ - **A review result lands** → see the result file written (by you or by the
1449
+ runner — **Reviewers** says which, per harness) and record `reviewed=` off its
1450
+ digest, then run the tick: a PR with survivors prints as
1451
+ `DISPATCH fix-pr PR#<M>`. Nothing survived and nothing to file → skip the
1452
+ fix-applier and dispatch the **finisher** directly: no member will touch that
1453
+ PR, so no push is coming and nothing will wake you. A review that failed is
1454
+ not a result — **Reviewers** says who retries it and what takes over.
1455
+ - **Monitor: `ready-to-merge` appears** → nothing to record; run the tick, and
1456
+ on `DISPATCH merge-bot` dispatch the next `merge-bot-<n>` (**Merge bot**).
1457
+ Catches hand-added labels as well as a finisher's own. The bot does not wait
1458
+ for that finisher's report (ADR 0012 Decision 2): its rebase is server-side,
1459
+ `gh pr update-branch --rebase`, so nothing on the finisher's worktree has to
1460
+ happen first.
1461
+ - **Merge-bot pass reports done** → write each `held-behind-#<lower>` it reports
1462
+ into that ticket's row as `held-behind:#<lower>` — the verdict moves no label
1463
+ and leaves nothing in the repo, so the row is the only place the tick can read
1464
+ it from — settle `merge-bot-<n>=done`, reap merged branches and worktrees with
1465
+ `reap.sh --apply` (below) — always, even when the pass merged nothing — and
1466
+ then run the tick. A label that landed at the last moment reads `DISPATCH
1467
+ merge-bot` again: dispatch the next bot straight away. A `rebase-fallback-#<pr>`
1468
+ on a conflict needs no record from you — the bot already appended
1469
+ `conflict-hold:#<pr>` to that PR's row, and the tick turns it into `DISPATCH
1470
+ fix-pr PR#<pr>` (**Reviewers**).
1471
+ - **The run ends, or the maintainer says drain** → `ledger.mjs drain
1472
+ "<reason>"` first, then release every claim that never became a PR (below)
1473
+ and settle each `impl-<N>=released`. Nothing else in the loop fires for those
1474
+ claims. The marker is on disk, so the tick holds the implementer row at
1475
+ `HOLD (draining)` from then on — for a replacement controller too — and keeps
1476
+ the review, fix-applier and merge rows firing until the open PRs merge.
1477
+ - **Monitor: CI run completes** → bind it (`ci-state.mjs --pr <N>`) and **record
1478
+ it as `ci=<run-id>:<attempt>:<conclusion>`, not just "CI green"** — in the
1479
+ ticket's ledger row, which outlives your context. `row` **replaces the whole
1480
+ line** (above), so repeat `class=`, `ports=` and `→ PR#` or they are gone.
1481
+ That key cannot be reconstructed once the head is superseded, so a
1482
+ controller holding only the colour cannot later tell an edge it has already
1483
+ spent from one that never fired, and that is the distinction the sibling
1484
+ bullet below turns on. The whole key, never the conclusion alone: **a
1485
+ conclusion is not stable** (below), because a rerun rewrites the run in
1486
+ place. The diff-validating `check` job green with no heavy job (the
1487
+ diff-validating suites, not the `rebase-check` currency gate) in `failure`
1488
+ → a finisher CANDIDATE (gated below), a `check`
1489
+ **failure** → a fixer. A `check`-green board whose heavy jobs are merely
1490
+ `skipped` (behind-count staleness, the normal case after a merge) still labels — do NOT
1491
+ gate on `ci-state --quiet` exit 0, which a behind PR never reaches. **This
1492
+ edge fires for every CI run the PR produces, and the implementer's own
1493
+ firing comes first for every PR** — `ci.yml` triggers on `pull_request`, so
1494
+ opening the PR at the end of `next-ticket` step 7 starts a run within seconds,
1495
+ while the review returns 20-40 minutes later. That first firing is
1496
+ the ordinary case for every PR, not a rarity, and no review has run at all
1497
+ when it arrives. **Green is therefore not the gate: dispatch a finisher only
1498
+ once the PR's review has returned AND its fix-applier, if one was dispatched,
1499
+ has sent its report — pushed is not reported**, and a push before that report
1500
+ is mid-work on a SHA the member may still move, which its own prompt tells it
1501
+ not to hand over. A push is therefore not an exit, and a report that has not
1502
+ arrived is asked for by name rather than read as one. Neither shape is caught
1503
+ by an empty outbox: on the implementer's firing there is no fix-applier to owe
1504
+ anything to, so the outbox is *vacuously* empty, and on a fix-applier's
1505
+ mid-work push nothing has been sent since the dispatch, so it is *genuinely*
1506
+ empty. **The outbox is the last test, not the only one, and it stands wherever
1507
+ a fix-applier exists** — that is exactly where a ruling you still owe it is
1508
+ outstanding, so never dispatch off it while you do. Empty your outbox to it
1509
+ first — including any ruling you have withdrawn or reversed — then dispatch
1510
+ (below); a final report is not proof it stopped. A PR that needs nothing fixed
1511
+ reaches a finisher through the **fix-applier reports `no-op`** bullet below,
1512
+ never by waiting for a second CI event this head will never produce.
1513
+ Then run the tick.
1514
+ - **A fix-applier reports `no-op`, or a SHA you have already bound** → dispatch
1515
+ the finisher **now**, against the existing head. No push means no new run, and
1516
+ the Monitor above is edge-keyed on `<run-id>:<attempt>:<conclusion>` — that
1517
+ head's terminal state already fired once and will never fire again, so waiting
1518
+ for the CI event waits forever. This stays a common outcome on a clean PR:
1519
+ `suggestion` is the band a clean diff produces, and every out-of-scope or
1520
+ refuted one is filed as an issue rather than committed. An edge-only label path
1521
+ therefore strands exactly the PRs with nothing wrong with them. **Reconcile, do
1522
+ not wait for an event** governs here too, not only the implementer row. **This
1523
+ bullet and the one above are a pair, and on a clean PR this one carries the
1524
+ whole route to a finisher**: a `no-op` report satisfies the gate above by
1525
+ itself — the review has returned, because a fix-applier exists only after it
1526
+ did, and the member has reported — so nothing further is owed and no further
1527
+ event is coming. Edit either bullet without the other and what strands is
1528
+ exactly the PR that needed no fixes.
1529
+ - **`ci-state.mjs --pr <N>` reads `verdict: "no-ci"`** → no workflow run will ever
1530
+ complete for this repo, so the CI-run-completion edge above never fires and
1531
+ waiting for it stalls the whole PR — the same silent-stall shape #111 reported
1532
+ before this verdict existed. Dispatch the finisher off the reviewer's final
1533
+ verdict instead, the moment it lands — and, same as above, never while you still
1534
+ owe it a ruling — or hold anything else it has not received, a ruling you have
1535
+ withdrawn or reversed included. The finisher's gate is then the
1536
+ `--declare-no-ci` declaration, not a `check` job: with it, label off the
1537
+ reviewer's verified suite run; **without it, do not label** — report that this
1538
+ repo has no CI configured and no declaration, and stop. Absence never reads as
1539
+ pass. See `review-and-fix.md` step 6.
1540
+
1541
+ **Every wake ends in the tick.** One invocation, and you act on what it prints:
1542
+
1543
+ ```
1544
+ ~/.fleet/bin/fleet-run fleet-tick.mjs [--implementer-cap <n>] [--reviewer-cap <n>] [--max-reviews <n>]
1545
+ ```
1546
+
1547
+ It reads the run itself, and nobody states a count. Live implementers, live
1548
+ review units (in-flight `review=` tokens plus unsettled `fix-pr-` ones), the
1549
+ merge bot, merge holds, tier mismatches and the drain marker come off
1550
+ `.fleet/ledger.md`; the unclaimed heads and the supply come off
1551
+ `.fleet/shortlist.json`, which it refreshes itself when the unclaimed count is
1552
+ below the implementer cap, when the file is missing or empty, or when an
1553
+ Exclusion's premise has lifted; the open PRs come off `gh`. A ledger token it
1554
+ cannot read, it refuses rather than guessing — a member counted live or gone on
1555
+ a guess is the over- or under-dispatch it exists to prevent — so correct that
1556
+ row with `ledger.mjs row` and tick again. The caps default to 2 implementers
1557
+ and 6 reviewers, and neither is a hard bound: pass `--implementer-cap` and
1558
+ `--reviewer-cap` on every tick when `$ARGUMENTS` set them, and never otherwise.
1559
+
1560
+ It prints `actual/target` and a named ACTION per role, with the whole **Queue
1561
+ depth** guard table applied in code. Act on each line as it reads:
1562
+
1563
+ - `PULL #<N> …` — one Pull per named ticket, in the order printed: phase 1's
1564
+ read, then phase 2's dispatch. A ticket that fails the read is relabelled or
1565
+ excluded (phase 1), and the next tick names the next head.
1566
+ - `REFRESHED shortlist: <n> entries; <k> lifted` — the tick refreshed the
1567
+ shortlist itself, and its `PULL` row already reads the result. `REFRESH
1568
+ FAILED` is yours: `shortlist.mjs` could not run, and the implementer row is
1569
+ blind until it can.
1570
+ - `SUGGEST /triage, hold idle` — nothing is admissible after the refresh.
1571
+ Suggest, never run (**Queue depth**).
1572
+ - `DISPATCH fix-pr PR#<M> …` — a fix-applier per PR, for a review's survivors
1573
+ or a merge bot's `conflict-hold:#<M>` (**Reviewers**). Printed
1574
+ ahead of reviews on purpose: finishing what is started beats starting more.
1575
+ - `DISPATCH review PR#<M> …` — a review per PR, oldest first, off your turn
1576
+ (**Reviewers**).
1577
+ - `DISPATCH merge-bot` — the next `merge-bot-<n>` (**Merge bot**).
1578
+ - `HOLD (…)` — the row is held and says why: draining, a tier mismatch, an
1579
+ unchecked tier, a saturated review side, `--max-reviews` in flight, or every
1580
+ queued merge candidate held behind a lower PR or on a conflict hold no
1581
+ fix-applier has cleared. The two tier holds are yours to clear — an
1582
+ unchecked tier by running `tier-check.mjs --batch` on the member it names,
1583
+ a mismatch by dispatching the replacement at the right tier (phase 2). Each
1584
+ prints its clearing step in the row's detail: the `tier-check.mjs` command
1585
+ with a batch entry per member it names (fill in `<file>` and `<session>`),
1586
+ or the replacement's name — `impl-<N>-b` on a first retry, else one letter
1587
+ past the highest the ticket has used, or that no retry letter is left.
1588
+ - `AT CAP`, `IDLE OK` — nothing to do on that row.
1589
+
1590
+ **Tier guards under Pull.** An alt Pull — the Pull phase 2 routes to the
1591
+ alternate tier — is where the tier floor is read. Run phase 2's tier guard
1592
+ before choosing the alternate tier, on the floor phase 2 defines over the
1593
+ accumulated `docs/metrics/tier-outcomes.tsv` and on no gate of this Pull's own:
1594
+ a second threshold stated here is a second definition, free to drift from
1595
+ the one that governs, and a throttle would need state nothing on disk records
1596
+ — a schema change with its own ticket. A floor breach — the guard firing —
1597
+ dispatches that Pull at the default tier instead, with no `tier=alt` in its
1598
+ row; say why in your report. The per-dispatch `tier-check.mjs --batch` stays
1599
+ phase 2's own step: a mismatch it finds is the
1600
+ `HOLD (tier mismatch impl-<N>)` above, and a member it has no verdict on is
1601
+ the `HOLD (tier unchecked impl-<N>)`. Nothing else in the loop owns it.
1602
+
1603
+ **`--max-reviews <n>`** bounds how many reviews are in flight at once, inside
1604
+ the reviewer cap. It defaults to the reviewer cap, and the reviewer slots it
1605
+ leaves still serve fix-appliers. Leave it at its default: every review unit
1606
+ already counts against the session's single `task.maxConcurrency` semaphore,
1607
+ which queues at its ceiling rather than refusing (#1771), so reviews run up
1608
+ to the reviewer cap without a tighter explicit bound.
1609
+
1610
+ **Why every wake.** A merge cascade is a firehose of merges, CI greens and
1611
+ rebases that holds your attention on the merge side while the implementer side
1612
+ drains to 0 and stays there — 0 implementers emit no completion event, so a
1613
+ refill that waited for one would never fire. A tick on every wake you are
1614
+ already handling is what makes that drain visible. **Every wake is still an
1615
+ edge, so none covers a fully drained queue**: no members and no open PRs is no
1616
+ event at all, and the tick goes unrun. That state is the heartbeat's (#357).
1617
+
1618
+ **Beat when there is nothing to do, and never end your turn on a drained
1619
+ queue.** You cannot be woken. A backgrounded Monitor does not wake an idle
1620
+ agent — measured twice, see **A member runs its test suite in the foreground**
1621
+ above, where `fix-pr-1184` backgrounded a suite plus a Monitor and sat idle for
1622
+ roughly two hours — and `run-merge-bot.md`'s CI gate states the general rule:
1623
+ "whatever wakes you is external and may never come". So hold the wait yourself,
1624
+ exactly the way that gate does:
1625
+
1626
+ ```bash
1627
+ ~/.fleet/bin/fleet-run fleet-heartbeat.mjs \
1628
+ [--base 300] [--ceiling 1200] [--multiplier 2] [--hold 240]
1629
+ ```
1630
+
1631
+ It blocks, then prints one line. Which line it is, is the whole protocol:
1632
+
1633
+ - `… interval elapsed (quiet=<n>) → run fleet-tick` — the level-check is due.
1634
+ Run the tick above **with `--fold-unchanged`** and act on what it prints.
1635
+ Then arm the beat again.
1636
+ - `… Ns of Ms remain → re-issue this command now, do not end your turn` — no
1637
+ command blocks for a whole interval (omp backgrounds one at
1638
+ 60s, which is why the
1639
+ CI gate tells you to re-issue `gh run watch`). Issue it again. That is still
1640
+ one blocking call per turn, never an idle turn.
1641
+
1642
+ The interval doubles while the fleet asks for nothing and stops at `--ceiling`,
1643
+ so a quiet night costs ~26 wakes instead of ~96. **The ceiling is a real bound,
1644
+ not a formality**: supply grows from OUTSIDE the fleet — a ticket you triage, a
1645
+ correction ticket a reviewer files — and that arrival emits no event either, so
1646
+ the ceiling is your worst-case latency for noticing it. Do not raise it past 30
1647
+ minutes.
1648
+
1649
+ **The beat does not stop on idleness.** An empty shortlist and an empty supply are
1650
+ not a reason to end the run; they are the state a newly triaged ticket arrives
1651
+ into. The run ends when you drain it, when the budget goes, or when this
1652
+ context does — not because there was briefly nothing to do.
1653
+
1654
+ **`--fold-unchanged` belongs to the heartbeat alone**, never to any other wake.
1655
+ It prints one line instead of the rows when a tick asks for nothing AND says
1656
+ exactly what the last one said, which is what makes an unattended night
1657
+ affordable; a tick on any other wake is read by a controller that just acted and
1658
+ needs the rows. An unchanged `PULL` or `DISPATCH` is never folded — unclaimed work
1659
+ always prints in full, because folding it would hide the stall behind this
1660
+ ticket's own remedy.
1661
+
1662
+ **When you stop on purpose, say why — one command, and it is the last thing
1663
+ you owe the next run.** The beat leaves a dated mark on every hold, so a run
1664
+ that dies abruptly (a crashed harness, a closed terminal, an OOM kill) is
1665
+ detected by its mark going stale. A run that stops KNOWINGLY can do better
1666
+ than being detected, and nothing else can write the reason afterwards:
1667
+
1668
+ ```bash
1669
+ ~/.fleet/bin/fleet-run fleet-heartbeat.mjs --stop "budget exhausted"
1670
+ ```
1671
+
1672
+ It holds nothing and returns at once. Use it when the budget goes, when you
1673
+ can see the context ceiling coming, or when you drain the run deliberately.
1674
+ Skipping it is not fatal — the next reader still reports the stop, it just
1675
+ reports that the beat stopped *without a recorded reason*, which is all it can
1676
+ honestly say about a death that named nothing.
1677
+
1678
+ **A `heartbeat STALLED` line is the PREVIOUS run, never this one.** `fleet-tick`
1679
+ prints it before its own rows when the mark it finds is overdue against the
1680
+ interval that mark recorded, and the cockpit shows the same line while it is
1681
+ up. It names when the beat was last seen, how overdue that is, how many
1682
+ tickets are still claimed and in flight, and how much supply the last read found
1683
+ — because the claimed ones keep the `in-progress` label, the candidate scan
1684
+ EXCLUDES that label, and those tickets are therefore invisible to your own
1685
+ shortlist and to the maintainer's. Read the line, decide what to do about the
1686
+ stranded tickets, and carry on; nothing in the fleet releases, relabels or
1687
+ reaps them for you, and nothing restarts the run that stranded them.
1688
+
1689
+ **Own the CI waits.** Members are turn-based and cannot hold across a ten-minute
1690
+ run — they rebase, push, stop. Arm a second persistent Monitor over open PRs'
1691
+ latest runs, keyed `<run-id>:<attempt>:<conclusion>` so each terminal state fires once, and
1692
+ emit the behind-count and the per-job conclusions with it: a `success` on a branch
1693
+ 8 behind is not actionable, and `check`-green-with-heavy-skipped is the staleness
1694
+ board you must not confuse with a red. Do not reinvent that read: one
1695
+ `~/.fleet/bin/fleet-run ci-state.mjs --pr <N>` per open PR already emits
1696
+ run id, attempt, conclusion, behind-count and per-job conclusions, branch derived
1697
+ from the PR — including the `gh api --hostname <host>` a GHE compare call needs,
1698
+ without which the probe 404s and `behind` comes back `null`, never 0, so every
1699
+ event reads as unknown-behind. Call it **without `--quiet`** — that flag drops
1700
+ `jobs` and `missing`.
1701
+
1702
+ A monitor event is a wake-up, never a verdict; members re-query at labelling
1703
+ time. See references/ci-and-staleness.md.
1704
+
1705
+ **A conclusion is not stable, even for a fixed run id on an unchanged head.** A
1706
+ rerun rewrites the run in place, so never cache a conclusion; key watchers on
1707
+ `<run-id>:<attempt>:<conclusion>`. Leaving `attempt` out of the key is the bug
1708
+ that looks like it works: a rerun that lands on the *same* conclusion regenerates
1709
+ an already-seen key and fires nothing, so the second failure is silent and reads
1710
+ exactly like a run still in progress. **Building that key with jq's `//` is the
1711
+ same bug in the opposite direction**: `ci-state` reports an in-progress run as
1712
+ `conclusion: ""`, and `//` catches `null` and `false` but never the empty
1713
+ string, so `.conclusion // "-"` passes `""` straight through, keys a RUNNING job
1714
+ as terminal and fires a spurious not-green — measured in four separate runs,
1715
+ including one where the controller then had to re-arm blind. Test any fallback
1716
+ you write against `""`, `null` AND a real conclusion, and check it still lets
1717
+ the real one through: `map(if . == null or . == "" then "-" else tostring end)`.
1718
+ Also: the newest
1719
+ run on a branch is frequently *not* CI, so `--limit 1` can hide the CI result
1720
+ entirely. See references/ci-and-staleness.md.
1721
+
1722
+ **A probe that cannot read is a transition event, not silence.** The natural
1723
+ watcher shape — `st=$(ci-state.mjs --pr "$pr" 2>/dev/null) || continue` — fails
1724
+ closed correctly and then throws the failure away, so a rate-limited probe emits
1725
+ NOTHING and "no event" becomes indistinguishable from "not green yet". Every
1726
+ open PR stalls unlabelled while the run reads as merely quiet; observed live
1727
+ twice. So check the REST budget *before* polling — `gh api rate_limit` is itself
1728
+ unmetered (`gh api rate_limit --jq '.resources.core.remaining'`, re-confirmed
1729
+ 2026-09-08) — and give an unreadable `ci-state` payload the same treatment one
1730
+ level down. The shape is **one outer tick loop with an inner pass over the open
1731
+ PRs**, because the two causes live at different levels — the budget is one
1732
+ account, the payload is one PR:
1733
+
1734
+ ```sh
1735
+ budget_out= list_out= cap_out= blind= # seed the latches: set -u reads each below before tick 1 ever assigns one
1736
+ pr_cap=200 # the open-PR read's --limit; gh stops there with exit 0 and no warning
1737
+ while :; do # one tick
1738
+ rl=$(gh api rate_limit --jq '.resources.core.remaining' 2>/dev/null || echo ERR)
1739
+ case "$rl" in ''|*[!0-9]*) rl=ERR;; esac # a non-numeric read is an outage, not a budget
1740
+ if [ "$rl" = ERR ] || [ "$rl" -lt 200 ]; then
1741
+ if [ -z "$budget_out" ]; then # ONE global latch: a quota outage hits every PR
1742
+ echo "WATCHER DEGRADED: core REST budget=$rl — CI polling paused, silence is NOT green"
1743
+ budget_out=1
1744
+ fi
1745
+ else
1746
+ if [ -n "$budget_out" ]; then
1747
+ echo "WATCHER RECOVERED: core budget=$rl — CI polling resumed"
1748
+ budget_out=
1749
+ fi
1750
+ prs=$(gh pr list --state open --limit "$pr_cap" --json number --jq '.[].number' 2>/dev/null) || prs=ERR
1751
+ if [ "$prs" = ERR ]; then
1752
+ if [ -z "$list_out" ]; then # global latch: this cause is account-level too
1753
+ echo "WATCHER DEGRADED: cannot list open PRs — CI polling paused, silence is NOT green"
1754
+ list_out=1
1755
+ fi
1756
+ else
1757
+ if [ -n "$list_out" ]; then
1758
+ echo "WATCHER RECOVERED: open-PR list readable again — CI polling resumed"
1759
+ list_out=
1760
+ fi
1761
+ if [ "$(printf '%s\n' "$prs" | grep -c .)" -ge "$pr_cap" ]; then
1762
+ if [ -z "$cap_out" ]; then # global latch: a full page may have been cut there
1763
+ echo "WATCHER DEGRADED: open-PR list hit its --limit $pr_cap — PRs past it are NOT watched, silence on them is NOT green"
1764
+ cap_out=1
1765
+ fi
1766
+ elif [ -n "$cap_out" ]; then
1767
+ echo "WATCHER RECOVERED: open-PR list under its --limit $pr_cap — every open PR watched again"
1768
+ cap_out=
1769
+ fi
1770
+ for pr in $(printf '%s\n' "$prs"); do # inline $(...): `for pr in $prs` is ONE iteration under zsh
1771
+ st=$(~/.fleet/bin/fleet-run ci-state.mjs --pr "$pr" 2>/dev/null) || : # not-green exits non-zero; the payload is the verdict
1772
+ if ! printf '%s' "$st" | jq -e '.verdict and .verdict != "rate-limited"' >/dev/null 2>&1; then
1773
+ case " $blind " in *" $pr "*) ;; *) # latch keyed BY PR: this cause is per-PR
1774
+ echo "WATCHER DEGRADED: no usable ci-state reading for #$pr — silence is NOT green"
1775
+ blind="$blind $pr" ;;
1776
+ esac
1777
+ continue # inner continue — still reaches the tick sleep
1778
+ fi
1779
+ case " $blind " in *" $pr "*)
1780
+ echo "WATCHER RECOVERED: ci-state reading #$pr again — CI polling resumed"
1781
+ keep=; for b in $(printf '%s\n' "$blind"); do [ "$b" = "$pr" ] || keep="$keep $b"; done; blind=$keep ;;
1782
+ esac
1783
+ : # your normal handling of $st for this PR
1784
+ done
1785
+ fi
1786
+ fi
1787
+ sleep 120 # the block's only pacing, once per tick
1788
+ done
1789
+ ```
1790
+
1791
+ **One gate, not a gate plus a caveat.** `jq -e '.verdict and .verdict !=
1792
+ "rate-limited"'` exits non-zero on unparseable input *and* on a false result, so
1793
+ that single test covers empty, garbage AND a self-named quota refusal. Empty
1794
+ stdin produces no result at all, which `-e` reports as exit 4 (measured), so a
1795
+ `[ -z "$st" ] ||` pre-check in front of it is a *second* gate testing what this
1796
+ one already tests — the caveat this heading is about. Leaving
1797
+ the named verdict to prose instead is how a watcher clears its latch on an
1798
+ outage payload and hands it downstream as CI state — the very blindness this
1799
+ section exists to remove, one level in. **The `.verdict and` half is load-bearing
1800
+ and not belt-and-braces**: inequality alone never tests that a verdict *exists*,
1801
+ so `{}`, `null` and `{"verdict":null}` all evaluate `null != "rate-limited"` →
1802
+ true and clear the gate (measured), handing an empty or error object downstream
1803
+ as a CI reading. Require the field, then compare it.
1804
+
1805
+ **It has to latch** — one line entering the degraded state, one leaving it,
1806
+ never one per tick. An unlatched line at a 120s poll gets the Monitor
1807
+ auto-stopped for volume during even a two-minute outage, reintroducing the same
1808
+ blindness by another route. **Latch each cause at the level its cause lives
1809
+ at**: the budget, the open-PR list and that list's cap are one global flag
1810
+ each — all three are account-level — but the payload latch is keyed by PR, and a
1811
+ shared scalar for those is an unlatched line wearing a latch's clothes — one
1812
+ persistently blind PR alongside one healthy PR re-clears the flag on every tick,
1813
+ emitting a DEGRADED and a false RECOVERED pair forever. The recovery line is
1814
+ what says the watch is alive again, so emit it on the first good pass even when
1815
+ nothing about the CI state changed; without it a reader cannot tell a recovered
1816
+ watcher from a dead one.
1817
+
1818
+ **All pacing in exactly one place — the tick loop's own tail `sleep`.** A sleep
1819
+ inside the per-PR pass multiplies by the number of open PRs (8 open PRs → 960s
1820
+ of pause per tick, against the 24s outage reset measured below), and a degraded
1821
+ branch that `continue`s the *outer* loop skips the tail sleep and busy-spins
1822
+ probe pairs during exactly the outage it is reporting. Every degraded
1823
+ branch above falls through to the same single sleep instead.
1824
+
1825
+ **Guard every probe, not just the ones with a verdict field.** The block makes
1826
+ *three* API calls, and the third — `gh pr list` — is the one that looks like
1827
+ plumbing rather than a probe. A non-quota failure there (secondary/abuse limit,
1828
+ 5xx, network blip, expired token) does not lower `.resources.core.remaining`, so
1829
+ the budget gate clears, and an unguarded `for pr in $(gh pr list …)` then
1830
+ iterates zero times over the empty substitution: no error, no latch, no DEGRADED
1831
+ line — total silence per tick, which is exactly what this section exists to
1832
+ remove. Capture its status (`prs=$(…) || prs=ERR`), latch it globally, and fall
1833
+ through to the same tail sleep. **Then iterate with the inline `$(printf '%s\n'
1834
+ "$prs")` form, never a bare `for pr in $prs`** — the assigned-variable trap in
1835
+ **Shell traps** above, which carries the mechanism and the measurements. It
1836
+ applies to **every** loop in this block, the `blind`-latch removal included:
1837
+ under a bare `for b in $blind` a recovered PR never leaves the list and the block
1838
+ emits a fresh RECOVERED every tick thereafter — the per-tick volume the latch
1839
+ exists to prevent, wearing a latch's clothes again.
1840
+
1841
+ **A readable list can still be a short one.** `gh pr list` stops at its
1842
+ `--limit` — 30 when the flag is absent — with exit 0 and no warning, so a list
1843
+ that fills its limit reads exactly like one that happens to be that long, and
1844
+ every open PR past it goes unwatched without a line. Pass an explicit `--limit`
1845
+ (`pr_cap`: one variable for the flag and the check, so the two cannot drift)
1846
+ and treat a full page as its own degraded cause — the "no silent caps" rule
1847
+ `candidates.mjs`'s `refuseIfCapped()` and `fleet-tick.mjs`'s `PR_LIMIT` already
1848
+ enforce. It latches globally like the list failure but does not pause polling:
1849
+ the PRs it did return are real, so the pass still watches them, and the
1850
+ DEGRADED line names the rest as unwatched until a pass comes back under the cap.
1851
+
1852
+ **Judge `ci-state` on its payload, never its exit code** — the same rule as
1853
+ `merge-gate.mjs` applies on the merge path, applied to the watcher. `not-green` is an
1854
+ ordinary, frequent state that exits non-zero, so a watcher treating any non-zero
1855
+ exit as an outage misfires constantly on PRs that are merely in progress. Empty
1856
+ or unparseable output is the degraded case; parseable JSON reading
1857
+ `verdict: "not-green"` is normal. An exhausted quota may also name itself,
1858
+ `verdict: "rate-limited"` on stdout — likewise degraded, and likewise not a
1859
+ reading, which is why the gate above tests the verdict rather than mere
1860
+ parseability: that payload is perfectly good JSON.
1861
+
1862
+ **Do not back off and wait.** These outages are short — a rolling window; one
1863
+ measured reset came 24 seconds after `remaining: 0` — and pausing members for a
1864
+ fixed interval stalls the fleet longer than the outage itself would have. A
1865
+ retry-and-wait loop is what turns a 60s outage into a stalled member. Report it,
1866
+ keep the local work moving (git, tests and mutation runs are all unaffected),
1867
+ re-probe.
1868
+
1869
+ **While the budget is exhausted, `ledger.mjs check` reads
1870
+ `verdict: "unverified"`** — the ledger was read and the tracker was not. That is
1871
+ correct behaviour, but `unverified` exits **0**, the same as `clean`, so a
1872
+ member treating exit 0 as "safe to file" files blind during exactly this window.
1873
+ Say so when you flag the outage: members read `verdict` explicitly until you
1874
+ report recovery, never the exit code alone.
1875
+
1876
+ ### Reviewers
1877
+
1878
+ **Dispatch the review, never wait on it, and act when its result lands. That is the default path.**
1879
+ The tick names every PR owed one — `DISPATCH review PR#<M>`, oldest first —
1880
+ and each gets one review, once per PR:
1881
+
1882
+ a `task` member named `review-pr-<pr#>`, agent `fleet-review-runner`, its prompt the same five args — it loads `review-eval.mjs` through the Resolver (`~/.fleet/bin/fleet-run --path review-eval.mjs`), awaits `runReviewOnOmp` in its own kernel, writes the result file and reports; record `review=member:review-pr-<pr#>` on the PR's row before the dispatch call.
1883
+
1884
+ Write the `review=` token with `ledger.mjs row`, which **replaces the whole
1885
+ line**, so carry every other field. The tick counts in-flight reviews off the
1886
+ ledger and nowhere else, so a review you launched and never recorded is one it
1887
+ names again.
1888
+
1889
+ **It is the only path on which `selectDimensions` sizes the fan-out to the
1890
+ diff and the verify budget follows severity.** Hand-dispatched (the fallback
1891
+ below), neither executes at all: sizing falls back to a reviewer's own
1892
+ judgement and nothing budgets the adversarial pass. It cuts one immutable
1893
+ snapshot, verifies every critical/important finding adversarially,
1894
+ re-dispatches each crashed specialist and each crashed refuter pair once before
1895
+ it assembles the result, and has `agent()` return **into the script**, so no
1896
+ report can go undelivered and you relay nothing — the delivery failure that
1897
+ cost one fleet five reports on one PR and four on another. None of it runs on
1898
+ your turn: a review takes 20-40 minutes, and a controller that held its turn
1899
+ for each one, one at a time, was what left implementer slots empty (map #1768).
1900
+
1901
+ **Know the trim before you rely on it — it is wider than `docsOnly` suggests.**
1902
+ `diff-stats.mjs` calls a PR docs-only only when it touches **no** src, tests *or*
1903
+ config, but that strictness cuts both ways and the size tier trims again on top.
1904
+ Measured: a docs PR that also adds one test file is profile `tests-only` and runs
1905
+ **three** (correctness+tests+comments), not six; a no-src, no-test diff that
1906
+ carries a config file keeps silent-failure at **any** size, so a docs+config diff
1907
+ too big for the size tier now runs correctness+silent-failure+comments, not
1908
+ correctness+comments; and any `single-file` or `small` profile trims to
1909
+ correctness+silent-failure+comments, keeping tests only when a test file is in
1910
+ the diff. `comments` is on that floor
1911
+ unconditionally since #218 — it used to need a docs FILE, and `classify()` scores
1912
+ any code extension `src` before it checks docs, so five production PRs whose whole
1913
+ substance was prose inside a `.js`/`.mjs`/`.sh` comment scored `docs: 0` and ran
1914
+ without the one specialist that fit them, `dimensionsUnrun` empty every time.
1915
+ That floor holds **regardless of `hasSrc`** (#236) — a one-file `.yml` or
1916
+ `.github/` shell change gets silent-failure too, not correctness alone.
1917
+ It is the size **tier's** floor,
1918
+ so `tests-only` outranks it when the diff has no config file: that profile is
1919
+ assigned ahead of `single-file`/`small`, so a no-src, no-config diff that also
1920
+ touches a test file gets no silent-failure-hunter — a tests-only diff that also
1921
+ carries a config file keeps it (#739). `single-file` means one file at **any** size, so a
1922
+ one-file rewrite trims too. An unknown profile widens to the full six, the safe
1923
+ direction, so a trim is never something to count on in advance — and a full six
1924
+ is never something to assume.
1925
+
1926
+ **The reviewer cap counts live review units.** A review in flight — a
1927
+ `review-pr-<pr#>` member still running — is one; each
1928
+ `fix-pr-<pr#>` is one; a finisher and a CI wait are zero; and a PR holds at most
1929
+ one slot at a time. In-flight reviews are derived, never remembered: a row with
1930
+ `review=` and no `reviewed=` is one, which is why the token goes on before
1931
+ anything else. The defaults are 2 implementers and 6 reviewers, and neither is
1932
+ a hard cap. The cap bounds units, not the agents a review fans out to — 1
1933
+ snapshot + up to 6 specialists + 2 refuters per critical/important finding — and
1934
+ how many reviews may be in flight at once, inside it, is `--max-reviews`. The
1935
+ slots a review does not hold still serve fix-appliers.
1936
+
1937
+ It returns `{pr, head, resume, testEnvironment, dimensionsRun, dimensionsUnrun, cwdAudit, counts, snapshot, survived, refuted, unverified}` —
1938
+ the **digest** first, then the snapshot and the findings — and it lands as
1939
+ one artefact, `<scratch>/review-<pr>.json`, holding that bare object: the
1940
+ `review-pr-<pr#>` runner writes it and reports the digest and the path.
1941
+
1942
+ **You read the digest; the findings are the fix-applier's.**
1943
+ `jq '{pr, head, resume, testEnvironment, dimensionsRun, dimensionsUnrun, cwdAudit, counts}' <scratch>/review-<pr>.json`
1944
+ is the whole of your read, and it is what you record: `reviewed=<head>:<survived>/<refuted>/<unverified>`,
1945
+ off `head` and `counts`, on the PR's row. Findings never enter your context —
1946
+ a result runs 26-61 KB, 7-15k tokens that used to land in yours and then again,
1947
+ up to ~10k characters, in every fix-applier prompt you wrote. The fix-applier
1948
+ reads every one off the file and makes every ruling on them
1949
+ (`review-and-fix.md`'s **The review result file**). What the digest tells you:
1950
+
1951
+ **`testEnvironment` says what every dimension's `test_run` is evidence about**,
1952
+ and it is present on a healthy run as well as a degraded one, so there is
1953
+ nothing to notice by its absence. The snapshot is `git archive`d and then
1954
+ `git init`ed with one commit, and the block that cuts it compares that commit's
1955
+ tree hash against the reviewed commit's (#1056): verified, a suite run in the
1956
+ snapshot collects and runs what a checkout does, and a red is a fact about the
1957
+ tree. UNVERIFIED, it is not — tests that ask git what ships decline or fail for
1958
+ the environment, and this field carries which line of the cut failed. The
1959
+ fix-applier reads it before acting on any `test_run` count; you read it so a
1960
+ degraded review never passes for a clean one.
1961
+ `unverified` is *not* "checked and cleared" — a `suggestion` skips the pass by
1962
+ policy, and a finding whose refuters all crashed lands there too. Both go to the
1963
+ fix-applier with the rest, in the file; never rule on them yourself.
1964
+ **`refutersDispatched`, carried on every finding, is what tells those two
1965
+ apart** — zero is the policy skip, above zero with no surviving vote is the
1966
+ crash — so the population is read off that field rather than off severity,
1967
+ which records only how much a finding would matter if true. `resume` is
1968
+ non-null exactly when a specialist or a refuter pair crashed again after the
1969
+ review's own in-run retry, and **resume beats handing a crash-heavy review
1970
+ on**: a deferred crash is a finding nobody ever looked at.
1971
+ No replay exists for a review that ran in a runner's own kernel — `resume` is reported, not acted on, and the fix-applier defers what it names.
1972
+ `refuted` comes back deliberately as well — a refutation is itself a claim, and
1973
+ one has been reversed on new evidence. The fix-applier may reverse one; its
1974
+ report lists every refutation it reversed, and you copy those to the ledger's
1975
+ `ruled` line.
1976
+
1977
+ **`dimensionsRun` is the dispatch; `dimensionsUnrun` is what names a gap.** A
1978
+ specialist that dies, and one that never executed the suite, both contribute zero
1979
+ findings while the key stays in `dimensionsRun` — so read the two together. A key
1980
+ in `dimensionsRun` and NOT in `dimensionsUnrun` ran a suite; every
1981
+ `dimensionsUnrun` entry is `{dimension, reason}` naming which failure it was.
1982
+ The review already re-dispatched each crashed specialist once, so what
1983
+ `dimensionsUnrun` still names is residue: the fix-applier names it unrun in its
1984
+ report and re-runs nothing — an absence of findings is not coverage. Same rule
1985
+ the fallback below states for a killed specialist, for the same reason.
1986
+
1987
+ The rule this replaces — treat any dimension with nothing in
1988
+ `survived`/`refuted`/`unverified` as unrun — was the workaround for having no
1989
+ such field, and it over-refuses in the direction that costs work: a dimension
1990
+ that ran clean has nothing in those three either (#137, #138).
1991
+
1992
+ **`cwdAudit` is the specialist's own inherited-checkout audit, one entry per
1993
+ dispatched dimension: `{dimension, state, line}`, `state` one of**
1994
+ `clean`/`dirty`/`unrepo`/`missing`. The prompt asks every specialist to run
1995
+ `git status --porcelain -uall` against the directory it inherited before
1996
+ returning and fold the result into a `CWD-AUDIT:` line — a convention, not
1997
+ schema, so a specialist that never emits it or misspells it still validates
1998
+ clean. This field is the runtime backstop that reads for the line regardless:
1999
+ `missing` is exactly as loud as `dirty`, and both name a checkout you should
2000
+ treat as a live scratch write until you have checked it (#1433/#1673).
2001
+
2002
+ **A throw, an empty return, or a notification whose status is not `completed`
2003
+ is a failure event, not a clean review.** The review throws on missing
2004
+ `args.pr`/`args.worktree` and on a snapshot agent that returned no tree, and a
2005
+ failure surfaces mid-loop, where "react, never block" makes it easy to log and
2006
+ carry on — leaving a PR that *reads* as reviewed and is not. **Retry once, then
2007
+ fall back — and whoever holds the review call is who retries:**
2008
+ The `review-pr-<pr#>` runner already retried once inside its cell and reports `failed` with both errors; hand-dispatch the fallback reviewer below as `review-pr-<pr#>-b`, the name that report gives.
2009
+ Either way, settle the dead review by appending `=failed` to its `review=`
2010
+ token, then append `review=fallback:review-pr-<pr#>[-b]` after it, both in one
2011
+ `ledger.mjs row` rewrite — the tick takes the last `review=` token on a row as
2012
+ the one in flight, so that order is what keeps the fallback counted against the
2013
+ cap. A runner member that is killed rather than failed follows **Failure
2014
+ handling** (fresh name, inherited state stated).
2015
+
2016
+ **Then dispatch a fix-applier** — on `DISPATCH fix-pr PR#<M>`, which the tick
2017
+ prints for a PR whose `reviewed=` counts survivors and that has had no
2018
+ fix-applier since — one named member per PR, `fix-pr-<pr#>`, never the PR's
2019
+ implementer, recorded with `ledger.mjs dispatch <pr#> fix-pr-<pr#>` before the
2020
+ call. Its prompt carries the PR number, the worktree abs path, the PR's branch,
2021
+ the same `testCmd` you passed the review, and the **path** `<scratch>/review-<pr>.json`
2022
+ — never the findings. The fix-applier owns every per-PR ruling you once made
2023
+ before dispatch: both mutual-exclusion scans, the suggested-fix re-derivation,
2024
+ `refuted=false` ≠ apply, per-site measurement for a sibling-site extension, and
2025
+ `testEnvironment`/`cwdAudit` before any `test_run`. It holds every finding and
2026
+ you hold none, so there is nothing for you to rank, relay or pre-rule — and a
2027
+ report from a refuter it spawns that surfaces to you is its to retrieve, never
2028
+ yours to scan or pass on.
2029
+
2030
+ **A `DISPATCH fix-pr PR#<M>` on a conflict hold** — the row carries the merge
2031
+ bot's `conflict-hold:#<M>` (`run-merge-bot.md` step 1's fallback), not
2032
+ survivors — is the same slot with a different job, and no review file to hand
2033
+ over. Name it `fix-pr-<M>`, or the next suffix (`-b`, `-c` …) when that name is
2034
+ already on record — `dispatch` refuses a reused one — and dispatch a
2035
+ `fleet-implementer` in the PR's existing worktree with the prompt below's
2036
+ worktree, branch and path discipline, but in place of its review paragraphs:
2037
+ bring `<branch>` current with `origin/main`, resolving every conflict by
2038
+ `run-merge-bot.md`'s **No-undo audit**, run `<testCmd>`, push, report the new
2039
+ head. Settle it `applied:<head>` — `no-op` if no conflict was left — which is
2040
+ what lifts the tick's merge hold; a dispatched-but-live one does not, and
2041
+ `failed`/`killed` leave the PR fix-due for a replacement. The push moves the
2042
+ head after `ready-to-merge`, so the next merge bot refuses it
2043
+ `head-moved-after-label-#<M>`: a fresh finisher, per **Failure handling**.
2044
+
2045
+ **A refutation resting on an injection nothing proved landed is not a refutation
2046
+ — it is a cell that never ran.** A mutation test and a finding reproduction are
2047
+ both failure injections: break something, read what the child does. When the
2048
+ break never reaches the child, the child behaves exactly like its baseline, which
2049
+ is what a genuine no-effect mutation looks like and what a correctly refuted
2050
+ finding looks like. So a negative result is admitted only together with its
2051
+ **positive control** — one run proving the injected difference is observable,
2052
+ either the child's output differing with the injection present versus absent or
2053
+ the child echoing the injected value back from inside. No control → the cell is
2054
+ unrun: re-run it, and never record it as a negative. Measured 2026-08-28 and
2055
+ re-measured on this tree, against a `probe.sh` that echoes both variables back:
2056
+
2057
+ ```sh
2058
+ zsh -c 'cfg="SETB=1 BADJ=1"; env $cfg sh ./probe.sh' # BADJ=[unset] SETB=[1 BADJ=1]
2059
+ bash -c 'cfg="SETB=1 BADJ=1"; env $cfg sh ./probe.sh' # BADJ=[1] SETB=[1]
2060
+ ```
2061
+
2062
+ zsh does not word-split an unquoted parameter expansion, so the whole string
2063
+ arrives as ONE argument: a variable literally named `SETB` takes the value
2064
+ `1 BADJ=1`, the injection variable `BADJ` is never set, and the probe still exits
2065
+ 0. It bites in both directions, and the reproduction direction is the worse one —
2066
+ `fix-pr-983` nearly reported a mutant as behaving identically to its baseline,
2067
+ while `fix-pr-1153` nearly retired a real review finding as non-reproducing after
2068
+ the same shape handed both trees a single argv word and drew `exit 2` from each,
2069
+ which is the signature of a correct refutation with nothing anomalous to notice.
2070
+ The fix-applier prompt and every refuter brief carry the rule and the safe
2071
+ invocation form; the merge bot's brief is the wrong seat, because a bot
2072
+ reads gates and never injects a fault.
2073
+
2074
+ **Where `testCmd` comes from:** the repo's own test command, the one you hand
2075
+ specialists per **Give specialists a stack-free test command** above — in this
2076
+ repo `node --test plugin/scripts/*.test.mjs`. Pass the same string to the
2077
+ review, to the fix-applier, and to the finisher — whose duty-2 mutation gate
2078
+ runs it too — so every gate runs one command. Omit it from the review args and
2079
+ the review (`review-core.mjs`, in a runner) now DERIVES it
2080
+ from the repo under review (#142) instead of defaulting to a fixed string —
2081
+ refusing outright if it can't; the fix-applier has no such fallback, so
2082
+ substituting `<testCmd>` with nothing leaves it no gate at all.
2083
+
2084
+ **Where `<branch>` comes from:** the PR's head branch —
2085
+ `gh pr view <N> --json headRefName -q .headRefName`, or the same branch you cut
2086
+ the worktree from. Substitute it exactly as you substitute `<testCmd>`, because
2087
+ the member cannot read it off git: phase 1 creates an already-open PR's worktree
2088
+ with `--detach`, and there `git branch --show-current` prints nothing and exits 0
2089
+ (measured 2026-09-18, git 2.50.1), so `git push origin
2090
+ "HEAD:$(git branch --show-current)"` exits 128 on `fatal: invalid refspec
2091
+ 'HEAD:'`. Left unsubstituted, the push that prompt ends on has no destination at
2092
+ all.
2093
+
2094
+ > You are ALREADY in worktree `<abs-path>`, whose PR branch is `<branch>` — the
2095
+ > push destination below, given to you because a detached worktree cannot supply
2096
+ > it. Do NOT create another worktree. The review is done and its result is the
2097
+ > file below — do not re-review, do not dispatch specialists.
2098
+ >
2099
+ > **`edit` and `read` resolve a bare relative path against the SESSION ROOT —
2100
+ > the controller's own main checkout — not against that worktree and not
2101
+ > against your `bash` cwd, which they share no `cwd` parameter with. Give them
2102
+ > the absolute worktree path on every call, mutation-probe copies included.**
2103
+ > The main checkout is the parent of `git rev-parse --path-format=absolute
2104
+ > --git-common-dir`. A `member-write-guard` refusal means the path hit the
2105
+ > main checkout — for `bash`, a missing or main-checkout `cwd` — so re-issue
2106
+ > it absolute, under your worktree.
2107
+ >
2108
+ > Read `$(~/.fleet/bin/fleet-run --root)/commands/review-and-fix.md` and run **steps 2, 3
2109
+ > and 5 only**: split apply-now/defer, commit, push, file every deferral as its
2110
+ > own issue with the label the finding's state calls for. Skip step 1 — the
2111
+ > review already ran — and steps 4 and 6: the controller owns the CI wait and
2112
+ > dispatches the finisher.
2113
+ >
2114
+ > **The review's result is `<scratch>/review-<pr>.json`** — the digest first
2115
+ > (`jq '{pr, head, resume, testEnvironment, dimensionsRun, dimensionsUnrun, cwdAudit, counts}'`),
2116
+ > then every finding (`jq '.survived'`, `jq '.unverified'`, `jq '.refuted'`).
2117
+ > Read it through `review-and-fix.md`'s **The review result file**, which holds
2118
+ > the rest of the recipes and every ruling on the findings: both
2119
+ > mutual-exclusion scans, the suggested-fix re-derivation, `refuted=false` ≠
2120
+ > apply, per-site measurement for a sibling-site extension, and `testEnvironment`
2121
+ > and `cwdAudit` before any `test_run`. Every one of those rulings is yours —
2122
+ > nobody upstream has made one, and the controller never reads the findings.
2123
+ >
2124
+ > **Every factual claim your diff restates needs a settling command run
2125
+ > against the tree first** — the issue body is a lead, never a citation.
2126
+ > **No positional references** (`the closing/second/last X`); name the thing
2127
+ > semantically. **Never write a COUNT or a tally into prose; state the
2128
+ > property instead** — unless it is a past-tense record of a measurement you
2129
+ > performed, which stays as written; a present-tense claim about a live
2130
+ > property must be restated as a property (`every other test in the file`),
2131
+ > true at any count. **A settling grep over literal text takes `grep -F`, and
2132
+ > its zero counts only after the same command finds a line known to match.**
2133
+ >
2134
+ > **Apply `survived` findings. A finding in `unverified` whose refuters ran and
2135
+ > crashed always defers** — and which of the two it is, you read off
2136
+ > `refutersDispatched`, never off severity and never off an empty vote list:
2137
+ > above zero with nothing surviving means every refuter dispatched against it
2138
+ > died, and at `critical` that is every one of them. Severity records how much a
2139
+ > finding would matter if true, never whether anything looked. Say *in the
2140
+ > deferral* that its refuters crashed rather than that it went unchecked — the
2141
+ > review re-dispatched each crash once already and reports what died again, so
2142
+ > a deferral that names the crash can still be re-verified. **A `suggestion` is also in `unverified`,
2143
+ > for a different reason — `refutersDispatched` of zero, the 0-refuter budget
2144
+ > the review gives that band by policy — and the rule below, not this one,
2145
+ > covers it.**
2146
+ >
2147
+ > **A `suggestion` is budgeted 0 refuters, so it is unchecked until you check
2148
+ > it.** For each one, first decide scope: is it inside the scope of the PR's own
2149
+ > ticket, or a different piece of work? **Out of scope → defer and file, never
2150
+ > apply.** **In scope → dispatch ONE refuter** against the finding before
2151
+ > touching the tree, biased to refuse, and hand it the prompt below with one
2152
+ > substitution: resolve `<scratch>/pr<N>/<finding>/` in it to an absolute path
2153
+ > under your own run root — `mktemp -d` once per round for
2154
+ > `<scratch>/pr<N>/fix-XXXXXXXX/`, never bare `pr<N>`, since finding ids
2155
+ > restart at 1 each round too — and write that absolute path into the
2156
+ > refuter's prompt in its place; a refuter never derives its own path:
2157
+ >
2158
+ > > Try to REFUTE this finding. Default to refuted=true if uncertain. Verify by
2159
+ > > RUNNING something — compile it, run the test, apply the mutation. Do not
2160
+ > > reason your way to agreement. Observe that run synchronously — run the
2161
+ > > command, wait for it, read its exit code. Never poll a log file for a
2162
+ > > completion marker: prefer ONE blocking run to a poll loop, and treat its
2163
+ > > return as permission to look, never as the answer. Reading a log the run has
2164
+ > > already finished writing is fine; waiting on one is not. If you match a test
2165
+ > > reporter's own output, accepting both `ℹ` and `#` is necessary but NOT
2166
+ > > sufficient — strip SGR escapes first as well. node's prefix moves with the
2167
+ > > node version and with whether stdout is a TTY, and color wraps the whole line
2168
+ > > so it begins with ESC and no prefix anchor matches at all, which returns
2169
+ > > empty at exit 0 — indistinguishable from a hung run and from a run of zero
2170
+ > > tests. For an uncolored baseline use `env -u FORCE_COLOR`; `FORCE_COLOR=`
2171
+ > > empty still enables color, so it is not a control. State your search scope
2172
+ > > AND what your pattern would have missed. A grep over one ref does not
2173
+ > > support a claim about history; a pattern built from the token a diff removed
2174
+ > > does not support a claim that the category is empty. A failure injection with
2175
+ > > no positive control has produced NO result, never a negative one. Before you
2176
+ > > read an injected fault — an env var, an argv word, a mutant — as having had
2177
+ > > no effect, prove the injection reached the child: one run whose output
2178
+ > > differs with it present versus absent, or the child echoing the injected
2179
+ > > value back. Uncontrolled, the cell is unrun — say so in your verdict instead
2180
+ > > of reporting a no-effect result. Build such an invocation as an array
2181
+ > > expanded braced and quoted —
2182
+ > > `cfg=(SETB=1 BADJ=1); env "${cfg[@]}" sh ./probe.sh` — or inline the
2183
+ > > assignments literally — `env SETB=1 BADJ=1 sh ./probe.sh`; NEVER from an
2184
+ > > unquoted scalar — `cfg="SETB=1 BADJ=1"; env $cfg sh ./probe.sh` — which under
2185
+ > > zsh passes ONE argument, sets a variable literally named `SETB` to
2186
+ > > `1 BADJ=1`, never sets `BADJ` at all, and still exits 0. `env $cfg[@]` is not
2187
+ > > the portable spelling either: measured, bash word-splits it into `SETB=1`
2188
+ > > and `BADJ=1[@]`, so the injection variable is set to a corrupted value,
2189
+ > > while zsh behaves exactly as with the bare `$cfg` — `BADJ` never set,
2190
+ > > exit 0. Everything you
2191
+ > > write — mutants, fixtures,
2192
+ > > scratch repos — goes under `<scratch>/pr<N>/<finding>/` and nowhere else;
2193
+ > > the checkout and any worktree are never write targets, though
2194
+ > > `git show`/`git archive` at a pinned ref read fine anywhere. Chain the
2195
+ > > directory change into the command, `cd "$D" && git …`, never
2196
+ > > `cd "$D"; git …`, so a failed `cd` cannot leave a `git` command running in
2197
+ > > the checkout — and bracket a fixture's own git with
2198
+ > > `git rev-parse --show-toplevel`: before `git init` it must NOT resolve to
2199
+ > > the repository, and a fresh scratch dir's `fatal: not a git repository`
2200
+ > > (exit 128) is the pass, not a failure; before any `git commit` it must
2201
+ > > resolve to your scratch path — compare resolved forms (`realpath`), since
2202
+ > > `--show-toplevel` can report `/private/tmp/…` for a `/tmp` scratch dir on
2203
+ > > macOS.
2204
+ >
2205
+ > Survives → apply it, with one hold: if its refuter reports a blast radius
2206
+ > touching lines another finding also changes, that is the mutual-exclusion
2207
+ > scan's second input — rule the pair before either change reaches the tree;
2208
+ > you hold every finding, so only you can see that the two cannot both land. Refuted → defer and file it, and
2209
+ > say the refutation in the issue body. **Apply only what survives — no report is not a survival.** A
2210
+ > refuter you never hear from leaves the finding exactly as unchecked as it
2211
+ > arrived, so it defers like a refuted one.
2212
+ >
2213
+ > **A finding's `suggested_fix` is a hypothesis, not a patch — the review never
2214
+ > ran it.** Only the claim is verified adversarially; the remedy text is unchecked.
2215
+ > Three were wrong as written in one run: a stated end state that dropped a
2216
+ > load-bearing option and measured RED, an assertion against a property the test
2217
+ > helper does not expose (`TypeError`), and an enumeration that stopped short of
2218
+ > two further stale clauses — one of them false in the *dangerous* direction. Run
2219
+ > the remedy before you commit it, and re-derive an assertion from the post-fix
2220
+ > tree rather than from the finding, since a sibling finding may edit the very
2221
+ > text it asserts on.
2222
+ >
2223
+ > **Retrieve that report yourself; do not wait to be handed it — this covers the
2224
+ > refuters YOU dispatch, and only those.** The review's own specialists do leave
2225
+ > transcripts, but nothing gives you their address: the review had `agent()`
2226
+ > return their findings into the script, so the result file holds their findings
2227
+ > and names no transcript, and nothing on disk indexes a transcript by PR or
2228
+ > dimension. Hunting their paths gets you nothing; read the file. A report from a refuter you spawned is
2229
+ > different — it surfaces to the controller rather than to you, and waiting for a
2230
+ > relay that never comes strands the finding. Its transcript is at the output file
2231
+ > named in your spawn result, and its report is the last record:
2232
+ >
2233
+ > A depth-2 helper cannot dispatch further (`task.maxRecursionDepth: 2`); reach it directly instead, by its full dotted id (`<member>.<helper>`), via `hub send` — delivered, woken, no transcript workaround needed.
2234
+ >
2235
+ > If retrieval comes back empty, ask the controller by name. Only when neither
2236
+ > works is the finding **unchecked** — defer and file it, and say so in the body. This is
2237
+ > `review-and-fix.md`'s **Specialists** rule; it reaches you here because the
2238
+ > steps that point at it are the ones you skip.
2239
+ >
2240
+ > The CI facts in that file apply to you — a `rebase-check` red, or heavy jobs
2241
+ > `skipped`, **solely** off a non-zero behind-count, is staleness and not a
2242
+ > failure. Never rebase to clear it. **`solely` is the load-bearing word:**
2243
+ > `ci.yml`'s `rebase-check` exits 1 on five conditions and only one is
2244
+ > staleness, so a non-zero behind-count does not by itself settle which fired.
2245
+ > The job log names the condition — and because the staleness condition exits
2246
+ > before the merge-commit condition is evaluated, the log is silent on that one
2247
+ > by construction, so measure it separately with
2248
+ > `git fetch origin && git rev-list --merges --count "origin/<base>..HEAD"` —
2249
+ > keep the fetch, or a stale local `origin/<base>` widens the range over the
2250
+ > base's own merge commits and reports a merge commit this branch never added.
2251
+ > A non-zero count does not send you to a local rebase either: the merge bot's
2252
+ > step-1 `gh pr update-branch --rebase` drops merge commits too
2253
+ > (`run-merge-bot.md` step 1), so both conditions clear on that one server-side
2254
+ > rebase. What it buys you is knowing the red was never solely staleness.
2255
+ >
2256
+ > **Run `<testCmd>` from the worktree before committing**, copied verbatim.
2257
+ > `tests 0` is a FAILED run, not a pass. Red or zero-test → fix it, or move that
2258
+ > finding to defer; never commit over it. **Never `--no-verify`** — a failing
2259
+ > hook is a finding you report, not an obstacle you route around. Report the test
2260
+ > result with your SHA. Nothing re-reviews this commit: the review ran against a
2261
+ > snapshot cut before your edits existed, and a refuter checked the finding's
2262
+ > claim, never your patch.
2263
+ >
2264
+ > **A test you ADD must kill its own mutant** — break what it pins, confirm it and
2265
+ > only it goes red, restore. **Then a change it should *not* catch, staying
2266
+ > green** — else you proved it fails, not that it discriminates: a pin asserting
2267
+ > whole-file text clears "it and only it goes red" and still reddens on any edit
2268
+ > (measured). A green suite says nothing about a new test: one pin this run
2269
+ > survived the exact mutation it was named for.
2270
+ >
2271
+ > **A mutation that never landed is not a green — it is a cell that did not
2272
+ > run.** Same rule for any fault you inject to see what breaks: prove the
2273
+ > injection reached the child before you read its result — one run whose output
2274
+ > differs with the injection present versus absent, or the child echoing the
2275
+ > injected value back. Without one, a probe that exits 0 reporting the mutant
2276
+ > behaving exactly like its baseline is indistinguishable from a real no-effect
2277
+ > result, and a reproduction that never happened reads as a refutation. Build
2278
+ > such an invocation as an array expanded braced and quoted —
2279
+ > `cfg=(SETB=1 BADJ=1); env "${cfg[@]}" sh ./probe.sh` — or inline the
2280
+ > assignments literally — `env SETB=1 BADJ=1 sh ./probe.sh`; NEVER from an
2281
+ > unquoted scalar — `cfg="SETB=1 BADJ=1"; env $cfg sh ./probe.sh` — which under
2282
+ > zsh passes ONE argument, sets a variable literally named `SETB` to `1 BADJ=1`,
2283
+ > never sets `BADJ` at all, and still exits 0. `env $cfg[@]` is not the portable
2284
+ > spelling either: measured, bash word-splits it into `SETB=1` and
2285
+ > `BADJ=1[@]`, so the injection variable is set to a corrupted value, while
2286
+ > zsh behaves exactly as with the bare `$cfg` — `BADJ` never set, exit 0.
2287
+ >
2288
+ > **Commit BEFORE you mutate, and restore with `cp`, never a git discard.**
2289
+ > `git checkout -- <file>` reverts the whole file, not your mutant — so it also
2290
+ > eats uncommitted edits you made earlier, and the "clean baseline" you measure
2291
+ > next is silently the reverted file. Two members hit this in one run; one lost
2292
+ > prose edits and caught it only because a non-catch control failed. Copy the
2293
+ > file aside and copy it back. Better still, mutate a copy under
2294
+ > `<scratch>/pr<N>/mutate/` and leave the worktree untouched — that is what
2295
+ > refuters are already required to do, and it has no blast radius at all.
2296
+ >
2297
+ > **Never `git stash` or `git stash pop` here either — a WIP commit is the
2298
+ > substitute, not a second scratch mechanism: `git commit -m wip`, then
2299
+ > restore or amend once you're back to real work.** The stash stack is
2300
+ > repo-global too, not per-worktree or per-session — the same `refs/stash`
2301
+ > every concurrent member and the main checkout share, not partitioned the
2302
+ > way `<scratch>/pr<N>/mutate/` above is. A bare pop takes whichever entry is
2303
+ > on top, from any worktree, silently — rc 0, no error — when the tree
2304
+ > receiving it is clean on the affected paths, and refuses only when that
2305
+ > tree is already dirty there. A bare `git stash` (push) does not reach into
2306
+ > a sibling's tree, so that half is not the risk — the pop is. Nothing
2307
+ > partitions the stack; this prohibition is the whole of the protection.
2308
+ >
2309
+ > **Report LAST, and only once nothing can still change.** A report you have
2310
+ > sent **pins that SHA** for the controller, which dispatches a finisher against
2311
+ > it. If a further instruction arrives after you have reported, reply saying the
2312
+ > SHA is moving *before* you touch the tree again — do not silently do the work
2313
+ > and re-report. Measured: three members in one run sent a final report and kept
2314
+ > working; one had its worktree audited mid-mutation, another handed over a SHA
2315
+ > that was two commits stale, and a finisher dispatched on either would have
2316
+ > halted on a diverged head.
2317
+ >
2318
+ > Then report to the controller the pushed SHA, your apply/defer split, and
2319
+ > the deferral issue numbers — a `filed: #N <subject>` line for every issue
2320
+ > step 5 created, and `unrecorded: #N <subject>` for one whose `ledger.mjs filed`
2321
+ > failed twice — and exit. **Deferring everything is a normal
2322
+ > outcome, not a stall:** nothing is then staged, `git commit` refuses an empty
2323
+ > index, `git push origin HEAD:<branch>` prints `Everything up-to-date`, and you
2324
+ > report `no-op, HEAD unchanged at <sha>` in place of a new SHA. Say it
2325
+ > explicitly — silence there is indistinguishable from a member that died. Never
2326
+ > manufacture a commit to make CI fire.
2327
+
2328
+ **Put the standing CI facts in that prompt, not in per-event messages** —
2329
+ otherwise you send "your red is staleness, do not rebase" once per member per
2330
+ merge. `review-and-fix.md` states them; the prompt only has to say they apply.
2331
+
2332
+ **The fix-applier pushes and exits — it does not hold the CI wait.** You own the
2333
+ persistent Monitor; a turn-based member re-reading `gh pr checks` each idle cycle
2334
+ rebuilds a 100k-token context for nothing the Monitor lacks. The prompt block
2335
+ above carries the report-last rule; you do not have to restate it. When the
2336
+ diff-validating `check` job is green **and no
2337
+ heavy job is in `failure`** (the heavy diff-validating suites — not the
2338
+ `rebase-check` currency gate; a `skipped` heavy job is behind-count staleness and
2339
+ fine — **solely** off that count, which is a condition to establish rather than
2340
+ infer, see the five-condition note in the fix-applier block above) — or
2341
+ `ci-state.mjs` reads `verdict: "no-ci"`, see below — **and once the PR's review
2342
+ has returned and its fix-applier, if one was dispatched, has sent its report,
2343
+ which the CI-completes edge above states in full** — dispatch a
2344
+ **finisher** — a fresh small agent, not the fix-applier resumed. **Dispatch it
2345
+ by its own definition and omit `model` on the call** — the tier (`haiku`)
2346
+ lives in `agents/fleet-finisher.agent.md`:
2347
+
2348
+ `fleet-finisher`.
2349
+
2350
+ Record it with `ledger.mjs dispatch <pr#> finisher-pr-<pr#>` before the call.
2351
+ Its four duties are a checklist — audit the
2352
+ worktree, confirm every deferral has a tracker home and re-run the acceptance
2353
+ mutation, apply one release label, report — and the
2354
+ merge gate downstream still catches whatever it gets wrong, the same argument
2355
+ that puts the merge bot on the same tier below. **Never dispatch
2356
+ one while you still owe the fix-applier a ruling**: the pinned SHA is only as good
2357
+ as the guarantee nothing else is inbound. **The test is your OUTBOX, not the
2358
+ member's last message** — anything you have decided that it has not received,
2359
+ including a ruling you have since **withdrawn or reversed**. **That is the test
2360
+ of THIS condition only**: an empty outbox says nothing is inbound from you, and
2361
+ nothing about whether the member considers itself finished, which is what the
2362
+ report condition above is for. A withdrawal you
2363
+ recorded only in the ledger is undelivered: the member still holds the original
2364
+ and will act on it. Relay everything — reversals too — then dispatch.
2365
+
2366
+ **An unanswered question from the member is an outbox item, and it blocks
2367
+ dispatch with the same weight as a ruling you have already made.** It does not
2368
+ feel like one — you have decided nothing yet, so the outbox reads empty — but a
2369
+ member waiting on you is a member that will push once you answer, and the SHA
2370
+ you are about to pin is exactly what that push moves. Measured on #488's run:
2371
+ `fix-pr-488` asked whether to add two pins, and the finisher was held until the
2372
+ member acknowledged the answer. That worked because the controller chose to
2373
+ hold, not because a rule required it. Answer it, or tell the member you are not
2374
+ ruling and it should proceed on its own default — either empties the outbox.
2375
+ What does not empty it is noticing the question and dispatching anyway.
2376
+
2377
+ **A final report is not proof the member stopped.** Observed twice: a ruling
2378
+ relayed after dispatch produced a new commit mid-audit, and a fix-applier that
2379
+ reported "nothing outstanding" resumed on a ledger-only withdrawal and was
2380
+ cycling mutants through the worktree when the finisher audited it. Both finishers
2381
+ correctly halted. Note what that costs to detect: two reads of the same worktree
2382
+ a minute apart showed *different* mutants, so a member's report and any single
2383
+ `git status` are each valid only at their instant. Its duties, in this order:
2384
+
2385
+ 1. **Audit the worktree** — run `worktree-audit.sh` (it takes no argument; it
2386
+ audits every worktree in one pass, so find this worktree's row in its
2387
+ output). Match the row by the resolved form of the worktree path you were
2388
+ dispatched with — `realpath <abs-path>`, or `cd <abs-path> && pwd -P` —
2389
+ never by that path as written: the row's `worktree` field is the physical
2390
+ path `git worktree list` reports, so a spelling reached through a symlink
2391
+ (macOS's `/tmp` and `/var/folders` are symlinks too) matches no row on a
2392
+ healthy worktree. Two checks, each with the instrument that can answer it.
2393
+ **Dirty:** the row's `dirty` field, or `git status --porcelain -unormal`
2394
+ inside the worktree itself — the explicit mode, never bare `--porcelain`, or
2395
+ `status.showUntrackedFiles = no` reads a dirty worktree as clean (#730). The
2396
+ row is the better read: in a worktree whose `.git` linkage is missing,
2397
+ `git status` answers for the enclosing repo at rc 0, where the audit reports
2398
+ the worktree unreadable. **Diverged:** the worktree's `HEAD` against your
2399
+ dispatch pin — the cause block's head-equality check below. Neither
2400
+ instrument above answers it: `git status --porcelain` reports no commits,
2401
+ and the row's `ahead` is counted against `origin/main`, which a PR worktree
2402
+ is always ahead of, so it cannot answer this. Three row shapes halt too,
2403
+ each named in the report with the script's stderr line quoted where it
2404
+ prints one: `readable:false` with `null` counts
2405
+ (`UNREADABLE: <wt> (<cause>)`) is *worktree unreadable*, `readable:false`
2406
+ with zero counts (`MISSING on disk: <wt>`) is *worktree missing*, and no
2407
+ row for this worktree at all is *worktree absent*. `git status` is no
2408
+ substitute for the audit here — it answers the dirty check only, and a
2409
+ finisher that cannot see the tree it labels cannot vouch for it. Dirty,
2410
+ diverged, unreadable, missing or absent halts the finisher *here*, before
2411
+ the label: it reports what it found and labels nothing. A finisher that
2412
+ verifies the dirt is harmless and labels anyway has substituted the rule's
2413
+ purpose for the rule, and you find out at merge time. **Give it the cause block below,
2414
+ verbatim** — a bare SHA mismatch names no cause, and the halt report needs
2415
+ one. **Give it `<testCmd>` too** — the same string you passed the workflow
2416
+ and the fix-applier — because duty 2's mutation gate runs it and nothing
2417
+ else hands the finisher one; substituted with nothing it leaves that gate
2418
+ no command at all.
2419
+ 2. **Confirm every deferral — and every claimed APPLY — has a home that outlives
2420
+ the merge.** The test is a durable home, not a tracker number: a tracker
2421
+ issue and a committed in-tree comment both qualify, and for a finding whose
2422
+ remedy was measured worse than the defect the in-tree note is the better one.
2423
+ What fails is a promise living only in a PR body, or on the PR's *own* source
2424
+ issue, which `Closes #N` buries on merge. Caught once at seven findings. A
2425
+ comment on an existing *follow-up* issue is filed: that is
2426
+ `review-and-fix.md` step 5, not a violation. Not filed → file it or halt,
2427
+ never label over it — and file it the way step 5 does, through
2428
+ `ledger.mjs check "<subject>"`, never a bare search. The finisher files last,
2429
+ off its own read of what the reviewer left behind, so a deferral it reads as
2430
+ unfiled may already be on the tracker under someone else's wording. Then
2431
+ record it the way step 5 does: `ledger.mjs filed <N> "<subject>"`
2432
+ immediately after `gh issue create`, with the same subject string you passed
2433
+ to `check`. If `filed` fails, retry once; if it fails again, leave the issue
2434
+ alone — it exists and is correct — and report it `unrecorded: #N <subject>`.
2435
+
2436
+ **A fix-applier's "applied" is a claim like any other**, and nothing else
2437
+ checks it — the review ran against a snapshot cut before those edits existed.
2438
+ Confirm `git diff origin/main...HEAD` actually contains what it reported
2439
+ applying. Two finishers in one run extended duty 2 this way unprompted, and
2440
+ one found five applies where the controller's hand-written list named three:
2441
+ a controller's list of what to verify is itself a claim.
2442
+
2443
+ **That range is right for the positive check and wrong for a negative one.**
2444
+ It spans the implementer's commits too, so a constraint of the form *file X
2445
+ was not touched* has to be scoped to the apply commit. Measured on PR #776:
2446
+ a controller wrote "neither document was touched" against
2447
+ `origin/main...HEAD` on a two-commit branch whose documents the IMPLEMENTER
2448
+ had correctly edited — the PR's whole point — and a finisher reading that
2449
+ literally halts a correct PR. It caught the error instead, and said so; do
2450
+ not rely on that.
2451
+
2452
+ **Whatever you verify by RUNNING, run in a tree nobody else owns.**
2453
+ Independently re-running the ticket's acceptance mutation — loosen the
2454
+ regex, delete the guard clause, flip the per-entry reset, run `<testCmd>`,
2455
+ watch it redden, discard — is the half of this duty reading a diff cannot
2456
+ do, and it stays. But it **writes**, and the PR's worktree belongs to
2457
+ another member. Measured on #380: a finisher was inside that worktree at the
2458
+ instant the fix-applier announced one more clause to land, and neither
2459
+ ordering is detectable afterwards from the diff — a restore lands on the
2460
+ uncommitted clause and destroys it silently, or the mutant is still in the
2461
+ tree when the fix-applier commits and a deliberately broken guard ships as
2462
+ the fix, in a commit nothing re-reviews. So take your own:
2463
+ `git worktree add --detach <scratch>/pr<N>/finish-<your member name> <your dispatch pin>`,
2464
+ mutate and run `<testCmd>` in there, then
2465
+ `git worktree remove --force <scratch>/pr<N>/finish-<your member name>`.
2466
+ **At your dispatch pin, never at the fetched branch tip** — duty 1 just
2467
+ proved the owned worktree sits at that pin, and `PR headRefOid` may carry
2468
+ commits no reviewer read, the substitution the halt block's head-equality
2469
+ check rejects for the same reason. The member name is in the path because
2470
+ the scratch root is shared with every sibling, so `<scratch>/pr<N>` alone
2471
+ collides whenever a PR gets a second finisher, and `worktree add` on an
2472
+ occupied path fails closed into a halt with a purely mechanical cause.
2473
+
2474
+ **Remove it on every path, the failing ones included** — a mutant that comes
2475
+ back green, a suite that will not start, your own halt at any duty. `--force`
2476
+ is required and is right only here: the tree is deliberately dirty when you
2477
+ are done, so a plain `git worktree remove` refuses it (`contains modified or
2478
+ untracked files`, rc 128, directory left on disk — measured, git 2.50.1),
2479
+ while everywhere else in this runbook that refusal is a finding precisely
2480
+ because the dirt may be someone's only copy. Here nothing in it is anyone's.
2481
+ Nothing sweeps a leak for you either: `reap.sh`'s branchless sweep is bounded
2482
+ to the fleet's worktree home, so a tree under `<scratch>` is a `kept` entry
2483
+ it reports and never collects. The tree you added is a checkout, so since #55
2484
+ it carries the tracked `./agent-test` like any other — run either that or
2485
+ `<testCmd>` in it, per **A reused worktree may lack the runner** above.
2486
+
2487
+ **None of this licenses a write to the owned worktree.** Duty 1 is a read;
2488
+ you never restore that tree, because you never wrote to it. A controller
2489
+ instruction to restore mutated paths there is an instruction to perform the
2490
+ silent-destruction ordering above — report it back, do not run it. One
2491
+ finisher refused exactly that instruction live, on the grounds it could not
2492
+ prove the diff was its own; that was judgement, and this is the rule.
2493
+ 3. Add `ready-to-merge` — after reading the PR's labels back
2494
+ (`gh pr view <pr> --json labels`) and finding **exactly one** release label,
2495
+ `patch`/`minor`/`major`. Zero or more than one halts the finisher before the
2496
+ label, naming which it found. This is the backstop for a label lost wherever
2497
+ it was lost, a hand-created PR included: a `gh pr create` that outran its
2498
+ caller's tool timeout leaves the PR open with the flag unapplied and no exit
2499
+ status anywhere to notice, and nothing downstream re-derives the release
2500
+ label. Count only those three — the PR carries other labels, `ready-to-merge`
2501
+ itself among them once you add it, so a PR wearing one release label beside
2502
+ them passes unchanged. A repo that defines none of the three does not gate on
2503
+ one — `gh label list` settles that, and it is no licence to skip the read
2504
+ where they exist.
2505
+ 4. Report you the label, the deferral issue numbers — a
2506
+ `filed: #N <subject>` line for every issue duty 2 created, and
2507
+ `unrecorded: #N <subject>` for one whose `filed` failed twice — and anything
2508
+ it halted on — cause and evidence, below, never a bare "head moved". The
2509
+ cause is one word of the ledger's `halted:<cause>` vocabulary:
2510
+ `live-editor`, `rebase` or `past-pin` from the cause block below,
2511
+ `unreadable`, `missing` or `absent` from duty 1's row shapes, and `other`
2512
+ for every other halt — the block's *anything else*, and a halt at duty 2,
2513
+ duty 3, the instrument re-check or the CI gate. A `rebase` halt's report
2514
+ carries the output of `git cherry <pin> HEAD origin/main`, run in the
2515
+ worktree.
2516
+
2517
+ **Give the finisher the instrument re-check verbatim too.** Duty 1 and duty 2
2518
+ each run a script the digest covers — `worktree-audit.sh` and `ledger.mjs`,
2519
+ both under `plugin/scripts/` — and the label at duty 3 rests on what they
2520
+ returned. The rule is stated once, at the top of this file, which no finisher
2521
+ is dispatched to read, so it reaches one through this block or not at all:
2522
+
2523
+ > **Re-check the instrument set before you act on what duty 1 or duty 2 read,
2524
+ > and again before you add the label.**
2525
+ > `~/.fleet/bin/fleet-run instruments.sh --repo "$(dirname "$(env -u GIT_DIR -u GIT_WORK_TREE git rev-parse --git-common-dir)")"`.
2526
+ > Exit 0 is the only code that lets you go on. Exit 1 (the set changed) and
2527
+ > exit 2 (the check could not answer) both halt you: report what it printed,
2528
+ > add no label, and do NOT re-read the script that gave you the reading.
2529
+ > `--repo` is required and the spelling is the point — the run's baseline lives
2530
+ > in the audited checkout's gitignored `.fleet/`, which the scratch worktree
2531
+ > you take at duty 2 does not carry, so a bare invocation from there exits 2 on
2532
+ > a missing baseline instead of comparing anything. The `env -u GIT_DIR -u
2533
+ > GIT_WORK_TREE` wrapper guards against an ambient `GIT_DIR` in your own shell
2534
+ > pointing this check at the wrong tree — the script's own internal unset
2535
+ > cannot reach back and fix a path you already resolved wrong. The baseline
2536
+ > itself names the tree to audit: a cross-workspace run pinned it once at
2537
+ > phase 0, and your `--repo` only locates that baseline, never the audited
2538
+ > tree — so an exit 2 naming a moved or unreadable audited tree is a halt
2539
+ > like every other, not a spelling for you to correct.
2540
+
2541
+ **Once the label is on, take it off before you approve any push.** The label is a
2542
+ verdict on the tree the finisher read, and a GitHub label does not follow the
2543
+ branch — on #180 it survived a push and came to sit on a commit nobody had
2544
+ audited. Remove `ready-to-merge` *first*, then approve: removing the artifact the
2545
+ merge bot gates on is the reliable stop, where messaging the bot races it, and a
2546
+ label has been observed holding until after an abort message arrived. Then
2547
+ dispatch a **fresh** finisher against the new head; the first audit does not
2548
+ transfer, since it verified a different tree. The merge bot refuses that head on
2549
+ its own (`run-merge-bot.md`, **The labelled head**), so this is not the only
2550
+ guard — but its refusal costs a pass and leaves the label lying, which is yours
2551
+ to clear either way.
2552
+
2553
+ A halt at step 1 reads identical from a bare SHA mismatch whatever caused it,
2554
+ and the causes below are the ones seen so far, not a closed list. Give the
2555
+ finisher this verbatim, so it derives the cause itself instead of asking anyone:
2556
+
2557
+ > Worktree differs from your pin, or from what you last read. **Check
2558
+ > head-equality first: `worktree HEAD == the SHA you were dispatched against` on
2559
+ > a clean tree settles it.** Against your dispatch pin, never against
2560
+ > `PR headRefOid`: a member that kept working and pushed after the pin matches
2561
+ > the branch tip on a clean tree, so a headRefOid comparison reports "settled"
2562
+ > over commits no reviewer read — the exact divergence this halt exists to
2563
+ > catch. `headRefOid` is a second, separate read (pushed vs unpushed), never the
2564
+ > equality the halt turns on. A rebase entry sitting at or behind the pin is
2565
+ > that head's provenance — the implementer's own pre-push replay — not
2566
+ > divergence from it, and needs no adjudication at all. Three finishers in one
2567
+ > run adjudicated a reflog this one check had already answered. Only when the
2568
+ > head differs from your pin, work out what happened. Each cause below is cheap
2569
+ > and self-checkable, and `anything else` is a cause too, not a gap:
2570
+ >
2571
+ > - **Live editor.** `git status --porcelain -unormal` is dirty. Sample
2572
+ > `git diff --stat` twice, a minute apart — diffstat growing means someone
2573
+ > is still writing. Halt, name `live-editor`, report both samples.
2574
+ > - **Rebase.** `git status --porcelain -unormal` is clean, head still differs
2575
+ > from your pin. `git reflog` in the worktree: a `reset`/rebase entry near
2576
+ > the move, not a plain `commit`, means the branch replayed onto a new
2577
+ > base — its own commits on a new parent, content-identical only on a
2578
+ > conflict-free replay.
2579
+ > Halt, name `rebase`, report the reflog line and the output of
2580
+ > `git cherry <pin> HEAD origin/main`, run in the worktree.
2581
+ > - **Work past the pin.** `git status --porcelain -unormal` is clean, head
2582
+ > still differs from your pin, and `git reflog` in the worktree reads a plain
2583
+ > `commit` at the move — no `reset`/rebase entry there, any of those sitting
2584
+ > at or behind the pin as provenance. A member kept working and committed
2585
+ > after you were dispatched. Measured 2026-08-28 on #983, where the finisher
2586
+ > matched neither cause above and halted on its own judgement (#997).
2587
+ > Halt, name `past-pin`, and report **the commit, and whether it
2588
+ > is pushed, unpushed, or unknown**: `git log -1 --format='%h %s'` names it,
2589
+ > and `git ls-remote origin <branch>` answers the rest — a non-zero exit or
2590
+ > any other failed read is **unknown**, never folded into "unpushed": the
2591
+ > same rule `release-ticket.sh`'s own `ls-remote` names ("a failure here is
2592
+ > an unknown answer, never a 'no'") and `reaping.md`'s remote check shares
2593
+ > ("its failure is an unknown answer, never a 'not pushed'"). Only a
2594
+ > successful read settles pushed vs not: equal to that commit means pushed,
2595
+ > and a fresh finisher can audit it; a successful read that comes back
2596
+ > without it means the commit exists only in that worktree, where no
2597
+ > reviewer can reach it. Ask the remote, not the PR object, whose head lags
2598
+ > a ref move — the same field `run-merge-bot.md` refuses to poll, for that
2599
+ > reason. The controller's next move differs between pushed, unpushed, and
2600
+ > unknown, so a report naming only two of the three is not a report of this
2601
+ > cause.
2602
+ > - **Anything else.** Matching none of the above is not a licence to report
2603
+ > the mismatch as unexplained — that report is the one this block exists to
2604
+ > make unnecessary, and it is where labelling over a moved head starts
2605
+ > looking reasonable. Halt, name `other`, and name what you did find: both
2606
+ > `git status --porcelain -unormal` samples, the `git reflog` line at the
2607
+ > move, and both SHAs. A cause nobody has named yet is still a cause you
2608
+ > observed, and your report is what gets it named.
2609
+ >
2610
+ > Every cause halts, always — named or not, you never verify the dirt is
2611
+ > harmless and label over it, a rebase is not a fast-forward you get to accept,
2612
+ > a commit past the pin is not one either, and a cause you could not name is
2613
+ > the least settled of the lot. Naming the cause makes the halt cheap to
2614
+ > resolve, never a reason to skip it.
2615
+
2616
+ **Resolving a finisher halt.** A halt is the finisher working correctly — it
2617
+ refused to label — so it is never `failed`, which stays for a finisher that
2618
+ crashed or gave up. Record it `ledger.mjs settle finisher-pr-<M>=halted:<cause>`,
2619
+ `<cause>` the word the report names; the ledger refuses any other. Every halt
2620
+ escalates two ways: the cockpit flags the PR `halted:<cause>` at severity 4 off
2621
+ that token, and you post the finisher's halt report — cause and evidence — with
2622
+ `gh pr comment <M>`, so it outlives the run. **No label**: the missing
2623
+ `ready-to-merge` already keeps the PR out of the merge queue. Then the cause
2624
+ decides the rest — two resolve automatically, every other one escalates:
2625
+
2626
+ | Cause | Resolution |
2627
+ |---|---|
2628
+ | `live-editor` | **Automatic.** Ask the live member **by name** for its report, wait for it, then dispatch `finisher-pr-<M>-b` at the current head. If the head moved in the meantime, resolve it as `past-pin` instead. |
2629
+ | `past-pin` | **Automatic, through the tick: re-review.** The head carries commits no reviewer read. The tick prints `DISPATCH review PR#<M>` for a PR whose latest finisher is `halted:past-pin` and whose latest `reviewed=<head>` is not its current head, until a review of it is running or has returned; record that review's tokens as any review's, and its result reaches a fresh finisher through the same gate. |
2630
+ | `rebase` | **Escalate** — comment and flag, nothing more. Read the report's `git cherry <pin> HEAD origin/main`: only `-` lines is a clean rebase, and a `+` line is a conflict resolution that changed content or a commit past the pin. No automatic rule until a live halt shows the case recurring. |
2631
+ | `unreadable`, `missing`, `absent`, `other` | **Escalate** — comment and flag, no automatic retry. |
2632
+
2633
+ `past-pin` needs the tick because the dead-review path cannot reach it: once a
2634
+ review has **returned**, its `reviewed=` token holds the PR out of `review-due=`,
2635
+ and settling that review `=failed` re-queues nothing — that path covers only a
2636
+ review that died before returning. A head that moved past `reviewed=` with no
2637
+ such halt — a fix-applier's push — stays not due: duty 2 verifies what it
2638
+ applied.
2639
+
2640
+ Gate on the `check` job, **not** on `ci-state --quiet` exit 0: a behind PR never
2641
+ reaches full green, so an exit-0 gate strands it unlabelled. The finisher reads
2642
+ per-job state (`ci-state.mjs` without `--quiet`, or its `jobs`), since `--quiet`
2643
+ drops `jobs` and `missing`. Normal path, not only kill-recovery.
2644
+
2645
+ **`ci-state.mjs` reads `verdict: "no-ci"`** — no `check` job exists in this repo
2646
+ to gate on, and that is not a third way to skip the wait. **The
2647
+ `--declare-no-ci` declaration is caller-side, and reading it back out of the
2648
+ payload verifies nothing**: the flag is echoed into `reasons` and flips the exit
2649
+ code, so re-running with it and finding it there confirms only that you passed
2650
+ it. Passing it yourself is not a second opinion. Check the two facts it stands
2651
+ for instead:
2652
+
2653
+ 1. `ci-state.mjs` **without** the flag still reads `verdict: "no-ci"`. A repo
2654
+ whose CI is merely misconfigured — workflow files present under other names,
2655
+ or `.github/workflows/` unreadable — exits 2 there rather than reading no-ci,
2656
+ so this is the check that separates real absence from misconfiguration, the
2657
+ case that must never ship silently.
2658
+ 2. The reviewer's own final verdict reports a green `testCmd` run on the SHA it
2659
+ pushed. `review-and-fix.md` step 3 requires it to, and that run is the only
2660
+ gate this repo actually has.
2661
+
2662
+ Both → add the label, and say it rests on the reviewer's suite run, not on CI.
2663
+ Either missing → halt here, same as a dirty worktree: report `no CI configured,
2664
+ no verified suite run on record` and add no label.
2665
+
2666
+ **Correction tickets ship new wrong claims — inherited from the ticket, and
2667
+ minted in prose the ticket never asked for.** Put the check on the
2668
+ **implementer**, not only the reviewer: every factual claim the diff restates
2669
+ must have a settling command run against the tree first — the issue body is a
2670
+ lead, never a citation — and the diff must **match the ticket's stated size**,
2671
+ since added prose is where minted claims enter. No positional references (`the
2672
+ closing/second/last X`); name the thing semantically. Evidence from a run on
2673
+ **another repo** is cited by host: a github.com source as `owner/repo#N`;
2674
+ anything else (GHE, GitLab, internal) as prose naming host and repo and saying
2675
+ it cannot be settled from this repo — a bare `#N` stays bare only for this
2676
+ repo's own issues and PRs. The workflow's `comments`
2677
+ dimension checks every added assertion against the tree, including comments in
2678
+ files the diff does not touch; a fallback reviewer has to be told that *and* told
2679
+ to read each corrected sentence literally, clause by clause.
2680
+ See references/correction-tickets.md.
2681
+
2682
+ **But the discipline follows the DIFF, not the class — hand it to any
2683
+ implementer whose diff writes prose.** Phase 2 selects it on `class=correction`,
2684
+ and that selection is too narrow: a `routine` ticket that adds a test fixture, a
2685
+ helper, or a coverage case writes comment prose too, and prose is where minted
2686
+ claims live. Measured twice in one run, both `class=routine`, both therefore
2687
+ dispatched WITHOUT this block: PR #756 added an unasked-for comment asserting a
2688
+ silent-failure mode that does not exist (gross PATH damage is loud — 10 of 39
2689
+ tests red), and PR #768 minted a false comparative ("the cheapest of the four to
2690
+ tear down, not the dearest", when its route is the only one of four needing any
2691
+ in-body teardown) **and** introduced two positional references replacing a
2692
+ name-based one. Neither ticket asked for either sentence.
2693
+
2694
+ Two of the rules above are what caught both, so give them to every implementer
2695
+ regardless of class: **every factual claim the diff restates needs a settling
2696
+ command first**, and **no positional references**. A third earns its place here
2697
+ — **never write a COUNT or a tally into prose; state the property instead** —
2698
+ unless it is a past-tense record of a measurement you performed, which stays
2699
+ as written; a present-tense claim about a live property must be restated as a
2700
+ property (`every other test in the file`), true at any count. A
2701
+ count is false the moment the next commit lands, and #768 falsified two of them
2702
+ (`the only other chmodSync(..., 0o644)`, already off by one before it; `fails 75
2703
+ of the 85 cases`, measured 81 of 91) in a file whose own header records having
2704
+ shipped a stale count once already. The immutable-body rule earns the same
2705
+ place: **every claim a commit body or a PR body asserts needs its settling
2706
+ command re-run at the commit that ships it, and written inline beside it.**
2707
+ The literal-text `-F` rule earns the same place: **a settling command over
2708
+ literal text uses `grep -F`, and its zero counts only after the same
2709
+ command, with the same flags, finds a line known to match.** Measured on
2710
+ #1087, the same false zero fired twice in one run. A relayed enumeration
2711
+ delivers only what it names, so this list is the whole of what a controller
2712
+ hands over, never a preface to it.
2713
+
2714
+ **One more rule, and the one the diff cannot carry: a claim written into a
2715
+ commit body or a PR body needs its settling command re-run at the commit that
2716
+ ships it, not at the commit that motivated it — and the command goes inline,
2717
+ beside the claim.** The rules above scope to prose the diff restates, and a
2718
+ pushed commit body is not in the diff: it cannot be edited, only retracted by a
2719
+ later commit, which is itself a fresh unverified historical claim. So the check
2720
+ has to sit at write time, and review-time is already too late. The claim types
2721
+ are wider than measurement — a line number, a SHA, an **attribution** of who
2722
+ said what, a positional reference and a count all rot the same way, and an
2723
+ attribution is the worst of them, because the argument it carries collapses
2724
+ when it turns out false, while a wrong line number leaves the surrounding
2725
+ reasoning standing. `Verified:` is the construct a later reader trusts
2726
+ *instead of* re-deriving, so a wrong figure under that header is worse than no
2727
+ figure at all. Measured on #399: `f961cf2` and `acce6ee` both close `Verified:`
2728
+ with `86/86 across both test files` naming the suites that read this file, a
2729
+ file set the tree does not bear out — `git log -1 --format=%b <sha> | grep -A2
2730
+ Verified:` shows what each shipped. Inline is what makes the difference visible:
2731
+ a claim carrying the command that produces it can be re-run instead of trusted.
2732
+ A claim whose settling command cannot be written is still not one to assert
2733
+ bare: settle it inline, mark it unsettleable from this repo per the citation
2734
+ convention above, or drop it. The marker ending is not a loophole but the case
2735
+ that convention already sanctions: it directs foreign evidence to be asserted as
2736
+ prose saying it cannot be settled from this repo, and that marker is itself what
2737
+ tells a later reader not to trust the claim instead of re-deriving it, which is
2738
+ the property this rule protects.
2739
+
2740
+ **The settling command for "which files read X" must never be a literal-path
2741
+ grep.** The path is assembled in more than one spelling here, one of them behind
2742
+ a local `read` helper, so a grep for the path string answers with the files that
2743
+ merely *name* it — comments included — and misses the files that build it.
2744
+ Replace the file with `MUTATED` in a throwaway copy, run the suite, and read off
2745
+ which suites red: that answers which ones **depend on its contents**, which is
2746
+ the question a coverage claim actually needs, and it returns a different set
2747
+ from any spelling of the grep.
2748
+
2749
+ **A settling command over literal text uses `grep -F`, and its zero counts only
2750
+ after the same command finds a line known to match.** Prose fragments and
2751
+ code snippets routinely carry `\`, `.`, `*`, `[` or `$`, and without `-F` those
2752
+ are read as a pattern rather than as the text itself, so the command answers
2753
+ for a different string from the one the claim names — and a wrong zero is the
2754
+ benign-looking answer. Measured on #1087: `grep -c 'settled by:\s+x'` answers
2755
+ 0 against a file holding that exact line, and `grep -cF` answers 1. A zero or
2756
+ an absence counts only after the same command, with the same flags, finds a
2757
+ line known to match: a command that cannot find a match settles nothing, and
2758
+ under `Verified:` its zero reads as a checked absence.
2759
+
2760
+ #### Fallback: hand-dispatched reviewer member
2761
+
2762
+ Only where the review unit is unavailable **or has failed** — never a
2763
+ preference. "Unavailable" is the review unit not being there to dispatch at
2764
+ all; "failed" is the failure event above, surviving its one retry. A review that
2765
+ is present and failing is not absent, and reading this line as absence-only
2766
+ leaves the likeliest failure with no sanctioned path at all. One named member
2767
+ per PR — `review-pr-<pr#>`, or `review-pr-<pr#>-b` where a runner already held
2768
+ that name — never its implementer, recorded as
2769
+ `review=fallback:review-pr-<pr#>[-b]` on the PR's row. It runs off your turn
2770
+ like the review it replaces. Give it the PR number and tell it to read
2771
+ `$(~/.fleet/bin/fleet-run --root)/commands/review-and-fix.md` — the resolved file
2772
+ path, not a slash invocation; command availability inside a member is not
2773
+ guaranteed the way skill availability is. It then does the fix-applier's job too:
2774
+ apply, defer, file, push, report, exit. On its report, record
2775
+ `reviewed=<head>:0/<refuted>/<deferred>` against the head it pushed — it applied
2776
+ its own survivors, so the zero is what tells the tick no fix-applier is owed —
2777
+ and it reaches a finisher through the same gate as any other PR.
2778
+
2779
+ **Authorize the fan-out explicitly.** State that the full specialist set IS the
2780
+ requested work — otherwise the reviewer inherits the standing "do not call the
2781
+ AgentTool unless requested" and silently downgrades to a thinner solo review.
2782
+ Nothing computes the count here, so apply the heuristic yourself: two or three
2783
+ specialists for annotation-only or single-file, the full set for production code.
2784
+ See references/member-lifecycle.md.
2785
+
2786
+ **Delivering specialist reports is your duty on this path, not the reviewer's.**
2787
+ Reports surface to *you* and grandchildren are unaddressable, so a reviewer must
2788
+ never be told to ping for one. But it **can** read the report itself: a specialist
2789
+ it spawned writes its transcript to the output file named in its spawn result, and
2790
+ `tail -1 <file> | jq -r '.message.content[]?|select(.type=="text").text'`
2791
+ extracts the final report — bounded, unlike reading the whole file. State that in
2792
+ the prompt: retrieve first, ask you by name only if the file yields nothing, and
2793
+ rule a dimension **unrun** only when neither works — not silently, and not after
2794
+ waiting forever, since a killed specialist never reports and never gets relayed.
2795
+ See references/member-lifecycle.md.
2796
+
2797
+ So two obligations enter the event loop for as long as a hand-dispatched reviewer
2798
+ is live:
2799
+
2800
+ - **A specialist report lands** (a task-notification from a grandchild you never
2801
+ dispatched) → **relay it to the reviewer that owns the PR — source named, text
2802
+ included.** Relay anyway even though the reviewer can retrieve it itself — a
2803
+ duplicate costs nothing, a missed report costs a verdict. Telling it to ping the
2804
+ specialist does not work either — a depth-2 member cannot dispatch
2805
+ further, so the reviewer has no path to its own un-nameable children
2806
+ beyond reading their output file.
2807
+ - **A reviewer's verdict claims a dimension went undelivered** → reconcile it
2808
+ against your relay receipts before accepting it. Receipts say relayed → re-send
2809
+ naming the specialist and hold that verdict until it lands; a relay can arrive
2810
+ after a verdict is already composed. Only you hold the msg id, so only you can
2811
+ catch this — the reviewer cannot tell "no report exists" from "one was sent that
2812
+ I have not received". One reviewer ruled a relayed dimension "not covered by a
2813
+ specialist" and shipped a headline claim that report refuted.
2814
+
2815
+ Neither belongs in a workflow-path prompt: there `agent()` returns into the
2816
+ script, no relay ever occurs, and a rule to wait for one strands every finding.
2817
+
2818
+ **Same receipts gate the finisher dispatch** — dispatch only once every
2819
+ specialist report you know landed for this PR is relayed, none unrelayed. The
2820
+ reviewer applies findings and pushes as each relay lands, so an
2821
+ unrelayed report is exactly as inbound as a fix-applier ruling you haven't sent
2822
+ (above) — dispatch past it and you pin a SHA the reviewer is about to move past.
2823
+ Necessary, not sufficient — a reviewer re-reading its own inbox late still moves
2824
+ the head, which is what the halt block's cause list above is for.
2825
+ Vacuous on the workflow path: `agent()` already returned every report before
2826
+ you had a tree to dispatch a finisher against, so nothing is ever outstanding
2827
+ there.
2828
+
2829
+ ### Merge bot
2830
+
2831
+ Per pass, named `merge-bot-<n>`, never two at once. `ledger.mjs dispatch
2832
+ merge-bot` names it before the dispatch call — `n` is 1 + the `merge-bot-`
2833
+ entries already in the ledger's `## Dispatched` list, so it restarts at 1 every
2834
+ run, a replacement for a dead bot takes the next `n`, and nobody counts. Dispatch
2835
+ it on the tick's `DISPATCH merge-bot`: the first `ready-to-merge` label is
2836
+ enough, and it never waits for the finisher's report. Tell it to read
2837
+ `$(~/.fleet/bin/fleet-run --root)/commands/run-merge-bot.md` and run **one**
2838
+ pass — drain the queue, re-evaluating after each merge, hold a 15-minute grace
2839
+ for late labels, then report once and exit — and say that you dispatched it,
2840
+ which is what makes it hold that grace instead of arming its own watcher. **Dispatch
2841
+ it by its own definition and omit `model` on the call** — the tier (`haiku`)
2842
+ lives in `agents/fleet-merge-bot.agent.md`:
2843
+
2844
+ `fleet-merge-bot`.
2845
+
2846
+ Rebase, wait for green, check the
2847
+ label, merge is checklist work, and a bad merge still needs the label and the
2848
+ per-job CI state to have been read correctly, which is exactly what a wrong
2849
+ merge later surfaces and a human resolves; `no-undo-audit.sh` is the
2850
+ deterministic, script-driven backstop run before every push specifically to
2851
+ catch a wrongly-resolved conflict, so the tier buys nothing that backstop
2852
+ doesn't already cover.
2853
+
2854
+ **Put the shell traps in the bot's brief, not in a follow-up message.** A bot
2855
+ already looping cannot be corrected — the loop consumes the turns a correction
2856
+ would land in. **Every entry in Shell traps, verbatim** — that section is where
2857
+ they are stated once, and this is the seat that has to paste them: the bot
2858
+ reads an exit code off `gh pr update-branch`, `merge-gate.mjs` and
2859
+ `prove-merge.sh`, which is the `PIPESTATUS` and read-only-`status` pair, and its
2860
+ grace poll captures `gh pr list` output and loops over it, which is the
2861
+ assigned-variable trap. The brief always travels with the dispatch.
2862
+
2863
+ **Its merge gate is one script, run twice.** Step 3 of `run-merge-bot.md` is
2864
+ `merge-gate.mjs --pr <n> --pre <sha> [--post <sha>]`: read-only, it runs the
2865
+ instrument re-check, the label and review-decision read and a run-bound
2866
+ `ci-state`, and answers their conjunction — exit 0 mergeable, 1 blocked (the
2867
+ bot reports `<reason>-#<pr>`), 2 could not evaluate. The bot runs it once
2868
+ before any CI wait and again immediately before `gh pr merge`, and merges only
2869
+ on that second exit 0. Nothing but the gate reads `ci-state` on the merge path,
2870
+ so a bot's report names the gate's `reason`, never a field it read by hand.
2871
+
2872
+ **You own the watcher, not the bot.** A dying member takes a watcher down with it
2873
+ and the queue stops silently. Arm one yourself, `persistent: true`, seeded before
2874
+ the loop so handled PRs do not re-fire.
2875
+
2876
+ **Every merge invalidates every other open PR, silently.** The rest show *stale
2877
+ green* until something re-triggers, then flip to `rebase-check: FAILURE` with the
2878
+ slow jobs skipped. Behind-count is the only honest signal.
2879
+ See references/ci-and-staleness.md.
2880
+
2881
+ **One rebase per PR, at merge time.** The bot establishes currency once, when the
2882
+ PR is the merge candidate; requiring it earlier costs a full CI cycle per sibling
2883
+ merge. Any behind-count you hand a bot is expired on arrival; say so. See
2884
+ references/ci-and-staleness.md.
2885
+
2886
+ `run-merge-bot.md` carries the mechanics — intra-pass re-checks, run-binding, the
2887
+ ancestry proof, post-rebase red triage. Do not restate them here.
2888
+
2889
+ ### Reap after each merge pass
2890
+
2891
+ A merge deletes the remote branch and leaves the local branch `[gone]` with its
2892
+ worktree — and its `node_modules` — still on disk. Reap after **each** merge pass,
2893
+ not once at the end: a stale worktree still answers `git worktree list`, so the
2894
+ in-flight probe (`inflight.sh`, run by the Shortlist and by every Pull) reads an
2895
+ already-merged ticket as taken and the queue quietly shrinks. The trigger is the
2896
+ bot's one exit report, and it reaps every time — a pass that merged nothing
2897
+ included (phase 3, **Merge-bot pass reports done**). See references/reaping.md.
2898
+
2899
+ `~/.fleet/bin/fleet-run reap.sh --apply` recomputes every precondition
2900
+ inside the same invocation as the delete — `for-each-ref` for `[gone]`, `git
2901
+ cherry origin/main` to authorize `-D`, worktree removal without `--force` — and
2902
+ reports reaped and kept-with-reason counts. Update the reaped tickets' ledger rows
2903
+ in the same step. See references/reaping.md.
2904
+
2905
+ **It sweeps detached worktrees too — the shape a `[gone]` walk structurally
2906
+ cannot see.** Bounded to `.worktrees/`, so a checkout of yours outside it is
2907
+ reported, never removed. Read `worktreesRemoved` alongside `reaped`: a pass that
2908
+ reaps branches and removes no worktrees is a finding, not a quiet success.
2909
+ See references/reaping.md.
2910
+
2911
+ **Do not invoke `commit-commands:clean_gone`.** It runs `git branch -D` and
2912
+ `git worktree remove --force` with no merged check at all — nothing there stops it
2913
+ deleting a branch, or discarding a member's uncommitted work, that exists nowhere
2914
+ else. The skill is the maintainer's to fix; do the reap yourself.
2915
+ See references/reaping.md.
2916
+
2917
+ **Never reap a branch a live member is on.** Cross-check `.fleet/ledger.md` first:
2918
+ a row without a terminal state means someone may still be in that worktree, and
2919
+ the dirty check does not see a member that committed but has not pushed.
2920
+ See references/reaping.md.
2921
+
2922
+ ### Release the claims that never became PRs — at end of run, and on drain
2923
+
2924
+ Phase 1 is serial and claims ahead of dispatch, so a ticket can be legitimately
2925
+ claimed and then never sent: a collision surfaces after the claim, or the
2926
+ maintainer says drain. The claim still holds the `in-progress`
2927
+ label, a worktree and a branch, and **`reap.sh` will not take them** — the branch
2928
+ is not `[gone]` and has no unique commits, so it is correctly not reapable. Reaping
2929
+ fires after each merge pass and nothing fires at end of run, so the claim survives
2930
+ it and the in-flight probe reads a free ticket as taken next run. Same silent queue
2931
+ shrink as a stale merged worktree, from the opposite end.
2932
+
2933
+ `~/.fleet/bin/fleet-run release-ticket.sh <N> impl-<N> implementer --apply` —
2934
+ the pair the claim took, so the two name the same branch and worktree — is the
2935
+ inverse of the claim, and recomputes its preconditions inside the same
2936
+ invocation as the delete: 0 commits ahead of `origin/main`, no unique commits
2937
+ (`git cherry`), no branch on `origin`, and — whenever the worktree directory is
2938
+ there to read — a clean worktree. Where that directory is established absent the
2939
+ dirty check does not run at all, and `git worktree remove` is no backstop for it:
2940
+ it gates its own clean check on the same `stat`, so the script's absence
2941
+ measurement is sole arbiter there. Two of the four are recomputed a second time
2942
+ at the delete itself: the dirty check by git, which is what `worktree remove`
2943
+ without `--force` is; and the ahead count, re-run against `origin/main`
2944
+ immediately before the branch delete, because a commit can land across the
2945
+ `gh issue view` between the checks and the delete. The `git cherry` and
2946
+ pushed-branch checks are **not** re-run there — a commit landing in that window
2947
+ is ahead of `origin/main` by construction, so the recount covers it. All clear →
2948
+ drops the label, removes the worktree without `--force`, deletes the branch with
2949
+ `-D`, authorized by those two commit checks plus the recount and by nothing else
2950
+ (`-d` measures against local HEAD, and a claim has no upstream, so it refuses a
2951
+ pristine claim whenever local `main` is behind `origin/main` — #760). Any one of
2952
+ them failing → it touches nothing and names the blocker. **That refusal is the
2953
+ finding, never an obstacle**: a claim carrying commits or a pushed branch is not
2954
+ auto-released, ever — run `worktree-audit.sh` (it audits every worktree; find
2955
+ this claim's row in the output) and decide by hand.
2956
+
2957
+ Run it over every claimed ticket with no PR when the run ends or the maintainer
2958
+ drains, and on the spot for a claim abandoned mid-run (a bail before
2959
+ implementing, a collision found after the claim). Update the released tickets'
2960
+ ledger rows in the same step. See references/reaping.md.
2961
+
2962
+ ## Worktree and claim model
2963
+
2964
+ Ruled on #1315, measured 2026-09-09 in a throwaway clone (`/tmp/fleet-probe`)
2965
+ that never touched the real checkout.
2966
+
2967
+ **Claim, release and reap are unchanged on omp.** `claim-ticket.sh`,
2968
+ `release-ticket.sh`, `reap.sh` and `inflight.sh` are git-native and operate on
2969
+ the single shared ref store every worktree and the main checkout read and
2970
+ write directly (**Phase 1**, **Reap after each merge pass**, **Release the claims
2971
+ that never became PRs** above); nothing in omp's `task` model touches that
2972
+ store, so none of the four scripts carries a dialect branch.
2973
+
2974
+ **A fleet member is never dispatched with omp's `isolated: true`.** Measured:
2975
+ an isolated spawn builds its workspace under `~/.omp/wt/<hash>/m` — an APFS
2976
+ clone (on this box), never a registered `git worktree` of the repo — and,
2977
+ because `apply` defaults to `true`, its changes are patch-applied into the
2978
+ **calling session's own cwd** the instant the spawn completes: a file an
2979
+ isolated probe created there appeared as `?? probe-isolated.txt` in the probe
2980
+ session's own cwd — which for an actual fleet run is the controller's main
2981
+ checkout — not in the worktree the prompt named. That is the exact
2982
+ silent-spill hazard this section exists to guard against, on by default, so
2983
+ `isolated` stays unused for every member and `task.isolation.enabled` stays
2984
+ off.
2985
+
2986
+ **A member's tree is the claimed worktree, addressed by absolute path.** An
2987
+ `edit` header without the worktree prefix resolves into the main checkout,
2988
+ where `member-write-guard` refuses it (**You read your instruments out of a
2989
+ tree every member can write to** above). How a
2990
+ member gets its cwd: the `task` tool's item schema — `name`/`agent`/`task`/
2991
+ `outputSchema`/`schemaMode` always, `effort`/`isolated` only when their own
2992
+ settings enable them — carries no working-directory field; measured
2993
+ directly: a member dispatched through it with none of those fields, told
2994
+ only to report `pwd`, returned the calling session's own cwd, not the
2995
+ claimed worktree, the same output an un-`cwd`-set `bash` call gives from
2996
+ that session, so the recipe is the dispatch-prompt absolute path, plus
2997
+ `bash`'s own `cwd` parameter set to it on every call and absolute paths for
2998
+ `write`/`edit`.
2999
+
3000
+ **The one open gap this ticket measured: `task` does not accept a per-dispatch
3001
+ working directory.** `omp://tools/task.md` documents non-isolated spawns as
3002
+ running `runSubprocess(...)` "directly with parent cwd" — no `cwd` field
3003
+ appears anywhere in the item schema — and the probe above confirms it in
3004
+ practice: the recipe is the absolute-path discipline above, not a placeholder
3005
+ for a `cwd` field that does not exist. The gap is now enforced rather than only
3006
+ written down: the plugin's `member-write-guard` omp extension (ADR 0020)
3007
+ refuses a fleet member's `write`/`edit`/`ast_edit` into the main checkout's
3008
+ non-ignored tree and an implementer's `bash` from a main-checkout cwd, and the
3009
+ missing field itself is requested upstream as can1357/oh-my-pi#13754.
3010
+
3011
+ **The same gap reaches past the filesystem: `task`-dispatched members share one
3012
+ `eval` kernel.** Measured 2026-09-21 on #1447, in a live run rather than a
3013
+ probe clone: two sibling implementers dispatched in the same batch, and the
3014
+ controller that dispatched both, reported the same Python kernel pid and the
3015
+ same runner file under `$TMPDIR/omp-python-runner/`, and each read the others'
3016
+ top-level bindings out of its own `eval` cell — a bare `WT` bound by one member
3017
+ was read back by a sibling and by the controller, the collision #1447 was filed
3018
+ on as an unproven self-report. `omp://tools/eval.md` states the mechanism:
3019
+ retained kernels are keyed by `python:${sessionId}`, normalized cwd and
3020
+ interpreter — `js:${sessionId}` for the JS VM — and "Parent and ordinary task
3021
+ subagents may share an inherited eval executor id; children created by eval's
3022
+ own `agent()` explicitly do not." Neither key component separates two members
3023
+ of one run: the session id is inherited from the controller, and the cwd is the
3024
+ main checkout for all of them, because `eval`, unlike `bash`, takes no `cwd`
3025
+ parameter to set. So the absolute-path discipline above is load-bearing inside
3026
+ `eval` too, and it needs one rule `write`/`edit` do not — member-prefixed
3027
+ binding names, since a shared global has no path to be absolute about. The
3028
+ corollary is `reset`: it "is likewise destructive to concurrent work sharing
3029
+ that backend session", so a member resetting its own kernel resets every
3030
+ concurrent sibling's. No per-dispatch knob turns any of this off: `task`'s item
3031
+ shape carries no kernel, executor or cwd field, and `python.kernelMode` set to
3032
+ `"per-call"` — the one documented lever that would hand every call a fresh
3033
+ kernel — is a session setting a child inherits, not something one dispatch can
3034
+ set for one member. Isolating a member's kernel is an omp-side change, so
3035
+ discipline is the whole of the remedy here — unlike the missing `cwd` field
3036
+ above, which `member-write-guard` enforces for `write`/`edit`/`ast_edit` and
3037
+ `eval` bypasses. **Phase 2** carries all three rules to every member.
3038
+
3039
+ **`release-ticket.sh` is not a no-op on omp, and `inflight.sh`'s probes are
3040
+ unaffected by a running member.** Measured against a hand-built claim (a
3041
+ branch plus a `git worktree add`) with a member sleeping inside it: a `bash`
3042
+ call with `cwd` set to the worktree, and a non-isolated `task` spawn told to
3043
+ work there, both operate inside the existing worktree and leave `git worktree
3044
+ list` unchanged — they coexist with the claim rather than duplicating it. An
3045
+ isolated spawn is architecturally blind to the worktree — its relative writes
3046
+ land in its own `~/.omp/wt/…` workspace regardless of the prompt — but it
3047
+ neither removes nor hides the claim, and `~/.omp/wt/` was empty after every
3048
+ isolated run: omp's own teardown touches only omp's own workspace, never the
3049
+ claim. `release-ticket.sh`'s three-artifact teardown (label, worktree, branch)
3050
+ is therefore still necessary. With the member live inside
3051
+ the worktree, `git worktree list` and `git branch --list` from the main
3052
+ checkout reported the claim unchanged before, during and after — `inflight.sh`
3053
+ hides nothing from omp.
3054
+
3055
+ **The controller's own cwd stays the main checkout, unchanged.** Nothing in
3056
+ this section's dispatch recipe — the cwd recipe above, the isolated-workspace
3057
+ measurement, or the teardown scoping — moves
3058
+ where the controller itself runs from.
3059
+
3060
+ ## Queue depth
3061
+
3062
+ - **shortlist** — `.fleet/shortlist.json`'s entries with no `impl-` row and no
3063
+ live `excluded` row: admissible, not yet pulled. The tick's `unclaimed=`.
3064
+ - **supply** — `scanned`, the open `ready-for-agent` tickets `shortlist.mjs`'s
3065
+ candidate scan returned, before any filter. Only a Pull's full read judges
3066
+ decided?, so a shortlist of undecided tickets is supply that every Pull
3067
+ relabels away — and relabelling is what stops it being counted next scan.
3068
+ - **review backlog** — PRs owed a review. `fleet-tick.mjs` counts every
3069
+ open PR without `ready-to-merge` **that closes an issue** and carries no `review=`
3070
+ token on the ledger — one settled `=failed` is owed a review again, and so is
3071
+ one whose latest finisher halted `past-pin` past its latest `reviewed=` head
3072
+ (**Resolving a finisher halt**) — and it
3073
+ prints them as `review-due=`. Exact, not a wider read: the ledger records
3074
+ which PRs are under review or reviewed, so nothing about it is guesswork. The
3075
+ closing-issue test is what keeps it from widening: a chore PR you author
3076
+ yourself closes nothing and is left unlabelled for the maintainer, so no
3077
+ member of the fleet will ever review it, and counting it floors the backlog at
3078
+ a depth nothing in the run can drain — the implementer gate then holds for the
3079
+ rest of the run against a queue of nothing (#590). GitHub's own linked-issue
3080
+ set decides that, not a keyword regex over the body; see
3081
+ `docs/agents/issue-tracker.md`. **That exemption is for the chore PR THIS run
3082
+ authors, never one a PRIOR run left open** — step 0 folds those into this
3083
+ run's review queue, so count one when you reason about backlog BY HAND. **The
3084
+ `fleet-tick.mjs` number still excludes it**: nothing in its filter
3085
+ distinguishes an inherited chore PR from this run's own, since a PR closing no
3086
+ issue fails the closing-issue test either way — folding one in cannot reach
3087
+ the count. So the by-hand judgement and the script's output differ here, and
3088
+ such a PR's review is dispatched by hand.
3089
+
3090
+ **Defaults: 2 implementers, 6 reviewers — no hard cap on either.** Reviewer
3091
+ slots in use ≈ I·(T_review + 0.94·T_fix)/T_impl ≈ 1.95·I (spec 2026-09-24 § 3
3092
+ §3, medians since 2026-08-07: T_impl 19.3 min, T_fix 21.0 min, T_review ~18
3093
+ min, 0.94 fix-appliers per review), so at the default about four of the six
3094
+ are busy, and an idle slot costs nothing. Re-derive it from the map's guard
3095
+ once 20 or more PRs have merged under it, never from one run's rows.
3096
+
3097
+ **The review-backlog gate is narrowed, and the merge-queue depth never gates.**
3098
+ More PRs into a review-bound pipeline buy nothing, but the pipeline is
3099
+ review-bound only when a PR is still owed its review after the tick's own
3100
+ dispatches AND no reviewer slot is left for it — `HOLD (review side
3101
+ saturated)`. A deep backlog with free slots is a `DISPATCH review` on the same
3102
+ tick, never a reason to idle an implementer. A deep `ready-to-merge` queue is
3103
+ *not* that signal at all: each PR rebases exactly once, when it becomes the
3104
+ candidate, so producing more PRs adds no rebases-per-PR — it changes only
3105
+ *when* a given PR is ready.
3106
+
3107
+ **Reconcile, do not wait for an event.** "A slot is free and the shortlist is
3108
+ non-empty" is a *level* condition — re-derive the deficit on **every** tick,
3109
+ whatever woke you: a member finishing, a member bailing before implementing, a
3110
+ merge landing. An edge-triggered loop that only Pulls on completion stalls
3111
+ silently the moment the shortlist empties, because 0 implementers emit no
3112
+ completion event. With the shortlist empty the table below governs — refresh,
3113
+ and never Pull a ticket the shortlist does not hold.
3114
+
3115
+ **Do not re-derive this by hand — `fleet-tick.mjs` computes it.** One invocation
3116
+ prints per-role `actual/target` and an explicit ACTION with the backlog gate
3117
+ above and every row of the table below already applied; every wake in Phase 3
3118
+ ends in it. The deficit is then *computed, not remembered*, which is
3119
+ the whole point: a table you must remember to consult is one you will not
3120
+ consult under a merge-side event storm, and that is how implementers reached
3121
+ 0/target with one approved ticket waiting and ~57 `ready-for-agent` in supply while nobody
3122
+ noticed (#3). What follows stays here as the explanation of what the script decides —
3123
+ never as a second, hand-run copy of it.
3124
+
3125
+ | shortlist (unclaimed) | implementer row prints |
3126
+ |---|---|
3127
+ | ≥ 1 | `PULL #N …`, one head per free slot — a Pull each (phase 1) |
3128
+ | below the cap, missing or empty | the tick refreshes first — `REFRESHED shortlist: n entries; k lifted` — and Pulls from what it found |
3129
+ | 0 after that refresh | `SUGGEST /triage, hold idle` |
3130
+
3131
+ Four holds outrank every row: `HOLD (draining)` once `ledger.mjs drain` has
3132
+ recorded the drain, `HOLD (tier mismatch impl-<N>)` until a replacement is
3133
+ dispatched at the right tier, `HOLD (tier unchecked impl-<N>)` until
3134
+ `tier-check.mjs` has written its verdict on the newest implementer, and
3135
+ `HOLD (review side saturated)` when a PR is still owed its review and no
3136
+ reviewer slot is left for it — refreshing to enable a Pull you are holding
3137
+ buys nothing.
3138
+
3139
+ `/triage` is user-invoked only — suggest, never run. The suggestion is a report,
3140
+ not a blocking prompt. Counts come from cheap `gh issue list --search`, no bodies.
3141
+ A starved implementer queue never stalls the review or merge side.
3142
+
3143
+ ## Invariants
3144
+
3145
+ - Implementers and review units at their caps (default 2 and 6, no hard cap on
3146
+ either), ≤ 1 merge bot. Caps bound *members* and review units, not live
3147
+ agents — members fan out and their children consume slots you never dispatched.
3148
+ - A grandchild surfaces as its own task-notification. An unrecognized task-id is
3149
+ not a member reporting done.
3150
+ - A reviewer never reviews a PR it implemented.
3151
+ - The merge bot only touches PRs whose implementer reported done. Rebasing a
3152
+ worktree someone is working in destroys uncommitted work.
3153
+ - `ready-to-merge` is added by a reviewer only — never an implementer, never you.
3154
+ **The run's own artifact PR is exempt, and it is exempt because this invariant
3155
+ does not reach it:** what the line forbids is a fleet member signing off its own
3156
+ ticket work, which presupposes an issue, an implementer, a `review-pr` run and a
3157
+ finisher, and the data-only close-out PR you author has none of them. Label and
3158
+ merge that one yourself instead of re-deriving a blocker from this line and
3159
+ stranding the rows behind it. The exemption belongs to the run that authors the
3160
+ PR and does not outlive it: one still open when the run ends is a PR a prior run
3161
+ left open, which phase 0 folds into the next run's review queue as ticket work —
3162
+ and a chore PR is not exempt from being wrong, only from waiting on a reviewer
3163
+ no phase of this run will ever dispatch against it.
3164
+ - **Every member acts through the maintainer's `gh` credentials, so no write is
3165
+ attributable.** Any invariant about *who* did something is unenforceable after
3166
+ the fact: when a label moves unexpectedly, ask members directly, rule out
3167
+ automation with `grep -rn '<label>' .github/workflows/`, and do not re-add it.
3168
+ - Phase 1 is serial. Everything else may run concurrently.
3169
+
3170
+ ## Guards
3171
+
3172
+ **Verify every reported SHA.** `~/.fleet/bin/fleet-run verify-sha.sh
3173
+ <branch> <sha>` before enqueueing — a member can commit in a nested worktree,
3174
+ leaving the SHA on a stray branch while its report reads normally. Exit codes as
3175
+ `inflight.sh`: `# 0 reachable, 1 not reachable, 2 unanswerable`. Not reachable
3176
+ (exit 1) → flag, do not enqueue, do not return the ticket to the shortlist until the
3177
+ maintainer rules. **Exit 2 is not a verdict** — the question could not be
3178
+ answered, and every cause of it reaches you as one shape: no JSON on stdout at
3179
+ all, the cause on stderr alone. Read that stderr, fix what it names and re-run;
3180
+ escalate if it repeats. Never read exit 2 as `not reachable`, and never record it
3181
+ as a stray commit — the flag and the maintainer's ruling above are what exit 1
3182
+ earns, and spending them on a probe that never answered costs a member its
3183
+ ticket over a failure a re-run would have cleared.
3184
+
3185
+ **Never `--delete-branch`.** It errors on a `main` held by another worktree, or
3186
+ strands the feature worktree on `main`. `gh pr merge <n> --merge` alone; GitHub
3187
+ deletes the remote branch anyway.
3188
+
3189
+ **Never force a rebase to start.** No `git clean`, `git checkout .`,
3190
+ `git reset --hard`, `git stash`. Uncommitted changes may exist nowhere else.
3191
+ Non-empty `git status --porcelain -unormal` → stop and report — the explicit
3192
+ mode, never bare `--porcelain`, or `status.showUntrackedFiles = no` reads an
3193
+ empty answer here and licenses the rebase over work this check exists to
3194
+ protect (#730). Stashing empties it either way, so that check and
3195
+ `no-undo-audit.sh` both go quiet on work nothing else holds.
3196
+
3197
+ **Cross-check what members report about their environment.** Wrong often enough
3198
+ to matter, and a confident wrong report from a reviewer flips a verdict.
3199
+
3200
+ **Distrust negative claims hardest.** "Nothing else references this", "the sweep
3201
+ is clean" — most likely false, least likely checked: a grep that found nothing
3202
+ looks like a grep never run. Make members state their search scope. Negative claim
3203
+ vs specific finding with paths → paths win.
3204
+
3205
+ **Members share one filesystem, one docker stack and one process table**, and the
3206
+ failures arrive as *wrong findings*, not errors:
3207
+
3208
+ - **A pattern kill reaches siblings — say so in the dispatch prompt.** `pkill -f
3209
+ <pattern>` matches on the whole command line, machine-wide. Members hold
3210
+ separate worktrees, but the process table is not partitioned by them and a
3211
+ test file's name is identical in every one, so a pattern naming a test file
3212
+ matches whichever member happens to be running it. Measured: an implementer
3213
+ chasing its own stalled run issued `pkill -f "claim-ticket.test.mjs"` and
3214
+ killed a `node --test claim-ticket.test.mjs inflight.test.mjs` that was not
3215
+ its own.
3216
+
3217
+ **What the victim's output looks like depends on the signal — and one of the
3218
+ cases is a clean green.** Each measured on node v26.8.1/darwin against a
3219
+ purpose-spawned fixture killed by its own PID. `pkill -f` **defaults to
3220
+ SIGTERM**, and a SIGTERMed runner prints `Interrupted while running:` followed
3221
+ by a *complete* summary block with `cancelled` non-zero, exiting `rc=1` — so
3222
+ `cancelled` is exactly the thing to search for in the default case. `pkill -9
3223
+ -f` leaves no summary block at all and the shell reports `rc=137`: SIGKILL
3224
+ means the harness never lived long enough to report. A kill landing on one of
3225
+ node's per-file **child** test processes leaves a complete block with `fail`
3226
+ non-zero and `cancelled 0` at `rc=1`, indistinguishable from an ordinary test
3227
+ failure. And a kill landing on a process a **test itself spawns** leaves a
3228
+ complete `pass N / fail 0 / cancelled 0` at the expected N over a corrupted
3229
+ run: `spawnSync` reports a SIGKILLed child as `status null`, and a test
3230
+ asserting only that the process it spawned exited non-zero —
3231
+ `assert.notEqual(r.status, 0)`, a form used across this suite, in files that
3232
+ spawn the shell scripts they cover — passes vacuously on `null`.
3233
+
3234
+ So **a complete summary block proves the runner survived, not that the run was
3235
+ uncontaminated.** Scrutinize reds, short counts *and* greens from inside the
3236
+ incident window; a killed **baseline** compared against a clean mutant is a
3237
+ wrong measurement that reads exactly like a real result.
3238
+
3239
+ **The command line is no partition either — not reliably.** Ports are derived
3240
+ per issue precisely so collisions are impossible; argv isolates a run only
3241
+ sometimes. Measured with `ps -Ao pid,ppid,args -ww` (without `-ww` macOS `ps`
3242
+ truncates, and the truncation reads as an absence): an invocation carrying an
3243
+ **absolute** path puts a member-unique string in argv, while one carrying
3244
+ repo-relative filenames is byte-identical across members. Which of the two you
3245
+ get is not yours to choose — members are briefed on `./agent-test
3246
+ <file-or-dir>` over the suite under `plugin/scripts/`, and that runner `exec`s
3247
+ node with the file list its caller's shell already expanded, never a literal
3248
+ glob. Clearing your own leftover process needs its PID, not a pattern.
3249
+
3250
+ Members report a stalled run to the controller instead of pattern-killing it,
3251
+ and the controller re-checks any measurement taken in the window.
3252
+
3253
+ **Do not guess the victim — the blast radius is the machine, not the Pull.**
3254
+ In that incident the controller reasoned from dispatch scope to "almost
3255
+ certainly `impl-<N>`" and told the maintainer so; the named member then proved
3256
+ it was not the victim (it had never invoked those files standalone, and its
3257
+ mutation baselines post-dated the window). Idle members of *previous* runs,
3258
+ other omp sessions on the same machine, and the maintainer's own shell are
3259
+ all `pkill -f` targets and none of them appear in your ledger. Warn every live
3260
+ member, record the incident as unattributed, and re-check measurements by
3261
+ timestamp rather than by who you think was running.
3262
+
3263
+ - **A warning acted on silently is indistinguishable from one that never
3264
+ arrived.** The same incident: the controller's warning DID reach the member,
3265
+ which re-ran, found nothing changed, and said nothing — correctly reading
3266
+ "send once, never re-send" as covering it. The controller then had to spend a
3267
+ round trip asking whether its own outbox was lossy. So say in the dispatch
3268
+ prompt that **confirmation state includes warnings received and acted on, even
3269
+ when the outcome is no change** — one line, in the report the member already
3270
+ owes. That is the cheap half of the *never read silence as assent* rule, paid
3271
+ by the member rather than by the controller's guesswork.
3272
+
3273
+ - **Specialist tree isolation is `review-and-fix.md`'s job — do not restate it.**
3274
+ It owns the object-store rule, the two-tree split, snapshot provisioning, and
3275
+ which suites a snapshot cannot validly run. Your only duty is to *not*
3276
+ contradict it.
3277
+ - **Filesystem isolation is not stack isolation.** A private copy of the tree and
3278
+ a test command solve different problems; the compose project name comes from
3279
+ the environment, not the working directory, so three agents on three snapshots
3280
+ still collide on one postgres. "I'm on my own copy" is exactly the intuition
3281
+ that skips the command — say both, every time. Which command depends on the
3282
+ audience: a member in a worktree uses `./agent-test`; a specialist on a
3283
+ snapshot does not — the runner that bootstrap materializes derives its
3284
+ isolation triple from the directory name, and a snapshot is not a claimed
3285
+ worktree, so every snapshot in the fleet gets the same fixed ports — and
3286
+ takes the one `review-and-fix.md` hands out. The bootstrap itself now
3287
+ SUCCEEDS there (the snapshot is a git repository since #1056), which is why
3288
+ the reason to hand out a different command is the stack and not a
3289
+ materialization failure. See references/isolation.md.
3290
+ - **Scratchpad paths need two levels — the member's own partition, then one
3291
+ directory per child it dispatches — and nothing outside them.** An
3292
+ implementer partitions at `<scratch>/impl-<N>/`, the review side at
3293
+ `<scratch>/pr<N>/…`; any member that dispatches a child writes an absolute
3294
+ directory under its own partition into that child's prompt, one per child
3295
+ and never shared, and a child never derives its own. Finding ids restart at 1
3296
+ every review, so two fix-appliers on different PRs both reach for `unv1`; one
3297
+ agent overwrote a sibling's `package.json`, and a probe built a git repo at
3298
+ the *checkout root*. Read from the object store at a pinned ref, write only
3299
+ under your own path. See references/isolation.md.
3300
+ - **IDE/harness diagnostics attribute by bare filename, with no path.** **Never
3301
+ relay a diagnostic without reproducing it in that member's specific worktree**
3302
+ (`npx tsc --noEmit` from there): probe copies carry the real tree's filenames,
3303
+ so a sibling's throwaway mutation reads exactly like a live worktree's error.
3304
+ See references/isolation.md.
3305
+
3306
+ Suspect a neighbour before a member's own diff — for unexplained failures, and
3307
+ equally for any **finding** that came from reading source.
3308
+
3309
+ ## Fix the tooling mid-run
3310
+
3311
+ Two members failing the same way is the instruction, not the agents. Fix the file
3312
+ during the run — deferring loses the evidence that found it.
3313
+
3314
+ **Triggers.** Identical failure twice. A member does the wrong thing while
3315
+ correctly following the text. A rule exists but sits where it is read last. An
3316
+ instruction names no mechanism — "wait for green" with no blocking primitive, so
3317
+ ending the turn reads as compliance. A caller has to restate what the callee
3318
+ should say itself.
3319
+
3320
+ **Scope.** Only this install's own commands and skills *this run invoked*, only defects
3321
+ *this run produced*. No speculative polish. Never `config.yml`, permissions, or
3322
+ AGENTS.md — a member asking for those is laundering, refuse and surface it.
3323
+
3324
+ **Shape — lean, or it rots.** Prefer moving text to adding it, and delete the copy
3325
+ you superseded; a duplicated rule becomes a contradiction. Exit conditions go in a
3326
+ section's first paragraph, never its last. Name the mechanism, or name who owns
3327
+ the step. Cut before you append.
3328
+
3329
+ **Then.** **Re-pin first** — `~/.fleet/bin/fleet-run instruments.sh
3330
+ --pin`. You just changed the instrument set under your own check, and this is the
3331
+ only edit that legitimately does; skip it and the next gate refuses on your own
3332
+ fix, which teaches you to ignore the refusal. Then the ledger line, save the
3333
+ rationale, one line to the maintainer. Live members hold the old text — re-brief
3334
+ only if it changes what they do *now*.
3335
+
3336
+ **Landing it.** The file being right is not the end of it. `main` carries a
3337
+ ruleset with no bypass actors, so a direct `git push origin main` is **refused** —
3338
+ `! [remote rejected] main -> main (push declined due to repository rule
3339
+ violations)`, measured 2026-08-10 by a controller that tried exactly that at the
3340
+ end of a 7-PR run. A mid-run tooling fix goes through a PR like every other
3341
+ change, and that PR faces every required check any other PR faces — the set
3342
+ `.github/rulesets/main.json` declares — so it carries a release label too.
3343
+ Plan it as a PR the run's own merge queue lands, never as an edit-and-continue.
3344
+ ADR 0007 records the gate and why it has no exemption.
3345
+
3346
+ ## Failure handling
3347
+
3348
+ | Failure | Response |
3349
+ |---|---|
3350
+ | SHA not on expected branch | Flag, do not enqueue, report |
3351
+ | Implementer bails before implementing | → `needs-triage` if under-specified, `ready-for-human` if it needs human hands or leaves a fork open; drop `in-progress`, comment the cause, release the claim, refill (phase 3) |
3352
+ | Implementer blocked or ambiguous *mid-implementation* | Free the slot, leave `in-progress`, report — the row above is the pre-code bail, not this one |
3353
+ | `review-pr` workflow throws or returns no tree | Retry once, then hand-dispatch the fallback reviewer. Never enqueue the PR as reviewed — the workflow is not a member, so no other row here covers it |
3354
+ | Reviewer or fix-applier cannot reach green | Report, leave the PR unlabeled, free the slot |
3355
+ | Merge bot hits the hold rule | Report `held-behind-#<lower>`, PR stays queued |
3356
+ | Merge bot finds the worktree ahead of the PR head **on the local-rebase fallback** | `worktree-diverged-#<pr>`, PR stays queued. Read the stray commit; push-or-discard is yours, and the maintainer's if the evidence cannot settle it |
3357
+ | Merge bot finds the head moved after `ready-to-merge` was applied | `head-moved-after-label-#<pr>`, PR stays queued, label untouched. Dispatch a **fresh** finisher against the new head — the first audit verified a different tree |
3358
+ | Merge bot cannot resolve a rebase safely | Stop that PR, report, continue. On a conflict the bot has already appended `conflict-hold:#<pr>` to the PR's row; the tick prints `DISPATCH fix-pr PR#<pr>` and holds the merge until that fix-applier settles |
3359
+ | Merge bot's gate refuses on its instrument re-check (`instrument-set-changed` or `instruments-unanswerable`, exit 2) | Report `<reason>-#<pr>` with what it printed, PR stays queued, label untouched. Do not re-run the gate |
3360
+ | Member silent or truncated | Send to ping or resume — same unit of work; see the state machine below |
3361
+ | Member idle with work outstanding | Read the PR first, *then* ping. Idle ≠ done |
3362
+ | Member **killed** (spend limit, API error, crash) | Confirm it is dead first — a frozen transcript does not establish that; see below — then new member, new name, prompt carries inherited state |
3363
+
3364
+ A red PR never silently becomes `ready-to-merge`.
3365
+
3366
+ **A frozen transcript does not establish that a member is dead — the
3367
+ discriminator is its scratch dir.** A member wedged on a blocked tool call
3368
+ emits the whole signature of a dead one: record counts unchanged from one poll
3369
+ of its transcript to the next. So read the mtimes of the files anywhere under
3370
+ the scratch directory its own dispatch prompt assigned it, subdirectories
3371
+ included — `<scratch>/impl-<N>/` for an implementer, that member's own
3372
+ run-scoped subdirectory under `<scratch>/pr<N>/` on the review side, never
3373
+ the bare `pr<N>/` tree those siblings share — since a member waiting on a
3374
+ child it dispatched writes nothing itself while that child writes below it.
3375
+ Read them at two observations a poll apart — `touch` a marker file outside
3376
+ that directory at the first, and
3377
+ `find <dir> -type f -newer <marker>` at the second lists every file that
3378
+ moved: **mtimes that moved between the two mean BLOCKED, a live member
3379
+ still holding its claim and its worktree, so the killed row above does not
3380
+ apply to it; mtimes unchanged at both are the dead signature.** Only the first
3381
+ of those two verdicts is conclusive — a member wedged on a call that writes
3382
+ nothing freezes its scratch dir too — so settle the dead one on the liveness
3383
+ read below, never on the two listings alone. Measured on #503: a refuter
3384
+ wedged forever on `until grep -q` for a marker `node --test` never writes, its
3385
+ transcript's record counts unchanged across two polls while its own scratch
3386
+ files carried fresh mtimes throughout — alive the entire time it read as dead.
3387
+ The filenames are not a contract: they are whatever that member happens to be
3388
+ writing, and they differ by member and by role. That second listing is cheap
3389
+ at the price, because the cost of the wrong call is asymmetric — a live member
3390
+ written off gets killed and re-dispatched, which discards the work in flight
3391
+ and, where it holds a claim or a worktree, collides the fleet with itself,
3392
+ while one poll spent on a member that had in fact stopped costs only the poll.
3393
+ The refuter's own observation rule in the fix-applier prompt above stops a
3394
+ member from creating that state; this one stops you from misreading whoever
3395
+ reaches it anyway, and neither replaces the other.
3396
+
3397
+ Settle outcome and liveness are different facts, not the same table with two
3398
+ spellings. Recovery is a fresh member, fresh name (`impl-<N>-b`,
3399
+ `fix-pr-<M>-b`, `review-pr-<M>-b`) whose prompt states what it inherits.
3400
+
3401
+ `hub cancel` leaves a peer hard-aborted and unmessageable, but a `failed` job's peer can stay `idle` and answer normally. No distinct truncated state exists.
3402
+
3403
+ Reviewers that went idle on CI recover as a **finisher, not a re-review** once
3404
+ commits are pushed. See references/member-lifecycle.md.
3405
+
3406
+ Audit every worktree before dispatching replacements with
3407
+ `~/.fleet/bin/fleet-run worktree-audit.sh` — it reports each worktree's
3408
+ ahead-count and uncommitted files, the committed-vs-uncommitted distinction that
3409
+ decides whether a replacement redoes or destroys work.
3410
+
3411
+ ## Run ledger
3412
+
3413
+ One git-ignored `.fleet/ledger.md`, updated at **every** state change via
3414
+ `~/.fleet/bin/fleet-run ledger.mjs` subcommands (`row`, `filed`, `ruled`,
3415
+ `check`, `read`, `dispatch`, `settle`, `drain`). Your context is the least
3416
+ durable thing in the run: it compacts, and a controller that loses the dispatch
3417
+ map or the filed list redoes finished work. Two duplicate tickets shipped in one
3418
+ run from exactly that.
3419
+
3420
+ One line per ticket, rewritten in place (`ledger.mjs row <ticket> <text>`):
3421
+
3422
+ ```
3423
+ #332 impl-332=PR#344 → PR#344 → MERGED 73b356de
3424
+ #324 impl-324=PR#346 → PR#346 · fix-pr-346 · ports=16324 · ruled:6-applies · held-behind:#313
3425
+ #351 impl-351 · class=routine · tier=alt
3426
+ #358 excluded · behind-pr:#346
3427
+ #360 excluded · behind-issue:#351
3428
+ ```
3429
+
3430
+ **A member's token is `<member>` while it is live and `<member>=<outcome>` once
3431
+ it settles** — the grammar is `ledger-grammar.mjs`'s, and the tick derives every
3432
+ live count from it, so nobody states one. Write neither by hand:
3433
+
3434
+ - **`ledger.mjs dispatch <ticket|pr> <member>`** — before the dispatch call,
3435
+ marks the member live on its row and appends it to `## Dispatched`. `dispatch
3436
+ merge-bot` names the next bot itself. It refuses a name this run already
3437
+ used (a replacement takes `-b`, `-c` …), a second live member on one ticket
3438
+ or PR, and any implementer once the run is draining.
3439
+ - **`ledger.mjs settle <member> <outcome>`** — rewrites the token to
3440
+ `<member>=<outcome>` in both places. Outcomes: `impl-N` = `PR#M | bailed |
3441
+ released | killed | tier-mismatch`; `fix-pr-M` = `applied:<head> | no-op |
3442
+ failed | killed`; `finisher-pr-M` = `labelled | failed | killed |
3443
+ halted:<cause>`, `<cause>` one of `live-editor | rebase | past-pin |
3444
+ unreadable | missing | absent | other` (**Resolving a finisher halt**);
3445
+ `merge-bot-n` = `done | killed`. A settled member stays settled. `settle
3446
+ impl-N=PR#M` also folds a `#M` row a PR-bound dispatch made before the settle
3447
+ into `#N`'s row, so one row names each PR from then on — but only when `#N`'s
3448
+ row named no PR before this write (a second `PR#` on it would misattribute
3449
+ the fold, or bury `#N`'s own fresher `review=` state under an older one) and
3450
+ `#M`'s row is genuinely the fallback (a live or settled PR-bound token on it,
3451
+ or nothing at all) rather than an unrelated row that merely shares the key.
3452
+ - **`ledger.mjs drain "<reason>"`** — the one drain marker per run; supply
3453
+ stops, the review and merge sides keep going.
3454
+
3455
+ `row` refuses a malformed member token anywhere in its text — one whose outcome
3456
+ is outside the vocabulary above, e.g. `merge-bot-1=dispatched` — at exit 2,
3457
+ naming the token and writing nothing, because every reader would take it as a
3458
+ permanent settle.
3459
+
3460
+ `→ PR#M` stays as the human-readable arrow; the tick reads only the `=`
3461
+ tokens. `tier=alt` marks the every-5th-Pull member (phase 2), and `excluded ·
3462
+ behind-pr:#M | behind-issue:#M` is an Exclusion (phase 1) — a ticket row like
3463
+ any other, never a section of its own.
3464
+
3465
+ A PR's review is not a member, so it carries its own pair of row tokens,
3466
+ written with `row` (**Reviewers**): `review=wf:<runId>` |
3467
+ `review=member:review-pr-<n>` | `review=fallback:review-pr-<n>[-b]` at launch,
3468
+ settled dead as `…=failed`, then `reviewed=<head>:<survived>/<refuted>/<unverified>`
3469
+ when the result lands. A row with `review=` and no `reviewed=` is a review in
3470
+ flight, and the tick counts it against the reviewer cap. `ci=<run-id>:<attempt>:<conclusion>`
3471
+ and `held-behind:#<lower>` are row tokens the same way (Phase 3), and so is
3472
+ `conflict-hold:#<pr>` — the one row token the merge bot writes itself, naming
3473
+ the row's own PR (`run-merge-bot.md` step 1). It is not an Exclusion: that
3474
+ gates a ticket's claim, this a reviewed PR's merge.
3475
+
3476
+ Plus two append-only lists:
3477
+
3478
+ - **filed** (`ledger.mjs filed <issue> <subject>`, checked with `ledger.mjs check
3479
+ <subject>` before every `gh issue create`) — so a finding already recorded
3480
+ this run is not filed twice. That is not a guarantee against duplicates at
3481
+ large; the tracker query below is what covers those. The FILER writes this
3482
+ one, not you: `review-and-fix.md` step 5 and finisher duty 2 each run `filed`
3483
+ immediately after their own `gh issue create`, with the subject they passed
3484
+ to `check`, and report `filed: #N <subject>`. A filer whose `filed` failed
3485
+ twice reports `unrecorded: #N <subject>` instead, and you run `filed` for it.
3486
+ - **ruled** (`ledger.mjs ruled <pr> <decision>`) — PR + decision + one-line reason,
3487
+ so a replacement controller does not re-litigate a settled call.
3488
+
3489
+ **Writer policy: the controller owns run state (`row`/`settle`/`dispatch`/`drain`/`ruled`);
3490
+ filers append filings with `filed`; all writes are serialized by `<file>.lock`.**
3491
+ Every write rewrites the whole file from what it read, so without the lock two
3492
+ concurrent writers are last-writer-wins — measured, 8 concurrent `filed` kept
3493
+ 2–5 of 8 rows (#531). A writer that cannot take the lock within 10 s exits 2
3494
+ naming the holder's pid, having written nothing; a lock whose holder is dead is
3495
+ taken over, and a leftover `<file>.lock.reap` is never reclaimed. One other
3496
+ shape wedges the lock permanently the same way, needing the same fix: an empty
3497
+ `<file>.lock` — its writer was killed between creating it and writing its pid
3498
+ into it — is unparseable and therefore, by design, always read as live rather
3499
+ than handed to the death check; its timeout names `<file>.lock` itself, since
3500
+ there is no pid to name. A zombie holder — a pid whose process exited
3501
+ but whose parent never `wait()`-ed on it — also answers a liveness check as
3502
+ alive, because the OS keeps a reserved pid until it is reaped, but that is
3503
+ transient, not a wedge: once the pid is reaped (the parent's own exit is
3504
+ normally enough to trigger this), the next writer's death check reads it as
3505
+ dead and takes the lock over the same as any other dead holder — no hand
3506
+ removal needed. The other two shapes do not clear on their own — remove
3507
+ `<file>.lock` or `<file>.lock.reap` by hand once nothing is writing. Reads
3508
+ (`check`, `read`) take no lock.
3509
+
3510
+ **The gap the lock does not close:** `check` → `gh issue create` → `filed` is
3511
+ three commands, and the lock covers each one alone, so two filers can both read
3512
+ `clean` in the seconds before either records. Accepted — the measured
3513
+ same-run accidental duplicate, #298 → #302, was filed minutes apart — and no
3514
+ claim/reserve step exists to close it.
3515
+
3516
+ `check` exits **0** clean, **1** already in this run's filed list, **2** usage
3517
+ error (no JSON on stdout), **3** the ledger is clean but open or closed tracker issues match — read
3518
+ those and decide. Exit **3** is scored: some row gh returned has to score above
3519
+ zero against the subject, because the ANDed query also matches issues the
3520
+ overlap rates 0.00, and every measured stop over those was survived only by a
3521
+ reader who overrode it and searched the tracker by hand — obeying it would have
3522
+ dropped a real deferral (#388). It also prints the closest filed rows with an overlap score.
3523
+ Those never move the exit code — the same finding gets worded differently by
3524
+ whoever finds it second — but once the tracker read succeeds, a filed row at or
3525
+ above `NEAR_SOFT_HIT` in `ledger.mjs` does move the verdict to `soft-hit`, as
3526
+ does a tracker set with no scoring row in it; a read that failed stays
3527
+ `unverified`, which outranks both. **Exit 0 is not automatically "safe to file":** when `gh`
3528
+ cannot be reached the answer is ledger-only, and it says `TRACKER NOT CHECKED` —
3529
+ an issue filed by an earlier run is invisible to it; and `soft-hit` means rows
3530
+ worth reading were found while none of them established a duplicate, so read
3531
+ them before filing. The stdout JSON names all of that in one field:
3532
+ `verdict` is `already-filed`, `tracker-hit`, `clean`, `soft-hit` or
3533
+ `unverified`. Only `already-filed` and `tracker-hit` carry a non-zero code, so
3534
+ `verdict` is the only thing that tells a searched-and-clean tracker from one
3535
+ that was never read and from one whose rows you have to read yourself.
3536
+
3537
+ The ledger half reports its own readability as its own field, `ledger.ok`, the
3538
+ peer of `tracker.ok`: false when the file did not exist, and false too when the
3539
+ path led to something that did not parse as a ledger — which is what tells a
3540
+ ledger that was read and held nothing filed from one there was nothing to read
3541
+ (#231). The absent case is the normal one for a run's first `check` — `.fleet/`
3542
+ is git-ignored and created lazily by the first write — so it stays `clean` at
3543
+ exit 0, and `ledger.ok` is the field that says why rather than the verdict
3544
+ moving. The stderr warning is deliberately narrower than the field: it fires on
3545
+ a path with no file, so a `--file` that landed on the wrong existing file is a
3546
+ silent `ok:false` with nothing on stderr. Gate on the field, not on the warning.
3547
+
3548
+ **Write the ledger line before dispatching, not after.** A member that dies
3549
+ between spawn and write is invisible — and members die in batches.
3550
+
3551
+ ## Report
3552
+
3553
+ One running table, updated as events land:
3554
+
3555
+ ```
3556
+ #N ticket impl-<N> PR #M fix-pr-<M> label:yes merged
3557
+ #N ticket impl-<N> PR #M fix-pr-<M> label:no - red CI
3558
+ #N ticket impl-<N> - - - - blocked: SHA off-branch
3559
+ ```
3560
+
3561
+ Plus a queue-depth line: shortlist, supply, whether triage was suggested.
3562
+
3563
+ ## Red flags
3564
+
3565
+ - "Fork the controller so the member has context" → fork inherits everything.
3566
+ - "This member finished, send it the next ticket" → resumes its transcript.
3567
+ - "The name is cosmetic" → the name is the ledger token and the hub address.
3568
+ - "Name the specialists too" → a depth-2 member cannot dispatch further.
3569
+ - "ready-for-agent came back empty, widen to ready-for-human" → empty means no work.
3570
+ - "The reap at the end will pick up the claim I never dispatched" → it declines:
3571
+ not `[gone]`, no unique commits. Release it, or it reads as taken next run.
3572
+ - "Touches eight files, too big for the fleet" → size is not the axis. Decided is.
3573
+ - "Body is three lines, so it's simple" → short bodies hide open design choices.
3574
+ - "The brief is thorough, so it's decided" → thorough ≠ decided. Read it for the
3575
+ choice it leaves open.
3576
+ - "I'd have to pick an approach myself" → that IS undecided.
3577
+ - "The reviewer can dispatch, it'll fan out" → not unless authorized.
3578
+ - "Tell the reviewer to ping its specialists" (fallback path) → a depth-2 member
3579
+ cannot dispatch further, so the ping goes nowhere. Tell it to
3580
+ read the specialist's output file instead; your relay is the backup, not the
3581
+ only path.
3582
+ - "I relayed it, so the reviewer has it" (fallback path) → sent is not read, and a relay can land
3583
+ after the verdict is composed. Two reviewers ruled relayed dimensions
3584
+ undelivered, one of them shipping a headline claim the report it disclaimed
3585
+ refuted. Reconcile verdicts against your receipts.
3586
+ - "It reported the SHA, so it's on the branch" → verify.
3587
+ - "Let the merge bot arm its own monitor" → it dies, the queue stops.
3588
+ - "The member died, message it the state" → dead agents do not read mail.
3589
+ - "Its CI is green, ship it" → check behind-count; green decays invisibly.
3590
+ - "The specialist says nothing else references it" → the claim most often wrong.
3591
+ Ask what scope it searched.
3592
+ - "Five implementers = five times throughput" → reviews are 3-5x longer. It means
3593
+ a backlog.
3594
+ - "`npm install` to set up the worktree" → the wrong install mutates the lockfile
3595
+ for the whole repo.
3596
+ - "I'm on my own copy, so I'm isolated" → not from the docker stack.
3597
+ - "`commit-commands:clean_gone` printed nothing, the tree is clean" → its
3598
+ `[gone]` detection works fine; it just runs `-D`/`--force` with no merged
3599
+ check, so "printed nothing" only means nothing was gone yet, not that it's safe.
3600
+ - "`--force` the worktree removal, the PR merged anyway" → merged says nothing
3601
+ about uncommitted files, and the reviewer may still be in there.
3602
+ - "Reap once at the end of the run" → stale worktrees make phase 0 read merged
3603
+ tickets as taken, so the starvation compounds with every Pull.