@feigi/fleet-ctl 3.43.5 → 3.43.7

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.
@@ -31,8 +31,9 @@ set either,
31
31
  the backward-compat `spawns` default (`omp://task-agent-discovery.md:38-39`
32
32
  — missing `spawns` defaults to `*` only when `tools` includes `task`) never
33
33
  fired: every spawn from this agent's cell was refused, 110+ times in one
34
- session, always falling through to a hand-dispatched fallback reviewer that
35
- redid the whole snapshot/fan-out sequence from scratch.
34
+ session, and each refusal failed the review the cell was running. A failed
35
+ review is reported `failed` with both errors (step 3), and the controller
36
+ retries it under the next letter.
36
37
 
37
38
  1. **Run exactly ONE `eval` cell, language `js`, with `timeout: 0`.** A review
38
39
  runs 20–40 minutes, and `timeout: 0` means no cell deadline can end it
@@ -74,7 +74,7 @@ jq '.refuted' "$R" # refuted: your
74
74
 
75
75
  `eval` loading `scripts/review-eval.mjs` through the Resolver (`fleet-run --path review-eval.mjs`) and calling `runReviewOnOmp({pr, branch, worktree, testCmd, scratch})` is the fleet's **default** review path. Its `scratch` is the scratch root, never `<scratch>/pr<N>`: the review creates that partition itself and refuses a `scratch` already ending in one, or one that is not an absolute path.
76
76
 
77
- `$(~/.fleet/bin/fleet-run --root)/skills/run-team/SKILL.md`'s Reviewers section owns its dispatch. It cuts the snapshot, sizes the fan-out, adversarially verifies every **critical/important** finding, and has `agent()` return **into the script**, so no report can go undelivered, the failure that cost one fleet five reports on one PR and four on another. It does **not** verify the `suggestion` band — that gets 0 refuters by policy, which is why step 2 checks each in-scope one itself before applying it, and files the rest. **You cannot run it** — the one member that runs it is the `review-pr-<pr#>` runner (`agents/fleet-review-runner.agent.md`), never a reader of this file; this section is the fallback for a member dispatched without it, the `review-pr-<pr#>-b` reviewer the controller sends after a review failed twice included.
77
+ `$(~/.fleet/bin/fleet-run --root)/skills/run-team/SKILL.md`'s Reviewers section owns its dispatch. It cuts the snapshot, sizes the fan-out, adversarially verifies every **critical/important** finding, and has `agent()` return **into the script**, so no report can go undelivered, the failure that cost one fleet five reports on one PR and four on another. It does **not** verify the `suggestion` band — that gets 0 refuters by policy, which is why step 2 checks each in-scope one itself before applying it, and files the rest. **You cannot run it** — the one member that runs it is the `review-pr-<pr#>` runner (`agents/fleet-review-runner.agent.md`), never a reader of this file; this section is the fallback for a member dispatched without it.
78
78
 
79
79
  It cannot ask the user anything and cannot wait on CI — rebasing, watching checks, binding and labelling stay here.
80
80
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@feigi/fleet-ctl",
3
- "version": "3.43.5",
3
+ "version": "3.43.7",
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": {
@@ -81,9 +81,9 @@ import { latestFinisherAttempts } from "./fleet-tick.mjs";
81
81
  // human. The names are not the bare `killed` flag, which is the implementer's.
82
82
  //
83
83
  // A PR's review is not a member: `review=wf:<runId>` is a Workflow
84
- // with nobody to name, while `review=member:<name>` and
85
- // `review=fallback:<name>` name a runner member, live until the token is
86
- // settled `=failed` or a later `reviewed=` records its result.
84
+ // with nobody to name, while `review=member:<name>` names a runner member,
85
+ // live until the token is settled `=failed` or a later `reviewed=` records
86
+ // its result.
87
87
  //
88
88
  // A `review=` token puts the PR under review only while
89
89
  // it is live. A settled `review=…=failed` is a dead review and the PR is owed
@@ -136,9 +136,9 @@ export function parseRow(row) {
136
136
 
137
137
  // `live` holds live entries in row order, each one of two kinds: a
138
138
  // ledger-grammar member (`kind: "member"`, its parsed token as `token`) or
139
- // a review runner a `review=member:`/`review=fallback:` token names
140
- // (`kind: "runner"`, a name and nothing else — it is no ledger-grammar
141
- // member, so it has none of a parsed token's fields). A runner carries no
139
+ // a review runner a `review=member:` token names (`kind: "runner"`, a name
140
+ // and nothing else — it is no ledger-grammar member, so it has none of a
141
+ // parsed token's fields). A runner carries no
142
142
  // `token`, so reading a member field off one through `.token` throws
143
143
  // rather than reading `undefined`. `implOutcomes` holds each impl name's
144
144
  // latest well-formed outcome: only an impl outcome decides a card. A
@@ -185,7 +185,7 @@ export function parseRow(row) {
185
185
  review = true;
186
186
  const { kind, name, failed } = REVIEW.exec(tok)?.groups ?? {};
187
187
  if (!failed) reviewLive = true;
188
- if (kind === "member" || kind === "fallback") {
188
+ if (kind === "member") {
189
189
  if (failed) settled.add(name);
190
190
  else { live.push({ kind: "runner", name }); runners.push(name); }
191
191
  }
@@ -158,10 +158,10 @@ export function classifyRole(signals) {
158
158
  // alone resolves nothing.
159
159
  function roleFromNamePatterns(hay) {
160
160
  if (/^impl-|implement ticket/.test(hay)) return "implementer";
161
- // Both per-PR member names book as review spend: `fix-pr-<n>` is the default
162
- // path's applier, `review-pr-<n>` the hand-dispatch fallback's reviewer. Miss
163
- // one and its cache writes fall through to "other", moving the review-side
164
- // headline — the one number anyone acts on — by several points.
161
+ // Both per-PR member names book as review spend: `fix-pr-<n>` is the
162
+ // fix-applier, `review-pr-<n>` the reviewer runner. Miss one and its cache
163
+ // writes fall through to "other", moving the review-side headline — the one
164
+ // number anyone acts on — by several points.
165
165
  //
166
166
  // `resolve-pr-<n>` joins the same bucket: it is a controller
167
167
  // dispatch against an ALREADY-OPEN PR, not new ticket work — measured
@@ -684,7 +684,7 @@ export function deriveRun({ rows, dispatched, drain }, prs, closed = new Set(),
684
684
  }
685
685
  if (tok.startsWith("review=")) {
686
686
  const m = REVIEW.exec(tok);
687
- if (!m) throw new LedgerError(`${where}: '${tok}' is not review=wf:<runId> | member:review-pr-<n> | fallback:review-pr-<n>, optionally =failed`);
687
+ if (!m) throw new LedgerError(`${where}: '${tok}' is not review=wf:<runId> | member:review-pr-<n>, optionally =failed`);
688
688
  st.inFlight = !m.groups.failed;
689
689
  if (!m.groups.failed) st.reviewedAny = true;
690
690
  } else if (tok.startsWith("reviewed=")) {
@@ -125,19 +125,18 @@ export function rowNums(text) {
125
125
  }
126
126
 
127
127
  // A PR's review is not a member, so it carries its own pair of row tokens.
128
- // The launch is `review=wf:<runId>` | `review=member:<name>` |
129
- // `review=fallback:<name>`, settled dead as `…=failed`; the capture groups are
130
- // the kind, the runId or runner name, and the `=failed` suffix. A launch's
131
- // identity comes out of this one regex, `=failed` aside: a workflow's is its
132
- // runId, a runner's is its name whichever of member or fallback launched it,
133
- // since both are the one hub member of that name. The first runner on PR <n>
134
- // is `review-pr-<n>`, every later one the next letter the PR's rows do not
135
- // carry yet (`-b`, `-c`, …). The
128
+ // The launch is `review=wf:<runId>` | `review=member:<name>`, settled dead as
129
+ // `…=failed`; the capture groups are the kind, the runId or runner name, and
130
+ // the `=failed` suffix. A launch's identity comes out of this one regex,
131
+ // `=failed` aside: a workflow's is its runId, a runner's is its name, the one
132
+ // hub member of that name. The first runner on PR <n> is `review-pr-<n>`,
133
+ // every later one the next letter the PR's rows do not carry yet (`-b`, `-c`,
134
+ // …). The
136
135
  // result is `reviewed=<head>:<survived>/<refuted>/<unverified>:<run>`, `<run>`
137
136
  // the name of the review's own run root under `<scratch>/pr<n>/` (`run-` and
138
137
  // the eight characters `mktemp` chose), where its result file `review.json`
139
138
  // sits.
140
- export const REVIEW = /^review=(?<kind>wf|member|fallback):(?<name>[^=\s]+)(?<failed>=failed)?$/;
139
+ export const REVIEW = /^review=(?<kind>wf|member):(?<name>[^=\s]+)(?<failed>=failed)?$/;
141
140
  export const REVIEWED = /^reviewed=([0-9a-fA-F]{7,40}):(\d+)\/(\d+)\/(\d+):(run-[A-Za-z0-9]{8})$/;
142
141
 
143
142
  // The stream a row belongs to: its PR, else its key.
@@ -178,8 +177,7 @@ function readReviews(tokens) {
178
177
  }
179
178
  const { kind, name, failed } = m.groups;
180
179
  const launch = { id: `review=${kind}:${name}`, kind, name, failed: failed !== undefined, answered: false };
181
- launch.key = kind === "wf" ? launch.id : `runner:${name}`;
182
- if (launches.some((l) => l.key === launch.key)) out.repeated.push(launch.id);
180
+ if (launches.some((l) => l.id === launch.id)) out.repeated.push(launch.id);
183
181
  const open = launches.find(isOpen);
184
182
  if (open) out.crowded.push({ id: launch.id, open: open.id });
185
183
  launches.push(launch);
@@ -213,9 +211,9 @@ function added(before, after) {
213
211
 
214
212
  // The runner name a new launch on PR <pr> takes: `review-pr-<pr>`, else the
215
213
  // first letter from `b` that no runner launch on the PR's rows already uses —
216
- // member or fallback, `=failed` or not — and no name in `retired` holds, the
217
- // names an earlier run of this omp session launched. null for a stream keyed
218
- // by no PR number, or with every letter taken.
214
+ // `=failed` or not — and no name in `retired` holds, the names an earlier run
215
+ // of this omp session launched. null for a stream keyed by no PR number, or
216
+ // with every letter taken.
219
217
  function nextReviewer(launches, pr, retired) {
220
218
  if (typeof pr !== "number") return null;
221
219
  const used = new Set([...launches.filter((l) => l.kind !== "wf").map((l) => l.name), ...retired]);
@@ -293,8 +291,8 @@ export function splitRowClause({ pr, row }) {
293
291
  * its outcome;
294
292
  * - unparseable review tokens: a `review=`/`reviewed=` matches REVIEW/REVIEWED;
295
293
  * - paired results: every `reviewed=` answers a launch (readReviews above);
296
- * - unique launches: a launch identity — a workflow's runId, a runner's name
297
- * whatever its kind — appears at most once in its PR's stream;
294
+ * - unique launches: a launch identity — a workflow's runId, a runner's name —
295
+ * appears at most once in its PR's stream;
298
296
  * - unretired runners: no launch takes a runner name `retired` holds, which an
299
297
  * earlier run of this omp session launched;
300
298
  * - one open launch per PR: no launch appears while an earlier one is open;
@@ -317,7 +315,7 @@ export function rowWriteRefusal(before, after, oldLine, line, retired = []) {
317
315
  const b = read(was, id);
318
316
  const bad = added(b.unparseable, a.unparseable)[0];
319
317
  if (bad !== undefined) {
320
- return `'${bad}' on ${where(id)} is not review=wf:<runId> | member:<name> | fallback:<name> (optionally =failed) `
318
+ return `'${bad}' on ${where(id)} is not review=wf:<runId> | member:<name> (optionally =failed) `
321
319
  + "or reviewed=<head>:<survived>/<refuted>/<unverified>:<run> — unparseable review token";
322
320
  }
323
321
  const unpaired = added(b.unpaired, a.unpaired)[0];
@@ -331,7 +329,7 @@ export function rowWriteRefusal(before, after, oldLine, line, retired = []) {
331
329
  return `launch '${repeated}' is already on ${where(id)}'s rows — unique launches: every launch takes an identity the PR has not used`
332
330
  + (next === null ? "" : `; the next free reviewer name is ${next}`);
333
331
  }
334
- const reused = a.launches.find((l) => l.kind !== "wf" && retired.includes(l.name) && !b.launches.some((o) => o.key === l.key));
332
+ const reused = a.launches.find((l) => l.kind !== "wf" && retired.includes(l.name) && !b.launches.some((o) => o.id === l.id));
335
333
  if (reused !== undefined) {
336
334
  const next = nextReviewer(a.launches, id, retired);
337
335
  return `launch '${reused.id}' on ${where(id)} names a runner an earlier run of this session already used — unretired runners: omp would answer it with \`${reused.name}-2\``
@@ -445,9 +443,9 @@ export const REVIEWER = /^review-pr-([1-9][0-9]*)(-[b-z])?$/;
445
443
  * reviewer's, bare. */
446
444
  export const isRetirable = (name) => parseMember(name) !== null || REVIEWER.test(name);
447
445
 
448
- // The reviewer runner names a row's `review=member:<name>` and
449
- // `review=fallback:<name>` launches took, `=failed` or answered or open. A
450
- // workflow launch is named by its runId, which no hub member holds.
446
+ // The reviewer runner names a row's `review=member:<name>` launches took,
447
+ // `=failed` or answered or open. A workflow launch is named by its runId,
448
+ // which no hub member holds.
451
449
  function launchedRunners(text) {
452
450
  const out = [];
453
451
  for (const word of text.split(/\s+/)) {
@@ -700,10 +700,11 @@ export function digestOf(result) {
700
700
 
701
701
  // The digits refusal review-eval.mjs's `runReviewToFile` runs before
702
702
  // its first attempt, so a dispatch mistake is refused once instead of being
703
- // retried and sent to the fallback reviewer. It lives here, not there, because
704
- // review-eval.mjs is a library and arg.mjs's `scripts/*.mjs` importers are its
705
- // CLI roster, each one probed to refuse a stray flag; this module already
706
- // consumes the digits rule on the review path. Null when `pr` is a PR number.
703
+ // retried and re-launched under the next runner name. It lives here, not
704
+ // there, because review-eval.mjs is a library and arg.mjs's `scripts/*.mjs`
705
+ // importers are its CLI roster, each one probed to refuse a stray flag; this
706
+ // module already consumes the digits rule on the review path. Null when `pr`
707
+ // is a PR number.
707
708
  export function runnerPrRefusal(pr) {
708
709
  return isDigits(pr) ? null : `args.pr must be a PR number, got ${JSON.stringify(pr)}`;
709
710
  }
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "window_start": null,
3
- "fitted_through": null,
3
+ "fitted_commit": null,
4
4
  "n_rows": 0,
5
5
  "stage": 1,
6
6
  "cells": [
@@ -15,24 +15,32 @@
15
15
  // file degrades the line, never the exit. Exit 2 only on a usage error or
16
16
  // an unreadable/invalid table: the caller does not dispatch then.
17
17
  // fit --table <json> --features <tsv> --members <tsv> --verdicts <tsv>
18
- // --guard <cost-guard.json> [--due]
19
- // Re-fits the table from the three TSVs and the guard and rewrites
20
- // `--table`. With `--due`, writes nothing and prints `DUE=yes|no
21
- // MERGED=<n>/<N>`: whether N merged PRs have landed since
22
- // `fitted_through`.
18
+ // --guard <cost-guard.json> --commit <rev> [--due]
19
+ // Re-fits the table from the three TSVs as committed at `--commit` (read
20
+ // with `git show`, never from the working tree) and the guard, and
21
+ // rewrites `--table`, recording the commit's sha as `fitted_commit`. The
22
+ // TSV flags name paths inside the repository that holds them. With
23
+ // `--due`, writes nothing and prints `DUE=yes|no MERGED=<n>/<N>`: whether
24
+ // N merged PRs have landed since `fitted_commit`, counting the features
25
+ // rows at `--commit` that the fitted commit's features file does not hold.
23
26
  // --check --table <json> --features <tsv> --members <tsv> --verdicts <tsv>
24
- // Re-fits from the rows the table was fitted through, against the guard
25
- // snapshot the table itself records, and exits 1 when the result is not
26
- // the table: the table is a code carrier, never hand-edited.
27
+ // Re-fits from the commit the table records as `fitted_commit` (an empty
28
+ // corpus while it is null), against the guard snapshot the table itself
29
+ // records, and exits 1 when the result is not the table: the table is a
30
+ // code carrier, never hand-edited. A `fitted_commit` this repository does
31
+ // not hold exits 2 naming the `git fetch` that brings it.
27
32
  //
28
33
  // The script never touches the network: the issue, the sizing verdict and
29
- // the guard are files the caller wrote.
34
+ // the guard are files the caller wrote, and a fitted commit is fetched by the
35
+ // caller.
30
36
 
31
37
  import { readFileSync, writeFileSync, renameSync, existsSync, appendFileSync, mkdirSync } from "node:fs";
32
- import { basename, dirname, join } from "node:path";
38
+ import { spawnSync } from "node:child_process";
39
+ import { basename, dirname, join, resolve } from "node:path";
33
40
  import { fileURLToPath } from "node:url";
34
41
  import { isDeepStrictEqual } from "node:util";
35
42
  import { isCLI } from "./is-cli.mjs";
43
+ import { gitEnv } from "./git-env.mjs";
36
44
  import { makeDie, defineFlags } from "./arg.mjs";
37
45
  import { CELL, POLICY_CELL, drawCell, parseMember } from "./ledger-grammar.mjs";
38
46
  import { parseTsv as parseMemberTsv } from "./member-outcomes.mjs";
@@ -306,40 +314,33 @@ function datedRows(features) {
306
314
  }
307
315
 
308
316
  /**
309
- * Per-ticket input rows: the ticket's features rows inside [window, cutoff],
317
+ * Per-ticket input rows: the ticket's features rows inside the window,
310
318
  * attributed to its LAST row's (in file order) cell and stratum, restricted to rows the
311
319
  * free classifier routed plus exploration rows — a row a live B classifier
312
320
  * routed is the A/B's test set, not the fit's. Its verdict rules its last
313
321
  * input row. A row with a blank `run_date` (route writes one for a session id
314
- * with no date) is no input row: it cannot be placed against the window, the
315
- * cut or its ruling, and a window bound drops it anyway. A `run_date` that is
322
+ * with no date) is no input row: it cannot be placed against the window or
323
+ * its ruling, and a window bound drops it anyway. A `run_date` that is
316
324
  * neither blank nor YYYY-MM-DD is refused (see `datedRows`).
317
- * A fit over everything cuts at its latest features row's date;
318
- * the verdict and member rows are cut at that same date, so `--check`'s
319
- * re-fit at the recorded `fitted_through` reads the rows the fit read and a
320
- * verdict or member row that lands later waits for the next fit instead of
321
- * failing CI.
325
+ * A fit reads everything in the commit it is given: no row is cut by date,
326
+ * because `--check` re-reads that same commit rather than re-cutting the
327
+ * working tree's files.
322
328
  */
323
- function fitTickets({ features, members, verdicts, window, cutoff }) {
324
- const inRange = datedRows(features).filter((r) => (!window || r.run_date >= window)
325
- && (cutoff === undefined || (cutoff !== null && r.run_date <= cutoff)));
326
- const through = cutoff === undefined ? inRange.map((r) => r.run_date).sort().at(-1) ?? null : cutoff;
327
- const upToThrough = (r) => through === null || !r.run_date || r.run_date <= through;
328
- members = members.filter(upToThrough);
329
+ function fitTickets({ features, members, verdicts, window }) {
330
+ const inRange = datedRows(features).filter((r) => !window || r.run_date >= window);
329
331
  const byTicket = new Map();
330
332
  for (const r of inRange) {
331
333
  if (!byTicket.has(r.ticket)) byTicket.set(r.ticket, []);
332
334
  byTicket.get(r.ticket).push(r);
333
335
  }
334
- // A ruling whose date is not YYYY-MM-DD cannot be placed against the cut, and
335
- // a string `<=` would drop 'abc' or '2027' unseen: it is left in, so `rulingFor`
336
- // refuses it when its ticket is an input ticket. An input ticket is one the
337
- // fit reads — its last in-range row is an exploration row or has `sizing_src`
338
- // `rule`, which the skip below keeps — not every ticket with an in-range
339
- // features row. `fit --due` also refuses for a ticket the skip drops:
340
- // `mergedSince` calls `verdictOf` on every ticket with an in-window row dated
341
- // after `fitted_through`, with no such skip.
342
- const rulings = rulingsByTicket(verdicts.filter((r) => !DATE.test(r.run_date) || upToThrough(r)));
336
+ // `rulingFor` refuses a ruling whose date is not YYYY-MM-DD when its ticket
337
+ // is an input ticket. An input ticket is one the fit reads — its last
338
+ // in-window row is an exploration row or has `sizing_src` `rule`, which the
339
+ // skip below keeps — not every ticket with an in-window features row.
340
+ // `fit --due` also refuses for a ticket the skip drops: `mergedSince` calls
341
+ // `verdictOf` on every ticket with an in-window row the fitted commit does
342
+ // not hold, with no such skip.
343
+ const rulings = rulingsByTicket(verdicts);
343
344
  const lastPulls = lastPullByTicket(inRange);
344
345
  const out = [];
345
346
  for (const [ticket, rows] of byTicket) {
@@ -367,7 +368,7 @@ function fitTickets({ features, members, verdicts, window, cutoff }) {
367
368
  for (const r of rows) if (r.router_usd !== "") cost += Number(r.router_usd) || 0;
368
369
  out.push({ ticket, cell: last.chosen_cell, stratum: ruleStratum(last), verdict, cost, costKnown, fixRounds });
369
370
  }
370
- return { tickets: out, used: inRange };
371
+ return out;
371
372
  }
372
373
 
373
374
  function estimate(tickets) {
@@ -423,13 +424,12 @@ function adopt(est, cells, tripped) {
423
424
 
424
425
  /**
425
426
  * The re-fit table. `guard` is `{ tripped, n, window_start }` (readGuard's
426
- * shape); `cutoff` limits every input to rows with `run_date <= cutoff`
427
- * (--check), or is undefined for a fit over everything, which cuts at its
428
- * latest features row's date.
427
+ * shape); `commit` is the sha of the commit the inputs were read from, or null
428
+ * for the empty corpus before any fit.
429
429
  */
430
- export function fitTable({ prior, features, members, verdicts, guard, cutoff }) {
430
+ export function fitTable({ prior, features, members, verdicts, guard, commit = null }) {
431
431
  const window = guard.window_start ?? prior.window_start ?? null;
432
- const { tickets, used } = fitTickets({ features, members, verdicts, window, cutoff });
432
+ const tickets = fitTickets({ features, members, verdicts, window });
433
433
  const estimates = estimate(tickets);
434
434
  const tripped = new Set(guard.tripped);
435
435
 
@@ -447,10 +447,9 @@ export function fitTable({ prior, features, members, verdicts, guard, cutoff })
447
447
  if (!cells.includes(cell) && cells.includes(survives) && !tripped.has(survives)) cells.push(cell);
448
448
  }
449
449
  }
450
- const dates = used.map((r) => r.run_date).sort();
451
450
  return {
452
451
  window_start: window,
453
- fitted_through: dates.length ? dates[dates.length - 1] : prior.fitted_through ?? null,
452
+ fitted_commit: commit,
454
453
  n_rows: tickets.length,
455
454
  stage,
456
455
  cells,
@@ -462,13 +461,53 @@ export function fitTable({ prior, features, members, verdicts, guard, cutoff })
462
461
  };
463
462
  }
464
463
 
465
- /** Merged PRs (tickets with a verdict on their last such row in file order) among the YYYY-MM-DD-dated features rows dated after `fitted_through`. */
466
- export function mergedSince({ table, features, verdicts }) {
464
+ /**
465
+ * Merged PRs (tickets with a verdict on their last such row in file order)
466
+ * among the YYYY-MM-DD-dated features rows on or after `window_start` that the
467
+ * fitted commit's features file (`fitted`, parsed rows; empty before any fit)
468
+ * does not hold, matched by `session` and `agent`.
469
+ */
470
+ export function mergedSince({ table, features, verdicts, fitted }) {
467
471
  const rulings = rulingsByTicket(verdicts);
468
- const after = datedRows(features).filter((r) => (!table.window_start || r.run_date >= table.window_start) && (!table.fitted_through || r.run_date > table.fitted_through));
472
+ const read = new Set(fitted.map((r) => `${r.session}\0${r.agent}`));
473
+ const after = datedRows(features).filter((r) => (!table.window_start || r.run_date >= table.window_start) && !read.has(`${r.session}\0${r.agent}`));
469
474
  return [...lastPullByTicket(after)].filter(([ticket, p]) => verdictOf(rulings, ticket, p.run_date)).length;
470
475
  }
471
476
 
477
+ // ---------------------------------------------------------------------------
478
+ // the commit a fit reads
479
+ // ---------------------------------------------------------------------------
480
+
481
+ const SHA = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
482
+
483
+ // `git` run in the directory holding `path`, so `path` names a file of the
484
+ // repository around it whichever directory the caller is in.
485
+ function gitBeside(path, args) {
486
+ const r = spawnSync("git", ["-C", dirname(resolve(path)), ...args], { encoding: "utf8", env: gitEnv(), maxBuffer: 1 << 30 });
487
+ if (r.error) throw r.error;
488
+ return r;
489
+ }
490
+
491
+ /**
492
+ * The full sha `rev` names as a commit in the repository holding `path`, or null when it names none there.
493
+ * Throws when git itself fails (not a repository, unreadable config, no git): that is not an answer about `rev`.
494
+ */
495
+ export function resolveCommit(path, rev) {
496
+ if (rev.startsWith("-")) return null;
497
+ const r = gitBeside(path, ["rev-parse", "--verify", "--quiet", `${rev}^{commit}`]);
498
+ if (r.status === 0) return r.stdout.trim();
499
+ // `--verify --quiet` exits 1, silently, for a rev that names no commit; any other status is git failing.
500
+ if (r.status === 1) return null;
501
+ throw new Error(r.stderr.trim() || `git rev-parse exited ${r.status}`);
502
+ }
503
+
504
+ /** `path` as committed at `sha`; throws when the commit does not hold it. */
505
+ export function showAt(sha, path) {
506
+ const r = gitBeside(path, ["show", `${sha}:./${basename(path)}`]);
507
+ if (r.status !== 0) throw new Error(r.stderr.trim() || `git show exited ${r.status}`);
508
+ return r.stdout;
509
+ }
510
+
472
511
  // ---------------------------------------------------------------------------
473
512
  // CLI
474
513
  // ---------------------------------------------------------------------------
@@ -479,7 +518,7 @@ function main() {
479
518
  flags: {
480
519
  session: "value", ticket: "value", arm: "value", "impl-row": "value", issue: "value",
481
520
  sizing: "value", guard: "value", table: "value", pending: "value", "chain-head": "bool",
482
- features: "value", members: "value", verdicts: "value", check: "bool", due: "bool",
521
+ features: "value", members: "value", verdicts: "value", commit: "value", check: "bool", due: "bool",
483
522
  },
484
523
  positionals: ["route", "fit"],
485
524
  });
@@ -492,7 +531,7 @@ function main() {
492
531
  }
493
532
  const allowed = {
494
533
  route: ["session", "ticket", "arm", "impl-row", "issue", "sizing", "guard", "table", "pending", "chain-head"],
495
- fit: ["table", "features", "members", "verdicts", "guard", "due"],
534
+ fit: ["table", "features", "members", "verdicts", "guard", "commit", "due"],
496
535
  check: ["check", "table", "features", "members", "verdicts"],
497
536
  }[mode];
498
537
  const given = argv.filter((a) => a.startsWith("--")).map((a) => a.slice(2).split("=")[0]);
@@ -533,24 +572,45 @@ function main() {
533
572
  return;
534
573
  }
535
574
 
536
- const read = (flag, parse) => {
575
+ const short = (sha) => (sha === null ? "no commit" : sha.slice(0, 8));
576
+ const fileAt = (sha, flag, parse) => {
537
577
  const p = need(flag);
538
- try { return parse(readFileSync(p, "utf8")); } catch (e) { die(`cannot read --${flag} ${p}: ${e.message}`); }
578
+ try { return parse(showAt(sha, p)); } catch (e) { die(`cannot read --${flag} ${p} at commit ${short(sha)}: ${e.message}`); }
579
+ };
580
+ // The three TSVs as committed at `sha`, never the working tree's copies.
581
+ const corpusAt = (sha) => ({
582
+ features: fileAt(sha, "features", parseFeatures),
583
+ members: fileAt(sha, "members", parseMemberTsv),
584
+ verdicts: fileAt(sha, "verdicts", parseTierOutcomes),
585
+ });
586
+ // The commit `rev` names in the repository holding --features, or null; git itself failing is a die, not "no such commit".
587
+ const commitOf = (rev) => {
588
+ try { return resolveCommit(need("features"), rev); } catch (e) { die(`cannot resolve ${rev} in the repository holding --features ${need("features")}: ${e.message}`); }
589
+ };
590
+ // The commit the table records: null before any fit, else a sha this repository holds.
591
+ const fittedCommit = () => {
592
+ const sha = table.fitted_commit;
593
+ if (sha === null) return null;
594
+ if (typeof sha !== "string" || !SHA.test(sha)) die(`${tablePath}: \`fitted_commit\` is not null or a full commit sha`);
595
+ if (commitOf(sha) === null) {
596
+ die(`${tablePath} was fitted from commit ${sha}, which this repository does not hold — run \`git fetch --depth=1 origin ${sha}\``);
597
+ }
598
+ return sha;
539
599
  };
540
- const features = read("features", parseFeatures);
541
- const members = read("members", parseMemberTsv);
542
- const verdicts = read("verdicts", parseTierOutcomes);
543
600
  // The join throws on a features row it cannot place and on a ruling of an input ticket it cannot place.
544
- // For `fit` and `--check` an input ticket is one `fitTickets` reads (its last in-range row is an
545
- // exploration row or has `sizing_src` `rule`), not every ticket with an in-range features row. `fit --due` also
601
+ // For `fit` and `--check` an input ticket is one `fitTickets` reads (its last in-window row is an
602
+ // exploration row or has `sizing_src` `rule`), not every ticket with an in-window features row. `fit --due` also
546
603
  // covers a ticket `fitTickets` skips, because `mergedSince` calls `verdictOf` on every ticket with an in-window
547
- // row dated after `fitted_through`, with no such skip.
604
+ // row the fitted commit does not hold, with no such skip.
548
605
  const joined = (fit) => {
549
606
  try { return fit(); } catch (e) { die(`cannot join --features ${need("features")} with --verdicts ${need("verdicts")}: ${e.message}`); }
550
607
  };
551
608
 
552
609
  if (mode === "check") {
553
- const refit = joined(() => fitTable({ prior: table, features, members, verdicts, guard: { ...table.guard, window_start: table.window_start }, cutoff: table.fitted_through }));
610
+ for (const flag of ["features", "members", "verdicts"]) need(flag);
611
+ const fitted = fittedCommit();
612
+ const { features, members, verdicts } = fitted === null ? { features: [], members: [], verdicts: [] } : corpusAt(fitted);
613
+ const refit = joined(() => fitTable({ prior: table, features, members, verdicts, guard: { ...table.guard, window_start: table.window_start }, commit: fitted }));
554
614
  const differ = Object.keys({ ...refit, ...table }).filter((k) => !isDeepStrictEqual(refit[k], table[k]));
555
615
  if (differ.length) {
556
616
  process.stderr.write(`${NAME}: ${tablePath} is not a re-fit of its own rows — differs in ${differ.map((k) => `\`${k}\``).join(", ")}; re-fitted:\n${JSON.stringify(refit, null, 2)}\n`);
@@ -558,22 +618,28 @@ function main() {
558
618
  process.exitCode = 1;
559
619
  return;
560
620
  }
561
- process.stdout.write(`${NAME}: ${tablePath} matches a re-fit of ${refit.n_rows} tickets through ${refit.fitted_through ?? "no rows"}\n`);
621
+ process.stdout.write(`${NAME}: ${tablePath} matches a re-fit of ${refit.n_rows} tickets at ${short(fitted)}\n`);
562
622
  return;
563
623
  }
564
624
 
625
+ const commitArg = need("commit");
626
+ const sha = commitOf(commitArg);
627
+ if (sha === null) die(`--commit ${commitArg} is not a commit of the repository holding --features ${need("features")}`);
628
+ const { features, members, verdicts } = corpusAt(sha);
565
629
  const guardPath = need("guard");
566
630
  const guard = readGuard(readJson(guardPath));
567
631
  if (guard === null) die(`cannot read --guard ${guardPath} as a cost guard — the fit needs its tripped cells and per-cell n`);
568
632
  if (F.has("due")) {
569
- const n = joined(() => mergedSince({ table, features, verdicts }));
633
+ const fitted = fittedCommit();
634
+ const read = fitted === null ? [] : fileAt(fitted, "features", parseFeatures);
635
+ const n = joined(() => mergedSince({ table, features, verdicts, fitted: read }));
570
636
  process.stdout.write(`DUE=${n >= FIT_EVERY_MERGED ? "yes" : "no"} MERGED=${n}/${FIT_EVERY_MERGED}\n`);
571
637
  return;
572
638
  }
573
- const next = joined(() => fitTable({ prior: table, features, members, verdicts, guard }));
639
+ const next = joined(() => fitTable({ prior: table, features, members, verdicts, guard, commit: sha }));
574
640
  writeFileSync(`${tablePath}.tmp`, `${JSON.stringify(next, null, 2)}\n`);
575
641
  renameSync(`${tablePath}.tmp`, tablePath);
576
- process.stdout.write(`${NAME}: fitted ${next.n_rows} tickets through ${next.fitted_through ?? "no rows"}; rows ${JSON.stringify(next.rows)}; burn_in ${next.burn_in}; stage ${next.stage}\n`);
642
+ process.stdout.write(`${NAME}: fitted ${next.n_rows} tickets at ${short(sha)}; rows ${JSON.stringify(next.rows)}; burn_in ${next.burn_in}; stage ${next.stage}\n`);
577
643
  }
578
644
 
579
645
  if (isCLI(import.meta.url)) main();
@@ -75,8 +75,7 @@ references/member-lifecycle.md.
75
75
 
76
76
  **A depth-2 member cannot dispatch further** (`task.maxRecursionDepth: 2`):
77
77
  if `task` is absent at your depth, ask the controller to dispatch the
78
- specialists and relay their reports. Say so in a fallback reviewer's prompt,
79
- or it silently downgrades to a solo review. See references/member-lifecycle.md.
78
+ specialists and relay their reports. See references/member-lifecycle.md.
80
79
 
81
80
  **Fresh context per member.** One member, one unit of work, gone. Never
82
81
  re-task a finished member — waking it drags the old ticket back in. Refill =
@@ -591,7 +590,7 @@ phase, or in any later one, asks the maintainer which tickets to take.
591
590
  settled `=failed` where it stands: a `ledger.mjs review <pr>
592
591
  review=member:<name>=failed` call that turns `review=member:<name>` on
593
592
  the PR's row into `review=member:<name>=failed`
594
- (`fallback:` and `wf:` launches alike), after which the tick owes the PR
593
+ (`wf:` launches alike), after which the tick owes the PR
595
594
  a review again under the next free reviewer name.
596
595
  - `prior: none` — no record proves the previous run dead (no record yet, or
597
596
  no `omp` process found above the rotation): every claim is `report`, and
@@ -2345,10 +2344,8 @@ write that adds a review token (one the row holds is carried), drops an open
2345
2344
  launch, names a member twice on the line, or makes a PR map to a second row. A
2346
2345
  bad token the ledger already holds is carried, never re-judged.
2347
2346
 
2348
- **It is the only path on which `selectDimensions` sizes the fan-out to the
2349
- diff and the verify budget follows severity.** Hand-dispatched (the fallback
2350
- below), neither executes at all: sizing falls back to a reviewer's own
2351
- judgement and nothing budgets the adversarial pass. It cuts one immutable
2347
+ **`selectDimensions` sizes the fan-out to the diff and the verify budget
2348
+ follows severity.** It cuts one immutable
2352
2349
  snapshot, verifies every critical/important finding adversarially,
2353
2350
  re-dispatches each crashed specialist and each crashed refuter pair once before
2354
2351
  it assembles the result, and has `agent()` return **into the script**, so no
@@ -2455,8 +2452,7 @@ in `dimensionsRun` and NOT in `dimensionsUnrun` ran a suite; every
2455
2452
  `dimensionsUnrun` entry is `{dimension, reason}` naming which failure it was.
2456
2453
  The review already re-dispatched each crashed specialist once, so what
2457
2454
  `dimensionsUnrun` still names is residue: the fix-applier names it unrun in its
2458
- report and re-runs nothing — an absence of findings is not coverage. Same rule
2459
- the fallback below states for a killed specialist, for the same reason.
2455
+ report and re-runs nothing — an absence of findings is not coverage.
2460
2456
 
2461
2457
  The rule this replaces — treat any dimension with nothing in
2462
2458
  `survived`/`refuted`/`unverified` as unrun — was the workaround for having no
@@ -2477,15 +2473,18 @@ treat as a live scratch write until you have checked it.
2477
2473
  is a failure event, not a clean review.** The review throws on missing
2478
2474
  `args.pr`/`args.worktree` and on a snapshot agent that returned no tree, and a
2479
2475
  failure surfaces mid-loop, where "react, never block" makes it easy to log and
2480
- carry on — leaving a PR that *reads* as reviewed and is not. **Retry once, then
2481
- fall back — and whoever holds the review call is who retries:**
2482
- 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.
2483
- Either way, settle the dead review by appending `=failed` to its `review=`
2484
- token, then append `review=fallback:<that name>` after it, both in one
2485
- `ledger.mjs review <pr> review=<dead launch>=failed review=fallback:<that name>`
2476
+ carry on — leaving a PR that *reads* as reviewed and is not. **Retry once
2477
+ under the next runner letter, then stop:** the `review-pr-<pr#>` runner
2478
+ already retried once inside its cell and reports `failed` with both errors, so
2479
+ the retry is a second runner under the next letter the PR's rows do not carry
2480
+ yet — `review-pr-<pr#>-b` after a first runner — recorded as
2481
+ `review=member:<that name>`. A second failure is reported, and the PR stays at
2482
+ review-due. Settle the dead review by appending `=failed` to its `review=`
2483
+ token, then append `review=member:<that name>` after it, both in one
2484
+ `ledger.mjs review <pr> review=<dead launch>=failed review=member:<that name>`
2486
2485
  call — `review` settles the dead launch in place, and refuses a new launch
2487
2486
  while the dead one still reads open, and the tick takes the last `review=`
2488
- token on a row as the one in flight, so that order is what keeps the fallback
2487
+ token on a row as the one in flight, so that order is what keeps the retry
2489
2488
  counted against the cap. A
2490
2489
  runner member that is killed rather than failed follows **Failure
2491
2490
  handling** (fresh name, inherited state stated).
@@ -3423,7 +3422,7 @@ decides the rest — two resolve automatically, every other one escalates:
3423
3422
  | Cause | Resolution |
3424
3423
  |---|---|
3425
3424
  | `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. |
3426
- | `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, with `ledger.mjs review <M>` onto the PR's row, 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`) — `review` refuses a second `review-pr-<M>` and names the free one — and its result reaches a fresh finisher through the same gate. |
3425
+ | `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, with `ledger.mjs review <M>` onto the PR's row, its runner under the next letter the PR's rows do not carry yet (`review-pr-<M>-b`, or `-c` where a retry already took `-b`) — `review` refuses a second `review-pr-<M>` and names the free one — and its result reaches a fresh finisher through the same gate. |
3427
3426
  | `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. |
3428
3427
  | `unreadable`, `missing`, `absent`, `other` | **Escalate** — comment and flag, no automatic retry. |
3429
3428
 
@@ -3506,85 +3505,6 @@ an absence counts only after the same command, with the same flags, finds a
3506
3505
  line known to match: a command that cannot find a match settles nothing, and
3507
3506
  under `Verified:` its zero reads as a checked absence.
3508
3507
 
3509
- #### Fallback: hand-dispatched reviewer member
3510
-
3511
- Only where the review unit is unavailable **or has failed** — never a
3512
- preference. "Unavailable" is the review unit not being there to dispatch at
3513
- all; "failed" is the failure event above, surviving its one retry. A review that
3514
- is present and failing is not absent, and reading this line as absence-only
3515
- leaves the likeliest failure with no sanctioned path at all. One named member
3516
- per PR — `review-pr-<pr#>` while no reviewer on the PR has held that name,
3517
- else the next letter its rows do not carry yet (`-b`, `-c`, …) — never its
3518
- implementer, recorded as `review=fallback:<that name>` on the PR's row with `ledger.mjs review <pr>`. It runs off your turn
3519
- like the review it replaces. Give it the PR number and tell it to read
3520
- `$(~/.fleet/bin/fleet-run --root)/commands/review-and-fix.md` — the resolved file
3521
- path, not a slash invocation; command availability inside a member is not
3522
- guaranteed the way skill availability is. Tell it to check every added
3523
- assertion against the tree, including comments in files the diff does not
3524
- touch, and to read each corrected sentence literally, clause by clause. It then
3525
- does the fix-applier's job too:
3526
- apply, defer, file, push, report, exit — and before it reports, it writes its
3527
- findings as a review result file in a run root of its own, made with
3528
- `mktemp -d "<scratch>/pr<pr>/run-XXXXXXXX"` (`<scratch>` the absolute path you
3529
- named in its prompt), in the shape `review-and-fix.md`'s
3530
- **The review result file** describes, and reports that file's path. On its
3531
- report, record `reviewed=<head>:0/<refuted>/<deferred>:<run>` with `ledger.mjs review <pr>`, `<run>` that run
3532
- root's name, against the head it pushed — it applied
3533
- its own survivors, so the zero is what tells the tick no fix-applier is owed for
3534
- them; a nonzero `<deferred>` is still fix-due, as any review's unverified band is —
3535
- and it reaches a finisher through the same gate as any other PR.
3536
-
3537
- **Authorize the fan-out explicitly.** State that the full specialist set IS the
3538
- requested work — holding the dispatch tool is not authorization to use it, and
3539
- a reviewer not told so declines the fan-out and silently downgrades to a
3540
- thinner solo review.
3541
- Nothing computes the count here, so apply the heuristic yourself: two or three
3542
- specialists for annotation-only or single-file, the full set for production code.
3543
- See references/member-lifecycle.md.
3544
-
3545
- **Delivering specialist reports is your duty on this path, not the reviewer's.**
3546
- Reports surface to *you* and grandchildren are unaddressable, so a reviewer must
3547
- never be told to ping for one. But it **can** read the report itself: a specialist
3548
- it spawned writes its transcript to the output file named in its spawn result, and
3549
- `tail -1 <file> | jq -r '.message.content[]?|select(.type=="text").text'`
3550
- extracts the final report — bounded, unlike reading the whole file. State that in
3551
- the prompt: retrieve first, ask you by name only if the file yields nothing, and
3552
- rule a dimension **unrun** only when neither works — not silently, and not after
3553
- waiting forever, since a killed specialist never reports and never gets relayed.
3554
- See references/member-lifecycle.md.
3555
-
3556
- So two obligations enter the event loop for as long as a hand-dispatched reviewer
3557
- is live:
3558
-
3559
- - **A specialist report lands** (a task-notification from a grandchild you never
3560
- dispatched) → **relay it to the reviewer that owns the PR — source named, text
3561
- included.** Relay anyway even though the reviewer can retrieve it itself — a
3562
- duplicate costs nothing, a missed report costs a verdict. Telling it to ping the
3563
- specialist does not work either — a depth-2 member cannot dispatch
3564
- further, so the reviewer has no path to its own un-nameable children
3565
- beyond reading their output file.
3566
- - **A reviewer's verdict claims a dimension went undelivered** → reconcile it
3567
- against your relay receipts before accepting it. Receipts say relayed → re-send
3568
- naming the specialist and hold that verdict until it lands; a relay can arrive
3569
- after a verdict is already composed. Only you hold the msg id, so only you can
3570
- catch this — the reviewer cannot tell "no report exists" from "one was sent that
3571
- I have not received". One reviewer ruled a relayed dimension "not covered by a
3572
- specialist" and shipped a headline claim that report refuted.
3573
-
3574
- Neither belongs in a workflow-path prompt: there `agent()` returns into the
3575
- script, no relay ever occurs, and a rule to wait for one strands every finding.
3576
-
3577
- **Same receipts gate the finisher dispatch** — dispatch only once every
3578
- specialist report you know landed for this PR is relayed, none unrelayed. The
3579
- reviewer applies findings and pushes as each relay lands, so an
3580
- unrelayed report is exactly as inbound as a fix-applier ruling you haven't sent
3581
- (above) — dispatch past it and you pin a SHA the reviewer is about to move past.
3582
- Necessary, not sufficient — a reviewer re-reading its own inbox late still moves
3583
- the head, which is what the halt block's cause list above is for.
3584
- Vacuous on the workflow path: `agent()` already returned every report before
3585
- you had a tree to dispatch a finisher against, so nothing is ever outstanding
3586
- there.
3587
-
3588
3508
  ### Merge bot
3589
3509
 
3590
3510
  Per pass, named `merge-bot-<n>`, never two at once. `ledger.mjs dispatch
@@ -4177,7 +4097,7 @@ Plan it as a PR the run's own merge queue lands, never as an edit-and-continue.
4177
4097
  | SHA not on expected branch | Flag, do not enqueue, report |
4178
4098
  | Implementer bails before implementing | → `needs-triage` if under-specified, `ready-for-human` if it needs human hands or leaves a fork open; drop `in-progress`, comment the cause, release the claim, refill (phase 3) |
4179
4099
  | Implementer blocked or ambiguous *mid-implementation* | Free the slot, leave `in-progress`, report — the row above is the pre-code bail, not this one |
4180
- | `review-pr` workflow throws or returns no tree | Retry once, then hand-dispatch the fallback reviewer. Never enqueue the PR as reviewed — the workflow is not a member, so no other row here covers it |
4100
+ | `review-pr` workflow throws or returns no tree | Retry once under the next letter (`review-pr-<pr#>-b`); still failing, report and leave the PR at review-due. Never enqueue the PR as reviewed — the workflow is not a member, so no other row here covers it |
4181
4101
  | Reviewer or fix-applier cannot reach green | Report, leave the PR unlabeled, free the slot |
4182
4102
  | Merge bot hits the hold rule | Report `held-behind-#<lower>`, PR stays queued |
4183
4103
  | Merge bot finds the worktree ahead of the PR head **on the local-rebase fallback** | `worktree-diverged-#<pr>`, PR stays queued. Read the stray commit; push-or-discard is yours, and the maintainer's if the evidence cannot settle it |
@@ -4342,7 +4262,7 @@ any other, never a section of its own.
4342
4262
 
4343
4263
  A PR's review is not a member, so it carries its own pair of row tokens,
4344
4264
  written with `review` onto the PR's row (**Reviewers**): `review=wf:<runId>` |
4345
- `review=member:<name>` | `review=fallback:<name>` at launch, `<name>` being
4265
+ `review=member:<name>` at launch, `<name>` being
4346
4266
  `review-pr-<n>` for the PR's first runner and the next letter its rows do not
4347
4267
  carry yet (`review-pr-<n>-b`, `-c`, …) for every later one,
4348
4268
  settled dead as `…=failed`, then `reviewed=<head>:<survived>/<refuted>/<unverified>:<run>`
@@ -4365,8 +4285,7 @@ it your own removal reads as one. `row` refuses a `label-off=` naming no
4365
4285
  maps to the PR — its settled `impl-<N>=PR#<M>` token, else its first `PR#`
4366
4286
  mention, else its key — in ledger order. Every `reviewed=` answers the nearest
4367
4287
  earlier launch that is neither answered nor `=failed`. A launch identity (a
4368
- workflow's runId, or a runner's name whichever of member or fallback launched
4369
- it, `=failed` aside) appears once, and no launch takes a runner name the
4288
+ workflow's runId, or a runner's name, `=failed` aside) appears once, and no launch takes a runner name the
4370
4289
  ledger's `## Retired` holds — an earlier run of this session launched it —
4371
4290
  naming the next free reviewer name instead. No launch appears
4372
4291
  while an earlier one is open — unanswered and not `=failed`. Every
@@ -4485,15 +4404,6 @@ Plus a queue-depth line: shortlist, supply, whether triage was suggested.
4485
4404
  - "The brief is thorough, so it's decided" → thorough ≠ decided. Read it for the
4486
4405
  choice it leaves open.
4487
4406
  - "I'd have to pick an approach myself" → that IS undecided.
4488
- - "The reviewer can dispatch, it'll fan out" → not unless authorized.
4489
- - "Tell the reviewer to ping its specialists" (fallback path) → a depth-2 member
4490
- cannot dispatch further, so the ping goes nowhere. Tell it to
4491
- read the specialist's output file instead; your relay is the backup, not the
4492
- only path.
4493
- - "I relayed it, so the reviewer has it" (fallback path) → sent is not read, and a relay can land
4494
- after the verdict is composed. Two reviewers ruled relayed dimensions
4495
- undelivered, one of them shipping a headline claim the report it disclaimed
4496
- refuted. Reconcile verdicts against your receipts.
4497
4407
  - "It reported the SHA, so it's on the branch" → verify.
4498
4408
  - "Let the merge bot arm its own monitor" → it dies, the queue stops.
4499
4409
  - "The member died, message it the state" → dead agents do not read mail.
@@ -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#>` (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 the PR's row does not carry yet, `review-pr-<pr#>-b`, `-c`, …; a reviewer's launch and result are recorded on the PR's row with `ledger.mjs review <pr#>`), `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 retry, past-pin re-review — takes the next letter the PR's row does not carry yet, `review-pr-<pr#>-b`, `-c`, …; a reviewer's launch and result are recorded on the PR's row with `ledger.mjs review <pr#>`), `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