@feigi/fleet-ctl 3.34.0 → 3.35.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.
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: fleet-review-runner
3
- description: A `/skill:run-team` review runner on omp — dispatched by the controller as review-pr-<pr#> with pr, branch, worktree, testCmd and scratch (the scratch root); runs runReviewOnOmp to completion in its own eval cell, writes <scratch>/pr<pr>/<run>/review.json in the review's own run root, and reports the digest, the path and the reviewed= token naming that run. Never invoked directly.
3
+ description: A `/skill:run-team` review runner on omp — dispatched by the controller as review-pr-<pr#> (the PR's first runner; a later one takes the next free letter, review-pr-<pr#>-b, -c, …) with pr, branch, worktree, testCmd and scratch (the scratch root); runs runReviewOnOmp to completion in its own eval cell, writes <scratch>/pr<pr>/<run>/review.json in the review's own run root, and reports the digest, the path and the reviewed= token naming that run. Never invoked directly.
4
4
  model: "@smol:low"
5
5
  spawns: fleet-review-snapshot, fleet-review-test-run, fleet-review-correctness, fleet-review-silent-failure, fleet-review-tests, fleet-review-comments, fleet-review-types, fleet-review-simplify, fleet-review-verifier
6
6
  ---
@@ -63,15 +63,15 @@ redid the whole snapshot/fan-out sequence from scratch.
63
63
  3. **Report what the cell returned, and nothing else.** Your final message is
64
64
  your report. Never paste, count or summarize findings yourself: they are in
65
65
  the file, for the fix-applier, and the controller reads only the digest.
66
- - `status: "completed"` → first line `review-pr-<pr>: completed <path>`,
66
+ - `status: "completed"` → first line `<your name>: completed <path>` — the
67
+ member name you were dispatched as, `review-pr-<pr>` or a later letter —
67
68
  then the returned `path`, `ledger`, `attempts`, `errors` and `digest`,
68
69
  verbatim, as JSON. `errors` is non-empty when the first attempt failed
69
70
  and the retry completed — report it anyway.
70
- - `status: "failed"` → first line `review-pr-<pr>: failed`, then both
71
- `errors` verbatim and `fallback`: the name (`review-pr-<pr>-b`) the
72
- controller gives the hand-dispatched fallback reviewer. Do not run the
73
- cell again — the one retry already happened inside it.
71
+ - `status: "failed"` → first line `<your name>: failed`, then both
72
+ `errors` verbatim. Do not run the cell again — the one retry already
73
+ happened inside it.
74
74
  - **The cell threw** (an argument refused before any review ran, the
75
75
  Resolver failing, the result file failing to write) → first line
76
- `review-pr-<pr>: failed`, then the error text verbatim. Do not run the
76
+ `<your name>: failed`, then the error text verbatim. Do not run the
77
77
  cell again.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@feigi/fleet-ctl",
3
- "version": "3.34.0",
3
+ "version": "3.35.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": {
@@ -25,8 +25,8 @@
25
25
  // fleet-tick.mjs's I/O and main() never run here, main() being guarded on
26
26
  // argv[1].
27
27
  import { assessBeat, isStalled, stallReport, NO_OWNER } from "./fleet-state.mjs";
28
- import { parseToken, rowPr, premisesOf, HALT_CAUSES } from "./ledger-grammar.mjs";
29
- import { REVIEWED, latestFinisherAttempts } from "./fleet-tick.mjs";
28
+ import { parseToken, rowPr, premisesOf, HALT_CAUSES, REVIEW, REVIEWED } from "./ledger-grammar.mjs";
29
+ import { latestFinisherAttempts } from "./fleet-tick.mjs";
30
30
 
31
31
  // A ledger row is freeform, controller-authored text. Two example shapes:
32
32
  // #<n> impl-<n>=PR#<m> → PR#<m> → MERGED 73b356de
@@ -98,10 +98,9 @@ import { REVIEWED, latestFinisherAttempts } from "./fleet-tick.mjs";
98
98
  // supply, not a claim — read through ledger-grammar.mjs's premisesOf(), the
99
99
  // reading shortlist.mjs and fleet-tick.mjs use too.
100
100
  //
101
- // Captures the matched kind, so parseRow tells a Workflow from a runner by
102
- // that capture instead of a second scan; see the review notes above for
103
- // what each kind means and how `=failed` settles it.
104
- const REVIEW = /^review=(wf|member|fallback):([^=\s]+?)(=failed)?$/;
101
+ // ledger-grammar.mjs's REVIEW captures the matched kind, so parseRow tells a
102
+ // Workflow from a runner by that capture instead of a second scan; see the
103
+ // review notes above for what each kind means and how `=failed` settles it.
105
104
 
106
105
  // Which of two well-formed impl tokens is the later attempt for THIS
107
106
  // row's ticket. A token whose number matches the row's own ticket always
@@ -184,7 +183,7 @@ export function parseRow(row) {
184
183
  }
185
184
  if (tok.startsWith("review=")) {
186
185
  review = true;
187
- const [, kind, name, failed] = REVIEW.exec(tok) ?? [];
186
+ const { kind, name, failed } = REVIEW.exec(tok)?.groups ?? {};
188
187
  if (!failed) reviewLive = true;
189
188
  if (kind === "member" || kind === "fallback") {
190
189
  if (failed) settled.add(name);
@@ -156,8 +156,8 @@ import { makeDie, defineFlags } from "./arg.mjs";
156
156
  import { isCLI } from "./is-cli.mjs";
157
157
  import { gitEnv } from "./git-env.mjs";
158
158
  import { fleetFile, FleetDirUnresolvable } from "./fleet-dir.mjs";
159
- import { parseMember, memberTokens } from "./ledger-grammar.mjs";
160
- import { deriveRun, dispositionsToken, LedgerError, rowNums } from "./fleet-tick.mjs";
159
+ import { parseMember, memberTokens, rowNums } from "./ledger-grammar.mjs";
160
+ import { deriveRun, dispositionsToken, LedgerError } from "./fleet-tick.mjs";
161
161
  import { VERDICT_SCHEMA } from "./review-core.mjs";
162
162
 
163
163
  const NAME = "dispositions-check";
@@ -61,7 +61,7 @@
61
61
  // the ledger; main() does the I/O. Split so the guard table and the reading are
62
62
  // both unit-testable without a network.
63
63
 
64
- import { parseMember, parseToken, rowPr, premisesOf } from "./ledger-grammar.mjs";
64
+ import { parseMember, parseToken, premisesOf, rowNums, REVIEW, REVIEWED } from "./ledger-grammar.mjs";
65
65
 
66
66
  // Every role's TARGET is its configured cap. Availability of work belongs in
67
67
  // the ACTION, not the target: a reviewer target that shrank to the backlog
@@ -369,13 +369,6 @@ export function actionable(rows) {
369
369
 
370
370
  export class LedgerError extends Error {}
371
371
 
372
- // `review=wf:<runId>` | `review=member:review-pr-<n>` |
373
- // `review=fallback:review-pr-<n>[-b]`, settled dead as `…=failed`; the result
374
- // is `reviewed=<head>:<survived>/<refuted>/<unverified>:<run>`, `<run>` the
375
- // name of the review's own run root under `<scratch>/pr<n>/` (`run-` and the
376
- // eight characters `mktemp` chose), where its result file `review.json` sits.
377
- const REVIEW = /^review=(?:wf|member|fallback):[^=\s]+(=failed)?$/;
378
- export const REVIEWED = /^reviewed=([0-9a-fA-F]{7,40}):(\d+)\/(\d+)\/(\d+):(run-[A-Za-z0-9]{8})$/;
379
372
  // The `reviewed=` shape before it named a run: it names no result file, so
380
373
  // nothing can tell which review a dispositions verdict answered. Only a ledger
381
374
  // written before the plugin update and read after it can hold one.
@@ -449,24 +442,6 @@ export function labelOffMember(tok) {
449
442
  return m !== null && m.family === "finisher-pr" ? m : null;
450
443
  }
451
444
 
452
- // A row's key number and its PR: the PR every PR-bound token on the row
453
- // speaks for. That PR is ledger-grammar.mjs's rowPr(): on a row carrying an
454
- // `impl-` token, its settled `impl-<N>=PR#<n>` token's PR, never a prose
455
- // `PR#` mention; on any other row, its first `PR#<n>` mention. A row with
456
- // none is keyed by the PR's own number when it is about a PR at all (a PR
457
- // this run's implementers did not open) — this is ledger.mjs's
458
- // memberRowIndex() fallback specifically, which gates on the member being
459
- // PR-bound before it ever reaches this fallback. deriveRun below applies the
460
- // same row-key fallback to every row's own bookkeeping unconditionally,
461
- // signal or not; only memberRowIndex()'s caller already knows it holds a
462
- // PR-bound member. Ticket and PR numbers share GitHub's one number
463
- // space, so a ticket's key never names an open PR.
464
- export function rowNums(text) {
465
- const key = text.split(/\s/)[0];
466
- const keyNum = /^#[0-9]+$/.test(key) ? Number(key.slice(1)) : null;
467
- return { keyNum, pr: rowPr(text) ?? keyNum };
468
- }
469
-
470
445
  // PRs whose finisher attempts are read off the ledger while the open list shows
471
446
  // no `ready-to-merge` on them — `unqueued` is the set of open PR numbers without
472
447
  // it, so the label shape stays the caller's (gh's `{name}` here, plain names in
@@ -691,8 +666,8 @@ export function deriveRun({ rows, dispatched, drain }, prs, closed = new Set(),
691
666
  if (tok.startsWith("review=")) {
692
667
  const m = REVIEW.exec(tok);
693
668
  if (!m) throw new LedgerError(`${where}: '${tok}' is not review=wf:<runId> | member:review-pr-<n> | fallback:review-pr-<n>, optionally =failed`);
694
- st.inFlight = !m[1];
695
- if (!m[1]) st.reviewedAny = true;
669
+ st.inFlight = !m.groups.failed;
670
+ if (!m.groups.failed) st.reviewedAny = true;
696
671
  } else if (tok.startsWith("reviewed=")) {
697
672
  const m = REVIEWED.exec(tok);
698
673
  if (!m && REVIEWED_RUNLESS.test(tok)) {
@@ -12,10 +12,11 @@
12
12
  // apart.
13
13
  //
14
14
  // Rows stay freeform text. Only a token whose name part is a member name is
15
- // claimed here; everything else a row carries (`class=routine`, `ports=`,
16
- // `ci=`, `held-behind:#M`, `conflict-hold:#<pr>`, the
17
- // `review=`/`reviewed=` pair, the `→ PR#M` arrow) is not a member and is left
18
- // alone.
15
+ // claimed as a member here; everything else a row carries (`class=routine`,
16
+ // `ports=`, `ci=`, `held-behind:#M`, `conflict-hold:#<pr>`, the
17
+ // `review=`/`reviewed=` pair, the `→ PR#M` arrow) is not a member. The
18
+ // review pair has a grammar of its own below, REVIEW and REVIEWED, which
19
+ // `ledger.mjs row` checks a write against before it lands.
19
20
 
20
21
  import { createHash } from "node:crypto";
21
22
 
@@ -105,6 +106,197 @@ export function rowPr(text) {
105
106
  return m ? Number(m[1]) : null;
106
107
  }
107
108
 
109
+ // A row's key number and its PR: the PR every PR-bound token on the row
110
+ // speaks for. That PR is rowPr() above: on a row carrying an `impl-` token,
111
+ // its settled `impl-<N>=PR#<n>` token's PR, never a prose `PR#` mention; on
112
+ // any other row, its first `PR#<n>` mention. A row with none is keyed by the
113
+ // PR's own number when it is about a PR at all (a PR this run's implementers
114
+ // did not open) — ledger.mjs's memberRowIndex() fallback specifically, which
115
+ // gates on the member being PR-bound before it ever reaches this fallback.
116
+ // fleet-tick.mjs's deriveRun applies the same row-key fallback to every row's
117
+ // own bookkeeping unconditionally, signal or not; only memberRowIndex()'s
118
+ // caller already knows it holds a PR-bound member. Ticket and PR numbers share
119
+ // GitHub's one number space, so a ticket's key never names an open PR.
120
+ export function rowNums(text) {
121
+ const key = text.split(/\s/)[0];
122
+ const keyNum = /^#[0-9]+$/.test(key) ? Number(key.slice(1)) : null;
123
+ return { keyNum, pr: rowPr(text) ?? keyNum };
124
+ }
125
+
126
+ // A PR's review is not a member, so it carries its own pair of row tokens.
127
+ // The launch is `review=wf:<runId>` | `review=member:<name>` |
128
+ // `review=fallback:<name>`, settled dead as `…=failed`; the capture groups are
129
+ // the kind, the runId or runner name, and the `=failed` suffix. A launch's
130
+ // identity comes out of this one regex, `=failed` aside: a workflow's is its
131
+ // runId, a runner's is its name whichever of member or fallback launched it,
132
+ // since both are the one hub member of that name. The first runner on PR <n>
133
+ // is `review-pr-<n>`, every later one the next letter the PR's rows do not
134
+ // carry yet (`-b`, `-c`, …). The
135
+ // result is `reviewed=<head>:<survived>/<refuted>/<unverified>:<run>`, `<run>`
136
+ // the name of the review's own run root under `<scratch>/pr<n>/` (`run-` and
137
+ // the eight characters `mktemp` chose), where its result file `review.json`
138
+ // sits.
139
+ export const REVIEW = /^review=(?<kind>wf|member|fallback):(?<name>[^=\s]+)(?<failed>=failed)?$/;
140
+ export const REVIEWED = /^reviewed=([0-9a-fA-F]{7,40}):(\d+)\/(\d+)\/(\d+):(run-[A-Za-z0-9]{8})$/;
141
+
142
+ // Every PR's token stream: every row that maps to it under rowNums(), in
143
+ // ledger row order, its tokens run end to end — the order fleet-tick.mjs's
144
+ // fold reads a PR's review record in. A row naming no PR and keyed by no
145
+ // number is a stream of its own, under its key.
146
+ function streams(rows) {
147
+ const out = new Map();
148
+ for (const text of rows) {
149
+ const id = rowNums(text).pr ?? text.split(/\s/)[0];
150
+ if (!out.has(id)) out.set(id, []);
151
+ out.get(id).push(...text.split(/\s+/).filter(Boolean));
152
+ }
153
+ return out;
154
+ }
155
+
156
+ const isOpen = (launch) => !launch.failed && !launch.answered;
157
+
158
+ // One stream's review record, read in order. A `reviewed=` answers the
159
+ // nearest earlier launch that is neither answered yet nor settled `=failed`;
160
+ // one with no such launch is `unpaired`. A launch is open while unanswered
161
+ // and not failed: `crowded` holds each launch that appeared while an earlier
162
+ // one was open, with that open one; `repeated` each launch whose identity an
163
+ // earlier launch already took. A token outside REVIEW/REVIEWED is
164
+ // `unparseable` and plays no part in the pairing.
165
+ function readReviews(tokens) {
166
+ const launches = [];
167
+ const out = { unpaired: [], repeated: [], crowded: [], unparseable: [] };
168
+ for (const tok of tokens) {
169
+ if (tok.startsWith("review=")) {
170
+ const m = REVIEW.exec(tok);
171
+ if (!m) {
172
+ out.unparseable.push(tok);
173
+ continue;
174
+ }
175
+ const { kind, name, failed } = m.groups;
176
+ const launch = { id: `review=${kind}:${name}`, kind, name, failed: failed !== undefined, answered: false };
177
+ launch.key = kind === "wf" ? launch.id : `runner:${name}`;
178
+ if (launches.some((l) => l.key === launch.key)) out.repeated.push(launch.id);
179
+ const open = launches.find(isOpen);
180
+ if (open) out.crowded.push({ id: launch.id, open: open.id });
181
+ launches.push(launch);
182
+ } else if (tok.startsWith("reviewed=")) {
183
+ if (!REVIEWED.test(tok)) {
184
+ out.unparseable.push(tok);
185
+ continue;
186
+ }
187
+ const answers = launches.findLast(isOpen);
188
+ if (answers) answers.answered = true;
189
+ else out.unpaired.push(tok);
190
+ }
191
+ }
192
+ out.launches = launches;
193
+ out.open = launches.filter(isOpen).map((l) => l.id);
194
+ return out;
195
+ }
196
+
197
+ // The entries of `after` that `before` does not account for, counting
198
+ // duplicates: what a write added.
199
+ function added(before, after) {
200
+ const left = new Map();
201
+ for (const x of before) left.set(x, (left.get(x) ?? 0) + 1);
202
+ return after.filter((x) => {
203
+ const n = left.get(x) ?? 0;
204
+ if (n === 0) return true;
205
+ left.set(x, n - 1);
206
+ return false;
207
+ });
208
+ }
209
+
210
+ // The runner name a new launch on PR <pr> takes: `review-pr-<pr>`, else the
211
+ // first letter from `b` that no runner launch on the PR's rows already uses —
212
+ // member or fallback, `=failed` or not. null for a stream keyed by no PR
213
+ // number, or with every letter taken.
214
+ function nextReviewer(launches, pr) {
215
+ if (typeof pr !== "number") return null;
216
+ const used = new Set(launches.filter((l) => l.kind !== "wf").map((l) => l.name));
217
+ const base = `review-pr-${pr}`;
218
+ if (!used.has(base)) return base;
219
+ for (let c = "b".charCodeAt(0); c <= "z".charCodeAt(0); c++) {
220
+ const name = `${base}-${String.fromCharCode(c)}`;
221
+ if (!used.has(name)) return name;
222
+ }
223
+ return null;
224
+ }
225
+
226
+ const OPEN_WAYS_OUT = "wait for its reviewed=, or, once Member-killed confirms its runner dead, settle it =failed in the same rewrite as the new launch";
227
+
228
+ /**
229
+ * Why `ledger.mjs row` must not write `line` over `oldLine` (null for a new
230
+ * row), `before` and `after` the ledger's rows on either side of the write —
231
+ * or null when it may. Only a violation the write ADDS is a reason: each
232
+ * rule's offending entries are listed before the write and after it, and the
233
+ * after list must hold nothing the before list lacks, duplicates counted. Where
234
+ * an entry sits plays no part, since `row` rewrites the whole line, so a bad
235
+ * token already on the ledger and carried forward or moved never blocks a
236
+ * write. Entries are token texts, except a launch's, which is its identity
237
+ * with `=failed` aside, so settling a launch in place adds nothing. The rules:
238
+ * - unique members: a member name appears at most once on the line, whatever
239
+ * its outcome;
240
+ * - unparseable review tokens: a `review=`/`reviewed=` matches REVIEW/REVIEWED;
241
+ * - paired results: every `reviewed=` answers a launch (readReviews above);
242
+ * - unique launches: a launch identity — a workflow's runId, a runner's name
243
+ * whatever its kind — appears at most once in its PR's stream;
244
+ * - one open launch per PR: no launch appears while an earlier one is open;
245
+ * - an open launch is never removed: every launch open before the write is in
246
+ * its PR's stream after it, `=failed` allowed, on any of the PR's rows.
247
+ */
248
+ export function rowWriteRefusal(before, after, oldLine, line) {
249
+ const names = (text) => (text === null ? [] : memberTokens(text).map((t) => t.name));
250
+ const dupes = (list) => list.filter((n, i) => list.indexOf(n) !== i);
251
+ const member = added(dupes(names(oldLine)), dupes(names(line)))[0];
252
+ if (member !== undefined) {
253
+ return `member '${member}' appears more than once on this line — unique members: one token per member, live or settled`;
254
+ }
255
+ const was = streams(before);
256
+ const now = streams(after);
257
+ const where = (id) => (typeof id === "number" ? `PR #${id}` : `row ${id}`);
258
+ const read = (map, id) => readReviews(map.get(id) ?? []);
259
+ for (const [id, tokens] of now) {
260
+ const a = readReviews(tokens);
261
+ const b = read(was, id);
262
+ const bad = added(b.unparseable, a.unparseable)[0];
263
+ if (bad !== undefined) {
264
+ return `'${bad}' on ${where(id)} is not review=wf:<runId> | member:<name> | fallback:<name> (optionally =failed) `
265
+ + "or reviewed=<head>:<survived>/<refuted>/<unverified>:<run> — unparseable review token";
266
+ }
267
+ const unpaired = added(b.unpaired, a.unpaired)[0];
268
+ if (unpaired !== undefined) {
269
+ return `'${unpaired}' on ${where(id)} answers no open launch — paired results: every reviewed= follows a review= `
270
+ + "launch that no earlier reviewed= answered and that is not settled =failed; write a reviewed= only off a review result file";
271
+ }
272
+ const repeated = added(b.repeated, a.repeated)[0];
273
+ if (repeated !== undefined) {
274
+ const next = nextReviewer(a.launches, id);
275
+ return `launch '${repeated}' is already on ${where(id)}'s rows — unique launches: every launch takes an identity the PR has not used`
276
+ + (next === null ? "" : `; the next free reviewer name is ${next}`);
277
+ }
278
+ const crowded = added(b.crowded.map((c) => c.id), a.crowded.map((c) => c.id))[0];
279
+ if (crowded !== undefined) {
280
+ const { open } = a.crowded.find((c) => c.id === crowded);
281
+ // The stream names the later launch as the crowded one, but the write may
282
+ // have added the earlier one — then the new launch is the offender and
283
+ // the open one is the launch the ledger already held.
284
+ const fresh = added(b.launches.map((l) => l.id), a.launches.map((l) => l.id));
285
+ const [offender, holder] = fresh.includes(open) && !fresh.includes(crowded) ? [open, crowded] : [crowded, open];
286
+ return `launch '${offender}' on ${where(id)} while launch '${holder}' is open — one open launch per PR: ${OPEN_WAYS_OUT}`;
287
+ }
288
+ }
289
+ for (const [id, tokens] of was) {
290
+ const kept = new Set(read(now, id).launches.map((l) => l.id));
291
+ const dropped = readReviews(tokens).open.find((l) => !kept.has(l));
292
+ if (dropped !== undefined) {
293
+ return `this write removes open launch '${dropped}' from ${where(id)}'s rows — an open launch is never removed, `
294
+ + `only settled =failed where it stands: ${OPEN_WAYS_OUT}`;
295
+ }
296
+ }
297
+ return null;
298
+ }
299
+
108
300
  // A ticket row is `#N <text>`; it is an Exclusion when `excluded` is the
109
301
  // text's first word — `impl-N · … excluded …` is a row about something else.
110
302
  // `#N excluded · behind-pr:#M` / `behind-issue:#M`: `#M` is an issue or PR
@@ -35,7 +35,7 @@ import { fileURLToPath } from "node:url";
35
35
  import { spawnSync, execFileSync } from "node:child_process";
36
36
  import { makeDie, isFlagLike, hasEqualsForm, isDigits } from "./arg.mjs";
37
37
  import { fleetFile, FleetDirUnresolvable } from "./fleet-dir.mjs";
38
- import { parseMember, parseToken, memberTokens, nextMergeBot, agentDefinition, CELL, tierValues, rowPr, ROWS, DISPATCHED, FILED, RULED, DRAIN, headerRe, escapeText, unescapeText } from "./ledger-grammar.mjs";
38
+ import { parseMember, parseToken, memberTokens, nextMergeBot, agentDefinition, CELL, tierValues, rowPr, rowWriteRefusal, ROWS, DISPATCHED, FILED, RULED, DRAIN, headerRe, escapeText, unescapeText } from "./ledger-grammar.mjs";
39
39
  import { deriveRun, LedgerError, labelOffMember } from "./fleet-tick.mjs";
40
40
  import { stateFileIn, readState, writeState, assessBeat, stallsAt } from "./fleet-state.mjs";
41
41
  import { isDead, processSource, ancestry, controllerOf, judgeController, ProcUnreadable } from "./proc.mjs";
@@ -808,11 +808,15 @@ if (cmd === "read") {
808
808
  }
809
809
  const i = data.rows.findIndex((r) => r.split(/\s/)[0] === key);
810
810
  const created = i === -1;
811
- if (created) {
812
- data.rows.push(line);
813
- } else {
814
- data.rows[i] = line;
815
- }
811
+ const after = created ? [...data.rows, line] : data.rows.with(i, line);
812
+ // A PR's review record is read off its rows — every row mapping to it, in
813
+ // ledger order — so a write that adds a result no launch accounts for, a
814
+ // second launch while one is open, or drops an open launch makes the tick
815
+ // re-ignite or lose a review. Refused here, before anything is written;
816
+ // what the ledger already held is carried, never re-judged. Local only.
817
+ const refusal = rowWriteRefusal(data.rows, after, created ? null : data.rows[i], line);
818
+ if (refusal !== null) die(`row ${key}: ${refusal}`);
819
+ data.rows = after;
816
820
  // Logged only after save() returns — a failed write must not claim a row
817
821
  // was recorded when it never made it to disk.
818
822
  save(data);
@@ -0,0 +1,188 @@
1
+ #!/usr/bin/env node
2
+ // The consumer-repo pre-flight: what the fleet needs from this machine and
3
+ // this repository before a run-team run may shortlist or dispatch anything.
4
+ // run-team calls it at the start of Phase 0, so the checks run without the
5
+ // maintainer copying a block by hand.
6
+ //
7
+ // THE CHECKS are the CHECKS table below, one probe per row, each run with the
8
+ // main checkout as its cwd. A row passes when its argv exits 0 and, where the
9
+ // row says `want`, its stdout carries a line equal to that string — or, for
10
+ // `want: NONEMPTY`, any non-blank line. A row marked `warn` reports a miss as a
11
+ // WARN and passes: the CI-workflow row, because a repo without a workflow
12
+ // named CI still runs, its workflow named per call (`ci-state.mjs
13
+ // --workflow`) or declared absent (`--declare-no-ci`). Every other miss is a
14
+ // FAIL. Every row runs, so one run names every failure, not the first.
15
+ //
16
+ // No row names a manifest, a lockfile or a test runner: the consumer's Install
17
+ // step and Test entrypoint come from its Recipe, and the fleet keeps no table
18
+ // of supported technologies.
19
+ //
20
+ // THE MARKER. A run where nothing FAILed writes `.fleet/preflight.json`
21
+ // (resolved through fleet-dir.mjs, so a worktree and the main checkout name
22
+ // the same file) holding a sha256 of the check set: every row's name, argv,
23
+ // `want` and `warn`. A later run whose check set hashes the same prints
24
+ // PREFLIGHT SKIPPED and runs nothing — the rows cost several `gh` calls, and
25
+ // every controller tick already spends its own share of the secondary rate
26
+ // limit. A row added, removed or changed moves the hash, so the next run
27
+ // checks again. A failed run writes no marker. A marker that cannot be read
28
+ // is treated as absent. Deleting the file makes the next run check again.
29
+ //
30
+ // CLI (no arguments):
31
+ // preflight.mjs one `ok|WARN|FAIL <name>[: why]` line per row, then
32
+ // `PREFLIGHT OK`, `PREFLIGHT SKIPPED` or
33
+ // `PREFLIGHT FAILED: <names>`.
34
+ // Exit 0 passed or skipped, 1 a row failed, 2 could not run
35
+ // (an argument given, no repository) or could not write the
36
+ // marker after every row passed, the row lines printed first.
37
+ //
38
+ // Zero deps: node builtins and sibling scripts only.
39
+
40
+ import { spawnSync } from "node:child_process";
41
+ import { createHash } from "node:crypto";
42
+ import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
43
+ import { dirname, join } from "node:path";
44
+ import { isCLI } from "./is-cli.mjs";
45
+ import { makeDie } from "./arg.mjs";
46
+ import { fleetFile } from "./fleet-dir.mjs";
47
+ import { gitEnv } from "./git-env.mjs";
48
+
49
+ export const MARKER_FILE = "preflight.json";
50
+ export const NONEMPTY = { nonEmpty: true };
51
+ const PROBE_TIMEOUT_MS = 60_000;
52
+ const NAME = "preflight";
53
+ const die = makeDie(NAME);
54
+
55
+ const label = (l) => ({ name: `label:${l}`, argv: ["gh", "label", "list", "--search", l, "--json", "name", "--jq", ".[].name"], want: l });
56
+
57
+ // A workflow file whose top-level `name:` is CI, matched the way ci-state.mjs
58
+ // reads a workflow's name: either quote style, and a trailing ` # comment` is
59
+ // not part of the name. A plain `^name: *CI *$` would WARN for a repo
60
+ // `--workflow CI` resolves without trouble.
61
+ const CI_NAMED = String.raw`grep -lE "^name:[[:space:]]*[\"']?CI[\"']?([[:space:]]+#.*)?[[:space:]]*\$" .github/workflows/*.y*ml`;
62
+
63
+ // A leading `~/` in an argv element is the user's home, expanded at run time
64
+ // and hashed as written, so the hash does not change with the box.
65
+ export const CHECKS = [
66
+ { name: "binary:node", argv: ["node", "-v"] },
67
+ { name: "binary:git", argv: ["git", "--version"] },
68
+ { name: "binary:gh", argv: ["gh", "--version"] },
69
+ { name: "binary:jq", argv: ["jq", "--version"] },
70
+ { name: "binary:python3", argv: ["python3", "--version"] },
71
+ { name: "binary:shasum", argv: ["shasum", "--version"] },
72
+ { name: "gh-auth", argv: ["gh", "auth", "status"] },
73
+ { name: "origin-remote", argv: ["git", "remote", "get-url", "origin"] },
74
+ { name: "origin-main", argv: ["git", "rev-parse", "--verify", "-q", "origin/main"] },
75
+ { name: "worktrees-ignored", argv: ["git", "check-ignore", "-q", ".worktrees/probe"] },
76
+ { name: "fleet-ignored", argv: ["git", "check-ignore", "-q", ".fleet/probe"] },
77
+ label("ready-for-agent"),
78
+ label("in-progress"),
79
+ label("ready-to-merge"),
80
+ { name: "allow-merge-commit", argv: ["gh", "api", "repos/{owner}/{repo}", "--jq", ".allow_merge_commit"], want: "true" },
81
+ { name: "ruleset", argv: ["gh", "api", "repos/{owner}/{repo}/rulesets", "--jq", ".[].name"], want: NONEMPTY },
82
+ { name: "ci-workflow", argv: ["sh", "-c", CI_NAMED], warn: true },
83
+ { name: "resolver", argv: ["~/.fleet/bin/fleet-run", "--root"] },
84
+ ];
85
+
86
+ /** sha256 over every row's name, argv, want and warn, in table order. */
87
+ export function checkSetHash(checks) {
88
+ const rows = checks.map(({ name, argv, want, warn }) => [name, argv, want, warn === true]);
89
+ return createHash("sha256").update(JSON.stringify(rows)).digest("hex");
90
+ }
91
+
92
+ const wanted = (want) => (want === NONEMPTY ? "a non-blank line" : `a line "${want}"`);
93
+
94
+ // One row: null when it passed, else why it did not.
95
+ function probe({ argv, want }, cwd, env, timeoutMs) {
96
+ const shown = argv.join(" ");
97
+ if (argv.some((a) => a.startsWith("~/")) && !env.HOME) return `${shown} did not run: HOME is not set`;
98
+ const [cmd, ...args] = argv.map((a) => (a.startsWith("~/") ? join(env.HOME, a.slice(2)) : a));
99
+ const r = spawnSync(cmd, args, { cwd, env, encoding: "utf8", timeout: timeoutMs });
100
+ // ENOENT and EACCES mean it never started; ETIMEDOUT and ENOBUFS mean it ran
101
+ // and was killed, so a hung `gh` is not reported as a missing binary.
102
+ if (r.error?.code === "ETIMEDOUT") return `${shown} timed out after ${timeoutMs}ms`;
103
+ if (r.error?.code === "ENOBUFS") return `${shown} output exceeded maxBuffer`;
104
+ if (r.error) return `${shown} did not run: ${r.error.code ?? r.error.message}`;
105
+ if (r.status !== 0) {
106
+ const last = r.stderr.trim().split("\n").at(-1);
107
+ return `${shown} ${r.signal ? `killed by ${r.signal}` : `exited ${r.status}`}${last ? `: ${last}` : ""}`;
108
+ }
109
+ if (want === undefined) return null;
110
+ const lines = r.stdout.split("\n").map((l) => l.trim());
111
+ const said = lines.filter(Boolean);
112
+ const hit = want === NONEMPTY ? said.length > 0 : lines.includes(want);
113
+ return hit ? null : `${shown} printed ${said.length ? JSON.stringify(said.join(" ")) : "nothing"}, want ${wanted(want)}`;
114
+ }
115
+
116
+ function readMarker(path) {
117
+ try {
118
+ return JSON.parse(readFileSync(path, "utf8"))?.checks;
119
+ } catch {
120
+ return null;
121
+ }
122
+ }
123
+
124
+ /**
125
+ * Run `checks` from the main checkout `cwd` belongs to, unless the marker
126
+ * records this exact check set as passed. Writes the marker when no row
127
+ * failed. Throws FleetDirUnresolvable when `cwd` is in no repository.
128
+ *
129
+ * Returns `{ skipped, marker, results: [{name, warn, ok, why}], failed,
130
+ * writeError }`; `writeError` is null, or says why the marker could not be
131
+ * written — the rows have run by then, so they come back with it.
132
+ */
133
+ export function runPreflight({ checks = CHECKS, cwd = process.cwd(), env = process.env, timeoutMs = PROBE_TIMEOUT_MS } = {}) {
134
+ const marker = fleetFile(MARKER_FILE, { cwd });
135
+ const workspace = dirname(dirname(marker));
136
+ const hash = checkSetHash(checks);
137
+ if (readMarker(marker) === hash) return { skipped: true, marker, results: [], failed: [], writeError: null };
138
+
139
+ const childEnv = gitEnv({}, env);
140
+ const results = checks.map((c) => {
141
+ const why = probe(c, workspace, childEnv, timeoutMs);
142
+ return { name: c.name, warn: c.warn === true, ok: why === null, why };
143
+ });
144
+ const failed = results.filter((r) => !r.ok && !r.warn).map((r) => r.name);
145
+ let writeError = null;
146
+ if (failed.length === 0) {
147
+ const tmp = `${marker}.${process.pid}.tmp`;
148
+ try {
149
+ mkdirSync(dirname(marker), { recursive: true });
150
+ writeFileSync(tmp, `${JSON.stringify({ checks: hash, passed: new Date().toISOString() })}\n`);
151
+ try {
152
+ renameSync(tmp, marker);
153
+ } catch (e) {
154
+ rmSync(tmp, { force: true });
155
+ throw e;
156
+ }
157
+ } catch (e) {
158
+ writeError = `cannot write ${marker}: ${e?.code ?? e?.message}`;
159
+ }
160
+ }
161
+ return { skipped: false, marker, results, failed, writeError };
162
+ }
163
+
164
+ function main() {
165
+ // No flags at all, so not defineFlags: its unknown-flag refusal lists the
166
+ // accepted flags, and this script has none to list.
167
+ if (process.argv.length > 2) die(`takes no arguments, got: ${process.argv.slice(2).join(" ")}`);
168
+ let r;
169
+ try {
170
+ r = runPreflight();
171
+ } catch (e) {
172
+ die(e.message);
173
+ }
174
+ if (r.skipped) {
175
+ console.log(`PREFLIGHT SKIPPED: this check set already passed (${r.marker}; delete it to check again)`);
176
+ return;
177
+ }
178
+ for (const x of r.results) console.log(x.ok ? `ok ${x.name}` : `${x.warn ? "WARN" : "FAIL"} ${x.name}: ${x.why}`);
179
+ if (r.failed.length) {
180
+ console.log(`PREFLIGHT FAILED: ${r.failed.join(", ")}`);
181
+ process.exitCode = 1;
182
+ return;
183
+ }
184
+ if (r.writeError) die(r.writeError);
185
+ console.log(`PREFLIGHT OK (${r.marker})`);
186
+ }
187
+
188
+ if (isCLI(import.meta.url)) main();
@@ -152,11 +152,11 @@ export async function runReviewOnOmp(args) {
152
152
  // than that names a file that is gone.
153
153
  //
154
154
  // Failure is a throw or an empty return. The holder of the review call retries
155
- // once; a second failure returns `failed` with both errors and the fallback
156
- // reviewer's name (`review-pr-<pr>-b`), and writes no file, so nothing reads a
157
- // half-review as a review. A dispatch mistake — a pr that is not a PR number, a
158
- // scratch that is not absolute (eval's cwd is the MAIN CHECKOUT, so a relative
159
- // one would put the file there), a scratch that already ends in `pr<N>`
155
+ // once; a second failure returns `failed` with both errors, and writes no
156
+ // file, so nothing reads a half-review as a review. A dispatch mistake — a pr
157
+ // that is not a PR number, a scratch that is not absolute (eval's cwd is the
158
+ // MAIN CHECKOUT, so a relative one would put the file there), a scratch that
159
+ // already ends in `pr<N>`
160
160
  // — throws before any run: it is not a review failure, and retrying or falling
161
161
  // back would only repeat it. So does a write fault other than a file already
162
162
  // at the path: the review ran, the environment could not keep it. `run` is the
@@ -236,7 +236,7 @@ export async function runReviewToFile(args, run = runReviewOnOmp) {
236
236
  digest: digestOf(result),
237
237
  };
238
238
  }
239
- return { status: "failed", errors, fallback: `review-pr-${pr}-b` };
239
+ return { status: "failed", errors };
240
240
  }
241
241
 
242
242
  // The run root a result's `snapshot` sits in — `<scratch>/pr<pr>/run-` and
@@ -288,6 +288,22 @@ phase, or in any later one, asks the maintainer which tickets to take.
288
288
  read that fails. `main-checkout.mjs --check` prints the same answer
289
289
  without a tick.
290
290
 
291
+ **Run the pre-flight, once the pin and the baseline are recorded.**
292
+ `~/.fleet/bin/fleet-run preflight.mjs` checks what this machine and this
293
+ repository must give the fleet — the binaries, `gh` auth, `origin/main`,
294
+ `.worktrees/` and `.fleet/` ignored, the three labels, merge commits on, a
295
+ ruleset, the Resolver — and prints one `ok`, `WARN` or `FAIL` line per
296
+ check, each naming its check. **Exit 1 stops the run:** no shortlist, no
297
+ dispatch. Report every `FAIL` line to the maintainer by its check's name;
298
+ the run starts again once they are fixed. Exit 2 means it could not run at
299
+ all, or every check passed and the marker could not be written, and stops
300
+ the run the same way. `WARN ci-workflow` stops nothing:
301
+ a repo with no workflow named CI still runs, its workflow named per call
302
+ with `--workflow` or declared absent with `--declare-no-ci`. A pass writes
303
+ `.fleet/preflight.json`, keyed to a hash of the check set, and every later
304
+ run prints `PREFLIGHT SKIPPED` without a single `gh` call until a check is
305
+ added or changed.
306
+
291
307
  **Check the merge gate against its spec, once the fast-forward has put the
292
308
  ratified spec in front of you.** Where the workspace checks a ruleset spec
293
309
  in, `.github/scripts/apply-ruleset.sh --check` compares it to the live gate
@@ -2114,7 +2130,12 @@ a `task` member named `review-pr-<pr#>`, agent `fleet-review-runner`, its prompt
2114
2130
  Write the `review=` token with `ledger.mjs row`, which **replaces the whole
2115
2131
  line**, so carry every other field. The tick counts in-flight reviews off the
2116
2132
  ledger and nowhere else, so a review you launched and never recorded is one it
2117
- names again.
2133
+ names again. `row` reads the PR's review record across every row that maps to
2134
+ the PR, in ledger order, and refuses a write that adds a `reviewed=` with no
2135
+ open launch before it, a launch identity the PR already used, a second launch
2136
+ while one is open, the removal of an open launch, a member name twice on the
2137
+ line, or an unparseable `review=`/`reviewed=` (the ledger's token grammar,
2138
+ below). A bad token the ledger already holds is carried, never re-judged.
2118
2139
 
2119
2140
  **It is the only path on which `selectDimensions` sizes the fan-out to the
2120
2141
  diff and the verify budget follows severity.** Hand-dispatched (the fallback
@@ -2250,12 +2271,13 @@ is a failure event, not a clean review.** The review throws on missing
2250
2271
  failure surfaces mid-loop, where "react, never block" makes it easy to log and
2251
2272
  carry on — leaving a PR that *reads* as reviewed and is not. **Retry once, then
2252
2273
  fall back — and whoever holds the review call is who retries:**
2253
- The `review-pr-<pr#>` runner already retried once inside its cell and reports `failed` with both errors; hand-dispatch the fallback reviewer below as `review-pr-<pr#>-b`, the name that report gives.
2274
+ The `review-pr-<pr#>` runner already retried once inside its cell and reports `failed` with both errors; hand-dispatch the fallback reviewer below under the next letter the PR's rows do not carry yet — `review-pr-<pr#>-b` after a first runner.
2254
2275
  Either way, settle the dead review by appending `=failed` to its `review=`
2255
- token, then append `review=fallback:review-pr-<pr#>[-b]` after it, both in one
2256
- `ledger.mjs row` rewrite — the tick takes the last `review=` token on a row as
2257
- the one in flight, so that order is what keeps the fallback counted against the
2258
- cap. A runner member that is killed rather than failed follows **Failure
2276
+ token, then append `review=fallback:<that name>` after it, both in one
2277
+ `ledger.mjs row` rewrite — `row` refuses a new launch while the dead one still
2278
+ reads open, and the tick takes the last `review=` token on a row as the one in
2279
+ flight, so that order is what keeps the fallback counted against the cap. A
2280
+ runner member that is killed rather than failed follows **Failure
2259
2281
  handling** (fresh name, inherited state stated).
2260
2282
 
2261
2283
  **Then dispatch a fix-applier** — on `DISPATCH fix-pr PR#<M>`, which the tick
@@ -3144,7 +3166,7 @@ decides the rest — two resolve automatically, every other one escalates:
3144
3166
  | Cause | Resolution |
3145
3167
  |---|---|
3146
3168
  | `live-editor` | **Automatic.** Ask the live member **by name** for its report, wait for it, then dispatch `finisher-pr-<M>-b` at the current head. If the head moved in the meantime, resolve it as `past-pin` instead. |
3147
- | `past-pin` | **Automatic, through the tick: re-review.** The head carries commits no reviewer read. The tick prints `DISPATCH review PR#<M>` for a PR whose latest finisher is `halted:past-pin` and whose latest `reviewed=<head>` is not its current head, until a review of it is running or has returned; record that review's tokens as any review's, and its result reaches a fresh finisher through the same gate. |
3169
+ | `past-pin` | **Automatic, through the tick: re-review.** The head carries commits no reviewer read. The tick prints `DISPATCH review PR#<M>` for a PR whose latest finisher is `halted:past-pin` and whose latest `reviewed=<head>` is not its current head, until a review of it is running or has returned; record that review's tokens as any review's, its runner under the next letter the PR's rows do not carry yet (`review-pr-<M>-b`, or `-c` where a fallback already took `-b`) — `row` refuses a second `review-pr-<M>` and names the free one — and its result reaches a fresh finisher through the same gate. |
3148
3170
  | `rebase` | **Escalate** — comment and flag, nothing more. Read the report's `git cherry <pin> HEAD origin/main`: only `-` lines is a clean rebase, and a `+` line is a conflict resolution that changed content or a commit past the pin. No automatic rule until a live halt shows the case recurring. |
3149
3171
  | `unreadable`, `missing`, `absent`, `other` | **Escalate** — comment and flag, no automatic retry. |
3150
3172
 
@@ -3153,7 +3175,9 @@ review has **returned**, its `reviewed=` token holds the PR out of `review-due=`
3153
3175
  and settling that review `=failed` re-queues nothing — that path covers only a
3154
3176
  review that died before returning. A head that moved past `reviewed=` with no
3155
3177
  such halt — a fix-applier's push — stays not due: duty 2 verifies what it
3156
- applied.
3178
+ applied. **A rebase never gets a `reviewed=`:** the earlier review still
3179
+ counts, because dispositions verdicts are tied to its head. Never write a
3180
+ `reviewed=` you did not read off a review result file.
3157
3181
 
3158
3182
  **Resolving a finisher that died.** A finisher settled `failed` or `killed` left
3159
3183
  its PR without `ready-to-merge`, and nothing else notices: the PR is out of the
@@ -3232,9 +3256,9 @@ preference. "Unavailable" is the review unit not being there to dispatch at
3232
3256
  all; "failed" is the failure event above, surviving its one retry. A review that
3233
3257
  is present and failing is not absent, and reading this line as absence-only
3234
3258
  leaves the likeliest failure with no sanctioned path at all. One named member
3235
- per PR — `review-pr-<pr#>`, or `review-pr-<pr#>-b` where a runner already held
3236
- that name — never its implementer, recorded as
3237
- `review=fallback:review-pr-<pr#>[-b]` on the PR's row. It runs off your turn
3259
+ per PR — `review-pr-<pr#>` while no reviewer on the PR has held that name,
3260
+ else the next letter its rows do not carry yet (`-b`, `-c`, …) — never its
3261
+ implementer, recorded as `review=fallback:<that name>` on the PR's row. It runs off your turn
3238
3262
  like the review it replaces. Give it the PR number and tell it to read
3239
3263
  `$(~/.fleet/bin/fleet-run --root)/commands/review-and-fix.md` — the resolved file
3240
3264
  path, not a slash invocation; command availability inside a member is not
@@ -3901,7 +3925,8 @@ reaches it anyway, and neither replaces the other.
3901
3925
 
3902
3926
  Settle outcome and liveness are different facts, not the same table with two
3903
3927
  spellings. Recovery is a fresh member, fresh name (`impl-<N>-b`,
3904
- `fix-pr-<M>-b`, `review-pr-<M>-b`) whose prompt states what it inherits.
3928
+ `fix-pr-<M>-b`, and for a reviewer the next letter PR M's rows do not carry
3929
+ yet) whose prompt states what it inherits.
3905
3930
 
3906
3931
  `hub cancel` leaves a peer hard-aborted and unmessageable, but a `failed` job's peer can stay `idle` and answer normally. No distinct truncated state exists.
3907
3932
 
@@ -3991,7 +4016,9 @@ any other, never a section of its own.
3991
4016
 
3992
4017
  A PR's review is not a member, so it carries its own pair of row tokens,
3993
4018
  written with `row` (**Reviewers**): `review=wf:<runId>` |
3994
- `review=member:review-pr-<n>` | `review=fallback:review-pr-<n>[-b]` at launch,
4019
+ `review=member:<name>` | `review=fallback:<name>` at launch, `<name>` being
4020
+ `review-pr-<n>` for the PR's first runner and the next letter its rows do not
4021
+ carry yet (`review-pr-<n>-b`, `-c`, …) for every later one,
3995
4022
  settled dead as `…=failed`, then `reviewed=<head>:<survived>/<refuted>/<unverified>:<run>`
3996
4023
  when the result lands, `<run>` the review's `run-XXXXXXXX` run root under
3997
4024
  `<scratch>/pr<n>/`, which holds its `review.json`. A row with `review=` and no `reviewed=` is a review in
@@ -4008,6 +4035,21 @@ finisher's miss only after the last attempt a `label-off=` names, so without
4008
4035
  it your own removal reads as one. `row` refuses a `label-off=` naming no
4009
4036
  `finisher-pr` member that `## Dispatched` or some row already carries.
4010
4037
 
4038
+ `row` holds a PR's review record to these rules, read across every row that
4039
+ maps to the PR — its settled `impl-<N>=PR#<M>` token, else its first `PR#`
4040
+ mention, else its key — in ledger order. Every `reviewed=` answers the nearest
4041
+ earlier launch that is neither answered nor `=failed`. A launch identity (a
4042
+ workflow's runId, or a runner's name whichever of member or fallback launched
4043
+ it, `=failed` aside) appears once. No launch appears
4044
+ while an earlier one is open — unanswered and not `=failed`. A launch open
4045
+ before the write is still on one of the PR's rows after it, `=failed` allowed.
4046
+ A member name appears once on the line, whatever its outcome. Every
4047
+ `review=`/`reviewed=` parses. A write that adds a violation is refused, exit 2,
4048
+ nothing written; one already on the ledger and carried forward is not. A
4049
+ second launch refused for an open one waits for that one's `reviewed=`, or —
4050
+ once the Member-killed row confirms its runner dead — settles it `=failed` in
4051
+ the same rewrite as the new launch.
4052
+
4011
4053
  Plus two append-only lists:
4012
4054
 
4013
4055
  - **filed** (`ledger.mjs filed <issue> <subject>`, checked with `ledger.mjs check
@@ -4,7 +4,7 @@ Why member name load-bearing, why every member single-use, how a member's job ou
4
4
 
5
5
  ## Every member is named
6
6
 
7
- The name is the ledger token and the hub address (`hub send <name>`, `agent://<name>`); omit it and the ledger cannot match the member. Names follow unit of work: `impl-<issue#>`, `fix-pr-<pr#>` (default path's applier), `review-pr-<pr#>` (hand-dispatch fallback's reviewer), `finisher-pr-<pr#>` (Phase 3's finisher), `merge-bot-<n>` (one merge pass; `ledger.mjs dispatch merge-bot` numbers it from the ledger's `## Dispatched` list — a per-run counter, never a PR).
7
+ The name is the ledger token and the hub address (`hub send <name>`, `agent://<name>`); omit it and the ledger cannot match the member. Names follow unit of work: `impl-<issue#>`, `fix-pr-<pr#>` (default path's applier), `review-pr-<pr#>` (the PR's first reviewer; every later one on the PR — failed-runner fallback, review-and-fix self-apply, past-pin re-review — takes the next letter its ledger rows do not carry yet, `review-pr-<pr#>-b`, `-c`, …), `finisher-pr-<pr#>` (Phase 3's finisher), `merge-bot-<n>` (one merge pass; `ledger.mjs dispatch merge-bot` numbers it from the ledger's `## Dispatched` list — a per-run counter, never a PR).
8
8
 
9
9
  ## A depth-2 member cannot dispatch further
10
10
 
@@ -58,7 +58,7 @@ A member's settle outcome and its liveness are different facts, not the same tab
58
58
 
59
59
  Two axes — job outcome (`completed`/`failed`/`cancelled`) crossed with peer liveness (`running`/`idle`/`parked`). `hub cancel` → `cancelled`, the peer hard-aborted and unmessageable, `history://` still readable. A **`failed` job's peer can stay `idle` and resumable**. No distinct truncated state exists.
60
60
 
61
- Recovery = fresh member, fresh name (`impl-<N>-b`, `fix-pr-<M>-b`, `review-pr-<M>-b`), whose prompt states what it inherits:
61
+ Recovery = fresh member, fresh name (`impl-<N>-b`, `fix-pr-<M>-b`, and for a reviewer the next letter PR M's rows do not carry yet — `review-pr-<M>-b`, or `-c` where `-b` is taken), whose prompt states what it inherits:
62
62
 
63
63
  - committed-and-pushed vs committed-only vs **uncommitted in the worktree**
64
64
  - uncommitted work exists nowhere else — no `git clean`, `git checkout .`,