@feigi/fleet-ctl 3.54.3 → 3.56.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.
@@ -10,20 +10,7 @@ arg violations violations
10
10
  path worktree
11
11
  path scratch
12
12
  path mismatched-record
13
- literal N
14
- literal test
15
- literal cmd
16
13
  literal your name
17
- literal subject
18
- literal finding
19
- literal base
20
- literal args
21
- literal the run root's name in the review path
22
- literal the review file's head
23
- literal sha
24
- literal member
25
- literal helper
26
- literal file
27
14
  ---
28
15
  ## kind: review, dispositions-retry
29
16
  You are ALREADY in worktree `<abs-path>`, whose PR branch is `<branch>` — the
@@ -38,16 +25,6 @@ it. Do NOT create another worktree. There is no review file: the PR sits on a
38
25
  conflict hold and you are here to clear it — do not review, do not dispatch
39
26
  specialists.
40
27
 
41
- ## kind: review, conflict, dispositions-retry
42
- **`edit` and `read` resolve a bare relative path against the SESSION ROOT —
43
- the controller's own main checkout — not against that worktree and not
44
- against your `bash` cwd, which they share no `cwd` parameter with. Give them
45
- the absolute worktree path on every call, mutation-probe copies included.**
46
- The main checkout is the parent of `git rev-parse --path-format=absolute
47
- --git-common-dir`. A `member-write-guard` refusal means the path hit the
48
- main checkout — for `bash`, a missing or main-checkout `cwd` — so re-issue
49
- it absolute, under your worktree.
50
-
51
28
  ## kind: review, dispositions-retry
52
29
  Read `$(~/.fleet/bin/fleet-run --root)/commands/review-and-fix.md` and run **steps 2, 3
53
30
  and 5 only**: split apply-now/defer, commit, push, file every deferral as its
@@ -66,192 +43,6 @@ and `cwdAudit` before any result of the shared test run. Every one of those
66
43
  rulings is yours — nobody upstream has made one, and the controller never
67
44
  reads the findings.
68
45
 
69
- **Every factual claim your diff restates needs a settling command run
70
- against the tree first** — the issue body is a lead, never a citation.
71
- **No positional references** (`the closing/second/last X`); name the thing
72
- semantically. **Never write a COUNT or a tally into prose; state the
73
- property instead** — unless it is a past-tense record of a measurement you
74
- performed, which stays as written; a present-tense claim about a live
75
- property must be restated as a property (`every other test in the file`),
76
- true at any count. **A settling grep over literal text takes `grep -F`, and
77
- its zero counts only after the same command finds a line known to match.**
78
-
79
- **Apply `survived` findings. A finding in `unverified` whose refuters ran and
80
- crashed or abstained always defers** — and which it is, you read off
81
- `refutersDispatched` and `refutersInconclusive`, never off severity and never
82
- off an empty vote list: `refutersDispatched` above zero with nothing decided
83
- means every refuter dispatched against it died or abstained, and
84
- `refutersInconclusive` counts the ones that abstained. Severity records how much a
85
- finding would matter if true, never whether anything looked. Say *in the
86
- deferral* which it was rather than that it went unchecked. Name a crash as
87
- crashed refuters — the review re-dispatched each crash once already and
88
- reports what died again, so a deferral that names the crash can still be
89
- re-verified. An abstention is not a crash: cite the inconclusive runs each
90
- abstaining refuter named in its `reason`, and never describe its refuters as
91
- crashed. **A `suggestion` is also in `unverified`,
92
- for a different reason — `refutersDispatched` of zero, the 0-refuter budget
93
- the review gives that band by policy — and the rule below, not this one,
94
- covers it.**
95
-
96
- **A `suggestion` is budgeted 0 refuters, so it is unchecked until you check
97
- it.** For each one, first decide scope: is it inside the scope of the PR's own
98
- ticket, or a different piece of work? **Out of scope → defer and file, never
99
- apply** — but the claim bar runs first: an out-of-scope suggestion whose
100
- claim is about shape (`claimKind: shape`) gets no refuter and goes to the
101
- closed suggestion-band record, and every other one gets the same refuter an
102
- in-scope one does, dispatched the same way, before it is filed.
103
- **In scope → dispatch ONE refuter** against the finding before
104
- touching the tree, biased to refuse, and hand it the prompt below with one
105
- substitution: resolve `<scratch>/pr<N>/<finding>/` in it to an absolute path
106
- under your own run root — `mktemp -d` once per round for
107
- `<scratch>/pr<N>/fix-XXXXXXXX/`, never bare `pr<N>`, since finding ids
108
- restart at 1 each round too — and write that absolute path into the
109
- refuter's prompt in its place; a refuter never derives its own path:
110
-
111
- > Try to REFUTE this finding. Default to refuted=true if uncertain. Verify by
112
- > RUNNING something — compile it, run the test, apply the mutation. Do not
113
- > reason your way to agreement. Observe that run synchronously — run the
114
- > command, wait for it, read its exit code. Never poll a log file for a
115
- > completion marker: prefer ONE blocking run to a poll loop, and treat its
116
- > return as permission to look, never as the answer. Reading a log the run has
117
- > already finished writing is fine; waiting on one is not. If you match a test
118
- > reporter's own output, accepting both `ℹ` and `#` is necessary but NOT
119
- > sufficient — strip SGR escapes first as well. node's prefix moves with the
120
- > node version and with whether stdout is a TTY, and color wraps the whole line
121
- > so it begins with ESC and no prefix anchor matches at all, which returns
122
- > empty at exit 0 — indistinguishable from a hung run and from a run of zero
123
- > tests. For an uncolored baseline use `env -u FORCE_COLOR`; `FORCE_COLOR=`
124
- > empty still enables color, so it is not a control. State your search scope
125
- > AND what your pattern would have missed. A grep over one ref does not
126
- > support a claim about history; a pattern built from the token a diff removed
127
- > does not support a claim that the category is empty.
128
- >
129
- > When your check scores a mutant killed or a test red, run only in your own
130
- > copy of the tree, and these rules decide it and nothing else:
131
- >
132
- > **Valid red:** a run that completed — the command returned on its own, with no
133
- > signal and no timeout, deadline or kill having fired — in which the test the
134
- > claim names is reported failing. An exit ≠ 0 with no failing test is not red,
135
- > and a different test failing is not red for this claim. A red in the full
136
- > suite only triggers a narrowed run; it is never evidence on its own.
137
- >
138
- > **Narrowed run:** the Test entrypoint with arguments appended, `<testCmd>
139
- > <args>`. That appended arguments reach the Test entrypoint is all that is
140
- > promised about them, so a narrowed run counts only if it reports `tests` > 0
141
- > and its output names the claimed test. If no narrowing can be proven, run the
142
- > full `<testCmd>` and read the named test's own result from its output.
143
- >
144
- > **Kill:** the mutant produced a valid red in a narrowed run, and the same
145
- > narrowed command, in the same tree with the mutant reverted, ran a valid green
146
- > with the named test passing — completed, exit 0, `tests` > 0, `cancelled` 0. A
147
- > completed exit ≠ 0 with the named test not failing is not a kill, and no kill
148
- > stands without that green run on the unmutated tree. The result is
149
- > inconclusive, never a kill, when the red does not reproduce in the narrowed
150
- > run, when the unmutated tree is red too, or when no usable run exists.
151
- >
152
- > **Evidence line:** every kill and every valid red you claim carries one line
153
- > in the claim's own free-text field: `red: <cmd> → exit N, fail K incl <test>;
154
- > baseline: <cmd> → exit 0, <test> pass`. A failing-test finding filed off the
155
- > review's shared run carries the `red:` half alone.
156
- >
157
- > This refuter has no abstain: a run that could not decide — neither a valid red
158
- > nor a valid green — is no kill and no refutation, so name the runs in
159
- > `reason`, each with its evidence line, and leave `refuted` true, so the
160
- > suggestion defers on the record instead of applying on a check that decided
161
- > nothing.
162
- >
163
- > A failure injection with
164
- > no positive control has produced NO result, never a negative one. Before you
165
- > read an injected fault — an env var, an argv word, a mutant — as having had
166
- > no effect, prove the injection reached the child: one run whose output
167
- > differs with it present versus absent, or the child echoing the injected
168
- > value back. Uncontrolled, the cell is unrun — say so in your verdict instead
169
- > of reporting a no-effect result. Build such an invocation as an array
170
- > expanded braced and quoted —
171
- > `cfg=(SETB=1 BADJ=1); env "${cfg[@]}" sh ./probe.sh` — or inline the
172
- > assignments literally — `env SETB=1 BADJ=1 sh ./probe.sh`; NEVER from an
173
- > unquoted scalar — `cfg="SETB=1 BADJ=1"; env $cfg sh ./probe.sh` — which under
174
- > zsh passes ONE argument, sets a variable literally named `SETB` to
175
- > `1 BADJ=1`, never sets `BADJ` at all, and still exits 0. `env $cfg[@]` is not
176
- > the portable spelling either: measured, bash word-splits it into `SETB=1`
177
- > and `BADJ=1[@]`, so the injection variable is set to a corrupted value,
178
- > while zsh behaves exactly as with the bare `$cfg` — `BADJ` never set,
179
- > exit 0. Everything you
180
- > write — mutants, fixtures,
181
- > scratch repos — goes under `<scratch>/pr<N>/<finding>/` and nowhere else;
182
- > the checkout and any worktree are never write targets, though
183
- > `git show`/`git archive` at a pinned ref read fine anywhere. Chain the
184
- > directory change into the command, `cd "$D" && git …`, never
185
- > `cd "$D"; git …`, so a failed `cd` cannot leave a `git` command running in
186
- > the checkout — and bracket a fixture's own git with
187
- > `git rev-parse --show-toplevel`: before `git init` it must NOT resolve to
188
- > the host repository, and `fatal: not a git repository` (exit 128) is the
189
- > usual pass, not a failure — an outer repository whose ignore rules cover
190
- > your scratch dir is a pass too; before any `git commit` it must resolve to
191
- > your scratch path, which catches a forgotten `git init` under any enclosing
192
- > repository — compare resolved forms (`realpath`), since `--show-toplevel`
193
- > can report a symlinked parent such as `/tmp` or a symlinked `$HOME` under
194
- > its resolved name.
195
-
196
- Survives → apply it, with one hold: if its refuter reports a blast radius
197
- touching lines another finding also changes, that is the mutual-exclusion
198
- scan's second input — rule the pair before either change reaches the tree;
199
- you hold every finding, so only you can see that the two cannot both land. Refuted → defer and file it, and
200
- say the refutation in the issue body. **Apply only what survives — no report is not a survival.** A
201
- refuter you never hear from leaves the finding exactly as unchecked as it
202
- arrived, so it defers like a refuted one.
203
-
204
- **Out of scope, the refuter decides only where the suggestion is filed — it
205
- defers either way, never applied.** Refuted → the closed suggestion-band
206
- record, never an open issue. Survived, or its refuter crashed or abstained →
207
- its own open issue labelled `needs-triage`, citing the verdict, or the run
208
- that crashed, in the body. There is no cap on these refuters: count the ones
209
- you dispatch against out-of-scope suggestions, since your report names that
210
- count.
211
-
212
- **A finding's `suggested_fix` is a hypothesis, not a patch — the review never
213
- ran it.** Only the claim is verified adversarially; the remedy text is unchecked.
214
- Three were wrong as written in one run: a stated end state that dropped a
215
- load-bearing option and measured RED, an assertion against a property the test
216
- helper does not expose (`TypeError`), and an enumeration that stopped short of
217
- two further stale clauses — one of them false in the *dangerous* direction. Run
218
- the remedy before you commit it, and re-derive an assertion from the post-fix
219
- tree rather than from the finding, since a sibling finding may edit the very
220
- text it asserts on.
221
-
222
- **Retrieve that report yourself; do not wait to be handed it — this covers the
223
- refuters YOU dispatch, and only those.** The review's own specialists do leave
224
- transcripts, but nothing gives you their address: the review had `agent()`
225
- return their findings into the script, so the result file holds their findings
226
- and names no transcript, and nothing on disk indexes a transcript by PR or
227
- dimension. Hunting their paths gets you nothing; read the file. A report from a refuter you spawned is
228
- different — it surfaces to the controller rather than to you, and waiting for a
229
- relay that never comes strands the finding. Its transcript is at the output file
230
- named in your spawn result, and its report is the last record:
231
-
232
- A depth-2 helper cannot dispatch further (`task.maxRecursionDepth: 2`); reach it directly instead, by its full dotted id (`<member>.<helper>`), via `hub send` — delivered, woken, no transcript workaround needed.
233
-
234
- If retrieval comes back empty, ask the controller by name. Only when neither
235
- works is the finding **unchecked** — defer and file it, and say so in the body. This is
236
- `review-and-fix.md`'s **Specialists** rule; it reaches you here because the
237
- steps that point at it are the ones you skip.
238
-
239
- The CI facts in that file apply to you — a `rebase-check` red, or heavy jobs
240
- `skipped`, **solely** off a non-zero behind-count, is staleness and not a
241
- failure. Never rebase to clear it. **`solely` is the load-bearing word:**
242
- `ci.yml`'s `rebase-check` exits 1 on five conditions and only one is
243
- staleness, so a non-zero behind-count does not by itself settle which fired.
244
- The job log names the condition — and because the staleness condition exits
245
- before the merge-commit condition is evaluated, the log is silent on that one
246
- by construction, so measure it separately with
247
- `git fetch origin && git rev-list --merges --count "origin/<base>..HEAD"` —
248
- keep the fetch, or a stale local `origin/<base>` widens the range over the
249
- base's own merge commits and reports a merge commit this branch never added.
250
- A non-zero count does not send you to a local rebase either: the merge bot's
251
- step-1 `gh pr update-branch --rebase` drops merge commits too
252
- (`run-merge-bot.md` step 1), so both conditions clear on that one server-side
253
- rebase. What it buys you is knowing the red was never solely staleness.
254
-
255
46
  **Run `<testCmd>` from the worktree before committing**, copied verbatim.
256
47
  `tests 0` is a FAILED run, not a pass. Red or zero-test → fix it, or move that
257
48
  finding to defer; never commit over it. **Never `--no-verify`** — a failing
@@ -260,133 +51,9 @@ result with your SHA. Nothing re-reviews this commit: the review ran against a
260
51
  snapshot cut before your edits existed, and a refuter checked the finding's
261
52
  claim, never your patch.
262
53
 
263
- **A test you ADD must kill its own mutant** — break what it pins, confirm it and
264
- only it goes red and that the red is a kill by the rules below, restore. **Then
265
- a change it should *not* catch, staying green** — else you proved it fails, not
266
- that it discriminates: a pin asserting whole-file text clears "it and only it
267
- goes red" and still reddens on any edit (measured). A green suite says nothing
268
- about a new test: one pin this run survived the exact mutation it was named for.
269
-
270
- **Valid red:** a run that completed — the command returned on its own, with
271
- no signal and no timeout, deadline or kill having fired — in which the test
272
- the claim names is reported failing. An exit ≠ 0 with no failing test is not
273
- red, and a different test failing is not red for this claim. A red in the full
274
- suite only triggers a narrowed run; it is never evidence on its own.
275
-
276
- **Narrowed run:** the Test entrypoint with arguments appended,
277
- `<testCmd> <args>`. That appended arguments reach the Test entrypoint is all
278
- that is promised about them, so a narrowed run counts only if it reports
279
- `tests` > 0 and its output names the claimed test. If no narrowing can be
280
- proven, run the full `<testCmd>` and read the named test's own result from its
281
- output.
282
-
283
- **Kill:** the mutant produced a valid red in a narrowed run, and the same
284
- narrowed command, in the same tree with the mutant reverted, ran a valid green
285
- with the named test passing — completed, exit 0, `tests` > 0, `cancelled` 0. A
286
- completed exit ≠ 0 with the named test not failing is not a kill, and no kill
287
- stands without that green run on the unmutated tree. The result is
288
- inconclusive, never a kill, when the red does not reproduce in the narrowed
289
- run, when the unmutated tree is red too, or when no usable run exists.
290
-
291
- **Evidence line:** every kill and every valid red you claim carries one line
292
- in the claim's own free-text field:
293
- `red: <cmd> → exit N, fail K incl <test>; baseline: <cmd> → exit 0, <test> pass`.
294
- A failing-test finding filed off the review's shared run carries the `red:`
295
- half alone.
296
-
297
- An inconclusive result proves nothing about the test: do not report the test
298
- as proven, and measure again in a clean state. Put each kill's evidence line in
299
- your report, beside the test result.
300
-
301
- **A mutation that never landed is not a green — it is a cell that did not
302
- run.** Same rule for any fault you inject to see what breaks: prove the
303
- injection reached the child before you read its result — one run whose output
304
- differs with the injection present versus absent, or the child echoing the
305
- injected value back. Without one, a probe that exits 0 reporting the mutant
306
- behaving exactly like its baseline is indistinguishable from a real no-effect
307
- result, and a reproduction that never happened reads as a refutation. Build
308
- such an invocation as an array expanded braced and quoted —
309
- `cfg=(SETB=1 BADJ=1); env "${cfg[@]}" sh ./probe.sh` — or inline the
310
- assignments literally — `env SETB=1 BADJ=1 sh ./probe.sh`; NEVER from an
311
- unquoted scalar — `cfg="SETB=1 BADJ=1"; env $cfg sh ./probe.sh` — which under
312
- zsh passes ONE argument, sets a variable literally named `SETB` to `1 BADJ=1`,
313
- never sets `BADJ` at all, and still exits 0. `env $cfg[@]` is not the portable
314
- spelling either: measured, bash word-splits it into `SETB=1` and
315
- `BADJ=1[@]`, so the injection variable is set to a corrupted value, while
316
- zsh behaves exactly as with the bare `$cfg` — `BADJ` never set, exit 0.
317
-
318
- **Commit BEFORE you mutate, and restore with `cp`, never a git discard.**
319
- `git checkout -- <file>` reverts the whole file, not your mutant — so it also
320
- eats uncommitted edits you made earlier, and the "clean baseline" you measure
321
- next is silently the reverted file. Two members hit this in one run; one lost
322
- prose edits and caught it only because a non-catch control failed. Copy the
323
- file aside and copy it back. Better still, mutate a copy under
324
- `<scratch>/pr<N>/mutate/` and leave the worktree untouched — that is what
325
- refuters are already required to do, and it has no blast radius at all.
326
-
327
- **Never `git stash` or `git stash pop` here either — a WIP commit is the
328
- substitute, not a second scratch mechanism: `git commit -m wip`, then
329
- restore or amend once you're back to real work.** The stash stack is
330
- repo-global too, not per-worktree or per-session — the same `refs/stash`
331
- every concurrent member and the main checkout share, not partitioned the
332
- way `<scratch>/pr<N>/mutate/` above is. A bare pop takes whichever entry is
333
- on top, from any worktree, silently — rc 0, no error — when the tree
334
- receiving it is clean on the affected paths, and refuses only when that
335
- tree is already dirty there. A bare `git stash` (push) does not reach into
336
- a sibling's tree, so that half is not the risk — the pop is. Nothing
337
- partitions the stack; this prohibition is the whole of the protection.
338
-
339
- **Report LAST, and only once nothing can still change.** A report you have
340
- sent **pins that SHA** for the controller, which dispatches a finisher against
341
- it. If a further instruction arrives after you have reported, reply saying the
342
- SHA is moving *before* you touch the tree again — do not silently do the work
343
- and re-report. Measured: three members in one run sent a final report and kept
344
- working; one had its worktree audited mid-mutation, another handed over a SHA
345
- that was two commits stale, and a finisher dispatched on either would have
346
- halted on a diverged head.
347
-
348
54
  **Before you report, write every ruling to `<scratch>/dispositions-<your name>.json`**,
349
55
  `<your name>` the `fix-pr-<pr>[-x]` you were dispatched as — the record the controller checks with
350
- `dispositions-check.mjs` before it dispatches any finisher. It is
351
- `{"head": "<the review file's head>", "run": "<the run root's name in the review path>", "entries": [ … ]}`
352
- — `run` the `<run>` of the review path above, which the check holds against the
353
- review the PR's latest `reviewed=` names: a record written against an earlier
354
- review, a same-head one included, is a mismatch. One entry per
355
- `survived` finding and per `unverified` finding, plus one per `refuted`
356
- finding you reverse. Each entry carries `bucket`
357
- (`survived|unverified|refuted`), `index` (its position in that bucket of the
358
- review file), `scope` (`in|out`), `claimKind` (`behavior|shape`) and
359
- `disposition` (`apply|defer`), and where they apply `reason`, `issue` (the
360
- number you filed it to or commented on), `verdictPath` (a suggestion's
361
- refuter verdict file, in scope and, above the claim bar, out of scope) and
362
- `remedyFiles` (the files its remedy names). An out-of-scope suggestion whose
363
- refuter crashed before any verdict reached you still names the path its
364
- verdict would have taken. A `refuted` entry carries `scope`, `claimKind` and `disposition`
365
- like every other entry, and a non-empty `reason` holding the evidence that
366
- reverses it; a missing or blank `reason` is a mismatch. A finding with no
367
- `line`, or on a line the PR's diff touched —
368
- `git diff` from its merge-base with `origin/main` to the review's head — is
369
- in scope whatever its `scope` says. An in-scope `survived` finding you defer
370
- carries `reason` `false-rationale`, `mutual-exclusion`, `remedy-worse` or
371
- `remedy-outside-diff`; the last needs `remedyFiles` to name a file the PR's
372
- diff does not touch, and for a `critical` or `important` finding it sends the
373
- PR to a human instead of passing. Any
374
- other reason, none, or a `survived` or `unverified` finding with no entry is
375
- a mismatch, and the PR gets no finisher. `disposition` has no `dismiss`: an
376
- in-scope `survived` finding verified correct, needing no change, is deferred
377
- with `reason` `false-rationale` and filed on the closed suggestion-band
378
- record.
379
-
380
- Then report to the controller the pushed SHA, your apply/defer split, how
381
- many refuters you dispatched against out-of-scope suggestions, and
382
- the deferral issue numbers — a `filed: #N <subject>` line for every issue
383
- step 5 created, and `unrecorded: #N <subject>` for one whose `ledger.mjs filed`
384
- failed twice — and exit. **Deferring everything is a normal
385
- outcome, not a stall:** nothing is then staged, `git commit` refuses an empty
386
- index, `git push origin HEAD:<branch>` prints `Everything up-to-date`, and you
387
- report `no-op, HEAD unchanged at <sha>` in place of a new SHA. Say it
388
- explicitly — silence there is indistinguishable from a member that died. Never
389
- manufacture a commit to make CI fire.
56
+ `dispositions-check.mjs` before it dispatches any finisher.
390
57
  ## kind: conflict
391
58
  Bring `<branch>` current with `origin/main`, resolving every conflict by the
392
59
  **No-undo audit** in `$(~/.fleet/bin/fleet-run --root)/commands/run-merge-bot.md`.
@@ -2,80 +2,9 @@
2
2
  arg n n
3
3
  arg scratch scratch
4
4
  path scratch
5
- literal N
6
5
  ---
7
- You are merge-bot-<n>. Read `$(~/.fleet/bin/fleet-run --root)/commands/run-merge-bot.md` and run **one**
8
- pass — drain the queue, re-evaluating after each merge, hold a 15-minute grace
9
- for late labels, then report once and exit. The controller dispatched you, which
10
- is what makes you hold that grace instead of arming your own watcher.
6
+ You are merge-bot-<n>.
11
7
 
12
- Your scratch directory is `<scratch>/`; you write only under
13
- `<scratch>/pr<N>/merge-bot-<n>/`.
14
-
15
- **zsh word-splits an unquoted command substitution's result; it does NOT split
16
- an unquoted parameter expansion.** That one difference is the whole rule, and the
17
- hazard is the **assigned-variable** form, never `$(…)`. Measured on zsh 5.9
18
- against `849`, `850`, `852` on three lines:
19
-
20
- | Form | zsh | bash / sh |
21
- |---|---|---|
22
- | `prs=$(gh pr list …)` then `for pr in $prs` | **1 iteration**, all three glued into one value | 3 |
23
- | `for pr in $(gh pr list …)` | 3 | 3 |
24
- | `for _ in $(seq 1 60)` | 60 | 60 |
25
-
26
- **Word the rule against the first row.** A warning spelled *never `for x in
27
- $(…)`* names the safe form as the hazard, so a reader avoids the form that works,
28
- keeps the one that collapses, and rewrites correct bounded polls on the way.
29
- A ticket was once filed carrying that inversion in its own remedy clause and in its title,
30
- and its filer measured both forms and retracted it; the corrected rule is this
31
- row. `$(…)` splits. Leave it alone.
32
-
33
- **Capture-then-loop needs `while IFS= read -r` fed by a heredoc**, which is
34
- line-exact under every shell:
35
-
36
- ```sh
37
- while IFS= read -r pr; do
38
- [ -n "$pr" ] || continue # a blank line from an empty capture, not a probe that could not look
39
- node …/ci-state.mjs --pr "$pr" </dev/null # every inner call, per the trap below
40
- done <<EOF
41
- $prs
42
- EOF
43
- ```
44
-
45
- The inline `$(printf '%s\n' "$prs")` form splits correctly too and is what Phase
46
- 3's block uses, but it splits on *every* whitespace character, so it is safe only
47
- for values that cannot contain one — PR numbers cannot, branch names and paths
48
- can. Measured on a two-line list whose first value is `two words`: three
49
- iterations through `$(printf …)`, two through `while IFS= read -r`. On an empty
50
- `$prs` the counts diverge the other way: `for pr in $(printf '%s\n' "$prs")`
51
- iterates **zero** times, but the heredoc form iterates **once** with `pr` empty —
52
- the guard above is what stops that iteration from probing `--pr ""`.
53
-
54
- **`</dev/null` every command inside a `while read` loop.** The loop's stdin *is*
55
- the list, and any inner command that reads stdin eats the rest of it. Measured on
56
- the three-line list above: one unredirected inner reader takes the loop to **1
57
- iteration**, `</dev/null` on it restores 3 — the identical signature to the
58
- word-split bug, so a correct heredoc fix missing this half looks exactly like no
59
- fix at all, and reads as one.
60
-
61
- **A probe that could not look emits an event; it never `continue`s.** Stated in
62
- full at *A probe that cannot read is a transition event, not silence* in Phase 3,
63
- and it binds every watcher in this file rather than that one block: the third
64
- value beside pass and fail is what turns a broken loop into a loud failure
65
- instead of a quiet one. A guard that drops an unreadable probe — `[ -n "$json" ]
66
- || continue` — makes *could not look* indistinguishable from *nothing to report*.
67
-
68
- **`$?`/`PIPESTATUS` is unconditionally-TRUE in zsh.** zsh has no `PIPESTATUS`
69
- (its array is lowercase `pipestatus`, 1-indexed), so `${PIPESTATUS[0]}` is always
70
- empty and `[ "" -eq 0 ]` passes. A bot's merge gate opened without ever reading
71
- an exit code.
72
-
73
- **`status` is a READ-ONLY variable in zsh**, an alias for `$?`. So the obvious
74
- bash idiom for reading the payload — `status=$(jq -r '.status' ci.json)` — aborts
75
- with `read-only variable: status`. Measured this way it fails safe (a hard abort,
76
- no merge), but the same assignment inside an `if`, or with stderr suppressed,
77
- reads as a check that silently did not run. Same root cause as the `PIPESTATUS`
78
- trap, opposite failure direction — so name the variable anything else
79
- (`ci_status`).
8
+ scratch: <scratch>
80
9
 
81
10
  The controller does not acknowledge reports. Send once and exit; never re-send unless the controller asks by name.