@feigi/fleet-ctl 3.141.5 → 3.143.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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@feigi/fleet-ctl",
3
- "version": "3.141.5",
3
+ "version": "3.143.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": {
@@ -38,13 +38,31 @@
38
38
  // The verdicts come from `tier-outcomes.mjs append`, which
39
39
  // works them out from the Charges; this script never writes one.
40
40
  // metrics `metrics-refresh.mjs`. Any non-zero exit is a failed step.
41
+ // gather run-records.mjs's gather(): every run archive `ledger.mjs
42
+ // rotate` left in `.fleet/` (`ledger.<stamp>.md`,
43
+ // `phase0.<stamp>.json`, `closeout.<stamp>.json`) into
44
+ // `docs/metrics/runs/<stamp>/` with its `plugin-version`, and
45
+ // every review's `review.json` and Charges file under the
46
+ // scratch root into `docs/metrics/reviews/<pr>/<run>/`. The
47
+ // phase-0 receipt's `recipe` step output is withheld, since
48
+ // a Recipe command can carry an environment assignment. A
49
+ // run's own archives exist only once the next run has
50
+ // rotated, so this commits the runs before it; a file main
51
+ // already holds comes back byte for byte and adds nothing.
52
+ // A directory it cannot list or a file it cannot copy fails
53
+ // the step.
41
54
  // commit-and-pr `git switch -c <branch>` (`--branch`, default
42
55
  // `chore/run-artifacts-<UTC date>`, suffixed `b`, `c`… while
43
- // that name exists locally or on origin), commit exactly the
44
- // three `docs/metrics/*.tsv` files, `git fetch origin`, `git
45
- // rebase origin/main`, push `-u` with a lease, `gh pr
46
- // create --label patch` with a body naming the reason and the
47
- // rows each file gained and lost, `git switch main`. The
56
+ // that name exists locally or on origin), `git add` the
57
+ // new and changed files under `docs/metrics/runs/` and
58
+ // `docs/metrics/reviews/` that isRunRecord() allows, commit
59
+ // exactly those and the three `docs/metrics/*.tsv` files,
60
+ // `git fetch origin`, `git rebase origin/main`, push `-u`
61
+ // with a lease, `gh pr
62
+ // create --label patch` with a body naming the reason, the
63
+ // rows each file gained and lost and the record files
64
+ // added, `git switch main`. A file there that isRunRecord()
65
+ // does not allow is never staged; the output names it. The
48
66
  // rebase is three-way, so rows `main` gained during the run
49
67
  // stay; one that conflicts or that git refuses is aborted, the
50
68
  // branch is pushed as it was, and the PR is opened all the
@@ -146,13 +164,14 @@ import { homedir } from "node:os";
146
164
  import { dirname, join } from "node:path";
147
165
  import { fileURLToPath } from "node:url";
148
166
  import { makeDie, defineFlags } from "./arg.mjs";
149
- import { FleetDirUnresolvable, fleetFile } from "./fleet-dir.mjs";
167
+ import { FleetDirUnresolvable, fleetFile, scratchRoot } from "./fleet-dir.mjs";
150
168
  import { inertVerdict } from "./finisher-scope.mjs";
151
169
  import { gitEnv } from "./git-env.mjs";
152
170
  import { isCLI } from "./is-cli.mjs";
153
171
  import { CLOSEOUT_RECEIPT, RECEIPT, RECEIPT_HELD, memberTokens, rowPr, isOmpSessionDirName } from "./ledger-grammar.mjs";
154
172
  import { encodeProjectDir } from "./member-record.mjs";
155
173
  import { tickCaps } from "./phase0-receipt.mjs";
174
+ import { RECORD_DIRS, gather, recordChanges, refusedLine } from "./run-records.mjs";
156
175
 
157
176
  const NAME = "closeout";
158
177
  const SCRIPTS = dirname(fileURLToPath(import.meta.url));
@@ -334,12 +353,31 @@ function stepMetrics({ cwd }) {
334
353
  return r.status === 0 ? ok(r.stdout) : failed(`metrics-refresh.mjs failed: ${detail(r)}`);
335
354
  }
336
355
 
337
- // A name for the metrics branch: `--branch` as given, else the dated default,
356
+ // Copies the run archives and the review evidence into the checkout, for the
357
+ // commit step to stage.
358
+ function stepGather({ fleetDir }) {
359
+ const wt = workTree();
360
+ if (wt.error) return failed(wt.error);
361
+ let scratch;
362
+ try {
363
+ scratch = scratchRoot({ cwd: wt.cwd });
364
+ } catch (e) {
365
+ if (!(e instanceof FleetDirUnresolvable)) throw e;
366
+ return failed(`cannot name the scratch root: ${e.message}`);
367
+ }
368
+ try {
369
+ return ok(gather({ cwd: wt.cwd, fleetDir, scratch }).join("\n"));
370
+ } catch (e) {
371
+ return failed(`gather failed: ${e.message}`);
372
+ }
373
+ }
374
+
375
+ // A name for the branch: `--branch` as given, else `stem` and the UTC date,
338
376
  // lettered while the name is taken. A probe that fails to answer is no answer
339
377
  // at all, never "not taken".
340
- function pickBranch(git, given) {
378
+ function pickBranch(git, given, stem) {
341
379
  if (given !== null) return { name: given };
342
- const base = `chore/run-artifacts-${new Date().toISOString().slice(0, 10).replaceAll("-", "")}`;
380
+ const base = `${stem}${new Date().toISOString().slice(0, 10).replaceAll("-", "")}`;
343
381
  for (const suffix of ["", ..."bcdefghijklmnopqrstuvwxyz"]) {
344
382
  const name = base + suffix;
345
383
  const local = git(["show-ref", "--verify", "--quiet", `refs/heads/${name}`]);
@@ -351,11 +389,22 @@ function pickBranch(git, given) {
351
389
  return { error: `every lettered ${base} name is taken` };
352
390
  }
353
391
 
354
- // The rows each metrics file gained and lost on the branch, one TSV line a row.
355
- function rowCounts(git) {
356
- const r = git(["diff", "--numstat", "origin/main...HEAD", "--", ...METRICS]);
357
- if (r.status !== 0) return { error: `git diff --numstat failed: ${detail(r)}` };
358
- return { lines: r.stdout.split("\n").filter(Boolean).map((l) => l.split("\t")).map(([added, removed, file]) => `- ${file}: +${added} -${removed}`) };
392
+ // The rows each metrics file gained and lost on the branch, one TSV line a
393
+ // row, then the record files it adds under each of RECORD_DIRS.
394
+ function rowCounts(git, tsvs) {
395
+ const lines = [];
396
+ if (tsvs.length > 0) {
397
+ const r = git(["diff", "--numstat", "origin/main...HEAD", "--", ...tsvs]);
398
+ if (r.status !== 0) return { error: `git diff --numstat failed: ${detail(r)}` };
399
+ lines.push(...r.stdout.split("\n").filter(Boolean).map((l) => l.split("\t")).map(([added, removed, file]) => `- ${file}: +${added} -${removed}`));
400
+ }
401
+ for (const dir of RECORD_DIRS) {
402
+ const r = git(["diff", "--name-only", "--diff-filter=A", "origin/main...HEAD", "--", dir]);
403
+ if (r.status !== 0) return { error: `git diff --name-only -- ${dir} failed: ${detail(r)}` };
404
+ const added = r.stdout.split("\n").filter(Boolean).length;
405
+ if (added > 0) lines.push(`- ${dir}/: ${added} file(s) added`);
406
+ }
407
+ return { lines };
359
408
  }
360
409
 
361
410
  // Replays the branch's commit onto the `origin/main` just fetched, three-way,
@@ -385,42 +434,57 @@ function rebaseOntoMain(git) {
385
434
  return { leftOpen: `rebase refused: ${refused}` };
386
435
  }
387
436
 
388
- // Everything the step does while the checkout is on the metrics branch; the
389
- // caller switches back to main whatever this returns.
390
- function onBranch({ git, cwd, reason, receipt, save }) {
391
- const dirty = git(["status", "--porcelain", "--", ...METRICS]);
392
- if (dirty.status !== 0) return failed(`git status failed: ${detail(dirty)}`);
393
- if (dirty.stdout !== "") {
394
- const commit = git(["commit", "-m", `Closeout: ${reason}`, "--", ...METRICS]);
395
- if (commit.status !== 0) return failed(`git commit failed: ${detail(commit)}`);
396
- }
397
- const rebased = rebaseOntoMain(git);
398
- if (rebased.error) return failed(rebased.error);
437
+ // Everything the commit flow does while the checkout is on its branch; the
438
+ // caller switches back to main whatever this returns or throws. `tsvs` are
439
+ // the metrics files the commit carries beside the record files; `rebase`
440
+ // false skips the fetch and the replay, for a caller whose branch was cut from
441
+ // an `origin/main` it has just fetched and whose work tree may hold changes
442
+ // the commit leaves out.
443
+ function onBranch({ git, cwd, title, tsvs, rebase, state, save }) {
444
+ const records = recordChanges(git, cwd);
445
+ if (records.error) return failed(records.error);
446
+ const refusedLines = records.refused.map(refusedLine);
447
+ const fail = (line) => failed([...refusedLines, line].join("\n"));
448
+ if (records.allowed.length > 0) {
449
+ const add = git(["add", "--", ...records.allowed]);
450
+ if (add.status !== 0) return fail(`git add failed: ${detail(add)}`);
451
+ }
452
+ const paths = [...tsvs, ...records.allowed];
453
+ if (paths.length > 0) {
454
+ const dirty = git(["status", "--porcelain", "--", ...paths]);
455
+ if (dirty.status !== 0) return fail(`git status failed: ${detail(dirty)}`);
456
+ if (dirty.stdout !== "") {
457
+ const commit = git(["commit", "-m", title, "--", ...paths]);
458
+ if (commit.status !== 0) return fail(`git commit failed: ${detail(commit)}`);
459
+ }
460
+ }
461
+ const rebased = rebase ? rebaseOntoMain(git) : { leftOpen: null };
462
+ if (rebased.error) return fail(rebased.error);
399
463
  const ahead = git(["rev-list", "--count", "origin/main..HEAD"]);
400
- if (ahead.status !== 0) return failed(`git rev-list --count origin/main..HEAD failed: ${detail(ahead)}`);
401
- if (ahead.stdout === "0") return failed(`nothing to commit: ${METRICS.join(", ")} are unchanged`);
464
+ if (ahead.status !== 0) return fail(`git rev-list --count origin/main..HEAD failed: ${detail(ahead)}`);
465
+ if (ahead.stdout === "0") return fail(`nothing to commit: ${[...tsvs, ...RECORD_DIRS].join(", ")} are unchanged`);
402
466
  const head = git(["rev-parse", "HEAD"]);
403
- if (head.status !== 0) return failed(`git rev-parse HEAD failed: ${detail(head)}`);
467
+ if (head.status !== 0) return fail(`git rev-parse HEAD failed: ${detail(head)}`);
404
468
 
405
469
  // The lease is the head this step last pushed, never what the fetch above
406
470
  // just read: an empty one expects the branch absent from origin.
407
- const lease = `--force-with-lease=refs/heads/${receipt.branch}:${receipt.pin ?? ""}`;
408
- const push = git(["push", "-u", lease, "origin", receipt.branch], NETWORK_TIMEOUT_MS);
409
- if (push.status !== 0) return failed(`git push failed: ${detail(push)}`);
410
- receipt.pin = head.stdout;
411
- receipt.rebase = rebased.leftOpen;
471
+ const lease = `--force-with-lease=refs/heads/${state.branch}:${state.pin ?? ""}`;
472
+ const push = git(["push", "-u", lease, "origin", state.branch], NETWORK_TIMEOUT_MS);
473
+ if (push.status !== 0) return fail(`git push failed: ${detail(push)}`);
474
+ state.pin = head.stdout;
475
+ state.rebase = rebased.leftOpen;
412
476
  save();
413
- const lines = [`pushed ${receipt.pin}`, ...(rebased.leftOpen === null ? [] : [rebased.leftOpen])];
414
-
415
- if (receipt.pr !== null) return ok([...lines, `PR ${receipt.pr} already opened for ${receipt.branch}`].join("\n"));
416
- const counts = rowCounts(git);
417
- if (counts.error) return failed(counts.error);
418
- const body = `Closeout: ${reason}\n\nRows changed:\n${counts.lines.join("\n")}\n`;
419
- const pr = run("gh", ["pr", "create", "--head", receipt.branch, "--title", `Closeout: ${reason}`, "--label", "patch", "--body", body], { cwd, env: { GH_REPO: "" }, timeoutMs: NETWORK_TIMEOUT_MS });
420
- if (pr.status !== 0) return failed(`gh pr create failed: ${detail(pr)}`);
421
- receipt.pr = pr.stdout.split("\n").at(-1);
477
+ const lines = [...refusedLines, `pushed ${state.pin}`, ...(rebased.leftOpen === null ? [] : [rebased.leftOpen])];
478
+
479
+ if (state.pr !== null) return ok([...lines, `PR ${state.pr} already opened for ${state.branch}`].join("\n"));
480
+ const counts = rowCounts(git, tsvs);
481
+ if (counts.error) return fail(counts.error);
482
+ const body = `${title}\n\nRows changed:\n${counts.lines.join("\n")}\n`;
483
+ const pr = run("gh", ["pr", "create", "--head", state.branch, "--title", title, "--label", "patch", "--body", body], { cwd, env: { GH_REPO: "" }, timeoutMs: NETWORK_TIMEOUT_MS });
484
+ if (pr.status !== 0) return fail(`gh pr create failed: ${detail(pr)}`);
485
+ state.pr = pr.stdout.split("\n").at(-1);
422
486
  save();
423
- return ok([...lines, `PR ${receipt.pr} opened on ${receipt.branch}`].join("\n"));
487
+ return ok([...lines, `PR ${state.pr} opened on ${state.branch}`].join("\n"));
424
488
  }
425
489
 
426
490
  // The work tree the command runs in, as `{ cwd }`, or `{ error }`.
@@ -429,29 +493,44 @@ function workTree() {
429
493
  return top.status === 0 ? { cwd: top.stdout } : { error: `not inside a git work tree: ${detail(top)}` };
430
494
  }
431
495
 
432
- function stepCommitAndPR({ reason, branch, receipt, save }) {
433
- const wt = workTree();
434
- if (wt.error) return failed(wt.error);
435
- const { cwd } = wt;
496
+ /**
497
+ * The commit flow the Close-out PR and phase 0's catch-up share, run in the
498
+ * checkout at `cwd`: switch to `state.branch`, or cut one (`given`, else
499
+ * pickBranch() over `stem`) when it is null, stage and commit the allowed
500
+ * record files and `tsvs` under `title`, rebase when `rebase` is true, push
501
+ * with a lease, open the PR, and switch back to main, a throw on the branch
502
+ * included. `state` carries `{branch, pr, pin, rebase}` across calls and
503
+ * `save()` records it. The result is a step's `{status, output}`.
504
+ */
505
+ export function commitAndPr({ cwd, given = null, stem, title, tsvs, rebase, state, save }) {
436
506
  const git = (args, timeoutMs) => run("git", args, { cwd, timeoutMs });
437
-
438
- if (receipt.branch === null) {
439
- const picked = pickBranch(git, branch);
507
+ if (state.branch === null) {
508
+ const picked = pickBranch(git, given, stem);
440
509
  if (picked.error) return failed(picked.error);
441
510
  const made = git(["switch", "-c", picked.name]);
442
511
  if (made.status !== 0) return failed(`git switch -c ${picked.name} failed: ${detail(made)}`);
443
- receipt.branch = picked.name;
512
+ state.branch = picked.name;
444
513
  save();
445
514
  } else {
446
- const back = git(["switch", receipt.branch]);
447
- if (back.status !== 0) return failed(`git switch ${receipt.branch} failed: ${detail(back)}`);
515
+ const back = git(["switch", state.branch]);
516
+ if (back.status !== 0) return failed(`git switch ${state.branch} failed: ${detail(back)}`);
517
+ }
518
+ let result = null;
519
+ try {
520
+ result = onBranch({ git, cwd, title, tsvs, rebase, state, save });
521
+ } finally {
522
+ const main = git(["switch", "main"]);
523
+ if (main.status !== 0 && result !== null) result = failed([result.status === "ok" ? null : result.output, `git switch main failed: ${detail(main)}`].filter(Boolean).join("\n"));
448
524
  }
449
- const result = onBranch({ git, cwd, reason, receipt, save });
450
- const main = git(["switch", "main"]);
451
- if (main.status !== 0) return failed([result.status === "ok" ? null : result.output, `git switch main failed: ${detail(main)}`].filter(Boolean).join("\n"));
452
525
  return result;
453
526
  }
454
527
 
528
+ function stepCommitAndPR({ reason, branch, receipt, save }) {
529
+ const wt = workTree();
530
+ if (wt.error) return failed(wt.error);
531
+ return commitAndPr({ cwd: wt.cwd, given: branch, stem: "chore/run-artifacts-", title: `Closeout: ${reason}`, tsvs: METRICS, rebase: true, state: receipt, save });
532
+ }
533
+
455
534
  // The receipt `phase0.mjs` resumes would otherwise outlive the run it describes.
456
535
  // It is set aside under the name `phase0.mjs` holds a previous run's receipt
457
536
  // under, which the next run's rotation restores and archives with the ledger.
@@ -619,6 +698,7 @@ const FINISH = {
619
698
  scrape: stepScrape,
620
699
  "tier-outcomes": stepTierOutcomes,
621
700
  metrics: stepMetrics,
701
+ gather: stepGather,
622
702
  "commit-and-pr": stepCommitAndPR,
623
703
  "phase0-receipt": stepPhase0Receipt,
624
704
  "heartbeat-stop": stepHeartbeatStop,
@@ -30,7 +30,11 @@
30
30
  // CLAUDE.md or GEMINI.md, at any depth. A file directly in the root
31
31
  // .out-of-scope/, spelled exactly so, is exempt from the dot rule
32
32
  // alone
33
- // data one of the METRICS paths closeout.mjs names, and no other file
33
+ // data one of the METRICS paths closeout.mjs names, or a run record or
34
+ // review evidence file run-records.mjs's isRunRecord() accepts — a
35
+ // path of the allowlisted shape under docs/metrics/runs/ or
36
+ // docs/metrics/reviews/ — that is also outside the prompt surface,
37
+ // and no other file
34
38
  //
35
39
  // Stdout is one JSON line:
36
40
  //
@@ -60,6 +64,7 @@ import { statSync } from "node:fs";
60
64
  import { isAbsolute, resolve } from "node:path";
61
65
  import { makeDie, defineFlags, writeAll } from "./arg.mjs";
62
66
  import { METRICS } from "./closeout.mjs";
67
+ import { isRunRecord } from "./run-records.mjs";
63
68
  import { isDocs, isMarkdown, isTestDir } from "./diff-stats.mjs";
64
69
  import { gitEnv } from "./git-env.mjs";
65
70
  import { isCLI } from "./is-cli.mjs";
@@ -136,6 +141,12 @@ export function classifyEntry(path, status, oldMode, newMode) {
136
141
  const mode = modeProblem(status, oldMode, newMode);
137
142
  if (mode !== null) return { class: null, why: mode };
138
143
  if (METRICS.includes(path)) return { class: "data", why: "run metrics file" };
144
+ if (isRunRecord(path)) {
145
+ // No name isRunRecord() accepts is on the prompt surface today; the check
146
+ // stays so a record still has to pass it should either rule ever widen.
147
+ const surface = promptSurface(path);
148
+ return surface === null ? { class: "data", why: "run record or review evidence file" } : { class: null, why: surface };
149
+ }
139
150
  if (isTestDir(path)) return { class: null, why: "under a test directory" };
140
151
  if (!isMarkdown(path)) return { class: null, why: isDocs(path) ? "docs, but not .md or .markdown" : "not prose or data" };
141
152
  const surface = promptSurface(path);
@@ -164,7 +164,7 @@ export function reconcile(s) {
164
164
  // The conflict rows only ask the controller to write a record — never to
165
165
  // dispatch — so they stand outside the dispatch hold: the fix-applier a
166
166
  // conflict hold leads to obeys the hold through its own role's row. The
167
- // closed-PR rows dispatch nothing either.
167
+ // fix-failed escalation and the closed-PR rows dispatch nothing either.
168
168
  return [
169
169
  ...dispatchHold(s, [...implementers(s), ...rev.rows]),
170
170
  ...rev.conflictRows,
@@ -450,6 +450,15 @@ function reviewers(s) {
450
450
  conflictRows.push(row(`ESCALATE conflict ${prs(s.conflictEscalate)}`,
451
451
  { extra: "GitHub reads CONFLICTING again after two conflict fix-appliers landed; comment on the PR and flag it for a human — no hold, no fix-applier" }));
452
452
  }
453
+ // A PR owed a fix-applier on which two have settled `failed` since its
454
+ // latest review, none landed after them: no third, so not actionable, and
455
+ // repeated every tick until a new `reviewed=` lands or the PR closes. Like
456
+ // the conflict escalation it dispatches nothing and is no review unit.
457
+ if (s.fixEscalate.length) {
458
+ conflictRows.push(row(`ESCALATE fix-failed ${prs(s.fixEscalate.map((e) => e.pr))}`,
459
+ { extra: `${s.fixEscalate.flatMap((e) => e.members).join(", ")} settled failed since the latest review; no third fix-applier`
460
+ + " — comment on the PR once and tell the maintainer; a new review hands it back" }));
461
+ }
453
462
  if (!rows.length && !unlabelledRows.length) rows.push(row("IDLE OK"));
454
463
  rows.push(...unlabelledRows);
455
464
  return { rows, conflictRows };
@@ -830,6 +839,11 @@ export function foldLedger({ rows, dispatched }, open, { lenient = false } = {})
830
839
  // `fixMembers`: every fix-applier on this PR, wherever its token sits —
831
840
  // one still unsettled anywhere holds the PR off fixDue, since `dispatch`
832
841
  // refuses a second live one on the PR.
842
+ // `fixFailed`: every fix-applier on this PR settled `failed` after the
843
+ // latest `reviewed=` (from the first token, with none), in row order, one
844
+ // copy per member as for `fixLanded`; `fixFailures()` keeps those whose
845
+ // retry suffix sorts after every landed one's. `killed` and live members
846
+ // are not in it, and a `reviewed=` empties it, as it resets `reviewFixed`.
833
847
  // `reviewedHead`/`reviewedRun`: the latest `reviewed=<head>:…:<run>`.
834
848
  // `pastPinHalt`: the latest
835
849
  // finisher since that review settled `halted:past-pin` — any
@@ -843,7 +857,7 @@ export function foldLedger({ rows, dispatched }, open, { lenient = false } = {})
843
857
  // CONFLICT line off, since it may be pushing to the branch right now.
844
858
  const st = (pr !== null && byPr.get(pr)) || {
845
859
  inFlight: false, reviewedAny: false, survived: 0, unverified: 0, reviewFixed: false,
846
- fixMembers: new Set(), fixLanded: new Set(), conflictLanded: new Set(),
860
+ fixMembers: new Set(), fixLanded: new Set(), conflictLanded: new Set(), fixFailed: new Set(),
847
861
  conflictOpen: false, reviewedHead: null, reviewedRun: null, pastPinHalt: false, dispositions: [], workers: new Set(),
848
862
  finishers: new Set(), parked: [],
849
863
  };
@@ -864,7 +878,9 @@ export function foldLedger({ rows, dispatched }, open, { lenient = false } = {})
864
878
  if ((t.bound === "pr" && t.number === pr) || t.family === "impl") st.workers.add(t.name);
865
879
  // A settled `failed`/`killed` fix-applier leaves review findings or a
866
880
  // conflict unfixed and no successor dispatched — the PR stays fix-due
867
- // for a `-b` replacement. Only a live attempt, or one that actually
881
+ // for a `-b` replacement, unless that `failed` is the second since the
882
+ // PR's latest review with none landed after it (`fixFailed`), which
883
+ // escalates. Only a live attempt, or one that actually
868
884
  // landed (`applied:`/`no-op`), holds it off. Read the outcome off the
869
885
  // member's merged record (`members`, narrowed above) rather than this
870
886
  // row's own copy of the token: "a member settled ANYWHERE is settled",
@@ -896,14 +912,15 @@ export function foldLedger({ rows, dispatched }, open, { lenient = false } = {})
896
912
  if (t.family === "fix-pr" && t.number === pr) {
897
913
  st.fixMembers.add(t.name);
898
914
  const o = members.get(t.name).outcome;
899
- if ((o === "no-op" || /^applied:/.test(o)) && !st.fixLanded.has(t.name)
900
- && (t.outcome !== null || !settledInRow.has(t.name))) {
915
+ const placed = t.outcome !== null || !settledInRow.has(t.name);
916
+ if ((o === "no-op" || /^applied:/.test(o)) && !st.fixLanded.has(t.name) && placed) {
901
917
  st.fixLanded.add(t.name);
902
918
  if (st.conflictOpen) {
903
919
  st.conflictOpen = false;
904
920
  st.conflictLanded.add(t.name);
905
921
  } else st.reviewFixed = true;
906
922
  }
923
+ if (o === "failed" && placed) st.fixFailed.add(t.name);
907
924
  }
908
925
  if (t.family === "finisher-pr" && t.number === pr) st.finishers.add(t.name);
909
926
  if (t.family === "finisher-pr" && t.number === pr
@@ -929,7 +946,7 @@ export function foldLedger({ rows, dispatched }, open, { lenient = false } = {})
929
946
  if (!m && lenient) {
930
947
  malformed.add(i);
931
948
  latestFinisher = null;
932
- Object.assign(st, { inFlight: false, reviewedAny: true, reviewFixed: false, pastPinHalt: false });
949
+ Object.assign(st, { inFlight: false, reviewedAny: true, reviewFixed: false, pastPinHalt: false, fixFailed: new Set() });
933
950
  continue;
934
951
  }
935
952
  if (!m && REVIEWED_RUNLESS.test(tok)) {
@@ -940,7 +957,7 @@ export function foldLedger({ rows, dispatched }, open, { lenient = false } = {})
940
957
  latestFinisher = null;
941
958
  Object.assign(st, {
942
959
  inFlight: false, reviewedAny: true, survived: Number(m[2]), unverified: Number(m[4]), reviewFixed: false,
943
- reviewedHead: m[1].toLowerCase(), reviewedRun: m[5], pastPinHalt: false,
960
+ reviewedHead: m[1].toLowerCase(), reviewedRun: m[5], pastPinHalt: false, fixFailed: new Set(),
944
961
  });
945
962
  } else if (labelOffMember(tok) === null) {
946
963
  if (!lenient) throw new LedgerError(`${where}: '${tok}' is not label-off=<finisher-pr member> — fix the row with \`ledger.mjs row\``);
@@ -1135,6 +1152,29 @@ export function deriveRun({ rows, dispatched, drain, retired = [] }, prs, queued
1135
1152
  const retry = parseMember(cur.member).retry ?? "";
1136
1153
  return ![...st.fixLanded].some((n) => !st.conflictLanded.has(n) && (parseMember(n).retry ?? "") > retry);
1137
1154
  };
1155
+ // The fix-appliers settled `failed` since the PR's latest review whose retry
1156
+ // suffix sorts after that of every one on the PR that landed: a landed one
1157
+ // restarts the count, of any kind. Two of them and the fleet dispatches no
1158
+ // third fix-applier to the PR until a new review restarts it.
1159
+ const fixFailures = (st) => [...st.fixFailed].filter((n) => {
1160
+ const retry = parseMember(n).retry ?? "";
1161
+ return ![...st.fixLanded].some((l) => (parseMember(l).retry ?? "") >= retry);
1162
+ });
1163
+ const fixEscalated = (st) => fixFailures(st).length >= 2;
1164
+ // A returned review whose survived or unverified findings no review
1165
+ // fix-applier has answered — `ledger.mjs dispatch` refuses a finisher
1166
+ // on either until one has — a conflict hold no fix-applier has cleared,
1167
+ // or a dispositions mismatch no retry has answered — on a PR still open,
1168
+ // with no fix-applier working it and no newer review running. The first
1169
+ // two are answered apart here: a landed conflict fix-applier lifts the
1170
+ // hold and leaves findings it never read due for a review one.
1171
+ const fixOwed = ([n, st]) => open.has(n)
1172
+ && (((st.survived > 0 || st.unverified > 0) && !st.reviewFixed) || conflictHeld(st) || mismatchDue(st))
1173
+ && !fixRunning(st) && !st.inFlight;
1174
+ // The PRs owed a fix-applier, split below by `fixEscalated` into `fixDue`
1175
+ // and `fixEscalate`, as `conflicting` is into `conflicts` and
1176
+ // `conflictEscalate`.
1177
+ const owed = [...byPr.entries()].filter(fixOwed);
1138
1178
  // A `review=` token with no `reviewed=` after it reads as in flight, and the
1139
1179
  // ledger alone never says otherwise: a review whose own `reviewed=` write
1140
1180
  // never landed stays in flight after its PR merges, counting as a review unit
@@ -1171,18 +1211,21 @@ export function deriveRun({ rows, dispatched, drain, retired = [] }, prs, queued
1171
1211
  // The in-flight reviews of PRs the open list does not carry: the ones
1172
1212
  // the probe could retire, so the caller asks gh about these and no others.
1173
1213
  reviewsOffList: reviewing.filter(([n]) => !open.has(n)).map(([n]) => n).sort(asc),
1174
- // A returned review whose survived or unverified findings no review
1175
- // fix-applier has answered — `ledger.mjs dispatch` refuses a finisher
1176
- // on either until one has — a conflict hold no fix-applier has cleared,
1177
- // or a dispositions mismatch no retry has answered — on a PR still open,
1178
- // with no fix-applier working it and no newer review running. The first
1179
- // two are answered apart here: a landed conflict fix-applier lifts the
1180
- // hold and leaves findings it never read due for a review one.
1181
- fixDue: [...byPr.entries()]
1182
- .filter(([n, st]) => open.has(n)
1183
- && (((st.survived > 0 || st.unverified > 0) && !st.reviewFixed) || conflictHeld(st) || mismatchDue(st))
1184
- && !fixRunning(st) && !st.inFlight)
1185
- .map(([n]) => n).sort(asc),
1214
+ // Each PR a fix-applier is owed on (`fixOwed`), unless two fix-appliers
1215
+ // have settled `failed` on it since its latest review with none landed
1216
+ // after them: that PR is `fixEscalate`'s instead.
1217
+ fixDue: owed.filter(([, st]) => !fixEscalated(st)).map(([n]) => n).sort(asc),
1218
+ // Each PR a fix-applier would be owed on but for two `failed` since its
1219
+ // latest review, `{pr, members}` ascending, `members` the counted ones:
1220
+ // the reviewers row escalates it, dispatching nothing.
1221
+ fixEscalate: owed.filter(([, st]) => fixEscalated(st))
1222
+ .map(([n, st]) => ({ pr: n, members: fixFailures(st) })).sort((a, b) => a.pr - b.pr),
1223
+ // Every PR, open or not, with two `failed` fix-appliers counted, `{pr,
1224
+ // members}` ascending — the one reading of the count: `ledger.mjs
1225
+ // dispatch` refuses any fix-applier on a PR off this list, so it answers
1226
+ // with no open list, as `conflictHeld` does.
1227
+ fixFailed: [...byPr.entries()].filter(([, st]) => fixEscalated(st))
1228
+ .map(([n, st]) => ({ pr: n, members: fixFailures(st) })).sort((a, b) => a.pr - b.pr),
1186
1229
  // Open, not signed off, owned (openPrs() reads that off the PR's author
1187
1230
  // and draft flag; a PR closing no issue is as due as one closing one),
1188
1231
  // with no live or returned review on record —
@@ -2363,7 +2363,7 @@ async function runDispatch() {
2363
2363
  // conflict hold, dispositions retry — so its definition reads nothing off
2364
2364
  // the ledger.
2365
2365
  //
2366
- // The finisher's gates below turn on the tick's own verdict, not a second
2366
+ // The fix-applier's and the finisher's gates below turn on the tick's own verdict, not a second
2367
2367
  // reading of row `i`: a PR's tokens can be split across its ticket row and
2368
2368
  // its own `#<pr>` row, and a settle can live in `## Dispatched` alone, so
2369
2369
  // one row's text can read held where the tick reads cleared, and the
@@ -2379,6 +2379,19 @@ async function runDispatch() {
2379
2379
  }
2380
2380
  };
2381
2381
 
2382
+ // No third fix-applier, of any kind, on a PR where two have settled
2383
+ // `failed` since its latest review with none landed after them — read off
2384
+ // the tick's own fold, the one its `ESCALATE fix-failed` row reads, so a
2385
+ // hand-dispatched one is refused like the tick's. A new review restarts the
2386
+ // count.
2387
+ if (member.family === "fix-pr") {
2388
+ const failed = tickFold("fix-applier failure count").fixFailed.find((f) => f.pr === member.number);
2389
+ if (failed !== undefined) {
2390
+ die(`${member.name}: ${failed.members.join(", ")} settled failed on PR #${member.number} since its latest review — the fleet dispatches no third fix-applier; `
2391
+ + `a new review of PR #${member.number} (\`ledger.mjs review ${member.number} review=member:<next reviewer name>\`, dispatched as any review) restarts the count — not dispatching ${member.name}`);
2392
+ }
2393
+ }
2394
+
2382
2395
  // A finisher labels its PR `ready-to-merge`, so it is recorded only once
2383
2396
  // the PR sits on no conflict hold a fix-applier has yet to clear — a PR
2384
2397
  // known to conflict cannot merge, and a finisher would race the fix-applier
@@ -56,10 +56,17 @@
56
56
  // Compared like any other path, the first append would hold every
57
57
  // dispatching row for the rest of the run, and clearing it with `--record`
58
58
  // after every ruling would certify whatever stray write landed beside it.
59
- // So `snapshot()` leaves exactly those three paths out, for the reason
60
- // instruments.sh leaves `docs/metrics/` out of its pin. Three named files, not
61
- // the directory: anything else under `docs/metrics/` is still a stray write.
62
- // The price: a member's leaked write to one of those three files goes unseen.
59
+ // So `snapshot()` leaves those three paths out, for the reason instruments.sh
60
+ // leaves `docs/metrics/` out of its pin.
61
+ // The same holds for the run records and review evidence the close-out and
62
+ // phase 0's catch-up copy into `docs/metrics/runs/` and `docs/metrics/reviews/`
63
+ // and commit on a branch, which appear in the work tree and leave it again
64
+ // when the checkout switches back to main: a path run-records.mjs's
65
+ // isRunRecord() allows is left out too, while it is the regular file with no
66
+ // executable bit a commit carries. A symlink or an executable there, which
67
+ // the commit refuses, is still audited. Named files and one allowlisted shape,
68
+ // not the directory: anything else under `docs/metrics/` is still a stray
69
+ // write. The price: a member's leaked write to one of those paths goes unseen.
63
70
  //
64
71
  // FOUR ANSWERS, worktree-audit.sh's three plus the baseline's own refusal:
65
72
  // clean — the porcelain entries and hashes equal the baseline's, and HEAD
@@ -124,10 +131,12 @@ import { join } from "node:path";
124
131
  import { isCLI } from "./is-cli.mjs";
125
132
  import { makeDie, defineFlags } from "./arg.mjs";
126
133
  import { gitEnv, mainCheckoutDirFromGitCommonDir } from "./git-env.mjs";
134
+ import { isPlainFile, isRunRecord } from "./run-records.mjs";
127
135
 
128
136
  export const BASELINE_FILE = "main-checkout.sha";
129
137
  export const RECORD_COMMAND = "~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run main-checkout.mjs --record";
130
- const RUN_BOOKKEEPING = new Set(["docs/metrics/tier-outcomes.tsv", "docs/metrics/member-outcomes.tsv", "docs/metrics/ticket-features.tsv"]);
138
+ const RUN_METRICS = new Set(["docs/metrics/tier-outcomes.tsv", "docs/metrics/member-outcomes.tsv", "docs/metrics/ticket-features.tsv"]);
139
+ const isRunBookkeeping = (root, rel) => RUN_METRICS.has(rel) || (isRunRecord(rel) && isPlainFile(join(root, rel)));
131
140
  // Any change to an entry's hash or to a line's format bumps VERSION: a
132
141
  // baseline an older plugin wrote then reads `outdated` (re-record) and one a
133
142
  // newer plugin wrote reads `newer`, never as a baseline this code wrote.
@@ -209,11 +218,11 @@ const sha = (buf) => createHash("sha256").update(buf).digest("hex");
209
218
  // the hash where its status line would not — folded with its HEAD, so a
210
219
  // commit in it moves the hash too. A commitless repository's HEAD is the
211
220
  // branch it names. Nothing is left out: the run's bookkeeping is
212
- // `RUN_BOOKKEEPING`, the main checkout's named paths, not a nested
221
+ // `isRunBookkeeping`, the main checkout's paths, not a nested
213
222
  // repository's. Any git that fails throws: `unknown`, never a hash that reads
214
223
  // clean.
215
224
  function nestedHash(abs, env) {
216
- const now = entriesAt(abs, env, new Set());
225
+ const now = entriesAt(abs, env, () => false);
217
226
  if (!now.ok) throw new Error(now.why);
218
227
  let head = git("git rev-parse HEAD", ["rev-parse", "-q", "--verify", "HEAD^{commit}"], abs, env);
219
228
  if (!head.ok) {
@@ -241,10 +250,10 @@ function nestedHash(abs, env) {
241
250
  * `--no-renames` so every entry names exactly one path.
242
251
  */
243
252
  export function snapshot(root, env = process.env) {
244
- return entriesAt(root, env, RUN_BOOKKEEPING);
253
+ return entriesAt(root, env, (rel) => isRunBookkeeping(root, rel));
245
254
  }
246
255
 
247
- // `snapshot` of the repository at `root`, leaving out the paths in `skip`.
256
+ // `snapshot` of the repository at `root`, leaving out each path `skip` accepts.
248
257
  function entriesAt(root, env, skip) {
249
258
  const r = git("git status --porcelain -uall", ["--no-optional-locks", "status", "--porcelain", "-uall", "-z", "--no-renames"], root, env);
250
259
  if (!r.ok) return r;
@@ -253,8 +262,8 @@ function entriesAt(root, env, skip) {
253
262
  if (!line) continue;
254
263
  if (line.length < 4 || line[2] !== " ") return { ok: false, why: `git status printed an entry it does not document: ${JSON.stringify(line)}` };
255
264
  const rel = line.slice(3);
256
- if (skip.has(rel)) continue;
257
265
  try {
266
+ if (skip(rel)) continue;
258
267
  entries.set(line, hashPath(root, rel, env));
259
268
  } catch (e) {
260
269
  return { ok: false, why: `cannot hash ${rel}: ${e?.code ?? e?.message ?? e}` };
@@ -20,7 +20,7 @@ const isRecord = (x) => x !== null && typeof x === "object" && !Array.isArray(x)
20
20
  // by a finished phase 0.
21
21
  export const STEP_NAMES = Object.freeze([
22
22
  "alarm", "branch", "fast-forward", "pin", "baseline", "labels", "preflight", "ruleset", "tier-roles", "metrics",
23
- "cockpit", "rotate", "reclaim", "evict", "recipe", "fold-in", "stranded", "shortlist",
23
+ "cockpit", "rotate", "catch-up", "reclaim", "evict", "recipe", "fold-in", "stranded", "shortlist",
24
24
  ]);
25
25
 
26
26
  // The statuses a step can end in that let the run go on: `ok`, and the two