@feigi/fleet-ctl 3.53.1 → 3.54.1

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.53.1",
3
+ "version": "3.54.1",
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();