@feigi/fleet-ctl 3.54.0 → 3.54.2

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.54.0",
3
+ "version": "3.54.2",
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": {
@@ -0,0 +1,428 @@
1
+ #!/usr/bin/env node
2
+ // The end of a run as two commands, each a list of named steps with a receipt.
3
+ //
4
+ // closeout.mjs begin --reason "<r>"
5
+ // closeout.mjs finish --reason "<r>" [--branch <name>]
6
+ //
7
+ // Reached through the Resolver and run from the MAIN checkout. The middle of
8
+ // the end of a run is the ordinary loop (the tick's review, fix-applier and
9
+ // merge rows), so the end is two calls around it: `begin` starts the drain,
10
+ // `finish` closes the run once the tick says it is over.
11
+ //
12
+ // `begin` steps:
13
+ //
14
+ // drain `ledger.mjs drain "<reason>"`. A second drain is answered with the
15
+ // standing marker at exit 0, so a run already draining is `ok`.
16
+ // release every ticket row that carries a live or `bailed` `impl-` member
17
+ // token and no PR: `release-ticket.sh <N> impl-<N> implementer
18
+ // --apply`, then `ledger.mjs settle <member>=released` for each of
19
+ // its live tokens (a `bailed` token is settled already). A claim the
20
+ // script refuses is printed `NEED hand-release #<N> <blocker>` and
21
+ // the loop goes on to the next claim; the step is then pending.
22
+ //
23
+ // `finish` steps, in order, because the order is the point:
24
+ //
25
+ // tick `fleet-tick.mjs`, with the caps `.fleet/phase0.json` records
26
+ // when it names them. Failed unless its last line is
27
+ // `ACTION: run over`.
28
+ // scrape `member-outcomes.mjs <dir>` for every session directory
29
+ // omp keeps for this cwd, each scraper's own yield line as the
30
+ // output. A scraper that exits non-zero fails the step: a
31
+ // skipped scrape loses the run's member rows for good.
32
+ // tier-outcomes `tier-outcomes.mjs check --live`. Its exit 1 is a failed
33
+ // step. At exit 0 each `WARNING PR #<n> carries reviewed=` on
34
+ // its stderr is a PR the ledger marks reviewed with no row:
35
+ // `NEED tier-outcomes append <n>`, and the step is pending.
36
+ // The verdicts are the controller's; this script never
37
+ // writes one.
38
+ // metrics `metrics-refresh.mjs`. Any non-zero exit is a failed step.
39
+ // commit-and-pr `git switch -c <branch>` (`--branch`, default
40
+ // `chore/run-artifacts-<UTC date>`, suffixed `b`, `c`… while
41
+ // that name exists locally or on origin), commit exactly the
42
+ // three `docs/metrics/*.tsv` files, push `-u`, `gh pr create
43
+ // --label patch` with a body naming the reason and the rows
44
+ // each file gained and lost, `git switch main`. The branch, and
45
+ // the PR once it exists, are kept in the receipt: a re-run
46
+ // after a failed push or PR resumes on that branch and never
47
+ // opens a second PR.
48
+ // heartbeat-stop `fleet-heartbeat.mjs --stop "<reason>"`, last, because
49
+ // every reader takes a recorded stop as the end of the run.
50
+ //
51
+ // THE RECEIPT is `.fleet/closeout.json` (resolved through fleet-dir.mjs, so a
52
+ // worktree and the main checkout name one file), shared by both commands:
53
+ //
54
+ // { reason, begun, branch, pr, steps: { <name>: { status, at, output } } }
55
+ //
56
+ // `status` is ok, pending or failed; `at` an ISO time; `output` the step's own
57
+ // words. Every step name of both commands is always present: one not yet run
58
+ // is `pending`. `begun` is the time `begin` finished its steps, ok or pending,
59
+ // null until then; `branch` and `pr` belong to the commit-and-pr step. A re-run
60
+ // skips every `ok` step and runs the rest, stopping at the first that is not
61
+ // `ok`, so the steps after it stay `pending`. `ledger.mjs rotate` archives the
62
+ // receipt beside the ledger as `closeout.<UTC stamp>.json`.
63
+ //
64
+ // One `closeout: <step>: <status>` line per step on stdout, its output under
65
+ // it, indented, with the `NEED` lines at the left margin. Exit 0 every step
66
+ // ok; 2 a usage error; 3 a step failed, or the receipt could not be read or
67
+ // written; 4 a `NEED` is pending: dispatch what the line names, then run the
68
+ // same command again.
69
+ //
70
+ // Zero deps: node builtins and sibling scripts only.
71
+
72
+ import { spawnSync } from "node:child_process";
73
+ import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync } from "node:fs";
74
+ import { homedir } from "node:os";
75
+ import { dirname, join } from "node:path";
76
+ import { fileURLToPath } from "node:url";
77
+ import { makeDie, defineFlags } from "./arg.mjs";
78
+ import { FleetDirUnresolvable, fleetFile } from "./fleet-dir.mjs";
79
+ import { gitEnv } from "./git-env.mjs";
80
+ import { isCLI } from "./is-cli.mjs";
81
+ import { CLOSEOUT_RECEIPT, RECEIPT, memberTokens, rowPr } from "./ledger-grammar.mjs";
82
+ import { encodeProjectDir, isOmpSessionDirName } from "./member-record.mjs";
83
+
84
+ const NAME = "closeout";
85
+ const SCRIPTS = dirname(fileURLToPath(import.meta.url));
86
+ const MAX_BUFFER = 64 * 1024 * 1024;
87
+ const NETWORK_TIMEOUT_MS = 120_000;
88
+ const METRICS = ["docs/metrics/member-outcomes.tsv", "docs/metrics/ticket-features.tsv", "docs/metrics/tier-outcomes.tsv"];
89
+ const TICK_OVER = "ACTION: run over";
90
+
91
+ const script = (name) => join(SCRIPTS, name);
92
+
93
+ function how(r) {
94
+ if (r.error) return r.error.code ?? r.error.message;
95
+ if (r.signal) return `killed by ${r.signal}`;
96
+ return `exit ${r.status}`;
97
+ }
98
+
99
+ const trimmed = (s) => String(s ?? "").trim();
100
+
101
+ /**
102
+ * Runs a child to completion from `cwd`. `status` is the exit status, null
103
+ * when the child never ran or was killed (`how` says which). The environment
104
+ * is scrubbed of GIT_DIR/GIT_WORK_TREE for every child — git itself, `gh`,
105
+ * and the sibling scripts — so an ambient one cannot point any step at another
106
+ * repository.
107
+ */
108
+ function run(cmd, args, { cwd, env, timeoutMs } = {}) {
109
+ const r = spawnSync(cmd, args, { cwd, encoding: "utf8", maxBuffer: MAX_BUFFER, env: gitEnv(env), timeout: timeoutMs });
110
+ return { status: r.error ? null : r.status, stdout: trimmed(r.stdout), stderr: trimmed(r.stderr), how: how(r) };
111
+ }
112
+
113
+ const node = (name, args, opts) => run(process.execPath, [script(name), ...args], opts);
114
+ const sh = (name, args, opts) => run("sh", [script(name), ...args], opts);
115
+
116
+ // What a failed child said, or how it ended when it said nothing.
117
+ const detail = (r) => [r.stdout, r.stderr].filter(Boolean).join("\n") || r.how;
118
+
119
+ const ok = (output = "") => ({ status: "ok", output });
120
+ const pending = (output) => ({ status: "pending", output });
121
+ const failed = (output) => ({ status: "failed", output });
122
+
123
+ function fatal(message) {
124
+ process.stderr.write(`${NAME}: ${message}\n`);
125
+ process.exit(3);
126
+ }
127
+
128
+ // ── the receipt ──────────────────────────────────────────────────────────────
129
+
130
+ const blank = () => ({ status: "pending", at: null, output: "" });
131
+
132
+ function readReceipt(path, stepNames) {
133
+ let prior = null;
134
+ try {
135
+ prior = JSON.parse(readFileSync(path, "utf8"));
136
+ } catch (e) {
137
+ if (e.code !== "ENOENT") fatal(`cannot read receipt ${path}: ${e.message}`);
138
+ }
139
+ const steps = Object.fromEntries(stepNames.map((n) => [n, { ...blank(), ...prior?.steps?.[n] }]));
140
+ return { reason: prior?.reason ?? null, begun: prior?.begun ?? null, branch: prior?.branch ?? null, pr: prior?.pr ?? null, steps };
141
+ }
142
+
143
+ function writeReceipt(path, receipt) {
144
+ const tmp = `${path}.${process.pid}.tmp`;
145
+ try {
146
+ mkdirSync(dirname(path), { recursive: true });
147
+ writeFileSync(tmp, `${JSON.stringify(receipt, null, 2)}\n`);
148
+ renameSync(tmp, path);
149
+ } catch (e) {
150
+ fatal(`cannot write receipt ${path}: ${e.message}`);
151
+ }
152
+ }
153
+
154
+ // ── begin ────────────────────────────────────────────────────────────────────
155
+
156
+ function stepDrain({ cwd, reason }) {
157
+ const r = node("ledger.mjs", ["drain", reason], { cwd });
158
+ return r.status === 0 ? ok(r.stdout) : failed(`ledger.mjs drain failed: ${detail(r)}`);
159
+ }
160
+
161
+ // What release-ticket.sh refused for: the blockers of its JSON receipt on
162
+ // stdout, else the first line it printed.
163
+ function blocker(r) {
164
+ try {
165
+ const { blockers } = JSON.parse(r.stdout);
166
+ if (Array.isArray(blockers) && blockers.length > 0) return blockers.join("; ");
167
+ } catch {
168
+ // Not a receipt: a refusal before it could write one, in prose.
169
+ }
170
+ return detail(r).split("\n")[0];
171
+ }
172
+
173
+ function stepRelease({ cwd }) {
174
+ const read = node("ledger.mjs", ["read"], { cwd });
175
+ if (read.status !== 0) return failed(`ledger.mjs read failed: ${detail(read)}`);
176
+ let rows;
177
+ try {
178
+ rows = JSON.parse(read.stdout).rows;
179
+ } catch (e) {
180
+ return failed(`ledger.mjs read: unparseable answer: ${e.message}`);
181
+ }
182
+ if (!Array.isArray(rows)) return failed("ledger.mjs read: no rows in its answer");
183
+
184
+ const lines = [];
185
+ let needs = 0;
186
+ const need = (line) => {
187
+ needs += 1;
188
+ lines.push(line);
189
+ };
190
+ for (const text of rows) {
191
+ if (rowPr(text) !== null) continue;
192
+ const members = memberTokens(text).filter((t) => t.family === "impl" && t.error === null && (t.outcome === null || t.outcome === "bailed"));
193
+ if (members.length === 0) continue;
194
+ const ticket = members[0].number;
195
+ const release = sh("release-ticket.sh", [String(ticket), `impl-${ticket}`, "implementer", "--apply"], { cwd });
196
+ if (release.status !== 0) {
197
+ need(`NEED hand-release #${ticket} ${blocker(release)}`);
198
+ continue;
199
+ }
200
+ lines.push(`released #${ticket}`);
201
+ for (const t of members.filter((m) => m.outcome === null)) {
202
+ const settle = node("ledger.mjs", ["settle", `${t.name}=released`], { cwd });
203
+ if (settle.status !== 0) need(`NEED hand-release #${ticket} released, but ledger.mjs settle ${t.name}=released failed: ${detail(settle)}`);
204
+ }
205
+ }
206
+ if (lines.length === 0) return ok("no claim to release");
207
+ return (needs > 0 ? pending : ok)(lines.join("\n"));
208
+ }
209
+
210
+ // ── finish ───────────────────────────────────────────────────────────────────
211
+
212
+ // The caps `phase0.mjs` recorded, as the tick's own flags; none when there is
213
+ // no receipt or it names none.
214
+ function tickCaps(fleetDir) {
215
+ let phase0;
216
+ try {
217
+ phase0 = JSON.parse(readFileSync(join(fleetDir, RECEIPT), "utf8"));
218
+ } catch (e) {
219
+ if (e.code === "ENOENT") return { args: [] };
220
+ return { error: `cannot read ${join(fleetDir, RECEIPT)}: ${e.message}` };
221
+ }
222
+ const args = [];
223
+ if (phase0?.caps?.impl != null) args.push("--implementer-cap", String(phase0.caps.impl));
224
+ if (phase0?.caps?.review != null) args.push("--reviewer-cap", String(phase0.caps.review));
225
+ return { args };
226
+ }
227
+
228
+ function stepTick({ cwd, fleetDir }) {
229
+ const caps = tickCaps(fleetDir);
230
+ if (caps.error) return failed(caps.error);
231
+ const r = node("fleet-tick.mjs", caps.args, { cwd });
232
+ if (r.status !== 0) return failed(`fleet-tick.mjs failed: ${detail(r)}`);
233
+ const last = r.stdout.split("\n").at(-1);
234
+ if (!last.startsWith(TICK_OVER)) return failed(`the tick's last line is not \`${TICK_OVER}\`: ${last || "(no output)"}`);
235
+ return ok(last);
236
+ }
237
+
238
+ function stepScrape({ cwd }) {
239
+ let root;
240
+ try {
241
+ const home = process.env.HOME ?? homedir();
242
+ root = join(home, ".omp", "agent", "sessions", encodeProjectDir(cwd, { home }));
243
+ } catch (e) {
244
+ return failed(`cannot name this cwd's omp session directory: ${e.message}`);
245
+ }
246
+ let sessions;
247
+ try {
248
+ // Directories only: the same directory holds this cwd's own top-level
249
+ // transcripts as loose files, which are not sessions.
250
+ sessions = readdirSync(root, { withFileTypes: true }).filter((e) => e.isDirectory() && isOmpSessionDirName(e.name)).map((e) => e.name).sort();
251
+ } catch (e) {
252
+ if (e.code === "ENOENT") return ok(`no session directory at ${root}`);
253
+ return failed(`cannot read ${root}: ${e.code ?? e.message}`);
254
+ }
255
+ if (sessions.length === 0) return ok(`no session under ${root}`);
256
+ const lines = [];
257
+ for (const name of sessions) {
258
+ const r = node("member-outcomes.mjs", [join(root, name)], { cwd });
259
+ if (r.status !== 0) return failed([...lines, `member-outcomes.mjs ${name} failed: ${detail(r)}`].join("\n"));
260
+ lines.push(`${name}: ${r.stderr || r.stdout}`);
261
+ }
262
+ return ok(lines.join("\n"));
263
+ }
264
+
265
+ function stepTierOutcomes({ cwd }) {
266
+ const r = node("tier-outcomes.mjs", ["check", "--live"], { cwd });
267
+ if (r.status !== 0) return failed(`tier-outcomes.mjs check --live failed: ${detail(r)}`);
268
+ const prs = [...new Set([...r.stderr.matchAll(/WARNING PR #(\d+) carries reviewed=/g)].map((m) => m[1]))];
269
+ if (prs.length > 0) return pending(prs.map((pr) => `NEED tier-outcomes append ${pr}`).join("\n"));
270
+ return ok(r.stdout);
271
+ }
272
+
273
+ function stepMetrics({ cwd }) {
274
+ const r = node("metrics-refresh.mjs", [], { cwd });
275
+ return r.status === 0 ? ok(r.stdout) : failed(`metrics-refresh.mjs failed: ${detail(r)}`);
276
+ }
277
+
278
+ // A name for the metrics branch: `--branch` as given, else the dated default,
279
+ // lettered while the name is taken. A probe that fails to answer is no answer
280
+ // at all, never "not taken".
281
+ function pickBranch(git, given) {
282
+ if (given !== null) return { name: given };
283
+ const base = `chore/run-artifacts-${new Date().toISOString().slice(0, 10).replaceAll("-", "")}`;
284
+ for (const suffix of ["", ..."bcdefghijklmnopqrstuvwxyz"]) {
285
+ const name = base + suffix;
286
+ const local = git(["show-ref", "--verify", "--quiet", `refs/heads/${name}`]);
287
+ if (local.status !== 0 && local.status !== 1) return { error: `git show-ref refs/heads/${name} failed: ${detail(local)}` };
288
+ const remote = git(["ls-remote", "--exit-code", "--heads", "origin", name], NETWORK_TIMEOUT_MS);
289
+ if (remote.status !== 0 && remote.status !== 2) return { error: `git ls-remote origin ${name} failed: ${detail(remote)}` };
290
+ if (local.status === 1 && remote.status === 2) return { name };
291
+ }
292
+ return { error: `every lettered ${base} name is taken` };
293
+ }
294
+
295
+ // The rows each metrics file gained and lost on the branch, one TSV line a row.
296
+ function rowCounts(git) {
297
+ const r = git(["diff", "--numstat", "origin/main...HEAD", "--", ...METRICS]);
298
+ if (r.status !== 0) return { error: `git diff --numstat failed: ${detail(r)}` };
299
+ return { lines: r.stdout.split("\n").filter(Boolean).map((l) => l.split("\t")).map(([added, removed, file]) => `- ${file}: +${added} -${removed}`) };
300
+ }
301
+
302
+ // Everything the step does while the checkout is on the metrics branch; the
303
+ // caller switches back to main whatever this returns.
304
+ function onBranch({ git, cwd, reason, receipt, save }) {
305
+ const dirty = git(["status", "--porcelain", "--", ...METRICS]);
306
+ if (dirty.status !== 0) return failed(`git status failed: ${detail(dirty)}`);
307
+ if (dirty.stdout !== "") {
308
+ const commit = git(["commit", "-m", `Closeout: ${reason}`, "--", ...METRICS]);
309
+ if (commit.status !== 0) return failed(`git commit failed: ${detail(commit)}`);
310
+ }
311
+ const ahead = git(["rev-list", "--count", "origin/main..HEAD"]);
312
+ if (ahead.status !== 0) return failed(`git rev-list --count origin/main..HEAD failed: ${detail(ahead)}`);
313
+ if (ahead.stdout === "0") return failed(`nothing to commit: ${METRICS.join(", ")} are unchanged`);
314
+
315
+ const push = git(["push", "-u", "origin", receipt.branch], NETWORK_TIMEOUT_MS);
316
+ if (push.status !== 0) return failed(`git push failed: ${detail(push)}`);
317
+
318
+ if (receipt.pr !== null) return ok(`PR ${receipt.pr} already opened for ${receipt.branch}`);
319
+ const counts = rowCounts(git);
320
+ if (counts.error) return failed(counts.error);
321
+ const body = `Closeout: ${reason}\n\nRows changed:\n${counts.lines.join("\n")}\n`;
322
+ const pr = run("gh", ["pr", "create", "--head", receipt.branch, "--title", `Closeout: ${reason}`, "--label", "patch", "--body", body], { cwd, env: { GH_REPO: "" }, timeoutMs: NETWORK_TIMEOUT_MS });
323
+ if (pr.status !== 0) return failed(`gh pr create failed: ${detail(pr)}`);
324
+ receipt.pr = pr.stdout.split("\n").at(-1);
325
+ save();
326
+ return ok(`PR ${receipt.pr} opened on ${receipt.branch}`);
327
+ }
328
+
329
+ function stepCommitAndPR({ reason, branch, receipt, save }) {
330
+ const top = run("git", ["rev-parse", "--show-toplevel"], { cwd: process.cwd() });
331
+ if (top.status !== 0) return failed(`not inside a git work tree: ${detail(top)}`);
332
+ const cwd = top.stdout;
333
+ const git = (args, timeoutMs) => run("git", args, { cwd, timeoutMs });
334
+
335
+ if (receipt.branch === null) {
336
+ const picked = pickBranch(git, branch);
337
+ if (picked.error) return failed(picked.error);
338
+ const made = git(["switch", "-c", picked.name]);
339
+ if (made.status !== 0) return failed(`git switch -c ${picked.name} failed: ${detail(made)}`);
340
+ receipt.branch = picked.name;
341
+ save();
342
+ } else {
343
+ const back = git(["switch", receipt.branch]);
344
+ if (back.status !== 0) return failed(`git switch ${receipt.branch} failed: ${detail(back)}`);
345
+ }
346
+ const result = onBranch({ git, cwd, reason, receipt, save });
347
+ const main = git(["switch", "main"]);
348
+ if (main.status !== 0) return failed([result.status === "ok" ? null : result.output, `git switch main failed: ${detail(main)}`].filter(Boolean).join("\n"));
349
+ return result;
350
+ }
351
+
352
+ function stepHeartbeatStop({ cwd, reason }) {
353
+ const r = node("fleet-heartbeat.mjs", ["--stop", reason], { cwd });
354
+ return r.status === 0 ? ok(r.stdout) : failed(`fleet-heartbeat.mjs --stop failed: ${detail(r)}`);
355
+ }
356
+
357
+ // ── the steps, in order ──────────────────────────────────────────────────────
358
+
359
+ const BEGIN = { drain: stepDrain, release: stepRelease };
360
+ const FINISH = {
361
+ tick: stepTick,
362
+ scrape: stepScrape,
363
+ "tier-outcomes": stepTierOutcomes,
364
+ metrics: stepMetrics,
365
+ "commit-and-pr": stepCommitAndPR,
366
+ "heartbeat-stop": stepHeartbeatStop,
367
+ };
368
+ const STEP_NAMES = [...Object.keys(BEGIN), ...Object.keys(FINISH)];
369
+
370
+ const say = (line) => process.stdout.write(`${line}\n`);
371
+
372
+ // Runs `steps` in order against the receipt, skipping every `ok` one, and
373
+ // stops at the first that is not: the receipt is written after each step, and
374
+ // the exit status is the one that step earns.
375
+ function runSteps(steps, ctx, receipt, receiptPath) {
376
+ const save = () => writeReceipt(receiptPath, receipt);
377
+ for (const [name, step] of Object.entries(steps)) {
378
+ if (receipt.steps[name].status !== "ok") {
379
+ const result = step({ ...ctx, receipt, save });
380
+ receipt.steps[name] = { status: result.status, at: new Date().toISOString(), output: result.output };
381
+ save();
382
+ }
383
+ const { status, output } = receipt.steps[name];
384
+ say(`${NAME}: ${name}: ${status}`);
385
+ for (const line of output.split("\n").filter(Boolean)) say(line.startsWith("NEED ") ? line : ` ${line}`);
386
+ if (status === "failed") return 3;
387
+ if (status === "pending") return 4;
388
+ }
389
+ return 0;
390
+ }
391
+
392
+ function main() {
393
+ const die = makeDie(NAME);
394
+ const F = defineFlags(die, { flags: { reason: "value", branch: "value" }, positionals: ["begin", "finish"] });
395
+ F.sweep();
396
+ F.stray();
397
+ const cmd = process.argv[2];
398
+ if (cmd !== "begin" && cmd !== "finish") die(`usage: ${NAME}.mjs begin --reason <reason> | finish --reason <reason> [--branch <name>]`);
399
+ const reason = F.arg("reason");
400
+ if (reason === null) die("--reason is required");
401
+ const branch = F.arg("branch");
402
+ if (branch !== null && cmd === "begin") die("--branch belongs to finish");
403
+
404
+ let fleetDir;
405
+ try {
406
+ fleetDir = fleetFile(null);
407
+ } catch (e) {
408
+ if (!(e instanceof FleetDirUnresolvable)) throw e;
409
+ die(e.message);
410
+ }
411
+ const receiptPath = join(fleetDir, CLOSEOUT_RECEIPT);
412
+ const receipt = readReceipt(receiptPath, STEP_NAMES);
413
+ receipt.reason = reason;
414
+ const ctx = { cwd: process.cwd(), fleetDir, reason, branch };
415
+
416
+ if (cmd === "begin") {
417
+ const code = runSteps(BEGIN, ctx, receipt, receiptPath);
418
+ if (receipt.steps.drain.status === "ok" && receipt.steps.release.status !== "failed") {
419
+ receipt.begun = new Date().toISOString();
420
+ writeReceipt(receiptPath, receipt);
421
+ }
422
+ process.exitCode = code;
423
+ } else {
424
+ process.exitCode = runSteps(FINISH, ctx, receipt, receiptPath);
425
+ }
426
+ }
427
+
428
+ if (isCLI(import.meta.url)) main();
@@ -22,13 +22,17 @@
22
22
  import { createHash } from "node:crypto";
23
23
 
24
24
  // How an archive beside the ledger is named. `ledger.mjs rotate` files the
25
- // ledger as `ledger.<stamp>.md` and the phase-0 receipt as `phase0.<stamp>.json`
26
- // under one stamp, and `phase0.mjs` files a receipt the rotation left behind
27
- // the same way, so the format lives here once.
25
+ // ledger as `ledger.<stamp>.md` and the two run receipts, the phase-0 one as
26
+ // `phase0.<stamp>.json` and the end-of-run one as `closeout.<stamp>.json`,
27
+ // under one stamp. `phase0.mjs` files a phase-0 receipt the rotation left
28
+ // behind the same way, so the format lives here once.
28
29
  const RECEIPT_STEM = "phase0";
29
30
  export const RECEIPT = `${RECEIPT_STEM}.json`;
30
31
  export const archiveStamp = () => new Date().toISOString().replace(/\.\d{3}Z$/, "Z").replaceAll(":", "");
31
32
  export const receiptArchiveName = (stamp) => `${RECEIPT_STEM}.${stamp}.json`;
33
+ const CLOSEOUT_STEM = "closeout";
34
+ export const CLOSEOUT_RECEIPT = `${CLOSEOUT_STEM}.json`;
35
+ export const closeoutArchiveName = (stamp) => `${CLOSEOUT_STEM}.${stamp}.json`;
32
36
 
33
37
  // The outcome vocabulary, verbatim from the spec. A word is matched exactly,
34
38
  // except the three that carry a value, which match OUTCOME_PATTERNS below.
@@ -47,7 +47,7 @@ import { fileURLToPath } from "node:url";
47
47
  import { spawnSync, execFileSync } from "node:child_process";
48
48
  import { makeDie, isFlagLike, hasEqualsForm, isDigits } from "./arg.mjs";
49
49
  import { fleetFile, FleetDirUnresolvable } from "./fleet-dir.mjs";
50
- import { parseMember, parseToken, memberTokens, nextMergeBot, nextRetry, liveOnLedger, retiredOnLedger, isRetirable, agentDefinition, CELL, tierValues, rowPr, rowWriteRefusal, isReviewToken, addedReviewToken, newSplitRow, splitRowClause, added, premisesOf, MEMBER_FAMILIES, ROWS, DISPATCHED, FILED, RULED, DRAIN, RETIRED, RECEIPT, archiveStamp, receiptArchiveName, headerRe, escapeText, unescapeText } from "./ledger-grammar.mjs";
50
+ import { parseMember, parseToken, memberTokens, nextMergeBot, nextRetry, liveOnLedger, retiredOnLedger, isRetirable, agentDefinition, CELL, tierValues, rowPr, rowWriteRefusal, isReviewToken, addedReviewToken, newSplitRow, splitRowClause, added, premisesOf, MEMBER_FAMILIES, ROWS, DISPATCHED, FILED, RULED, DRAIN, RETIRED, RECEIPT, archiveStamp, receiptArchiveName, CLOSEOUT_RECEIPT, closeoutArchiveName, headerRe, escapeText, unescapeText } from "./ledger-grammar.mjs";
51
51
  import { deriveRun, LedgerError, labelOffMember, HELD, CONFLICT_HOLD } from "./fleet-tick.mjs";
52
52
  import { stateFileIn, readState, writeState, assessBeat, stallsAt } from "./fleet-state.mjs";
53
53
  import { processSource, ancestry, controllerOf, judgeController, ProcUnreadable } from "./proc.mjs";
@@ -1446,10 +1446,10 @@ function runCheck() {
1446
1446
  // hard-linked to its stamped name, then unlinked or, when a successor is
1447
1447
  // carried, replaced by it — so its bytes are untouched, and the link refuses
1448
1448
  // atomically when that name is already taken rather than overwriting an older
1449
- // archive. A `phase0.json` receipt beside the ledger belongs to the same run,
1450
- // so it is archived as `phase0.<stamp>.json` under the ledger archive's own
1451
- // stamp — a warning-only move after the ledger move, refused up front only
1452
- // when that name is taken.
1449
+ // archive. The two receipts beside the ledger, `phase0.json` and
1450
+ // `closeout.json`, belong to the same run, so each is archived as
1451
+ // `<name>.<stamp>.json` under the ledger archive's own stamp — a warning-only
1452
+ // move after the ledger move, refused up front only when a name is taken.
1453
1453
  //
1454
1454
  // What follows depends on the verdict below. After a `dead` or `none` one
1455
1455
  // nothing is carried: the next write subcommand finds no file and starts the
@@ -1567,14 +1567,17 @@ function runRotate() {
1567
1567
  carry = carryOf(text);
1568
1568
  }
1569
1569
  const carrying = carry.rows.length > 0 || carry.dispatched.length > 0 || carry.retired.length > 0;
1570
- // The phase-0 receipt beside the ledger belongs to the run being rotated
1571
- // away, so it takes the archive's own stamp: `phase0.<stamp>.json` next to
1572
- // `ledger.<stamp>.md`. A name already taken refuses before anything moves,
1573
- // as the ledger's own does.
1570
+ // The receipts beside the ledger belong to the run being rotated away, so
1571
+ // each takes the archive's own stamp: `phase0.<stamp>.json` and
1572
+ // `closeout.<stamp>.json` next to `ledger.<stamp>.md`. A name already taken
1573
+ // refuses before anything moves, as the ledger's own does.
1574
1574
  const stamp = archiveStamp();
1575
- const receipt = join(dirname(file), RECEIPT);
1576
- const receiptArchive = existsSync(receipt) ? join(dirname(file), receiptArchiveName(stamp)) : null;
1577
- if (receiptArchive !== null && existsSync(receiptArchive)) die(`refusing to rotate ${file}: ${receiptArchive} already exists`);
1575
+ const receipts = [[RECEIPT, receiptArchiveName], [CLOSEOUT_RECEIPT, closeoutArchiveName]]
1576
+ .map(([name, archiveName]) => ({ from: join(dirname(file), name), to: join(dirname(file), archiveName(stamp)) }))
1577
+ .filter(({ from }) => existsSync(from));
1578
+ for (const { to } of receipts) {
1579
+ if (existsSync(to)) die(`refusing to rotate ${file}: ${to} already exists`);
1580
+ }
1578
1581
  let archive = null;
1579
1582
  if (exists) {
1580
1583
  archive = join(dirname(file), `${basename(file, ".md")}.${stamp}.md`);
@@ -1601,12 +1604,12 @@ function runRotate() {
1601
1604
  // After the ledger has moved, and a warning rather than a refusal: the
1602
1605
  // ledger is already archived, and a receipt left where it is is read as a
1603
1606
  // previous run's by the next phase 0, which moves it aside itself.
1604
- if (receiptArchive !== null) {
1607
+ for (const { from, to } of receipts) {
1605
1608
  try {
1606
- renameSync(receipt, receiptArchive);
1607
- console.error(` archived ${receipt} -> ${receiptArchive}`);
1609
+ renameSync(from, to);
1610
+ console.error(` archived ${from} -> ${to}`);
1608
1611
  } catch (e) {
1609
- console.error(` could not archive ${receipt} -> ${receiptArchive}: ${e.message}`);
1612
+ console.error(` could not archive ${from} -> ${to}: ${e.message}`);
1610
1613
  }
1611
1614
  }
1612
1615
  // Nothing to carry writes nothing, so the next write starts the skeleton