@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.
- package/agents/fleet-finisher.agent.md +223 -1
- package/agents/fleet-fix-applier.agent.md +331 -0
- package/agents/fleet-merge-bot.agent.md +80 -1
- package/package.json +1 -1
- package/scripts/dispatch-prompt.mjs +2 -3
- package/scripts/fleet-state.mjs +27 -2
- package/scripts/fleet-tick.mjs +225 -39
- package/scripts/ledger-grammar.mjs +8 -14
- package/scripts/ledger.mjs +10 -9
- package/scripts/member-write-guard.mjs +5 -4
- package/skills/run-team/SKILL.md +65 -54
- package/skills/run-team/briefs/finisher.md +8 -125
- package/skills/run-team/briefs/fix-applier.md +1 -334
- package/skills/run-team/briefs/merge-bot.md +2 -73
package/skills/run-team/SKILL.md
CHANGED
|
@@ -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
|
|
168
|
-
every trap here is a zsh-vs-bash difference that ships as a
|
|
169
|
-
correct in the shell you tested in, silently wrong in the
|
|
170
|
-
3's monitor paragraph
|
|
171
|
-
|
|
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
|
|
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,
|
|
1227
|
-
prose reminder.**
|
|
1228
|
-
|
|
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
|
|
1265
|
-
|
|
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`; `
|
|
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`,
|
|
1785
|
-
`reap.sh --apply` (below)
|
|
1786
|
-
|
|
1787
|
-
(below),
|
|
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.
|
|
1963
|
-
|
|
1964
|
-
|
|
1965
|
-
|
|
1966
|
-
replacement at the right tier (phase 2). Each
|
|
1967
|
-
|
|
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
|
|
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`
|
|
2615
|
-
row
|
|
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
|
|
2627
|
-
|
|
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
|
|
2658
|
-
|
|
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
|
|
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
|
-
|
|
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
|
|
3474
|
-
|
|
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
|
-
**
|
|
3668
|
-
already looping cannot be corrected — the loop
|
|
3669
|
-
|
|
3670
|
-
|
|
3671
|
-
|
|
3672
|
-
|
|
3673
|
-
|
|
3674
|
-
|
|
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
|
|
3711
|
-
included (phase 3, **Merge-bot pass reports done**). See
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
8
|
-
literal cmd
|
|
9
|
-
literal test
|
|
8
|
+
path scratch
|
|
10
9
|
---
|
|
11
10
|
## kind: fresh, repair
|
|
12
|
-
|
|
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
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
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.
|