@feigi/fleet-ctl 3.61.0 → 3.61.1

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.
@@ -287,6 +287,10 @@ working; one had its worktree audited mid-mutation, another handed over a SHA
287
287
  that was two commits stale, and a finisher dispatched on either would have
288
288
  halted on a diverged head.
289
289
 
290
+ **The CI wait is the controller's, never yours.** Once your work is pushed,
291
+ write your report and exit; never poll a CI run. `review-and-fix.md` step 4
292
+ states who owns the wait.
293
+
290
294
  **The dispositions record**, the one your brief names the path of:
291
295
 
292
296
  It is
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@feigi/fleet-ctl",
3
- "version": "3.61.0",
3
+ "version": "3.61.1",
4
4
  "description": "Agent fleet: run-team controller, merge bot, PR reviewer, and the ticket pipeline they share",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
@@ -5,9 +5,11 @@
5
5
  // [--member <name>] [--json]
6
6
  //
7
7
  // Roles: implementer, fix-applier, finisher, merge-bot, review-runner,
8
- // recipe-deriver. A role with kinds (fix-applier: review, conflict,
9
- // dispositions-retry, red-check; finisher: fresh, repair) requires --kind; a role
10
- // without them refuses it as an unknown flag.
8
+ // recipe-deriver, relabel (the comment a Pull posts on a ticket it returns,
9
+ // not a member's brief). A role with kinds (fix-applier: review, conflict,
10
+ // dispositions-retry, red-check; finisher: fresh, repair; relabel:
11
+ // needs-triage, fork, hands) requires --kind; a role without them refuses it
12
+ // as an unknown flag.
11
13
  //
12
14
  // OUTPUT. The brief on stdout and nothing else. With --json the payload
13
15
  // {role, kind, args, sha256} replaces it, `sha256` being the hash of the
@@ -73,7 +75,7 @@ import { runnerScratchRefusal } from "./review-core.mjs";
73
75
  const NAME = "dispatch-prompt";
74
76
  const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url));
75
77
  const BRIEFS_DIR = join(SCRIPT_DIR, "..", "skills", "run-team", "briefs");
76
- const ROLES = ["implementer", "fix-applier", "finisher", "merge-bot", "review-runner", "recipe-deriver"];
78
+ const ROLES = ["implementer", "fix-applier", "finisher", "merge-bot", "review-runner", "recipe-deriver", "relabel"];
77
79
  const RESERVED = ["member", "json", "kind"];
78
80
  const USAGE = `usage: ${NAME}.mjs render <role> [--kind <kind>] [--<arg> <value>…] [--member <name>] [--json] — roles: ${ROLES.join(", ")}`;
79
81
  const PLACEHOLDER = /<([A-Za-z][^<>\n]*)>/g;
@@ -27,15 +27,17 @@ correctly and ends its turn has reported nothing: the controller learns the
27
27
  outcome only by re-reading artifacts and pinging, and a finding held only in
28
28
  that member's context is lost. Members did exactly this in one run —
29
29
  finishers, a reviewer and merge bots alike, the work done and only the
30
- delivery missing. Say it in every dispatch prompt. See
30
+ delivery missing. Every brief's report paragraph says it. See
31
31
  references/member-lifecycle.md.
32
32
 
33
- **Say in every dispatch prompt that you do not acknowledge reports.** A
34
- member cannot see whether its report arrived, so silence from you is
35
- indistinguishable from loss and it re-sends — three members did in one run,
36
- each burning a turn, and in all three the original had in fact arrived. Give
37
- them the line verbatim: *"The controller does not acknowledge reports. Send
38
- once and exit; never re-send unless the controller asks by name."*
33
+ **The implementer, fix-applier, finisher, merge-bot and review-runner briefs
34
+ each tell the member you do not acknowledge reports; you never write that line
35
+ yourself.** A member cannot see whether its report arrived, so silence
36
+ from you is indistinguishable from loss and it re-sends — three members did in
37
+ one run, each burning a turn, and in all three the original had in fact arrived.
38
+ Each of those templates under `briefs/` carries the line: *"The controller does
39
+ not acknowledge reports. Send once and exit; never re-send unless the controller
40
+ asks by name."*
39
41
 
40
42
  **But a missing report is NOT evidence the member failed to send one — the
41
43
  inbound direction drops AND delays messages.** Both were measured in one run,
@@ -114,9 +116,9 @@ changed.
114
116
  **A label gate and a CI verdict are also taken by dispatched members, not
115
117
  only by you** — the finisher labels, and the merge bot merges on its own
116
118
  reading — and neither is dispatched to read this file, so neither can be
117
- reached by stating the rule here. Each carries its own copy: the finisher's
118
- in the verbatim block at its duties below, the merge bot's inside
119
- `merge-gate.mjs`, step 3 of `run-merge-bot.md`.
119
+ reached by stating the rule here. Each carries its own copy: the finisher's
120
+ in the instrument re-check block of `agents/fleet-finisher.agent.md`, the merge bot's inside
121
+ `merge-gate.mjs`, step 3 of `run-merge-bot.md`.
120
122
  - **Re-pin only after a change you made deliberately.** The mid-run tooling fix
121
123
  below is the one legitimate writer. Re-pinning to clear a refusal you cannot
122
124
  explain discards the check.
@@ -141,9 +143,9 @@ was lost is that you pinged it by name with a concrete next action.
141
143
  `finisher-pr-1184` reached for the same pattern minutes later — a proactive
142
144
  warning is the only reason it did not repeat the stall. Its
143
145
  `pgrep -f 'finish-finisher-pr-1184'` could never have matched any process, so
144
- the poll it was waiting on was structurally incapable of firing. Say it in
145
- every dispatch prompt — this file is yours, not theirs, so a member learns
146
- it only if you write it into the prompt.
146
+ the poll it was waiting on was structurally incapable of firing. This file is
147
+ yours, not theirs: the implementer, fix-applier and finisher briefs carry the
148
+ rule, as the line `A member runs its test suite in the foreground and blocks on it.`
147
149
 
148
150
  **The scratch root is computed, never invented and never recorded.** No harness
149
151
  supplies a scratch directory to a member, so a member left to name its own
@@ -156,7 +158,7 @@ re-invoked controller runs it, so nothing writes it down. It exits non-zero,
156
158
  with its reason, when the root would sit inside a git work tree that does not
157
159
  ignore it; that is an environment to fix, not a cue to pick another root.
158
160
  `<scratch>` in this file is that path, resolved before you send anything: every
159
- prompt below that carries one carries the absolute path you wrote — an
161
+ brief that carries one carries the absolute path you passed it — an
160
162
  implementer's `<scratch>/impl-<N>/`, the recipe deriver's
161
163
  `<scratch>/derive-recipe/`, a fix-applier's, a finisher's and a merge bot's
162
164
  `<scratch>/pr<N>/…`, and a review runner's `scratch` argument, which is the
@@ -241,7 +243,7 @@ trap, opposite failure direction — so name the variable anything else
241
243
 
242
244
  **The other deliberate copy is `env $cfg sh ./probe.sh`.** The first trap's
243
245
  mechanism bites argv as well as loops, and that instance stays written out in the
244
- fix-applier prompt and every refuter brief under **Reviewers** rather than here,
246
+ fix-applier body and every refuter brief rather than here,
245
247
  because the seats that inject faults are the ones that need it and a bot reads
246
248
  gates without ever injecting one. Do not fold it into this block, and do not
247
249
  restate this block there.
@@ -651,25 +653,15 @@ fleet has already judged unimplementable straight to the next member.
651
653
  three causes, two labels: `ready-for-human` for hands or a fork;
652
654
  `needs-triage` for a brief that names no *what*.
653
655
  `gh issue edit <N> --remove-label ready-for-agent --add-label <label>` (no
654
- `in-progress` to drop — it was never claimed), preceded by exactly one comment:
655
-
656
- - `needs-triage`:
657
-
658
- > *Relabelled by the fleet controller.* Pulled for implementation and
659
- > returned: the brief does not decide what to build. Missing decision: <one
660
- > line>. Returning to /triage; `ready-for-agent` restored once decided.
661
-
662
- - `ready-for-human` (fork):
663
-
664
- > *Relabelled by the fleet controller.* Pulled for implementation and
665
- > returned: the brief leaves a decision open. Open fork: <options, verbatim
666
- > from the brief>.
667
-
668
- - `ready-for-human` (hands):
669
-
670
- > *Relabelled by the fleet controller.* Pulled for implementation and
671
- > returned: needs human hands — <external access | manual testing |
672
- > judgment during the work>: <one line>.
656
+ `in-progress` to drop — it was never claimed), preceded by exactly one comment,
657
+ the one `~/.fleet/bin/fleet-run dispatch-prompt.mjs render relabel --kind <kind> …`
658
+ prints. `--kind needs-triage` takes `--line`, the one-line missing decision;
659
+ `--kind fork` takes `--options`, the options verbatim from the brief, and is
660
+ the `ready-for-human` comment for a fork; `--kind hands` takes `--hands`,
661
+ one of external access, manual testing or judgment during the work, and
662
+ `--line`, and is the `ready-for-human` comment for hands. The three comments
663
+ live in `briefs/relabel.md`; `pull.mjs` posts its own one-line copy of the same
664
+ words when a Pull answer relabels, so a change to either is a change to both.
673
665
 
674
666
  Neither label invokes anything: `/triage` is maintainer-run, and both labels
675
667
  only stop the ticket costing a read per scan. These comments are the only
@@ -873,10 +865,10 @@ placeholders — the ticket number, the worktree abs path and branch
873
865
  `<scratch>` as `scratch-root.mjs` printed it — and the
874
866
  distilled brief (`<distilled brief>`): the title plus the `## Agent Brief`
875
867
  comment or the issue body, whichever carries the brief, and its `Out of
876
- scope`, pasted verbatim from the Pull's own read. Beyond those it carries only
877
- the lines **Rules that fail silently** above say every dispatch prompt
878
- carries — the report is a message, reports are not acknowledged, the suite
879
- runs in the foreground — and a `staleness.mjs` **could not check** verdict with its
868
+ scope`, pasted verbatim from the Pull's own read. Beyond those
869
+ `briefs/implementer.md` carries only its report paragraph, the
870
+ no-acknowledgement line, the foreground-suite line
871
+ — and a `staleness.mjs` **could not check** verdict with its
880
872
  reason when the Pull got one, so the member's own re-derive step knows the
881
873
  controller's probe could not look.
882
874
 
@@ -2224,10 +2216,10 @@ named member per PR, `fix-pr-<pr#>` (the next suffix when that name is already
2224
2216
  on record), never the PR's
2225
2217
  implementer, its brief rendered with `dispatch-prompt.mjs render fix-applier
2226
2218
  --kind review --member fix-pr-<pr#> …` and then recorded with `ledger.mjs
2227
- dispatch <pr#> fix-pr-<pr#>` before the call. Its prompt carries the PR number, the worktree abs path, the PR's branch,
2219
+ dispatch <pr#> fix-pr-<pr#>` before the call. Its brief carries the PR number, the worktree abs path, the PR's branch,
2228
2220
  the same `testCmd` you passed the review, and the **path** `<scratch>/pr<pr>/<run>/review.json`,
2229
2221
  `<run>` off the PR's latest `reviewed=` — never the findings. Every `<scratch>`
2230
- in that prompt is the absolute path `scratch-root.mjs` printed, the
2222
+ in that brief is the absolute path `scratch-root.mjs` printed, the
2231
2223
  `dispositions-<its name>.json` record's included. The fix-applier owns every per-PR ruling you once made
2232
2224
  before dispatch: both mutual-exclusion scans, the suggested-fix re-derivation,
2233
2225
  `refuted=false` ≠ apply, per-site measurement for a sibling-site extension, and
@@ -2246,8 +2238,8 @@ already on record — `dispatch` refuses a reused one — render its brief with
2246
2238
  and dispatch it with the
2247
2239
  `agent` that `ledger.mjs dispatch` printed, in the PR's existing worktree.
2248
2240
  `dispatch` prints this member's definition, `fleet-fix-applier` whatever the
2249
- row's `tier=` — read it off that output, never recall it. Its prompt takes the prompt below's
2250
- worktree, branch and path discipline, but in place of its review paragraphs:
2241
+ row's `tier=` — read it off that output, never recall it. Its `conflict` brief carries the
2242
+ same worktree and branch identity paragraph, but in place of the review paragraphs:
2251
2243
  bring `<branch>` current with `origin/main`, resolving every conflict by
2252
2244
  `run-merge-bot.md`'s **No-undo audit**, run `<testCmd>`, push, report the new
2253
2245
  head. Settle it `applied:<head>` — `no-op` if no conflict was left — which is
@@ -2264,7 +2256,7 @@ handling**.
2264
2256
  **Then dispatch a red-check fixer** — on a `check`-job `failure` bound to the
2265
2257
  PR's current head that is not **solely** staleness: a `rebase-check` red, or
2266
2258
  heavy jobs `skipped`, that comes only off the behind-count gets no fixer (the
2267
- five-condition note in the fix-applier block below states how to establish
2259
+ five-condition note in the fix-applier body states how to establish
2268
2260
  that). The tick prints no `DISPATCH` for it, so you reconcile it yourself, and
2269
2261
  it always goes after the review, never before. Take the common case, the
2270
2262
  implementer's own first CI firing turning red before any review exists: the
@@ -2289,8 +2281,8 @@ refuses a reused name — render its brief with `dispatch-prompt.mjs render
2289
2281
  fix-applier --kind red-check --member <name> …`, record it with `ledger.mjs dispatch <pr#> <name>`
2290
2282
  before the call, and dispatch it with the `agent` that command printed
2291
2283
  (`fleet-fix-applier`, as for a review fix-applier), in the PR's
2292
- existing worktree. Its prompt takes the prompt below's worktree, branch and
2293
- path discipline, but in place of its review paragraphs: read the failing job's
2284
+ existing worktree. Its `red-check` brief carries the same worktree and branch
2285
+ identity paragraph, but in place of the review paragraphs: read the failing job's
2294
2286
  log, fix the cause, run `<testCmd>`, push, report the new head, and **stop**.
2295
2287
  It is told outright not to watch, poll or wait for CI: your persistent Monitor
2296
2288
  owns the next run on the pushed head, and the finisher gate — review returned
@@ -2306,9 +2298,9 @@ reach green" covers.
2306
2298
  `dispositions-mismatch=<member>:<run>` for its latest review's run, and no later
2307
2299
  fix-applier has landed — is one automatic retry, a review fix-applier named the
2308
2300
  next suffix (`fix-pr-<M>-b`) and dispatched like the first, its brief rendered with `--kind dispositions-retry`. Its prompt is the
2309
- first one's, with three paths and a list copied in: the review file
2310
- `<scratch>/pr<M>/<run>/review.json`, the mismatched member's record `<scratch>/dispositions-<member>.json`
2311
- it starts from, its own record `<scratch>/dispositions-<its own name>.json` it writes, and the check's violation list **verbatim** — the lines
2301
+ first one's with the retry paragraph added: `--mismatched-record`, the mismatched member's record
2302
+ `<scratch>/dispositions-<member>.json` it starts from, and `--violations`, the check's
2303
+ violation list as printed — the lines
2312
2304
  `dispositions-check.mjs` printed, each naming a bucket, an index and a rule;
2313
2305
  re-run the check for the mismatched member to reprint them. It writes its own
2314
2306
  record, and when it reports you run the check for it exactly as for the first
@@ -2343,7 +2335,7 @@ arrives as ONE argument: a variable literally named `SETB` takes the value
2343
2335
  while `fix-pr-1153` nearly retired a real review finding as non-reproducing after
2344
2336
  the same shape handed both trees a single argv word and drew `exit 2` from each,
2345
2337
  which is the signature of a correct refutation with nothing anomalous to notice.
2346
- The fix-applier prompt and every refuter brief carry the rule and the safe
2338
+ The fix-applier body and every refuter brief carry the rule and the safe
2347
2339
  invocation form; the merge bot's brief is the wrong seat, because a bot
2348
2340
  reads gates and never injects a fault.
2349
2341
 
@@ -2382,9 +2374,9 @@ review's test-run block captures into its log and the test-run agent reports as
2382
2374
  dimension unrun, for the reason "no suite slot within <n> s — the host is at its
2383
2375
  suite bound; not a test failure", with no retry inside the run: re-review it
2384
2376
  under the next runner letter (`review-pr-<pr#>-b` after a first runner), as for
2385
- a runner that reported `failed`. Tell every implementer, fix-applier and
2386
- finisher, in its brief, in one line: exit 75 is not a test result; run the
2387
- command again.
2377
+ a runner that reported `failed`. The implementer, fix-applier and finisher briefs
2378
+ carry the one-line rule: *Exit 75 from the suite is not a test result; run the
2379
+ command again.*
2388
2380
 
2389
2381
  A slot holder killed without releasing is taken over by the next waiter under
2390
2382
  the same `.reap` discipline as the ledger's lock; the wedges that discipline
@@ -2403,384 +2395,40 @@ substituting `<testCmd>` with nothing leaves it no gate at all.
2403
2395
 
2404
2396
  **Where `<branch>` comes from:** the PR's head branch —
2405
2397
  `gh pr view <N> --json headRefName -q .headRefName`, or the same branch you cut
2406
- the worktree from. Substitute it exactly as you substitute `<testCmd>`, because
2398
+ the worktree from. Pass it as `--branch`, because
2407
2399
  the member cannot read it off git: phase 1 creates an already-open PR's worktree
2408
2400
  with `--detach`, and there `git branch --show-current` prints nothing and exits 0
2409
2401
  (measured 2026-09-18, git 2.50.1), so `git push origin
2410
2402
  "HEAD:$(git branch --show-current)"` exits 128 on `fatal: invalid refspec
2411
- 'HEAD:'`. Left unsubstituted, the push that prompt ends on has no destination at
2412
- all.
2413
-
2414
- > You are ALREADY in worktree `<abs-path>`, whose PR branch is `<branch>` — the
2415
- > push destination below, given to you because a detached worktree cannot supply
2416
- > it. Do NOT create another worktree. The review is done and its result is the
2417
- > file below — do not re-review, do not dispatch specialists.
2418
- >
2419
- > **`edit` and `read` resolve a bare relative path against the SESSION ROOT —
2420
- > the controller's own main checkout — not against that worktree and not
2421
- > against your `bash` cwd, which they share no `cwd` parameter with. Give them
2422
- > the absolute worktree path on every call, mutation-probe copies included.**
2423
- > The main checkout is the parent of `git rev-parse --path-format=absolute
2424
- > --git-common-dir`. A `member-write-guard` refusal means the path hit the
2425
- > main checkout — for `bash`, a missing or main-checkout `cwd` — so re-issue
2426
- > it absolute, under your worktree.
2427
- >
2428
- > Read `$(~/.fleet/bin/fleet-run --root)/commands/review-and-fix.md` and run **steps 2, 3
2429
- > and 5 only**: split apply-now/defer, commit, push, file every deferral as its
2430
- > own issue with the label the finding's state calls for. Skip step 1 — the
2431
- > review already ran — and steps 4 and 6: the controller owns the CI wait and
2432
- > dispatches the finisher.
2433
- >
2434
- > **The review's result is `<scratch>/pr<pr>/<run>/review.json`** — the digest first
2435
- > (`jq '{pr, head, resume, testEnvironment, dimensionsRun, dimensionsUnrun, cwdAudit, counts}'`),
2436
- > then every finding (`jq '.survived'`, `jq '.unverified'`, `jq '.refuted'`).
2437
- > Read it through `review-and-fix.md`'s **The review result file**, which holds
2438
- > the rest of the recipes and every ruling on the findings: both
2439
- > mutual-exclusion scans, the suggested-fix re-derivation, `refuted=false` ≠
2440
- > apply, per-site measurement for a sibling-site extension, and `testEnvironment`
2441
- > and `cwdAudit` before any result of the shared test run. Every one of those
2442
- > rulings is yours — nobody upstream has made one, and the controller never
2443
- > reads the findings.
2444
- >
2445
- > **Every factual claim your diff restates needs a settling command run
2446
- > against the tree first** — the issue body is a lead, never a citation.
2447
- > **No positional references** (`the closing/second/last X`); name the thing
2448
- > semantically. **Never write a COUNT or a tally into prose; state the
2449
- > property instead** — unless it is a past-tense record of a measurement you
2450
- > performed, which stays as written; a present-tense claim about a live
2451
- > property must be restated as a property (`every other test in the file`),
2452
- > true at any count. **A settling grep over literal text takes `grep -F`, and
2453
- > its zero counts only after the same command finds a line known to match.**
2454
- >
2455
- > **Apply `survived` findings. A finding in `unverified` whose refuters ran and
2456
- > crashed or abstained always defers** — and which it is, you read off
2457
- > `refutersDispatched` and `refutersInconclusive`, never off severity and never
2458
- > off an empty vote list: `refutersDispatched` above zero with nothing decided
2459
- > means every refuter dispatched against it died or abstained, and
2460
- > `refutersInconclusive` counts the ones that abstained. Severity records how much a
2461
- > finding would matter if true, never whether anything looked. Say *in the
2462
- > deferral* which it was rather than that it went unchecked. Name a crash as
2463
- > crashed refuters — the review re-dispatched each crash once already and
2464
- > reports what died again, so a deferral that names the crash can still be
2465
- > re-verified. An abstention is not a crash: cite the inconclusive runs each
2466
- > abstaining refuter named in its `reason`, and never describe its refuters as
2467
- > crashed. **A `suggestion` is also in `unverified`,
2468
- > for a different reason — `refutersDispatched` of zero, the 0-refuter budget
2469
- > the review gives that band by policy — and the rule below, not this one,
2470
- > covers it.**
2471
- >
2472
- > **A `suggestion` is budgeted 0 refuters, so it is unchecked until you check
2473
- > it.** For each one, first decide scope: is it inside the scope of the PR's own
2474
- > ticket, or a different piece of work? **Out of scope → defer and file, never
2475
- > apply** — but the claim bar runs first: an out-of-scope suggestion whose
2476
- > claim is about shape (`claimKind: shape`) gets no refuter and goes to the
2477
- > closed suggestion-band record, and every other one gets the same refuter an
2478
- > in-scope one does, dispatched the same way, before it is filed.
2479
- > **In scope → dispatch ONE refuter** against the finding before
2480
- > touching the tree, biased to refuse, and hand it the prompt below with one
2481
- > substitution: resolve `<scratch>/pr<N>/<finding>/` in it to an absolute path
2482
- > under your own run root — `mktemp -d` once per round for
2483
- > `<scratch>/pr<N>/fix-XXXXXXXX/`, never bare `pr<N>`, since finding ids
2484
- > restart at 1 each round too — and write that absolute path into the
2485
- > refuter's prompt in its place; a refuter never derives its own path:
2486
- >
2487
- > > Try to REFUTE this finding. Default to refuted=true if uncertain. Verify by
2488
- > > RUNNING something — compile it, run the test, apply the mutation. Do not
2489
- > > reason your way to agreement. Observe that run synchronously — run the
2490
- > > command, wait for it, read its exit code. Never poll a log file for a
2491
- > > completion marker: prefer ONE blocking run to a poll loop, and treat its
2492
- > > return as permission to look, never as the answer. Reading a log the run has
2493
- > > already finished writing is fine; waiting on one is not. If you match a test
2494
- > > reporter's own output, accepting both `ℹ` and `#` is necessary but NOT
2495
- > > sufficient — strip SGR escapes first as well. node's prefix moves with the
2496
- > > node version and with whether stdout is a TTY, and color wraps the whole line
2497
- > > so it begins with ESC and no prefix anchor matches at all, which returns
2498
- > > empty at exit 0 — indistinguishable from a hung run and from a run of zero
2499
- > > tests. For an uncolored baseline use `env -u FORCE_COLOR`; `FORCE_COLOR=`
2500
- > > empty still enables color, so it is not a control. State your search scope
2501
- > > AND what your pattern would have missed. A grep over one ref does not
2502
- > > support a claim about history; a pattern built from the token a diff removed
2503
- > > does not support a claim that the category is empty.
2504
- > >
2505
- > > When your check scores a mutant killed or a test red, run only in your own
2506
- > > copy of the tree, and these rules decide it and nothing else:
2507
- > >
2508
- > > **Valid red:** a run that completed — the command returned on its own, with no
2509
- > > signal and no timeout, deadline or kill having fired — in which the test the
2510
- > > claim names is reported failing. An exit ≠ 0 with no failing test is not red,
2511
- > > and a different test failing is not red for this claim. A red in the full
2512
- > > suite only triggers a narrowed run; it is never evidence on its own.
2513
- > >
2514
- > > **Narrowed run:** the Test entrypoint with arguments appended, `<testCmd>
2515
- > > <args>`. That appended arguments reach the Test entrypoint is all that is
2516
- > > promised about them, so a narrowed run counts only if it reports `tests` > 0
2517
- > > and its output names the claimed test. If no narrowing can be proven, run the
2518
- > > full `<testCmd>` and read the named test's own result from its output.
2519
- > >
2520
- > > **Kill:** the mutant produced a valid red in a narrowed run, and the same
2521
- > > narrowed command, in the same tree with the mutant reverted, ran a valid green
2522
- > > with the named test passing — completed, exit 0, `tests` > 0, `cancelled` 0. A
2523
- > > completed exit ≠ 0 with the named test not failing is not a kill, and no kill
2524
- > > stands without that green run on the unmutated tree. The result is
2525
- > > inconclusive, never a kill, when the red does not reproduce in the narrowed
2526
- > > run, when the unmutated tree is red too, or when no usable run exists.
2527
- > >
2528
- > > **Evidence line:** every kill and every valid red you claim carries one line
2529
- > > in the claim's own free-text field: `red: <cmd> → exit N, fail K incl <test>;
2530
- > > baseline: <cmd> → exit 0, <test> pass`. A failing-test finding filed off the
2531
- > > review's shared run carries the `red:` half alone.
2532
- > >
2533
- > > This refuter has no abstain: a run that could not decide — neither a valid red
2534
- > > nor a valid green — is no kill and no refutation, so name the runs in
2535
- > > `reason`, each with its evidence line, and leave `refuted` true, so the
2536
- > > suggestion defers on the record instead of applying on a check that decided
2537
- > > nothing.
2538
- > >
2539
- > > A failure injection with
2540
- > > no positive control has produced NO result, never a negative one. Before you
2541
- > > read an injected fault — an env var, an argv word, a mutant — as having had
2542
- > > no effect, prove the injection reached the child: one run whose output
2543
- > > differs with it present versus absent, or the child echoing the injected
2544
- > > value back. Uncontrolled, the cell is unrun — say so in your verdict instead
2545
- > > of reporting a no-effect result. Build such an invocation as an array
2546
- > > expanded braced and quoted —
2547
- > > `cfg=(SETB=1 BADJ=1); env "${cfg[@]}" sh ./probe.sh` — or inline the
2548
- > > assignments literally — `env SETB=1 BADJ=1 sh ./probe.sh`; NEVER from an
2549
- > > unquoted scalar — `cfg="SETB=1 BADJ=1"; env $cfg sh ./probe.sh` — which under
2550
- > > zsh passes ONE argument, sets a variable literally named `SETB` to
2551
- > > `1 BADJ=1`, never sets `BADJ` at all, and still exits 0. `env $cfg[@]` is not
2552
- > > the portable spelling either: measured, bash word-splits it into `SETB=1`
2553
- > > and `BADJ=1[@]`, so the injection variable is set to a corrupted value,
2554
- > > while zsh behaves exactly as with the bare `$cfg` — `BADJ` never set,
2555
- > > exit 0. Everything you
2556
- > > write — mutants, fixtures,
2557
- > > scratch repos — goes under `<scratch>/pr<N>/<finding>/` and nowhere else;
2558
- > > the checkout and any worktree are never write targets, though
2559
- > > `git show`/`git archive` at a pinned ref read fine anywhere. Chain the
2560
- > > directory change into the command, `cd "$D" && git …`, never
2561
- > > `cd "$D"; git …`, so a failed `cd` cannot leave a `git` command running in
2562
- > > the checkout — and bracket a fixture's own git with
2563
- > > `git rev-parse --show-toplevel`: before `git init` it must NOT resolve to
2564
- > > the host repository, and `fatal: not a git repository` (exit 128) is the
2565
- > > usual pass, not a failure — an outer repository whose ignore rules cover
2566
- > > your scratch dir is a pass too; before any `git commit` it must resolve to
2567
- > > your scratch path, which catches a forgotten `git init` under any enclosing
2568
- > > repository — compare resolved forms (`realpath`), since `--show-toplevel`
2569
- > > can report a symlinked parent such as `/tmp` or a symlinked `$HOME` under
2570
- > > its resolved name.
2571
- >
2572
- > Survives → apply it, with one hold: if its refuter reports a blast radius
2573
- > touching lines another finding also changes, that is the mutual-exclusion
2574
- > scan's second input — rule the pair before either change reaches the tree;
2575
- > you hold every finding, so only you can see that the two cannot both land. Refuted → defer and file it, and
2576
- > say the refutation in the issue body. **Apply only what survives — no report is not a survival.** A
2577
- > refuter you never hear from leaves the finding exactly as unchecked as it
2578
- > arrived, so it defers like a refuted one.
2579
- >
2580
- > **Out of scope, the refuter decides only where the suggestion is filed — it
2581
- > defers either way, never applied.** Refuted → the closed suggestion-band
2582
- > record, never an open issue. Survived, or its refuter crashed or abstained →
2583
- > its own open issue labelled `needs-triage`, citing the verdict, or the run
2584
- > that crashed, in the body. There is no cap on these refuters: count the ones
2585
- > you dispatch against out-of-scope suggestions, since your report names that
2586
- > count.
2587
- >
2588
- > **A finding's `suggested_fix` is a hypothesis, not a patch — the review never
2589
- > ran it.** Only the claim is verified adversarially; the remedy text is unchecked.
2590
- > Three were wrong as written in one run: a stated end state that dropped a
2591
- > load-bearing option and measured RED, an assertion against a property the test
2592
- > helper does not expose (`TypeError`), and an enumeration that stopped short of
2593
- > two further stale clauses — one of them false in the *dangerous* direction. Run
2594
- > the remedy before you commit it, and re-derive an assertion from the post-fix
2595
- > tree rather than from the finding, since a sibling finding may edit the very
2596
- > text it asserts on.
2597
- >
2598
- > **Retrieve that report yourself; do not wait to be handed it — this covers the
2599
- > refuters YOU dispatch, and only those.** The review's own specialists do leave
2600
- > transcripts, but nothing gives you their address: the review had `agent()`
2601
- > return their findings into the script, so the result file holds their findings
2602
- > and names no transcript, and nothing on disk indexes a transcript by PR or
2603
- > dimension. Hunting their paths gets you nothing; read the file. A report from a refuter you spawned is
2604
- > different — it surfaces to the controller rather than to you, and waiting for a
2605
- > relay that never comes strands the finding. Its transcript is at the output file
2606
- > named in your spawn result, and its report is the last record:
2607
- >
2608
- > 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.
2609
- >
2610
- > If retrieval comes back empty, ask the controller by name. Only when neither
2611
- > works is the finding **unchecked** — defer and file it, and say so in the body. This is
2612
- > `review-and-fix.md`'s **Specialists** rule; it reaches you here because the
2613
- > steps that point at it are the ones you skip.
2614
- >
2615
- > The CI facts in that file apply to you — a `rebase-check` red, or heavy jobs
2616
- > `skipped`, **solely** off a non-zero behind-count, is staleness and not a
2617
- > failure. Never rebase to clear it. **`solely` is the load-bearing word:**
2618
- > `ci.yml`'s `rebase-check` exits 1 on five conditions and only one is
2619
- > staleness, so a non-zero behind-count does not by itself settle which fired.
2620
- > The job log names the condition — and because the staleness condition exits
2621
- > before the merge-commit condition is evaluated, the log is silent on that one
2622
- > by construction, so measure it separately with
2623
- > `git fetch origin && git rev-list --merges --count "origin/<base>..HEAD"` —
2624
- > keep the fetch, or a stale local `origin/<base>` widens the range over the
2625
- > base's own merge commits and reports a merge commit this branch never added.
2626
- > A non-zero count does not send you to a local rebase either: the merge bot's
2627
- > step-1 `gh pr update-branch --rebase` drops merge commits too
2628
- > (`run-merge-bot.md` step 1), so both conditions clear on that one server-side
2629
- > rebase. What it buys you is knowing the red was never solely staleness.
2630
- >
2631
- > **Run `<testCmd>` from the worktree before committing**, copied verbatim.
2632
- > `tests 0` is a FAILED run, not a pass. Red or zero-test → fix it, or move that
2633
- > finding to defer; never commit over it. **Never `--no-verify`** — a failing
2634
- > hook is a finding you report, not an obstacle you route around. Report the test
2635
- > result with your SHA. Nothing re-reviews this commit: the review ran against a
2636
- > snapshot cut before your edits existed, and a refuter checked the finding's
2637
- > claim, never your patch.
2638
- >
2639
- > **A test you ADD must kill its own mutant** — break what it pins, confirm it and
2640
- > only it goes red and that the red is a kill by the rules below, restore. **Then
2641
- > a change it should *not* catch, staying green** — else you proved it fails, not
2642
- > that it discriminates: a pin asserting whole-file text clears "it and only it
2643
- > goes red" and still reddens on any edit (measured). A green suite says nothing
2644
- > about a new test: one pin this run survived the exact mutation it was named for.
2645
- >
2646
- > **Valid red:** a run that completed — the command returned on its own, with
2647
- > no signal and no timeout, deadline or kill having fired — in which the test
2648
- > the claim names is reported failing. An exit ≠ 0 with no failing test is not
2649
- > red, and a different test failing is not red for this claim. A red in the full
2650
- > suite only triggers a narrowed run; it is never evidence on its own.
2651
- >
2652
- > **Narrowed run:** the Test entrypoint with arguments appended,
2653
- > `<testCmd> <args>`. That appended arguments reach the Test entrypoint is all
2654
- > that is promised about them, so a narrowed run counts only if it reports
2655
- > `tests` > 0 and its output names the claimed test. If no narrowing can be
2656
- > proven, run the full `<testCmd>` and read the named test's own result from its
2657
- > output.
2658
- >
2659
- > **Kill:** the mutant produced a valid red in a narrowed run, and the same
2660
- > narrowed command, in the same tree with the mutant reverted, ran a valid green
2661
- > with the named test passing — completed, exit 0, `tests` > 0, `cancelled` 0. A
2662
- > completed exit ≠ 0 with the named test not failing is not a kill, and no kill
2663
- > stands without that green run on the unmutated tree. The result is
2664
- > inconclusive, never a kill, when the red does not reproduce in the narrowed
2665
- > run, when the unmutated tree is red too, or when no usable run exists.
2666
- >
2667
- > **Evidence line:** every kill and every valid red you claim carries one line
2668
- > in the claim's own free-text field:
2669
- > `red: <cmd> → exit N, fail K incl <test>; baseline: <cmd> → exit 0, <test> pass`.
2670
- > A failing-test finding filed off the review's shared run carries the `red:`
2671
- > half alone.
2672
- >
2673
- > An inconclusive result proves nothing about the test: do not report the test
2674
- > as proven, and measure again in a clean state. Put each kill's evidence line in
2675
- > your report, beside the test result.
2676
- >
2677
- > **A mutation that never landed is not a green — it is a cell that did not
2678
- > run.** Same rule for any fault you inject to see what breaks: prove the
2679
- > injection reached the child before you read its result — one run whose output
2680
- > differs with the injection present versus absent, or the child echoing the
2681
- > injected value back. Without one, a probe that exits 0 reporting the mutant
2682
- > behaving exactly like its baseline is indistinguishable from a real no-effect
2683
- > result, and a reproduction that never happened reads as a refutation. Build
2684
- > such an invocation as an array expanded braced and quoted —
2685
- > `cfg=(SETB=1 BADJ=1); env "${cfg[@]}" sh ./probe.sh` — or inline the
2686
- > assignments literally — `env SETB=1 BADJ=1 sh ./probe.sh`; NEVER from an
2687
- > unquoted scalar — `cfg="SETB=1 BADJ=1"; env $cfg sh ./probe.sh` — which under
2688
- > zsh passes ONE argument, sets a variable literally named `SETB` to `1 BADJ=1`,
2689
- > never sets `BADJ` at all, and still exits 0. `env $cfg[@]` is not the portable
2690
- > spelling either: measured, bash word-splits it into `SETB=1` and
2691
- > `BADJ=1[@]`, so the injection variable is set to a corrupted value, while
2692
- > zsh behaves exactly as with the bare `$cfg` — `BADJ` never set, exit 0.
2693
- >
2694
- > **Commit BEFORE you mutate, and restore with `cp`, never a git discard.**
2695
- > `git checkout -- <file>` reverts the whole file, not your mutant — so it also
2696
- > eats uncommitted edits you made earlier, and the "clean baseline" you measure
2697
- > next is silently the reverted file. Two members hit this in one run; one lost
2698
- > prose edits and caught it only because a non-catch control failed. Copy the
2699
- > file aside and copy it back. Better still, mutate a copy under
2700
- > `<scratch>/pr<N>/mutate/` and leave the worktree untouched — that is what
2701
- > refuters are already required to do, and it has no blast radius at all.
2702
- >
2703
- > **Never `git stash` or `git stash pop` here either — a WIP commit is the
2704
- > substitute, not a second scratch mechanism: `git commit -m wip`, then
2705
- > restore or amend once you're back to real work.** The stash stack is
2706
- > repo-global too, not per-worktree or per-session — the same `refs/stash`
2707
- > every concurrent member and the main checkout share, not partitioned the
2708
- > way `<scratch>/pr<N>/mutate/` above is. A bare pop takes whichever entry is
2709
- > on top, from any worktree, silently — rc 0, no error — when the tree
2710
- > receiving it is clean on the affected paths, and refuses only when that
2711
- > tree is already dirty there. A bare `git stash` (push) does not reach into
2712
- > a sibling's tree, so that half is not the risk — the pop is. Nothing
2713
- > partitions the stack; this prohibition is the whole of the protection.
2714
- >
2715
- > **Report LAST, and only once nothing can still change.** A report you have
2716
- > sent **pins that SHA** for the controller, which dispatches a finisher against
2717
- > it. If a further instruction arrives after you have reported, reply saying the
2718
- > SHA is moving *before* you touch the tree again — do not silently do the work
2719
- > and re-report. Measured: three members in one run sent a final report and kept
2720
- > working; one had its worktree audited mid-mutation, another handed over a SHA
2721
- > that was two commits stale, and a finisher dispatched on either would have
2722
- > halted on a diverged head.
2723
- >
2724
- > **Before you report, write every ruling to `<scratch>/dispositions-<your name>.json`**,
2725
- > `<your name>` the `fix-pr-<pr>[-x]` you were dispatched as — the record the controller checks with
2726
- > `dispositions-check.mjs` before it dispatches any finisher. It is
2727
- > `{"head": "<the review file's head>", "run": "<the run root's name in the review path>", "entries": [ … ]}`
2728
- > — `run` the `<run>` of the review path above, which the check holds against the
2729
- > review the PR's latest `reviewed=` names: a record written against an earlier
2730
- > review, a same-head one included, is a mismatch. One entry per
2731
- > `survived` finding and per `unverified` finding, plus one per `refuted`
2732
- > finding you reverse. Each entry carries `bucket`
2733
- > (`survived|unverified|refuted`), `index` (its position in that bucket of the
2734
- > review file), `scope` (`in|out`), `claimKind` (`behavior|shape`) and
2735
- > `disposition` (`apply|defer`), and where they apply `reason`, `issue` (the
2736
- > number you filed it to or commented on), `verdictPath` (a suggestion's
2737
- > refuter verdict file, in scope and, above the claim bar, out of scope) and
2738
- > `remedyFiles` (the files its remedy names). An out-of-scope suggestion whose
2739
- > refuter crashed before any verdict reached you still names the path its
2740
- > verdict would have taken. A `refuted` entry carries `scope`, `claimKind` and `disposition`
2741
- > like every other entry, and a non-empty `reason` holding the evidence that
2742
- > reverses it; a missing or blank `reason` is a mismatch. A finding with no
2743
- > `line`, or on a line the PR's diff touched —
2744
- > `git diff` from its merge-base with `origin/main` to the review's head — is
2745
- > in scope whatever its `scope` says. An in-scope `survived` finding you defer
2746
- > carries `reason` `false-rationale`, `mutual-exclusion`, `remedy-worse` or
2747
- > `remedy-outside-diff`; the last needs `remedyFiles` to name a file the PR's
2748
- > diff does not touch, and for a `critical` or `important` finding it sends the
2749
- > PR to a human instead of passing. Any
2750
- > other reason, none, or a `survived` or `unverified` finding with no entry is
2751
- > a mismatch, and the PR gets no finisher. `disposition` has no `dismiss`: an
2752
- > in-scope `survived` finding verified correct, needing no change, is deferred
2753
- > with `reason` `false-rationale` and filed on the closed suggestion-band
2754
- > record.
2755
- >
2756
- > Then write your report to the file your brief names,
2757
- > `<scratch>/reports/<your name>.json`: `head` the pushed SHA, `applied` and
2758
- > `deferred` your apply/defer split by bucket and index, each deferral's issue
2759
- > number on its `deferred` entry, the deferral issues as `{issue, subject}`
2760
- > entries — `filed` for every issue step 5 created, and `unrecorded` for one
2761
- > whose `ledger.mjs filed` failed twice, which the controller's settle records —
2762
- > `dispositionsRecord` your record's path and `testRun` your test result. Then
2763
- > send the one line your brief gives, `<your name>: <outcome> <path>`, and exit.
2764
- > **Deferring everything is a normal
2765
- > outcome, not a stall:** nothing is then staged, `git commit` refuses an empty
2766
- > index, `git push origin HEAD:<branch>` prints `Everything up-to-date`, and your
2767
- > report's `outcome` is `no-op`, its `head` the unchanged SHA. Say it
2768
- > explicitly — silence there is indistinguishable from a member that died. Never
2769
- > manufacture a commit to make CI fire.
2770
-
2771
- **Put the standing CI facts in that prompt, not in per-event messages** —
2403
+ 'HEAD:'`. A brief rendered without it would leave the push no destination at
2404
+ all, which is why the renderer requires it.
2405
+
2406
+ **What a fix-applier receives.** Its standing text — the worktree and
2407
+ session-root discipline, the review result file and every ruling on it, the
2408
+ claim discipline, the refuter prompt, the kill rule, the stash prohibition, the
2409
+ dispositions record and the report rules — is the body of
2410
+ `agents/fleet-fix-applier.agent.md`, which the harness injects as its system
2411
+ prompt, so none of it is pasted. The brief carries what varies, and the
2412
+ renderer prints it: `~/.fleet/bin/fleet-run dispatch-prompt.mjs render
2413
+ fix-applier --kind <review|conflict|dispositions-retry|red-check> --member <name>
2414
+ --worktree <abs-path> --branch <branch> --testCmd <testCmd> --scratch <scratch>`,
2415
+ plus `--pr <pr#> --run <run>` for a review or a dispositions retry and
2416
+ `--mismatched-record <path> --violations <list>` for a retry. Then
2417
+ `ledger.mjs dispatch <pr#> <name>` records it before the call.
2418
+
2419
+ **The standing CI facts are in the fix-applier body, not in per-event messages** —
2772
2420
  otherwise you send "your red is staleness, do not rebase" once per member per
2773
- merge. `review-and-fix.md` states them; the prompt only has to say they apply.
2421
+ merge. `review-and-fix.md` states them; the body says they apply.
2774
2422
 
2775
2423
  **The fix-applier pushes and exits — it does not hold the CI wait.** You own the
2776
2424
  persistent Monitor; a turn-based member re-reading `gh pr checks` each idle cycle
2777
- rebuilds a 100k-token context for nothing the Monitor lacks. The prompt block
2778
- above carries the report-last rule; you do not have to restate it. When the
2425
+ rebuilds a 100k-token context for nothing the Monitor lacks. The body
2426
+ carries the report-last rule and the brief says to push, write the report and exit; you do not have to restate either. When the
2779
2427
  diff-validating `check` job is green **and no
2780
2428
  heavy job is in `failure`** (the heavy diff-validating suites — not the
2781
2429
  `rebase-check` currency gate; a `skipped` heavy job is behind-count staleness and
2782
2430
  fine — **solely** off that count, which is a condition to establish rather than
2783
- infer, see the five-condition note in the fix-applier block above) — or
2431
+ infer, see the five-condition note in the fix-applier body) — or
2784
2432
  `ci-state.mjs` reads `verdict: "no-ci"`, see below — **and once the PR's review
2785
2433
  has returned and its fix-applier, if one was dispatched, has sent its report,
2786
2434
  which the CI-completes edge above states in full** — dispatch a
@@ -2889,12 +2537,12 @@ a minute apart showed *different* mutants, so a member's report and any single
2889
2537
  finisher that cannot see the tree it labels cannot vouch for it, so none of
2890
2538
  the script's steps is run by hand to get past a halt. A finisher that
2891
2539
  verifies the dirt is harmless and labels anyway has substituted the rule's
2892
- purpose for the rule, and you find out at merge time. **Give it the cause
2893
- block below, verbatim** — it holds the script call and what each exit
2894
- means, and a bare SHA mismatch names no cause. **Give it `<testCmd>` too** —
2895
- the same string you passed the workflow and the fix-applier — because duty
2896
- 2's mutation gate runs it and nothing else hands the finisher one;
2897
- substituted with nothing it leaves that gate no command at all.
2540
+ purpose for the rule, and you find out at merge time. The halt-cause block in
2541
+ `agents/fleet-finisher.agent.md` holds the script call and what each exit
2542
+ means, and a bare SHA mismatch names no cause. **Pass `--testCmd` too** —
2543
+ the same string you passed the workflow and the fix-applier — because duty
2544
+ 2's mutation gate runs it and nothing else hands the finisher one; the renderer
2545
+ refuses a finisher brief rendered without it.
2898
2546
  2. **Confirm every deferral — and every claimed APPLY — has a home that outlives
2899
2547
  the merge.** The test is a durable home, not a tracker number: a tracker
2900
2548
  issue and a committed in-tree comment both qualify, and for a finding whose
@@ -3012,122 +2660,17 @@ a minute apart showed *different* mutants, so a member's report and any single
3012
2660
  printed, the JSON line, so a `rebase` halt's report carries the output of
3013
2661
  `git cherry <pin> HEAD origin/main` that its `evidence` holds.
3014
2662
 
3015
- **Give the finisher the instrument re-check verbatim too.** Duty 1 and duty 2
3016
- each run a script the digest covers — `finisher-audit.mjs` (which runs
3017
- `worktree-audit.sh`) and `ledger.mjs`, both under `plugin/scripts/` — and the
3018
- label at duty 3 rests on what they returned. The rule is stated once, at the
3019
- top of this file, which no finisher is dispatched to read, so it reaches one
3020
- through this block, which `agents/fleet-finisher.agent.md` carries in its body:
3021
-
3022
- > **Re-check the instrument set before you act on what duty 1 or duty 2 read,
3023
- > and again before you add the label.**
3024
- > `~/.fleet/bin/fleet-run instruments.sh --repo "$(dirname "$(env -u GIT_DIR -u GIT_WORK_TREE git rev-parse --git-common-dir)")"`.
3025
- > Exit 0 is the only code that lets you go on. Exit 1 (the set changed) and
3026
- > exit 2 (the check could not answer) both halt you: report what it printed,
3027
- > add no label, and do NOT re-read the script that gave you the reading.
3028
- > `--repo` is required and the spelling is the point — the run's baseline lives
3029
- > in the audited checkout's gitignored `.fleet/`, which the scratch worktree
3030
- > you take at duty 2 does not carry, so a bare invocation from there exits 2 on
3031
- > a missing baseline instead of comparing anything. The `env -u GIT_DIR -u
3032
- > GIT_WORK_TREE` wrapper guards against an ambient `GIT_DIR` in your own shell
3033
- > pointing this check at the wrong tree — the script's own internal unset
3034
- > cannot reach back and fix a path you already resolved wrong. The baseline
3035
- > itself names the tree to audit: a cross-workspace run pinned it once at
3036
- > phase 0, and your `--repo` only locates that baseline, never the audited
3037
- > tree — so an exit 2 naming a moved or unreadable audited tree is a halt
3038
- > like every other, not a spelling for you to correct.
3039
-
3040
- **Give the finisher the test-run verdict rule verbatim too.** Duty 2 runs
3041
- `<testCmd>` for the acceptance mutation, and the finisher's agent definition
3042
- carries a copy of the rule below. A `node --test`
3043
- stopped by an outside `timeout` still prints a summary, covering only the tests
3044
- it reached, so reading that summary alone reads a partial suite as a whole one:
3045
-
3046
- > **A test run is a verdict only if it ran to completion — and you read that
3047
- > off the test command's own exit status.**
3048
- > Redirect the run's output to a file in your scratch directory and read the
3049
- > command's own `$?` straight after it, then read the file. In an `eval` cell
3050
- > there is no `$?`: spawn `<testCmd>` with its output going to that file and
3051
- > read the exit code and the signal off the spawn result — `exitCode` and
3052
- > `signalCode` on Bun's `spawnSync`, `returncode` on Python's `subprocess.run`,
3053
- > which is negative for a signal. Never read the status of
3054
- > `<testCmd> | tail` or `<testCmd> | grep`: a pipeline's status is its
3055
- > last stage's, so the filter's 0 hides the run's own exit, and the array that
3056
- > holds the earlier stages' statuses is spelled differently per shell. A run is
3057
- > a verdict only when that exit status is 0 **and** its summary shows `tests`
3058
- > above 0 and `cancelled` 0. A summary line without that
3059
- > is not a verdict, whatever pass count it prints.
3060
- > **A run completed when the command itself returned on its own** — an exit
3061
- > code, no signal, and no `timeout`, deadline or kill of yours having fired.
3062
- > Judge that by how the run ended, never by its `cancelled` count: a failing
3063
- > `before` hook or a per-test `timeout` cancels tests inside a run that
3064
- > completed, and a SIGTERM'd `node --test` can exit 1 with `cancelled` above 0
3065
- > in a run that did not.
3066
- > **Any run that did not complete is a killed run** — 124 (`timeout`), 137
3067
- > (SIGKILL), 143 (SIGTERM), a signal in the spawn result, an `eval` cell's
3068
- > deadline — and read for green it is FAILED, the same bucket as
3069
- > `tests 0`, however many tests had passed before the kill. Halt with cause
3070
- > `other` and the exit code plus the summary line as evidence; label nothing.
3071
- > The same holds for the mutation gate: a killed run is not a mutant that
3072
- > reddened, and the files it cancelled are not failures — only a run that
3073
- > completed can kill a mutant. A completed run that exits 1 is not a killed run
3074
- > either, whatever its `cancelled` count, and not a killed mutant on its exit
3075
- > status alone: the acceptance mutation scores a kill only by the rules below.
3076
- > Exit 0 with `tests 0` stays FAILED.
3077
- > Do not wrap `<testCmd>` in an external `timeout`. Run a long suite in one
3078
- > `eval` cell with `timeout: 0`, as the review runner does, and wait for it.
3079
- >
3080
- > **Valid red:** a run that completed — the command returned on its own, with
3081
- > no signal and no timeout, deadline or kill having fired — in which the test
3082
- > the claim names is reported failing. An exit ≠ 0 with no failing test is not
3083
- > red, and a different test failing is not red for this claim. A red in the full
3084
- > suite only triggers a narrowed run; it is never evidence on its own.
3085
- >
3086
- > **Narrowed run:** the Test entrypoint with arguments appended,
3087
- > `<testCmd> <args>`. That appended arguments reach the Test entrypoint is all
3088
- > that is promised about them, so a narrowed run counts only if it reports
3089
- > `tests` > 0 and its output names the claimed test. If no narrowing can be
3090
- > proven, run the full `<testCmd>` and read the named test's own result from its
3091
- > output.
3092
- >
3093
- > **Kill:** the mutant produced a valid red in a narrowed run, and the same
3094
- > narrowed command, in the same tree with the mutant reverted, ran a valid green
3095
- > with the named test passing — completed, exit 0, `tests` > 0, `cancelled` 0. A
3096
- > completed exit ≠ 0 with the named test not failing is not a kill, and no kill
3097
- > stands without that green run on the unmutated tree. The result is
3098
- > inconclusive, never a kill, when the red does not reproduce in the narrowed
3099
- > run, when the unmutated tree is red too, or when no usable run exists.
3100
- >
3101
- > **Evidence line:** every kill and every valid red you claim carries one line
3102
- > in the claim's own free-text field:
3103
- > `red: <cmd> → exit N, fail K incl <test>; baseline: <cmd> → exit 0, <test> pass`.
3104
- > A failing-test finding filed off the review's shared run carries the `red:`
3105
- > half alone.
3106
- >
3107
- > An inconclusive acceptance mutation is neither a kill nor a pass: halt with
3108
- > cause `other`, with both runs — the mutant's and the unmutated tree's — as
3109
- > evidence; label nothing. A kill's evidence line goes in your report.
3110
-
3111
- **Give the finisher duty 3 verbatim as well, as one script.** The finisher's
3112
- agent definition carries this block in its body, so the brief does not repeat
3113
- it. Two finishers in one run read the release-label check as the whole duty
3114
- and reported `labelled` on a PR that never got the label, so the check and the
3115
- label write are one command and the finisher never runs either alone:
3116
-
3117
- > **Duty 3 is one script, and its exit code is your verdict.**
3118
- > `~/.fleet/bin/fleet-run finisher-label.mjs --pr <M> --pin <your dispatch pin>`
3119
- > (the full SHA). It confirms exactly one of `patch`/`minor`/`major` is on the
3120
- > PR, records the head you audited, adds `ready-to-merge`, and reads the labels
3121
- > back. Exit 0 is the only code that means the label is on. Exit 3 means the PR
3122
- > carries zero or more than one release label: you are halted before the label,
3123
- > and the receipt names which it found. Exit 4 means the read-back does not carry
3124
- > the label, written or not. Exit 2 means a `gh` call or the invocation
3125
- > itself failed: report the stderr it printed. Every non-zero exit halts you
3126
- > with cause `other`, with the receipt as evidence, and you do not run any of
3127
- > its steps by hand to get past it. A repo whose label list defines none of the
3128
- > three does not gate on one, and the script says so in its receipt. Put the
3129
- > receipt, the JSON line it printed, in your report as printed: it is what tells
3130
- > the controller the label is on.
2663
+ **What a finisher receives.** The instrument re-check, the test-run verdict
2664
+ rule, duty 1's audit script and what each of its exits means, duty 3's script
2665
+ and the halt-cause rule are the body of `agents/fleet-finisher.agent.md`, which
2666
+ the harness injects as its system prompt; none of them is pasted. The
2667
+ instrument-set rule is stated once, at the top of this file, which no finisher
2668
+ is dispatched to read, so it reaches one through that body. The brief carries
2669
+ the PR, the worktree, the dispatch pin, `<testCmd>` and the scratch root:
2670
+ `~/.fleet/bin/fleet-run dispatch-prompt.mjs render finisher --kind <fresh|repair>
2671
+ --member finisher-pr-<pr#> --pr <pr#> --pin <sha> --worktree <abs-path>
2672
+ --testCmd <testCmd> --scratch <scratch>`, which `ledger.mjs dispatch <pr#>
2673
+ finisher-pr-<pr#>` records.
3131
2674
 
3132
2675
  **Once the label is on, take it off before you approve any push.** The label is a
3133
2676
  verdict on the tree the finisher read, and a GitHub label does not follow the
@@ -3147,36 +2690,10 @@ its own (`run-merge-bot.md`, **The labelled head**), so this is not the only
3147
2690
  guard — but its refusal costs a pass and leaves the label lying, which is yours
3148
2691
  to clear either way, the same way: `label-off=` first, then the removal.
3149
2692
 
3150
- A halt at step 1 reads identical from a bare SHA mismatch whatever caused it,
2693
+ A halt at duty 1 reads identical from a bare SHA mismatch whatever caused it,
3151
2694
  and the causes `finisher-audit.mjs` names are the ones seen so far, not a
3152
- closed list. Give the finisher this verbatim, so it gets the cause from one
3153
- script instead of asking anyone:
3154
-
3155
- > **Duty 1 is one script, and its exit code is your verdict.**
3156
- > `~/.fleet/bin/fleet-run finisher-audit.mjs --worktree <abs-path> --pin <your dispatch pin>`
3157
- > (the path you were dispatched with, and the full SHA). It finds your
3158
- > worktree's row, reads whether the tree is dirty, compares the worktree's
3159
- > `HEAD` to your pin, and when the head differs derives the cause from the
3160
- > reflog. Exit 0, with `cause` null, is the only code that means the worktree is
3161
- > clean at your pin. Exit 1 means `cause` is non-null: you are halted, and
3162
- > `cause` is the word you name — `live-editor`, `rebase`, `past-pin`,
3163
- > `unreadable`, `missing`, `absent` or `other`, and `other` is a cause too, not
3164
- > a gap. Exit 2 means the script could not look: you are halted with cause
3165
- > `other`, with the line it printed on stderr as the evidence.
3166
- >
3167
- > The pin is the SHA you were dispatched against, never `PR headRefOid`: a
3168
- > member that kept working and pushed after the pin matches the branch tip on a
3169
- > clean tree, so a headRefOid comparison reports "settled" over commits no
3170
- > reviewer read — the exact divergence this halt exists to catch. You do not
3171
- > run any of the script's steps by hand to get past a halt or to second-guess
3172
- > it. Put the verdict, the JSON line it printed, in your report as printed: its
3173
- > `evidence` is what the controller resolves the halt from.
3174
- >
3175
- > Every cause halts, always — named or not, you never verify the dirt is
3176
- > harmless and label over it, a rebase is not a fast-forward you get to accept,
3177
- > a commit past the pin is not one either, and a cause you could not name is
3178
- > the least settled of the lot. Naming the cause makes the halt cheap to
3179
- > resolve, never a reason to skip it.
2695
+ closed list; the finisher's agent body gives it the cause from one script
2696
+ instead of asking anyone.
3180
2697
 
3181
2698
  **Resolving a finisher halt.** A halt is the finisher working correctly — it
3182
2699
  refused to label — so it is never `failed`, which stays for a finisher that
@@ -3289,13 +2806,15 @@ that name it refuses, naming the bot and the `dispatch-prompt.mjs render
3289
2806
  merge-bot --member merge-bot-<n> …` to run — render it, then run `ledger.mjs
3290
2807
  dispatch merge-bot` again. Dispatch
3291
2808
  it on the tick's `DISPATCH merge-bot`: the first `ready-to-merge` label is
3292
- enough, and it never waits for the finisher's report. Tell it to read
2809
+ enough, and it never waits for the finisher's report. Its body
2810
+ (`agents/fleet-merge-bot.agent.md`) tells it to read
3293
2811
  `$(~/.fleet/bin/fleet-run --root)/commands/run-merge-bot.md` and run **one**
3294
2812
  pass — drain the queue, re-evaluating after each merge, hold a 15-minute grace
3295
- for late labels, then report once and exit — and say that you dispatched it,
2813
+ for late labels, then report once and exit — and that you dispatched it,
3296
2814
  which is what makes it hold that grace instead of arming its own watcher. Its
3297
- prompt names the absolute `<scratch>` (`scratch-root.mjs`'s output): the bot
3298
- writes only under `<scratch>/pr<N>/merge-bot-<n>/`. **Dispatch
2815
+ brief is `~/.fleet/bin/fleet-run dispatch-prompt.mjs render merge-bot --member
2816
+ merge-bot-<n> --n <n> --scratch <scratch>`, `<scratch>` the absolute
2817
+ `scratch-root.mjs` output: the bot writes only under `<scratch>/pr<N>/merge-bot-<n>/`. **Dispatch
3299
2818
  it with the `agent` that `ledger.mjs dispatch merge-bot` printed and omit
3300
2819
  `model` on the call** — the tier lives in that definition's frontmatter,
3301
2820
  `agents/fleet-merge-bot.agent.md`, as the `@smol:low` route, which resolves
@@ -3717,7 +3236,7 @@ vs specific finding with paths → paths win.
3717
3236
  **Members share one filesystem, one docker stack and one process table**, and the
3718
3237
  failures arrive as *wrong findings*, not errors:
3719
3238
 
3720
- - **A pattern kill reaches siblings — say so in the dispatch prompt.** `pkill -f
3239
+ - **A pattern kill reaches siblings — the implementer, fix-applier and finisher briefs forbid it.** `pkill -f
3721
3240
  <pattern>` matches on the whole command line, machine-wide. Members hold
3722
3241
  separate worktrees, but the process table is not partitioned by them and a
3723
3242
  test file's name is identical in every one, so a pattern naming a test file
@@ -3776,8 +3295,8 @@ failures arrive as *wrong findings*, not errors:
3776
3295
  arrived.** The same incident: the controller's warning DID reach the member,
3777
3296
  which re-ran, found nothing changed, and said nothing — correctly reading
3778
3297
  "send once, never re-send" as covering it. The controller then had to spend a
3779
- round trip asking whether its own outbox was lossy. So say in the dispatch
3780
- prompt that **confirmation state includes warnings received and acted on, even
3298
+ round trip asking whether its own outbox was lossy. So the briefs say that
3299
+ **confirmation state includes warnings received and acted on, even
3781
3300
  when the outcome is no change** — one line, in the report the member already
3782
3301
  owes. That is the cheap half of the *never read silence as assent* rule, paid
3783
3302
  by the member rather than by the controller's guesswork.
@@ -3920,7 +3439,7 @@ at the price, because the cost of the wrong call is asymmetric — a live member
3920
3439
  written off gets killed and re-dispatched, which discards the work in flight
3921
3440
  and, where it holds a claim or a worktree, collides the fleet with itself,
3922
3441
  while one poll spent on a member that had in fact stopped costs only the poll.
3923
- The refuter's own observation rule in the fix-applier prompt above stops a
3442
+ The refuter's own observation rule in the fix-applier body stops a
3924
3443
  member from creating that state; this one stops you from misreading whoever
3925
3444
  reaches it anyway, and neither replaces the other.
3926
3445
 
@@ -26,6 +26,11 @@ before your final message, and send nothing until
26
26
  answers `valid`. Your final message is then one line,
27
27
  `<your name>: <outcome> <scratch>/reports/<your name>.json`, `<outcome>` the
28
28
  report's `outcome`.
29
+
30
+ The controller does not acknowledge reports. Send once and exit; never re-send unless the controller asks by name.
31
+ Confirmation state includes warnings received and acted on, even when the outcome is no change: say so when you report.
32
+ A member runs its test suite in the foreground and blocks on it. Exit 75 from the suite is not a test result; run the command again.
33
+ Never run `pkill -f` on a pattern: members share one process table, so a pattern such as a test file's name matches every member's run, not only yours. Clearing your own leftover process needs its PID; report a stalled run to the controller instead.
29
34
  ## kind: repair
30
35
 
31
36
  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.
@@ -85,6 +85,13 @@ before your final message, and send nothing until
85
85
  answers `valid`. Your final message is then one line,
86
86
  `<your name>: <outcome> <scratch>/reports/<your name>.json`, `<outcome>` the
87
87
  report's `outcome`.
88
+
89
+ Push, write your report, exit; never poll a CI run.
90
+
91
+ The controller does not acknowledge reports. Send once and exit; never re-send unless the controller asks by name.
92
+ Confirmation state includes warnings received and acted on, even when the outcome is no change: say so when you report.
93
+ A member runs its test suite in the foreground and blocks on it. Exit 75 from the suite is not a test result; run the command again.
94
+ Never run `pkill -f` on a pattern: members share one process table, so a pattern such as a test file's name matches every member's run, not only yours. Clearing your own leftover process needs its PID; report a stalled run to the controller instead.
88
95
  ## kind: dispositions-retry
89
96
 
90
97
  This is the one automatic retry of a dispositions mismatch. The mismatched
@@ -32,4 +32,6 @@ answers `valid`. Your final message is then one line,
32
32
  report's `outcome`.
33
33
 
34
34
  The controller does not acknowledge reports. Send once and exit; never re-send unless the controller asks by name.
35
+ Confirmation state includes warnings received and acted on, even when the outcome is no change: say so when you report.
35
36
  A member runs its test suite in the foreground and blocks on it. Exit 75 from the suite is not a test result; run the command again.
37
+ Never run `pkill -f` on a pattern: members share one process table, so a pattern such as a test file's name matches every member's run, not only yours. Clearing your own leftover process needs its PID; report a stalled run to the controller instead.
@@ -15,3 +15,4 @@ answers `valid`. Your final message is then one line,
15
15
  `merge-bot-<n>: done <scratch>/reports/merge-bot-<n>.json`.
16
16
 
17
17
  The controller does not acknowledge reports. Send once and exit; never re-send unless the controller asks by name.
18
+ Confirmation state includes warnings received and acted on, even when the outcome is no change: say so when you report.
@@ -0,0 +1,15 @@
1
+ ---
2
+ arg line one line
3
+ arg options options
4
+ arg hands hands
5
+ ---
6
+ ## kind: needs-triage
7
+ *Relabelled by the fleet controller.* Pulled for implementation and
8
+ returned: the brief does not decide what to build. Missing decision:
9
+ <one line>. Returning to /triage; `ready-for-agent` restored once decided.
10
+ ## kind: fork
11
+ *Relabelled by the fleet controller.* Pulled for implementation and
12
+ returned: the brief leaves a decision open. Open fork: <options>.
13
+ ## kind: hands
14
+ *Relabelled by the fleet controller.* Pulled for implementation and
15
+ returned: needs human hands — <hands>: <one line>.
@@ -21,3 +21,4 @@ never a directory whose last component is `pr` plus digits: the review creates
21
21
  that partition under the root itself.
22
22
 
23
23
  The controller does not acknowledge reports. Send once and exit; never re-send unless the controller asks by name.
24
+ Confirmation state includes warnings received and acted on, even when the outcome is no change: say so when you report.
@@ -278,16 +278,13 @@ unknown: fix that environment fault and check again; deriving would not
278
278
  help. This step is yours: one derivation
279
279
  per run start at most, never one per member, and a member never derives.
280
280
  Dispatch a `task` member named `derive-recipe`, agent
281
- `fleet-recipe-deriver`, and wait for its report — nothing in this run can
282
- claim before it lands:
283
-
284
- > Derive, prove and cache the Recipe of the repository at `<repo>`. Your
285
- > scratch directory is `<scratch>/derive-recipe/`; write nowhere else.
286
- > Follow your definition's procedure exactly, and end with its report line.
287
-
288
- `<repo>` is this main checkout's absolute path and `<scratch>` is the
289
- absolute path `scratch-root.mjs` prints (SKILL.md's **The scratch root is
290
- computed**), written into the prompt before you send it. The member reads the repository,
281
+ `fleet-recipe-deriver`, its prompt the brief `~/.fleet/bin/fleet-run
282
+ dispatch-prompt.mjs render recipe-deriver --member derive-recipe --repo <repo>
283
+ --scratch <scratch>` prints, and wait for its report — nothing in this run can
284
+ claim before it lands. `<repo>` is this main checkout's absolute path and
285
+ `<scratch>` is the absolute path `scratch-root.mjs` prints (SKILL.md's **The
286
+ scratch root is computed**); the renderer refuses a relative one. The member
287
+ reads the repository,
291
288
  proposes both commands and proves them with `recipe-prove.mjs` in a
292
289
  throwaway worktree of `origin/main`: the Install step must leave the tree
293
290
  clean, and the Test entrypoint must be shown to run real tests — the