@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.
@@ -18,9 +18,9 @@
18
18
  // worktree refuses: the checks below judge the checkout the controller reads
19
19
  // its rules from). The steps, each a named entry in the receipt, run in
20
20
  // this order because the order is the point — the pin is recorded after the
21
- // fast-forward, the rotation comes before the fold-in, the scratch
22
- // reclaim straight after the rotation, the metrics refresh before the first
23
- // Pull is routed:
21
+ // fast-forward, the rotation comes before the fold-in, the catch-up straight
22
+ // after the rotation and the scratch reclaim straight after the catch-up, the
23
+ // metrics refresh before the first Pull is routed:
24
24
  //
25
25
  // alarm `~/.fleet/alarm/<pid>.json` names this omp's pid and start time
26
26
  // and this `.fleet/`. Missing, malformed or mismatched, or no omp
@@ -38,6 +38,8 @@
38
38
  // pin `instruments.sh --pin`, which certifies the Install root; the
39
39
  // ok line names its kind, root and version. A linked
40
40
  // checkout refuses: a fleet run executes an installed package.
41
+ // The `version=` line the pin writes to
42
+ // `.fleet/instruments.sha` is the receipt's `pluginVersion`.
41
43
  // baseline `main-checkout.mjs --record`; its refusals fail the step.
42
44
  // labels `label-map.mjs ensure`, the Label map derivation step. Exit 0
43
45
  // is ok, its output the map ensure printed. Exit 3 is pending,
@@ -65,6 +67,25 @@
65
67
  // cockpit `board.mjs serve --open` launched detached, `--spend-dir`
66
68
  // passed through. Recorded; never fails the run.
67
69
  // rotate `ledger.mjs rotate`. Exit 2 is a refusal and fails the step.
70
+ // catch-up run-records.mjs's gather() copies every run archive in
71
+ // `.fleet/` (the previous run's, which the rotation has just
72
+ // filed, and any earlier one) and every review evidence file
73
+ // under the scratch root into `docs/metrics/runs/` and
74
+ // `docs/metrics/reviews/`; when that leaves main lacking a
75
+ // record of a run that never closed out — no
76
+ // `closeout.<stamp>.json` beside its ledger archive —
77
+ // closeout.mjs's commitAndPr() commits every file main lacks
78
+ // alone on `chore/run-records-<UTC date>` (lettered while
79
+ // taken), pushes it and opens a PR, then switches back to
80
+ // main. A run that closed out leaves its records to this
81
+ // run's close-out, which gathers them again, so the catch-up
82
+ // opens no second PR carrying the same files. Before the
83
+ // reclaim, so a close-out that never ran loses nothing: the
84
+ // reclaim keeps a merged PR's evidence until main holds it.
85
+ // Recorded, and never fails the run but for a checkout it
86
+ // could not switch back to main; what it could not commit,
87
+ // the close-out gathers again, and its output says how far
88
+ // a failed commit got — a branch pushed with no PR included.
68
89
  // reclaim `reclaim-scratch.mjs --root <scratch> --after-rotate --apply`,
69
90
  // then `reclaim-scratch.mjs --siblings --root <scratch> --apply`
70
91
  // for the other keys under the scratch parent, which runs
@@ -102,7 +123,7 @@
102
123
  // THE RECEIPT is `.fleet/phase0.json` (resolved through fleet-dir.mjs, so a
103
124
  // worktree and the main checkout name one file):
104
125
  //
105
- // { run, session, scratch, inFlight, objective,
126
+ // { run, session, scratch, inFlight, objective, pluginVersion,
106
127
  // steps: { <name>: { status, at, output } } }
107
128
  //
108
129
  // `status` is ok, pending, failed, drift or unanswered; `at` an ISO time;
@@ -119,6 +140,8 @@
119
140
  // default when it records none — and a resume whose `--objective` names the
120
141
  // other one exits 2 naming both, leaving the receipt as it was. A resumed
121
142
  // receipt recording a value that is not an Objective exits 3 naming it.
143
+ // `pluginVersion` is the version the pin recorded, null when it recorded
144
+ // none; a resumed receipt keeps it.
122
145
  //
123
146
  // RESUMABLE. A re-run reads the receipt. It continues it — skipping every `ok`
124
147
  // step but `alarm` and re-running the rest — only when its `run` equals the
@@ -173,6 +196,7 @@ import { dirname, join, resolve } from "node:path";
173
196
  import { fileURLToPath } from "node:url";
174
197
  import { makeDie, defineFlags, isDigits } from "./arg.mjs";
175
198
  import { alarmFile } from "./controller-alarm.mjs";
199
+ import { commitAndPr } from "./closeout.mjs";
176
200
  import { ownClosingIssues } from "./closing-refs.mjs";
177
201
  import { FleetDirUnresolvable, fleetFile } from "./fleet-dir.mjs";
178
202
  import { readState, stateFileIn } from "./fleet-state.mjs";
@@ -183,6 +207,7 @@ import { OBJECTIVES, RECEIPT, RECEIPT_HELD, archiveStamp, receiptArchiveName, ro
183
207
  import { ancestry, controllerOf, processSource, ProcUnreadable } from "./proc.mjs";
184
208
  import { IN_FLIGHT_DEFAULT, OBJECTIVE_DEFAULT } from "./phase0-receipt.mjs";
185
209
  import { readRecipe } from "./recipe-read.mjs";
210
+ import { gather, recordChanges, refusedLine, unclosedRecords } from "./run-records.mjs";
186
211
 
187
212
  const NAME = "phase0";
188
213
  const SCRIPTS = dirname(fileURLToPath(import.meta.url));
@@ -249,14 +274,28 @@ function fastForward({ cwd }) {
249
274
  return ok(`fast-forwarded ${behind} commits to origin/main`);
250
275
  }
251
276
 
252
- function pin({ cwd }) {
277
+ function pin({ cwd, fleetDir, receipt }) {
253
278
  const r = sh("instruments.sh", ["--pin"], { cwd });
254
279
  if (r.status !== 0) return refusal("instruments.sh --pin failed:", r);
280
+ receipt.pluginVersion = pinnedVersion(fleetDir);
255
281
  // `instruments: pinned <digest> over <kind> <root> (version <v>)`
256
282
  const m = /^instruments: pinned [0-9a-f]+ over (.+)$/m.exec(r.stderr);
257
283
  return ok(`instruments pinned: ${m ? m[1] : r.stderr || "?"}`);
258
284
  }
259
285
 
286
+ // The `version=` line of the pin `instruments.sh --pin` just wrote, or null
287
+ // when it wrote none or the file cannot be read.
288
+ function pinnedVersion(fleetDir) {
289
+ let text;
290
+ try {
291
+ text = readFileSync(join(fleetDir, "instruments.sha"), "utf8");
292
+ } catch {
293
+ return null;
294
+ }
295
+ const m = /^version=(\S+)$/m.exec(text);
296
+ return m === null ? null : m[1];
297
+ }
298
+
260
299
  function baseline({ cwd }) {
261
300
  const r = node("main-checkout.mjs", ["--record"], { cwd });
262
301
  if (r.status !== 0) return refusal("main-checkout.mjs --record refused:", r);
@@ -352,6 +391,44 @@ function rotate(ctx) {
352
391
  return ok([head, ...lines(r.stderr).map((l) => l.trim())].join("\n"));
353
392
  }
354
393
 
394
+ // The previous runs' archives and the review evidence in scratch, committed on
395
+ // a branch of their own when main lacks a record of a run that never closed
396
+ // out. A run that closed out leaves its records to the next close-out, this
397
+ // run's, which gathers everything again, so committing them here too would
398
+ // open a second PR carrying the same files. The work tree may hold the metrics
399
+ // refresh's rows, which the commit leaves out, so the branch is cut from the
400
+ // main the fast-forward just brought level and is not rebased.
401
+ function catchUp({ cwd, fleetDir, scratch }) {
402
+ let gathered;
403
+ try {
404
+ gathered = gather({ cwd, fleetDir, scratch });
405
+ } catch (e) {
406
+ return ok(`not gathered: ${e.message} — the close-out gathers them`);
407
+ }
408
+ const git = (args, timeoutMs) => run("git", args, { cwd, timeoutMs });
409
+ const records = recordChanges(git, cwd);
410
+ if (records.error) return ok([...gathered, `not committed: ${records.error} — the close-out commits them`].join("\n"));
411
+ const refused = records.refused.map(refusedLine);
412
+ if (records.allowed.length === 0) {
413
+ return ok([...gathered, ...refused, "nothing to catch up: main holds every run record and review evidence file"].join("\n"));
414
+ }
415
+ if (unclosedRecords(fleetDir, records.allowed).length === 0) {
416
+ return ok([...gathered, ...refused, "nothing to catch up: every run whose records main lacks closed out, so this run's close-out commits them"].join("\n"));
417
+ }
418
+ const state = { branch: null, pr: null, pin: null, rebase: null };
419
+ const result = commitAndPr({ cwd, stem: "chore/run-records-", title: "Run records: phase 0 catch-up", tsvs: [], rebase: false, state, save: () => {} });
420
+ if (result.status === "ok") return ok([...gathered, result.output].join("\n"));
421
+ const head = git(["symbolic-ref", "-q", "HEAD"]);
422
+ if (head.status === 0 && head.stdout === "refs/heads/main") {
423
+ // How far the flow got before it failed, from what it recorded on the way.
424
+ const left = state.pin !== null
425
+ ? `pushed ${state.branch} at ${state.pin}, but no PR is open for it`
426
+ : state.branch !== null ? `not pushed; whatever was committed stays on the local branch ${state.branch}` : "not committed";
427
+ return ok([...gathered, `${left}: ${result.output} — the close-out commits them`].join("\n"));
428
+ }
429
+ return failed([...gathered, result.output, "the checkout is not back on main — switch it to main before the run goes on"].join("\n"));
430
+ }
431
+
355
432
  function reclaim({ cwd, scratch }) {
356
433
  const live = node("reclaim-scratch.mjs", ["--root", scratch, "--after-rotate", "--apply"], { cwd });
357
434
  // The sibling pass runs whatever the live sweep answered: a failure there is recorded beside it, never a reason to skip it.
@@ -549,7 +626,7 @@ function alarm({ fleetDir }) {
549
626
  const STEPS = {
550
627
  "alarm": alarm, "branch": branch, "fast-forward": fastForward, "pin": pin, "baseline": baseline, "labels": labels,
551
628
  "preflight": preflight, "ruleset": ruleset, "tier-roles": tierRoles, "metrics": metrics, "cockpit": cockpit, "rotate": rotate,
552
- "reclaim": reclaim, "evict": evict, "recipe": recipe, "fold-in": foldIn, "stranded": stranded, "shortlist": shortlist,
629
+ "catch-up": catchUp, "reclaim": reclaim, "evict": evict, "recipe": recipe, "fold-in": foldIn, "stranded": stranded, "shortlist": shortlist,
553
630
  };
554
631
 
555
632
  const STEP_NAMES = Object.keys(STEPS);
@@ -705,7 +782,8 @@ function main() {
705
782
  renameSync(receiptPath, held);
706
783
  }
707
784
 
708
- const receipt = { run: resumed ? previous.run : null, session, scratch, inFlight, objective, steps: {} };
785
+ const pluginVersion = resumed && typeof previous.pluginVersion === "string" ? previous.pluginVersion : null;
786
+ const receipt = { run: resumed ? previous.run : null, session, scratch, inFlight, objective, pluginVersion, steps: {} };
709
787
  for (const name of STEP_NAMES) {
710
788
  // `alarm` checks the omp running this invocation, so its `ok` is never carried.
711
789
  const was = resumed && name !== "alarm" ? previous.steps[name] : undefined;
@@ -34,7 +34,16 @@
34
34
  // of them: a bot's token names no PR, and GitHub reads MERGED
35
35
  // while the bot is still writing under pr<M>/merge-bot-<n>/. An
36
36
  // OPEN PR's pr<M>/ is kept whole except its run-* roots, which
37
- // follow the --pr rule below.
37
+ // follow the --pr rule below. A MERGED PR's entry that holds
38
+ // review evidence — a `<run>/review.json` under pr<M>/, or a
39
+ // Charges file naming its run — is also kept until origin/main
40
+ // holds every file of it where run-records.mjs's reviewTargets()
41
+ // puts it, under docs/metrics/reviews/<M>/: the Close-out PR
42
+ // carries it there. `git ls-tree origin/main` in the checkout the
43
+ // ledger sits in answers that, once per sweep; a lookup that fails,
44
+ // or evidence that cannot be read, keeps the entry with that
45
+ // reason. A CLOSED PR gets no Ruling, and its entries keep the
46
+ // rule above.
38
47
  // impl-<N>/
39
48
  // removed when issue #N is CLOSED, or OPEN with no live
40
49
  // impl-<N>[-x] token, no claim worktree standing, and idle past
@@ -121,6 +130,7 @@ import { gitEnv } from "./git-env.mjs";
121
130
  import { ghAliasedRead, how } from "./gh-aliased-read.mjs";
122
131
  import { isCLI } from "./is-cli.mjs";
123
132
  import { liveOnLedger, parseMember, REVIEWER } from "./ledger-grammar.mjs";
133
+ import { REVIEWS_DIR, reviewTargets } from "./run-records.mjs";
124
134
 
125
135
  const NAME = "reclaim-scratch";
126
136
  const die = makeDie(NAME);
@@ -269,6 +279,16 @@ function worktreeListing(checkout) {
269
279
  }
270
280
  }
271
281
 
282
+ // The paths origin/main holds under REVIEWS_DIR, as `{paths}`, or `{unknown}`
283
+ // naming why the checkout could not say. A missing origin/main is an unknown.
284
+ function evidenceOnMain(checkout) {
285
+ const r = spawnSync("git", ["ls-tree", "-r", "-z", "--name-only", "--full-tree", "origin/main", "--", `${REVIEWS_DIR}/`], {
286
+ cwd: checkout, encoding: "utf8", maxBuffer: MAX_BUFFER, timeout: GH_TIMEOUT_MS, env: gitEnv(),
287
+ });
288
+ if (r.error || r.status !== 0) return { unknown: `git ls-tree origin/main -- ${REVIEWS_DIR}/ failed (${how(r)})` };
289
+ return { paths: new Set(r.stdout.split("\0").filter(Boolean)) };
290
+ }
291
+
272
292
  // Whether a claim worktree stands for issue `n`: a listed worktree directly under
273
293
  // `.worktrees/` whose directory name names `n` as a whole segment, and whose
274
294
  // directory is still there. `{stands}` is true or false; `{unknown}`
@@ -329,7 +349,7 @@ function githubStates(numbers) {
329
349
  }
330
350
 
331
351
  // The root sweep's verdicts: `{remove: [{path, reason}], kept: [{path, reason}]}`.
332
- function judgeRoot(root, names, live, now, listing) {
352
+ function judgeRoot(root, names, live, now, listing, checkout) {
333
353
  const cutoff = now - RETENTION_MS;
334
354
  const remove = [];
335
355
  const kept = [];
@@ -342,6 +362,22 @@ function judgeRoot(root, names, live, now, listing) {
342
362
  return r !== null && Number(r[1]) === n;
343
363
  });
344
364
  const implHolder = (n) => liveMembers.find((m) => m.family === "impl" && m.number === n)?.name;
365
+ // Why a MERGED PR's entry is kept for its review evidence, or null when it
366
+ // holds none origin/main lacks. origin/main is read once, on first need.
367
+ let onMain = null;
368
+ const evidenceHold = (path, name, n) => {
369
+ let found;
370
+ try {
371
+ found = reviewTargets(path, name);
372
+ } catch (e) {
373
+ return `PR #${n} is MERGED, and its review evidence cannot be read: ${e.code ?? e.message}`;
374
+ }
375
+ if (found.targets.length === 0) return null;
376
+ onMain ??= evidenceOnMain(checkout);
377
+ if (onMain.unknown !== undefined) return `PR #${n} is MERGED, but whether origin/main holds its review evidence cannot be told: ${onMain.unknown}`;
378
+ const missing = found.targets.filter((t) => !onMain.paths.has(t.to)).map((t) => t.to);
379
+ return missing.length === 0 ? null : `PR #${n} is MERGED, but origin/main does not hold its review evidence yet: ${missing.join(", ")}`;
380
+ };
345
381
 
346
382
  const byAge = (path, name, young) => {
347
383
  const holder = live.find((t) => name.includes(t));
@@ -437,7 +473,12 @@ function judgeRoot(root, names, live, now, listing) {
437
473
  continue;
438
474
  }
439
475
  const holder = prHolder(n);
440
- if (holder !== undefined) kept.push({ path, reason: `PR #${n} is ${s.state}, but live ${holder} names it` });
476
+ if (holder !== undefined) {
477
+ kept.push({ path, reason: `PR #${n} is ${s.state}, but live ${holder} names it` });
478
+ continue;
479
+ }
480
+ const held = s.state === "MERGED" ? evidenceHold(path, name, n) : null;
481
+ if (held !== null) kept.push({ path, reason: held });
441
482
  else remove.push({ path, reason: `PR #${n} is ${s.state}` });
442
483
  continue;
443
484
  }
@@ -600,7 +641,7 @@ function main() {
600
641
  die(`could not list --root ${root}: ${e.message}`);
601
642
  }
602
643
  const listing = worktreeListing(found.checkout);
603
- ({ remove, kept } = judgeRoot(root, names, live, now, listing));
644
+ ({ remove, kept } = judgeRoot(root, names, live, now, listing, found.checkout));
604
645
  }
605
646
 
606
647
  const removed = [];
@@ -0,0 +1,251 @@
1
+ // A run's records and each reviewed PR's review evidence, as files the
2
+ // Close-out PR commits under docs/metrics/ — the one place that names them.
3
+ //
4
+ // docs/metrics/runs/<stamp>/ledger.md, phase0.json, closeout.json,
5
+ // plugin-version
6
+ // docs/metrics/reviews/<pr>/<run>/review.json,
7
+ // dispositions-fix-pr-<pr>[-x].json
8
+ //
9
+ // `<stamp>` is the ledger archive's own (`ledger.<stamp>.md`, archiveStamp()
10
+ // in ledger-grammar.mjs), and the three files under it are the archives
11
+ // `ledger.mjs rotate` leaves beside the ledger: `ledger.<stamp>.md`,
12
+ // `phase0.<stamp>.json` and `closeout.<stamp>.json`. The phase-0 receipt is
13
+ // committed with its `recipe` step's output withheld: that output is the
14
+ // Recipe's command lines, and a command can carry an environment assignment,
15
+ // a secret among them. A phase-0 archive that cannot be read as JSON cannot be
16
+ // withheld from, so it is not committed. `plugin-version` is one line, the
17
+ // `pluginVersion` that run's phase-0 receipt recorded from the instruments
18
+ // pin; a receipt that records none gets no file. `<run>` is the review's run
19
+ // root (`run-` and eight characters), `<scratch>/pr<pr>/<run>/`, and a Charges
20
+ // file goes into the run its own `run` field names.
21
+ //
22
+ // isRunRecord() is the allowlist: the commit step stages only paths it
23
+ // accepts, as isPlainFile() files, finisher-scope.mjs classifies only those as
24
+ // data beside the metrics TSVs, and main-checkout.mjs leaves the plain files
25
+ // among them out of its snapshot as the run's own bookkeeping. A file of any
26
+ // other name under those directories — a recipe, a transcript, a brief — is
27
+ // never staged. reviewTargets() is the one mapping from a scratch entry to the
28
+ // paths its evidence is committed under: gather() copies along it, and
29
+ // reclaim-scratch.mjs keeps a merged PR's evidence until origin/main holds
30
+ // every one of them.
31
+ //
32
+ // Zero deps: node builtins and sibling scripts only.
33
+
34
+ import { chmodSync, copyFileSync, lstatSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
35
+ import { dirname, join } from "node:path";
36
+
37
+ export const RUNS_DIR = "docs/metrics/runs";
38
+ export const REVIEWS_DIR = "docs/metrics/reviews";
39
+ export const RECORD_DIRS = Object.freeze([RUNS_DIR, REVIEWS_DIR]);
40
+ export const PLUGIN_VERSION = "plugin-version";
41
+
42
+ const STAMP = "[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{6}Z";
43
+ const RUN_ROOT = /^run-[A-Za-z0-9]{8}$/;
44
+ const RUN_RECORD = new RegExp(`^${RUNS_DIR}/${STAMP}/(?:ledger\\.md|phase0\\.json|closeout\\.json|${PLUGIN_VERSION})$`);
45
+ const RUN_DIR = new RegExp(`^${RUNS_DIR}/(${STAMP})/`);
46
+ const REVIEW_RECORD = new RegExp(`^${REVIEWS_DIR}/([1-9][0-9]*)/run-[A-Za-z0-9]{8}/(?:review\\.json|dispositions-fix-pr-\\1(?:-[a-z])?\\.json)$`);
47
+ // The archives `ledger.mjs rotate` leaves beside the ledger, by stamp, and the
48
+ // name each takes under docs/metrics/runs/<stamp>/.
49
+ const ARCHIVE = new RegExp(`^(?:ledger\\.(${STAMP})\\.md|phase0\\.(${STAMP})\\.json|closeout\\.(${STAMP})\\.json)$`);
50
+ const PR_ENTRY = /^pr([1-9][0-9]*)$/;
51
+ const DISPOSITIONS_ENTRY = /^dispositions-fix-pr-([1-9][0-9]*)(?:-[a-z])?\.json$/;
52
+
53
+ /** Whether `path` (repository-relative, `/`-separated) is a run record or review evidence file the Close-out PR may commit. */
54
+ export const isRunRecord = (path) => RUN_RECORD.test(path) || REVIEW_RECORD.test(path);
55
+
56
+ // The lstat of `path` when it is a regular file — never a symlink's target —
57
+ // else null; an absent path is null, any other failure throws.
58
+ const fileStat = (path) => {
59
+ try {
60
+ const st = lstatSync(path);
61
+ return st.isFile() ? st : null;
62
+ } catch (e) {
63
+ if (e.code === "ENOENT") return null;
64
+ throw e;
65
+ }
66
+ };
67
+
68
+ const isFile = (path) => fileStat(path) !== null;
69
+
70
+ /** Whether `path` is a regular file with no executable bit: the only kind of run record a commit carries. */
71
+ export const isPlainFile = (path) => {
72
+ const st = fileStat(path);
73
+ return st !== null && (st.mode & 0o111) === 0;
74
+ };
75
+
76
+ /** What the committed phase-0 receipt holds in place of its `recipe` step's output. */
77
+ export const RECIPE_WITHHELD = "withheld: the Recipe's command lines can carry environment assignments";
78
+
79
+ /**
80
+ * The run records `fleetDir` holds: `{copies: [{from, to}], writes: [{to,
81
+ * text}], notes}`, `to` repository-relative. A phase-0 archive is written with
82
+ * its `recipe` step's output withheld, and one that cannot be read as JSON is
83
+ * left out, with a note. Throws when `fleetDir` cannot be listed or a phase-0
84
+ * archive cannot be read.
85
+ */
86
+ export function runArchives(fleetDir) {
87
+ const copies = [];
88
+ const writes = [];
89
+ const notes = [];
90
+ for (const name of readdirSync(fleetDir).sort()) {
91
+ const m = ARCHIVE.exec(name);
92
+ if (m === null) continue;
93
+ const from = join(fleetDir, name);
94
+ if (!isFile(from)) continue;
95
+ const [stamp, file] = m[1] ? [m[1], "ledger.md"] : m[2] ? [m[2], "phase0.json"] : [m[3], "closeout.json"];
96
+ const dir = `${RUNS_DIR}/${stamp}`;
97
+ if (file !== "phase0.json") {
98
+ copies.push({ from, to: `${dir}/${file}` });
99
+ continue;
100
+ }
101
+ const text = readFileSync(from, "utf8");
102
+ let receipt;
103
+ try {
104
+ receipt = JSON.parse(text);
105
+ } catch {
106
+ // Not the parser's message: it can quote the receipt's own bytes.
107
+ notes.push(`${from} not committed: it is not JSON, so its recipe step cannot be withheld`);
108
+ continue;
109
+ }
110
+ const recipe = receipt?.steps?.recipe;
111
+ if (recipe !== null && typeof recipe === "object" && "output" in recipe) recipe.output = RECIPE_WITHHELD;
112
+ writes.push({ to: `${dir}/phase0.json`, text: `${JSON.stringify(receipt, null, 2)}\n` });
113
+ const version = receipt?.pluginVersion;
114
+ if (typeof version === "string" && /^[^\s]+$/.test(version)) writes.push({ to: `${dir}/${PLUGIN_VERSION}`, text: `${version}\n` });
115
+ }
116
+ return { copies, writes, notes };
117
+ }
118
+
119
+ /**
120
+ * The paths a scratch entry's review evidence is committed under, as
121
+ * `{targets: [{from, to}], notes}`. `pr<M>/` gives each `<run>/review.json`
122
+ * under it; `dispositions-fix-pr-<M>[-x].json` gives itself, in the run its
123
+ * `run` field names, or a note when it names none. Any other entry gives
124
+ * nothing. Throws when the entry cannot be read.
125
+ */
126
+ export function reviewTargets(path, name) {
127
+ const pr = PR_ENTRY.exec(name);
128
+ if (pr !== null) {
129
+ let runs;
130
+ try {
131
+ runs = readdirSync(path, { withFileTypes: true });
132
+ } catch (e) {
133
+ if (e.code === "ENOTDIR") return { targets: [], notes: [] };
134
+ throw e;
135
+ }
136
+ const targets = runs
137
+ .filter((d) => d.isDirectory() && RUN_ROOT.test(d.name) && isFile(join(path, d.name, "review.json")))
138
+ .map((d) => ({ from: join(path, d.name, "review.json"), to: `${REVIEWS_DIR}/${pr[1]}/${d.name}/review.json` }))
139
+ .sort((a, b) => (a.to < b.to ? -1 : 1));
140
+ return { targets, notes: [] };
141
+ }
142
+ const d = DISPOSITIONS_ENTRY.exec(name);
143
+ if (d === null || !isFile(path)) return { targets: [], notes: [] };
144
+ let run;
145
+ try {
146
+ run = JSON.parse(readFileSync(path, "utf8")).run;
147
+ } catch (e) {
148
+ return { targets: [], notes: [`${path} names no review run: ${e.message}`] };
149
+ }
150
+ if (typeof run !== "string" || !RUN_ROOT.test(run)) return { targets: [], notes: [`${path} names no review run: run is ${JSON.stringify(run ?? null)}`] };
151
+ return { targets: [{ from: path, to: `${REVIEWS_DIR}/${d[1]}/${run}/${name}` }], notes: [] };
152
+ }
153
+
154
+ /**
155
+ * Every review evidence file under `scratch`, as reviewTargets() maps it.
156
+ * An absent scratch root holds none; one that cannot be listed throws.
157
+ */
158
+ export function reviewEvidence(scratch) {
159
+ let names;
160
+ try {
161
+ names = readdirSync(scratch).sort();
162
+ } catch (e) {
163
+ if (e.code === "ENOENT") return { copies: [], notes: [] };
164
+ throw e;
165
+ }
166
+ const copies = [];
167
+ const notes = [];
168
+ for (const name of names) {
169
+ const found = reviewTargets(join(scratch, name), name);
170
+ copies.push(...found.targets);
171
+ notes.push(...found.notes);
172
+ }
173
+ return { copies, notes };
174
+ }
175
+
176
+ /**
177
+ * Copies every run archive in `fleetDir` and every review evidence file under
178
+ * `scratch` into the checkout at `cwd`, plain mode 0644, replacing what is
179
+ * there: a file already committed comes back byte for byte, so git sees only
180
+ * what is new. What stood at a destination is removed first, so a symlink
181
+ * there is replaced rather than written through. The lines it returns say
182
+ * what was gathered; it throws on a directory it cannot list or a file it
183
+ * cannot copy.
184
+ */
185
+ export function gather({ cwd, fleetDir, scratch }) {
186
+ const runs = runArchives(fleetDir);
187
+ const reviews = reviewEvidence(scratch);
188
+ const place = (to) => {
189
+ const abs = join(cwd, to);
190
+ mkdirSync(dirname(abs), { recursive: true });
191
+ rmSync(abs, { force: true });
192
+ return abs;
193
+ };
194
+ for (const { from, to } of [...runs.copies, ...reviews.copies]) {
195
+ const abs = place(to);
196
+ copyFileSync(from, abs);
197
+ chmodSync(abs, 0o644);
198
+ }
199
+ for (const { to, text } of runs.writes) {
200
+ const abs = place(to);
201
+ writeFileSync(abs, text);
202
+ chmodSync(abs, 0o644);
203
+ }
204
+ return [
205
+ `${runs.copies.length + runs.writes.length} run record file(s) from ${fleetDir}`,
206
+ `${reviews.copies.length} review evidence file(s) from ${scratch}`,
207
+ ...runs.notes,
208
+ ...reviews.notes,
209
+ ];
210
+ }
211
+
212
+ /**
213
+ * The run records among `paths` whose run left no close-out receipt
214
+ * (`closeout.<stamp>.json`) in `fleetDir`. A run that closed out leaves its
215
+ * records to the next run's close-out; phase 0's catch-up commits for the
216
+ * others.
217
+ */
218
+ export function unclosedRecords(fleetDir, paths) {
219
+ return paths.filter((path) => {
220
+ const m = RUN_DIR.exec(path);
221
+ return m !== null && !isFile(join(fleetDir, `closeout.${m[1]}.json`));
222
+ });
223
+ }
224
+
225
+ /** The output line naming a path recordChanges() refused. */
226
+ export const refusedLine = (path) => `not staged, not a run record isRunRecord() allows: ${path}`;
227
+
228
+ /**
229
+ * What the commit may stage under RECORD_DIRS in the checkout at `cwd`, which
230
+ * `git` runs in: `{allowed, refused}`, each a list of repository-relative
231
+ * paths, or `{error}`. The candidates are what `git ls-files --others
232
+ * --modified --exclude-standard` lists there, and what the index already
233
+ * holds staged there, as a commit that failed after its `git add` leaves it.
234
+ * Only a regular file isRunRecord() accepts, with no executable bit, is
235
+ * allowed; anything else — another name, a symlink, an executable, a
236
+ * deletion — is refused, so a commit never carries it.
237
+ */
238
+ export function recordChanges(git, cwd) {
239
+ const paths = [];
240
+ for (const args of [["ls-files", "-z", "--others", "--modified", "--exclude-standard"], ["diff", "--cached", "--name-only", "--no-renames", "-z"]]) {
241
+ const r = git([...args, "--", ...RECORD_DIRS]);
242
+ if (r.status !== 0) return { error: `git ${args[0]} -- ${RECORD_DIRS.join(" ")} failed: ${[r.stdout, r.stderr].filter(Boolean).join("\n") || r.how}` };
243
+ paths.push(...r.stdout.split("\0").filter(Boolean));
244
+ }
245
+ const allowed = [];
246
+ const refused = [];
247
+ for (const path of new Set(paths)) {
248
+ (isRunRecord(path) && isPlainFile(join(cwd, path)) ? allowed : refused).push(path);
249
+ }
250
+ return { allowed, refused };
251
+ }
@@ -225,8 +225,8 @@ Record each ruling with `ledger.mjs ruled <pr> <decision>`, one line with its re
225
225
  - **The reviewer.** **Dispatch the review, never wait on it, and act when its result lands. That is the default path.** `DISPATCH review PR#<M>`: a `task` member named `review-pr-<pr#>`, agent `fleet-review-runner`, its prompt the five args `pr`, `branch`, `worktree`, `testCmd` and `scratch`. Record `review=member:review-pr-<pr#>` on the PR's row before the call, with `ledger.mjs review <pr> <token>`: the tick counts in-flight reviews off the ledger and nowhere else. `scratch` is the scratch root itself, never a `pr<N>` partition (`references/reviewers.md`). The runner writes the result file and reports its path and `reviewed=` token.
226
226
  A row with `review=` and no `reviewed=` is a review in flight, and the tick counts it as a live review unit unless gh reports its PR MERGED or CLOSED.
227
227
  - **The fix-applier.** `DISPATCH fix-pr PR#<M>` on a `reviewed=` count that survived or unverified findings, with no fix-applier live: name `fix-pr-<pr#>` (the next suffix if that name is on record), never the PR's implementer; render with `dispatch-prompt.mjs render fix-applier --kind review --member fix-pr-<pr#> …`, then record `ledger.mjs dispatch <pr#> fix-pr-<pr#>` before the call. Its brief carries the PR number, the worktree abs path, the PR's branch, the same `testCmd` you passed the review, and the **path** `<scratch>/pr<pr>/<run>/review.json`, `<run>` off the PR's latest `reviewed=` — never the findings. Every `<scratch>` in that brief is the absolute path `scratch-root.mjs` printed. Its rulings are the fix-applier body's (`agents/fleet-fix-applier.agent.md`); you hold none, and a refuter report that surfaces to you is its to retrieve, never yours to scan or pass on. On a PR carrying `ready-to-merge`, its push moves the head after the label: a fresh finisher, per **Failure handling**.
228
- - **The conflict hold.** `DISPATCH fix-pr PR#<M>` on a conflict hold: the row carries an unresolved `conflict-hold:#<M>`, the merge bot's or one you recorded off the tick's `CONFLICT` line. It is the same slot with a different job, and no review file to hand over. Name it `fix-pr-<M>`, or the next suffix (`-b`, `-c` …) when that name is on record; render with `dispatch-prompt.mjs render fix-applier --kind conflict --member <name> …`; dispatch with the `agent` `ledger.mjs dispatch` printed, in the PR's existing worktree. Read the definition off that output (`fleet-fix-applier` whatever the row's `tier=`), never recall it. Settle `applied:<head>`, or `no-op` if no conflict was left, which lifts the merge hold; a dispatched-but-live one does not, and `failed`/`killed` leave the PR fix-due for a replacement. It answers the hold and nothing else: review findings the row also carries get a review `DISPATCH fix-pr PR#<M>` once it lands.
229
- - **Then dispatch a red-check fixer** — on a `check`-job `failure` bound to the PR's current head that is not **solely** staleness (the five-condition note in `agents/fleet-fix-applier.agent.md`). Name `fix-pr-<M>`, or the next free suffix; render with `dispatch-prompt.mjs render fix-applier --kind red-check --member <name> …`, record with `ledger.mjs dispatch <pr#> <name>` before the call, and dispatch with the printed `agent` in the PR's existing worktree. Never while a review or a review fix-applier on the PR is live or still owes its report — a dispositions mismatch awaiting its retry and a conflict hold awaiting its fix-applier included; a red before any review still gets its review first. The tick prints no `DISPATCH` for it: reconcile it yourself, always after the review. The finisher gate applies to it as to a fix-applier. Settle it `applied:<head>` once a fix is pushed; `no-op` only when the red is not its to fix — a flake that passes on rerun, or staleness — with nothing pushed, never for "could not fix"; `failed` when it cannot reach green (**Failure handling**). Its three dispatch edges are under **The finisher gate**; their rationale is in `references/member-lifecycle.md` (The red-check fixer's three edges).
228
+ - **The conflict hold.** `DISPATCH fix-pr PR#<M>` on a conflict hold: the row carries an unresolved `conflict-hold:#<M>`, the merge bot's or one you recorded off the tick's `CONFLICT` line. It is the same slot with a different job, and no review file to hand over. Name it `fix-pr-<M>`, or the next suffix (`-b`, `-c` …) when that name is on record; render with `dispatch-prompt.mjs render fix-applier --kind conflict --member <name> …`; dispatch with the `agent` `ledger.mjs dispatch` printed, in the PR's existing worktree. Settle `applied:<head>`, or `no-op` if no conflict was left, which lifts the merge hold; a dispatched-but-live one does not, and `failed`/`killed` leave the PR fix-due for a replacement; a second `failed` since its latest review escalates. It answers the hold and nothing else: review findings the row also carries get a review `DISPATCH fix-pr PR#<M>` once it lands.
229
+ - **Then dispatch a red-check fixer** — on a `check`-job `failure` bound to the PR's current head that is not **solely** staleness (the five-condition note in `agents/fleet-fix-applier.agent.md`). Name `fix-pr-<M>`, or the next free suffix; render with `dispatch-prompt.mjs render fix-applier --kind red-check --member <name> …`, record with `ledger.mjs dispatch <pr#> <name>` before the call, and dispatch with the printed `agent` in the PR's existing worktree. `dispatch` refuses one on a `fix-failed` PR, row or not; act as on the row. Never while a review or a review fix-applier on the PR is live or still owes its report — a dispositions mismatch awaiting its retry and a conflict hold awaiting its fix-applier included; a red before any review still gets its review first. The tick prints no `DISPATCH` for it: reconcile it yourself, always after the review. The finisher gate applies to it as to a fix-applier. Settle it `applied:<head>` once a fix is pushed; `no-op` only when the red is not its to fix — a flake that passes on rerun, or staleness — with nothing pushed, never for "could not fix"; `failed` when it cannot reach green (**Failure handling**).
230
230
  - **The merge bot.** Named `merge-bot-<n>`; `ledger.mjs dispatch merge-bot` numbers it. Render `--member merge-bot-<n> --n <n> --scratch <scratch>`. Dispatch with the printed agent, omit `model`, and dispatch on the first `ready-to-merge` label without waiting for the finisher report.
231
231
  - **The finisher.** Its render and receives are in `references/finisher.md`.
232
232
 
@@ -386,6 +386,7 @@ It prints `actual/target` and a named ACTION per role. Act on each line as it re
386
386
  - `ESCALATE unlabelled PR#<M> …` — a second finisher settled `labelled` and the label is still off: not actionable, the maintainer's.
387
387
  - `CONFLICT PR#<M> …` — record the hold with `fleet-event.mjs conflict <M>`, never with the `ledger.mjs row` form; the tick then prints `DISPATCH fix-pr`.
388
388
  - `ESCALATE conflict PR#<M> …` — PR M reads CONFLICTING again after two conflict fix-appliers: comment on the PR and flag it for a human, write no hold, dispatch no fix-applier.
389
+ - `ESCALATE fix-failed PR#<M> …` — no third fix-applier: comment on the PR once, tell the maintainer; a new review hands it back.
389
390
  - `ESCALATE pr-closed #<N> PR#<M>`, `… pr-unchecked …` — the maintainer's: tell them once per ticket per run; no dispatch or comment for #N. Reopening M or closing #N clears it. Only `replace #N` (`NEED resume`, same row) or `release #N` (closed-PR `release-ticket.sh --apply`, settle `released`) acts, once no live member names M.
390
391
  - `HOLD (…)` — the row is held and its detail names the clearing step: dispatch nothing on that row until it clears; a tier mismatch is yours to clear by dispatching the replacement.
391
392
  - `AT CAP`, `IDLE OK` — nothing to do on that row.
@@ -804,7 +805,7 @@ Match the failure to its row in the table below and run that response; where the
804
805
  | Implementer bails before implementing | Act by the report's `bailCause` as the **Relabel causes** table says, then refill (**What a wake owes beyond its call**) |
805
806
  | Implementer blocked or ambiguous *mid-implementation* | Free the slot. A `blocked` report settles on the **Implementer report** wake, no label moved; with no report, `ledger.mjs settle impl-<N> blocked`, its Ending still `hollow`. Leave `in-progress`, report — the ticket is not In flight and waits for a human; its `NEED derive-recipe` is phase 0's mid-run trigger |
806
807
  | `review-pr` workflow throws or returns no tree | Retry once under the next letter (`review-pr-<pr#>-b`); still failing, report and leave the PR at review-due. Never enqueue the PR as reviewed — the workflow is not a member, so no other row here covers it |
807
- | Reviewer, fix-applier or red-check fixer cannot reach green | Report, leave the PR unlabeled, free the slot — the last two settle `failed`; a wake's `NEED derive-recipe` is phase 0's mid-run trigger |
808
+ | Reviewer, fix-applier or red-check fixer cannot reach green | Report, leave the PR unlabeled, free the slot — the last two settle `failed`; a wake's `NEED derive-recipe` is phase 0's mid-run trigger; a second `failed` fix-applier since review escalates |
808
809
  | Merge bot finds the worktree ahead of the PR head **on the local-rebase fallback** | `worktree-diverged-#<pr>`, PR stays queued. Read the stray commit; push-or-discard is yours, and the maintainer's if the evidence cannot settle it |
809
810
  | Merge bot finds the head moved after `ready-to-merge` was applied | The label binds to the head's net change, not to one SHA: a proven rebase-carry keeps the label — the bot proceeds and reports `rebase-carry-#<pr>` with the labelled and accepted SHAs, and nothing is dispatched. Any other move is `head-moved-after-label-#<pr>`, PR stays queued, label untouched. Dispatch a **fresh** finisher against the new head — the first audit verified a different tree |
810
811
  | Merge bot cannot resolve a rebase safely | Stop that PR, report, continue. On a conflict the bot has already appended `conflict-hold:#<pr>` to the PR's row; the tick prints `DISPATCH fix-pr PR#<pr>` and holds the merge until that fix-applier settles. A PR that conflicts before any bot reaches it is the tick's `CONFLICT PR#<pr>` line, whose hold you record |
@@ -1,6 +1,6 @@
1
1
  # Close-out: what each metrics step does and why
2
2
 
3
- `closeout.mjs finish` runs the scrape, the tier-outcomes check, the metrics refresh, the commit of the metrics files, and the phase-0 receipt move, and SKILL.md's **End of run** says how to drive it. This file is how each of those works, for the controller to read when a step refuses, and how `closeout.mjs reopen` undoes a drain. The verdict rules — what `closed_own_ticket` and `minted_false_claim` mean, and that a value not in hand is left blank — stay in SKILL.md under **Guard: accumulate per PR**, because the controller still rules them.
3
+ `closeout.mjs finish` runs the scrape, the tier-outcomes check, the metrics refresh, the gather of the run records and the review evidence, the commit of the metrics and record files, and the phase-0 receipt move, and SKILL.md's **End of run** says how to drive it. This file is how each of those works, for the controller to read when a step refuses, and how `closeout.mjs reopen` undoes a drain. The verdict rules — what `closed_own_ticket` and `minted_false_claim` mean, and that a value not in hand is left blank — stay in SKILL.md under **Guard: accumulate per PR**, because the controller still rules them.
4
4
 
5
5
  - **The run ends, or the maintainer says drain** → `fleet-event.mjs drain --reason "<reason>"`
6
6
  first (below). The marker is on disk, so the tick
@@ -19,7 +19,8 @@
19
19
  once the run is draining with no open PR and no live implementer.
20
20
  3. `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run closeout.mjs finish --reason "<reason>"` — scrapes
21
21
  the run's member facts, checks the tier-outcomes rows, refreshes the
22
- metrics, commits the three metrics files and opens their PR, sets the
22
+ metrics, gathers the earlier runs' records and the review evidence,
23
+ commits them with the three metrics files and opens their PR, sets the
23
24
  phase-0 receipt aside as `.fleet/phase0.previous.json`, records
24
25
  `fleet-heartbeat.mjs --stop`, because every reader takes a recorded stop
25
26
  as the end of the run, and then merges the Close-out PR. On `NEED
@@ -124,6 +125,26 @@ the cause and run `finish` again — the pending file stays in `.fleet/` and the
124
125
  next run's phase-0 pass drains it — and never commit the metrics files with a
125
126
  drain that failed claiming the corpus is complete.
126
127
 
128
+ ## Gather the run records and the review evidence
129
+
130
+ **Gather the run records and the review evidence after the metrics refresh,
131
+ before the commit.** The `gather` step of `closeout.mjs finish` copies, from
132
+ `.fleet/`, every run archive `ledger.mjs rotate` left there into
133
+ `docs/metrics/runs/<UTC stamp>/` — `ledger.md`, `phase0.json`, `closeout.json`,
134
+ and a `plugin-version` line from the version the phase-0 receipt recorded —
135
+ and, from the scratch root, every review's `review.json` into
136
+ `docs/metrics/reviews/<pr>/<run>/`, with each Charges file
137
+ (`dispositions-fix-pr-<pr>[-x].json`) beside the review run it answers. The
138
+ phase-0 receipt goes in with its `recipe` step's output withheld, because that
139
+ output is the Recipe's command lines and a command can carry an environment
140
+ assignment; a phase-0 archive that cannot be read as JSON is not gathered, and
141
+ the step's output names it. A run's own archives exist only once the next run
142
+ has rotated, so the records it carries are the earlier runs'; a file main
143
+ already holds comes back byte for byte and adds nothing. A Charges file that
144
+ names no review run is not gathered, and the step's output names it. A
145
+ directory it cannot list or a file it cannot copy fails the step, so
146
+ `commit-and-pr` stays pending: fix the cause and run `finish` again.
147
+
127
148
  ## Commit the metrics files and open a PR
128
149
 
129
150
  The metrics files are the run's own artifacts and none commits itself. Carry
@@ -141,6 +162,14 @@ a data row loses it: `member-outcomes.tsv` is regenerated from harness
141
162
  transcripts the fleet does not own, so re-running the scrape later is worth
142
163
  only what the harness still holds.
143
164
 
165
+ The commit carries the run records and the review evidence beside the three
166
+ metrics files, because a review's evidence is deleted from scratch once its PR
167
+ has merged and main holds it, and a run's ledger and receipts otherwise stay on
168
+ one machine. Only the files `isRunRecord()` in `run-records.mjs` allows are
169
+ staged: the shapes above, regular files with no executable bit. Anything else
170
+ under `docs/metrics/runs/` or `docs/metrics/reviews/` — a recipe, a transcript,
171
+ a brief — is left out of the commit, and the step's output names it.
172
+
144
173
  ## Move the phase-0 receipt
145
174
 
146
175
  **Set aside the phase-0 receipt after the commit — before the heartbeat.** The receipt `.fleet/phase0.json` records each phase-0 step's result and the In-flight bound the tick reads; `closeout.mjs finish` moves it to `.fleet/phase0.previous.json` so the next run can find it under the name `phase0.mjs` reserves for a previous run's receipt, and that run's rotation restores and archives it with the ledger. A missing `.fleet/phase0.json` counts as nothing to move and is `ok`.
@@ -222,7 +222,7 @@ not rely on that.
222
222
  **The acceptance mutation runs unless `finisher-scope.mjs` says the diff is inert.**
223
223
  A mutation that loosens a regex, deletes a guard or flips a reset has nothing to
224
224
  kill in a diff made only of Markdown prose (`.md` or `.markdown` outside the
225
- prompt surface) or only of the run-metrics files. The finisher does not decide
225
+ prompt surface) or only of the run-metrics files, run records and review evidence. The finisher does not decide
226
226
  that by reading the diff: the script reads it, and only its exit 0 skips the
227
227
  mutation. An exit 1 is not overridden, and an exit 2 is never read as a 0.
228
228