@feigi/fleet-ctl 3.154.8 → 3.156.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.
@@ -14,12 +14,21 @@
14
14
  // A TREE, for `evictTrees(root)`, is a directory that holds `.git` at its own
15
15
  // top level and whose `git rev-parse --show-toplevel` resolves, by realpath,
16
16
  // to that same directory. A directory that resolves to an enclosing repository
17
- // — one with no `.git` of its own, or with one git cannot read — is never
18
- // stripped, and git is never asked about a directory with no `.git`. The walk
19
- // goes down from `root` at any depth and never follows a symlink, never enters
20
- // a `.git`, and never enters a path it removes (or, in a dry run, would
21
- // remove) as ignored, so a repository inside `node_modules` goes with that
22
- // directory and is not a tree of its own.
17
+ // is never stripped, and git is never asked about a directory with no `.git`.
18
+ // A directory that holds a `.git` of its own but that git does not resolve to
19
+ // itself — git errors, times out or exits non-zero (an unreadable `.git`, a
20
+ // `.git` with no HEAD, dubious ownership), the realpath comparison throws, or
21
+ // git names another top-level — is SKIPPED: not evicted, and named with its
22
+ // reason in `skipped`, never in `failed`. So is a directory the walk cannot
23
+ // look in for a `.git` (any error but ENOENT or ENOTDIR — a parent with no
24
+ // search permission), or cannot list because of EACCES or EPERM, the root
25
+ // included; a directory with more than one reason is named once, the reasons
26
+ // joined. A directory with no `.git` of its own, and one whose listing fails
27
+ // with ENOENT or ENOTDIR, are neither. The walk goes down from `root` at any
28
+ // depth and never follows a symlink, never enters a `.git`, and never enters a
29
+ // path it removes (or, in a dry run, would remove) as ignored, so a repository
30
+ // inside `node_modules` goes with that directory and is not a tree of its own,
31
+ // nor skipped. A skipped directory does not stop the walk.
23
32
  //
24
33
  // No status check, no mark, no restore: a tree is evicted whatever `git status`
25
34
  // says. A claim tree's status check and its mark are evict.mjs's own.
@@ -87,39 +96,57 @@ export function removeIgnored(tree, ignored) {
87
96
  return errors.length ? `could not remove ${errors.join("; ")}` : null;
88
97
  }
89
98
 
90
- // Whether `dir` is a tree: a `.git` of its own, and git answering for this
91
- // directory rather than for an enclosing repository.
92
- function isTree(dir) {
99
+ // What `dir` is to the walk: `{tree: false}` when it holds no `.git` of its
100
+ // own, `{tree: true}` when it does and git answers for this directory rather
101
+ // than for an enclosing repository, and `{skip}` — why — when it holds one and
102
+ // git does not, or when looking for one fails for any reason but its absence.
103
+ function treeVerdict(dir) {
93
104
  try {
94
105
  lstatSync(join(dir, ".git"));
95
- } catch {
96
- return false;
106
+ } catch (e) {
107
+ if (e.code === "ENOENT" || e.code === "ENOTDIR") return { tree: false };
108
+ return { skip: `cannot look for a .git in it (${e.code ?? e.message})` };
97
109
  }
98
110
  const r = git(dir, ["rev-parse", "--show-toplevel"]);
99
- if (r.error || r.status !== 0) return false;
111
+ if (r.error || r.status !== 0) return { skip: `git rev-parse --show-toplevel did not answer for it (${how(r)})` };
112
+ const top = r.stdout.replace(/\n$/, "");
100
113
  try {
101
- return realpathSync(r.stdout.replace(/\n$/, "")) === realpathSync(dir);
102
- } catch {
103
- return false;
114
+ if (realpathSync(top) === realpathSync(dir)) return { tree: true };
115
+ } catch (e) {
116
+ return { skip: `comparing git's top-level ${top} with it failed (${e.code ?? e.message})` };
104
117
  }
118
+ return { skip: `git resolves it to the top-level ${top}, not to itself` };
105
119
  }
106
120
 
121
+ const byPath = (a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
122
+
107
123
  /**
108
- * Evict every tree under `root`, `root` itself included: `{evicted, failed}`.
124
+ * Evict every tree under `root`, `root` itself included:
125
+ * `{evicted, failed, skipped}`.
109
126
  * `evicted` is `[{path, ignored}]` for each tree that held ignored paths — in a
110
127
  * dry run, what `apply` would remove — and a tree holding none is in neither.
111
128
  * `failed` is `[{path, error}]`: a tree whose ignored paths cannot be listed or
112
129
  * all removed, or a directory whose listing fails for any reason but its being
113
- * gone, not a directory, or unreadable. Best-effort: the walk goes on.
130
+ * gone, not a directory, or unreadable. `skipped` is `[{path, reason}]`: a
131
+ * directory the walk cannot evaluate, and so leaves as it is — one that holds
132
+ * a `.git` of its own which git does not resolve to that directory (rev-parse
133
+ * errors, times out or exits non-zero, the realpath comparison throws, or
134
+ * another top-level), one it cannot look in for a `.git`, and one whose listing
135
+ * fails with EACCES or EPERM, each named once with every reason it has. Never a
136
+ * failure, and never a path inside an ignored directory the walk removes.
137
+ * Best-effort: the walk goes on.
114
138
  */
115
139
  export function evictTrees(root, { apply }) {
116
140
  const evicted = [];
117
141
  const failed = [];
142
+ const skipped = [];
118
143
  const skip = new Set();
119
144
  const stack = [root];
120
145
  while (stack.length) {
121
146
  const dir = stack.pop();
122
- if (isTree(dir)) {
147
+ const verdict = treeVerdict(dir);
148
+ const reasons = verdict.skip === undefined ? [] : [verdict.skip];
149
+ if (verdict.tree) {
123
150
  let ignored;
124
151
  try {
125
152
  ignored = ignoredPaths(dir);
@@ -139,16 +166,18 @@ export function evictTrees(root, { apply }) {
139
166
  entries = readdirSync(dir, { withFileTypes: true });
140
167
  } catch (e) {
141
168
  // A directory the walk cannot list or search holds no tree it can reach:
142
- // skipped, as freshUnder() skips one it cannot read, and never a failure.
143
- if (!["ENOENT", "ENOTDIR", "EACCES", "EPERM"].includes(e.code)) failed.push({ path: dir, error: `cannot list it (${e.code ?? e.message})` });
144
- continue;
169
+ // skipped and named, as freshUnder() skips one it cannot read, and never
170
+ // a failure.
171
+ if (e.code === "EACCES" || e.code === "EPERM") reasons.push(`cannot list it (${e.code})`);
172
+ else if (e.code !== "ENOENT" && e.code !== "ENOTDIR") failed.push({ path: dir, error: `cannot list it (${e.code ?? e.message})` });
145
173
  }
174
+ if (reasons.length > 0) skipped.push({ path: dir, reason: reasons.join("; ") });
175
+ if (entries === undefined) continue;
146
176
  for (const e of entries) {
147
177
  if (e.name === ".git" || !e.isDirectory()) continue;
148
178
  const path = join(dir, e.name);
149
179
  if (!skip.has(path)) stack.push(path);
150
180
  }
151
181
  }
152
- const byPath = (a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
153
- return { evicted: evicted.sort(byPath), failed: failed.sort(byPath) };
182
+ return { evicted: evicted.sort(byPath), failed: failed.sort(byPath), skipped: skipped.sort(byPath) };
154
183
  }
@@ -58,9 +58,9 @@
58
58
  // (`.fleet/briefs/<member>.json`) is kind `review` or
59
59
  // `dispositions-retry` — a review fix-applier, not one that cleared a
60
60
  // conflict hold or a red check — and with no `dispositions-*=<member>:`
61
- // token on the PR's rows yet: `dispositions-check.mjs --member <member>
62
- // --scratch <scratch>`, its stdout printed. That script writes its own
63
- // verdict token; its exit 1 is a verdict, its exit 2 a NEED.
61
+ // token on the PR's rows yet: `ledger.mjs dispositions <member> --scratch
62
+ // <scratch>`, its stdout printed. That verb writes the verdict token
63
+ // itself; its exit 1 is a verdict, any other nonzero exit a NEED.
64
64
  // A `failed` outcome takes no dispositions check and runs the Recipe read, below.
65
65
  // The Recipe read, after an `impl-report` settled `blocked` or a `fix-report` settled `failed`, whatever the member's cause: `derive-testcmd.sh . install`, `. check` and `. test`, each `--at origin/main`, from the main checkout, the three reads phase0.mjs's `recipe` step makes (recipe-read.mjs is the one reader of both). All three exit 0: nothing printed, the cache is valid. One refused (exit 1): the refused reads, then `NEED derive-recipe`, which is phase 0's mid-run trigger; a refusal naming `--at` is no cache fault, and the controller fetches and reads again. Exit 3 or any other failure of a read: a `NEED recipe-read …` line carrying the environment fault, since the cache's state is unknown and deriving would not help. A cause local to the member's worktree reads valid from the main checkout and prints nothing. No other outcome runs the reads.
66
66
  // finisher-report <finisher-pr-M[-x]>
@@ -655,23 +655,23 @@ function fixReport(ev, member) {
655
655
  ev.note(`dispositions already checked for ${member}`);
656
656
  return;
657
657
  }
658
- const by = `dispositions-check.mjs --member ${member} --scratch ${ev.scratch}`;
658
+ const by = `ledger.mjs dispositions ${member} --scratch ${ev.scratch}`;
659
659
  const sidecar = join(ev.fleetDir, BRIEFS, `${member}.json`);
660
660
  let kind;
661
661
  try {
662
662
  ({ kind } = JSON.parse(readFileSync(sidecar, "utf8")));
663
663
  } catch (e) {
664
- ev.need(`dispositions-check ${member} — its brief ${sidecar} is unreadable (${e.code ?? e.message}), so whether it answered a review is unknown: run ${by} if it did`);
664
+ ev.need(`dispositions ${member} — its brief ${sidecar} is unreadable (${e.code ?? e.message}), so whether it answered a review is unknown: run ${by} if it did`);
665
665
  return;
666
666
  }
667
667
  if (!REVIEW_FIX_KINDS.has(kind)) {
668
668
  ev.note(`no dispositions check: ${member} was a ${kind} fix-applier`);
669
669
  return;
670
670
  }
671
- const r = node("dispositions-check.mjs", ["--member", member, "--scratch", ev.scratch]);
671
+ const r = node("ledger.mjs", ["dispositions", member, "--scratch", ev.scratch]);
672
672
  ev.print(r.stdout);
673
673
  if (r.status === 0 || r.status === 1) ev.note(`dispositions checked (exit ${r.status})`);
674
- else ev.need(`dispositions-check ${member} — nothing judged (${r.how}): ${said(r)}; run ${by} again`);
674
+ else ev.need(`dispositions ${member} — nothing judged (${r.how}): ${said(r)}; run ${by} again`);
675
675
  }
676
676
 
677
677
  const listed = (labels) => (labels.length === 0 ? "(none)" : labels.join(", "));
@@ -1291,7 +1291,7 @@ export function deriveRun({ rows, dispatched, drain, retired = [] }, prs, queued
1291
1291
  // `ledger.mjs dispatch` gates a finisher off this, read from the same
1292
1292
  // per-PR fold as everything above, `ledger.mjs settle --from-report`
1293
1293
  // checks a fix-applier's `no-op` against `fleetHead`, and
1294
- // dispositions-check.mjs reads the review file it judges against off
1294
+ // `ledger.mjs dispositions` reads the review file it judges against off
1295
1295
  // `run`. Nothing in this tick acts on it.
1296
1296
  reviewed: [...byPr.entries()].filter(([, st]) => st.reviewedHead !== null)
1297
1297
  .map(([n, st]) => ({
@@ -265,8 +265,8 @@ function streams(rows) {
265
265
  /** Every token of PR `pr`'s stream, in ledger row order: the tokens firstReview() reads. */
266
266
  export const prTokens = (rows, pr) => streams(rows).get(pr) ?? [];
267
267
 
268
- // dispositions-check.mjs's verdict on a review fix-applier's disposition
269
- // record: `dispositions-ok=fix-pr-<M>[-x]:<run>`,
268
+ // The verdict `ledger.mjs dispositions` derives from a review fix-applier's
269
+ // disposition record: `dispositions-ok=fix-pr-<M>[-x]:<run>`,
270
270
  // `dispositions-mismatch=…`, `dispositions-escalate=…` (a critical or
271
271
  // important deferral, or a second mismatch on one review, that the
272
272
  // maintainer answers) or `dispositions-unchecked=…` (no rule broke, but where
@@ -274,10 +274,10 @@ export const prTokens = (rows, pr) => streams(rows).get(pr) ?? [];
274
274
  // record answers, as its `reviewed=` names it. `ledger.mjs dispatch` refuses a
275
275
  // finisher on anything but an ok. A mismatch returns the PR to fixDue for one
276
276
  // retry. An escalate clears one of two ways: the maintainer's escalation
277
- // answers, recorded through dispositions-check.mjs, replace an escalate over
277
+ // answers, recorded through `ledger.mjs dispositions`, replace an escalate over
278
278
  // a deferral outside the PR's diff with the verdict they give, and a second
279
279
  // mismatch on one review clears only when a new review of the PR counts again
280
- // from none. An unchecked is answered by running the check again, so the tick
280
+ // from none. An unchecked is answered by running the verb again, so the tick
281
281
  // offers no fix-applier for it. A token outside this shape is no verdict at
282
282
  // all, which the gate reads as unchecked: fail closed.
283
283
  export function dispositionsToken(tok) {
@@ -289,7 +289,8 @@ export function dispositionsToken(tok) {
289
289
  }
290
290
 
291
291
  // The maintainer's answer to one finding a fix-applier's record escalated, as
292
- // dispositions-check.mjs writes it onto the PR's row, and the only writer:
292
+ // `ledger.mjs dispositions` writes it onto the PR's row with `--uphold` or
293
+ // `--send-back`, and the only writer:
293
294
  // `escalation-answer=<run>:<bucket>[<index>]:upheld` (the deferral stands) or
294
295
  // `…:sent-back` (the finding is applied in this PR). `<run>` is the run of the
295
296
  // review whose escalation it answers, as its `reviewed=` names it, and
@@ -327,8 +328,8 @@ export function escalationAnswers(tokens, run) {
327
328
  * verdict anywhere on the stream names its run. A review with findings no
328
329
  * fix-applier answered was superseded, and is skipped; a failed review wrote
329
330
  * no `reviewed=`, and is no review. `answered` names runs answered on top of
330
- * the ledger's: dispositions-check.mjs passes the run of the record it is
331
- * checking, whose verdict is not written yet. `{head, survived, refuted,
331
+ * the ledger's: `ledger.mjs dispositions` passes the run of the record it is
332
+ * judging, whose verdict is not written yet. `{head, survived, refuted,
332
333
  * unverified, run}`, or null when no review qualifies.
333
334
  */
334
335
  export function firstReview(tokens, answered = []) {
@@ -440,6 +441,74 @@ export function addedReviewToken(oldLine, line) {
440
441
  return added(words(oldLine), words(line))[0];
441
442
  }
442
443
 
444
+ // A Gate verdict is a ledger token a dispatch gate reads: a dispositions
445
+ // verdict, an Escalation answer or a `reviewed=`. A dispositions verdict and
446
+ // an answer are written only by `ledger.mjs dispositions`, which derives them
447
+ // from their evidence; the one input an argument supplies there is the
448
+ // 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`.
451
+
452
+ /** Whether `word` begins like a dispositions verdict or an Escalation answer,
453
+ * parseable or not: the words `ledger.mjs token` refuses. The dispositions
454
+ * prefixes are matched case-insensitively, as dispositionsToken() parses them. */
455
+ export const isDispositionsWord = (word) => /^dispositions-(?:ok|mismatch|escalate|unchecked)=/i.test(word) || word.startsWith("escalation-answer=");
456
+
457
+ /** Whether `word` is a Gate verdict: one dispositionsToken(),
458
+ * escalationAnswerToken() or REVIEWED parses. */
459
+ export const isGateVerdict = (word) => dispositionsToken(word) !== null || escalationAnswerToken(word) !== null || REVIEWED.test(word);
460
+
461
+ // A word shaped like a Gate verdict that none of the three parses.
462
+ const malformedGateWord = (word) => (isDispositionsWord(word) || word.startsWith("reviewed=")) && !isGateVerdict(word);
463
+
464
+ /** The command that writes the Gate verdict `word` is shaped like, for a
465
+ * refusal to name. */
466
+ export function gateVerdictWriter(word) {
467
+ if (word.startsWith("reviewed=")) return "`fleet-event.mjs review-result <pr> <path>`";
468
+ if (word.startsWith("escalation-answer=")) return "`ledger.mjs dispositions <member> --scratch <scratch> --uphold '<list>' --send-back '<list>'`";
469
+ const member = dispositionsToken(word)?.member.name ?? "<member>";
470
+ return `\`ledger.mjs dispositions ${member} --scratch <scratch>\``;
471
+ }
472
+
473
+ /**
474
+ * Why `ledger.mjs row` must not write `line` over `oldLine` (null for a new
475
+ * row), or null when it may: the row's Gate verdicts, in row order, must
476
+ * equal the rewrite's. That refuses adding, changing, dropping or reordering
477
+ * one, and a whole-row wipe of a row that holds one. A row holding a Gate
478
+ * verdict keeps its PR, as rowNums() reads it: a rewrite that carries every
479
+ * verdict but maps the row to another PR moves them off their own PR's
480
+ * stream, so it is refused too. A verdict-shaped word no grammar parses is
481
+ * held to the one-way half: adding one is refused, dropping one is allowed,
482
+ * so a runless `reviewed=` and a legacy head-named verdict can still be
483
+ * cleaned off a row.
484
+ */
485
+ export function gateVerdictRefusal(oldLine, line) {
486
+ const words = (text) => (text === null ? [] : text.split(/\s+/).filter(Boolean));
487
+ const [was, now] = [words(oldLine), words(line)];
488
+ const [before, after] = [was.filter(isGateVerdict), now.filter(isGateVerdict)];
489
+ const carried = "a rewrite carries every Gate verdict exactly as the row holds it";
490
+ const badWord = added(was.filter(malformedGateWord), now.filter(malformedGateWord))[0];
491
+ if (badWord !== undefined) {
492
+ return `adds '${badWord}', a word shaped like a Gate verdict that no grammar parses — ${carried}; ${gateVerdictWriter(badWord)} writes the verdict`;
493
+ }
494
+ if (before.length === after.length && before.every((w, i) => w === after[i])) {
495
+ if (before.length === 0) return null;
496
+ const [from, to] = [rowNums(oldLine).pr, rowNums(line).pr];
497
+ if (from === to) return null;
498
+ const name = (pr) => (pr === null ? "no PR" : `PR #${pr}`);
499
+ return `moves its Gate verdicts from ${name(from)} to ${name(to)} — ${carried}, on the PR it maps to`;
500
+ }
501
+ const gained = added(before, after)[0];
502
+ if (gained !== undefined) {
503
+ return `adds or changes Gate verdict '${gained}' — ${carried}; ${gateVerdictWriter(gained)} writes it`;
504
+ }
505
+ const lost = added(after, before)[0];
506
+ if (lost !== undefined) {
507
+ return `drops Gate verdict '${lost}' — ${carried}; ${gateVerdictWriter(lost)} writes it again`;
508
+ }
509
+ return `reorders its Gate verdicts — ${carried}`;
510
+ }
511
+
443
512
  // Every row key a ledger's rows map to each PR number under rowNums(), in
444
513
  // ledger order.
445
514
  function prRowKeys(rows) {
@@ -39,11 +39,19 @@
39
39
  // name whose outcome is outside its family's vocabulary — into
40
40
  // `## Retired`, where `dispatch` and that numbering still read it.
41
41
  //
42
- // Writer policy: the controller owns run state
43
- // (`row`/`token`/`settle`/`dispatch`/`review`/`drain`/`ruled`/`rotate`); filers append
44
- // filings with `filed`; all writes are serialized by `<file>.lock`. Every
45
- // write subcommand except `rotate` — which moves the file whole and never
46
- // loads it, see runRotate() — rewrites the WHOLE file from what it loaded,
42
+ // Writer policy: a Gate verdict — a dispositions verdict, an Escalation
43
+ // answer, a `reviewed=` — is written only by its own verb, whoever calls it:
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`
47
+ // refuses all three, and `row` carries every Gate verdict exactly as the row
48
+ // holds it, so no other verb adds, changes or drops one. `filed` appends
49
+ // filings, and all writes are serialized by `<file>.lock`; the other tokens
50
+ // of a row are freeform to the writers that have them (`row`/`token`/
51
+ // `settle`/`dispatch`/`drain`/`ruled`/`rotate`). Every write subcommand
52
+ // except `rotate` — which moves the file whole and never loads it, see
53
+ // runRotate() — rewrites the WHOLE file
54
+ // from what it loaded,
47
55
  // so two unlocked writers are last-writer-wins — measured, 8 concurrent
48
56
  // `filed` kept 2-5 of 8 rows — and the lock is what lets a second kind of
49
57
  // writer exist at all. The reasoning for each part of the lock lives at
@@ -63,7 +71,7 @@ import { spawnSync, execFileSync } from "node:child_process";
63
71
  import { makeDie, isFlagLike, hasEqualsForm, isDigits, writeAll } from "./arg.mjs";
64
72
  import { fleetFile, FleetDirUnresolvable } from "./fleet-dir.mjs";
65
73
  import { readReceipt } from "./phase0-receipt.mjs";
66
- import { parseMember, parseToken, memberTokens, nextMergeBot, nextRetry, liveOnLedger, settledOnLedger, retiredOnLedger, retiredName, readRetired, agentDefinition, expectedDefinition, CELL, POLICY_CELL, tierValues, cellValues, decidingCell, rowPr, rowWriteRefusal, isReviewToken, addedReviewToken, newSplitRow, splitRowClause, added, premisesOf, MEMBER_FAMILIES, HALT_CAUSES, ROWS, DISPATCHED, ROUTED, FILED, RULED, DRAIN, RETIRED, RECEIPT, archiveStamp, receiptArchiveName, CLOSEOUT_RECEIPT, closeoutArchiveName, BRIEFS, briefsArchiveName, memberRole, parseDispatchedEntry, dispatchedEntry, parseRouting, parseRoutedEntry, routedEntry, headerRe, escapeText, ledgerSection, nextReviewerName, isOmpSessionDirName } from "./ledger-grammar.mjs";
74
+ import { parseMember, parseToken, memberTokens, nextMergeBot, nextRetry, liveOnLedger, settledOnLedger, retiredOnLedger, retiredName, readRetired, agentDefinition, expectedDefinition, CELL, POLICY_CELL, tierValues, cellValues, decidingCell, rowPr, rowNums, rowWriteRefusal, isReviewToken, addedReviewToken, isDispositionsWord, gateVerdictWriter, gateVerdictRefusal, newSplitRow, splitRowClause, added, premisesOf, MEMBER_FAMILIES, HALT_CAUSES, ROWS, DISPATCHED, ROUTED, FILED, RULED, DRAIN, RETIRED, RECEIPT, archiveStamp, receiptArchiveName, CLOSEOUT_RECEIPT, closeoutArchiveName, BRIEFS, briefsArchiveName, memberRole, parseDispatchedEntry, dispatchedEntry, parseRouting, parseRoutedEntry, routedEntry, headerRe, escapeText, ledgerSection, nextReviewerName, isOmpSessionDirName } from "./ledger-grammar.mjs";
67
75
  import { deriveRun, LedgerError, labelOffMember, CONFLICT_HOLD, PARKED } from "./fleet-tick.mjs";
68
76
  import { stateFileIn, readState, writeState, assessBeat, stallsAt } from "./fleet-state.mjs";
69
77
  import { processSource, ancestry, controllerOf, judgeController, ProcUnreadable } from "./proc.mjs";
@@ -284,7 +292,7 @@ const requireFile = requireFileIdx !== -1;
284
292
  if (requireFileIdx !== -1) argv.splice(requireFileIdx, 1);
285
293
 
286
294
  const [cmd, ...rest] = argv;
287
- if (!cmd) die("usage: ledger.mjs [--file <path>] [--require-file] row|token|filed|ruled|check|read|dispatch|settle|review|drain|undrain|rotate [args]");
295
+ if (!cmd) die("usage: ledger.mjs [--file <path>] [--require-file] row|token|filed|ruled|check|read|dispatch|settle|review|dispositions|drain|undrain|rotate [args]");
288
296
 
289
297
  // A `--`-prefixed token in `check`'s free-text tail used to fold
290
298
  // straight into the duplicate-filing subject, so a misspelled flag searched
@@ -700,14 +708,16 @@ async function acquireLock() {
700
708
  // so a caller gating on the exit code reads the same failure either way.
701
709
  if (requireFile && !existsSync(file)) die(`--require-file given but ledger file does not exist: ${file}`);
702
710
 
703
- const WRITE_COMMANDS = new Set(["row", "token", "filed", "ruled", "dispatch", "settle", "review", "drain", "undrain", "rotate"]);
711
+ const WRITE_COMMANDS = new Set(["row", "token", "filed", "ruled", "dispatch", "settle", "review", "dispositions", "drain", "undrain", "rotate"]);
704
712
  // `settle --from-report` takes the lock itself, once its checks have run —
705
- // see runSettleFromReport().
713
+ // see runSettleFromReport(). So does `dispositions`, once every git, gh and
714
+ // file read has run — see runDispositions().
706
715
  const FROM_REPORT = cmd === "settle" && rest.includes("--from-report");
716
+ const LATE_LOCK = FROM_REPORT || cmd === "dispositions";
707
717
  // A merge bot's dispatch reads the queue it records before the lock, for the
708
718
  // same reason: a gh call held under the lock stalls every other writer.
709
719
  const QUEUED = cmd === "dispatch" && rest.length === 1 && /^merge-bot(-[0-9]+)?$/.test(rest[0]) ? queueSnapshot() : null;
710
- if (WRITE_COMMANDS.has(cmd) && !FROM_REPORT) await acquireLock();
720
+ if (WRITE_COMMANDS.has(cmd) && !LATE_LOCK) await acquireLock();
711
721
  // `rotate` never load()s: a ledger load() would refuse is still the previous
712
722
  // run's record, and it is archived as-is — and read line by line when it
713
723
  // carries live members forward, see carryOf().
@@ -796,6 +806,11 @@ if (cmd === "read") {
796
806
  if (reviewToken !== undefined) {
797
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`);
798
808
  }
809
+ // Every Gate verdict is its own verb's to write, so a rewrite carries the
810
+ // row's as they stand — none added, changed, dropped or reordered, which
811
+ // also refuses a whole-row wipe of a row that holds one.
812
+ const gateWhy = gateVerdictRefusal(oldRow, line);
813
+ if (gateWhy !== null) die(`row ${key}: ${gateWhy}`);
799
814
  // Every token about a PR lives on the PR's row, so a write that makes a PR
800
815
  // map to a second row splits its history across two rows the tick reads in
801
816
  // row order, not write order. Added only: a split already on disk is
@@ -901,6 +916,8 @@ if (cmd === "read") {
901
916
  runToken();
902
917
  } else if (cmd === "review") {
903
918
  runReview();
919
+ } else if (cmd === "dispositions") {
920
+ await runDispositions();
904
921
  } else if (cmd === "drain") {
905
922
  // One marker per run. A second `drain` — a replacement controller that
906
923
  // cannot tell whether its predecessor got this far — is answered with the
@@ -932,7 +949,7 @@ if (cmd === "read") {
932
949
  if (rest.length) die("usage: ledger.mjs rotate");
933
950
  runRotate();
934
951
  } else {
935
- die(`unknown subcommand '${cmd}' — expected row, token, filed, ruled, check, read, dispatch, settle, review, drain, undrain or rotate`);
952
+ die(`unknown subcommand '${cmd}' — expected row, token, filed, ruled, check, read, dispatch, settle, review, dispositions, drain, undrain or rotate`);
936
953
  }
937
954
 
938
955
  // Reached only by an arm that did not die, so every write subcommand that did
@@ -1965,32 +1982,32 @@ function dispositionsRefusal(pr, review) {
1965
1982
  if (review === undefined) return null;
1966
1983
  if (review.fixLive.length > 0) {
1967
1984
  return `${review.fixLive.join(", ")} still live on PR #${pr} — a fix-applier answering review ${review.run} has not settled, `
1968
- + "so no dispositions verdict answers its work yet; settle it, run dispositions-check.mjs for it, then dispatch the finisher again";
1985
+ + "so no dispositions verdict answers its work yet; settle it, run `ledger.mjs dispositions` for it, then dispatch the finisher again";
1969
1986
  }
1970
1987
  if (review.survived === 0 && review.unverified === 0) return null;
1971
1988
  const v = review.dispositions;
1972
1989
  if (v === null) {
1973
1990
  return `dispositions unchecked — no dispositions-ok=/dispositions-mismatch=/dispositions-escalate=/dispositions-unchecked= token answers PR #${pr}'s latest review, `
1974
- + `${review.run} at ${review.head}; run dispositions-check.mjs --member fix-pr-${pr}[-<x>] --scratch <scratch> for the fix-applier `
1991
+ + `${review.run} at ${review.head}; run ledger.mjs dispositions fix-pr-${pr}[-<x>] --scratch <scratch> for the fix-applier `
1975
1992
  + "that answered that review, then dispatch the finisher again";
1976
1993
  }
1977
1994
  if (v.verdict === "unchecked") {
1978
1995
  return `dispositions unchecked — ${v.member}'s check of review ${review.run} could not read where a deferral was filed (gh unreachable, `
1979
1996
  + "or an issue unreadable — an issue that does not exist is unreadable too, and no re-run answers that one: the check's stderr names "
1980
- + `it, and the record's issue number needs correcting); run dispositions-check.mjs --member ${v.member} --scratch <scratch> again once gh answers, `
1997
+ + `it, and the record's issue number needs correcting); run ledger.mjs dispositions ${v.member} --scratch <scratch> again once gh answers, `
1981
1998
  + "then dispatch the finisher again";
1982
1999
  }
1983
2000
  if (v.verdict === "mismatch") {
1984
2001
  return `dispositions mismatch — ${v.member}'s disposition record fails the check against review ${review.run}; `
1985
- + `dispositions-check.mjs --member ${v.member} --scratch <scratch> names each violating entry by bucket, index and rule`;
2002
+ + `ledger.mjs dispositions ${v.member} --scratch <scratch> names each violating entry by bucket, index and rule`;
1986
2003
  }
1987
2004
  if (v.verdict === "escalate") {
1988
2005
  return `dispositions escalate — ${v.member} deferred a finding above suggestion severity because its remedy lies outside the PR's diff, `
1989
2006
  + `or its record drew a second mismatch on this review: review ${review.run} gets no finisher until the escalate clears. `
1990
2007
  + "An outside-diff deferral clears when the maintainer's escalation answers are recorded with "
1991
- + `dispositions-check.mjs --member ${v.member} --scratch <scratch> --uphold '<list>' --send-back '<list>'; `
2008
+ + `ledger.mjs dispositions ${v.member} --scratch <scratch> --uphold '<list>' --send-back '<list>'; `
1992
2009
  + "a second mismatch clears only with a new review of the PR. "
1993
- + `dispositions-check.mjs --member ${v.member} --scratch <scratch> alone names each escalated finding or violating entry by bucket and index, `
2010
+ + `ledger.mjs dispositions ${v.member} --scratch <scratch> alone names each escalated finding or violating entry by bucket and index, `
1994
2011
  + "for the PR comment that hands it to the maintainer";
1995
2012
  }
1996
2013
  return null;
@@ -3143,6 +3160,103 @@ function runReview() {
3143
3160
  console.log(JSON.stringify({ pr: prNum, row: key, line, created, next: nextReviewerName(data.rows, prNum, retired) }));
3144
3161
  }
3145
3162
 
3163
+ // `dispositions <member> --scratch <dir> [--repo <path>] [--uphold <list>]
3164
+ // [--send-back <list>]`: the only writer of a PR's `dispositions-*=` verdict
3165
+ // and `escalation-answer=` tokens. It judges the fix-applier's disposition
3166
+ // record in-process, through the module dispositions-check.mjs exports,
3167
+ // against the ledger this call loaded — every git, gh and file read happens
3168
+ // first, with no lock held, since a gh call under the lock stalls every other
3169
+ // writer. Only then does it take the lock, load the ledger again and write
3170
+ // onto the row that carries the member as it stands now, every other token
3171
+ // kept: a token another writer put on that row while the tracker was read is
3172
+ // carried, never dropped. The verdict is judged against the review that was
3173
+ // the latest when it was read; one written for a review that has since been
3174
+ // superseded does nothing, since the gate and the tick read only verdicts
3175
+ // naming the latest run. A run recording answers is the exception: under the
3176
+ // lock it asks again that the escalate they answer is still the PR's current
3177
+ // verdict on that same review and that no fix-applier is live, and exits 2
3178
+ // with nothing written when either has changed, so two answer runs that read
3179
+ // one escalate cannot both write. A verdict the row already carries is not
3180
+ // written again, and its findings are printed all the same. The write passes
3181
+ // rowWriteRefusal() like any other. Its payload, stderr lines and exit status
3182
+ // are printVerdict()'s: 0 ok, 1 mismatch, escalate or unchecked, 2 nothing
3183
+ // judged and nothing written.
3184
+ async function runDispositions() {
3185
+ const usage = "usage: ledger.mjs dispositions <fix-pr-M[-x]> --scratch <dir> [--repo <path>] [--uphold <list>] [--send-back <list>]";
3186
+ const flags = new Map();
3187
+ let member = null;
3188
+ for (let i = 0; i < rest.length; i++) {
3189
+ const word = rest[i];
3190
+ if (!word.startsWith("--")) {
3191
+ if (member !== null) die(`dispositions: unexpected argument '${word}' — ${usage}`);
3192
+ member = word;
3193
+ continue;
3194
+ }
3195
+ const name = word.slice(2).split("=")[0];
3196
+ if (!["scratch", "repo", "uphold", "send-back"].includes(name)) die(`dispositions: unknown flag ${word} — ${usage}`);
3197
+ if (hasEqualsForm(name, rest)) die(`dispositions: --${name} needs a space-separated value, not --${name}=`);
3198
+ if (flags.has(name)) die(`dispositions: --${name} is given twice${name === "uphold" || name === "send-back" ? " — name every finding in one comma-separated list" : ""}`);
3199
+ const value = rest[++i];
3200
+ if (isFlagLike(value)) die(`dispositions: --${name} needs a value — ${usage}`);
3201
+ flags.set(name, value);
3202
+ }
3203
+ if (member === null || !flags.has("scratch")) die(usage);
3204
+ const { judgeMember, latestReview, answerMap, printVerdict, withVerdict, CheckRefusal } = await import("./dispositions-check.mjs");
3205
+ const refusing = (fn) => {
3206
+ try {
3207
+ return fn();
3208
+ } catch (e) {
3209
+ if (e instanceof CheckRefusal) die(e.message);
3210
+ throw e;
3211
+ }
3212
+ };
3213
+ const listed = refusing(() => answerMap(flags.get("uphold") ?? null, flags.get("send-back") ?? null));
3214
+ const result = refusing(() => judgeMember({
3215
+ name: member, scratch: flags.get("scratch"), repo: flags.get("repo") ?? process.cwd(), ledger: data, listed,
3216
+ }));
3217
+
3218
+ await acquireLock();
3219
+ data = load();
3220
+ const { pr, run, token } = result;
3221
+ // Answers clear the escalate they answer, so what recording them needs is
3222
+ // asked again on the ledger as it stands under the lock: two answer runs
3223
+ // that both read the same escalate would otherwise both write.
3224
+ if (result.recorded.length > 0) {
3225
+ let why = null;
3226
+ try {
3227
+ const latest = latestReview(data, pr, result.member, true);
3228
+ if (latest.run !== run) why = `PR #${pr}'s latest review is ${latest.run} now, not ${run}`;
3229
+ } catch (e) {
3230
+ if (!(e instanceof CheckRefusal)) throw e;
3231
+ why = e.message;
3232
+ }
3233
+ if (why !== null) {
3234
+ die(`dispositions: the ledger changed while ${result.member}'s record was judged — ${why}; nothing written, run \`ledger.mjs dispositions ${result.member} --scratch ${flags.get("scratch")}\` again to judge it as it stands`);
3235
+ }
3236
+ }
3237
+ const i = data.rows.findIndex((r) => rowNums(r).pr === pr && memberTokens(r).some((t) => t.name === result.member));
3238
+ if (i === -1) {
3239
+ die(`dispositions: ${result.member} is on no row of PR #${pr} now — the ledger changed while its record was judged; nothing written, run \`ledger.mjs dispositions ${result.member} --scratch ${flags.get("scratch")}\` again`);
3240
+ }
3241
+ const oldRow = data.rows[i];
3242
+ const key = rowKey(oldRow);
3243
+ if (!/^#[0-9]+$/.test(key)) die(`dispositions: the row carrying ${result.member} has no #<n> key to be rewritten by: ${oldRow}`);
3244
+ const text = oldRow.slice(key.length).trim();
3245
+ const answerTokens = result.recorded.map(([a, answer]) => `escalation-answer=${run}:${a}:${answer}`);
3246
+ const updated = withVerdict([text, ...answerTokens].join(" · "), token);
3247
+ if (updated === text) {
3248
+ console.error(` ${result.member}: row ${key} already carries ${token} — not written again`);
3249
+ } else {
3250
+ const line = `${key} ${updated}`;
3251
+ const after = data.rows.with(i, line);
3252
+ const refusal = rowWriteRefusal(data.rows, after, oldRow, line, readRetired(data.retired).names);
3253
+ if (refusal !== null) die(`dispositions: row ${key}: ${refusal}`);
3254
+ data.rows = after;
3255
+ save(data);
3256
+ }
3257
+ printVerdict(result);
3258
+ }
3259
+
3146
3260
  // A row's tokens: its words after the key, bar the ` · ` separators between
3147
3261
  // them.
3148
3262
  function rowTokens(text) {
@@ -3235,7 +3349,9 @@ function withTier(line, tok) {
3235
3349
  // call's tokens before it. A token is one word: an empty argument, one with
3236
3350
  // a space in it (prose, which would split into words the row's own words
3237
3351
  // then dedupe against), and the row's ` · ` separator are no token. A member
3238
- // token is `dispatch`'s or `settle`'s, a review token `review`'s. A word
3352
+ // token is `dispatch`'s or `settle`'s, a review token `review`'s, and a
3353
+ // dispositions verdict or an Escalation answer `dispositions`' — any word
3354
+ // beginning like one, parseable or not. A word
3239
3355
  // shaped like a member that the grammar cannot parse, a `tier=` that is not
3240
3356
  // a cell, a `tier=` naming a second tier in one call, any `cell=` (the row
3241
3357
  // step's, never a token), a `conflict-hold` or `parked` token the tick cannot
@@ -3253,6 +3369,11 @@ function tokenRefusal(tok, earlier) {
3253
3369
  if (isReviewToken(tok)) {
3254
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";
3255
3371
  }
3372
+ if (isDispositionsWord(tok)) {
3373
+ return tok.startsWith("escalation-answer=")
3374
+ ? `is an Escalation answer — a Gate verdict is written only by ${gateVerdictWriter(tok)}, which takes the maintainer's answer only against an escalate its own check raised; running that again is how a verdict is restored`
3375
+ : `is a dispositions verdict — a Gate verdict is written only by ${gateVerdictWriter(tok)}, which derives it from the disposition record and the review; running that again is how a verdict is restored`;
3376
+ }
3256
3377
  const name = tok.split("=")[0];
3257
3378
  if (MEMBER_FAMILIES.some((family) => name.startsWith(`${family}-`))) {
3258
3379
  return "is shaped like a member token this grammar cannot parse — a member is impl-<N>, fix-pr-<M>, finisher-pr-<M> or merge-bot-<n>, a retry suffix allowed";
@@ -121,7 +121,12 @@
121
121
  // The sibling pass's kept entries also carry "idle": true when nothing under
122
122
  // the key was found modified within the retention, false otherwise.
123
123
  // `--pr` mode adds `"evicted":[{"path","reason","ignored"}]` after `removed`:
124
- // each tree that held ignored paths, `ignored` naming them.
124
+ // each tree that held ignored paths, `ignored` naming them, and
125
+ // `"skipped":[{"path","reason"}]` after `failed`: each directory in a kept run
126
+ // root that evict-tree.mjs could not evaluate — one with a `.git` git does not
127
+ // resolve to it, one it cannot look in for a `.git`, or one it cannot list for
128
+ // EACCES or EPERM. A skipped directory is never in `failed`, so the snapshot
129
+ // step's marker, which reads `failed`, does not fire for it.
125
130
  // `ledger` is the file read, or null when none was (`--pr` mode, or
126
131
  // `--after-rotate` with no file) — so "never read" stays distinct from "read
127
132
  // and found empty". A dry run prints the same receipt with "applied":false,
@@ -686,8 +691,9 @@ function main() {
686
691
 
687
692
  const now = Date.now();
688
693
  let ledger = null;
689
- // `--pr` mode's evictions; null in every other mode.
690
- let evicted = null;
694
+ // `--pr` mode's evictions and skipped directories, in its receipt only.
695
+ const evicted = [];
696
+ const skipped = [];
691
697
  let remove;
692
698
  let kept = [];
693
699
  const failed = [];
@@ -700,11 +706,11 @@ function main() {
700
706
  failed.push({ path: parent, error: e.message });
701
707
  }
702
708
  // `--pr` mode also evicts the trees in every run root it keeps.
703
- evicted = [];
704
709
  for (const run of kept) {
705
710
  const done = evictTrees(run.path, { apply });
706
711
  for (const t of done.evicted) evicted.push({ path: t.path, reason: "a tree in a kept review run root", ignored: t.ignored });
707
712
  failed.push(...done.failed);
713
+ skipped.push(...done.skipped);
708
714
  }
709
715
  } else if (siblings) {
710
716
  if (apply) {
@@ -759,7 +765,7 @@ function main() {
759
765
  if (error === null) removed.push(entry);
760
766
  else failed.push({ path: entry.path, error });
761
767
  }
762
- const receipt = { applied: apply, ledger, removed, ...(evicted === null ? {} : { evicted }), kept, failed };
768
+ const receipt = { applied: apply, ledger, removed, ...(pr === null ? {} : { evicted }), kept, failed, ...(pr === null ? {} : { skipped }) };
763
769
  writeAll(1, `${JSON.stringify(receipt)}\n`);
764
770
  }
765
771
 
@@ -993,10 +993,11 @@ function standaloneScratchRoot() {
993
993
  * run root of this PR, it evicts every tree in that run root: the snapshot and
994
994
  * each specialist's and refuter's copy lose every path git ignores in them,
995
995
  * and nothing restores them. The run root's other files stay, review.json
996
- * among them. A failed eviction, and a reported run root it refuses to touch,
997
- * are logged; neither, nor a log that throws, changes what the review returns
998
- * or throws. A snapshot step that reported no run root evicts nothing and
999
- * logs nothing.
996
+ * among them. A failed eviction, a directory the eviction skips, and a
997
+ * reported run root it refuses to touch, are logged — a skip worded as a skip,
998
+ * not a failure; none of them, nor a log that throws, changes what the review
999
+ * returns or throws. A snapshot step that reported no run root evicts nothing
1000
+ * and logs nothing.
1000
1001
  */
1001
1002
  export async function runReview(host, args) {
1002
1003
  const run = { partition: null, runRoot: null };
@@ -1041,6 +1042,7 @@ function evictRunRoot(log, { partition, runRoot }) {
1041
1042
  }
1042
1043
  const done = evictTrees(runRoot, { apply: true });
1043
1044
  for (const f of done.failed) say(`eviction at the end of the review failed in ${f.path}: ${f.error}`);
1045
+ for (const s of done.skipped) say(`eviction at the end of the review skipped ${s.path}: ${s.reason}`);
1044
1046
  } catch (e) {
1045
1047
  say(`eviction at the end of the review failed in ${runRoot}: ${e?.message ?? e}`);
1046
1048
  }