@feigi/fleet-ctl 3.156.2 → 3.157.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -66,11 +66,9 @@ retries it under the next letter.
66
66
  the file, for the fix-applier, and the controller reads only the digest.
67
67
  - `status: "completed"` → first line `<your name>: completed <path>` — the
68
68
  member name you were dispatched as, `review-pr-<pr>` or a later letter —
69
- then the returned `path`, `ledger`, `attempts`, `errors` and `digest`,
70
- verbatim, as JSON. `ledger` is the `reviewed=` token the controller
71
- records on the PR's row with `ledger.mjs review <pr>`; you write no
72
- ledger token yourself. `errors` is non-empty when the first attempt failed
73
- and the retry completed — report it anyway.
69
+ then the returned `path`, `attempts`, `errors` and `digest`, verbatim, as
70
+ JSON; you write no ledger token yourself. `errors` is non-empty when the
71
+ first attempt failed and the retry completed — report it anyway.
74
72
  - `status: "failed"` → first line `<your name>: failed`, then both
75
73
  `errors` verbatim. Do not run the cell again — the one retry already
76
74
  happened inside it.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@feigi/fleet-ctl",
3
- "version": "3.156.2",
3
+ "version": "3.157.0",
4
4
  "description": "Agent fleet: run-team controller, merge bot, PR reviewer, and the ticket pipeline they share",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
@@ -97,12 +97,14 @@
97
97
  // The reap and the reclaim run once for every merge bot settled `done`, always, even when the pass merged nothing, and again on the next tick after an `APPLY FAILED` line, and on every tick while this run has no controller record to remember the pass by.
98
98
  // The bot may also have written `conflict-hold:#<pr>` onto a held PR's own row earlier in the same pass, before reporting: a token the bot wrote in that pass, never one `reap.sh` writes.
99
99
  // review-result <pr> <path>
100
- // The review result file at `<path>`, which must be
100
+ // `ledger.mjs review <pr> --result <path> --scratch <scratch>`: the
101
+ // ledger derives `reviewed=<head>:<survived>/<refuted>/<unverified>:<run>`
102
+ // from the review result file at `<path>`, which must be
101
103
  // `<scratch>/pr<pr>/<run>/<file>`, `<run>` a review run root
102
- // (`run-` and eight characters) and no `..` segment: its `head` and
103
- // `counts` make `ledger.mjs review <pr>
104
- // reviewed=<head>:<survived>/<refuted>/<unverified>:<run>`, skipped when
105
- // the PR's rows already carry that token.
104
+ // (`run-` and eight characters) and no `..` segment, a `pr` it carries
105
+ // this PR and its `head` and `counts` naming a token. A token the PR's
106
+ // rows already carry is not written again. A refusal is the ledger's,
107
+ // passed through, nothing written.
106
108
  // The result file is `<scratch>/pr<pr>/<run>/review.json`, `<run>` the review's own `run-XXXXXXXX` run root.
107
109
  // review-failed <pr> <launch>
108
110
  // `ledger.mjs review <pr> review=<launch>=failed`, `<launch>` as the
@@ -219,8 +221,8 @@
219
221
  // Zero deps: node builtins and sibling scripts only.
220
222
 
221
223
  import { spawnSync } from "node:child_process";
222
- import { readdirSync, readFileSync, realpathSync } from "node:fs";
223
- import { basename, dirname, join, normalize, resolve } from "node:path";
224
+ import { readdirSync, readFileSync } from "node:fs";
225
+ import { dirname, join, resolve } from "node:path";
224
226
  import { fileURLToPath } from "node:url";
225
227
  import { makeDie, defineFlags, isDigits, writeAll } from "./arg.mjs";
226
228
  import { FleetDirUnresolvable, fleetFile } from "./fleet-dir.mjs";
@@ -868,47 +870,23 @@ function park(ev, member, pr, reason) {
868
870
  ev.token(pr, tok);
869
871
  }
870
872
 
871
- // `p` with its symlinks resolved, or as written when it does not exist yet.
872
- function real(p) {
873
- try {
874
- return realpathSync(p);
875
- } catch {
876
- return p;
877
- }
878
- }
879
-
880
- // The run name of a review result file at `path` in PR `pr`'s partition of
881
- // `scratch`, or die naming why it is not one.
882
- function reviewRun(scratch, pr, path) {
883
- if (path.split("/").includes("..")) die(`review-result: ${path} has a ".." segment — pass the result file's path without one`);
884
- const file = resolve(path);
885
- const runRoot = dirname(file);
886
- const partition = join(normalize(scratch), `pr${pr}`);
887
- if (real(dirname(runRoot)) !== real(partition)) die(`review-result: ${file} is not under PR #${pr}'s partition ${partition}/ — nothing written`);
888
- const run = basename(runRoot);
889
- if (!/^run-[A-Za-z0-9]{8}$/.test(run)) die(`review-result: ${runRoot} is not a review run root (run- and eight characters) — nothing written`);
890
- return { file, run };
891
- }
892
-
873
+ // The review result file at `path` goes to `ledger.mjs review <pr> --result`,
874
+ // which owns every check of the path and the file and derives the `reviewed=`
875
+ // token from it; a token the PR's rows already carry comes back unwritten.
893
876
  function reviewResult(ev, pr, path) {
894
- const { file, run } = reviewRun(ev.scratch, pr, path);
895
- let result;
896
- try {
897
- result = JSON.parse(readFileSync(file, "utf8"));
898
- } catch (e) {
899
- die(`review-result: cannot read ${file}: ${e.code ?? e.message} — nothing written`);
900
- }
901
- if (result?.pr !== undefined && Number(result.pr) !== pr) die(`review-result: ${file} is PR #${result.pr}'s review, not #${pr}'s — nothing written`);
902
- const { survived, refuted, unverified } = result?.counts ?? {};
903
- const token = `reviewed=${result?.head}:${survived}/${refuted}/${unverified}:${run}`;
904
- if (!REVIEWED.test(token)) die(`review-result: ${file} carries no head and counts a reviewed= token can name (${token}) — nothing written`);
905
- if (prWords(ev.ledger, pr).includes(token)) {
906
- ev.note(`PR #${pr} already ${token}`);
877
+ const r = node("ledger.mjs", ["review", String(pr), "--result", path, "--scratch", ev.scratch]);
878
+ if (r.status !== 0) {
879
+ ev.refuse(`review #${pr} --result ${path}`, r);
907
880
  return;
908
881
  }
909
- const r = node("ledger.mjs", ["review", String(pr), token]);
910
- if (r.status === 0) ev.note(`PR #${pr} ${token}`);
911
- else ev.refuse(`review #${pr} ${token}`, r);
882
+ let receipt = {};
883
+ try {
884
+ receipt = JSON.parse(r.stdout);
885
+ } catch {
886
+ // The ledger answered 0, so the write is settled; only its token is unread.
887
+ }
888
+ const token = typeof receipt.reviewed === "string" ? receipt.reviewed : `the result at ${path}`;
889
+ ev.note(receipt.written === false ? `PR #${pr} already ${token}` : `PR #${pr} ${token}`);
912
890
  }
913
891
 
914
892
  function reviewFailed(ev, pr, launch) {
@@ -970,7 +970,7 @@ export function foldLedger({ rows, dispatched }, open, { lenient = false } = {})
970
970
  }
971
971
  if (!m && REVIEWED_RUNLESS.test(tok)) {
972
972
  throw new LedgerError(`${where}: '${tok}' names no review run — reviewed= is now <head>:<survived>/<refuted>/<unverified>:<run>, `
973
- + "<run> the run-XXXXXXXX directory holding that review's review.json; drop the token with `ledger.mjs row` and record it again with `ledger.mjs review <pr>`");
973
+ + "<run> the run-XXXXXXXX directory holding that review's review.json; drop the token with `ledger.mjs row` and record it again with `ledger.mjs review <pr> --result <path>`");
974
974
  }
975
975
  if (!m) throw new LedgerError(`${where}: '${tok}' is not reviewed=<head>:<survived>/<refuted>/<unverified>:<run>`);
976
976
  latestFinisher = null;
@@ -15,9 +15,9 @@
15
15
  // claimed as a member here; everything else a row carries (`class=routine`,
16
16
  // `ports=`, `ci=`, `conflict-hold:#<pr>`, the
17
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 review` writes and `ledger.mjs row` checks a write against
20
- // before it lands.
18
+ // review pair has a grammar of its own below, REVIEW and REVIEWED. A launch is
19
+ // written by `ledger.mjs review`, a result by `ledger.mjs review --result`,
20
+ // and `ledger.mjs row` checks a write against it before it lands.
21
21
 
22
22
  import { createHash } from "node:crypto";
23
23
 
@@ -427,7 +427,8 @@ export function nextReviewerName(rows, pr, retired = []) {
427
427
  const OPEN_WAYS_OUT = "wait for its reviewed=, or, once Member-killed confirms its runner dead, settle it =failed in the same `ledger.mjs review` call as the new launch";
428
428
 
429
429
  /** Whether a word of a row is a review token — `review=…` or `reviewed=…`,
430
- * parseable or not. `ledger.mjs review` writes these and nothing else. */
430
+ * parseable or not. `ledger.mjs review` writes these and nothing else: a
431
+ * launch from its arguments, a `reviewed=` only from a result file. */
431
432
  export const isReviewToken = (word) => word.startsWith("review=") || word.startsWith("reviewed=");
432
433
 
433
434
  /**
@@ -446,8 +447,9 @@ export function addedReviewToken(oldLine, line) {
446
447
  // an answer are written only by `ledger.mjs dispositions`, which derives them
447
448
  // from their evidence; the one input an argument supplies there is the
448
449
  // maintainer's answer to an escalate, as `--uphold`/`--send-back` flags. A
449
- // `reviewed=` is written by `ledger.mjs review`, off `fleet-event.mjs
450
- // review-result`.
450
+ // `reviewed=` is written by `ledger.mjs review <pr> --result <path>`, which
451
+ // derives it from the review result file; `fleet-event.mjs review-result`
452
+ // calls it.
451
453
 
452
454
  /** Whether `word` begins like a dispositions verdict or an Escalation answer,
453
455
  * parseable or not: the words `ledger.mjs token` refuses. The dispositions
@@ -42,8 +42,8 @@
42
42
  // Writer policy: a Gate verdict — a dispositions verdict, an Escalation
43
43
  // answer, a `reviewed=` — is written only by its own verb, whoever calls it:
44
44
  // `dispositions` for the first two, which it derives from their evidence,
45
- // and `review` for the third, which still takes its `reviewed=` as an
46
- // argument, not yet deriving it from the review's result file. `token`
45
+ // and `review --result` for the third, which it derives from the review's
46
+ // result file and refuses as an argument. `token`
47
47
  // refuses all three, and `row` carries every Gate verdict exactly as the row
48
48
  // holds it, so no other verb adds, changes or drops one. `filed` appends
49
49
  // filings, and all writes are serialized by `<file>.lock`; the other tokens
@@ -63,7 +63,7 @@
63
63
  // life, so the stall readers judge a busy run by them (fleet-state.mjs has
64
64
  // the rule).
65
65
 
66
- import { readFileSync, writeFileSync, mkdirSync, existsSync, renameSync, unlinkSync, linkSync } from "node:fs";
66
+ import { readFileSync, writeFileSync, mkdirSync, existsSync, renameSync, unlinkSync, linkSync, realpathSync } from "node:fs";
67
67
  import { createHash } from "node:crypto";
68
68
  import { dirname, resolve, join, basename, isAbsolute } from "node:path";
69
69
  import { fileURLToPath } from "node:url";
@@ -82,6 +82,7 @@ import { ownClosingIssues } from "./closing-refs.mjs";
82
82
  import { isTicketless } from "./ticketless.mjs";
83
83
  import { RELEASE_LABELS, LABEL_LIST_ARGS, LABEL_LIST_LIMIT, releaseLabelsIn, releaseLabelsDefined } from "./release-labels.mjs";
84
84
  import { LabelMapUnreadable, readLabelMap } from "./label-map.mjs";
85
+ import { REVIEWED, prTokens } from "./ledger-grammar.mjs";
85
86
 
86
87
  const NAME = "ledger";
87
88
  // The plugin's own agent definitions — the directory tier-check.mjs reads
@@ -804,7 +805,7 @@ if (cmd === "read") {
804
805
  // order, so `row` adds none; one the row already holds is carried.
805
806
  const reviewToken = addedReviewToken(oldRow, line);
806
807
  if (reviewToken !== undefined) {
807
- die(`row ${key}: adds review token '${reviewToken}' — review tokens are written only with \`ledger.mjs review <pr> <token>…\`, which puts them on the PR's row`);
808
+ die(`row ${key}: adds review token '${reviewToken}' — ${reviewTokenWriter(reviewToken)}`);
808
809
  }
809
810
  // Every Gate verdict is its own verb's to write, so a rewrite carries the
810
811
  // row's as they stand — none added, changed, dropped or reordered, which
@@ -3115,38 +3116,132 @@ function numberArg(arg, what, usage) {
3115
3116
  return Number(digits);
3116
3117
  }
3117
3118
 
3118
- // `review <pr> <token>…`: the only writer of a PR's `review=`/`reviewed=`
3119
- // tokens. Each lands on the PR's row — the ticket row once `settle
3119
+ // What a refusal names as the writer of review token `tok`: a `reviewed=` is a
3120
+ // Gate verdict `review` derives from a result file; a launch is an argument.
3121
+ function reviewTokenWriter(tok) {
3122
+ return tok.startsWith("reviewed=")
3123
+ ? "a reviewed= is written only with `ledger.mjs review <pr> --result <path>`, which derives it from the review's result file and puts it on the PR's row"
3124
+ : "review tokens are written only with `ledger.mjs review <pr> <token>…`, which puts them on the PR's row";
3125
+ }
3126
+
3127
+ // The `reviewed=` token a review result file at `path` derives, for PR `pr`.
3128
+ // `path` is `<scratch>/pr<pr>/<run>/<file>` with no `..` segment, `<run>` a
3129
+ // review run root (`run-` and eight characters); `scratch` is `--scratch`, else
3130
+ // the root `settle --from-report` falls back to. The token is the file's
3131
+ // `head` and `counts` with that run, and a `pr` the file carries must be
3132
+ // `pr`. Dies, writing nothing, naming the first check the file fails.
3133
+ function reviewResultToken(pr, path, scratchArg) {
3134
+ const where = `review #${pr} --result`;
3135
+ if (path.split("/").includes("..")) die(`${where}: ${path} has a ".." segment — pass the result file's path without one`);
3136
+ let scratch = scratchArg;
3137
+ if (scratch === null) {
3138
+ try {
3139
+ scratch = defaultScratch();
3140
+ } catch (e) {
3141
+ if (!(e instanceof FleetDirUnresolvable)) throw e;
3142
+ die(`${where}: no --scratch, and the scratch root could not be resolved — ${e.message}`);
3143
+ }
3144
+ }
3145
+ const real = (p) => {
3146
+ try {
3147
+ return realpathSync(p);
3148
+ } catch {
3149
+ return p;
3150
+ }
3151
+ };
3152
+ const file = resolve(path);
3153
+ const runRoot = dirname(file);
3154
+ const partition = join(resolve(scratch), `pr${pr}`);
3155
+ if (real(dirname(runRoot)) !== real(partition)) die(`${where}: ${file} is not under PR #${pr}'s partition ${partition}/ — nothing written`);
3156
+ const run = basename(runRoot);
3157
+ if (!/^run-[A-Za-z0-9]{8}$/.test(run)) die(`${where}: ${runRoot} is not a review run root (run- and eight characters) — nothing written`);
3158
+ let result;
3159
+ try {
3160
+ result = JSON.parse(readFileSync(file, "utf8"));
3161
+ } catch (e) {
3162
+ die(`${where}: cannot read ${file}: ${e.code ?? e.message} — nothing written`);
3163
+ }
3164
+ if (result?.pr !== undefined && Number(result.pr) !== pr) die(`${where}: ${file} is PR #${result.pr}'s review, not #${pr}'s — nothing written`);
3165
+ const { survived, refuted, unverified } = result?.counts ?? {};
3166
+ const token = `reviewed=${result?.head}:${survived}/${refuted}/${unverified}:${run}`;
3167
+ if (!REVIEWED.test(token)) die(`${where}: ${file} carries no head and counts a reviewed= token can name (${token}) — nothing written`);
3168
+ return token;
3169
+ }
3170
+
3171
+ // `review <pr> [--result <path> [--scratch <dir>]] [<review=…>…]`: the only
3172
+ // writer of a PR's `review=`/`reviewed=` tokens. A `reviewed=` is a Gate
3173
+ // verdict, so it is written only from `--result`, which derives it from the
3174
+ // review result file (reviewResultToken()); a `reviewed=` word among the
3175
+ // arguments is refused, parseable or not, since an argument is not evidence.
3176
+ // `--scratch` names the scratch root the file must sit under, as `settle
3177
+ // --from-report`'s `--reports` names its reports root, else the root
3178
+ // scratch-root.mjs prints. A launch token (`review=…`, `review=…=failed`) is an
3179
+ // argument token and may come in the same call, written before the result it
3180
+ // answers. Each token lands on the PR's row — the ticket row once `settle
3120
3181
  // impl-<N>=PR#M` has run, else `#M`, created when neither exists — so the
3121
3182
  // row's token order is write order, the order the tick folds the PR's review
3122
3183
  // record in. `review=X=failed` for a launch the row holds open as `review=X`
3123
3184
  // rewrites that token in place; every other token is appended as ` · <token>`.
3124
- // The whole ledger before and after is judged by rowWriteRefusal() under the
3125
- // lock, and a refusal writes nothing. The receipt's `next` is the runner name
3126
- // the PR's next launch takes as the ledger stands after the write, null with
3127
- // every letter taken.
3185
+ // A result token the PR's rows already carry is not written again: with no
3186
+ // launch in the call, exit 0 with nothing written. The whole ledger before
3187
+ // and after is judged by rowWriteRefusal() under the lock, and a refusal
3188
+ // writes nothing. The receipt names the derived token as `reviewed`, with
3189
+ // `written` saying whether this call put it on the row, and its `next` is the
3190
+ // runner name the PR's next launch takes as the ledger stands after the
3191
+ // write, null with every letter taken.
3128
3192
  function runReview() {
3129
- const usage = "usage: ledger.mjs review <pr> <review=…|reviewed=…>…";
3193
+ const usage = "usage: ledger.mjs review <pr> [--result <path> [--scratch <dir>]] [<review=…>…]";
3130
3194
  const [pr, ...parts] = rest;
3131
3195
  if (!pr || parts.length === 0) die(usage);
3132
3196
  const prNum = numberArg(pr, "a PR number", usage);
3133
- const tokens = parts.join(" ").split(/\s+/).filter(Boolean);
3197
+ const flags = new Map();
3198
+ const words = [];
3199
+ for (let k = 0; k < parts.length; k++) {
3200
+ const word = parts[k];
3201
+ const flag = word.split("=")[0];
3202
+ if (flag !== "--result" && flag !== "--scratch") {
3203
+ words.push(word);
3204
+ continue;
3205
+ }
3206
+ if (flag !== word) die(`review #${prNum}: ${flag} needs a space-separated value, not ${flag}= — ${usage}`);
3207
+ if (flags.has(word)) die(`review #${prNum}: ${word} is given twice — ${usage}`);
3208
+ const value = parts[++k];
3209
+ if (value === undefined || isFlagLike(value)) die(`review #${prNum}: ${word} needs a value — ${usage}`);
3210
+ flags.set(word, value);
3211
+ }
3212
+ if (flags.has("--scratch") && !flags.has("--result")) die(`review #${prNum}: --scratch is read only with --result — ${usage}`);
3213
+ const tokens = words.join(" ").split(/\s+/).filter(Boolean);
3214
+ const typed = tokens.find((tok) => tok.startsWith("reviewed="));
3215
+ if (typed !== undefined) {
3216
+ die(`review #${prNum}: '${typed}' is a reviewed= token — a reviewed= is a Gate verdict, written only with \`ledger.mjs review ${prNum} --result <path>\`, which derives it from the review's result file; no argument supplies one`);
3217
+ }
3134
3218
  const other = tokens.find((tok) => !isReviewToken(tok));
3135
3219
  if (other !== undefined) {
3136
- die(`review #${prNum}: '${other}' is not a review token — review writes only review=… and reviewed=…; every other token goes through row, dispatch or settle`);
3220
+ die(`review #${prNum}: '${other}' is not a review token — review writes only review=… launches and the reviewed= its --result derives; every other token goes through row, dispatch or settle`);
3137
3221
  }
3222
+ if (tokens.length === 0 && !flags.has("--result")) die(usage);
3138
3223
  const retired = retiredNames("review");
3224
+ let reviewed = null;
3225
+ if (flags.has("--result")) {
3226
+ reviewed = reviewResultToken(prNum, flags.get("--result"), flags.get("--scratch") ?? null);
3227
+ if (!prTokens(data.rows, prNum).includes(reviewed)) tokens.push(reviewed);
3228
+ }
3139
3229
  const i = prRowIndex(prNum);
3140
3230
  const created = i === -1;
3141
3231
  const oldLine = created ? null : data.rows[i];
3142
- const words = created ? [`#${prNum}`] : oldLine.split(/(\s+)/);
3232
+ if (tokens.length === 0) {
3233
+ console.error(` review on row ${rowKey(oldLine)}: already carries ${reviewed} — not written again`);
3234
+ console.log(JSON.stringify({ pr: prNum, row: rowKey(oldLine), line: oldLine, created: false, written: false, reviewed, next: nextReviewerName(data.rows, prNum, retired) }));
3235
+ return;
3236
+ }
3237
+ const cells = created ? [`#${prNum}`] : oldLine.split(/(\s+)/);
3143
3238
  const appended = [];
3144
3239
  for (const tok of tokens) {
3145
- const open = tok.endsWith("=failed") ? words.lastIndexOf(tok.slice(0, -"=failed".length)) : -1;
3146
- if (open > 0) words[open] = tok;
3240
+ const open = tok.endsWith("=failed") ? cells.lastIndexOf(tok.slice(0, -"=failed".length)) : -1;
3241
+ if (open > 0) cells[open] = tok;
3147
3242
  else appended.push(tok);
3148
3243
  }
3149
- const head = words.join("");
3244
+ const head = cells.join("");
3150
3245
  const line = appended.length === 0 ? head
3151
3246
  : created ? `${head} ${appended.join(" · ")}`
3152
3247
  : `${head} · ${appended.join(" · ")}`;
@@ -3157,7 +3252,7 @@ function runReview() {
3157
3252
  save(data);
3158
3253
  const key = rowKey(line);
3159
3254
  console.error(` review on row ${key}`);
3160
- console.log(JSON.stringify({ pr: prNum, row: key, line, created, next: nextReviewerName(data.rows, prNum, retired) }));
3255
+ console.log(JSON.stringify({ pr: prNum, row: key, line, created, ...(reviewed === null ? {} : { reviewed, written: tokens.includes(reviewed) }), next: nextReviewerName(data.rows, prNum, retired) }));
3161
3256
  }
3162
3257
 
3163
3258
  // `dispositions <member> --scratch <dir> [--repo <path>] [--uphold <list>]
@@ -3367,7 +3462,7 @@ function tokenRefusal(tok, earlier) {
3367
3462
  return "is a member token — members are written only with `ledger.mjs dispatch` and `ledger.mjs settle`";
3368
3463
  }
3369
3464
  if (isReviewToken(tok)) {
3370
- return "is a review token — review tokens are written only with `ledger.mjs review <pr> <token>…`, which puts them on the PR's row";
3465
+ return `is a review token — ${reviewTokenWriter(tok)}`;
3371
3466
  }
3372
3467
  if (isDispositionsWord(tok)) {
3373
3468
  return tok.startsWith("escalation-answer=")
@@ -145,11 +145,12 @@ export async function runReviewOnOmp(args) {
145
145
  // keep out of its context. The run root is the review's own
146
146
  // `<scratch>/pr<pr>/run-XXXXXXXX`, the directory review-core.mjs's snapshot
147
147
  // step made with `mktemp` and the snapshot it returns sits in, so two reviews
148
- // of one PR — at one head or two — never write one file, and the ledger token
149
- // names the run whose file it is. No file is ever replaced. The file leaves
148
+ // of one PR — at one head or two — never write one file, and the `reviewed=`
149
+ // `ledger.mjs review --result` derives names the run whose file it is. No
150
+ // file is ever replaced. The file leaves
150
151
  // with its run root: the snapshot step of a later review of the same PR
151
- // removes that PR's run roots not touched for seven days, so a token older
152
- // than that names a file that is gone.
152
+ // removes that PR's run roots not touched for seven days, so a `reviewed=`
153
+ // older than that names a file that is gone.
153
154
  //
154
155
  // Failure is a throw or an empty return. The holder of the review call retries
155
156
  // once; a second failure returns `failed` with both errors, and writes no
@@ -186,22 +187,18 @@ export async function runReviewToFile(args, run = runReviewOnOmp) {
186
187
  errors.push(`attempt ${attempt}: ${e?.message ?? String(e)}`);
187
188
  continue;
188
189
  }
189
- // `result.counts` is read below to build the digest and the ledger
190
- // token, but that read happens AFTER `mkdir`/`writeFile` have already put
191
- // the file on disk — so a `run` that resolves to a truthy, object-shaped
192
- // result missing `.counts` would otherwise throw on the destructure below
193
- // OUTSIDE this function's own retry try/catch (which wraps only the
194
- // `run(args)` call), leaving a half-written review file on disk
195
- // that a fix-applier reading it would mistake for a completed review that
196
- // never actually finished. Treated the same as an empty return: retried,
197
- // then reported `failed`, and no file is written for it.
190
+ // A result with no object `counts` is no completed review: its digest
191
+ // would carry no counts, and `ledger.mjs review --result` derives no
192
+ // `reviewed=` from a file without them, so a fix-applier reading it would
193
+ // hold a review nothing can record. Treated the same as an empty return:
194
+ // retried, then reported `failed`, and no file is written for it.
198
195
  if (!result || typeof result !== "object" || !result.counts || typeof result.counts !== "object") {
199
196
  errors.push(`attempt ${attempt}: empty return (${String(result)})`);
200
197
  continue;
201
198
  }
202
199
  // The run root is read off the result, never rebuilt: only the snapshot
203
200
  // step's shell knew the `mktemp` name. A result whose snapshot is not in
204
- // a run root of this PR under this scratch names no run the ledger token
201
+ // a run root of this PR under this scratch names no run a `reviewed=`
205
202
  // could point a reader back to, so it is a failed attempt like the one
206
203
  // above.
207
204
  const runRoot = runRootOf(result.snapshot, scratch, pr);
@@ -231,12 +228,9 @@ export async function runReviewToFile(args, run = runReviewOnOmp) {
231
228
  errors.push(`attempt ${attempt}: could not write ${path}: ${e?.message ?? String(e)}`);
232
229
  continue;
233
230
  }
234
- const { survived, refuted, unverified } = result.counts;
235
231
  return {
236
232
  status: "completed",
237
233
  path,
238
- // The review's result token, ready for `ledger.mjs review <pr>`.
239
- ledger: `reviewed=${result.head}:${survived}/${refuted}/${unverified}:${basename(runRoot)}`,
240
234
  attempts: attempt,
241
235
  errors,
242
236
  digest: digestOf(result),
@@ -223,7 +223,7 @@ Record each ruling with `ledger.mjs ruled <pr> <decision>`, one line with its re
223
223
 
224
224
  ### Dispatching the members a wake names
225
225
 
226
- - **The reviewer.** **Dispatch the review, never wait on it, and act when its result lands. That is the default path.** `DISPATCH review PR#<M>`: a `task` member named `review-pr-<pr#>`, agent `fleet-review-runner`, its prompt the five args `pr`, `branch`, `worktree`, `testCmd` and `scratch`. Record `review=member:review-pr-<pr#>` on the PR's row before the call, with `ledger.mjs review <pr> <token>`: the tick counts in-flight reviews off the ledger and nowhere else. `scratch` is the scratch root itself, never a `pr<N>` partition (`references/reviewers.md`). The runner writes the result file and reports its path and `reviewed=` token.
226
+ - **The reviewer.** **Dispatch the review, never wait on it, and act when its result lands. That is the default path.** `DISPATCH review PR#<M>`: a `task` member named `review-pr-<pr#>`, agent `fleet-review-runner`, its prompt the five args `pr`, `branch`, `worktree`, `testCmd` and `scratch`. Record `review=member:review-pr-<pr#>` on the PR's row before the call, with `ledger.mjs review <pr> <token>`: the tick counts in-flight reviews off the ledger and nowhere else. `scratch` is the scratch root itself, never a `pr<N>` partition (`references/reviewers.md`). The runner writes the result file and reports its path.
227
227
  A row with `review=` and no `reviewed=` is a review in flight, and the tick counts it as a live review unit unless gh reports its PR MERGED or CLOSED.
228
228
  - **The fix-applier.** `DISPATCH fix-pr PR#<M>` on a `reviewed=` count that survived or unverified findings, with no fix-applier live: name `fix-pr-<pr#>` (the next suffix if that name is on record), never the PR's implementer; render with `dispatch-prompt.mjs render fix-applier --kind review --member fix-pr-<pr#> …`, then record `ledger.mjs dispatch <pr#> fix-pr-<pr#>` before the call. Its brief carries the PR number, the worktree abs path, the PR's branch, the same `testCmd` you passed the review, and the **path** `<scratch>/pr<pr>/<run>/review.json`, `<run>` off the PR's latest `reviewed=` — never the findings. Every `<scratch>` in that brief is the absolute path `scratch-root.mjs` printed. Its rulings are the fix-applier body's (`agents/fleet-fix-applier.agent.md`); you hold none, and a refuter report that surfaces to you is its to retrieve, never yours to scan or pass on. On a PR carrying `ready-to-merge`, its push moves the head after the label: a fresh finisher, per **Failure handling**.
229
229
  - **The conflict hold.** `DISPATCH fix-pr PR#<M>` on a conflict hold: the row carries an unresolved `conflict-hold:#<M>`, the merge bot's or one you recorded off the tick's `CONFLICT` line. It is the same slot with a different job, and no review file to hand over. Name it `fix-pr-<M>`, or the next suffix (`-b`, `-c` …) when that name is on record; render with `dispatch-prompt.mjs render fix-applier --kind conflict --member <name> …`; dispatch with the `agent` `ledger.mjs dispatch` printed, in the PR's existing worktree. Settle `applied:<head>`, or `no-op` if no conflict was left, which lifts the merge hold; a dispatched-but-live one does not, and `failed`/`killed` leave the PR fix-due for a replacement; a second `failed` since its latest review escalates. It answers the hold and nothing else: review findings the row also carries get a review `DISPATCH fix-pr PR#<M>` once it lands.
@@ -256,9 +256,9 @@ references/isolation.md.
256
256
 
257
257
  **You read the digest; the findings are the fix-applier's.**
258
258
  `jq '{pr, head, resume, testEnvironment, suiteVerdict, dimensionsRun, dimensionsUnrun, cwdAudit, counts}' <scratch>/pr<pr>/<run>/review.json`
259
- is the whole of your read, and it is what you record: `reviewed=<head>:<survived>/<refuted>/<unverified>:<run>`,
260
- off `head`, `counts` and the run root's name — the runner's `ledger` field — on
261
- the PR's row, with `ledger.mjs review <pr>`. Every later path to the review is built from that token, before a
259
+ is the whole of your read. The record is the `reviewed=<head>:<survived>/<refuted>/<unverified>:<run>`
260
+ the `fleet-event.mjs review-result <pr> <path>` wake writes on the PR's row, off `head`, `counts` and the run root's
261
+ name, never one typed with `ledger.mjs review <pr>`. Every later path to the review is built from that token, before a
262
262
  restart or after one: `<scratch>/pr<pr>/<run>/review.json`, `<run>` off the PR's
263
263
  latest `reviewed=`. Findings never enter your context. The fix-applier
264
264
  reads every one off the file and makes every ruling on them
@@ -748,7 +748,7 @@ decides the rest — two resolve automatically, every other one escalates:
748
748
  | Cause | Resolution |
749
749
  |---|---|
750
750
  | `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. |
751
- | `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 the next free letter `review` names, and its result reaches a fresh finisher through the same gate. |
751
+ | `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 launch as any review's, with `ledger.mjs review <M>` onto the PR's row, its runner the next free letter `review` names, and its result reaches a fresh finisher through the same gate. |
752
752
  | `rebase` | **Escalate** — comment and flag, nothing more. The report's `evidence.replay` reads `pure` only when `git range-diff origin/main <pin> HEAD` pairs every pinned commit with an unchanged one; `changed` (a commit dropped, edited or added, or a stale `origin/main`) or `unknown` means read `evidence.rangeDiff` before acting, and `evidence.remote.state` says whether that head is on the PR. No automatic rule until a live halt shows the case recurring. |
753
753
  | `stray` | **Escalate** — comment and flag; nothing pushes it automatically. Read `evidence.cherry`, `.content` and `.remote`. Push or discard is yours, or the maintainer's if they cannot settle it. A pushed stray is unreviewed: `ledger.mjs review <M>` first. |
754
754
  | `unreadable`, `missing`, `absent`, `other` | **Escalate** — comment and flag, no automatic retry. |
@@ -385,14 +385,14 @@ absent; `carries` null: the read could not be told, and `error` says why). A
385
385
  commit that undoes something the pin carries reads clean by content (`paths`
386
386
  empty) and only its `+` line catches it, so a `+` beside empty `paths` is not
387
387
  by itself safe to discard. A pushed stray is a head no reviewer read: record
388
- its review by hand with `ledger.mjs review <M>`, under the next runner letter
388
+ its review launch by hand with `ledger.mjs review <M>`, under the next runner letter
389
389
  as for a `past-pin` re-review below, before any finisher is dispatched.
390
390
 
391
391
  A `human` halt is a Ticketless PR whose diff is not inert: the maintainer adds
392
392
  `ready-to-merge` at the pinned head, which the merge bot merges off the
393
393
  finisher's `ready-to-merge-head:` comment; a moved head is merged by hand.
394
394
 
395
- 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.
395
+ 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 launch 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, recorded by the `review-result` wake, reaches a fresh finisher through the same gate.
396
396
 
397
397
  A halt at duty 1 reads identical from a bare SHA mismatch whatever caused it,
398
398
  and the causes `finisher-audit.mjs` names are the ones seen so far, not a
@@ -104,7 +104,7 @@ PR stays queued, label untouched, and no member is dispatched to restore the lin
104
104
 
105
105
  ## The review pair on a PR's row
106
106
 
107
- A PR's review is not a member, so it carries its own pair of row tokens, written with `review` onto the PR's row (**The reviewer**): `review=wf:<runId>` | `review=member:<name>` at launch, `<name>` being `review-pr-<n>` for the PR's first runner and the next letter its rows do not carry yet (`review-pr-<n>-b`, `-c`, …) for every later one, settled dead as `…=failed`, then `reviewed=<head>:<survived>/<refuted>/<unverified>:<run>` when the result lands, `<run>` the review's `run-XXXXXXXX` run root under `<scratch>/pr<n>/`, which holds its `review.json`.
107
+ A PR's review is not a member, so it carries its own pair of row tokens, written with `review` onto the PR's row (**The reviewer**): `review=wf:<runId>` | `review=member:<name>` at launch, `<name>` being `review-pr-<n>` for the PR's first runner and the next letter its rows do not carry yet (`review-pr-<n>-b`, `-c`, …) for every later one, settled dead as `…=failed`, then `reviewed=<head>:<survived>/<refuted>/<unverified>:<run>` when the result lands, `<run>` the review's `run-XXXXXXXX` run root under `<scratch>/pr<n>/`, which holds its `review.json`. A `reviewed=` is a Gate verdict: `ledger.mjs review <pr> --result <path>` derives it from that file, and the `fleet-event.mjs review-result <pr> <path>` wake runs it. No `review` argument carries one, and one typed there is refused.
108
108
 
109
109
  ## The ledger's readability field: `ledger.ok`
110
110
 
@@ -6,7 +6,7 @@ Why member name load-bearing, why every member single-use, how a member's job ou
6
6
 
7
7
  ## Every member is named
8
8
 
9
- 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#>` (the finisher gate'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).
9
+ 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 is recorded on the PR's row with `ledger.mjs review <pr#>`, its result by the `review-result` wake), `finisher-pr-<pr#>` (the finisher gate'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).
10
10
 
11
11
  ## The coordination contract
12
12
 
@@ -191,7 +191,7 @@ A mismatch on a ticket whose issue is already CLOSED holds nothing: the tick pro
191
191
 
192
192
  ## Dispatching the members a wake names, in full
193
193
 
194
- - **The reviewer.** **Dispatch the review, never wait on it, and act when its result lands. That is the default path.** `DISPATCH review PR#<M>`: a `task` member named `review-pr-<pr#>`, agent `fleet-review-runner`, its prompt the five args `pr`, `branch`, `worktree`, `testCmd` and `scratch`. Record `review=member:review-pr-<pr#>` on the PR's row before the call. `scratch` is the scratch root itself, never a `pr<N>` partition (`references/reviewers.md`). Write the `review=` token with `ledger.mjs review <pr> <token>`; `ledger.mjs` refuses a bad grammar. The tick names every PR owed one, oldest first, and each gets one review, once per PR. The tick counts in-flight reviews off the ledger and nowhere else, so a review you launched and never recorded is one it names again. The runner writes the result file and reports its path and `reviewed=` token.
194
+ - **The reviewer.** **Dispatch the review, never wait on it, and act when its result lands. That is the default path.** `DISPATCH review PR#<M>`: a `task` member named `review-pr-<pr#>`, agent `fleet-review-runner`, its prompt the five args `pr`, `branch`, `worktree`, `testCmd` and `scratch`. Record `review=member:review-pr-<pr#>` on the PR's row before the call. `scratch` is the scratch root itself, never a `pr<N>` partition (`references/reviewers.md`). Write the `review=` token with `ledger.mjs review <pr> <token>`; `ledger.mjs` refuses a bad grammar. The tick names every PR owed one, oldest first, and each gets one review, once per PR. The tick counts in-flight reviews off the ledger and nowhere else, so a review you launched and never recorded is one it names again. The runner writes the result file and reports its path; the `fleet-event.mjs review-result <pr> <path>` wake records its `reviewed=`.
195
195
  A row with `review=` and no `reviewed=` is a review in flight, and the tick counts it as a live review unit unless gh reports its PR MERGED or CLOSED.
196
196
  - **The fix-applier.** `DISPATCH fix-pr PR#<M>` on a `reviewed=` count that survived or unverified findings, with no fix-applier live: name `fix-pr-<pr#>` (the next suffix if that name is on record), never the PR's implementer; render with `dispatch-prompt.mjs render fix-applier --kind review --member fix-pr-<pr#> …`, then record `ledger.mjs dispatch <pr#> fix-pr-<pr#>` before the call. Its brief carries the PR number, the worktree abs path, the PR's branch, the same `testCmd` you passed the review, and the **path** `<scratch>/pr<pr>/<run>/review.json`, `<run>` off the PR's latest `reviewed=` — never the findings. Every `<scratch>` in that brief is the absolute path `scratch-root.mjs` printed. Its rulings are the fix-applier body's (`agents/fleet-fix-applier.agent.md`); you hold none. It holds every finding and you hold none, so there is nothing for you to rank, relay or pre-rule — and a report from a refuter it spawns that surfaces to you is its to retrieve, never yours to scan or pass on. It answers the hold and nothing else: survived or unverified findings of a returned review the row also carries stay unanswered through its settle, so the tick prints `DISPATCH fix-pr PR#<M>` again once it lands, and that one is a review fix-applier, dispatched as above. On a PR carrying `ready-to-merge`, the push moves the head after the label, so the next merge bot refuses it `head-moved-after-label-#<M>` and its report's settle takes the label off; then a fresh finisher, per **Failure handling**.
197
197
  - **The conflict hold.** `DISPATCH fix-pr PR#<M>` on a conflict hold: the row carries an unresolved `conflict-hold:#<M>`, the merge bot's or one you recorded off the tick's `CONFLICT` line. It is the same slot with a different job, and no review file to hand over. Name it `fix-pr-<M>`, or the next suffix (`-b`, `-c` …) when that name is on record; render with `dispatch-prompt.mjs render fix-applier --kind conflict --member <name> …`; dispatch with the `agent` `ledger.mjs dispatch` printed, in the PR's existing worktree. Read the definition off that output (`fleet-fix-applier` whatever the row's `tier=`), never recall it. Settle `applied:<head>`, or `no-op` if no conflict was left, which lifts the merge hold; a dispatched-but-live one does not, and `failed`/`killed` leave the PR fix-due for a replacement, but a second `failed` since the PR's latest review escalates (`ESCALATE fix-failed`).