@feigi/fleet-ctl 3.43.6 → 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.6",
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
  }
@@ -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