@feigi/fleet-ctl 3.36.1 → 3.37.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -66,7 +66,9 @@ redid the whole snapshot/fan-out sequence from scratch.
66
66
  - `status: "completed"` → first line `<your name>: completed <path>` — the
67
67
  member name you were dispatched as, `review-pr-<pr>` or a later letter —
68
68
  then the returned `path`, `ledger`, `attempts`, `errors` and `digest`,
69
- verbatim, as JSON. `errors` is non-empty when the first attempt failed
69
+ verbatim, as JSON. `ledger` is the `reviewed=` token the controller
70
+ records on the PR's row with `ledger.mjs review <pr>`; you write no
71
+ ledger token yourself. `errors` is non-empty when the first attempt failed
70
72
  and the retry completed — report it anyway.
71
73
  - `status: "failed"` → first line `<your name>: failed`, then both
72
74
  `errors` verbatim. Do not run the cell again — the one retry already
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@feigi/fleet-ctl",
3
- "version": "3.36.1",
3
+ "version": "3.37.1",
4
4
  "description": "Agent fleet: run-team controller, merge bot, PR reviewer, and the ticket pipeline they share",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
@@ -672,7 +672,7 @@ export function deriveRun({ rows, dispatched, drain }, prs, closed = new Set(),
672
672
  const m = REVIEWED.exec(tok);
673
673
  if (!m && REVIEWED_RUNLESS.test(tok)) {
674
674
  throw new LedgerError(`${where}: '${tok}' names no review run — reviewed= is now <head>:<survived>/<refuted>/<unverified>:<run>, `
675
- + "<run> the run-XXXXXXXX directory holding that review's review.json; rewrite the token with `ledger.mjs row`");
675
+ + "<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>`");
676
676
  }
677
677
  if (!m) throw new LedgerError(`${where}: '${tok}' is not reviewed=<head>:<survived>/<refuted>/<unverified>:<run>`);
678
678
  latestFinisher = null;
@@ -16,7 +16,8 @@
16
16
  // `ports=`, `ci=`, `held-behind:#M`, `conflict-hold:#<pr>`, the
17
17
  // `review=`/`reviewed=` pair, the `→ PR#M` arrow) is not a member. The
18
18
  // review pair has a grammar of its own below, REVIEW and REVIEWED, which
19
- // `ledger.mjs row` checks a write against before it lands.
19
+ // `ledger.mjs review` writes and `ledger.mjs row` checks a write against
20
+ // before it lands.
20
21
 
21
22
  import { createHash } from "node:crypto";
22
23
 
@@ -226,11 +227,55 @@ function nextReviewer(launches, pr) {
226
227
  return null;
227
228
  }
228
229
 
229
- const OPEN_WAYS_OUT = "wait for its reviewed=, or, once Member-killed confirms its runner dead, settle it =failed in the same rewrite as the new launch";
230
+ 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";
231
+
232
+ /** Whether a word of a row is a review token — `review=…` or `reviewed=…`,
233
+ * parseable or not. `ledger.mjs review` writes these and nothing else. */
234
+ export const isReviewToken = (word) => word.startsWith("review=") || word.startsWith("reviewed=");
235
+
236
+ /**
237
+ * The first review token `line` carries that `oldLine` (null for a new row)
238
+ * does not, duplicates counted, else undefined. `ledger.mjs row` writes none
239
+ * of its own — `ledger.mjs review` puts each on the PR's row, in write order —
240
+ * so a review token a row already holds is carried, never re-judged.
241
+ */
242
+ export function addedReviewToken(oldLine, line) {
243
+ const words = (text) => (text === null ? [] : text.split(/\s+/).filter(isReviewToken));
244
+ return added(words(oldLine), words(line))[0];
245
+ }
246
+
247
+ // Every row key a ledger's rows map to each PR number under rowNums(), in
248
+ // ledger order.
249
+ function prRowKeys(rows) {
250
+ const out = new Map();
251
+ for (const text of rows) {
252
+ const { pr } = rowNums(text);
253
+ if (pr === null) continue;
254
+ if (!out.has(pr)) out.set(pr, []);
255
+ out.get(pr).push(text.split(/\s/)[0]);
256
+ }
257
+ return out;
258
+ }
259
+
260
+ /**
261
+ * `{pr, row}` for the first PR that maps to more than one row in `after` and
262
+ * did not in `before` — `row` the key of the PR's row as `before` holds it,
263
+ * else (`before` held no row for that PR) the first key `after` maps it to —
264
+ * else null. Added only: a split already on the ledger never blocks a write.
265
+ */
266
+ export function newSplitRow(before, after) {
267
+ const was = prRowKeys(before);
268
+ for (const [pr, keys] of prRowKeys(after)) {
269
+ const held = was.get(pr) ?? [];
270
+ if (keys.length > 1 && held.length <= 1) return { pr, row: held[0] ?? keys[0] };
271
+ }
272
+ return null;
273
+ }
230
274
 
231
275
  /**
232
- * Why `ledger.mjs row` must not write `line` over `oldLine` (null for a new
233
- * row), `before` and `after` the ledger's rows on either side of the write —
276
+ * Why `ledger.mjs row` or `ledger.mjs review` must not write `line` over
277
+ * `oldLine` (null for a new row), `before` and `after` the ledger's rows on
278
+ * either side of the write —
234
279
  * or null when it may. Only a violation the write ADDS is a reason: each
235
280
  * rule's offending entries are listed before the write and after it, and the
236
281
  * after list must hold nothing the before list lacks, duplicates counted. Where
@@ -8,12 +8,13 @@
8
8
  // append-only, because their whole purpose is to outlive the reasoning that
9
9
  // produced them; `filed` appends at most one row per issue.
10
10
  //
11
- // `dispatch`, `settle` and `drain` exist so a reader can derive every
12
- // liveness count from this file alone, rather than from row text a controller
13
- // typed by hand: `dispatch` writes a member's live token onto its row and
14
- // appends it to `## Dispatched`, `settle` rewrites that token to
11
+ // `dispatch`, `settle`, `review` and `drain` exist so a reader can derive
12
+ // every liveness count from this file alone, rather than from row text a
13
+ // controller typed by hand: `dispatch` writes a member's live token onto its
14
+ // row and appends it to `## Dispatched`, `settle` rewrites that token to
15
15
  // `<member>=<outcome>` in both places (an implementer's settle to `PR#M` also
16
- // folds the PR's own `#M` row into its ticket's), and `drain` writes the
16
+ // folds the PR's own `#M` row into its ticket's), `review` appends a PR's
17
+ // `review=`/`reviewed=` tokens to the PR's row, and `drain` writes the
17
18
  // one marker that stops supply. The token grammar is
18
19
  // ledger-grammar.mjs's. Within a run `## Dispatched` gains an entry per
19
20
  // dispatch and never loses or reorders one — settling annotates an entry in
@@ -21,8 +22,8 @@
21
22
  // that carries a run's live entries forward carries a settled one only for a
22
23
  // member a carried row names.
23
24
  //
24
- // Writer policy: the controller owns run
25
- // state (`row`/`settle`/`dispatch`/`drain`/`ruled`/`rotate`); filers append
25
+ // Writer policy: the controller owns run state
26
+ // (`row`/`settle`/`dispatch`/`review`/`drain`/`ruled`/`rotate`); filers append
26
27
  // filings with `filed`; all writes are serialized by `<file>.lock`. Every
27
28
  // write subcommand except `rotate` — which moves the file whole and never
28
29
  // loads it, see runRotate() — rewrites the WHOLE file from what it loaded,
@@ -37,7 +38,7 @@ import { fileURLToPath } from "node:url";
37
38
  import { spawnSync, execFileSync } from "node:child_process";
38
39
  import { makeDie, isFlagLike, hasEqualsForm, isDigits } from "./arg.mjs";
39
40
  import { fleetFile, FleetDirUnresolvable } from "./fleet-dir.mjs";
40
- import { parseMember, parseToken, memberTokens, nextMergeBot, liveOnLedger, agentDefinition, CELL, tierValues, rowPr, rowWriteRefusal, ROWS, DISPATCHED, FILED, RULED, DRAIN, headerRe, escapeText, unescapeText } from "./ledger-grammar.mjs";
41
+ import { parseMember, parseToken, memberTokens, nextMergeBot, liveOnLedger, agentDefinition, CELL, tierValues, rowPr, rowWriteRefusal, isReviewToken, addedReviewToken, newSplitRow, premisesOf, ROWS, DISPATCHED, FILED, RULED, DRAIN, headerRe, escapeText, unescapeText } from "./ledger-grammar.mjs";
41
42
  import { deriveRun, LedgerError, labelOffMember } from "./fleet-tick.mjs";
42
43
  import { stateFileIn, readState, writeState, assessBeat, stallsAt } from "./fleet-state.mjs";
43
44
  import { isDead, processSource, ancestry, controllerOf, judgeController, ProcUnreadable } from "./proc.mjs";
@@ -226,7 +227,7 @@ const requireFile = requireFileIdx !== -1;
226
227
  if (requireFileIdx !== -1) argv.splice(requireFileIdx, 1);
227
228
 
228
229
  const [cmd, ...rest] = argv;
229
- if (!cmd) die("usage: ledger.mjs [--file <path>] [--require-file] row|filed|ruled|check|read|dispatch|settle|drain|rotate [args]");
230
+ if (!cmd) die("usage: ledger.mjs [--file <path>] [--require-file] row|filed|ruled|check|read|dispatch|settle|review|drain|rotate [args]");
230
231
 
231
232
  // A `--`-prefixed token in `check`'s free-text tail used to fold
232
233
  // straight into the duplicate-filing subject, so a misspelled flag searched
@@ -739,7 +740,7 @@ async function acquireLock() {
739
740
  // so a caller gating on the exit code reads the same failure either way.
740
741
  if (requireFile && !existsSync(file)) die(`--require-file given but ledger file does not exist: ${file}`);
741
742
 
742
- const WRITE_COMMANDS = new Set(["row", "filed", "ruled", "dispatch", "settle", "drain", "rotate"]);
743
+ const WRITE_COMMANDS = new Set(["row", "filed", "ruled", "dispatch", "settle", "review", "drain", "rotate"]);
743
744
  if (WRITE_COMMANDS.has(cmd)) await acquireLock();
744
745
  // `rotate` never load()s: a ledger load() would refuse is still the previous
745
746
  // run's record, and it is archived as-is — and read line by line when it
@@ -815,13 +816,28 @@ if (cmd === "read") {
815
816
  }
816
817
  const i = data.rows.findIndex((r) => r.split(/\s/)[0] === key);
817
818
  const created = i === -1;
819
+ const oldRow = created ? null : data.rows[i];
818
820
  const after = created ? [...data.rows, line] : data.rows.with(i, line);
821
+ // Every review token is `review`'s to write, onto the PR's row in write
822
+ // order, so `row` adds none; one the row already holds is carried.
823
+ const reviewToken = addedReviewToken(oldRow, line);
824
+ if (reviewToken !== undefined) {
825
+ 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`);
826
+ }
827
+ // Every token about a PR lives on the PR's row, so a write that makes a PR
828
+ // map to a second row splits its history across two rows the tick reads in
829
+ // row order, not write order. Added only: a split already on disk is
830
+ // carried.
831
+ const split = newSplitRow(data.rows, after);
832
+ if (split !== null) {
833
+ die(`row ${key}: PR #${split.pr} would map to more than one row — its PR's row is ${split.row}; rewrite that row instead`);
834
+ }
819
835
  // A PR's review record is read off its rows — every row mapping to it, in
820
- // ledger order — so a write that adds a result no launch accounts for, a
821
- // second launch while one is open, or drops an open launch makes the tick
822
- // re-ignite or lose a review. Refused here, before anything is written;
823
- // what the ledger already held is carried, never re-judged. Local only.
824
- const refusal = rowWriteRefusal(data.rows, after, created ? null : data.rows[i], line);
836
+ // ledger order — so a write that drops an open launch makes the tick lose
837
+ // a review. Refused here, with a member named twice on one line, before
838
+ // anything is written; what the ledger already held is carried, never
839
+ // re-judged. Local only.
840
+ const refusal = rowWriteRefusal(data.rows, after, oldRow, line);
825
841
  if (refusal !== null) die(`row ${key}: ${refusal}`);
826
842
  data.rows = after;
827
843
  // Logged only after save() returns — a failed write must not claim a row
@@ -881,6 +897,8 @@ if (cmd === "read") {
881
897
  runDispatch();
882
898
  } else if (cmd === "settle") {
883
899
  runSettle();
900
+ } else if (cmd === "review") {
901
+ runReview();
884
902
  } else if (cmd === "drain") {
885
903
  // One marker per run. A second `drain` — a replacement controller that
886
904
  // cannot tell whether its predecessor got this far — is answered with the
@@ -902,7 +920,7 @@ if (cmd === "read") {
902
920
  if (rest.length) die("usage: ledger.mjs rotate");
903
921
  runRotate();
904
922
  } else {
905
- die(`unknown subcommand '${cmd}' — expected row, filed, ruled, check, read, dispatch, settle, drain or rotate`);
923
+ die(`unknown subcommand '${cmd}' — expected row, filed, ruled, check, read, dispatch, settle, review, drain or rotate`);
906
924
  }
907
925
 
908
926
  // `check` alone of the subcommands leaves its arm early: the already-filed
@@ -1698,17 +1716,21 @@ function carries(row, name, live) {
1698
1716
  return memberTokens(row).some((t) => t.name === name && (live === undefined || (t.outcome === null) === live));
1699
1717
  }
1700
1718
 
1719
+ // The PR's row: the row whose PR is `pr` — ledger-grammar.mjs's rowPr(), the
1720
+ // reading the tick folds that PR's state by — else one keyed by that PR's own
1721
+ // number (a PR this run's implementers did not open, or have not settled to
1722
+ // yet). -1 when there is none yet. Every token about the PR belongs there.
1723
+ function prRowIndex(pr) {
1724
+ const i = data.rows.findIndex((r) => rowPr(r) === pr);
1725
+ return i !== -1 ? i : data.rows.findIndex((r) => rowKey(r) === `#${pr}`);
1726
+ }
1727
+
1701
1728
  // The row a member's token belongs on: an implementer's is its ticket's row; a
1702
- // PR-bound member's is the row whose PR is its PR — ledger-grammar.mjs's
1703
- // rowPr(), the reading the tick folds that PR's state by — else one keyed by
1704
- // that PR's own number (a PR this run's implementers did not open). -1 when there is
1705
- // none yet. A merge bot works no ticket and never has one.
1729
+ // PR-bound member's is its PR's row. -1 when there is none yet. A merge bot
1730
+ // works no ticket and never has one.
1706
1731
  function memberRowIndex(member) {
1707
1732
  if (member.bound === null) return -1;
1708
- if (member.bound === "pr") {
1709
- const i = data.rows.findIndex((r) => rowPr(r) === member.number);
1710
- if (i !== -1) return i;
1711
- }
1733
+ if (member.bound === "pr") return prRowIndex(member.number);
1712
1734
  return data.rows.findIndex((r) => rowKey(r) === `#${member.number}`);
1713
1735
  }
1714
1736
 
@@ -1990,19 +2012,16 @@ function runSettle() {
1990
2012
  // token — would let the fold misattribute
1991
2013
  // its content to the wrong PR, or bury the row's own fresher
1992
2014
  // `review=`/`reviewed=` state under the folded row's older one (the tick
1993
- // reads only the LAST). The candidate row must itself carry a live or
1994
- // settled PR-bound token for this exact PR — never an unrelated row that
1995
- // merely shares the key (an Exclusion row, say, on a mistyped PR number) —
1996
- // unless the row holds nothing past its key at all, in which case there is
1997
- // nothing it could be but an empty fallback and nothing to lose by
1998
- // folding it. Never one an implementer already claims as its own.
2015
+ // reads only the LAST). Any row keyed to the PR that no implementer claims
2016
+ // as its own is folded, a review-only one included: no token about the PR
2017
+ // can sit on this row before it names `PR#M`, so the folded row's tail,
2018
+ // appended after this row's tokens, keeps write order. An Exclusion row is
2019
+ // never folded: it is keyed to a TICKET number, so one keyed `#M` here is
2020
+ // an unrelated ticket's premise on a mistyped PR number, and folding it
2021
+ // would delete state a settled member can never restore.
1999
2022
  const prNum = outcome.startsWith("PR#") ? Number(outcome.slice("PR#".length)) : null;
2000
2023
  const j = prNum === null || i === -1 || priorPr !== null ? -1
2001
- : data.rows.findIndex((r) => {
2002
- if (rowKey(r) !== `#${prNum}` || memberTokens(r).some((t) => t.family === "impl")) return false;
2003
- const tail = r.slice(`#${prNum}`.length).trim();
2004
- return tail === "" || memberTokens(r).some((t) => t.bound === "pr" && t.number === prNum);
2005
- });
2024
+ : data.rows.findIndex((r) => rowKey(r) === `#${prNum}` && !memberTokens(r).some((t) => t.family === "impl") && premisesOf(r) === null);
2006
2025
  if (j !== -1) {
2007
2026
  const tail = data.rows[j].slice(`#${prNum}`.length).trim();
2008
2027
  if (tail !== "") data.rows[i] = `${data.rows[i]} · ${tail}`;
@@ -2013,3 +2032,48 @@ function runSettle() {
2013
2032
  console.error(` settled ${token}`);
2014
2033
  console.log(JSON.stringify(payload(i, true)));
2015
2034
  }
2035
+
2036
+ // `review <pr> <token>…`: the only writer of a PR's `review=`/`reviewed=`
2037
+ // tokens. Each lands on the PR's row — the ticket row once `settle
2038
+ // impl-<N>=PR#M` has run, else `#M`, created when neither exists — so the
2039
+ // row's token order is write order, the order the tick folds the PR's review
2040
+ // record in. `review=X=failed` for a launch the row holds open as `review=X`
2041
+ // rewrites that token in place; every other token is appended as ` · <token>`.
2042
+ // The whole ledger before and after is judged by rowWriteRefusal() under the
2043
+ // lock, and a refusal writes nothing.
2044
+ function runReview() {
2045
+ const usage = "usage: ledger.mjs review <pr> <review=…|reviewed=…>…";
2046
+ const [pr, ...parts] = rest;
2047
+ if (!pr || parts.length === 0) die(usage);
2048
+ refuseStrayInId(pr, "a PR number");
2049
+ const digits = pr.replace(/^#/, "");
2050
+ if (!isDigits(digits)) die(`'${pr}' is not a PR number — ${usage}`);
2051
+ const prNum = Number(digits);
2052
+ const tokens = parts.join(" ").split(/\s+/).filter(Boolean);
2053
+ const other = tokens.find((tok) => !isReviewToken(tok));
2054
+ if (other !== undefined) {
2055
+ die(`review #${prNum}: '${other}' is not a review token — review writes only review=… and reviewed=…; every other token goes through row, dispatch or settle`);
2056
+ }
2057
+ const i = prRowIndex(prNum);
2058
+ const created = i === -1;
2059
+ const oldLine = created ? null : data.rows[i];
2060
+ const words = created ? [`#${prNum}`] : oldLine.split(/(\s+)/);
2061
+ const appended = [];
2062
+ for (const tok of tokens) {
2063
+ const open = tok.endsWith("=failed") ? words.lastIndexOf(tok.slice(0, -"=failed".length)) : -1;
2064
+ if (open > 0) words[open] = tok;
2065
+ else appended.push(tok);
2066
+ }
2067
+ const head = words.join("");
2068
+ const line = appended.length === 0 ? head
2069
+ : created ? `${head} ${appended.join(" · ")}`
2070
+ : `${head} · ${appended.join(" · ")}`;
2071
+ const after = created ? [...data.rows, line] : data.rows.with(i, line);
2072
+ const refusal = rowWriteRefusal(data.rows, after, oldLine, line);
2073
+ if (refusal !== null) die(`review #${prNum}: ${refusal}`);
2074
+ data.rows = after;
2075
+ save(data);
2076
+ const key = rowKey(line);
2077
+ console.error(` review on row ${key}`);
2078
+ console.log(JSON.stringify({ pr: prNum, row: key, line, created }));
2079
+ }
@@ -229,7 +229,7 @@ export async function runReviewToFile(args, run = runReviewOnOmp) {
229
229
  return {
230
230
  status: "completed",
231
231
  path,
232
- // The review's result token, ready for `ledger.mjs row`.
232
+ // The review's result token, ready for `ledger.mjs review <pr>`.
233
233
  ledger: `reviewed=${result.head}:${survived}/${refuted}/${unverified}:${basename(runRoot)}`,
234
234
  attempts: attempt,
235
235
  errors,
@@ -551,8 +551,9 @@ phase, or in any later one, asks the maintainer which tickets to take.
551
551
  `impl-`, `fix-pr-`, `finisher-pr-` or `merge-bot-` member is settled:
552
552
  `ledger.mjs settle <name> killed`. A reviewer is no member `settle`
553
553
  takes — `settle review-pr-<n> killed` exits 2 — so its launch is
554
- settled `=failed` where it stands: a `ledger.mjs row` rewrite of its row
555
- that turns `review=member:<name>` into `review=member:<name>=failed`
554
+ settled `=failed` where it stands: a `ledger.mjs review <pr>
555
+ review=member:<name>=failed` call that turns `review=member:<name>` on
556
+ the PR's row into `review=member:<name>=failed`
556
557
  (`fallback:` and `wf:` launches alike), after which the tick owes the PR
557
558
  a review again under the next free reviewer name.
558
559
  - `prior: none` — no record proves the previous run dead (no record yet, or
@@ -1642,13 +1643,14 @@ one `fleet-tick.mjs` invocation, and you do what it prints. There are no hand-ru
1642
1643
  refill or dispatch edges left. Record first, because the tick reads the run off
1643
1644
  `.fleet/ledger.md` and nothing else of yours: a wake you have not written down is
1644
1645
  one it cannot see, and it names the same dispatch again. Every record goes
1645
- through `ledger.mjs` (**Run ledger**) — `settle` for a member's outcome, `row`
1646
- for a token on a ticket's line — never a hand edit.
1646
+ through `ledger.mjs` (**Run ledger**) — `settle` for a member's outcome,
1647
+ `review` for a review token on the PR's row, `row` for any other token on a
1648
+ ticket's line — never a hand edit.
1647
1649
 
1648
1650
  | Wake | Record, then tick |
1649
1651
  |---|---|
1650
1652
  | Implementer report | `verify-sha.sh`; `ledger.mjs settle impl-<N>=PR#<M>`, or `=bailed` and relabel by cause (**Implementer bails before implementing**, below) |
1651
- | Review workflow notification / `review-pr-<n>` report | the result file is `<scratch>/pr<pr>/<run>/review.json`, `<run>` the review's own `run-XXXXXXXX` run root; `reviewed=<head>:<survived>/<refuted>/<unverified>:<run>` on the PR's row (**Reviewers**) |
1653
+ | Review workflow notification / `review-pr-<n>` report | the result file is `<scratch>/pr<pr>/<run>/review.json`, `<run>` the review's own `run-XXXXXXXX` run root; `ledger.mjs review <pr> reviewed=<head>:<survived>/<refuted>/<unverified>:<run>` on the PR's row (**Reviewers**) |
1652
1654
  | Fix-applier report | `ledger.mjs settle fix-pr-<M>=…`; for a fix-applier that answered a review — not one that cleared a conflict hold, which has no review file — `~/.fleet/bin/fleet-run dispositions-check.mjs --member <that member> --scratch <scratch>`, from the checkout root: it judges that member's own record `<scratch>/dispositions-<member>.json` against the review file the PR's latest `reviewed=` names, `<scratch>/pr<M>/<run>/review.json`, writes `dispositions-ok=`, `dispositions-mismatch=`, `dispositions-escalate=` or `dispositions-unchecked=<member>:<run>` onto the PR's row itself, and exits 1 on a mismatch, an escalation or an unchecked, naming each violating or escalated entry's bucket and index, a violation its rule too, and each entry whose filed issue `gh` could not read — **Then dispatch a fix-applier** says what a mismatch asks of you, the gate paragraph below what an escalation or an unchecked does; copy the refutations it reversed — the record's `refuted` entries — to `ruled`; `ledger.mjs filed <N> "<subject>"` for each `unrecorded:` line |
1653
1655
  | Finisher report | `ledger.mjs settle finisher-pr-<M>=labelled` as reported, even when its read-back lacks `ready-to-merge` — the tick's `DISPATCH finisher PR#<M>` catches that next. A **repair** finisher's (one sent on that line) read-back lacking it also gets `gh pr comment <M>` with both finishers' read-backs: the one-shot escalation, where halts comment. `ledger.mjs filed <N> "<subject>"` for each `unrecorded:` line |
1654
1656
  | Finisher report (halted) | `ledger.mjs settle finisher-pr-<M>=halted:<cause>`; `gh pr comment <M>` with the finisher's halt report, cause and evidence; `ledger.mjs filed <N> "<subject>"` for each `unrecorded:` line; then the per-cause rule (**Resolving a finisher halt**, below) |
@@ -1697,7 +1699,7 @@ owes beyond its row:
1697
1699
  whichever point the ticket fails them.
1698
1700
  - **A review result lands** → see the result file written (by you or by the
1699
1701
  runner — **Reviewers** says which, per harness) and record `reviewed=` off its
1700
- digest, then run the tick: a PR with survived or unverified findings prints as
1702
+ digest with `ledger.mjs review <M>`, then run the tick: a PR with survived or unverified findings prints as
1701
1703
  `DISPATCH fix-pr PR#<M>`. No survived or unverified finding and nothing to file → skip the
1702
1704
  fix-applier and dispatch the **finisher** directly: no member will touch that
1703
1705
  PR, so no push is coming and nothing will wake you. A review that failed is
@@ -2223,15 +2225,20 @@ and each gets one review, once per PR:
2223
2225
 
2224
2226
  a `task` member named `review-pr-<pr#>`, agent `fleet-review-runner`, its prompt the five args `pr`, `branch`, `worktree`, `testCmd` and `scratch` — it loads `review-eval.mjs` through the Resolver (`~/.fleet/bin/fleet-run --path review-eval.mjs`), awaits `runReviewOnOmp` in its own kernel, writes the result file into the review's own run root and reports its path and `reviewed=` token; record `review=member:review-pr-<pr#>` on the PR's row before the dispatch call. **`scratch` is the scratch root itself, the absolute path `scratch-root.mjs` prints, never the review side's `<scratch>/pr<N>` partition:** the review creates `pr<N>/` under it, so a `pr<N>` passed in nests every run root at `pr<N>/pr<N>/`, and the review refuses a `scratch` whose last component is `pr` plus digits before dispatching anything.
2225
2227
 
2226
- Write the `review=` token with `ledger.mjs row`, which **replaces the whole
2227
- line**, so carry every other field. The tick counts in-flight reviews off the
2228
+ Write the `review=` token with `ledger.mjs review <pr> <token>`, which appends
2229
+ it to the **PR's row** — the ticket row once `settle impl-<N>=PR#M` has run,
2230
+ else `#M`, created when neither exists — and prints that row's key. `review`
2231
+ is the only writer of `review=`/`reviewed=` tokens, so a PR's tokens sit on
2232
+ one row in the order you wrote them. The tick counts in-flight reviews off the
2228
2233
  ledger and nowhere else, so a review you launched and never recorded is one it
2229
- names again. `row` reads the PR's review record across every row that maps to
2230
- the PR, in ledger order, and refuses a write that adds a `reviewed=` with no
2234
+ names again. `review` reads the PR's review record across every row that maps
2235
+ to the PR, in ledger order, and refuses a write that adds a `reviewed=` with no
2231
2236
  open launch before it, a launch identity the PR already used, a second launch
2232
- while one is open, the removal of an open launch, a member name twice on the
2233
- line, or an unparseable `review=`/`reviewed=` (the ledger's token grammar,
2234
- below). A bad token the ledger already holds is carried, never re-judged.
2237
+ while one is open, or an unparseable `review=`/`reviewed=` (the ledger's token
2238
+ grammar, below), or any token that is not a review token. `row` refuses a
2239
+ write that adds a review token (one the row holds is carried), drops an open
2240
+ launch, names a member twice on the line, or makes a PR map to a second row. A
2241
+ bad token the ledger already holds is carried, never re-judged.
2235
2242
 
2236
2243
  **It is the only path on which `selectDimensions` sizes the fan-out to the
2237
2244
  diff and the verify budget follows severity.** Hand-dispatched (the fallback
@@ -2296,7 +2303,7 @@ and reports the digest, the path and the `reviewed=` token naming that run.
2296
2303
  `jq '{pr, head, resume, testEnvironment, dimensionsRun, dimensionsUnrun, cwdAudit, counts}' <scratch>/pr<pr>/<run>/review.json`
2297
2304
  is the whole of your read, and it is what you record: `reviewed=<head>:<survived>/<refuted>/<unverified>:<run>`,
2298
2305
  off `head`, `counts` and the run root's name — the runner's `ledger` field — on
2299
- the PR's row. Every later path to the review is built from that token, before a
2306
+ the PR's row, with `ledger.mjs review <pr>`. Every later path to the review is built from that token, before a
2300
2307
  restart or after one: `<scratch>/pr<pr>/<run>/review.json`, `<run>` off the PR's
2301
2308
  latest `reviewed=`. Findings never enter your context —
2302
2309
  a result runs 26-61 KB, 7-15k tokens that used to land in yours and then again,
@@ -2370,9 +2377,11 @@ fall back — and whoever holds the review call is who retries:**
2370
2377
  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.
2371
2378
  Either way, settle the dead review by appending `=failed` to its `review=`
2372
2379
  token, then append `review=fallback:<that name>` after it, both in one
2373
- `ledger.mjs row` rewrite — `row` refuses a new launch while the dead one still
2374
- reads open, and the tick takes the last `review=` token on a row as the one in
2375
- flight, so that order is what keeps the fallback counted against the cap. A
2380
+ `ledger.mjs review <pr> review=<dead launch>=failed review=fallback:<that name>`
2381
+ call — `review` settles the dead launch in place, and refuses a new launch
2382
+ while the dead one still reads open, and the tick takes the last `review=`
2383
+ token on a row as the one in flight, so that order is what keeps the fallback
2384
+ counted against the cap. A
2376
2385
  runner member that is killed rather than failed follows **Failure
2377
2386
  handling** (fresh name, inherited state stated).
2378
2387
 
@@ -3266,7 +3275,7 @@ decides the rest — two resolve automatically, every other one escalates:
3266
3275
  | Cause | Resolution |
3267
3276
  |---|---|
3268
3277
  | `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. |
3269
- | `past-pin` | **Automatic, through the tick: re-review.** The head carries commits no reviewer read. The tick prints `DISPATCH review PR#<M>` for a PR whose latest finisher is `halted:past-pin` and whose latest `reviewed=<head>` is not its current head, until a review of it is running or has returned; record that review's tokens as any review's, its runner under the next letter the PR's rows do not carry yet (`review-pr-<M>-b`, or `-c` where a fallback already took `-b`) — `row` refuses a second `review-pr-<M>` and names the free one — and its result reaches a fresh finisher through the same gate. |
3278
+ | `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. |
3270
3279
  | `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. |
3271
3280
  | `unreadable`, `missing`, `absent`, `other` | **Escalate** — comment and flag, no automatic retry. |
3272
3281
 
@@ -3358,7 +3367,7 @@ is present and failing is not absent, and reading this line as absence-only
3358
3367
  leaves the likeliest failure with no sanctioned path at all. One named member
3359
3368
  per PR — `review-pr-<pr#>` while no reviewer on the PR has held that name,
3360
3369
  else the next letter its rows do not carry yet (`-b`, `-c`, …) — never its
3361
- implementer, recorded as `review=fallback:<that name>` on the PR's row. It runs off your turn
3370
+ implementer, recorded as `review=fallback:<that name>` on the PR's row with `ledger.mjs review <pr>`. It runs off your turn
3362
3371
  like the review it replaces. Give it the PR number and tell it to read
3363
3372
  `$(~/.fleet/bin/fleet-run --root)/commands/review-and-fix.md` — the resolved file
3364
3373
  path, not a slash invocation; command availability inside a member is not
@@ -3371,7 +3380,7 @@ findings as a review result file in a run root of its own, made with
3371
3380
  `mktemp -d "<scratch>/pr<pr>/run-XXXXXXXX"` (`<scratch>` the absolute path you
3372
3381
  named in its prompt), in the shape `review-and-fix.md`'s
3373
3382
  **The review result file** describes, and reports that file's path. On its
3374
- report, record `reviewed=<head>:0/<refuted>/<deferred>:<run>`, `<run>` that run
3383
+ report, record `reviewed=<head>:0/<refuted>/<deferred>:<run>` with `ledger.mjs review <pr>`, `<run>` that run
3375
3384
  root's name, against the head it pushed — it applied
3376
3385
  its own survivors, so the zero is what tells the tick no fix-applier is owed for
3377
3386
  them; a nonzero `<deferred>` is still fix-due, as any review's unverified band is —
@@ -4045,7 +4054,7 @@ decides whether a replacement redoes or destroys work.
4045
4054
 
4046
4055
  One git-ignored `.fleet/ledger.md` per run, updated at **every** state change via
4047
4056
  `~/.fleet/bin/fleet-run ledger.mjs` subcommands (`row`, `filed`, `ruled`,
4048
- `check`, `read`, `dispatch`, `settle`, `drain`, `rotate`). Your context is the least
4057
+ `check`, `read`, `dispatch`, `settle`, `review`, `drain`, `rotate`). Your context is the least
4049
4058
  durable thing in the run: it compacts, and a controller that loses the dispatch
4050
4059
  map or the filed list redoes finished work. Two duplicate tickets shipped in one
4051
4060
  run from exactly that.
@@ -4091,12 +4100,19 @@ live count from it, so nobody states one. Write neither by hand:
4091
4100
  halted:<cause>`, `<cause>` one of `live-editor | rebase | past-pin |
4092
4101
  unreadable | missing | absent | other` (**Resolving a finisher halt**);
4093
4102
  `merge-bot-n` = `done | killed`. A settled member stays settled. `settle
4094
- impl-N=PR#M` also folds a `#M` row a PR-bound dispatch made before the settle
4095
- into `#N`'s row, so one row names each PR from then on — but only when `#N`'s
4096
- row named no PR before this write (a second `PR#` on it would misattribute
4097
- the fold, or bury `#N`'s own fresher `review=` state under an older one) and
4098
- `#M`'s row is genuinely the fallback (a live or settled PR-bound token on it,
4099
- or nothing at all) rather than an unrelated row that merely shares the key.
4103
+ impl-N=PR#M` also folds a `#M` row a PR-bound dispatch or a `review` made
4104
+ before the settle into `#N`'s row, so the PR's row is the one row naming
4105
+ each PR from then on — but only when `#N`'s row named no PR before this
4106
+ write (a second `PR#` on it would misattribute the fold, or bury `#N`'s own
4107
+ fresher `review=` state under an older one) and no implementer claims `#M`'s
4108
+ row as its own.
4109
+ - **`ledger.mjs review <pr> <token>…`** — the only writer of `review=` and
4110
+ `reviewed=` (below): appends each to the PR's row — the ticket row once
4111
+ `settle impl-<N>=PR#M` has run, else `#M`, created when neither exists —
4112
+ and prints `{pr, row, line, created}`, `row` the key written. A
4113
+ `review=<launch>=failed` whose `review=<launch>` the row holds settles that
4114
+ launch in place, alone or with the next launch in the same call. Any other
4115
+ token is refused.
4100
4116
  - **`ledger.mjs drain "<reason>"`** — the one drain marker per run; supply
4101
4117
  stops, the review and merge sides keep going. It lives in this run's
4102
4118
  ledger, so the next run's rotation retires it with everything else.
@@ -4115,7 +4131,11 @@ live count from it, so nobody states one. Write neither by hand:
4115
4131
  `row` refuses a malformed member token anywhere in its text — one whose outcome
4116
4132
  is outside the vocabulary above, e.g. `merge-bot-1=dispatched` — at exit 2,
4117
4133
  naming the token and writing nothing, because every reader would take it as a
4118
- permanent settle.
4134
+ permanent settle. It refuses a write that adds a `review=`/`reviewed=` token
4135
+ (one the row already holds is carried), and one after which a PR maps to more
4136
+ than one row when it did not before — `row <M>` creating `#M` for a PR a ticket
4137
+ row maps, or a rewrite adding a `PR#M` mention to another row — naming the
4138
+ PR's row.
4119
4139
 
4120
4140
  `→ PR#M` stays as the human-readable arrow; the tick reads only the `=`
4121
4141
  tokens. `tier=<cell>` marks an Exploration Pull's cell and `route=<REASON>` a router fallback (phase 2), and `excluded ·
@@ -4123,7 +4143,7 @@ behind-pr:#M | behind-issue:#M` is an Exclusion (phase 1) — a ticket row like
4123
4143
  any other, never a section of its own.
4124
4144
 
4125
4145
  A PR's review is not a member, so it carries its own pair of row tokens,
4126
- written with `row` (**Reviewers**): `review=wf:<runId>` |
4146
+ written with `review` onto the PR's row (**Reviewers**): `review=wf:<runId>` |
4127
4147
  `review=member:<name>` | `review=fallback:<name>` at launch, `<name>` being
4128
4148
  `review-pr-<n>` for the PR's first runner and the next letter its rows do not
4129
4149
  carry yet (`review-pr-<n>-b`, `-c`, …) for every later one,
@@ -4143,20 +4163,20 @@ finisher's miss only after the last attempt a `label-off=` names, so without
4143
4163
  it your own removal reads as one. `row` refuses a `label-off=` naming no
4144
4164
  `finisher-pr` member that `## Dispatched` or some row already carries.
4145
4165
 
4146
- `row` holds a PR's review record to these rules, read across every row that
4166
+ `review` holds a PR's review record to these rules, read across every row that
4147
4167
  maps to the PR — its settled `impl-<N>=PR#<M>` token, else its first `PR#`
4148
4168
  mention, else its key — in ledger order. Every `reviewed=` answers the nearest
4149
4169
  earlier launch that is neither answered nor `=failed`. A launch identity (a
4150
4170
  workflow's runId, or a runner's name whichever of member or fallback launched
4151
4171
  it, `=failed` aside) appears once. No launch appears
4152
- while an earlier one is open — unanswered and not `=failed`. A launch open
4153
- before the write is still on one of the PR's rows after it, `=failed` allowed.
4154
- A member name appears once on the line, whatever its outcome. Every
4155
- `review=`/`reviewed=` parses. A write that adds a violation is refused, exit 2,
4156
- nothing written; one already on the ledger and carried forward is not. A
4157
- second launch refused for an open one waits for that one's `reviewed=`, or —
4158
- once the Member-killed row confirms its runner dead — settles it `=failed` in
4159
- the same rewrite as the new launch.
4172
+ while an earlier one is open — unanswered and not `=failed`. Every
4173
+ `review=`/`reviewed=` parses. `row` holds the rest: a launch open before the
4174
+ write is still on one of the PR's rows after it, `=failed` allowed, and a
4175
+ member name appears once on the line, whatever its outcome. A write that adds
4176
+ a violation is refused, exit 2, nothing written; one already on the ledger and
4177
+ carried forward is not. A second launch refused for an open one waits for
4178
+ that one's `reviewed=`, or — once the Member-killed row confirms its runner
4179
+ dead — settles it `=failed` in the same `review` call as the new launch.
4160
4180
 
4161
4181
  Plus two append-only lists:
4162
4182
 
@@ -4171,7 +4191,7 @@ Plus two append-only lists:
4171
4191
  - **ruled** (`ledger.mjs ruled <pr> <decision>`) — PR + decision + one-line reason,
4172
4192
  so a replacement controller does not re-litigate a settled call.
4173
4193
 
4174
- **Writer policy: the controller owns run state (`row`/`settle`/`dispatch`/`drain`/`ruled`);
4194
+ **Writer policy: the controller owns run state (`row`/`settle`/`dispatch`/`review`/`drain`/`ruled`);
4175
4195
  filers append filings with `filed`; all writes are serialized by `<file>.lock`.**
4176
4196
  Every write rewrites the whole file from what it read, so without the lock two
4177
4197
  concurrent writers are last-writer-wins — measured, 8 concurrent `filed` kept
@@ -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 its ledger rows do not carry yet, `review-pr-<pr#>-b`, `-c`, …), `finisher-pr-<pr#>` (Phase 3's finisher), `merge-bot-<n>` (one merge pass; `ledger.mjs dispatch merge-bot` numbers it from the ledger's `## Dispatched` list — a per-run counter, never a PR).
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).
8
8
 
9
9
  ## A depth-2 member cannot dispatch further
10
10
 
@@ -58,7 +58,7 @@ A member's settle outcome and its liveness are different facts, not the same tab
58
58
 
59
59
  Two axes — job outcome (`completed`/`failed`/`cancelled`) crossed with peer liveness (`running`/`idle`/`parked`). `hub cancel` → `cancelled`, the peer hard-aborted and unmessageable, `history://` still readable. A **`failed` job's peer can stay `idle` and resumable**. No distinct truncated state exists.
60
60
 
61
- Recovery = fresh member, fresh name (`impl-<N>-b`, `fix-pr-<M>-b`, and for a reviewer the next letter PR M's rows do not carry yet — `review-pr-<M>-b`, or `-c` where `-b` is taken), whose prompt states what it inherits:
61
+ Recovery = fresh member, fresh name (`impl-<N>-b`, `fix-pr-<M>-b`, and for a reviewer the next letter PR M's row does not carry yet — `review-pr-<M>-b`, or `-c` where `-b` is taken), whose prompt states what it inherits:
62
62
 
63
63
  - committed-and-pushed vs committed-only vs **uncommitted in the worktree**
64
64
  - uncommitted work exists nowhere else — no `git clean`, `git checkout .`,