@feigi/fleet-ctl 3.51.0 → 3.52.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.51.0",
3
+ "version": "3.52.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": {
@@ -21,6 +21,15 @@
21
21
 
22
22
  import { createHash } from "node:crypto";
23
23
 
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.
28
+ const RECEIPT_STEM = "phase0";
29
+ export const RECEIPT = `${RECEIPT_STEM}.json`;
30
+ export const archiveStamp = () => new Date().toISOString().replace(/\.\d{3}Z$/, "Z").replaceAll(":", "");
31
+ export const receiptArchiveName = (stamp) => `${RECEIPT_STEM}.${stamp}.json`;
32
+
24
33
  // The outcome vocabulary, verbatim from the spec. A word is matched exactly,
25
34
  // except the three that carry a value, which match OUTCOME_PATTERNS below.
26
35
  const FAMILIES = {
@@ -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, 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, 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,7 +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.
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.
1450
1453
  //
1451
1454
  // What follows depends on the verdict below. After a `dead` or `none` one
1452
1455
  // nothing is carried: the next write subcommand finds no file and starts the
@@ -1564,9 +1567,16 @@ function runRotate() {
1564
1567
  carry = carryOf(text);
1565
1568
  }
1566
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.
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`);
1567
1578
  let archive = null;
1568
1579
  if (exists) {
1569
- const stamp = new Date().toISOString().replace(/\.\d{3}Z$/, "Z").replaceAll(":", "");
1570
1580
  archive = join(dirname(file), `${basename(file, ".md")}.${stamp}.md`);
1571
1581
  try {
1572
1582
  linkSync(file, archive);
@@ -1588,6 +1598,17 @@ function runRotate() {
1588
1598
  } else {
1589
1599
  console.error(` nothing to rotate: ${file} does not exist`);
1590
1600
  }
1601
+ // After the ledger has moved, and a warning rather than a refusal: the
1602
+ // ledger is already archived, and a receipt left where it is is read as a
1603
+ // previous run's by the next phase 0, which moves it aside itself.
1604
+ if (receiptArchive !== null) {
1605
+ try {
1606
+ renameSync(receipt, receiptArchive);
1607
+ console.error(` archived ${receipt} -> ${receiptArchive}`);
1608
+ } catch (e) {
1609
+ console.error(` could not archive ${receipt} -> ${receiptArchive}: ${e.message}`);
1610
+ }
1611
+ }
1591
1612
  // Nothing to carry writes nothing, so the next write starts the skeleton
1592
1613
  // exactly as after any other verdict.
1593
1614
  if (carrying) {
@@ -0,0 +1,562 @@
1
+ #!/usr/bin/env node
2
+ // Phase 0 as one command: the run's start sequence, in order, with a receipt.
3
+ //
4
+ // phase0.mjs --session <dir> [--implementer-cap n] [--reviewer-cap n]
5
+ // [--plugin-checkout <dir>] [--spend-dir <dir>]
6
+ // [--workflow <name> | --declare-no-ci]
7
+ //
8
+ // Reached through the Resolver and run from the MAIN checkout (a linked
9
+ // worktree refuses: the checks below judge the checkout the controller reads
10
+ // its rules from). The steps, each a named entry in the receipt, run in
11
+ // this order because the order is the point — the pin certifies the tree the
12
+ // fast-forward left, the rotation comes before the fold-in, the scratch
13
+ // reclaim straight after the rotation, the metrics refresh before the first
14
+ // Pull is routed:
15
+ //
16
+ // branch `git symbolic-ref -q HEAD` is refs/heads/main. A checkout left
17
+ // on a branch whose PR has merged would fast-forward that branch
18
+ // and the baseline would record it as the run's ref.
19
+ // fast-forward `git fetch origin`, `rev-list --count main..origin/main`,
20
+ // `merge --ff-only origin/main`. HEAD moving means the rules this
21
+ // script came from are superseded: prints `SUPERSEDED <n>
22
+ // commits; re-run phase0.mjs` and fails, so the re-run executes
23
+ // from the new tree.
24
+ // pin `instruments.sh --pin`, with `--audit <plugin-checkout>` when
25
+ // given (a workspace that tracks no `plugin/…` of its own).
26
+ // baseline `main-checkout.mjs --record`; its refusals fail the step.
27
+ // preflight `preflight.mjs`. A non-zero exit fails the step; the FAIL, WARN
28
+ // and PREFLIGHT lines of an exit 1 are printed.
29
+ // ruleset `.github/scripts/apply-ruleset.sh --check`, when the workspace
30
+ // checks a ruleset spec in. Exit 3 is `drift` (the diff is the
31
+ // output), exit 2 or anything else `unanswered`; neither stops
32
+ // the run — reconciling is a write to the gate and the
33
+ // maintainer's.
34
+ // tier-roles `tier-roles.mjs --check`.
35
+ // metrics `metrics-refresh.mjs`. A non-zero exit fails the step.
36
+ // cockpit `board.mjs serve --open` launched detached, `--spend-dir`
37
+ // passed through. Recorded; never fails the run.
38
+ // rotate `ledger.mjs rotate`. Exit 2 is a refusal and fails the step.
39
+ // reclaim `reclaim-scratch.mjs --root <scratch> --after-rotate --apply`.
40
+ // Recorded; never fails the run.
41
+ // recipe `derive-testcmd.sh . install` and `. test --at origin/main`.
42
+ // Either exiting 1 is a cache with nothing valid in it: pending,
43
+ // `NEED derive-recipe`. Exit 3 (a tool the reader could not run)
44
+ // fails the step — deriving would not help.
45
+ // fold-in every open PR no carried ledger row names: one that closes an
46
+ // issue gets a `#<pr>` row from `ledger.mjs row` (the tick queues
47
+ // its review off it); one that closes none is listed as `NEED
48
+ // review PR#<pr> (closes no issue)`.
49
+ // stranded `stranded.mjs`. A `resume` entry whose ticket has no ledger row
50
+ // yet is pending: `NEED resume #<n> <worktree> <branch>`. A
51
+ // `report` entry is printed. Resuming a claim writes its row, so
52
+ // a re-run after the dispatch finds the need met.
53
+ // shortlist `shortlist.mjs`. A non-zero exit fails the step.
54
+ //
55
+ // THE RECEIPT is `.fleet/phase0.json` (resolved through fleet-dir.mjs, so a
56
+ // worktree and the main checkout name one file):
57
+ //
58
+ // { run, session, scratch, caps: {impl, review},
59
+ // steps: { <name>: { status, at, output } } }
60
+ //
61
+ // `status` is ok, pending, failed, drift or unanswered; `at` an ISO time;
62
+ // `output` the step's own words — the refusal for a failure, the NEED lines for
63
+ // a pending step. Every step name is always present: one not yet run is
64
+ // `pending`. `run` is the `at` that `ledger.mjs rotate` wrote into the
65
+ // controller record in `.fleet/heartbeat.json`, null until the rotation has
66
+ // run. `session` is `--session`, the one place the controller states its
67
+ // session directory. `scratch` is what `scratch-root.mjs` prints. `caps` are
68
+ // the flags as given, null for one not given: the tick's own defaults apply to
69
+ // a cap nobody set, and a number here would pretend somebody had.
70
+ //
71
+ // RESUMABLE. A re-run reads the receipt. It continues it — skipping every `ok`
72
+ // step and re-running the rest — only when its `run` equals the `at` the
73
+ // controller record holds now AND its `session` equals `--session`. That
74
+ // comparison alone does not separate two runs before the new run's rotation:
75
+ // the record still carries the previous run's `at` until `ledger.mjs rotate`
76
+ // writes the next, so the previous run's receipt still matches it, and a
77
+ // re-run that trusted `run` alone would skip `rotate`. The session rule closes
78
+ // a new session. A receipt of any other run (a `run` that is set and does not
79
+ // match, or a different session) is held as `phase0.previous.json` and the
80
+ // script starts at `branch`; this run's own receipt is written at
81
+ // `phase0.json` after every step. A receipt whose rotation has not run is
82
+ // simply overwritten: every step before `rotate` is idempotent and is re-run
83
+ // on every invocation until the rotation has run.
84
+ //
85
+ // THE ROTATION FILES THE PREVIOUS RUN'S RECEIPT. The `rotate` step takes this
86
+ // run's partial receipt off disk, puts the held one back at `phase0.json` and
87
+ // runs `ledger.mjs rotate`, which archives it as `phase0.<UTC stamp>.json`
88
+ // beside `ledger.<UTC stamp>.md`, one stamp for both. A rotation that refused
89
+ // leaves it held for the next attempt; one that archived the ledger and not
90
+ // the receipt files it under a stamp of this script's own. With no omp process
91
+ // above the run the rotation writes no controller record and `run` stays
92
+ // null; a receipt whose `rotate` step is `ok` is then resumed on the session
93
+ // alone.
94
+ //
95
+ // A step that fails stops the script; so does a pending one — nothing after
96
+ // the recipe may run before it is proven, and the shortlist waits for the
97
+ // stranded claims. The steps after it stay `pending` in the receipt.
98
+ //
99
+ // `--workflow` and `--declare-no-ci` name how a repository without a workflow
100
+ // called CI runs. `preflight.mjs` takes no arguments, so they are not passed
101
+ // to it: they are checked against each other here and recorded in the
102
+ // `preflight` step's output.
103
+ //
104
+ // One `phase0: <step>: <status> …` line per step on stdout, a step's further
105
+ // output indented under it when there is any, and the `NEED` lines last.
106
+ // Exit 0 every step ok, or `drift`/`unanswered` — advice the run goes on past;
107
+ // 2 a usage error; 3 a step failed, or the run could not start or record itself
108
+ // (the scratch root, the controller record, the receipt); 4 a step needs the
109
+ // controller — dispatch what the NEED line names, then run this again. A NEED
110
+ // the fold-in prints is advice too and changes no exit status: a PR with no
111
+ // issue behind it is the controller's to queue or leave, and nothing a re-run
112
+ // could meet.
113
+ //
114
+ // Zero deps: node builtins and sibling scripts only.
115
+
116
+ import { spawn, spawnSync } from "node:child_process";
117
+ import { existsSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
118
+ import { dirname, join, resolve } from "node:path";
119
+ import { fileURLToPath } from "node:url";
120
+ import { makeDie, defineFlags, isDigits } from "./arg.mjs";
121
+ import { FleetDirUnresolvable, fleetFile } from "./fleet-dir.mjs";
122
+ import { readState, stateFileIn } from "./fleet-state.mjs";
123
+ import { gitEnv } from "./git-env.mjs";
124
+ import { isCLI } from "./is-cli.mjs";
125
+ import { RECEIPT, archiveStamp, receiptArchiveName, rowNums } from "./ledger-grammar.mjs";
126
+
127
+ const NAME = "phase0";
128
+ const SCRIPTS = dirname(fileURLToPath(import.meta.url));
129
+ const MAX_BUFFER = 64 * 1024 * 1024;
130
+ const NETWORK_TIMEOUT_MS = 120_000;
131
+ const PR_LIMIT = 1000;
132
+ // The tail of a child's output is the part that says why it stopped.
133
+ const OUTPUT_MAX = 16_000;
134
+ // The previous run's receipt, set aside at startup until the rotation files it.
135
+ const HELD = "phase0.previous.json";
136
+ const RULESET_SPEC = join(".github", "rulesets", "main.json");
137
+ const RULESET_CHECK = join(".github", "scripts", "apply-ruleset.sh");
138
+
139
+ const script = (name) => join(SCRIPTS, name);
140
+
141
+ function how(r) {
142
+ if (r.error) return r.error.code ?? r.error.message;
143
+ if (r.signal) return `killed by ${r.signal}`;
144
+ return `exit ${r.status}`;
145
+ }
146
+
147
+ const trimmed = (s) => String(s ?? "").trim();
148
+ const lines = (s) => trimmed(s).split("\n").filter((l) => l.trim() !== "");
149
+
150
+ /**
151
+ * Runs a child to completion from `cwd`. `status` is the exit status, null
152
+ * when the child never ran or was killed (`how` says which); `text` is its
153
+ * stdout then stderr, trimmed.
154
+ */
155
+ function run(cmd, args, { cwd, env, timeoutMs } = {}) {
156
+ const r = spawnSync(cmd, args, {
157
+ cwd, encoding: "utf8", maxBuffer: MAX_BUFFER, env: gitEnv(env), timeout: timeoutMs,
158
+ });
159
+ const stdout = trimmed(r.stdout);
160
+ const stderr = trimmed(r.stderr);
161
+ return { status: r.error ? null : r.status, stdout, stderr, text: [stdout, stderr].filter(Boolean).join("\n"), how: how(r) };
162
+ }
163
+
164
+ const node = (name, args, opts) => run(process.execPath, [script(name), ...args], opts);
165
+ const sh = (name, args, opts) => run("sh", [script(name), ...args], opts);
166
+
167
+ const ok = (output) => ({ status: "ok", output });
168
+ const failed = (output) => ({ status: "failed", output });
169
+ const withText = (head, r) => (r.text ? `${head}\n${r.text}` : head);
170
+ const refusal = (what, r) => failed(withText(`${what} ${r.how}`, r));
171
+
172
+ // ── the steps ────────────────────────────────────────────────────────────────
173
+
174
+ function branch({ cwd }) {
175
+ const r = run("git", ["symbolic-ref", "-q", "HEAD"], { cwd });
176
+ if (r.status === 0 && r.stdout === "refs/heads/main") return ok("HEAD is refs/heads/main");
177
+ const now = r.status === 0 ? r.stdout : r.status === 1 ? "detached" : `unreadable (${r.how})`;
178
+ return failed(`HEAD is ${now}, not refs/heads/main — switch the checkout to main before the run starts`);
179
+ }
180
+
181
+ function fastForward({ cwd }) {
182
+ const fetch = run("git", ["fetch", "origin"], { cwd, timeoutMs: NETWORK_TIMEOUT_MS });
183
+ if (fetch.status !== 0) return refusal("git fetch origin failed:", fetch);
184
+ const count = run("git", ["rev-list", "--count", "main..origin/main"], { cwd });
185
+ if (count.status !== 0 || !isDigits(count.stdout)) return refusal("git rev-list --count main..origin/main failed:", count);
186
+ const behind = Number(count.stdout);
187
+ if (behind === 0) return ok("main is level with origin/main");
188
+ const merge = run("git", ["merge", "--ff-only", "origin/main"], { cwd });
189
+ if (merge.status !== 0) return refusal("git merge --ff-only origin/main failed:", merge);
190
+ return failed(`SUPERSEDED ${behind} commits; re-run phase0.mjs`);
191
+ }
192
+
193
+ function pin({ cwd, pluginCheckout }) {
194
+ const r = sh("instruments.sh", ["--pin", ...(pluginCheckout ? ["--audit", pluginCheckout] : [])], { cwd });
195
+ if (r.status !== 0) return refusal("instruments.sh --pin failed:", r);
196
+ return ok(pluginCheckout ? `instruments pinned, auditing ${pluginCheckout}` : "instruments pinned");
197
+ }
198
+
199
+ function baseline({ cwd }) {
200
+ const r = node("main-checkout.mjs", ["--record"], { cwd });
201
+ if (r.status !== 0) return refusal("main-checkout.mjs --record refused:", r);
202
+ return ok("main-checkout baseline recorded");
203
+ }
204
+
205
+ function preflight({ cwd, ci }) {
206
+ const r = node("preflight.mjs", [], { cwd });
207
+ if (r.status !== 0) {
208
+ // Exit 1 is a row that failed, and its FAIL, WARN and PREFLIGHT lines are
209
+ // the report; exit 2 is a script that could not run, whose own words are
210
+ // all there is, as are an exit 1 that printed none of those lines.
211
+ const fails = r.status === 1 ? lines(r.text).filter((l) => /^(FAIL|WARN|PREFLIGHT)/.test(l)) : [];
212
+ const keep = fails.length > 0 ? fails : lines(r.text);
213
+ return failed([`preflight.mjs ${r.how}`, ...keep].join("\n"));
214
+ }
215
+ return ok([`preflight.mjs passed (${lines(r.stdout).at(-1) ?? "no output"})`, ...(ci === null ? [] : [ci])].join("\n"));
216
+ }
217
+
218
+ function ruleset({ cwd }) {
219
+ if (!existsSync(join(cwd, RULESET_SPEC))) return ok(`no ruleset spec at ${RULESET_SPEC} — nothing to check`);
220
+ const r = run("bash", [join(cwd, RULESET_CHECK), "--check"], { cwd, timeoutMs: NETWORK_TIMEOUT_MS });
221
+ if (r.status === 0) return ok("the live gate matches the ruleset spec");
222
+ if (r.status === 3) return { status: "drift", output: withText("the live gate differs from the ruleset spec", r) };
223
+ return { status: "unanswered", output: withText(`apply-ruleset.sh --check could not answer (${r.how})`, r) };
224
+ }
225
+
226
+ function tierRoles({ cwd }) {
227
+ const r = node("tier-roles.mjs", ["--check"], { cwd });
228
+ if (r.status !== 0) return refusal("tier-roles.mjs --check failed:", r);
229
+ return ok("every tier route resolves");
230
+ }
231
+
232
+ function metrics({ cwd }) {
233
+ const r = node("metrics-refresh.mjs", [], { cwd });
234
+ if (r.status !== 0) return refusal("metrics-refresh.mjs failed:", r);
235
+ return ok(withText("metrics-refresh.mjs ran", r));
236
+ }
237
+
238
+ function cockpit({ cwd, spendDir }) {
239
+ const args = [script("board.mjs"), "serve", "--open", ...(spendDir ? ["--spend-dir", spendDir] : [])];
240
+ let child;
241
+ try {
242
+ child = spawn(process.execPath, args, { cwd, detached: true, stdio: "ignore", env: gitEnv() });
243
+ } catch (e) {
244
+ return ok(`not launched: ${e.message}`);
245
+ }
246
+ // A launch that fails does so after this returns; nobody reads the event.
247
+ child.on("error", () => {});
248
+ child.unref();
249
+ return ok(child.pid === undefined ? "not launched" : `launched board.mjs serve, pid ${child.pid}`);
250
+ }
251
+
252
+ function rotate(ctx) {
253
+ // This run's own partial receipt is off disk while the rotation runs, so the
254
+ // archive cannot file it under the previous run's stamp. What the rotation
255
+ // finds beside the ledger is the previous run's receipt, held since startup.
256
+ rmSync(ctx.receiptPath, { force: true });
257
+ const restored = existsSync(ctx.held);
258
+ if (restored) renameSync(ctx.held, ctx.receiptPath);
259
+ const r = node("ledger.mjs", ["rotate"], { cwd: ctx.cwd });
260
+ if (restored && existsSync(ctx.receiptPath)) {
261
+ // Not archived. After a refusal it waits, held, for the next attempt; after
262
+ // a rotation that moved the ledger and not the receipt it is filed here,
263
+ // unless that name is taken.
264
+ const filed = join(ctx.fleetDir, receiptArchiveName(archiveStamp()));
265
+ renameSync(ctx.receiptPath, r.status === 0 && !existsSync(filed) ? filed : ctx.held);
266
+ }
267
+ if (r.status !== 0) return refusal("ledger.mjs rotate refused:", r);
268
+ const { controller } = readState(stateFileIn(ctx.fleetDir), NAME);
269
+ ctx.receipt.run = controller?.at ?? null;
270
+ const head = ctx.receipt.run === null ? "ledger rotated; no omp process above this run, so no controller record — a re-run is keyed on the session alone" : `ledger rotated, run ${ctx.receipt.run}`;
271
+ // What rotate says on stderr is the only account of rows it did not carry
272
+ // and a receipt it could not archive.
273
+ return ok([head, ...lines(r.stderr).map((l) => l.trim())].join("\n"));
274
+ }
275
+
276
+ function reclaim({ cwd, scratch }) {
277
+ const r = node("reclaim-scratch.mjs", ["--root", scratch, "--after-rotate", "--apply"], { cwd });
278
+ return ok(r.status === 0 ? "scratch reclaimed" : withText(`reclaim-scratch.mjs ${r.how}, not enforced`, r));
279
+ }
280
+
281
+ function recipe({ cwd }) {
282
+ const reads = [["install"], ["test", "--at", "origin/main"]].map((a) => ({ a, r: sh("derive-testcmd.sh", [".", ...a], { cwd }) }));
283
+ const broken = reads.filter(({ r }) => r.status === 3 || (r.status !== 0 && r.status !== 1));
284
+ if (broken.length > 0) {
285
+ return failed(broken.map(({ a, r }) => withText(`derive-testcmd.sh . ${a.join(" ")} ${r.how} — the cache's state is unknown, and deriving would not help`, r)).join("\n"));
286
+ }
287
+ const refused = reads.filter(({ r }) => r.status === 1);
288
+ if (refused.length > 0) {
289
+ return { status: "pending", output: [...refused.map(({ a, r }) => withText(`derive-testcmd.sh . ${a.join(" ")} refused:`, r)), "NEED derive-recipe"].join("\n") };
290
+ }
291
+ return ok(`Recipe cache valid: ${reads.map(({ r }) => lines(r.stdout).at(-1) ?? "").join(" ; ")}`);
292
+ }
293
+
294
+ // The ledger's rows, read through `ledger.mjs read` so the ledger keeps one
295
+ // parser. `{ error }` when the read did not answer, `{ rows }` otherwise.
296
+ function ledgerRows(cwd) {
297
+ const r = node("ledger.mjs", ["read"], { cwd });
298
+ if (r.status !== 0) return { error: withText(`ledger.mjs read ${r.how}`, r) };
299
+ try {
300
+ const { rows } = JSON.parse(r.stdout);
301
+ if (Array.isArray(rows) && rows.every((x) => typeof x === "string")) return { rows };
302
+ } catch {
303
+ // Falls through to the refusal below.
304
+ }
305
+ return { error: "ledger.mjs read printed no {rows}" };
306
+ }
307
+
308
+ const rowKey = (row) => row.split(/\s/)[0];
309
+
310
+ function foldIn({ cwd }) {
311
+ const list = run("gh", ["pr", "list", "--state", "open", "--json", "number,closingIssuesReferences", "--limit", String(PR_LIMIT)], {
312
+ cwd, env: { GH_REPO: "" }, timeoutMs: NETWORK_TIMEOUT_MS,
313
+ });
314
+ if (list.status !== 0) return refusal("gh pr list failed:", list);
315
+ let prs;
316
+ try {
317
+ prs = JSON.parse(list.stdout);
318
+ } catch (e) {
319
+ return failed(`could not parse gh pr list: ${e.message}`);
320
+ }
321
+ if (!Array.isArray(prs)) return failed("gh pr list did not print a JSON array");
322
+ if (prs.length >= PR_LIMIT) return failed(`gh pr list came back at its cap of ${PR_LIMIT} — it may hold more PRs than it showed, so none is folded in`);
323
+ const ledger = ledgerRows(cwd);
324
+ if (ledger.error) return failed(`${ledger.error} — which PRs a carried row names is unknown`);
325
+
326
+ // A PR a carried row names is queued by that row already, and a `row` write
327
+ // replaces the whole line, wiping the live tokens carried on it.
328
+ const named = new Set();
329
+ for (const row of ledger.rows) {
330
+ const { keyNum, pr } = rowNums(row);
331
+ if (keyNum !== null) named.add(keyNum);
332
+ if (pr !== null) named.add(pr);
333
+ }
334
+ const queued = [];
335
+ const advice = [];
336
+ let carried = 0;
337
+ for (const pr of [...prs].sort((a, b) => a.number - b.number)) {
338
+ if (named.has(pr.number)) {
339
+ carried += 1;
340
+ continue;
341
+ }
342
+ const issues = (pr.closingIssuesReferences ?? []).map((i) => i.number).filter(Number.isInteger);
343
+ if (issues.length === 0) {
344
+ advice.push(`NEED review PR#${pr.number} (closes no issue)`);
345
+ continue;
346
+ }
347
+ const closes = `closes ${issues.map((n) => `#${n}`).join(", ")}`;
348
+ const w = node("ledger.mjs", ["row", String(pr.number), `PR#${pr.number} · inherited (${closes})`], { cwd });
349
+ if (w.status !== 0) return refusal(`ledger.mjs row ${pr.number} failed:`, w);
350
+ queued.push(`queued PR#${pr.number} for review (${closes})`);
351
+ }
352
+ const head = `${queued.length} PR(s) queued, ${carried} already on a carried row, ${advice.length} closing no issue`;
353
+ return ok([head, ...queued, ...advice].join("\n"));
354
+ }
355
+
356
+ function stranded({ cwd }) {
357
+ const r = node("stranded.mjs", [], { cwd });
358
+ if (r.status !== 0) return refusal("stranded.mjs could not answer:", r);
359
+ let verdict;
360
+ try {
361
+ verdict = JSON.parse(r.stdout);
362
+ } catch (e) {
363
+ return failed(`could not parse stranded.mjs output: ${e.message}`);
364
+ }
365
+ if (!Array.isArray(verdict?.claims) || !Array.isArray(verdict?.carried)) return failed("stranded.mjs printed no {claims, carried}");
366
+ const ledger = ledgerRows(cwd);
367
+ if (ledger.error) return failed(`${ledger.error} — which claims are already resumed is unknown`);
368
+ const rowed = new Set(ledger.rows.map(rowKey));
369
+
370
+ const body = [];
371
+ const needs = [];
372
+ for (const c of verdict.claims) {
373
+ if (c.action !== "resume") body.push(`report #${c.n} — ${c.why}`);
374
+ else if (rowed.has(`#${c.n}`)) body.push(`#${c.n} resumed: its ledger row is there`);
375
+ else needs.push(`NEED resume #${c.n} ${c.worktree} ${c.branch}`);
376
+ }
377
+ for (const t of verdict.carried) body.push(`carried ${t.name} ${t.token} (row ${t.row ?? "none"})`);
378
+ const head = `prior ${verdict.prior}: ${verdict.claims.length} claim(s), ${verdict.carried.length} live token(s) carried`;
379
+ return { status: needs.length > 0 ? "pending" : "ok", output: [head, ...body, ...needs].join("\n") };
380
+ }
381
+
382
+ function shortlist({ cwd }) {
383
+ const r = node("shortlist.mjs", [], { cwd });
384
+ if (r.status !== 0) return refusal("shortlist.mjs refused:", r);
385
+ return ok("shortlist built");
386
+ }
387
+
388
+ const STEPS = {
389
+ "branch": branch, "fast-forward": fastForward, "pin": pin, "baseline": baseline, "preflight": preflight,
390
+ "ruleset": ruleset, "tier-roles": tierRoles, "metrics": metrics, "cockpit": cockpit, "rotate": rotate,
391
+ "reclaim": reclaim, "recipe": recipe, "fold-in": foldIn, "stranded": stranded, "shortlist": shortlist,
392
+ };
393
+
394
+ const STEP_NAMES = Object.keys(STEPS);
395
+
396
+ // ── the receipt ──────────────────────────────────────────────────────────────
397
+
398
+ // Null when there is no receipt; a receipt that is there and cannot be read or
399
+ // is not one throws, naming the file and why.
400
+ function readReceipt(path) {
401
+ let text;
402
+ try {
403
+ text = readFileSync(path, "utf8");
404
+ } catch (e) {
405
+ if (e.code === "ENOENT") return null;
406
+ throw new Error(`cannot read the receipt ${path} (${e.code ?? e.message}) — move it aside and re-run`);
407
+ }
408
+ let r;
409
+ try {
410
+ r = JSON.parse(text);
411
+ } catch (e) {
412
+ throw new Error(`the receipt ${path} is not JSON (${e.message}) — move it aside and re-run`);
413
+ }
414
+ const record = (x) => x !== null && typeof x === "object" && !Array.isArray(x);
415
+ if (!(record(r) && record(r.steps) && Object.hasOwn(r, "run") && typeof r.session === "string")) {
416
+ throw new Error(`the receipt ${path} has no steps, run and session — move it aside and re-run`);
417
+ }
418
+ return r;
419
+ }
420
+
421
+ function writeReceipt(path, receipt) {
422
+ const tmp = `${path}.${process.pid}.tmp`;
423
+ mkdirSync(dirname(path), { recursive: true });
424
+ writeFileSync(tmp, `${JSON.stringify(receipt, null, 2)}\n`);
425
+ renameSync(tmp, path);
426
+ }
427
+
428
+ const capped = (s) => (s.length > OUTPUT_MAX ? `…${s.slice(-(OUTPUT_MAX - 1))}` : s);
429
+
430
+ function main() {
431
+ const die = makeDie(NAME);
432
+ const F = defineFlags(die, {
433
+ flags: {
434
+ session: "value", "implementer-cap": "value", "reviewer-cap": "value", "plugin-checkout": "value",
435
+ "spend-dir": "value", workflow: "value", "declare-no-ci": "bool",
436
+ },
437
+ });
438
+ F.sweep();
439
+ F.stray();
440
+ const absent = (name) => F.arg(name) === null;
441
+ if (absent("session")) die("--session is required: the controller's session directory, `~/.omp/agent/sessions/<encoded-cwd>/<ISO>_<uuid>`");
442
+ const session = resolve(F.arg("session"));
443
+ try {
444
+ if (!statSync(session).isDirectory()) die(`--session ${session} is not a directory`);
445
+ } catch (e) {
446
+ if (e.code === undefined) throw e;
447
+ die(`--session ${session} is not readable (${e.code})`);
448
+ }
449
+ const positive = (name) => {
450
+ const n = F.numArg(name);
451
+ if (n !== null && n < 1) die(`--${name} needs a positive number, got ${n}`);
452
+ return n;
453
+ };
454
+ const caps = { impl: positive("implementer-cap"), review: positive("reviewer-cap") };
455
+ if (F.has("declare-no-ci") && !absent("workflow")) die("--workflow and --declare-no-ci are alternatives, not a pair");
456
+ const ci = F.has("declare-no-ci") ? "CI: declared absent (--declare-no-ci)" : absent("workflow") ? null : `CI: workflow ${F.arg("workflow")} (--workflow)`;
457
+ const pathOf = (name) => (absent(name) ? null : resolve(F.arg(name)));
458
+ const pluginCheckout = pathOf("plugin-checkout");
459
+ const spendDir = pathOf("spend-dir");
460
+
461
+ let fleetDir;
462
+ try {
463
+ fleetDir = fleetFile(null);
464
+ } catch (e) {
465
+ if (!(e instanceof FleetDirUnresolvable)) throw e;
466
+ die(e.message);
467
+ }
468
+ const cwd = dirname(fleetDir);
469
+ const top = run("git", ["rev-parse", "--show-toplevel"], { cwd: process.cwd() });
470
+ if (top.status !== 0 || realpathSync(top.stdout) !== realpathSync(cwd)) {
471
+ die(`run this from the main checkout ${cwd}${top.status === 0 ? `, not ${top.stdout}` : ""}`);
472
+ }
473
+ const root = node("scratch-root.mjs", [], { cwd });
474
+ if (root.status !== 0) {
475
+ process.stderr.write(`${NAME}: scratch-root.mjs ${root.how}\n${root.text}\n`);
476
+ process.exitCode = 3;
477
+ return;
478
+ }
479
+ const scratch = root.stdout;
480
+
481
+ const receiptPath = join(fleetDir, RECEIPT);
482
+ const held = join(fleetDir, HELD);
483
+ const state = readState(stateFileIn(fleetDir), NAME);
484
+ if (state.degraded) {
485
+ // The record decides whether a receipt is the previous run's, and a record
486
+ // that could not be read says nothing about that.
487
+ process.stderr.write(`${NAME}: ${stateFileIn(fleetDir)} ${state.degraded} — repair it so the controller record is intact; a receipt is not set aside on a record that could not be read\n`);
488
+ process.exitCode = 3;
489
+ return;
490
+ }
491
+ const record = state.controller;
492
+ const now = new Date().toISOString();
493
+ let previous;
494
+ try {
495
+ previous = readReceipt(receiptPath);
496
+ } catch (e) {
497
+ // A receipt that is there and cannot be used may record a rotation already
498
+ // done; starting over would run it a second time.
499
+ process.stderr.write(`${NAME}: ${e.message}\n`);
500
+ process.exitCode = 3;
501
+ return;
502
+ }
503
+ // A receipt belongs to a rotated run when the rotation wrote a controller
504
+ // record it can be keyed on, or, with no omp process above the run to write
505
+ // one, when its rotation is recorded `ok`. Either way it is this run's only
506
+ // if the record now holds the `at` it names and the session is the same.
507
+ const rotated = previous !== null && (previous.run !== null || previous.steps.rotate?.status === "ok");
508
+ const resumed = rotated && previous.run === (record?.at ?? null) && previous.session === session;
509
+ if (rotated && !resumed) {
510
+ if (existsSync(held)) {
511
+ process.stderr.write(`${NAME}: cannot hold the previous run's receipt for the rotation: ${held} already holds another\n`);
512
+ process.exitCode = 3;
513
+ return;
514
+ }
515
+ renameSync(receiptPath, held);
516
+ }
517
+
518
+ const receipt = { run: resumed ? previous.run : null, session, scratch, caps, steps: {} };
519
+ for (const name of STEP_NAMES) {
520
+ const was = resumed ? previous.steps[name] : undefined;
521
+ receipt.steps[name] = was?.status === "ok" ? was : { status: "pending", at: now, output: "not run" };
522
+ }
523
+
524
+ const ctx = { cwd, fleetDir, held, receipt, receiptPath, scratch, pluginCheckout, spendDir, ci };
525
+ const say = (line) => process.stdout.write(`${line}\n`);
526
+ let stop = null;
527
+ for (const name of STEP_NAMES) {
528
+ if (receipt.steps[name].status === "ok") {
529
+ say(`phase0: ${name}: ok (done earlier in this run)`);
530
+ continue;
531
+ }
532
+ let result;
533
+ try {
534
+ result = STEPS[name](ctx);
535
+ } catch (e) {
536
+ result = failed(`${name} threw: ${e.message}`);
537
+ }
538
+ receipt.steps[name] = { status: result.status, at: new Date().toISOString(), output: capped(result.output) };
539
+ try {
540
+ writeReceipt(receiptPath, receipt);
541
+ } catch (e) {
542
+ say(`phase0: ${name}: ${result.status}`);
543
+ process.stderr.write(`${NAME}: cannot write ${receiptPath}: ${e.message}\n`);
544
+ process.exitCode = 3;
545
+ return;
546
+ }
547
+ const [head, ...rest] = lines(result.output).filter((l) => !l.startsWith("NEED "));
548
+ say(`phase0: ${name}: ${result.status}${head ? ` — ${head}` : ""}`);
549
+ for (const l of rest) say(` ${l}`);
550
+ if (result.status === "failed" || result.status === "pending") {
551
+ stop = result.status;
552
+ break;
553
+ }
554
+ }
555
+
556
+ for (const name of STEP_NAMES) {
557
+ for (const l of lines(receipt.steps[name].output)) if (l.startsWith("NEED ")) say(l);
558
+ }
559
+ process.exitCode = stop === "failed" ? 3 : stop === "pending" ? 4 : 0;
560
+ }
561
+
562
+ if (isCLI(import.meta.url)) main();