@feigi/fleet-ctl 3.55.0 → 3.57.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.
@@ -164,11 +164,12 @@ makes one up.
164
164
  ## Shell traps
165
165
 
166
166
  Monitor and Bash commands run under **zsh**, and the shell in this file is
167
- prescriptive — copied verbatim into a watcher or pasted into a bot's brief. So
168
- every trap here is a zsh-vs-bash difference that ships as a green-looking gate:
169
- correct in the shell you tested in, silently wrong in the one it runs in. Phase
170
- 3's monitor paragraph and the **Merge bot**'s brief both point here
171
- instead of restating any of it; the one deliberate copy is named at the end.
167
+ prescriptive — copied verbatim into a watcher or into the merge bot's agent
168
+ body. So every trap here is a zsh-vs-bash difference that ships as a
169
+ green-looking gate: correct in the shell you tested in, silently wrong in the
170
+ one it runs in. Phase 3's monitor paragraph points here instead of restating
171
+ any of it. The merge bot's agent body is the one place this block is copied
172
+ whole (see **Merge bot**); the other deliberate copy is named at the end.
172
173
 
173
174
  **zsh word-splits an unquoted command substitution's result; it does NOT split
174
175
  an unquoted parameter expansion.** That one difference is the whole rule, and the
@@ -236,7 +237,7 @@ reads as a check that silently did not run. Same root cause as the `PIPESTATUS`
236
237
  trap, opposite failure direction — so name the variable anything else
237
238
  (`ci_status`).
238
239
 
239
- **The one deliberate copy is `env $cfg sh ./probe.sh`.** The first trap's
240
+ **The other deliberate copy is `env $cfg sh ./probe.sh`.** The first trap's
240
241
  mechanism bites argv as well as loops, and that instance stays written out in the
241
242
  fix-applier prompt and every refuter brief under **Reviewers** rather than here,
242
243
  because the seats that inject faults are the ones that need it and a bot reads
@@ -1223,9 +1224,12 @@ that the tier it resolves to is now declared and pinned rather than inherited by
1223
1224
  accident. Keep `name: impl-<N>`: the name is what makes a member, and both the
1224
1225
  spend classifier and `member-outcomes.mjs` read it.
1225
1226
 
1226
- **After every Pull's dispatch, run the tier check — a scripted step, never a
1227
- prose reminder.** `~/.fleet/bin/fleet-run tier-check.mjs --batch <path-to-batch.json>`
1228
- judges the implementer just dispatched on the ledger's terms. The definition it
1227
+ **After every Pull's dispatch, the tier check runs — a scripted step, never a
1228
+ prose reminder.** `tick --apply` runs it itself, a batch of one apiece, on every
1229
+ implementer it would print `HOLD (tier unchecked impl-<N>)` for, `session` off
1230
+ the phase-0 receipt, and prints `APPLIED tier-check impl-<N>: <verdict>`. By
1231
+ hand it is `~/.fleet/bin/fleet-run tier-check.mjs --batch <path-to-batch.json>`,
1232
+ which judges the implementer just dispatched on the ledger's terms. The definition it
1229
1233
  should have run under comes off its ticket row's `tier=` token: none means the
1230
1234
  policy cell, `fleet-implementer-slow-high`; `tier=<cell>` means
1231
1235
  `fleet-implementer-<cell>` — the same mapping `ledger.mjs dispatch` prints its
@@ -1261,8 +1265,9 @@ verdicts, whether that member is still running or already settled `bailed`,
1261
1265
  one. Only the newest member counts, so a replacement (`impl-<N>-b`) is what
1262
1266
  clears a mismatch — and is then owed its own check. A mismatch on a ticket
1263
1267
  whose issue is already CLOSED holds nothing: the tick probes that issue and
1264
- drops it, since there is nothing left to replace. The tick never reads a
1265
- transcript: clear an unchecked hold by running the check on that member. A
1268
+ drops it, since there is nothing left to replace. The tick reads no transcript
1269
+ itself: `tick --apply` runs the check, and an unchecked hold it leaves is
1270
+ cleared by running the check on that member by hand. A
1266
1271
  settled member's check works only when its transcript exists;
1267
1272
  without one, the verdict is `tier-unverifiable` for a member settled `killed`
1268
1273
  or `released`, and exit 2 naming the wrong session for any other. Clear a
@@ -1723,7 +1728,7 @@ ticket's line — never a hand edit.
1723
1728
  | Finisher report (failed / killed) | `ledger.mjs settle finisher-pr-<M>=failed` for a finisher that crashed or gave up, `=killed` for one that was killed; no label, and the tick prints no dispatch for it. The cockpit flags the PR `finisher:failed` / `finisher:killed` at severity 4 and you resolve it by hand (**Resolving a finisher that died**, below) |
1724
1729
  | Label seen (persistent Monitor) | nothing to record |
1725
1730
  | CI run terminal | `ci=<run-id>:<attempt>:<conclusion>` on the row; then the finisher gate (below) |
1726
- | Merge-bot pass report | `held-behind:#<lower>` rows; `ledger.mjs settle merge-bot-<n>=done`; `reap.sh --apply`; `reclaim-scratch.mjs --root <scratch> --apply`. (The bot may also have written `conflict-hold:#<pr>` onto a held PR's own row earlier in this same pass, before reporting — a token the bot wrote in this pass, never one `reap.sh` writes.) |
1731
+ | Merge-bot pass report | `held-behind:#<lower>` rows; `ledger.mjs settle merge-bot-<n>=done`; `tick --apply` runs the reap and the reclaim. (The bot may also have written `conflict-hold:#<pr>` onto a held PR's own row earlier in this same pass, before reporting — a token the bot wrote in this pass, never one `reap.sh` writes.) |
1727
1732
  | Drain | `ledger.mjs drain "<reason>"`; release the claims (below); `settle impl-<N>=released`; then the rest of **End of run** (below), `--stop` last |
1728
1733
  | Heartbeat | nothing to record |
1729
1734
 
@@ -1781,10 +1786,13 @@ owes beyond its row:
1781
1786
  - **Merge-bot pass reports done** → write each `held-behind-#<lower>` it reports
1782
1787
  into that ticket's row as `held-behind:#<lower>` — the verdict moves no label
1783
1788
  and leaves nothing in the repo, so the row is the only place the tick can read
1784
- it from — settle `merge-bot-<n>=done`, reap merged branches and worktrees with
1785
- `reap.sh --apply` (below) — always, even when the pass merged nothing — then
1786
- reclaim their scratch with `reclaim-scratch.mjs --root <scratch> --apply`
1787
- (below), and then run the tick. A label that landed at the last moment reads `DISPATCH
1789
+ it from — settle `merge-bot-<n>=done`, and then run the tick: `tick --apply`
1790
+ reaps merged branches and worktrees with `reap.sh --apply` (below), then
1791
+ reclaims their scratch with `reclaim-scratch.mjs --root <scratch> --apply`
1792
+ (below), once for every merge bot settled `done` — always, even when the pass
1793
+ merged nothing — and runs both again on the next tick after an `APPLY FAILED`
1794
+ line, and on every tick while this run has no controller record to remember
1795
+ the pass by. A label that landed at the last moment reads `DISPATCH
1788
1796
  merge-bot` again: dispatch the next bot straight away. A `rebase-fallback-#<pr>`
1789
1797
  on a conflict needs no record from you — the bot already appended
1790
1798
  `conflict-hold:#<pr>` to that PR's row, and the tick turns it into `DISPATCH
@@ -1883,7 +1891,7 @@ owes beyond its row:
1883
1891
  **Every wake ends in the tick.** One invocation, and you act on what it prints:
1884
1892
 
1885
1893
  ```
1886
- ~/.fleet/bin/fleet-run fleet-tick.mjs [--implementer-cap <n>] [--reviewer-cap <n>] [--max-reviews <n>]
1894
+ ~/.fleet/bin/fleet-run fleet-tick.mjs --apply [--implementer-cap <n>] [--reviewer-cap <n>] [--max-reviews <n>]
1887
1895
  ```
1888
1896
 
1889
1897
  It reads the run itself, and nobody states a count. Live implementers, live
@@ -1959,16 +1967,18 @@ depth** guard table applied in code. Act on each line as it reads:
1959
1967
  - `HOLD (…)` — the row is held and says why: draining, a tier mismatch, an
1960
1968
  unchecked tier, a saturated review side, `--max-reviews` in flight, or every
1961
1969
  queued merge candidate held behind a lower PR or on a conflict hold no
1962
- fix-applier has cleared. The two tier holds are yours to clear — an
1963
- unchecked tier by running `tier-check.mjs --batch` on the member it names
1964
- (its `tier-ok=`, or `tier-unverifiable=` for a member settled `killed` or
1965
- `released` with no transcript, clears it), a mismatch by dispatching the
1966
- replacement at the right tier (phase 2). Each
1967
- prints its clearing step in the row's detail: the `tier-check.mjs` command
1970
+ fix-applier has cleared. An unchecked tier is `tick --apply`'s to check, and
1971
+ the hold stays while the check writes no verdict (its `tier-ok=`, or
1972
+ `tier-unverifiable=` for a member settled `killed` or `released` with no
1973
+ transcript, clears it); a mismatch is yours to clear, by dispatching the
1974
+ replacement at the right tier (phase 2). Each prints its clearing step in
1975
+ the row's detail. For a mismatch that is the replacement's name —
1976
+ `impl-<N>-b` on a first retry, else one letter past the highest the ticket
1977
+ has used, or that no retry letter is left. For an unchecked tier, which
1978
+ `tick --apply` has already tried, it is the `tier-check.mjs` command to run
1979
+ by hand when the tick ran without `--apply` or the check wrote no verdict,
1968
1980
  with a batch entry per member it names (fill in `<file>`; `<session>` too
1969
- when no receipt of this run records one),
1970
- or the replacement's name — `impl-<N>-b` on a first retry, else one letter
1971
- past the highest the ticket has used, or that no retry letter is left.
1981
+ when no receipt of this run records one).
1972
1982
  - `AT CAP`, `IDLE OK` — nothing to do on that row.
1973
1983
  - `MAIN-CHECKOUT-DIRTY <paths> …`, printed above the rows, with every
1974
1984
  dispatching row (implementers, reviewers, merge-bot) reading
@@ -2031,7 +2041,7 @@ depth** guard table applied in code. Act on each line as it reads:
2031
2041
  `--liveness-merge-bot` and `--liveness-review` set the thresholds, in minutes.
2032
2042
 
2033
2043
  **Tier guards under Pull.** The per-dispatch `tier-check.mjs --batch` is
2034
- phase 2's own step: a mismatch it finds is the
2044
+ phase 2's own step, run by `tick --apply`: a mismatch it finds is the
2035
2045
  `HOLD (tier mismatch impl-<N>)` above, and a member it has no verdict on is
2036
2046
  the `HOLD (tier unchecked impl-<N>)`. Nothing else in the loop owns it.
2037
2047
 
@@ -2611,10 +2621,8 @@ is the same slot with a different job, and no review file to hand
2611
2621
  over. Name it `fix-pr-<M>`, or the next suffix (`-b`, `-c` …) when that name is
2612
2622
  already on record — `dispatch` refuses a reused one — and dispatch it with the
2613
2623
  `agent` that `ledger.mjs dispatch` printed, in the PR's existing worktree.
2614
- `dispatch` reads the unresolved hold off the tick's own per-PR state — every
2615
- row naming the PR, not one — and prints this member's own definition, whatever
2616
- the row's `tier=` — read it off that output, never recall it; a review
2617
- fix-applier's is `null`. Its prompt takes the prompt below's
2624
+ `dispatch` prints this member's definition, `fleet-fix-applier` whatever the
2625
+ row's `tier=` — read it off that output, never recall it. Its prompt takes the prompt below's
2618
2626
  worktree, branch and path discipline, but in place of its review paragraphs:
2619
2627
  bring `<branch>` current with `origin/main`, resolving every conflict by
2620
2628
  `run-merge-bot.md`'s **No-undo audit**, run `<testCmd>`, push, report the new
@@ -2623,8 +2631,8 @@ what lifts the tick's merge hold; a dispatched-but-live one does not, and
2623
2631
  `failed`/`killed` leave the PR fix-due for a replacement. It answers the
2624
2632
  hold and nothing else: survived or unverified findings of a returned review the row also carries
2625
2633
  stay unanswered through its settle, so the tick prints `DISPATCH fix-pr
2626
- PR#<M>` again once it lands, and that one — `dispatch` now prints `null` —
2627
- is a review fix-applier, dispatched as above. On a PR carrying
2634
+ PR#<M>` again once it lands, and that one is a review fix-applier, dispatched
2635
+ as above. On a PR carrying
2628
2636
  `ready-to-merge`, the push moves the head after the label, so the next merge
2629
2637
  bot refuses it `head-moved-after-label-#<M>`: a fresh finisher, per **Failure
2630
2638
  handling**.
@@ -2654,8 +2662,8 @@ bullets without the others and what strands is exactly the red-only PR.
2654
2662
 
2655
2663
  Name it `fix-pr-<M>`, or the next free suffix (`-b`, `-c` …) — `dispatch`
2656
2664
  refuses a reused name — record it with `ledger.mjs dispatch <pr#> <name>`
2657
- before the call, and dispatch it with the `agent` that command printed (`null`
2658
- while no conflict hold stands, as for a review fix-applier), in the PR's
2665
+ before the call, and dispatch it with the `agent` that command printed
2666
+ (`fleet-fix-applier`, as for a review fix-applier), in the PR's
2659
2667
  existing worktree. Its prompt takes the prompt below's worktree, branch and
2660
2668
  path discipline, but in place of its review paragraphs: read the failing job's
2661
2669
  log, fix the cause, run `<testCmd>`, push, report the new head, and **stop**.
@@ -3378,7 +3386,7 @@ each run a script the digest covers — `finisher-audit.mjs` (which runs
3378
3386
  `worktree-audit.sh`) and `ledger.mjs`, both under `plugin/scripts/` — and the
3379
3387
  label at duty 3 rests on what they returned. The rule is stated once, at the
3380
3388
  top of this file, which no finisher is dispatched to read, so it reaches one
3381
- through this block or not at all:
3389
+ through this block, which `agents/fleet-finisher.agent.md` carries in its body:
3382
3390
 
3383
3391
  > **Re-check the instrument set before you act on what duty 1 or duty 2 read,
3384
3392
  > and again before you add the label.**
@@ -3400,7 +3408,7 @@ through this block or not at all:
3400
3408
 
3401
3409
  **Give the finisher the test-run verdict rule verbatim too.** Duty 2 runs
3402
3410
  `<testCmd>` for the acceptance mutation, and the finisher's agent definition
3403
- says nothing about what a run that was cut short looks like. A `node --test`
3411
+ carries a copy of the rule below. A `node --test`
3404
3412
  stopped by an outside `timeout` still prints a summary, covering only the tests
3405
3413
  it reached, so reading that summary alone reads a partial suite as a whole one:
3406
3414
 
@@ -3470,8 +3478,8 @@ it reached, so reading that summary alone reads a partial suite as a whole one:
3470
3478
  > evidence; label nothing. A kill's evidence line goes in your report.
3471
3479
 
3472
3480
  **Give the finisher duty 3 verbatim as well, as one script.** The finisher's
3473
- agent definition carries no duty text, so this brief is the whole of duty 3 it
3474
- sees. Two finishers in one run read the release-label check as the whole duty
3481
+ agent definition carries this block in its body, so the brief does not repeat
3482
+ it. Two finishers in one run read the release-label check as the whole duty
3475
3483
  and reported `labelled` on a PR that never got the label, so the check and the
3476
3484
  label write are one command and the finisher never runs either alone:
3477
3485
 
@@ -3664,14 +3672,17 @@ deterministic, script-driven backstop run before every push specifically to
3664
3672
  catch a wrongly-resolved conflict, so the tier buys nothing that backstop
3665
3673
  doesn't already cover.
3666
3674
 
3667
- **Put the shell traps in the bot's brief, not in a follow-up message.** A bot
3668
- already looping cannot be corrected — the loop consumes the turns a correction
3669
- would land in. **Every entry in Shell traps, verbatim** — that section is where
3670
- they are stated once, and this is the seat that has to paste them: the bot
3671
- reads an exit code off `gh pr update-branch`, `merge-gate.mjs` and
3672
- `prove-merge.sh`, which is the `PIPESTATUS` and read-only-`status` pair, and its
3673
- grace poll captures `gh pr list` output and loops over it, which is the
3674
- assigned-variable trap. The brief always travels with the dispatch.
3675
+ **The shell traps live in the merge bot's agent body, not in its brief and not
3676
+ in a follow-up message.** A bot already looping cannot be corrected — the loop
3677
+ consumes the turns a correction would land in — so
3678
+ `agents/fleet-merge-bot.agent.md` carries **every entry in Shell traps**, copied
3679
+ from that section, and the bot has them before its first turn. The bot reads an
3680
+ exit code off `gh pr update-branch`, `merge-gate.mjs` and `prove-merge.sh`,
3681
+ which is the `PIPESTATUS` and read-only-`status` pair, and its grace poll
3682
+ captures `gh pr list` output and loops over it, which is the assigned-variable
3683
+ trap. Its brief names the bot and `<scratch>`, plus the one-line
3684
+ no-acknowledgement notice; do not paste the
3685
+ traps there. An edit to Shell traps lands in that body in the same change.
3675
3686
 
3676
3687
  **Its merge gate is one script, run twice.** Step 3 of `run-merge-bot.md` is
3677
3688
  `merge-gate.mjs --pr <n> --pre <sha> [--post <sha>]`: read-only, it runs the
@@ -3707,8 +3718,9 @@ worktree — and its installed dependencies — still on disk. Reap after **each
3707
3718
  not once at the end: a stale worktree still answers `git worktree list`, so the
3708
3719
  in-flight probe (`inflight.sh`, run by the Shortlist and by every Pull) reads an
3709
3720
  already-merged ticket as taken and the queue quietly shrinks. The trigger is the
3710
- bot's one exit report, and it reaps every time — a pass that merged nothing
3711
- included (phase 3, **Merge-bot pass reports done**). See references/reaping.md.
3721
+ bot's `merge-bot-<n>=done`, and `tick --apply` reaps once for every one — a pass
3722
+ that merged nothing included (phase 3, **Merge-bot pass reports done**). See
3723
+ references/reaping.md.
3712
3724
 
3713
3725
  `~/.fleet/bin/fleet-run reap.sh --apply` recomputes every precondition
3714
3726
  inside the same invocation as the delete — `for-each-ref` for `[gone]`, `git
@@ -3736,7 +3748,7 @@ See references/reaping.md.
3736
3748
 
3737
3749
  ### Reclaim scratch after each merge pass
3738
3750
 
3739
- Right after `reap.sh --apply`, every pass:
3751
+ `tick --apply` runs it right after `reap.sh --apply`, every pass:
3740
3752
  `~/.fleet/bin/fleet-run reclaim-scratch.mjs --root <scratch> --apply`,
3741
3753
  `<scratch>` the path `scratch-root.mjs` prints. Reap authorizes on git's
3742
3754
  evidence and never removes scratch; Reclaim authorizes on GitHub state and
@@ -4328,14 +4340,13 @@ live count from it, so nobody states one. Write neither by hand:
4328
4340
  merge-bot` names the next bot itself. It prints `{member, agent, ticket,
4329
4341
  line, created, total}`; `agent` is the definition the `task` call names — an
4330
4342
  implementer's comes off its row's `tier=` (phase 2's tier check states the
4331
- mapping), a finisher's and a merge bot's are their own definitions, a
4332
- review fix-applier's is `null`, and a conflict-hold fix-applier's is
4333
- `fleet-implementer-slow-high`: its own section says how it is dispatched. It
4343
+ mapping), a finisher's and a merge bot's are their own definitions, and a
4344
+ fix-applier's is `fleet-fix-applier` for every kind of work. It
4334
4345
  refuses a name this session already used — on the ledger or in its
4335
4346
  `## Retired` — and names the replacement (`-b`, `-c` …), a
4336
4347
  second live member on one ticket or PR, any implementer once the run is
4337
4348
  draining, an implementer whose row's `tier=` names no single definition
4338
- or one with no file under `agents/`, and a fix-applier on a ledger the tick
4349
+ or one with no file under `agents/`, and a finisher on a ledger the tick
4339
4350
  itself refuses.
4340
4351
  - **`ledger.mjs settle <member> <outcome>`** — rewrites the token to
4341
4352
  `<member>=<outcome>` in both places. Outcomes: `impl-N` = `PR#M | bailed |
@@ -3,135 +3,18 @@ arg worktree abs-path
3
3
  arg pin your dispatch pin
4
4
  arg pr M
5
5
  arg testCmd testCmd
6
+ arg scratch scratch
6
7
  path worktree
7
- literal args
8
- literal cmd
9
- literal test
8
+ path scratch
10
9
  ---
11
10
  ## kind: fresh, repair
12
- **Re-check the instrument set before you act on what duty 1 or duty 2 read,
13
- and again before you add the label.**
14
- `~/.fleet/bin/fleet-run instruments.sh --repo "$(dirname "$(env -u GIT_DIR -u GIT_WORK_TREE git rev-parse --git-common-dir)")"`.
15
- Exit 0 is the only code that lets you go on. Exit 1 (the set changed) and
16
- exit 2 (the check could not answer) both halt you: report what it printed,
17
- add no label, and do NOT re-read the script that gave you the reading.
18
- `--repo` is required and the spelling is the point — the run's baseline lives
19
- in the audited checkout's gitignored `.fleet/`, which the scratch worktree
20
- you take at duty 2 does not carry, so a bare invocation from there exits 2 on
21
- a missing baseline instead of comparing anything. The `env -u GIT_DIR -u
22
- GIT_WORK_TREE` wrapper guards against an ambient `GIT_DIR` in your own shell
23
- pointing this check at the wrong tree — the script's own internal unset
24
- cannot reach back and fix a path you already resolved wrong. The baseline
25
- itself names the tree to audit: a cross-workspace run pinned it once at
26
- phase 0, and your `--repo` only locates that baseline, never the audited
27
- tree — so an exit 2 naming a moved or unreadable audited tree is a halt
28
- like every other, not a spelling for you to correct.
11
+ Finish PR <M>. Your arguments are the whole of your per-dispatch task:
29
12
 
30
- **A test run is a verdict only if it ran to completion — and you read that
31
- off the test command's own exit status.**
32
- Redirect the run's output to a file in your scratch directory and read the
33
- command's own `$?` straight after it, then read the file. In an `eval` cell
34
- there is no `$?`: spawn `<testCmd>` with its output going to that file and
35
- read the exit code and the signal off the spawn result — `exitCode` and
36
- `signalCode` on Bun's `spawnSync`, `returncode` on Python's `subprocess.run`,
37
- which is negative for a signal. Never read the status of
38
- `<testCmd> | tail` or `<testCmd> | grep`: a pipeline's status is its
39
- last stage's, so the filter's 0 hides the run's own exit, and the array that
40
- holds the earlier stages' statuses is spelled differently per shell. A run is
41
- a verdict only when that exit status is 0 **and** its summary shows `tests`
42
- above 0 and `cancelled` 0. A summary line without that
43
- is not a verdict, whatever pass count it prints.
44
- **A run completed when the command itself returned on its own** — an exit
45
- code, no signal, and no `timeout`, deadline or kill of yours having fired.
46
- Judge that by how the run ended, never by its `cancelled` count: a failing
47
- `before` hook or a per-test `timeout` cancels tests inside a run that
48
- completed, and a SIGTERM'd `node --test` can exit 1 with `cancelled` above 0
49
- in a run that did not.
50
- **Any run that did not complete is a killed run** — 124 (`timeout`), 137
51
- (SIGKILL), 143 (SIGTERM), a signal in the spawn result, an `eval` cell's
52
- deadline — and read for green it is FAILED, the same bucket as
53
- `tests 0`, however many tests had passed before the kill. Halt with cause
54
- `other` and the exit code plus the summary line as evidence; label nothing.
55
- The same holds for the mutation gate: a killed run is not a mutant that
56
- reddened, and the files it cancelled are not failures — only a run that
57
- completed can kill a mutant. A completed run that exits 1 is not a killed run
58
- either, whatever its `cancelled` count, and not a killed mutant on its exit
59
- status alone: the acceptance mutation scores a kill only by the rules below.
60
- Exit 0 with `tests 0` stays FAILED.
61
- Do not wrap `<testCmd>` in an external `timeout`. Run a long suite in one
62
- `eval` cell with `timeout: 0`, as the review runner does, and wait for it.
63
-
64
- **Valid red:** a run that completed — the command returned on its own, with
65
- no signal and no timeout, deadline or kill having fired — in which the test
66
- the claim names is reported failing. An exit ≠ 0 with no failing test is not
67
- red, and a different test failing is not red for this claim. A red in the full
68
- suite only triggers a narrowed run; it is never evidence on its own.
69
-
70
- **Narrowed run:** the Test entrypoint with arguments appended,
71
- `<testCmd> <args>`. That appended arguments reach the Test entrypoint is all
72
- that is promised about them, so a narrowed run counts only if it reports
73
- `tests` > 0 and its output names the claimed test. If no narrowing can be
74
- proven, run the full `<testCmd>` and read the named test's own result from its
75
- output.
76
-
77
- **Kill:** the mutant produced a valid red in a narrowed run, and the same
78
- narrowed command, in the same tree with the mutant reverted, ran a valid green
79
- with the named test passing — completed, exit 0, `tests` > 0, `cancelled` 0. A
80
- completed exit ≠ 0 with the named test not failing is not a kill, and no kill
81
- stands without that green run on the unmutated tree. The result is
82
- inconclusive, never a kill, when the red does not reproduce in the narrowed
83
- run, when the unmutated tree is red too, or when no usable run exists.
84
-
85
- **Evidence line:** every kill and every valid red you claim carries one line
86
- in the claim's own free-text field:
87
- `red: <cmd> → exit N, fail K incl <test>; baseline: <cmd> → exit 0, <test> pass`.
88
- A failing-test finding filed off the review's shared run carries the `red:`
89
- half alone.
90
-
91
- An inconclusive acceptance mutation is neither a kill nor a pass: halt with
92
- cause `other`, with both runs — the mutant's and the unmutated tree's — as
93
- evidence; label nothing. A kill's evidence line goes in your report.
94
-
95
- **Duty 3 is one script, and its exit code is your verdict.**
96
- `~/.fleet/bin/fleet-run finisher-label.mjs --pr <M> --pin <your dispatch pin>`
97
- (the full SHA). It confirms exactly one of `patch`/`minor`/`major` is on the
98
- PR, records the head you audited, adds `ready-to-merge`, and reads the labels
99
- back. Exit 0 is the only code that means the label is on. Exit 3 means the PR
100
- carries zero or more than one release label: you are halted before the label,
101
- and the receipt names which it found. Exit 4 means the read-back does not carry
102
- the label, written or not. Exit 2 means a `gh` call or the invocation
103
- itself failed: report the stderr it printed. Every non-zero exit halts you
104
- with cause `other`, with the receipt as evidence, and you do not run any of
105
- its steps by hand to get past it. A repo whose label list defines none of the
106
- three does not gate on one, and the script says so in its receipt. Put the
107
- receipt, the JSON line it printed, in your report as printed: it is what tells
108
- the controller the label is on.
109
-
110
- **Duty 1 is one script, and its exit code is your verdict.**
111
- `~/.fleet/bin/fleet-run finisher-audit.mjs --worktree <abs-path> --pin <your dispatch pin>`
112
- (the path you were dispatched with, and the full SHA). It finds your
113
- worktree's row, reads whether the tree is dirty, compares the worktree's
114
- `HEAD` to your pin, and when the head differs derives the cause from the
115
- reflog. Exit 0, with `cause` null, is the only code that means the worktree is
116
- clean at your pin. Exit 1 means `cause` is non-null: you are halted, and
117
- `cause` is the word you name — `live-editor`, `rebase`, `past-pin`,
118
- `unreadable`, `missing`, `absent` or `other`, and `other` is a cause too, not
119
- a gap. Exit 2 means the script could not look: you are halted with cause
120
- `other`, with the line it printed on stderr as the evidence.
121
-
122
- The pin is the SHA you were dispatched against, never `PR headRefOid`: a
123
- member that kept working and pushed after the pin matches the branch tip on a
124
- clean tree, so a headRefOid comparison reports "settled" over commits no
125
- reviewer read — the exact divergence this halt exists to catch. You do not
126
- run any of the script's steps by hand to get past a halt or to second-guess
127
- it. Put the verdict, the JSON line it printed, in your report as printed: its
128
- `evidence` is what the controller resolves the halt from.
129
-
130
- Every cause halts, always — named or not, you never verify the dirt is
131
- harmless and label over it, a rebase is not a fast-forward you get to accept,
132
- a commit past the pin is not one either, and a cause you could not name is
133
- the least settled of the lot. Naming the cause makes the halt cheap to
134
- resolve, never a reason to skip it.
13
+ pr: <M>
14
+ worktree: <abs-path>
15
+ pin: <your dispatch pin>
16
+ testCmd: <testCmd>
17
+ scratch: <scratch>
135
18
  ## kind: repair
136
19
 
137
20
  An earlier finisher on this PR reported `labelled`, but its read-back did not carry `ready-to-merge`: you are the repair finisher. Duty 3's script decides whether the label is on, as above.