@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.
- package/agents/fleet-recipe-deriver.agent.md +17 -7
- package/commands/review-and-fix.md +1 -1
- package/commands/run-merge-bot.md +1 -1
- package/package.json +1 -1
- package/scripts/derive-testcmd.sh +32 -11
- package/scripts/recipe-prove.mjs +43 -7
- package/scripts/review-core.mjs +44 -1
- package/skills/run-team/SKILL.md +68 -625
- package/skills/run-team/references/ci-and-staleness.md +27 -1
- package/skills/run-team/references/ci-watcher.md +88 -0
- package/skills/run-team/references/correction-tickets.md +27 -1
- package/skills/run-team/references/failure-handling.md +35 -0
- package/skills/run-team/references/finisher.md +93 -0
- package/skills/run-team/references/instruments.md +19 -0
- package/skills/run-team/references/isolation.md +140 -1
- package/skills/run-team/references/ledger.md +57 -0
- package/skills/run-team/references/member-lifecycle.md +43 -1
- package/skills/run-team/references/merge-bot.md +14 -0
- package/skills/run-team/references/pull.md +60 -0
- package/skills/run-team/references/reviewers.md +98 -0
- package/skills/run-team/references/shell-traps.md +55 -0
package/skills/run-team/SKILL.md
CHANGED
|
@@ -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
|
-
|
|
44
|
-
|
|
45
|
-
|
|
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.**
|
|
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
|
-
|
|
212
|
-
|
|
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 `$?`.
|
|
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.**
|
|
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.**
|
|
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.**
|
|
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.**
|
|
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.
|
|
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.**
|
|
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`.**
|
|
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
|
|
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.**
|
|
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
|
-
|
|
2257
|
-
|
|
2258
|
-
|
|
2259
|
-
|
|
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**,
|
|
2512
|
-
|
|
2513
|
-
|
|
2514
|
-
|
|
2515
|
-
|
|
2516
|
-
|
|
2517
|
-
|
|
2518
|
-
|
|
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`.**
|
|
2665
|
-
|
|
2666
|
-
|
|
2667
|
-
|
|
2668
|
-
**
|
|
2669
|
-
|
|
2670
|
-
|
|
2671
|
-
|
|
2672
|
-
|
|
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.**
|
|
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.**
|
|
2941
|
-
|
|
2942
|
-
|
|
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.**
|
|
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
|
-
|
|
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
|
|
3365
|
-
|
|
3366
|
-
**The gap the lock does not close:** `check` → `gh issue create` → `filed` is
|
|
3367
|
-
|
|
3368
|
-
`
|
|
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
|