@feigi/fleet-ctl 3.53.1 → 3.54.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.
@@ -0,0 +1,257 @@
1
+ #!/usr/bin/env node
2
+ // dispatch-prompt.mjs — render one member's dispatch brief from its template.
3
+ //
4
+ // dispatch-prompt.mjs render <role> [--kind <kind>] [--<arg> <value>…]
5
+ // [--member <name>] [--json]
6
+ //
7
+ // Roles: implementer, fix-applier, finisher, merge-bot, review-runner,
8
+ // recipe-deriver. A role with kinds (fix-applier: review, conflict,
9
+ // dispositions-retry; finisher: fresh, repair) requires --kind; a role
10
+ // without them refuses it as an unknown flag.
11
+ //
12
+ // OUTPUT. The brief on stdout and nothing else. With --json the payload
13
+ // {role, kind, args, sha256} replaces it, `sha256` being the hash of the
14
+ // brief's bytes. With --member <name> the brief is also written to
15
+ // `<fleet-dir>/briefs/<name>.md` and the payload plus `path` (the .md file)
16
+ // to `<fleet-dir>/briefs/<name>.json`, `<fleet-dir>` as fleet-dir.mjs's
17
+ // fleetFile() resolves it. Every file is written before anything reaches
18
+ // stdout, so a failed write leaves no brief for a caller to dispatch on.
19
+ //
20
+ // EXIT. 0 rendered. 2 refused, with the reason on stderr and nothing on
21
+ // stdout: a missing, unknown or relative argument, a template that carries a
22
+ // placeholder it never declared or no text at all for the kind, a leftover
23
+ // declared placeholder in the output, or instruments.sh answering anything
24
+ // but 0.
25
+ //
26
+ // INSTRUMENTS. After the command line has parsed and before anything is
27
+ // validated or rendered, instruments.sh runs from the main checkout — the
28
+ // directory holding the git common dir, where the run's baseline lives — and
29
+ // any outcome but exit 0 refuses: a changed set, an unanswerable check, a
30
+ // spawn that never ran, a signal. That is the fail-closed contract
31
+ // instruments.sh states for its own callers.
32
+ //
33
+ // THE TEMPLATE CONTRACT. One file per role, `skills/run-team/briefs/<role>.md`,
34
+ // beside the install this script runs from.
35
+ //
36
+ // - A frontmatter block, `---` on the first line and on its own closing line,
37
+ // holds one directive per line:
38
+ // arg <flag> <placeholder> the argument `--<flag>` fills `<placeholder>`
39
+ // path <flag> that argument must be an absolute path
40
+ // literal <text> `<text>` is carried to the member as written
41
+ // A placeholder is `<` + a letter + anything but `<`, `>` and a newline +
42
+ // `>`, matched by its inner text exactly; it may hold spaces. No flag and
43
+ // no placeholder is declared twice, and --member, --json and --kind are
44
+ // reserved.
45
+ // - Every placeholder the selected text carries must be declared by `arg` or
46
+ // `literal`; an undeclared one is a template defect and refuses, naming it.
47
+ // - An argument is required exactly when its placeholder occurs in the text
48
+ // selected for the kind. A flag the selected text never uses is refused.
49
+ // - The body is plain text. Lines `## kind: <k>[, <k>…]` open a section that
50
+ // applies to those kinds; text before the first such line applies to every
51
+ // kind. The brief is the applicable sections' lines in file order, joined
52
+ // with newlines and ended by one. Sections may repeat and interleave, which
53
+ // is how kinds share text without a copy.
54
+ // - Substitution is one pass over the template: a value is never rescanned,
55
+ // so a value holding another placeholder's spelling is not substituted into.
56
+ // After it, any declared placeholder still present in the output — which
57
+ // only a caller passing a value like `<branch>` can cause — refuses, naming
58
+ // it.
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.
63
+
64
+ import { spawnSync } from "node:child_process";
65
+ import { createHash } from "node:crypto";
66
+ import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
67
+ import { dirname, isAbsolute, join } from "node:path";
68
+ import { fileURLToPath } from "node:url";
69
+ import { makeDie, defineFlags, writeAll } from "./arg.mjs";
70
+ import { FleetDirUnresolvable, fleetFile } from "./fleet-dir.mjs";
71
+ import { gitEnv } from "./git-env.mjs";
72
+ import { runnerScratchRefusal } from "./review-core.mjs";
73
+
74
+ const NAME = "dispatch-prompt";
75
+ const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url));
76
+ const BRIEFS_DIR = join(SCRIPT_DIR, "..", "skills", "run-team", "briefs");
77
+ const ROLES = ["implementer", "fix-applier", "finisher", "merge-bot", "review-runner", "recipe-deriver"];
78
+ const RESERVED = ["member", "json", "kind"];
79
+ const USAGE = `usage: ${NAME}.mjs render <role> [--kind <kind>] [--<arg> <value>…] [--member <name>] [--json] — roles: ${ROLES.join(", ")}`;
80
+ const PLACEHOLDER = /<([A-Za-z][^<>\n]*)>/g;
81
+ const KIND_HEADER = /^## kind: (.+)$/;
82
+
83
+ const die = makeDie(NAME);
84
+
85
+ // --- the template ------------------------------------------------------------
86
+
87
+ function parseTemplate(role, text) {
88
+ const lines = text.split("\n");
89
+ if (lines.at(-1) === "") lines.pop();
90
+ const refuse = (why) => die(`template ${role}.md ${why}`);
91
+ if (lines[0] !== "---") refuse("does not open with a --- frontmatter block");
92
+ const close = lines.indexOf("---", 1);
93
+ if (close === -1) refuse("never closes its frontmatter block");
94
+
95
+ const args = [];
96
+ const paths = new Set();
97
+ const literals = new Set();
98
+ for (const line of lines.slice(1, close)) {
99
+ const m = /^(arg|path|literal) (.+)$/.exec(line);
100
+ if (m === null) refuse(`has a frontmatter line that is no directive: ${line}`);
101
+ if (m[1] === "literal") {
102
+ literals.add(m[2]);
103
+ } else if (m[1] === "path") {
104
+ paths.add(m[2]);
105
+ } else {
106
+ const split = /^(\S+) (.+)$/.exec(m[2]);
107
+ if (split === null) refuse(`has an arg line without a placeholder: ${line}`);
108
+ const [, flag, placeholder] = split;
109
+ if (RESERVED.includes(flag)) refuse(`declares the reserved flag --${flag}`);
110
+ if (args.some((a) => a.flag === flag || a.placeholder === placeholder)) refuse(`declares --${flag} or <${placeholder}> twice`);
111
+ args.push({ flag, placeholder });
112
+ }
113
+ }
114
+ for (const flag of paths) if (!args.some((a) => a.flag === flag)) refuse(`marks --${flag} as a path but never declares it`);
115
+ for (const a of args) if (literals.has(a.placeholder)) refuse(`declares <${a.placeholder}> as both an argument and a literal`);
116
+
117
+ const sections = [];
118
+ let current = { kinds: null, lines: [] };
119
+ sections.push(current);
120
+ for (const line of lines.slice(close + 1)) {
121
+ const header = KIND_HEADER.exec(line);
122
+ if (header === null) {
123
+ current.lines.push(line);
124
+ continue;
125
+ }
126
+ current = { kinds: header[1].split(",").map((k) => k.trim()), lines: [] };
127
+ sections.push(current);
128
+ }
129
+ const kinds = [...new Set(sections.flatMap((s) => s.kinds ?? []))];
130
+
131
+ const whole = sections.flatMap((s) => s.lines).join("\n");
132
+ for (const a of args) if (!whole.includes(`<${a.placeholder}>`)) refuse(`declares <${a.placeholder}> but never carries it`);
133
+ return { args, paths, literals, sections, kinds };
134
+ }
135
+
136
+ function loadTemplate(role) {
137
+ let text;
138
+ try {
139
+ text = readFileSync(join(BRIEFS_DIR, `${role}.md`), "utf8");
140
+ } catch (err) {
141
+ return die(`cannot read the template for ${role}: ${err.message}`);
142
+ }
143
+ return parseTemplate(role, text);
144
+ }
145
+
146
+ // --- the instrument check ---------------------------------------------------
147
+
148
+ function runInstruments() {
149
+ let root;
150
+ try {
151
+ root = dirname(fleetFile(null));
152
+ } catch (err) {
153
+ if (err instanceof FleetDirUnresolvable) die(`instruments.sh not run — no main checkout to run it from: ${err.message}`);
154
+ throw err;
155
+ }
156
+ const r = spawnSync("sh", [join(SCRIPT_DIR, "instruments.sh"), "--repo", root], {
157
+ encoding: "utf8",
158
+ stdio: ["ignore", "pipe", "pipe"],
159
+ env: gitEnv(),
160
+ });
161
+ if (r.error) die(`instruments.sh could not run: ${r.error.message}`);
162
+ if (r.signal) die(`instruments.sh was killed by ${r.signal}`);
163
+ if (r.status === 0) return;
164
+ const said = (r.stderr ?? "").trim() || (r.stdout ?? "").trim();
165
+ const verdict = r.status === 1 ? "the instrument set changed" : `the check could not answer (exit ${r.status})`;
166
+ die(`instruments.sh refused: ${verdict}${said ? ` — ${said}` : ""}`);
167
+ }
168
+
169
+ // --- main --------------------------------------------------------------------
170
+
171
+ const argv = process.argv.slice(2);
172
+ const role = argv[0] === "render" && argv[1] !== undefined && !argv[1].startsWith("--") ? argv[1] : null;
173
+ if (role !== null && !ROLES.includes(role)) die(`unknown role ${role} — roles: ${ROLES.join(", ")}`);
174
+ const template = role === null ? null : loadTemplate(role);
175
+ // The role is the one positional the shared stray() refusal does not know:
176
+ // take it out of argv so the declared grammar is just `render`.
177
+ if (role !== null) process.argv.splice(3, 1);
178
+
179
+ const flags = { member: "value", json: "bool" };
180
+ if (template !== null) {
181
+ if (template.kinds.length > 0) flags.kind = "value";
182
+ for (const a of template.args) flags[a.flag] = "value";
183
+ }
184
+ const { arg, has, sweep, stray } = defineFlags(die, { flags, positionals: ["render"] });
185
+ sweep();
186
+ stray();
187
+ if (role === null) die(USAGE);
188
+
189
+ runInstruments();
190
+
191
+ let kind = null;
192
+ if (template.kinds.length > 0) {
193
+ kind = arg("kind");
194
+ if (kind === null) die(`--kind is required for ${role} — one of ${template.kinds.join(", ")}`);
195
+ if (!template.kinds.includes(kind)) die(`--kind ${kind} is not a kind of ${role} — one of ${template.kinds.join(", ")}`);
196
+ }
197
+ const selected = template.sections.filter((s) => s.kinds === null || s.kinds.includes(kind)).flatMap((s) => s.lines);
198
+ const body = selected.join("\n");
199
+ if (body.trim() === "") die(`template ${role}.md carries no text for ${kind === null ? "the role" : `kind ${kind}`}`);
200
+
201
+ const declared = new Set(template.args.map((a) => a.placeholder));
202
+ for (const [, inner] of body.matchAll(PLACEHOLDER)) {
203
+ if (!declared.has(inner) && !template.literals.has(inner)) die(`template ${role}.md carries the undeclared placeholder <${inner}>`);
204
+ }
205
+
206
+ const required = template.args.filter((a) => body.includes(`<${a.placeholder}>`));
207
+ for (const a of template.args) {
208
+ if (!required.includes(a) && arg(a.flag) !== null) {
209
+ die(`--${a.flag} is not an argument of ${role}${kind === null ? "" : ` ${kind}`} — accepted: ${required.map((r) => `--${r.flag}`).join(", ")}`);
210
+ }
211
+ }
212
+
213
+ const values = new Map();
214
+ for (const a of required) {
215
+ const value = arg(a.flag);
216
+ if (value === null) die(`missing required argument: --${a.flag}`);
217
+ if (template.paths.has(a.flag) && !isAbsolute(value)) die(`--${a.flag} must be an absolute path, got ${value}`);
218
+ if (role === "review-runner" && a.flag === "scratch") {
219
+ const refusal = runnerScratchRefusal(value);
220
+ if (refusal !== null) die(refusal);
221
+ }
222
+ values.set(a.placeholder, value);
223
+ }
224
+
225
+ const brief = `${body.replace(PLACEHOLDER, (whole, inner) => (values.has(inner) ? values.get(inner) : whole))}\n`;
226
+ for (const a of required) {
227
+ if (brief.includes(`<${a.placeholder}>`)) die(`the rendered brief still carries <${a.placeholder}> — an argument value spells it`);
228
+ }
229
+
230
+ const payload = {
231
+ role,
232
+ kind,
233
+ args: Object.fromEntries(required.map((a) => [a.flag, values.get(a.placeholder)])),
234
+ sha256: createHash("sha256").update(brief).digest("hex"),
235
+ };
236
+
237
+ const member = arg("member");
238
+ if (member !== null) {
239
+ if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(member)) die(`--member ${member} is not a member name: letters, digits, '.', '_' and '-', starting alphanumeric`);
240
+ let mdPath;
241
+ try {
242
+ mdPath = fleetFile(`briefs/${member}.md`);
243
+ } catch (err) {
244
+ if (err instanceof FleetDirUnresolvable) die(`cannot place --member ${member}'s files: ${err.message}`);
245
+ throw err;
246
+ }
247
+ const jsonPath = join(dirname(mdPath), `${member}.json`);
248
+ try {
249
+ mkdirSync(dirname(mdPath), { recursive: true });
250
+ writeFileSync(mdPath, brief);
251
+ writeFileSync(jsonPath, `${JSON.stringify({ ...payload, path: mdPath }, null, 2)}\n`);
252
+ } catch (err) {
253
+ die(`cannot write --member ${member}'s files under ${dirname(mdPath)}: ${err.message}`);
254
+ }
255
+ }
256
+
257
+ writeAll(1, has("json") ? `${JSON.stringify(payload, null, 2)}\n` : brief);
@@ -22,13 +22,17 @@
22
22
  import { createHash } from "node:crypto";
23
23
 
24
24
  // How an archive beside the ledger is named. `ledger.mjs rotate` files the
25
- // ledger as `ledger.<stamp>.md` and the phase-0 receipt as `phase0.<stamp>.json`
26
- // under one stamp, and `phase0.mjs` files a receipt the rotation left behind
27
- // the same way, so the format lives here once.
25
+ // ledger as `ledger.<stamp>.md` and the two run receipts, the phase-0 one as
26
+ // `phase0.<stamp>.json` and the end-of-run one as `closeout.<stamp>.json`,
27
+ // under one stamp. `phase0.mjs` files a phase-0 receipt the rotation left
28
+ // behind the same way, so the format lives here once.
28
29
  const RECEIPT_STEM = "phase0";
29
30
  export const RECEIPT = `${RECEIPT_STEM}.json`;
30
31
  export const archiveStamp = () => new Date().toISOString().replace(/\.\d{3}Z$/, "Z").replaceAll(":", "");
31
32
  export const receiptArchiveName = (stamp) => `${RECEIPT_STEM}.${stamp}.json`;
33
+ const CLOSEOUT_STEM = "closeout";
34
+ export const CLOSEOUT_RECEIPT = `${CLOSEOUT_STEM}.json`;
35
+ export const closeoutArchiveName = (stamp) => `${CLOSEOUT_STEM}.${stamp}.json`;
32
36
 
33
37
  // The outcome vocabulary, verbatim from the spec. A word is matched exactly,
34
38
  // except the three that carry a value, which match OUTCOME_PATTERNS below.
@@ -47,7 +47,7 @@ import { fileURLToPath } from "node:url";
47
47
  import { spawnSync, execFileSync } from "node:child_process";
48
48
  import { makeDie, isFlagLike, hasEqualsForm, isDigits } from "./arg.mjs";
49
49
  import { fleetFile, FleetDirUnresolvable } from "./fleet-dir.mjs";
50
- import { parseMember, parseToken, memberTokens, nextMergeBot, nextRetry, liveOnLedger, retiredOnLedger, isRetirable, agentDefinition, CELL, tierValues, rowPr, rowWriteRefusal, isReviewToken, addedReviewToken, newSplitRow, splitRowClause, added, premisesOf, MEMBER_FAMILIES, ROWS, DISPATCHED, FILED, RULED, DRAIN, RETIRED, RECEIPT, archiveStamp, receiptArchiveName, headerRe, escapeText, unescapeText } from "./ledger-grammar.mjs";
50
+ import { parseMember, parseToken, memberTokens, nextMergeBot, nextRetry, liveOnLedger, retiredOnLedger, isRetirable, agentDefinition, CELL, tierValues, rowPr, rowWriteRefusal, isReviewToken, addedReviewToken, newSplitRow, splitRowClause, added, premisesOf, MEMBER_FAMILIES, ROWS, DISPATCHED, FILED, RULED, DRAIN, RETIRED, RECEIPT, archiveStamp, receiptArchiveName, CLOSEOUT_RECEIPT, closeoutArchiveName, headerRe, escapeText, unescapeText } from "./ledger-grammar.mjs";
51
51
  import { deriveRun, LedgerError, labelOffMember, HELD, CONFLICT_HOLD } from "./fleet-tick.mjs";
52
52
  import { stateFileIn, readState, writeState, assessBeat, stallsAt } from "./fleet-state.mjs";
53
53
  import { processSource, ancestry, controllerOf, judgeController, ProcUnreadable } from "./proc.mjs";
@@ -1446,10 +1446,10 @@ function runCheck() {
1446
1446
  // hard-linked to its stamped name, then unlinked or, when a successor is
1447
1447
  // carried, replaced by it — so its bytes are untouched, and the link refuses
1448
1448
  // atomically when that name is already taken rather than overwriting an older
1449
- // archive. A `phase0.json` receipt beside the ledger belongs to the same run,
1450
- // so it is archived as `phase0.<stamp>.json` under the ledger archive's own
1451
- // stamp — a warning-only move after the ledger move, refused up front only
1452
- // when that name is taken.
1449
+ // archive. The two receipts beside the ledger, `phase0.json` and
1450
+ // `closeout.json`, belong to the same run, so each is archived as
1451
+ // `<name>.<stamp>.json` under the ledger archive's own stamp — a warning-only
1452
+ // move after the ledger move, refused up front only when a name is taken.
1453
1453
  //
1454
1454
  // What follows depends on the verdict below. After a `dead` or `none` one
1455
1455
  // nothing is carried: the next write subcommand finds no file and starts the
@@ -1567,14 +1567,17 @@ function runRotate() {
1567
1567
  carry = carryOf(text);
1568
1568
  }
1569
1569
  const carrying = carry.rows.length > 0 || carry.dispatched.length > 0 || carry.retired.length > 0;
1570
- // The phase-0 receipt beside the ledger belongs to the run being rotated
1571
- // away, so it takes the archive's own stamp: `phase0.<stamp>.json` next to
1572
- // `ledger.<stamp>.md`. A name already taken refuses before anything moves,
1573
- // as the ledger's own does.
1570
+ // The receipts beside the ledger belong to the run being rotated away, so
1571
+ // each takes the archive's own stamp: `phase0.<stamp>.json` and
1572
+ // `closeout.<stamp>.json` next to `ledger.<stamp>.md`. A name already taken
1573
+ // refuses before anything moves, as the ledger's own does.
1574
1574
  const stamp = archiveStamp();
1575
- const receipt = join(dirname(file), RECEIPT);
1576
- const receiptArchive = existsSync(receipt) ? join(dirname(file), receiptArchiveName(stamp)) : null;
1577
- if (receiptArchive !== null && existsSync(receiptArchive)) die(`refusing to rotate ${file}: ${receiptArchive} already exists`);
1575
+ const receipts = [[RECEIPT, receiptArchiveName], [CLOSEOUT_RECEIPT, closeoutArchiveName]]
1576
+ .map(([name, archiveName]) => ({ from: join(dirname(file), name), to: join(dirname(file), archiveName(stamp)) }))
1577
+ .filter(({ from }) => existsSync(from));
1578
+ for (const { to } of receipts) {
1579
+ if (existsSync(to)) die(`refusing to rotate ${file}: ${to} already exists`);
1580
+ }
1578
1581
  let archive = null;
1579
1582
  if (exists) {
1580
1583
  archive = join(dirname(file), `${basename(file, ".md")}.${stamp}.md`);
@@ -1601,12 +1604,12 @@ function runRotate() {
1601
1604
  // After the ledger has moved, and a warning rather than a refusal: the
1602
1605
  // ledger is already archived, and a receipt left where it is is read as a
1603
1606
  // previous run's by the next phase 0, which moves it aside itself.
1604
- if (receiptArchive !== null) {
1607
+ for (const { from, to } of receipts) {
1605
1608
  try {
1606
- renameSync(receipt, receiptArchive);
1607
- console.error(` archived ${receipt} -> ${receiptArchive}`);
1609
+ renameSync(from, to);
1610
+ console.error(` archived ${from} -> ${to}`);
1608
1611
  } catch (e) {
1609
- console.error(` could not archive ${receipt} -> ${receiptArchive}: ${e.message}`);
1612
+ console.error(` could not archive ${from} -> ${to}: ${e.message}`);
1610
1613
  }
1611
1614
  }
1612
1615
  // Nothing to carry writes nothing, so the next write starts the skeleton
@@ -0,0 +1,137 @@
1
+ ---
2
+ arg worktree abs-path
3
+ arg pin your dispatch pin
4
+ arg pr M
5
+ arg testCmd testCmd
6
+ path worktree
7
+ literal args
8
+ literal cmd
9
+ literal test
10
+ ---
11
+ ## 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.
29
+
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.
135
+ ## kind: repair
136
+
137
+ 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.