@feigi/fleet-ctl 3.55.0 → 3.56.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@feigi/fleet-ctl",
3
- "version": "3.55.0",
3
+ "version": "3.56.0",
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": {
@@ -57,9 +57,8 @@
57
57
  // only a caller passing a value like `<branch>` can cause — refuses, naming
58
58
  // it.
59
59
  //
60
- // The text every member of a role shares is meant to live in that role's
61
- // agent body; until it does, the templates carry what the controller pasted
62
- // into the dispatch prompt by hand.
60
+ // The text every member of a role shares lives in that role's agent body; a
61
+ // template carries only what varies between dispatches of the role.
63
62
 
64
63
  import { spawnSync } from "node:child_process";
65
64
  import { createHash } from "node:crypto";
@@ -637,10 +637,9 @@ export function foldLedger({ rows, dispatched }, open, { lenient = false } = {})
637
637
  // fix-applier is still working the conflict.
638
638
  // `reviewFixed`: a REVIEW fix-applier landed after the latest
639
639
  // `reviewed=` — one read while no hold stood unresolved. The one read
640
- // while a hold did is the conflict fix-applier `ledger.mjs dispatch` named
641
- // a `fleet-implementer-<cell>`: it rebases and never sees the review file,
642
- // so it clears the hold and answers no finding. Each fix-applier
643
- // does one of those jobs once, so its landing folds once per PR
640
+ // while a hold did is the conflict fix-applier: it rebases and never sees
641
+ // the review file, so it clears the hold and answers no finding. Each
642
+ // fix-applier does one of those jobs once, so its landing folds once per PR
644
643
  // (`fixLanded`), however many copies of its token the rows carry.
645
644
  // `fixMembers`: every fix-applier on this PR, wherever its token sits —
646
645
  // one still unsettled anywhere holds the PR off fixDue, since `dispatch`
@@ -927,8 +926,8 @@ export function deriveRun({ rows, dispatched, drain }, prs, closed = new Set(),
927
926
  unlabelled: unlabelledFinishers({ rows, dispatched },
928
927
  new Set(prs.filter((p) => !isQueued(p)).map((p) => p.number))),
929
928
  // Every PR, open or not, on a conflict hold no fix-applier has cleared —
930
- // the one reading of a hold: `ledger.mjs dispatch` names a
931
- // fix-applier's definition and refuses a finisher off this list, so it
929
+ // the one reading of a hold: `ledger.mjs dispatch` refuses a finisher off
930
+ // this list, so it
932
931
  // answers the same per-PR fold this tick holds the merge on, split rows
933
932
  // and a settle made anywhere included, rather than re-deriving it from
934
933
  // one row's text.
@@ -651,22 +651,16 @@ export function expectedDefinition(rowText) {
651
651
  // The agent definition a member is dispatched as, for a parsed member
652
652
  // and the text of the row it works: `ledger.mjs dispatch` prints it so the
653
653
  // `task` call that follows names it off a script's output, not off prose a
654
- // compaction drops. A fix-applier on an unresolved conflict hold of its own PR
655
- // is a `fleet-implementer-<POLICY_CELL>` whatever the row's `tier=` —
656
- // it rebases the PR, it does not work a ticket at a tier. Any other fix-applier is a review
657
- // one and gets null: a generic `task` by design. Whether the hold is
658
- // unresolved is `conflictHeld`, the caller's to supply from fleet-tick.mjs's
659
- // deriveRun() — the reading the tick holds the merge on, which folds every
660
- // row of the PR, never one row's text alone. Throws whatever
661
- // expectedDefinition throws, and throws on a family this switch has no case
662
- // for: null is the review fix-applier's deliberate answer, so a
663
- // `default: return null` would print a new family as a generic `task`
664
- // without anyone having decided it is one.
665
- /** @returns {string|null} the definition name; null only for a review fix-applier. */
666
- export function agentDefinition(member, rowText, conflictHeld = false) {
654
+ // compaction drops. A fix-applier is `fleet-fix-applier` for every kind of
655
+ // work — a review's findings, a conflict hold, a dispositions retry — whatever
656
+ // the row says. Throws whatever expectedDefinition throws, and throws on a
657
+ // family this switch has no case for: a `default` answer would print a new
658
+ // family as a definition without anyone having decided it is one.
659
+ /** @returns {string} the definition name. */
660
+ export function agentDefinition(member, rowText) {
667
661
  switch (member.family) {
668
662
  case "impl": return expectedDefinition(rowText);
669
- case "fix-pr": return conflictHeld ? `fleet-implementer-${POLICY_CELL}` : null;
663
+ case "fix-pr": return "fleet-fix-applier";
670
664
  case "finisher-pr": return "fleet-finisher";
671
665
  case "merge-bot": return "fleet-merge-bot";
672
666
  default: throw new Error(`agentDefinition has no case for member family '${member.family}' (${member.name}) — add one to ledger-grammar.mjs`);
@@ -1877,15 +1877,17 @@ function runDispatch() {
1877
1877
  // refused here, before the member is live, not discovered by the check
1878
1878
  // after the call.
1879
1879
  //
1880
- // A fix-applier's turns on whether its PR sits on an unresolved conflict
1881
- // hold, and that is the tick's own verdict, not a second reading
1882
- // of row `i`: a PR's tokens can be split across its ticket row and its own
1883
- // `#<pr>` row, and a settle can live in `## Dispatched` alone, so
1880
+ // A fix-applier is `fleet-fix-applier` for every kind of work — review,
1881
+ // conflict hold, dispositions retry — so its definition reads nothing off
1882
+ // the ledger.
1883
+ //
1884
+ // The finisher's gates below turn on the tick's own verdict, not a second
1885
+ // reading of row `i`: a PR's tokens can be split across its ticket row and
1886
+ // its own `#<pr>` row, and a settle can live in `## Dispatched` alone, so
1884
1887
  // one row's text can read held where the tick reads cleared, and the
1885
1888
  // reverse. A ledger the tick refuses is refused here too, before the member
1886
- // is live, rather than named a definition off a reading the tick rejects.
1887
- // `tickFold` reads that fold for whichever of the two families needs it,
1888
- // `what` naming what could not be read off a refused ledger.
1889
+ // is live. `tickFold` reads that fold, `what` naming what could not be read
1890
+ // off a refused ledger.
1889
1891
  const tickFold = (what) => {
1890
1892
  try {
1891
1893
  return deriveRun({ rows: data.rows, dispatched: data.dispatched, drain: data.drain }, []);
@@ -1894,7 +1896,6 @@ function runDispatch() {
1894
1896
  die(`${e.message} — fleet-tick.mjs refuses this ledger, so ${member.name}'s ${what} cannot be read off it; fix it with \`ledger.mjs row\` before dispatching`);
1895
1897
  }
1896
1898
  };
1897
- const held = member.family === "fix-pr" && tickFold("definition").conflictHeld.includes(member.number);
1898
1899
 
1899
1900
  // A finisher labels its PR `ready-to-merge`, so it is recorded only once
1900
1901
  // the PR sits on no conflict hold a fix-applier has yet to clear — a PR
@@ -1922,7 +1923,7 @@ function runDispatch() {
1922
1923
  // refusal's tail names neither.
1923
1924
  let agent;
1924
1925
  try {
1925
- agent = agentDefinition(member, i === -1 ? "" : data.rows[i], held);
1926
+ agent = agentDefinition(member, i === -1 ? "" : data.rows[i]);
1926
1927
  if (member.family === "impl" && !existsSync(join(AGENTS_DIR, `${agent}.agent.md`))) {
1927
1928
  throw new Error(`row #${member.number}'s tier= names ${agent}, which has no agents/${agent}.agent.md — fix the row with \`ledger.mjs row\``);
1928
1929
  }
@@ -18,8 +18,8 @@
18
18
  // - any subagent whose definition name starts with `fleet-`;
19
19
  // - any subagent whose own id is a fleet member's task name (`impl-1411`,
20
20
  // `fix-pr-88`, `review-pr-2245`, `finisher-pr-7`, with an optional `-b`
21
- // recovery suffix): this is how a fix-applier is caught, since it is
22
- // dispatched under a generic `task` definition with no `fleet-` prefix;
21
+ // recovery suffix): a member named by id is caught whatever definition
22
+ // name its dispatch gave it;
23
23
  // - any subagent spawned BY a fleet member: its `parentId` is the member's
24
24
  // task name, while its own definition name is a generic one no prefix
25
25
  // check could see.
@@ -36,7 +36,8 @@
36
36
  // same set, and the checkout's HEAD besides).
37
37
  // - `bash` cwd, for every `fleet-implementer-<cell>` (ledger-grammar.mjs's
38
38
  // `CELL_DEF`), and for a fix-applier's own id (`fix-pr-<n>`) directly,
39
- // since a review fix-applier is a generic `task`: refuse when
39
+ // since its definition, `fleet-fix-applier`, is no implementer cell and
40
+ // `CELL_DEF` does not match it: refuse when
40
41
  // `input.cwd ?? ctx.cwd` lies inside the main checkout outside
41
42
  // `.worktrees/`. Command text is never parsed. Review specialists and
42
43
  // refuters are REQUIRED to start from the inherited cwd (`pwd` first,
@@ -71,7 +72,7 @@ import { fileURLToPath } from "node:url";
71
72
  import { gitEnv, workspaceDirFromGitCommonDir } from "./git-env.mjs";
72
73
  import { CELL_DEF } from "./ledger-grammar.mjs";
73
74
 
74
- /** The task names the controller gives fleet members; a subagent whose parent carries one is a member's child, and a fix-applier — dispatched under a generic `task` definition with no `fleet-` prefix — is caught by its own id matching this directly. */
75
+ /** The task names the controller gives fleet members; a subagent whose parent carries one is a member's child, and a member whose own id matches this is caught directly, whatever definition name its dispatch gave it. */
75
76
  const MEMBER_TASK_NAME = /^(impl|fix-pr|review-pr|finisher-pr)-\d+(-[a-z])?$/;
76
77
  const FIX_APPLIER_ID = /^fix-pr-\d+(-[a-z])?$/;
77
78
  const PATH_WRITERS = new Set(["write", "edit", "ast_edit"]);
@@ -164,11 +164,12 @@ makes one up.
164
164
  ## Shell traps
165
165
 
166
166
  Monitor and Bash commands run under **zsh**, and the shell in this file is
167
- prescriptive — copied verbatim into a watcher or pasted into a bot's brief. So
168
- every trap here is a zsh-vs-bash difference that ships as a green-looking gate:
169
- correct in the shell you tested in, silently wrong in the one it runs in. Phase
170
- 3's monitor paragraph and the **Merge bot**'s brief both point here
171
- instead of restating any of it; the one deliberate copy is named at the end.
167
+ prescriptive — copied verbatim into a watcher or into the merge bot's agent
168
+ body. So every trap here is a zsh-vs-bash difference that ships as a
169
+ green-looking gate: correct in the shell you tested in, silently wrong in the
170
+ one it runs in. Phase 3's monitor paragraph points here instead of restating
171
+ any of it. The merge bot's agent body is the one place this block is copied
172
+ whole (see **Merge bot**); the other deliberate copy is named at the end.
172
173
 
173
174
  **zsh word-splits an unquoted command substitution's result; it does NOT split
174
175
  an unquoted parameter expansion.** That one difference is the whole rule, and the
@@ -236,7 +237,7 @@ reads as a check that silently did not run. Same root cause as the `PIPESTATUS`
236
237
  trap, opposite failure direction — so name the variable anything else
237
238
  (`ci_status`).
238
239
 
239
- **The one deliberate copy is `env $cfg sh ./probe.sh`.** The first trap's
240
+ **The other deliberate copy is `env $cfg sh ./probe.sh`.** The first trap's
240
241
  mechanism bites argv as well as loops, and that instance stays written out in the
241
242
  fix-applier prompt and every refuter brief under **Reviewers** rather than here,
242
243
  because the seats that inject faults are the ones that need it and a bot reads
@@ -2611,10 +2612,8 @@ is the same slot with a different job, and no review file to hand
2611
2612
  over. Name it `fix-pr-<M>`, or the next suffix (`-b`, `-c` …) when that name is
2612
2613
  already on record — `dispatch` refuses a reused one — and dispatch it with the
2613
2614
  `agent` that `ledger.mjs dispatch` printed, in the PR's existing worktree.
2614
- `dispatch` reads the unresolved hold off the tick's own per-PR state — every
2615
- row naming the PR, not one — and prints this member's own definition, whatever
2616
- the row's `tier=` — read it off that output, never recall it; a review
2617
- fix-applier's is `null`. Its prompt takes the prompt below's
2615
+ `dispatch` prints this member's definition, `fleet-fix-applier` whatever the
2616
+ row's `tier=` — read it off that output, never recall it. Its prompt takes the prompt below's
2618
2617
  worktree, branch and path discipline, but in place of its review paragraphs:
2619
2618
  bring `<branch>` current with `origin/main`, resolving every conflict by
2620
2619
  `run-merge-bot.md`'s **No-undo audit**, run `<testCmd>`, push, report the new
@@ -2623,8 +2622,8 @@ what lifts the tick's merge hold; a dispatched-but-live one does not, and
2623
2622
  `failed`/`killed` leave the PR fix-due for a replacement. It answers the
2624
2623
  hold and nothing else: survived or unverified findings of a returned review the row also carries
2625
2624
  stay unanswered through its settle, so the tick prints `DISPATCH fix-pr
2626
- PR#<M>` again once it lands, and that one — `dispatch` now prints `null` —
2627
- is a review fix-applier, dispatched as above. On a PR carrying
2625
+ PR#<M>` again once it lands, and that one is a review fix-applier, dispatched
2626
+ as above. On a PR carrying
2628
2627
  `ready-to-merge`, the push moves the head after the label, so the next merge
2629
2628
  bot refuses it `head-moved-after-label-#<M>`: a fresh finisher, per **Failure
2630
2629
  handling**.
@@ -2654,8 +2653,8 @@ bullets without the others and what strands is exactly the red-only PR.
2654
2653
 
2655
2654
  Name it `fix-pr-<M>`, or the next free suffix (`-b`, `-c` …) — `dispatch`
2656
2655
  refuses a reused name — record it with `ledger.mjs dispatch <pr#> <name>`
2657
- before the call, and dispatch it with the `agent` that command printed (`null`
2658
- while no conflict hold stands, as for a review fix-applier), in the PR's
2656
+ before the call, and dispatch it with the `agent` that command printed
2657
+ (`fleet-fix-applier`, as for a review fix-applier), in the PR's
2659
2658
  existing worktree. Its prompt takes the prompt below's worktree, branch and
2660
2659
  path discipline, but in place of its review paragraphs: read the failing job's
2661
2660
  log, fix the cause, run `<testCmd>`, push, report the new head, and **stop**.
@@ -3378,7 +3377,7 @@ each run a script the digest covers — `finisher-audit.mjs` (which runs
3378
3377
  `worktree-audit.sh`) and `ledger.mjs`, both under `plugin/scripts/` — and the
3379
3378
  label at duty 3 rests on what they returned. The rule is stated once, at the
3380
3379
  top of this file, which no finisher is dispatched to read, so it reaches one
3381
- through this block or not at all:
3380
+ through this block, which `agents/fleet-finisher.agent.md` carries in its body:
3382
3381
 
3383
3382
  > **Re-check the instrument set before you act on what duty 1 or duty 2 read,
3384
3383
  > and again before you add the label.**
@@ -3400,7 +3399,7 @@ through this block or not at all:
3400
3399
 
3401
3400
  **Give the finisher the test-run verdict rule verbatim too.** Duty 2 runs
3402
3401
  `<testCmd>` for the acceptance mutation, and the finisher's agent definition
3403
- says nothing about what a run that was cut short looks like. A `node --test`
3402
+ carries a copy of the rule below. A `node --test`
3404
3403
  stopped by an outside `timeout` still prints a summary, covering only the tests
3405
3404
  it reached, so reading that summary alone reads a partial suite as a whole one:
3406
3405
 
@@ -3470,8 +3469,8 @@ it reached, so reading that summary alone reads a partial suite as a whole one:
3470
3469
  > evidence; label nothing. A kill's evidence line goes in your report.
3471
3470
 
3472
3471
  **Give the finisher duty 3 verbatim as well, as one script.** The finisher's
3473
- agent definition carries no duty text, so this brief is the whole of duty 3 it
3474
- sees. Two finishers in one run read the release-label check as the whole duty
3472
+ agent definition carries this block in its body, so the brief does not repeat
3473
+ it. Two finishers in one run read the release-label check as the whole duty
3475
3474
  and reported `labelled` on a PR that never got the label, so the check and the
3476
3475
  label write are one command and the finisher never runs either alone:
3477
3476
 
@@ -3664,14 +3663,17 @@ deterministic, script-driven backstop run before every push specifically to
3664
3663
  catch a wrongly-resolved conflict, so the tier buys nothing that backstop
3665
3664
  doesn't already cover.
3666
3665
 
3667
- **Put the shell traps in the bot's brief, not in a follow-up message.** A bot
3668
- already looping cannot be corrected — the loop consumes the turns a correction
3669
- would land in. **Every entry in Shell traps, verbatim** — that section is where
3670
- they are stated once, and this is the seat that has to paste them: the bot
3671
- reads an exit code off `gh pr update-branch`, `merge-gate.mjs` and
3672
- `prove-merge.sh`, which is the `PIPESTATUS` and read-only-`status` pair, and its
3673
- grace poll captures `gh pr list` output and loops over it, which is the
3674
- assigned-variable trap. The brief always travels with the dispatch.
3666
+ **The shell traps live in the merge bot's agent body, not in its brief and not
3667
+ in a follow-up message.** A bot already looping cannot be corrected — the loop
3668
+ consumes the turns a correction would land in — so
3669
+ `agents/fleet-merge-bot.agent.md` carries **every entry in Shell traps**, copied
3670
+ from that section, and the bot has them before its first turn. The bot reads an
3671
+ exit code off `gh pr update-branch`, `merge-gate.mjs` and `prove-merge.sh`,
3672
+ which is the `PIPESTATUS` and read-only-`status` pair, and its grace poll
3673
+ captures `gh pr list` output and loops over it, which is the assigned-variable
3674
+ trap. Its brief names the bot and `<scratch>`, plus the one-line
3675
+ no-acknowledgement notice; do not paste the
3676
+ traps there. An edit to Shell traps lands in that body in the same change.
3675
3677
 
3676
3678
  **Its merge gate is one script, run twice.** Step 3 of `run-merge-bot.md` is
3677
3679
  `merge-gate.mjs --pr <n> --pre <sha> [--post <sha>]`: read-only, it runs the
@@ -4328,14 +4330,13 @@ live count from it, so nobody states one. Write neither by hand:
4328
4330
  merge-bot` names the next bot itself. It prints `{member, agent, ticket,
4329
4331
  line, created, total}`; `agent` is the definition the `task` call names — an
4330
4332
  implementer's comes off its row's `tier=` (phase 2's tier check states the
4331
- mapping), a finisher's and a merge bot's are their own definitions, a
4332
- review fix-applier's is `null`, and a conflict-hold fix-applier's is
4333
- `fleet-implementer-slow-high`: its own section says how it is dispatched. It
4333
+ mapping), a finisher's and a merge bot's are their own definitions, and a
4334
+ fix-applier's is `fleet-fix-applier` for every kind of work. It
4334
4335
  refuses a name this session already used — on the ledger or in its
4335
4336
  `## Retired` — and names the replacement (`-b`, `-c` …), a
4336
4337
  second live member on one ticket or PR, any implementer once the run is
4337
4338
  draining, an implementer whose row's `tier=` names no single definition
4338
- or one with no file under `agents/`, and a fix-applier on a ledger the tick
4339
+ or one with no file under `agents/`, and a finisher on a ledger the tick
4339
4340
  itself refuses.
4340
4341
  - **`ledger.mjs settle <member> <outcome>`** — rewrites the token to
4341
4342
  `<member>=<outcome>` in both places. Outcomes: `impl-N` = `PR#M | bailed |
@@ -3,135 +3,18 @@ arg worktree abs-path
3
3
  arg pin your dispatch pin
4
4
  arg pr M
5
5
  arg testCmd testCmd
6
+ arg scratch scratch
6
7
  path worktree
7
- literal args
8
- literal cmd
9
- literal test
8
+ path scratch
10
9
  ---
11
10
  ## kind: fresh, repair
12
- **Re-check the instrument set before you act on what duty 1 or duty 2 read,
13
- and again before you add the label.**
14
- `~/.fleet/bin/fleet-run instruments.sh --repo "$(dirname "$(env -u GIT_DIR -u GIT_WORK_TREE git rev-parse --git-common-dir)")"`.
15
- Exit 0 is the only code that lets you go on. Exit 1 (the set changed) and
16
- exit 2 (the check could not answer) both halt you: report what it printed,
17
- add no label, and do NOT re-read the script that gave you the reading.
18
- `--repo` is required and the spelling is the point — the run's baseline lives
19
- in the audited checkout's gitignored `.fleet/`, which the scratch worktree
20
- you take at duty 2 does not carry, so a bare invocation from there exits 2 on
21
- a missing baseline instead of comparing anything. The `env -u GIT_DIR -u
22
- GIT_WORK_TREE` wrapper guards against an ambient `GIT_DIR` in your own shell
23
- pointing this check at the wrong tree — the script's own internal unset
24
- cannot reach back and fix a path you already resolved wrong. The baseline
25
- itself names the tree to audit: a cross-workspace run pinned it once at
26
- phase 0, and your `--repo` only locates that baseline, never the audited
27
- tree — so an exit 2 naming a moved or unreadable audited tree is a halt
28
- like every other, not a spelling for you to correct.
11
+ Finish PR <M>. Your arguments are the whole of your per-dispatch task:
29
12
 
30
- **A test run is a verdict only if it ran to completion — and you read that
31
- off the test command's own exit status.**
32
- Redirect the run's output to a file in your scratch directory and read the
33
- command's own `$?` straight after it, then read the file. In an `eval` cell
34
- there is no `$?`: spawn `<testCmd>` with its output going to that file and
35
- read the exit code and the signal off the spawn result — `exitCode` and
36
- `signalCode` on Bun's `spawnSync`, `returncode` on Python's `subprocess.run`,
37
- which is negative for a signal. Never read the status of
38
- `<testCmd> | tail` or `<testCmd> | grep`: a pipeline's status is its
39
- last stage's, so the filter's 0 hides the run's own exit, and the array that
40
- holds the earlier stages' statuses is spelled differently per shell. A run is
41
- a verdict only when that exit status is 0 **and** its summary shows `tests`
42
- above 0 and `cancelled` 0. A summary line without that
43
- is not a verdict, whatever pass count it prints.
44
- **A run completed when the command itself returned on its own** — an exit
45
- code, no signal, and no `timeout`, deadline or kill of yours having fired.
46
- Judge that by how the run ended, never by its `cancelled` count: a failing
47
- `before` hook or a per-test `timeout` cancels tests inside a run that
48
- completed, and a SIGTERM'd `node --test` can exit 1 with `cancelled` above 0
49
- in a run that did not.
50
- **Any run that did not complete is a killed run** — 124 (`timeout`), 137
51
- (SIGKILL), 143 (SIGTERM), a signal in the spawn result, an `eval` cell's
52
- deadline — and read for green it is FAILED, the same bucket as
53
- `tests 0`, however many tests had passed before the kill. Halt with cause
54
- `other` and the exit code plus the summary line as evidence; label nothing.
55
- The same holds for the mutation gate: a killed run is not a mutant that
56
- reddened, and the files it cancelled are not failures — only a run that
57
- completed can kill a mutant. A completed run that exits 1 is not a killed run
58
- either, whatever its `cancelled` count, and not a killed mutant on its exit
59
- status alone: the acceptance mutation scores a kill only by the rules below.
60
- Exit 0 with `tests 0` stays FAILED.
61
- Do not wrap `<testCmd>` in an external `timeout`. Run a long suite in one
62
- `eval` cell with `timeout: 0`, as the review runner does, and wait for it.
63
-
64
- **Valid red:** a run that completed — the command returned on its own, with
65
- no signal and no timeout, deadline or kill having fired — in which the test
66
- the claim names is reported failing. An exit ≠ 0 with no failing test is not
67
- red, and a different test failing is not red for this claim. A red in the full
68
- suite only triggers a narrowed run; it is never evidence on its own.
69
-
70
- **Narrowed run:** the Test entrypoint with arguments appended,
71
- `<testCmd> <args>`. That appended arguments reach the Test entrypoint is all
72
- that is promised about them, so a narrowed run counts only if it reports
73
- `tests` > 0 and its output names the claimed test. If no narrowing can be
74
- proven, run the full `<testCmd>` and read the named test's own result from its
75
- output.
76
-
77
- **Kill:** the mutant produced a valid red in a narrowed run, and the same
78
- narrowed command, in the same tree with the mutant reverted, ran a valid green
79
- with the named test passing — completed, exit 0, `tests` > 0, `cancelled` 0. A
80
- completed exit ≠ 0 with the named test not failing is not a kill, and no kill
81
- stands without that green run on the unmutated tree. The result is
82
- inconclusive, never a kill, when the red does not reproduce in the narrowed
83
- run, when the unmutated tree is red too, or when no usable run exists.
84
-
85
- **Evidence line:** every kill and every valid red you claim carries one line
86
- in the claim's own free-text field:
87
- `red: <cmd> → exit N, fail K incl <test>; baseline: <cmd> → exit 0, <test> pass`.
88
- A failing-test finding filed off the review's shared run carries the `red:`
89
- half alone.
90
-
91
- An inconclusive acceptance mutation is neither a kill nor a pass: halt with
92
- cause `other`, with both runs — the mutant's and the unmutated tree's — as
93
- evidence; label nothing. A kill's evidence line goes in your report.
94
-
95
- **Duty 3 is one script, and its exit code is your verdict.**
96
- `~/.fleet/bin/fleet-run finisher-label.mjs --pr <M> --pin <your dispatch pin>`
97
- (the full SHA). It confirms exactly one of `patch`/`minor`/`major` is on the
98
- PR, records the head you audited, adds `ready-to-merge`, and reads the labels
99
- back. Exit 0 is the only code that means the label is on. Exit 3 means the PR
100
- carries zero or more than one release label: you are halted before the label,
101
- and the receipt names which it found. Exit 4 means the read-back does not carry
102
- the label, written or not. Exit 2 means a `gh` call or the invocation
103
- itself failed: report the stderr it printed. Every non-zero exit halts you
104
- with cause `other`, with the receipt as evidence, and you do not run any of
105
- its steps by hand to get past it. A repo whose label list defines none of the
106
- three does not gate on one, and the script says so in its receipt. Put the
107
- receipt, the JSON line it printed, in your report as printed: it is what tells
108
- the controller the label is on.
109
-
110
- **Duty 1 is one script, and its exit code is your verdict.**
111
- `~/.fleet/bin/fleet-run finisher-audit.mjs --worktree <abs-path> --pin <your dispatch pin>`
112
- (the path you were dispatched with, and the full SHA). It finds your
113
- worktree's row, reads whether the tree is dirty, compares the worktree's
114
- `HEAD` to your pin, and when the head differs derives the cause from the
115
- reflog. Exit 0, with `cause` null, is the only code that means the worktree is
116
- clean at your pin. Exit 1 means `cause` is non-null: you are halted, and
117
- `cause` is the word you name — `live-editor`, `rebase`, `past-pin`,
118
- `unreadable`, `missing`, `absent` or `other`, and `other` is a cause too, not
119
- a gap. Exit 2 means the script could not look: you are halted with cause
120
- `other`, with the line it printed on stderr as the evidence.
121
-
122
- The pin is the SHA you were dispatched against, never `PR headRefOid`: a
123
- member that kept working and pushed after the pin matches the branch tip on a
124
- clean tree, so a headRefOid comparison reports "settled" over commits no
125
- reviewer read — the exact divergence this halt exists to catch. You do not
126
- run any of the script's steps by hand to get past a halt or to second-guess
127
- it. Put the verdict, the JSON line it printed, in your report as printed: its
128
- `evidence` is what the controller resolves the halt from.
129
-
130
- Every cause halts, always — named or not, you never verify the dirt is
131
- harmless and label over it, a rebase is not a fast-forward you get to accept,
132
- a commit past the pin is not one either, and a cause you could not name is
133
- the least settled of the lot. Naming the cause makes the halt cheap to
134
- resolve, never a reason to skip it.
13
+ pr: <M>
14
+ worktree: <abs-path>
15
+ pin: <your dispatch pin>
16
+ testCmd: <testCmd>
17
+ scratch: <scratch>
135
18
  ## kind: repair
136
19
 
137
20
  An earlier finisher on this PR reported `labelled`, but its read-back did not carry `ready-to-merge`: you are the repair finisher. Duty 3's script decides whether the label is on, as above.