@feigi/fleet-ctl 3.69.2 → 3.71.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.
@@ -40,29 +40,9 @@ Each of those templates under `briefs/` carries the line: *"The controller does
40
40
  not acknowledge reports. Send once and exit; never re-send unless the controller
41
41
  asks by name."*
42
42
 
43
- **But a missing report is NOT evidence the member failed to send one — the
44
- inbound direction drops AND delays messages.** Both were measured in one run,
45
- and they are indistinguishable at the moment you look: one finisher's report was
46
- accepted with a msg_id and never arrived at all, while another's arrived late —
47
- its original and its re-send landing together, after the controller had already
48
- concluded it was missing. Measured: a finisher completed every
49
- duty, labelled the PR, and sent its report; the send was accepted with a msg_id
50
- and never arrived. The controller read the silence as the member ending its turn
51
- without reporting, said so, and was wrong. The re-send it asked for by name is
52
- the only reason the report exists. So when a report is missing, **ask by name —
53
- that is what the "unless the controller asks by name" clause is for — and do not
54
- attribute the gap to the member until it answers.** A member re-sending on a
55
- named request should state the original's msg_id and that it is a re-send, which
56
- is what distinguishes a lost message from a member that never sent one; a
57
- controller that skips the ask cannot tell those apart and will guess wrong in
58
- whichever direction its expectations point. The tick prints `SETTLE <member>`
59
- for a report file on disk that passes its schema and `REPORT-INVALID` for one
60
- that fails it, so a missing message is read off those lines before anyone is
61
- pinged.
62
-
63
- Note this cuts against the paragraph above only in appearance: the default stays
64
- *send once*, because unprompted re-sends were measured 2-to-1 false. The ask is
65
- the controller's move, not the member's.
43
+ So when a report is missing, **ask by name — that is what the "unless the controller asks by name" clause is for — and do not attribute the gap to the member until it answers.** See references/member-lifecycle.md.
44
+
45
+ The ask is the controller's move, not the member's. See references/member-lifecycle.md.
66
46
 
67
47
  **Your OWN messages can vanish the same way, and that half is not recoverable by
68
48
  a re-send.** Two controller rulings were lost in one run, both with a
@@ -89,19 +69,7 @@ handing a finished member the next ticket.
89
69
 
90
70
  See references/member-lifecycle.md.
91
71
 
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
- a `bash` or `eval` write still lands. 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.
72
+ **You read your instruments out of a tree every member can write to — re-check them before every gate decision.** See references/instruments.md.
105
73
 
106
74
  - **Pin once**, at phase 0 step 0 below, from the main checkout you are
107
75
  running this from — never from a member's worktree, which is gitignored
@@ -135,19 +103,7 @@ branch per ticket and `reap.sh` deletes them in the ref store every worktree
135
103
  shares, so ordinary work moves refs several times a run and a per-gate
136
104
  refusal on that is noise.
137
105
 
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. This file is
149
- yours, not theirs: the implementer, fix-applier and finisher briefs carry the
150
- rule, as the line `A member runs its test suite in the foreground and blocks on it.`
106
+ **A member runs its test suite in the foreground and blocks on it.** See references/member-lifecycle.md.
151
107
 
152
108
  **The scratch root is computed, never invented and never recorded.** No harness
153
109
  supplies a scratch directory to a member, so a member left to name its own
@@ -177,23 +133,9 @@ one it runs in. Phase 3's monitor paragraph points here instead of restating
177
133
  any of it. The merge bot's agent body is the one place this block is copied
178
134
  whole (see **Merge bot**); the other deliberate copy is named at the end.
179
135
 
180
- **zsh word-splits an unquoted command substitution's result; it does NOT split
181
- an unquoted parameter expansion.** That one difference is the whole rule, and the
182
- hazard is the **assigned-variable** form, never `$(…)`. Measured on zsh 5.9
183
- against `849`, `850`, `852` on three lines:
184
-
185
- | Form | zsh | bash / sh |
186
- |---|---|---|
187
- | `prs=$(gh pr list …)` then `for pr in $prs` | **1 iteration**, all three glued into one value | 3 |
188
- | `for pr in $(gh pr list …)` | 3 | 3 |
189
- | `for _ in $(seq 1 60)` | 60 | 60 |
136
+ **zsh word-splits an unquoted command substitution's result; it does NOT split an unquoted parameter expansion.** See references/shell-traps.md.
190
137
 
191
- **Word the rule against the first row.** A warning spelled *never `for x in
192
- $(…)`* names the safe form as the hazard, so a reader avoids the form that works,
193
- keeps the one that collapses, and rewrites correct bounded polls on the way.
194
- A ticket was once filed carrying that inversion in its own remedy clause and in its title,
195
- and its filer measured both forms and retracted it; the corrected rule is this
196
- row. `$(…)` splits. Leave it alone.
138
+ **Word the rule against the first row.** See references/shell-traps.md.
197
139
 
198
140
  **Capture-then-loop needs `while IFS= read -r` fed by a heredoc**, which is
199
141
  line-exact under every shell:
@@ -207,21 +149,9 @@ $prs
207
149
  EOF
208
150
  ```
209
151
 
210
- The inline `$(printf '%s\n' "$prs")` form splits correctly too and is what Phase
211
- 3's block uses, but it splits on *every* whitespace character, so it is safe only
212
- for values that cannot contain one — PR numbers cannot, branch names and paths
213
- can. Measured on a two-line list whose first value is `two words`: three
214
- iterations through `$(printf …)`, two through `while IFS= read -r`. On an empty
215
- `$prs` the counts diverge the other way: `for pr in $(printf '%s\n' "$prs")`
216
- iterates **zero** times, but the heredoc form iterates **once** with `pr` empty —
217
- the guard above is what stops that iteration from probing `--pr ""`.
218
-
219
- **`</dev/null` every command inside a `while read` loop.** The loop's stdin *is*
220
- the list, and any inner command that reads stdin eats the rest of it. Measured on
221
- the three-line list above: one unredirected inner reader takes the loop to **1
222
- iteration**, `</dev/null` on it restores 3 — the identical signature to the
223
- word-split bug, so a correct heredoc fix missing this half looks exactly like no
224
- fix at all, and reads as one.
152
+ The inline `$(printf '%s\n' "$prs")` form splits correctly too and is what Phase 3's block uses, but it splits on *every* whitespace character, so it is safe only for values that cannot contain one — PR numbers cannot, branch names and paths can. See references/shell-traps.md.
153
+
154
+ **`</dev/null` every command inside a `while read` loop.** See references/shell-traps.md.
225
155
 
226
156
  **A probe that could not look emits an event; it never `continue`s.** Stated in
227
157
  full at *A probe that cannot read is a transition event, not silence* in Phase 3,
@@ -235,13 +165,7 @@ instead of a quiet one. A guard that drops an unreadable probe — `[ -n "$json"
235
165
  empty and `[ "" -eq 0 ]` passes. A bot's merge gate opened without ever reading
236
166
  an exit code.
237
167
 
238
- **`status` is a READ-ONLY variable in zsh**, an alias for `$?`. So the obvious
239
- bash idiom for reading the payload — `status=$(jq -r '.status' ci.json)` — aborts
240
- with `read-only variable: status`. Measured this way it fails safe (a hard abort,
241
- no merge), but the same assignment inside an `if`, or with stderr suppressed,
242
- reads as a check that silently did not run. Same root cause as the `PIPESTATUS`
243
- trap, opposite failure direction — so name the variable anything else
244
- (`ci_status`).
168
+ **`status` is a READ-ONLY variable in zsh**, an alias for `$?`. Name the variable anything else (`ci_status`). See references/shell-traps.md.
245
169
 
246
170
  **The other deliberate copy is `env $cfg sh ./probe.sh`.** The first trap's
247
171
  mechanism bites argv as well as loops, and that instance stays written out in the
@@ -673,20 +597,7 @@ queues at its ceiling rather than refusing, and is session-wide): below
673
597
  exits 0, so the notice is the operator's to read and report, never a reason to
674
598
  stop the run.
675
599
 
676
- **Every 5th Pull by ledger count goes at an exploration cell.** Count the `impl-`
677
- rows in `.fleet/ledger.md` at Pull time; the Pull that creates row 5, 10, 15 …
678
- is an Exploration Pull, and the router draws its cell: `k = 1 +
679
- (sha256("<session>\t<ticket>")[0:8] mod K)` over `router-table.json`'s
680
- `cells` minus the policy cell, in token order. While the table's `burn_in` is
681
- true every Pull draws, over every cell, the policy cell included. An
682
- Exploration Pull records `tier=<cell>` in the row, and a replacement inherits the row's tier —
683
- written at the Pull's row step, ahead of `ledger.mjs dispatch`, which reads it
684
- and prints `fleet-implementer-<cell>` as the `agent` to dispatch; a row with
685
- no `tier=` runs the policy cell. The
686
- assignment rolls to the next Pull when another open ticket sequences after
687
- it — a ticket the rest of the run
688
- depends on; `class` is not read. Do not tell the member it is a control: a member that
689
- knows it is being measured is not measuring the same thing.
600
+ **Every 5th Pull by ledger count goes at an exploration cell.** See references/pull.md.
690
601
 
691
602
  **The router's arguments, and nothing past its line.** `--impl-row` is the
692
603
  row count the Pull creates — or, while an assignment is rolling (the latest
@@ -718,16 +629,7 @@ historical row — the pre-cutover `fleet-implementer` and
718
629
  A hand-set column would fail both of those tests, and one derived against
719
630
  today's declared tiers would mislabel every historical row.
720
631
 
721
- **The readout counts DELIBERATE comparisons.** An earlier rule asked
722
- only for a `session`+`role` carrying more than one distinct `model`, which any
723
- session that happened to stage a routine ticket beside a correction one
724
- satisfies. Measured 2026-09-12 on one corpus: 198 keys as that query was
725
- literally written, 35 sessions across 21 `run_date`s once restricted to
726
- implementers, against 17 real pairs across 8 — so the gate below read itself
727
- past its floor on sessions where nothing had been controlled. Dispatch alone
728
- is not enough either: the two rows must actually have RUN a different model or
729
- effort, because a deliberate dispatch whose two sides resolve to the same model
730
- (a `modelRoles` override, measured on omp 2026-09-12) controls nothing.
632
+ **The readout counts DELIBERATE comparisons.** See references/pull.md.
731
633
 
732
634
  **Why one in five within the run, not a week of one tier then a week of the other:**
733
635
  tier would then be confounded with calendar date and therefore with prompt
@@ -824,28 +726,7 @@ diff. **Phase 0 does not size anything** — it shortlists, a Pull claims, and
824
726
  the sizing run happens inside the member after both, which is why the verdict
825
727
  has to travel in the member's report rather than being something you already hold.
826
728
 
827
- **A verdict is a measurement only if it post-dates the run that produced it.** A
828
- `Sizing:` line typed in before the skill ever ran is byte-identical to one the
829
- skill produced, so the body cannot settle this alone, and neither can the
830
- member's prose. The report file carries the second source: `sizing.ranBeforePr`,
831
- whether `sizing-a-ticket` ran before the PR was opened (measured on a member
832
- that wrote the line first, caught itself, and corrected it), and
833
- `sizing.signal`, what the verdict turned on. `append` applies the rule itself:
834
- it records `sizing` only when `ranBeforePr` is true AND `signal` is non-empty.
835
- Any other state — no report file, one that fails its schema, `sizing` null,
836
- `ranBeforePr` not true, an empty `signal` — leaves the field BLANK with a
837
- WARNING naming which, and you say which in `note`. A `--sizing` you do pass
838
- wins over the file, and stderr names the flag as the source: do not use it to
839
- fill that gap, and do not re-derive the verdict from the diff to fill it
840
- either — `sizing-a-ticket` weighs more than file count, and a substituted proxy
841
- reads as measured too. **A value not in hand is left BLANK, never estimated** —
842
- blank reads as unknown and drops the row from a stratified comparison, while a
843
- guess reads as measured and poisons one. Blank still means the field is
844
- WRITTEN and empty: omit the flag (`--sizing`, `--profile`, `--loc`, `--files`)
845
- and the script writes that field empty at full width, because a row of some
846
- in-between width cannot be told apart from a shifted one. The `note` field is
847
- free text and sits before those four, so the script refuses a tab or newline in
848
- it: one tab would shift all four for that row alone.
729
+ **A verdict is a measurement only if it post-dates the run that produced it.** See references/reviewers.md.
849
730
 
850
731
  The member-facts scrape, the drain of the pending ticket-features rows and the
851
732
  commit of the metrics files are steps of `closeout.mjs finish`, which **End of
@@ -918,18 +799,7 @@ query before that one counted every session whose implementers merely
918
799
  differed, so it cleared this floor by an order of magnitude while the
919
800
  controlled comparison did not exist yet.
920
801
 
921
- Why the agent body carries what it does — read this before editing any
922
- `fleet-implementer-<cell>` file, and keep every cell's body byte-identical. Each rule in the body's
923
- enumerate-and-declare block is load-bearing, for a different reason.
924
- **Enumerate-and-declare** answers a signature measured four times in one run:
925
- each implementer fixed exactly the cases its ticket named and left an adjacent
926
- one of the same class broken — a CRLF body **broken by** the fix for depth and
927
- split headings, a symlinked worktree after fixing locked and regular-file ones,
928
- an unreadable `refs/heads/<type>/` after fixing `refs/heads` itself, a bracketed
929
- file path after fixing typos and vendored ones. **All four failed to close their
930
- own ticket** — one's acceptance criterion went unmet, and the other three left
931
- the named defect reachable by a sibling spelling. Every one was caught by
932
- review, at review cost, which runs 3-5x the implementation it checks.
802
+ Why the agent body carries what it does — read this before editing any `fleet-implementer-<cell>` file, and keep every cell's body byte-identical. See references/pull.md.
933
803
 
934
804
  **Prose-first** and **wrongly-REFUSE** are not padding — they are the case
935
805
  which shipped with **enumerate-and-declare** already in its prompt. It missed a
@@ -1351,13 +1221,7 @@ already handling is what makes that drain visible. **Every wake is still an
1351
1221
  edge, so none covers a fully drained queue**: no members and no open PRs is no
1352
1222
  event at all, and the tick goes unrun. That state is the heartbeat's.
1353
1223
 
1354
- **Beat when there is nothing to do, and never end your turn on a drained
1355
- queue.** You cannot be woken. A backgrounded Monitor does not wake an idle
1356
- agent — measured twice, see **A member runs its test suite in the foreground**
1357
- above, where `fix-pr-1184` backgrounded a suite plus a Monitor and sat idle for
1358
- roughly two hours — and `run-merge-bot.md`'s CI gate states the general rule:
1359
- "whatever wakes you is external and may never come". So hold the wait yourself,
1360
- exactly the way that gate does:
1224
+ **Beat when there is nothing to do, and never end your turn on a drained queue.** See references/ci-and-staleness.md.
1361
1225
 
1362
1226
  ```bash
1363
1227
  ~/.fleet/bin/fleet-run fleet-heartbeat.mjs \
@@ -1469,22 +1333,7 @@ event reads as unknown-behind. Call it **without `--quiet`** — that flag drops
1469
1333
  A monitor event is a wake-up, never a verdict; members re-query at labelling
1470
1334
  time. See references/ci-and-staleness.md.
1471
1335
 
1472
- **A conclusion is not stable, even for a fixed run id on an unchanged head.** A
1473
- rerun rewrites the run in place, so never cache a conclusion; key watchers on
1474
- `<run-id>:<attempt>:<conclusion>`. Leaving `attempt` out of the key is the bug
1475
- that looks like it works: a rerun that lands on the *same* conclusion regenerates
1476
- an already-seen key and fires nothing, so the second failure is silent and reads
1477
- exactly like a run still in progress. **Building that key with jq's `//` is the
1478
- same bug in the opposite direction**: `ci-state` reports an in-progress run as
1479
- `conclusion: ""`, and `//` catches `null` and `false` but never the empty
1480
- string, so `.conclusion // "-"` passes `""` straight through, keys a RUNNING job
1481
- as terminal and fires a spurious not-green — measured in four separate runs,
1482
- including one where the controller then had to re-arm blind. Test any fallback
1483
- you write against `""`, `null` AND a real conclusion, and check it still lets
1484
- the real one through: `map(if . == null or . == "" then "-" else tostring end)`.
1485
- Also: the newest
1486
- run on a branch is frequently *not* CI, so `--limit 1` can hide the CI result
1487
- entirely. See references/ci-and-staleness.md.
1336
+ **A conclusion is not stable, even for a fixed run id on an unchanged head.** Never cache a conclusion, and test any fallback you write against `""`, `null` AND a real conclusion. See references/ci-and-staleness.md.
1488
1337
 
1489
1338
  **A probe that cannot read is a transition event, not silence.** The natural
1490
1339
  watcher shape — `st=$(ci-state.mjs --pr "$pr" 2>/dev/null) || continue` — fails
@@ -1523,10 +1372,7 @@ while :; do # one tick
1523
1372
  cap_out=1
1524
1373
  fi
1525
1374
  # gh pr list is GraphQL, so $rl still holds. The pass is budgeted at 4 core
1526
- # REST units per listed PR on top of the 200 floor. The 4 is the measured
1527
- # ceiling of one ci-state.mjs call on the counter `gh api rate_limit`
1528
- # reports, for single-page reads: 2 on the common path, 4 for a PR whose
1529
- # head dropped required jobs.
1375
+ # REST units per listed PR on top of the 200 floor. See references/ci-watcher.md.
1530
1376
  # A shortfall here, or at the Actions-bucket gate below, pauses this tick's pass.
1531
1377
  if [ "$rl" -lt $((200 + 4 * count)) ]; then
1532
1378
  if [ -z "$budget_out" ]; then
@@ -1588,19 +1434,7 @@ while :; do # one tick
1588
1434
  done
1589
1435
  ```
1590
1436
 
1591
- **One gate, not a gate plus a caveat.** `jq -e '.verdict and .verdict !=
1592
- "rate-limited"'` exits non-zero on unparseable input *and* on a false result, so
1593
- that single test covers empty, garbage AND a self-named quota refusal. Empty
1594
- stdin produces no result at all, which `-e` reports as exit 4 (measured), so a
1595
- `[ -z "$st" ] ||` pre-check in front of it is a *second* gate testing what this
1596
- one already tests — the caveat this heading is about. Leaving
1597
- the named verdict to prose instead is how a watcher clears its latch on an
1598
- outage payload and hands it downstream as CI state — the very blindness this
1599
- section exists to remove, one level in. **The `.verdict and` half is load-bearing
1600
- and not belt-and-braces**: inequality alone never tests that a verdict *exists*,
1601
- so `{}`, `null` and `{"verdict":null}` all evaluate `null != "rate-limited"` →
1602
- true and clear the gate (measured), handing an empty or error object downstream
1603
- as a CI reading. Require the field, then compare it.
1437
+ **One gate, not a gate plus a caveat.** See references/ci-watcher.md.
1604
1438
 
1605
1439
  **It has to latch** — one line entering the degraded state, one leaving it,
1606
1440
  never one per tick. An unlatched line at a 120s poll gets the Monitor
@@ -1615,12 +1449,7 @@ what says the watch is alive again, so emit it on the first good pass even when
1615
1449
  nothing about the CI state changed; without it a reader cannot tell a recovered
1616
1450
  watcher from a dead one.
1617
1451
 
1618
- **All pacing in exactly one place — the tick loop's own tail `sleep`.** A sleep
1619
- inside the per-PR pass multiplies by the number of open PRs (8 open PRs → 960s
1620
- of pause per tick, against the 24s outage reset measured below), and a degraded
1621
- branch that `continue`s the *outer* loop skips the tail sleep and busy-spins
1622
- probe pairs during exactly the outage it is reporting. Every degraded
1623
- branch above falls through to the same single sleep instead.
1452
+ **All pacing in exactly one place — the tick loop's own tail `sleep`.** See references/ci-watcher.md.
1624
1453
 
1625
1454
  **Guard every probe, not just the ones with a verdict field.** The block makes
1626
1455
  several API calls, and `gh pr list` is the one that looks like
@@ -1632,7 +1461,8 @@ line — total silence per tick, which is exactly what this section exists to
1632
1461
  remove. Capture its status (`prs=$(…) || prs=ERR`), latch it globally, and fall
1633
1462
  through to the same tail sleep. **Then iterate with the inline `$(printf '%s\n'
1634
1463
  "$prs")` form, never a bare `for pr in $prs`** — the assigned-variable trap in
1635
- **Shell traps** above, which carries the mechanism and the measurements. It
1464
+ **Shell traps**, which carries the mechanism, with its measurements in
1465
+ references/shell-traps.md. It
1636
1466
  applies to **every** loop in this block, the `blind`-latch removal included:
1637
1467
  under a bare `for b in $blind` a recovered PR never leaves the list and the block
1638
1468
  emits a fresh RECOVERED every tick thereafter — the per-tick volume the latch
@@ -1649,51 +1479,7 @@ enforce. It latches globally like the list failure but does not pause polling:
1649
1479
  the PRs it did return are real, so the pass still watches them, and the
1650
1480
  DEGRADED line names the rest as unwatched until a pass comes back under the cap.
1651
1481
 
1652
- **The budget is gated at the floor and again at the pass, and only the pass
1653
- gates announce recovery.** The tick-top floor (`200`) covers the `rate_limit`
1654
- and `gh pr list` reads. Once the open-PR list is
1655
- read, the pass gate reserves `200 + 4 × count` core REST units — 4 per listed PR
1656
- on top of the floor, so the reserve grows with the list instead of staying a
1657
- flat 200 that a long list drains mid-pass. The 4 is the measured ceiling of one
1658
- `ci-state.mjs` call's cost on the counter `gh api rate_limit` reports (measured
1659
- 2026-10-13): 2 on the common path, 4 when the head dropped required jobs, for up
1660
- to 100 jobs and 100 rules — more pages cost more. That counter is not the only
1661
- core bucket one call bills. The lookups `actions/workflows`,
1662
- `actions/workflows/<id>`, `actions/workflows/<id>/runs` and `actions/runs/<id>`
1663
- bill a second one that `rate_limit` does not report; the boundary is per route,
1664
- so `actions/runs/<id>/jobs` is on the reported counter. Every response says
1665
- `X-Ratelimit-Resource: core`, so only the reset epoch and the used sequence tell
1666
- the two apart, and the unreported bucket's remaining count is readable only from
1667
- the `X-Ratelimit-Remaining` header of a call that bills it. **A second pass gate
1668
- therefore probes it too**: one `gh api -i` read of
1669
- `actions/workflows?per_page=1` per tick, 1 unit of that bucket (measured
1670
- 2026-10-13: its remaining count fell by 1 per call while `rate_limit` stood
1671
- still, and its reset epoch differed from `rate_limit`'s). A `ci-state` call
1672
- spends 4 units of it on the common path — one `gh run list` and one `gh run view`
1673
- cost 2 each (measured the same day) — so it is held to the same `200 + 4 × count`
1674
- reserve. It has its own global latch (`hidden_out`) and its DEGRADED and
1675
- RECOVERED lines name it, so a pause on this bucket is not misread as the
1676
- reported budget running low. An unreadable header is an outage here exactly as a
1677
- non-numeric `rate_limit` read is. The probe runs only when the reported-bucket
1678
- gate has cleared, so a tick costs at most one probe call. The gate pauses before
1679
- the per-PR pass, so it never touches the per-PR blind latch: a PR is either not
1680
- polled — no per-PR line, and one already latched blind stays latched — or polled
1681
- and reported through that latch alone, never by both. A shortfall at any of
1682
- these gates pauses the **whole** pass and never polls a prefix of the list: a prefix runs
1683
- in list order, so the same tail PRs would go unread every tick with no line at
1684
- all (never polled, so nothing marks them blind), while the PRs that were polled
1685
- would run dry mid-pass and each emit a blind line. The DEGRADED line from each
1686
- pass gate names the amount it needed and the count it needed it for — except an
1687
- unreadable header, which has no amount to compare and prints `bucket=ERR` alone
1688
- — so a healthy-looking `budget=999` is not read as an outage with no cause. Only the
1689
- pass gates emit RECOVERED lines — the budget's and the unreported bucket's, and the
1690
- open-PR list's and its cap's with them — and all of them only once the pass will
1691
- actually run: announcing recovery at the floor, or for one bucket while the other
1692
- still pauses the pass, would report resumption on a tick whose other gate then
1693
- pauses it again — a DEGRADED/RECOVERED pair every tick — and announcing the list or
1694
- its cap on the tick that reads it back would say polling resumed on a tick that
1695
- polls nothing. A list or cap latch held across a paused tick stays latched and says
1696
- nothing more.
1482
+ **The budget is gated at the floor and again at the pass, and only the pass gates announce recovery.** See references/ci-watcher.md.
1697
1483
 
1698
1484
  **Judge `ci-state` on its payload, never its exit code** — the same rule as
1699
1485
  `merge-gate.mjs` applies on the merge path, applied to the watcher. `not-green` is an
@@ -1705,12 +1491,7 @@ or unparseable output is the degraded case; parseable JSON reading
1705
1491
  reading, which is why the gate above tests the verdict rather than mere
1706
1492
  parseability: that payload is perfectly good JSON.
1707
1493
 
1708
- **Do not back off and wait.** These outages are short — a rolling window; one
1709
- measured reset came 24 seconds after `remaining: 0` — and pausing members for a
1710
- fixed interval stalls the fleet longer than the outage itself would have. A
1711
- retry-and-wait loop is what turns a 60s outage into a stalled member. Report it,
1712
- keep the local work moving (git, tests and mutation runs are all unaffected),
1713
- re-probe.
1494
+ **Do not back off and wait.** See references/ci-watcher.md.
1714
1495
 
1715
1496
  **While the budget is exhausted, `ledger.mjs check` reads
1716
1497
  `verdict: "unverified"`** — the ledger was read and the tracker was not. That is
@@ -1752,30 +1533,7 @@ cost one fleet five reports on one PR and four on another. None of it runs on
1752
1533
  your turn: a review takes 20-40 minutes, and a controller that held its turn
1753
1534
  for each one, one at a time, was what left implementer slots empty.
1754
1535
 
1755
- **Know the trim before you rely on it — it is wider than `docsOnly` suggests.**
1756
- `diff-stats.mjs` calls a PR docs-only only when it touches **no** src, tests *or*
1757
- config, but that strictness cuts both ways and the size tier trims again on top.
1758
- Measured: a docs PR that also adds one test file is profile `tests-only` and runs
1759
- **three** (correctness+tests+comments), not six; a no-src, no-test diff that
1760
- carries a config file keeps silent-failure at **any** size, so a docs+config diff
1761
- too big for the size tier now runs correctness+silent-failure+comments, not
1762
- correctness+comments; and any `single-file` or `small` profile trims to
1763
- correctness+silent-failure+comments, keeping tests only when a test file is in
1764
- the diff. `comments` is on that floor
1765
- unconditionally — it used to need a docs FILE, and `classify()` scores
1766
- only a prose extension or a README/CHANGELOG-style name docs, so five production PRs whose whole
1767
- substance was prose inside a `.js`/`.mjs`/`.sh` comment scored `docs: 0` and ran
1768
- without the one specialist that fit them, `dimensionsUnrun` empty every time.
1769
- That floor holds **regardless of `hasSrc`** — a one-file `.yml` or
1770
- `.github/` shell change gets silent-failure too, not correctness alone.
1771
- It is the size **tier's** floor,
1772
- so `tests-only` outranks it when the diff has no config file: that profile is
1773
- assigned ahead of `single-file`/`small`, so a no-src, no-config diff that also
1774
- touches a test file gets no silent-failure-hunter — a tests-only diff that also
1775
- carries a config file keeps it. `single-file` means one file at **any** size, so a
1776
- one-file rewrite trims too. An unknown profile widens to the full six, the safe
1777
- direction, so a trim is never something to count on in advance — and a full six
1778
- is never something to assume.
1536
+ **Know the trim before you rely on it — it is wider than `docsOnly` suggests.** See references/reviewers.md.
1779
1537
 
1780
1538
  **Review units are counted, never capped.** A review in flight — a
1781
1539
  `review-pr-<pr#>` member still running — is one; each
@@ -1987,34 +1745,7 @@ prints no `DISPATCH fix-pr` for it, `dispatch` refuses the finisher naming
1987
1745
  `dispositions escalate`, and you post the check's output with `gh pr comment <M>`
1988
1746
  and flag the PR for a human. A new review of the PR counts again from none.
1989
1747
 
1990
- **A refutation resting on an injection nothing proved landed is not a refutation
1991
- — it is a cell that never ran.** A mutation test and a finding reproduction are
1992
- both failure injections: break something, read what the child does. When the
1993
- break never reaches the child, the child behaves exactly like its baseline, which
1994
- is what a genuine no-effect mutation looks like and what a correctly refuted
1995
- finding looks like. So a negative result is admitted only together with its
1996
- **positive control** — one run proving the injected difference is observable,
1997
- either the child's output differing with the injection present versus absent or
1998
- the child echoing the injected value back from inside. No control → the cell is
1999
- unrun: re-run it, and never record it as a negative. Measured 2026-08-28 and
2000
- re-measured on this tree, against a `probe.sh` that echoes both variables back:
2001
-
2002
- ```sh
2003
- zsh -c 'cfg="SETB=1 BADJ=1"; env $cfg sh ./probe.sh' # BADJ=[unset] SETB=[1 BADJ=1]
2004
- bash -c 'cfg="SETB=1 BADJ=1"; env $cfg sh ./probe.sh' # BADJ=[1] SETB=[1]
2005
- ```
2006
-
2007
- zsh does not word-split an unquoted parameter expansion, so the whole string
2008
- arrives as ONE argument: a variable literally named `SETB` takes the value
2009
- `1 BADJ=1`, the injection variable `BADJ` is never set, and the probe still exits
2010
- 0. It bites in both directions, and the reproduction direction is the worse one —
2011
- `fix-pr-983` nearly reported a mutant as behaving identically to its baseline,
2012
- while `fix-pr-1153` nearly retired a real review finding as non-reproducing after
2013
- the same shape handed both trees a single argv word and drew `exit 2` from each,
2014
- which is the signature of a correct refutation with nothing anomalous to notice.
2015
- The fix-applier body and every refuter brief carry the rule and the safe
2016
- invocation form; the merge bot's brief is the wrong seat, because a bot
2017
- reads gates and never injects a fault.
1748
+ **A refutation resting on an injection nothing proved landed is not a refutation — it is a cell that never ran.** See references/reviewers.md.
2018
1749
 
2019
1750
  **The suite slot bound.** At most `FLEET_SUITE_SLOTS` full suite runs execute on
2020
1751
  a host at once — 2 by default, whatever the member caps count — because each run
@@ -2070,15 +1801,7 @@ and the review (`review-core.mjs`, in a runner) reads the same cache itself,
2070
1801
  refusing outright when there is none; the fix-applier has no such fallback, so
2071
1802
  substituting `<testCmd>` with nothing leaves it no gate at all.
2072
1803
 
2073
- **Where `<branch>` comes from:** the PR's head branch —
2074
- `gh pr view <N> --json headRefName -q .headRefName`, or the same branch you cut
2075
- the worktree from. Pass it as `--branch`, because
2076
- the member cannot read it off git: references/isolation.md creates an already-open PR's worktree
2077
- with `--detach`, and there `git branch --show-current` prints nothing and exits 0
2078
- (measured 2026-09-18, git 2.50.1), so `git push origin
2079
- "HEAD:$(git branch --show-current)"` exits 128 on `fatal: invalid refspec
2080
- 'HEAD:'`. A brief rendered without it would leave the push no destination at
2081
- all, which is why the renderer requires it.
1804
+ **Where `<branch>` comes from:** the PR's head branch — `gh pr view <N> --json headRefName -q .headRefName`, or the same branch you cut the worktree from. See references/reviewers.md.
2082
1805
 
2083
1806
  **What a fix-applier receives.** Its standing text — the worktree and
2084
1807
  session-root discipline, the review result file and every ruling on it, the
@@ -2173,16 +1896,7 @@ merge, and a finisher on it would race the conflict fix-applier rebasing it.
2173
1896
  Dispatch that fix-applier, let it settle `applied:`/`no-op`, then dispatch the
2174
1897
  finisher again.
2175
1898
 
2176
- **An unanswered question from the member is an outbox item, and it blocks
2177
- dispatch with the same weight as a ruling you have already made.** It does not
2178
- feel like one — you have decided nothing yet, so the outbox reads empty — but a
2179
- member waiting on you is a member that will push once you answer, and the SHA
2180
- you are about to pin is exactly what that push moves. Measured on one run:
2181
- a `fix-pr-<M>` member asked whether to add two pins, and the finisher was held until the
2182
- member acknowledged the answer. That worked because the controller chose to
2183
- hold, not because a rule required it. Answer it, or tell the member you are not
2184
- ruling and it should proceed on its own default — either empties the outbox.
2185
- What does not empty it is noticing the question and dispatching anyway.
1899
+ **An unanswered question from the member is an outbox item, and it blocks dispatch with the same weight as a ruling you have already made.** See references/finisher.md.
2186
1900
 
2187
1901
  **A final report is not proof the member stopped.** Observed twice: a ruling
2188
1902
  relayed after dispatch produced a new commit mid-audit, and a fix-applier that
@@ -2220,30 +1934,7 @@ means, and a bare SHA mismatch names no cause. **Pass `--testCmd` too** —
2220
1934
  the same string you passed the workflow and the fix-applier — because duty
2221
1935
  2's mutation gate runs it and nothing else hands the finisher one; the renderer
2222
1936
  refuses a finisher brief rendered without it.
2223
- 2. **Confirm every deferral — and every claimed APPLY — has a home that outlives
2224
- the merge.** The test is a durable home, not a tracker number: a tracker
2225
- issue and a committed in-tree comment both qualify, and for a finding whose
2226
- remedy was measured worse than the defect the in-tree note is the better one.
2227
- What fails is a promise living only in a PR body, or on the PR's *own* source
2228
- issue, which `Closes #N` buries on merge. Caught once at seven findings. A
2229
- comment on an existing *follow-up* issue is filed: that is
2230
- `review-and-fix.md` step 5, not a violation. Not filed → file it or halt,
2231
- never label over it — and file it the way step 5 does, through
2232
- `ledger.mjs check "<subject>"`, never a bare search, labelled `needs-triage`
2233
- as every issue the plugin creates is, its body carrying the refuter's
2234
- verdict or the review's votes and the candidate remedy. A duplicate is a
2235
- comment citing that verdict on the existing issue, never a relabel: an open
2236
- `ready-for-agent` issue triage already promoted holds the deferral as it
2237
- stands. Only triage sets `ready-for-agent`, and step 5's guard on this rule —
2238
- open `needs-triage` issues citing `Deferred from PR` above 40 on 3
2239
- consecutive run dates send it back to the maintainer — counts these
2240
- filings too. The finisher files last,
2241
- off its own read of what the reviewer left behind, so a deferral it reads as
2242
- unfiled may already be on the tracker under someone else's wording. Then
2243
- record it the way step 5 does: `ledger.mjs filed <N> "<subject>"`
2244
- immediately after `gh issue create`, with the same subject string you passed
2245
- to `check`. If `filed` fails, retry once; if it fails again, leave the issue
2246
- alone — it exists and is correct — and report it `unrecorded: #N <subject>`.
1937
+ 2. **Confirm every deferral — and every claimed APPLY — has a home that outlives the merge.** See references/finisher.md.
2247
1938
 
2248
1939
  **A fix-applier's "applied" is a claim like any other**, and nothing else
2249
1940
  checks it — the review ran against a snapshot cut before those edits existed.
@@ -2252,49 +1943,11 @@ refuses a finisher brief rendered without it.
2252
1943
  one found five applies where the controller's hand-written list named three:
2253
1944
  a controller's list of what to verify is itself a claim.
2254
1945
 
2255
- **That range is right for the positive check and wrong for a negative one.**
2256
- It spans the implementer's commits too, so a constraint of the form *file X
2257
- was not touched* has to be scoped to the apply commit. Measured on one PR:
2258
- a controller wrote "neither document was touched" against
2259
- `origin/main...HEAD` on a two-commit branch whose documents the IMPLEMENTER
2260
- had correctly edited — the PR's whole point — and a finisher reading that
2261
- literally halts a correct PR. It caught the error instead, and said so; do
2262
- not rely on that.
2263
-
2264
- **Whatever you verify by RUNNING, run in a tree nobody else owns.**
2265
- Independently re-running the ticket's acceptance mutation — loosen the
2266
- regex, delete the guard clause, flip the per-entry reset, run `<testCmd>`,
2267
- confirm a kill by the test-run verdict rule below, discard — is the half of this duty reading a diff cannot
2268
- do, and it stays. But it **writes**, and the PR's worktree belongs to
2269
- another member. Measured once: a finisher was inside that worktree at the
2270
- instant the fix-applier announced one more clause to land, and neither
2271
- ordering is detectable afterwards from the diff — a restore lands on the
2272
- uncommitted clause and destroys it silently, or the mutant is still in the
2273
- tree when the fix-applier commits and a deliberately broken guard ships as
2274
- the fix, in a commit nothing re-reviews. So take your own:
2275
- `git worktree add --detach <scratch>/pr<N>/finish-<your member name> <your dispatch pin>`,
2276
- mutate and run `<testCmd>` in there, then
2277
- `git worktree remove --force <scratch>/pr<N>/finish-<your member name>`.
2278
- **At your dispatch pin, never at the fetched branch tip** — duty 1 just
2279
- proved the owned worktree sits at that pin, and `PR headRefOid` may carry
2280
- commits no reviewer read, the substitution the halt block's head-equality
2281
- check rejects for the same reason. `<scratch>` is the absolute root your dispatch prompt names. The member name is in the path because
2282
- the scratch root is shared with every sibling, so `<scratch>/pr<N>` alone
2283
- collides whenever a PR gets a second finisher, and `worktree add` on an
2284
- occupied path fails closed into a halt with a purely mechanical cause.
2285
-
2286
- **Remove it on every path, the failing ones included** — a mutant that comes
2287
- back green, a suite that will not start, your own halt at any duty. `--force`
2288
- is required and is right only here: the tree is deliberately dirty when you
2289
- are done, so a plain `git worktree remove` refuses it (`contains modified or
2290
- untracked files`, rc 128, directory left on disk — measured, git 2.50.1),
2291
- while everywhere else in this runbook that refusal is a finding precisely
2292
- because the dirt may be someone's only copy. Here nothing in it is anyone's.
2293
- Nothing sweeps a leak for you either: `reap.sh`'s branchless sweep is bounded
2294
- to the fleet's worktree home, so a tree under `<scratch>` is a `kept` entry
2295
- it reports and never collects. No claim built the tree you added, so it has
2296
- `./agent-test` only if the repository tracks one — run that or `<testCmd>`
2297
- in it, per `references/isolation.md`, **A reused worktree may lack the runner**.
1946
+ **That range is right for the positive check and wrong for a negative one.** See references/finisher.md.
1947
+
1948
+ **Whatever you verify by RUNNING, run in a tree nobody else owns.** See references/finisher.md.
1949
+
1950
+ **Remove it on every path, the failing ones included** — a mutant that comes back green, a suite that will not start, your own halt at any duty. See references/finisher.md.
2298
1951
 
2299
1952
  **None of this licenses a write to the owned worktree.** Duty 1 is a read;
2300
1953
  you never restore that tree, because you never wrote to it. A controller
@@ -2440,16 +2093,7 @@ Both → add the label, and say it rests on the reviewer's suite run, not on CI.
2440
2093
  Either missing → halt here, same as a dirty worktree: report `no CI configured,
2441
2094
  no verified suite run on record` and add no label.
2442
2095
 
2443
- **Every implementer body carries the claim discipline, because tickets that
2444
- restate facts ship new wrong claims** — inherited from the ticket, and minted
2445
- in prose nobody asked for. It was measured on tickets that would have been
2446
- judged routine too: an unasked-for comment asserting a silent-failure mode
2447
- that does not exist, a false comparative plus positional references replacing
2448
- a name-based one, and two present-tense counts already false when they were
2449
- written.
2450
- Nothing before dispatch can see the diff, so the discipline goes to every
2451
- implementer. A pushed commit body cannot be edited, so its claims are settled
2452
- at write time. See references/correction-tickets.md.
2096
+ **Every implementer body carries the claim discipline, because tickets that restate facts ship new wrong claims** — inherited from the ticket, and minted in prose nobody asked for. See references/correction-tickets.md.
2453
2097
 
2454
2098
  **The settling command for "which files read X" must never be a literal-path
2455
2099
  grep.** The path is assembled in more than one spelling here, one of them behind
@@ -2460,16 +2104,7 @@ which suites red: that answers which ones **depend on its contents**, which is
2460
2104
  the question a coverage claim actually needs, and it returns a different set
2461
2105
  from any spelling of the grep.
2462
2106
 
2463
- **A settling command over literal text uses `grep -F`, and its zero counts only
2464
- after the same command finds a line known to match.** Prose fragments and
2465
- code snippets routinely carry `\`, `.`, `*`, `[` or `$`, and without `-F` those
2466
- are read as a pattern rather than as the text itself, so the command answers
2467
- for a different string from the one the claim names — and a wrong zero is the
2468
- benign-looking answer. Measured once: `grep -c 'settled by:\s+x'` answers
2469
- 0 against a file holding that exact line, and `grep -cF` answers 1. A zero or
2470
- an absence counts only after the same command, with the same flags, finds a
2471
- line known to match: a command that cannot find a match settles nothing, and
2472
- under `Verified:` its zero reads as a checked absence.
2107
+ **A settling command over literal text uses `grep -F`, and its zero counts only after the same command finds a line known to match.** See references/correction-tickets.md.
2473
2108
 
2474
2109
  ### Merge bot
2475
2110
 
@@ -2508,14 +2143,16 @@ doesn't already cover.
2508
2143
  **The shell traps live in the merge bot's agent body, not in its brief and not
2509
2144
  in a follow-up message.** A bot already looping cannot be corrected — the loop
2510
2145
  consumes the turns a correction would land in — so
2511
- `agents/fleet-merge-bot.agent.md` carries **every entry in Shell traps**, copied
2512
- from that section, and the bot has them before its first turn. The bot reads an
2513
- exit code off `gh pr update-branch`, `merge-gate.mjs` and `prove-merge.sh`,
2514
- which is the `PIPESTATUS` and read-only-`status` pair, and its grace poll
2515
- captures `gh pr list` output and loops over it, which is the assigned-variable
2516
- trap. Its brief names the bot and `<scratch>`, plus the one-line
2517
- no-acknowledgement notice; do not paste the
2518
- traps there. An edit to Shell traps lands in that body in the same change.
2146
+ `agents/fleet-merge-bot.agent.md` carries **every entry in Shell traps**, each
2147
+ written out in full: the rules in that section with the measurements from
2148
+ `references/shell-traps.md` beside them, and the bot has them before its first
2149
+ turn. The bot reads an exit code off `gh pr update-branch`, `merge-gate.mjs` and
2150
+ `prove-merge.sh`, which is the `PIPESTATUS` and read-only-`status` pair, and its
2151
+ grace poll captures `gh pr list` output and loops over it, which is the
2152
+ assigned-variable trap. Its brief names the bot and `<scratch>`, plus the
2153
+ one-line no-acknowledgement notice; do not paste the traps there. An edit to
2154
+ Shell traps or to `references/shell-traps.md` lands in that body in the same
2155
+ change.
2519
2156
 
2520
2157
  **Its merge gate is one script, run twice.** Step 3 of `run-merge-bot.md` is
2521
2158
  `merge-gate.mjs --pr <n> --pre <sha> [--post <sha>]`: read-only, it runs the
@@ -2651,9 +2288,6 @@ ledger rows in the same step. See references/reaping.md.
2651
2288
 
2652
2289
  ## Worktree and claim model
2653
2290
 
2654
- Measured 2026-09-09 in a throwaway clone (`/tmp/fleet-probe`)
2655
- that never touched the real checkout.
2656
-
2657
2291
  **Claim, release and reap are unchanged on omp.** `claim-ticket.sh`,
2658
2292
  `release-ticket.sh`, `reap.sh` and `inflight.sh` are git-native and operate on
2659
2293
  the single shared ref store every worktree and the main checkout read and
@@ -2661,86 +2295,15 @@ write directly (**Phase 1**, **Reap after each merge pass**, **Release the claim
2661
2295
  that never became PRs** above); nothing in omp's `task` model touches that
2662
2296
  store, so none of the four scripts carries a dialect branch.
2663
2297
 
2664
- **A fleet member is never dispatched with omp's `isolated: true`.** Measured:
2665
- an isolated spawn builds its workspace under `~/.omp/wt/<hash>/m` — an APFS
2666
- clone (on this box), never a registered `git worktree` of the repo — and,
2667
- because `apply` defaults to `true`, its changes are patch-applied into the
2668
- **calling session's own cwd** the instant the spawn completes: a file an
2669
- isolated probe created there appeared as `?? probe-isolated.txt` in the probe
2670
- session's own cwd — which for an actual fleet run is the controller's main
2671
- checkout — not in the worktree the prompt named. That is the exact
2672
- silent-spill hazard this section exists to guard against, on by default, so
2673
- `isolated` stays unused for every member and `task.isolation.enabled` stays
2674
- off.
2675
-
2676
- **A member's tree is the claimed worktree, addressed by absolute path.** An
2677
- `edit` header without the worktree prefix resolves into the main checkout,
2678
- where `member-write-guard` refuses it (**You read your instruments out of a
2679
- tree every member can write to** above). How a
2680
- member gets its cwd: the `task` tool's item schema — `name`/`agent`/`task`/
2681
- `outputSchema`/`schemaMode` always, `effort`/`isolated` only when their own
2682
- settings enable them — carries no working-directory field; measured
2683
- directly: a member dispatched through it with none of those fields, told
2684
- only to report `pwd`, returned the calling session's own cwd, not the
2685
- claimed worktree, the same output an un-`cwd`-set `bash` call gives from
2686
- that session, so the recipe is the dispatch-prompt absolute path, plus
2687
- `bash`'s own `cwd` parameter set to it on every call and absolute paths for
2688
- `write`/`edit`.
2689
-
2690
- **The one open gap that probe measured: `task` does not accept a per-dispatch
2691
- working directory.** `omp://tools/task.md` documents non-isolated spawns as
2692
- running `runSubprocess(...)` "directly with parent cwd" — no `cwd` field
2693
- appears anywhere in the item schema — and the probe above confirms it in
2694
- practice: the recipe is the absolute-path discipline above, not a placeholder
2695
- for a `cwd` field that does not exist. The gap is now enforced rather than only
2696
- written down: the plugin's `member-write-guard` omp extension
2697
- refuses a fleet member's `write`/`edit`/`ast_edit` into the main checkout's
2698
- non-ignored tree and an implementer's `bash` from a main-checkout cwd, and the
2699
- missing field itself is requested upstream in `can1357/oh-my-pi`.
2700
-
2701
- **The same gap reaches past the filesystem: `task`-dispatched members share one
2702
- `eval` kernel.** Measured 2026-09-21, in a live run rather than a
2703
- probe clone: two sibling implementers dispatched in the same batch, and the
2704
- controller that dispatched both, reported the same Python kernel pid and the
2705
- same runner file under `$TMPDIR/omp-python-runner/`, and each read the others'
2706
- top-level bindings out of its own `eval` cell — a bare `WT` bound by one member
2707
- was read back by a sibling and by the controller, the collision a ticket was filed
2708
- on as an unproven self-report. `omp://tools/eval.md` states the mechanism:
2709
- retained kernels are keyed by `python:${sessionId}`, normalized cwd and
2710
- interpreter — `js:${sessionId}` for the JS VM — and "Parent and ordinary task
2711
- subagents may share an inherited eval executor id; children created by eval's
2712
- own `agent()` explicitly do not." Neither key component separates two members
2713
- of one run: the session id is inherited from the controller, and the cwd is the
2714
- main checkout for all of them, because `eval`, unlike `bash`, takes no `cwd`
2715
- parameter to set. So the absolute-path discipline above is load-bearing inside
2716
- `eval` too, and it needs one rule `write`/`edit` do not — member-prefixed
2717
- binding names, since a shared global has no path to be absolute about. The
2718
- corollary is `reset`: it "is likewise destructive to concurrent work sharing
2719
- that backend session", so a member resetting its own kernel resets every
2720
- concurrent sibling's. No per-dispatch knob turns any of this off: `task`'s item
2721
- shape carries no kernel, executor or cwd field, and `python.kernelMode` set to
2722
- `"per-call"` — the one documented lever that would hand every call a fresh
2723
- kernel — is a session setting a child inherits, not something one dispatch can
2724
- set for one member. Isolating a member's kernel is an omp-side change, so
2725
- discipline is the whole of the remedy here — unlike the missing `cwd` field
2726
- above, which `member-write-guard` enforces for `write`/`edit`/`ast_edit` and
2727
- `eval` bypasses. **Phase 2** carries all three rules to every member.
2728
-
2729
- **`release-ticket.sh` is not a no-op on omp, and `inflight.sh`'s probes are
2730
- unaffected by a running member.** Measured against a hand-built claim (a
2731
- branch plus a `git worktree add`) with a member sleeping inside it: a `bash`
2732
- call with `cwd` set to the worktree, and a non-isolated `task` spawn told to
2733
- work there, both operate inside the existing worktree and leave `git worktree
2734
- list` unchanged — they coexist with the claim rather than duplicating it. An
2735
- isolated spawn is architecturally blind to the worktree — its relative writes
2736
- land in its own `~/.omp/wt/…` workspace regardless of the prompt — but it
2737
- neither removes nor hides the claim, and `~/.omp/wt/` was empty after every
2738
- isolated run: omp's own teardown touches only omp's own workspace, never the
2739
- claim. `release-ticket.sh`'s three-artifact teardown (label, worktree, branch)
2740
- is therefore still necessary. With the member live inside
2741
- the worktree, `git worktree list` and `git branch --list` from the main
2742
- checkout reported the claim unchanged before, during and after — `inflight.sh`
2743
- hides nothing from omp.
2298
+ **A fleet member is never dispatched with omp's `isolated: true`.** See references/isolation.md.
2299
+
2300
+ **A member's tree is the claimed worktree, addressed by absolute path.** See references/isolation.md.
2301
+
2302
+ **The one open gap that probe measured: `task` does not accept a per-dispatch working directory.** See references/isolation.md.
2303
+
2304
+ **The same gap reaches past the filesystem: `task`-dispatched members share one `eval` kernel.** See references/isolation.md.
2305
+
2306
+ **`release-ticket.sh` is not a no-op on omp, and `inflight.sh`'s probes are unaffected by a running member.** See references/isolation.md.
2744
2307
 
2745
2308
  **The controller's own cwd stays the main checkout, unchanged.** Nothing in
2746
2309
  this section's dispatch recipe — the cwd recipe above, the isolated-workspace
@@ -2786,18 +2349,7 @@ where the controller itself runs from.
2786
2349
  until a merge brings the count below it; reviewers, finishers and the merge
2787
2350
  bot never slow for it. The tick's `B`.
2788
2351
 
2789
- **Default: In-flight bound 5, fixed for the run.** The level is set by load, not
2790
- throughput: B caps live review units (≤ open PRs ≤ B), and the review side is
2791
- about 84 % of cache-write tokens, fanning out to 1 snapshot + up to 6
2792
- specialists + 2 refuters per finding. 5 keeps worst-case review concurrency
2793
- below the former reviewer count of 6 and sits near the measured mean In flight
2794
- of 5.6. On the means that allows ≈ 1.7 merges per open-time hour against 1.89
2795
- measured, so the default does not rest on throughput headroom and the guard's
2796
- throughput test may trip on it; the merge gate saturates near 10–11, so
2797
- raising B past that buys nothing. 8 was rejected: peak review concurrency above
2798
- the former reviewer count, for a throughput gain the backlog does not show it
2799
- needs. Re-derive it from the map's guard once 20 or more PRs have merged under
2800
- it, never from one run's rows.
2352
+ **Default: In-flight bound 5, fixed for the run.** See references/pull.md.
2801
2353
 
2802
2354
  **The review backlog never gates, and the merge-queue depth is still no
2803
2355
  signal.** The only gate on a Pull is the In-flight count. A deep backlog is a
@@ -2937,47 +2489,16 @@ vs specific finding with paths → paths win.
2937
2489
  **Members share one filesystem, one docker stack and one process table**, and the
2938
2490
  failures arrive as *wrong findings*, not errors:
2939
2491
 
2940
- - **A pattern kill reaches siblings — the implementer, fix-applier and finisher briefs forbid it.** `pkill -f
2941
- <pattern>` matches on the whole command line, machine-wide. Members hold
2942
- separate worktrees, but the process table is not partitioned by them and a
2943
- test file's name is identical in every one, so a pattern naming a test file
2944
- matches whichever member happens to be running it. Measured: an implementer
2945
- chasing its own stalled run issued a `pkill -f` on its test file's name and
2946
- killed a `node --test` over two test files that was not
2947
- its own.
2948
-
2949
- **What the victim's output looks like depends on the signal — and one of the
2950
- cases is a clean green.** Each measured on node v26.8.1/darwin against a
2951
- purpose-spawned fixture killed by its own PID. `pkill -f` **defaults to
2952
- SIGTERM**, and a SIGTERMed runner prints `Interrupted while running:` followed
2953
- by a *complete* summary block with `cancelled` non-zero, exiting `rc=1` — so
2954
- `cancelled` is exactly the thing to search for in the default case. `pkill -9
2955
- -f` leaves no summary block at all and the shell reports `rc=137`: SIGKILL
2956
- means the harness never lived long enough to report. A kill landing on one of
2957
- node's per-file **child** test processes leaves a complete block with `fail`
2958
- non-zero and `cancelled 0` at `rc=1`, indistinguishable from an ordinary test
2959
- failure. And a kill landing on a process a **test itself spawns** leaves a
2960
- complete `pass N / fail 0 / cancelled 0` at the expected N over a corrupted
2961
- run: `spawnSync` reports a SIGKILLed child as `status null`, and a test
2962
- asserting only that the process it spawned exited non-zero —
2963
- `assert.notEqual(r.status, 0)`, a form used across this suite, in files that
2964
- spawn the shell scripts they cover — passes vacuously on `null`.
2492
+ - **A pattern kill reaches siblings — the implementer, fix-applier and finisher briefs forbid it.** See references/isolation.md.
2493
+
2494
+ **What the victim's output looks like depends on the signal — and one of the cases is a clean green.** See references/isolation.md.
2965
2495
 
2966
2496
  So **a complete summary block proves the runner survived, not that the run was
2967
2497
  uncontaminated.** Scrutinize reds, short counts *and* greens from inside the
2968
2498
  incident window; a killed **baseline** compared against a clean mutant is a
2969
2499
  wrong measurement that reads exactly like a real result.
2970
2500
 
2971
- **The command line is no partition either — not reliably.** Ports are derived
2972
- per issue precisely so collisions are impossible; argv isolates a run only
2973
- sometimes. Measured with `ps -Ao pid,ppid,args -ww` (without `-ww` macOS `ps`
2974
- truncates, and the truncation reads as an absence): an invocation carrying an
2975
- **absolute** path puts a member-unique string in argv, while one carrying
2976
- repo-relative filenames is byte-identical across members. Which of the two you
2977
- get is not yours to choose — members are briefed on `./agent-test` with the
2978
- arguments the Test entrypoint takes, and the runner hands them on exactly as
2979
- its caller's shell expanded them. Clearing your own leftover process needs its
2980
- PID, not a pattern.
2501
+ **The command line is no partition either — not reliably.** See references/isolation.md.
2981
2502
 
2982
2503
  Members report a stalled run to the controller instead of pattern-killing it,
2983
2504
  and the controller re-checks any measurement taken in the window.
@@ -3080,14 +2601,7 @@ dirty again. Any other path on that line is a stray write — leave the hold for
3080
2601
  the maintainer, because `--record` would certify it with yours. Live members
3081
2602
  hold the old text — re-brief only if it changes what they do *now*.
3082
2603
 
3083
- **Landing it.** The file being right is not the end of it. `main` carries a
3084
- ruleset with no bypass actors, so a direct `git push origin main` is **refused** —
3085
- `! [remote rejected] main -> main (push declined due to repository rule
3086
- violations)`, measured 2026-08-10 by a controller that tried exactly that at the
3087
- end of a 7-PR run. A mid-run tooling fix goes through a PR like every other
3088
- change, and that PR faces every required check any other PR faces — the set
3089
- `.github/rulesets/main.json` declares — so it carries a release label too.
3090
- Plan it as a PR the run's own merge queue lands, never as an edit-and-continue.
2604
+ Plan it as a PR the run's own merge queue lands, never as an edit-and-continue. See references/merge-bot.md.
3091
2605
 
3092
2606
  ## Failure handling
3093
2607
 
@@ -3113,36 +2627,7 @@ Plan it as a PR the run's own merge queue lands, never as an edit-and-continue.
3113
2627
 
3114
2628
  A red PR never silently becomes `ready-to-merge`.
3115
2629
 
3116
- **A frozen transcript does not establish that a member is dead — the
3117
- discriminator is its scratch dir.** A member wedged on a blocked tool call
3118
- emits the whole signature of a dead one: record counts unchanged from one poll
3119
- of its transcript to the next. So read the mtimes of the files anywhere under
3120
- the scratch directory its own dispatch prompt assigned it, subdirectories
3121
- included — `<scratch>/impl-<N>/` for an implementer, that member's own
3122
- run-scoped subdirectory under `<scratch>/pr<N>/` on the review side, never
3123
- the bare `pr<N>/` tree those siblings share — since a member waiting on a
3124
- child it dispatched writes nothing itself while that child writes below it.
3125
- Read them at two observations a poll apart — `touch` a marker file outside
3126
- that directory at the first, and
3127
- `find <dir> -type f -newer <marker>` at the second lists every file that
3128
- moved: **mtimes that moved between the two mean BLOCKED, a live member
3129
- still holding its claim and its worktree, so the killed row above does not
3130
- apply to it; mtimes unchanged at both are the dead signature.** Only the first
3131
- of those two verdicts is conclusive — a member wedged on a call that writes
3132
- nothing freezes its scratch dir too — so settle the dead one on the Member
3133
- unaccounted row above, never on the two listings alone. Measured once: a refuter
3134
- wedged forever on `until grep -q` for a marker `node --test` never writes, its
3135
- transcript's record counts unchanged across two polls while its own scratch
3136
- files carried fresh mtimes throughout — alive the entire time it read as dead.
3137
- The filenames are not a contract: they are whatever that member happens to be
3138
- writing, and they differ by member and by role. That second listing is cheap
3139
- at the price, because the cost of the wrong call is asymmetric — a live member
3140
- written off gets killed and re-dispatched, which discards the work in flight
3141
- and, where it holds a claim or a worktree, collides the fleet with itself,
3142
- while one poll spent on a member that had in fact stopped costs only the poll.
3143
- The refuter's own observation rule in the fix-applier body stops a
3144
- member from creating that state; this one stops you from misreading whoever
3145
- reaches it anyway, and neither replaces the other.
2630
+ **A frozen transcript does not establish that a member is dead — the discriminator is its scratch dir.** See references/failure-handling.md.
3146
2631
 
3147
2632
  Settle outcome and liveness are different facts, not the same table with two
3148
2633
  spellings. Recovery is a fresh member, fresh name (`impl-<N>-b`,
@@ -3335,60 +2820,18 @@ Plus two append-only lists:
3335
2820
  - **ruled** (`ledger.mjs ruled <pr> <decision>`) — PR + decision + one-line reason,
3336
2821
  so a replacement controller does not re-litigate a settled call.
3337
2822
 
3338
- **Writer policy: the controller owns run state (`row`/`token`/`settle`/`dispatch`/`review`/`drain`/`ruled`);
3339
- filers append filings with `filed`; all writes are serialized by `<file>.lock`.**
3340
- Every write rewrites the whole file from what it read, so without the lock two
3341
- concurrent writers are last-writer-wins — measured, 8 concurrent `filed` kept
3342
- 2–5 of 8 rows. A writer that cannot take the lock within 10 s exits 2
3343
- naming the holder's pid, having written nothing; a lock whose holder is dead is
3344
- taken over, and a leftover `<file>.lock.reap` is never reclaimed. One other
3345
- shape wedges the lock permanently the same way, needing the same fix: an empty
3346
- `<file>.lock` — its writer was killed between creating it and writing its pid
3347
- into it — is unparseable and therefore, by design, always read as live rather
3348
- than handed to the death check; its timeout names `<file>.lock` itself, since
3349
- there is no pid to name. A zombie holder — a pid whose process exited
3350
- but whose parent never `wait()`-ed on it — also answers a liveness check as
3351
- alive, because the OS keeps a reserved pid until it is reaped, but that is
3352
- transient, not a wedge: once the pid is reaped (the parent's own exit is
3353
- normally enough to trigger this), the next writer's death check reads it as
3354
- dead and takes the lock over the same as any other dead holder — no hand
3355
- removal needed. The other two shapes do not clear on their own — remove
3356
- `<file>.lock` or `<file>.lock.reap` by hand once nothing is writing. Reads
3357
- (`check`, `read`) take no lock.
2823
+ **Writer policy: the controller owns run state (`row`/`token`/`settle`/`dispatch`/`review`/`drain`/`ruled`); filers append filings with `filed`; all writes are serialized by `<file>.lock`.** See references/ledger.md.
3358
2824
 
3359
2825
  **The suite slots wedge the same ways, and clear the same way.**
3360
2826
  `~/.fleet/suite-slots/<i>.lock` is built on the ledger's lock primitive, so an empty or
3361
2827
  unparseable `<i>.lock` and a leftover `<i>.lock.reap` are permanent, a zombie
3362
2828
  holder is transient, and a dead holder is taken over. A wait that expired with
3363
2829
  exit 75 names each wedged file — remove it by hand once no suite run is
3364
- running, the way `<file>.lock` is removed above.
3365
-
3366
- **The gap the lock does not close:** `check` → `gh issue create` → `filed` is
3367
- three commands, and the lock covers each one alone, so two filers can both read
3368
- `clean` in the seconds before either records. Accepted — the measured
3369
- same-run accidental duplicate was filed minutes apart — and no
3370
- claim/reserve step exists to close it.
3371
-
3372
- `check` exits **0** clean, **1** already in this run's filed list, **2** usage
3373
- error (no JSON on stdout), **3** the ledger is clean but open or closed tracker issues match — read
3374
- those and decide. Exit **3** is scored: some row gh returned has to score above
3375
- zero against the subject, because the ANDed query also matches issues the
3376
- overlap rates 0.00, and every measured stop over those was survived only by a
3377
- reader who overrode it and searched the tracker by hand — obeying it would have
3378
- dropped a real deferral. It also prints the closest filed rows with an overlap score.
3379
- Those never move the exit code — the same finding gets worded differently by
3380
- whoever finds it second — but once the tracker read succeeds, a filed row at or
3381
- above `NEAR_SOFT_HIT` in `ledger.mjs` does move the verdict to `soft-hit`, as
3382
- does a tracker set with no scoring row in it; a read that failed stays
3383
- `unverified`, which outranks both. **Exit 0 is not automatically "safe to file":** when `gh`
3384
- cannot be reached the answer is ledger-only, and it says `TRACKER NOT CHECKED` —
3385
- an issue filed by an earlier run is invisible to it; and `soft-hit` means rows
3386
- worth reading were found while none of them established a duplicate, so read
3387
- them before filing. The stdout JSON names all of that in one field:
3388
- `verdict` is `already-filed`, `tracker-hit`, `clean`, `soft-hit` or
3389
- `unverified`. Only `already-filed` and `tracker-hit` carry a non-zero code, so
3390
- `verdict` is the only thing that tells a searched-and-clean tracker from one
3391
- that was never read and from one whose rows you have to read yourself.
2830
+ running, the way references/ledger.md removes `<file>.lock`.
2831
+
2832
+ **The gap the lock does not close:** `check` → `gh issue create` → `filed` is three commands, and the lock covers each one alone, so two filers can both read `clean` in the seconds before either records. See references/ledger.md.
2833
+
2834
+ `check` exits **0** clean, **1** already in this run's filed list, **2** usage error (no JSON on stdout), **3** the ledger is clean but open or closed tracker issues match — read those and decide. See references/ledger.md.
3392
2835
 
3393
2836
  The ledger half reports its own readability as its own field, `ledger.ok`, the
3394
2837
  peer of `tracker.ok`: false when the file did not exist, and false too when the