@feigi/fleet-ctl 3.128.3 → 3.129.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.128.3",
3
+ "version": "3.129.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": {
@@ -41,12 +41,22 @@
41
41
  // commit-and-pr `git switch -c <branch>` (`--branch`, default
42
42
  // `chore/run-artifacts-<UTC date>`, suffixed `b`, `c`… while
43
43
  // that name exists locally or on origin), commit exactly the
44
- // three `docs/metrics/*.tsv` files, push `-u`, `gh pr create
45
- // --label patch` with a body naming the reason and the rows
46
- // each file gained and lost, `git switch main`. The branch, and
47
- // the PR once it exists, are kept in the receipt: a re-run
48
- // after a failed push or PR resumes on that branch and never
49
- // opens a second PR.
44
+ // three `docs/metrics/*.tsv` files, `git fetch origin`, `git
45
+ // rebase origin/main`, push `-u` with a lease, `gh pr
46
+ // create --label patch` with a body naming the reason and the
47
+ // rows each file gained and lost, `git switch main`. The
48
+ // rebase is three-way, so rows `main` gained during the run
49
+ // stay; one that conflicts or that git refuses is aborted, the
50
+ // branch is pushed as it was, and the PR is opened all the
51
+ // same, for the merge step to leave open. The lease expects
52
+ // origin's branch at the head the receipt last recorded as
53
+ // pushed, or absent before the first push, so a re-run
54
+ // pushes its rebased branch over the one it pushed before,
55
+ // and over nothing else: a branch someone else pushed to
56
+ // fails the step. The branch, the pushed head
57
+ // (the merge step's pin) and the PR once it exists are kept
58
+ // in the receipt: a re-run after a failed push or PR resumes
59
+ // on that branch and never opens a second PR.
50
60
  // phase0-receipt moves `.fleet/phase0.json` to `.fleet/phase0.previous.json`,
51
61
  // the name `phase0.mjs` holds a previous run's receipt under,
52
62
  // so a run that ended here leaves no phase-0 receipt for the
@@ -56,8 +66,46 @@
56
66
  // before the stop. No `phase0.json` is nothing to move and is
57
67
  // `ok`; a held receipt already there that is not this one is
58
68
  // a failed step.
59
- // heartbeat-stop `fleet-heartbeat.mjs --stop "<reason>"`, last, because
60
- // every reader takes a recorded stop as the end of the run.
69
+ // heartbeat-stop `fleet-heartbeat.mjs --stop "<reason>"`. Every reader takes
70
+ // a recorded stop as the end of the run, and it comes before
71
+ // the merge step because a stopped beat starts no alarm
72
+ // turn: before the stop, every wake ends in a tick, which
73
+ // lists the open Close-out PR as a review to dispatch and
74
+ // holds the run open. A `finish` call omp has moved to the
75
+ // background still delivers its result as a turn of its own.
76
+ // merge merges the Close-out PR the step before opened. A rebase
77
+ // that conflicted or was refused leaves it open at once.
78
+ // Otherwise `inertVerdict()` (finisher-scope.mjs) at the
79
+ // pin; anything but `inert` leaves it open. Then, every 30 s,
80
+ // `gh pr view <n> --json state,headRefOid,mergeStateStatus`
81
+ // and `ci-state.mjs --pr <n> --declare-no-ci`: green CI, the
82
+ // head at the pin and `mergeStateStatus` CLEAN or HAS_HOOKS
83
+ // is one `gh pr merge <n> --merge --match-head-commit <pin>`,
84
+ // then a read that confirms MERGED: `merged PR #<n> at <sha>`.
85
+ // A PR already MERGED is that line too; one CLOSED is
86
+ // `closed: PR #<n>`. A failed check (UNSTABLE included), a
87
+ // head off the pin, BEHIND or DIRTY is `left open: PR #<n> —
88
+ // <reason>`, ok, with nothing armed or retried: the next
89
+ // run's phase 0 folds it in. Every other state keeps the
90
+ // step pending, `NEED merge-wait PR #<n>` over the last state
91
+ // read: CI pending, gh or CI unreadable, green CI with
92
+ // `mergeStateStatus` neither CLEAN nor HAS_HOOKS, or a `gh pr
93
+ // merge` that failed or has not landed. 30 minutes after the
94
+ // step first ran, that state leaves the PR open the same way:
95
+ // `the 30-min bound: <state>`, or `gh unreadable until the
96
+ // bound` / `CI unreadable until the bound`. The step stops
97
+ // waiting within 4 minutes of the `finish` call's start; the
98
+ // steps before it are not held to that. The next call resumes
99
+ // from the receipt without pushing, opening or merging again,
100
+ // and one call asks `gh pr merge` at most once. A receipt
101
+ // whose `mergeStarted` is not a past time, or whose `rebase`
102
+ // is neither null nor a reason, fails the step. The step runs
103
+ // gh and read-only git only, and never moves HEAD, the index
104
+ // or a ref. It never arms auto-merge: GitHub keeps
105
+ // auto-merge armed across pushes by anyone with write
106
+ // access, and every member pushes with the maintainer's
107
+ // credentials. It never passes `--delete-branch`, which also
108
+ // deletes the local branch and switches the checkout.
61
109
  //
62
110
  // `reopen` undoes `begin` for a run that must drain again: refused (exit 2)
63
111
  // once any `finish` step is ok, since the tick and what follows it have already
@@ -68,15 +116,19 @@
68
116
  // THE RECEIPT is `.fleet/closeout.json` (resolved through fleet-dir.mjs, so a
69
117
  // worktree and the main checkout name one file), shared by all three commands:
70
118
  //
71
- // { reason, begun, branch, pr, steps: { <name>: { status, at, output } } }
119
+ // { reason, begun, branch, pr, pin, rebase, mergeStarted, mergeOutcome,
120
+ // steps: { <name>: { status, at, output } } }
72
121
  //
73
122
  // `status` is ok, pending or failed; `at` an ISO time; `output` the step's own
74
123
  // words. Every step name of both commands is always present: one not yet run
75
124
  // is `pending`. `begun` is the time `begin` finished its steps, ok or pending,
76
- // null until then; `branch` and `pr` belong to the commit-and-pr step. A re-run
77
- // skips every `ok` step and runs the rest, stopping at the first that is not
78
- // `ok`, so the steps after it stay `pending`. `ledger.mjs rotate` archives the
79
- // receipt beside the ledger as `closeout.<UTC stamp>.json`.
125
+ // null until then; `branch`, `pr`, `pin` (the head pushed) and `rebase` (null,
126
+ // or why the rebase was aborted) belong to the commit-and-pr step;
127
+ // `mergeStarted` (the merge step's first run, an ISO time) and `mergeOutcome`
128
+ // (its final line) to the merge step. A re-run skips every `ok` step and runs
129
+ // the rest, stopping at the first that is not `ok`, so the steps after it stay
130
+ // `pending`. `ledger.mjs rotate` archives the receipt beside the ledger as
131
+ // `closeout.<UTC stamp>.json`.
80
132
  //
81
133
  // One `closeout: <step>: <status>` line per step on stdout, its output under
82
134
  // it, indented, with the `NEED` lines at the left margin. Exit 0 every step
@@ -95,6 +147,7 @@ import { dirname, join } from "node:path";
95
147
  import { fileURLToPath } from "node:url";
96
148
  import { makeDie, defineFlags } from "./arg.mjs";
97
149
  import { FleetDirUnresolvable, fleetFile } from "./fleet-dir.mjs";
150
+ import { inertVerdict } from "./finisher-scope.mjs";
98
151
  import { gitEnv } from "./git-env.mjs";
99
152
  import { isCLI } from "./is-cli.mjs";
100
153
  import { CLOSEOUT_RECEIPT, RECEIPT, RECEIPT_HELD, memberTokens, rowPr, isOmpSessionDirName } from "./ledger-grammar.mjs";
@@ -148,6 +201,8 @@ function fatal(message) {
148
201
  // ── the receipt ──────────────────────────────────────────────────────────────
149
202
 
150
203
  const blank = () => ({ status: "pending", at: null, output: "" });
204
+ // The receipt's own fields, in the order it is written; each null until set.
205
+ const RECEIPT_FIELDS = ["reason", "begun", "branch", "pr", "pin", "rebase", "mergeStarted", "mergeOutcome"];
151
206
 
152
207
  function readReceipt(path, stepNames) {
153
208
  let prior = null;
@@ -157,7 +212,7 @@ function readReceipt(path, stepNames) {
157
212
  if (e.code !== "ENOENT") fatal(`cannot read receipt ${path}: ${e.message}`);
158
213
  }
159
214
  const steps = Object.fromEntries(stepNames.map((n) => [n, { ...blank(), ...prior?.steps?.[n] }]));
160
- return { reason: prior?.reason ?? null, begun: prior?.begun ?? null, branch: prior?.branch ?? null, pr: prior?.pr ?? null, steps };
215
+ return { ...Object.fromEntries(RECEIPT_FIELDS.map((k) => [k, prior?.[k] ?? null])), steps };
161
216
  }
162
217
 
163
218
  function writeReceipt(path, receipt) {
@@ -303,6 +358,33 @@ function rowCounts(git) {
303
358
  return { lines: r.stdout.split("\n").filter(Boolean).map((l) => l.split("\t")).map(([added, removed, file]) => `- ${file}: +${added} -${removed}`) };
304
359
  }
305
360
 
361
+ // Replays the branch's commit onto the `origin/main` just fetched, three-way,
362
+ // so rows `main` gained during the run stay. A replay that stops on a
363
+ // conflict, or that git refuses to start, is aborted and the branch stays as
364
+ // it was: `{ leftOpen }` names why, and the step goes on to push and open the
365
+ // PR. `{ error }` is a fetch, or an abort, that failed.
366
+ function rebaseOntoMain(git) {
367
+ const fetch = git(["fetch", "origin"], NETWORK_TIMEOUT_MS);
368
+ if (fetch.status !== 0) return { error: `git fetch origin failed: ${detail(fetch)}` };
369
+ const rebase = git(["rebase", "origin/main"]);
370
+ if (rebase.status === 0) return { leftOpen: null };
371
+ const unmerged = git(["diff", "--name-only", "--diff-filter=U"]);
372
+ const stopped = git(["rev-parse", "--verify", "--quiet", "REBASE_HEAD"]);
373
+ if (stopped.status === 0) {
374
+ const abort = git(["rebase", "--abort"]);
375
+ if (abort.status !== 0) return { error: `git rebase origin/main stopped and git rebase --abort failed: ${detail(abort)}` };
376
+ }
377
+ // git's first line, then the paths it lists indented under it, such as the
378
+ // untracked files a replay would overwrite.
379
+ const [said, ...rest] = detail(rebase).split("\n");
380
+ const named = rest.filter((l) => /^\s/.test(l)).map((l) => l.trim());
381
+ const refused = [said, named.join(", ")].filter(Boolean).join(" ");
382
+ if (unmerged.status !== 0) return { leftOpen: `rebase failed: ${refused}; git diff --diff-filter=U failed: ${detail(unmerged)}` };
383
+ const files = unmerged.stdout.split("\n").filter(Boolean);
384
+ if (files.length > 0) return { leftOpen: `rebase conflict: ${files.join(", ")}` };
385
+ return { leftOpen: `rebase refused: ${refused}` };
386
+ }
387
+
306
388
  // Everything the step does while the checkout is on the metrics branch; the
307
389
  // caller switches back to main whatever this returns.
308
390
  function onBranch({ git, cwd, reason, receipt, save }) {
@@ -312,14 +394,25 @@ function onBranch({ git, cwd, reason, receipt, save }) {
312
394
  const commit = git(["commit", "-m", `Closeout: ${reason}`, "--", ...METRICS]);
313
395
  if (commit.status !== 0) return failed(`git commit failed: ${detail(commit)}`);
314
396
  }
397
+ const rebased = rebaseOntoMain(git);
398
+ if (rebased.error) return failed(rebased.error);
315
399
  const ahead = git(["rev-list", "--count", "origin/main..HEAD"]);
316
400
  if (ahead.status !== 0) return failed(`git rev-list --count origin/main..HEAD failed: ${detail(ahead)}`);
317
401
  if (ahead.stdout === "0") return failed(`nothing to commit: ${METRICS.join(", ")} are unchanged`);
402
+ const head = git(["rev-parse", "HEAD"]);
403
+ if (head.status !== 0) return failed(`git rev-parse HEAD failed: ${detail(head)}`);
318
404
 
319
- const push = git(["push", "-u", "origin", receipt.branch], NETWORK_TIMEOUT_MS);
405
+ // The lease is the head this step last pushed, never what the fetch above
406
+ // just read: an empty one expects the branch absent from origin.
407
+ const lease = `--force-with-lease=refs/heads/${receipt.branch}:${receipt.pin ?? ""}`;
408
+ const push = git(["push", "-u", lease, "origin", receipt.branch], NETWORK_TIMEOUT_MS);
320
409
  if (push.status !== 0) return failed(`git push failed: ${detail(push)}`);
410
+ receipt.pin = head.stdout;
411
+ receipt.rebase = rebased.leftOpen;
412
+ save();
413
+ const lines = [`pushed ${receipt.pin}`, ...(rebased.leftOpen === null ? [] : [rebased.leftOpen])];
321
414
 
322
- if (receipt.pr !== null) return ok(`PR ${receipt.pr} already opened for ${receipt.branch}`);
415
+ if (receipt.pr !== null) return ok([...lines, `PR ${receipt.pr} already opened for ${receipt.branch}`].join("\n"));
323
416
  const counts = rowCounts(git);
324
417
  if (counts.error) return failed(counts.error);
325
418
  const body = `Closeout: ${reason}\n\nRows changed:\n${counts.lines.join("\n")}\n`;
@@ -327,13 +420,19 @@ function onBranch({ git, cwd, reason, receipt, save }) {
327
420
  if (pr.status !== 0) return failed(`gh pr create failed: ${detail(pr)}`);
328
421
  receipt.pr = pr.stdout.split("\n").at(-1);
329
422
  save();
330
- return ok(`PR ${receipt.pr} opened on ${receipt.branch}`);
423
+ return ok([...lines, `PR ${receipt.pr} opened on ${receipt.branch}`].join("\n"));
331
424
  }
332
425
 
333
- function stepCommitAndPR({ reason, branch, receipt, save }) {
426
+ // The work tree the command runs in, as `{ cwd }`, or `{ error }`.
427
+ function workTree() {
334
428
  const top = run("git", ["rev-parse", "--show-toplevel"], { cwd: process.cwd() });
335
- if (top.status !== 0) return failed(`not inside a git work tree: ${detail(top)}`);
336
- const cwd = top.stdout;
429
+ return top.status === 0 ? { cwd: top.stdout } : { error: `not inside a git work tree: ${detail(top)}` };
430
+ }
431
+
432
+ function stepCommitAndPR({ reason, branch, receipt, save }) {
433
+ const wt = workTree();
434
+ if (wt.error) return failed(wt.error);
435
+ const { cwd } = wt;
337
436
  const git = (args, timeoutMs) => run("git", args, { cwd, timeoutMs });
338
437
 
339
438
  if (receipt.branch === null) {
@@ -383,6 +482,135 @@ function stepHeartbeatStop({ cwd, reason }) {
383
482
  return r.status === 0 ? ok(r.stdout) : failed(`fleet-heartbeat.mjs --stop failed: ${detail(r)}`);
384
483
  }
385
484
 
485
+ // One read of the PR: `{ state, headRefOid, mergeStateStatus }`, or
486
+ // `{ unreadable }` naming what gh answered instead.
487
+ function readPr(n, cwd, timeoutMs) {
488
+ const r = run("gh", ["pr", "view", n, "--json", "state,headRefOid,mergeStateStatus"], { cwd, env: { GH_REPO: "" }, timeoutMs });
489
+ if (r.status !== 0) return { unreadable: `gh pr view failed: ${detail(r)}` };
490
+ let v = null;
491
+ try {
492
+ v = JSON.parse(r.stdout);
493
+ } catch {
494
+ // Not JSON: named below with what gh printed.
495
+ }
496
+ if (typeof v?.state === "string" && typeof v.headRefOid === "string" && typeof v.mergeStateStatus === "string") return v;
497
+ return { unreadable: `gh pr view answered ${r.stdout || "nothing"}` };
498
+ }
499
+
500
+ // CI as the merge gate reads it, `ci-state.mjs --pr <n> --declare-no-ci`, with
501
+ // the payload and the exit status agreeing. A not-green answer whose run has
502
+ // not completed, or that found no run on the head yet, is still pending; one
503
+ // whose run completed is a failed check.
504
+ function readCi(n, cwd, timeoutMs) {
505
+ const r = node("ci-state.mjs", ["--pr", n, "--declare-no-ci"], { cwd, env: { GH_REPO: "" }, timeoutMs });
506
+ let ci = null;
507
+ try {
508
+ ci = JSON.parse(r.stdout);
509
+ } catch {
510
+ // Not JSON: unreadable below.
511
+ }
512
+ if (ci === null || typeof ci !== "object") return { unreadable: `ci-state.mjs answered nothing readable: ${detail(r)}` };
513
+ if (r.status === 0 && (ci.verdict === "green" || ci.verdict === "no-ci")) return { green: true, prHead: ci.prHead };
514
+ if (r.status === 1 && ci.verdict === "not-green" && Array.isArray(ci.reasons)) {
515
+ const why = ci.reasons.join("; ") || "not green";
516
+ return ci.status === "completed" ? { failed: why } : { pending: why };
517
+ }
518
+ return { unreadable: `ci-state.mjs ${r.how}, verdict ${ci.verdict ?? "absent"}` };
519
+ }
520
+
521
+ // The merge step's clocks: it stops waiting within CALL_MS of the `finish`
522
+ // call's start, reads the PR every POLL_MS, sleeps only while READ_MS is left
523
+ // after the sleep for the reads that follow it, and stops waiting BOUND_MS
524
+ // after its first run. CLOSEOUT_CALL_MS and CLOSEOUT_POLL_MS can only shorten
525
+ // theirs.
526
+ const shorter = (name, ms) => {
527
+ const v = Number(process.env[name]);
528
+ return Number.isInteger(v) && v > 0 && v < ms ? v : ms;
529
+ };
530
+ const CALL_MS = shorter("CLOSEOUT_CALL_MS", 4 * 60_000);
531
+ const POLL_MS = shorter("CLOSEOUT_POLL_MS", 30_000);
532
+ const READ_MS = CALL_MS / 8;
533
+ const BOUND_MS = 30 * 60_000;
534
+ const BOUND = "the 30-min bound";
535
+ const PR_NUMBER = /\/pull\/(\d+)$/;
536
+ const FULL_SHA = /^[0-9a-f]{40}$/;
537
+ const MERGEABLE = new Set(["CLEAN", "HAS_HOOKS"]);
538
+ // Atomics.wait never blocks on a value nothing writes, so it is a plain sleep.
539
+ const IDLE = new Int32Array(new SharedArrayBuffer(4));
540
+
541
+ function stepMerge({ receipt, save, started }) {
542
+ const n = PR_NUMBER.exec(receipt.pr ?? "")?.[1];
543
+ if (n === undefined) return failed(`no PR number in the receipt's pr: ${receipt.pr}`);
544
+ const done = (line) => {
545
+ receipt.mergeOutcome = line;
546
+ save();
547
+ return ok(line);
548
+ };
549
+ const leftOpen = (why) => done(`left open: PR #${n} — ${why}`);
550
+ const merged = (oid) => done(`merged PR #${n} at ${oid}`);
551
+ const { rebase } = receipt;
552
+ if (rebase !== null && (typeof rebase !== "string" || rebase === "")) return failed(`the receipt's rebase is neither null nor a reason: ${JSON.stringify(rebase)}`);
553
+ if (rebase !== null) return leftOpen(rebase);
554
+ if (!FULL_SHA.test(receipt.pin ?? "")) return failed(`no pushed head in the receipt to pin the merge to: ${receipt.pin}`);
555
+ const wt = workTree();
556
+ if (wt.error) return failed(wt.error);
557
+ const { cwd } = wt;
558
+ if (receipt.mergeStarted === null) {
559
+ receipt.mergeStarted = new Date().toISOString();
560
+ save();
561
+ }
562
+ // NaN, from anything but a time string, fails the comparison too.
563
+ const begun = typeof receipt.mergeStarted === "string" ? Date.parse(receipt.mergeStarted) : NaN;
564
+ if (!(begun <= Date.now())) return failed(`the receipt's mergeStarted is not a past time: ${JSON.stringify(receipt.mergeStarted)}`);
565
+
566
+ const v = inertVerdict({ worktree: cwd, pin: receipt.pin });
567
+ if (v.verdict !== "inert") {
568
+ const why = v.reason ?? v.paths.filter((p) => p.class === null).map((p) => `${p.path} (${p.why})`).join(", ");
569
+ return leftOpen(`verdict ${v.verdict}: ${why}`);
570
+ }
571
+
572
+ const bound = begun + BOUND_MS;
573
+ const deadline = started + CALL_MS - CALL_MS / 8;
574
+ const budget = () => Math.min(NETWORK_TIMEOUT_MS, Math.max(1, Math.floor(deadline - Date.now())));
575
+ // `at` is how the bound names the state if it is the last one read.
576
+ const atBound = (last) => leftOpen(`${last.at}: ${last.why}`);
577
+ const NOT_YET = { at: BOUND, why: "gh pr merge answered and the PR is not MERGED yet" };
578
+ let last = { at: BOUND, why: "not read yet" };
579
+ // What the call's one `gh pr merge` answered, kept for every later poll so a
580
+ // failed merge's own words reach the NEED line and the bound.
581
+ let asked = null;
582
+ while (Date.now() < deadline) {
583
+ const pr = readPr(n, cwd, budget());
584
+ if (pr.unreadable) last = { at: "gh unreadable until the bound", why: pr.unreadable };
585
+ else if (pr.state === "MERGED") return merged(pr.headRefOid);
586
+ else if (pr.state === "CLOSED") return done(`closed: PR #${n}`);
587
+ else if (pr.headRefOid !== receipt.pin) return leftOpen(`head moved off the pin ${receipt.pin}: ${pr.headRefOid}`);
588
+ else if (pr.mergeStateStatus === "BEHIND" || pr.mergeStateStatus === "DIRTY") return leftOpen(pr.mergeStateStatus);
589
+ else {
590
+ const ci = readCi(n, cwd, budget());
591
+ if (ci.failed) return leftOpen(`a check failed: ${ci.failed}`);
592
+ if (ci.unreadable) last = { at: "CI unreadable until the bound", why: ci.unreadable };
593
+ else if (ci.pending) last = { at: BOUND, why: `CI pending: ${ci.pending}` };
594
+ else if (ci.prHead !== receipt.pin) return leftOpen(`head moved off the pin ${receipt.pin}: ${ci.prHead}`);
595
+ else if (pr.mergeStateStatus === "UNSTABLE") return leftOpen("a check failed: UNSTABLE");
596
+ else if (!MERGEABLE.has(pr.mergeStateStatus)) last = { at: BOUND, why: `CI green, mergeStateStatus ${pr.mergeStateStatus}` };
597
+ else if (asked !== null) last = asked;
598
+ else {
599
+ const merge = run("gh", ["pr", "merge", n, "--merge", "--match-head-commit", receipt.pin], { cwd, env: { GH_REPO: "" }, timeoutMs: budget() });
600
+ const after = readPr(n, cwd, budget());
601
+ if (after.state === "MERGED") return merged(after.headRefOid);
602
+ asked = merge.status === 0 ? NOT_YET : { at: BOUND, why: `gh pr merge failed: ${detail(merge)}` };
603
+ last = asked;
604
+ }
605
+ }
606
+ if (Date.now() >= bound) return atBound(last);
607
+ if (Date.now() + POLL_MS + READ_MS >= deadline) break;
608
+ Atomics.wait(IDLE, 0, 0, POLL_MS);
609
+ }
610
+ if (Date.now() >= bound) return atBound(last);
611
+ return pending(`NEED merge-wait PR #${n}\n${last.why}`);
612
+ }
613
+
386
614
  // ── the steps, in order ──────────────────────────────────────────────────────
387
615
 
388
616
  const BEGIN = { drain: stepDrain, release: stepRelease };
@@ -394,6 +622,7 @@ const FINISH = {
394
622
  "commit-and-pr": stepCommitAndPR,
395
623
  "phase0-receipt": stepPhase0Receipt,
396
624
  "heartbeat-stop": stepHeartbeatStop,
625
+ merge: stepMerge,
397
626
  };
398
627
  const STEP_NAMES = [...Object.keys(BEGIN), ...Object.keys(FINISH)];
399
628
 
@@ -470,7 +699,7 @@ function main() {
470
699
  const receiptPath = join(fleetDir, CLOSEOUT_RECEIPT);
471
700
  const receipt = readReceipt(receiptPath, STEP_NAMES);
472
701
  receipt.reason = reason;
473
- const ctx = { cwd: process.cwd(), fleetDir, reason, branch };
702
+ const ctx = { cwd: process.cwd(), fleetDir, reason, branch, started: performance.timeOrigin };
474
703
  if (cmd === "reopen") {
475
704
  process.exitCode = reopen(ctx, receipt, receiptPath);
476
705
  } else if (cmd === "begin") {
@@ -24,7 +24,7 @@ These hold in every phase: check each wake against them, and report evidence tha
24
24
  - A grandchild surfaces as its own task-notification; an unrecognized task-id is not a member reporting done.
25
25
  - A reviewer never reviews a PR it implemented.
26
26
  - The merge bot only touches PRs whose implementer reported done; rebasing a worktree someone is working in destroys uncommitted work.
27
- - `ready-to-merge` is added by a reviewer only — never an implementer, never you — but for the run's own artifact PR, which this line does not reach: label and merge that one yourself.
27
+ - `ready-to-merge` is added by a reviewer only — never an implementer, never you.
28
28
  - Every member acts through the maintainer's `gh` credentials, so no write is attributable: when a label moves unexpectedly, ask members directly, rule out automation with `grep -rn '<label>' .github/workflows/`, and do not re-add it.
29
29
  - Phase 1 is serial; everything else may run concurrently.
30
30
 
@@ -193,9 +193,9 @@ owes beyond its call:
193
193
  `ACTION: run over → fleet-heartbeat.mjs --stop "<reason>"`, which it does
194
194
  once the run is draining with no open PR and no live implementer.
195
195
  3. `~/.fleet/bin/fleet-run closeout.mjs finish --reason "<reason>"`, which
196
- then records `fleet-heartbeat.mjs --stop` last, because every reader takes
197
- a recorded stop as the end of the run. A `NEED tier-outcomes append <pr>`
198
- is a reviewed PR with no verdict row — for an implementer's, one that never
196
+ records `fleet-heartbeat.mjs --stop` and then merges the Close-out PR. On `NEED merge-wait PR #<n>`,
197
+ run `finish` again at once. A PR it names `left open` is the next run's: you never label or merge it.
198
+ A `NEED tier-outcomes append <pr>` is a reviewed PR with no verdict row — for an implementer's, one that never
199
199
  reached its finisher: run `append <pr>` (**Guard: accumulate per PR**) and run `finish` again.
200
200
  A PR closing none or several: a NEED if a settled `impl-<N>=PR#<pr>` token
201
201
  names it, else a note. A step it fails is explained in
@@ -20,9 +20,11 @@
20
20
  3. `~/.fleet/bin/fleet-run closeout.mjs finish --reason "<reason>"` — scrapes
21
21
  the run's member facts, checks the tier-outcomes rows, refreshes the
22
22
  metrics, commits the three metrics files and opens their PR, sets the
23
- phase-0 receipt aside as `.fleet/phase0.previous.json`, then records
24
- `fleet-heartbeat.mjs --stop` last, because every reader takes a recorded
25
- stop as the end of the run. A `NEED tier-outcomes append <pr>` is a
23
+ phase-0 receipt aside as `.fleet/phase0.previous.json`, records
24
+ `fleet-heartbeat.mjs --stop`, because every reader takes a recorded stop
25
+ as the end of the run, and then merges the Close-out PR. On `NEED
26
+ merge-wait PR #<n>`, run `finish` again at once. A PR it names `left open`
27
+ is the next run's: you never label or merge it. A `NEED tier-outcomes append <pr>` is a
26
28
  reviewed PR with no verdict row — for an implementer's PR, one that never
27
29
  reached its finisher, since `ledger.mjs dispatch` refuses that finisher
28
30
  until the row exists: run `append <pr>` (**Guard: accumulate per PR**) and run `finish` again. A reviewed
@@ -13,16 +13,6 @@ The invariants SKILL.md states one line each, as they read before they were tigh
13
13
  - The merge bot only touches PRs whose implementer reported done. Rebasing a
14
14
  worktree someone is working in destroys uncommitted work.
15
15
  - `ready-to-merge` is added by a reviewer only — never an implementer, never you.
16
- **The run's own artifact PR is exempt, and it is exempt because this invariant
17
- does not reach it:** what the line forbids is a fleet member signing off its own
18
- ticket work, which presupposes an issue, an implementer, a `review-pr` run and a
19
- finisher, and the metrics PR you author has none of them. Label and
20
- merge that one yourself instead of re-deriving a blocker from this line and
21
- stranding the rows behind it. The exemption belongs to the run that authors the
22
- PR and does not outlive it: one still open when the run ends is a PR a prior run
23
- left open, which phase 0 folds into the next run's review queue as ticket work —
24
- and a PR is not exempt from being wrong, only from waiting on a reviewer
25
- no phase of this run will ever dispatch against it.
26
16
  - **Every member acts through the maintainer's `gh` credentials, so no write is
27
17
  attributable.** Any invariant about *who* did something is unenforceable after
28
18
  the fact: when a label moves unexpectedly, ask members directly, rule out