@feigi/fleet-ctl 3.66.2 → 3.67.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.66.2",
3
+ "version": "3.67.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": {
@@ -1,8 +1,8 @@
1
1
  #!/usr/bin/env node
2
- // A member's report, recorded as one command: the writes its wake owes, then
3
- // the tick.
2
+ // A wake recorded as one command: the writes it owes, then the tick.
4
3
  //
5
4
  // fleet-event.mjs <kind> <args> [--in-flight <n>]
5
+ // fleet-event.mjs drain --reason "<reason>" [--in-flight <n>]
6
6
  //
7
7
  // Reached through the Resolver and run from the main checkout. Every kind
8
8
  // performs its writes, then runs `fleet-tick.mjs --apply` with the In-flight
@@ -18,7 +18,7 @@
18
18
  // settled, under any outcome, is not settled again.
19
19
  //
20
20
  // impl-report <impl-N[-x]>
21
- // `ledger.mjs settle <member> --from-report`. Settled `bailed`: the
21
+ // `ledger.mjs settle <member> --from-report`, which runs `verify-sha.sh` and reads the PR itself. Settled `bailed`: the
22
22
  // report's `bailCause` names the label (undecided `needs-triage`, fork
23
23
  // and hands `ready-for-human`), then:
24
24
  // `gh issue edit <N> --remove-label ready-for-agent --remove-label
@@ -35,6 +35,8 @@
35
35
  // It runs on a second run too: it measures the claim again and
36
36
  // writes nothing when nothing is left to release. A refusal prints
37
37
  // `NEED hand-release #<N> <blocker>` and is never forced.
38
+ // Dropping `in-progress` is the load-bearing half: phase 1 applied it and `candidates.mjs` excludes it, so leaving it makes the ticket invisible to the controller's scans and the maintainer's. It does not loop; it disappears.
39
+ // `reap.sh` declines a claim that never became a PR, so the release of a bailed claim is `release-ticket.sh`'s.
38
40
  // fix-report <fix-pr-M[-x]>
39
41
  // `settle --from-report`, which records the filings and rulings the
40
42
  // report carries. Settled `applied:`/`no-op`, on a PR whose rows carry
@@ -54,11 +56,15 @@
54
56
  // whether or not its settle was accepted, since the settle refuses
55
57
  // exactly that read-back. Either comment is skipped when the PR already
56
58
  // carries it.
59
+ // A settle that refuses on `ready-to-merge` — missing from the PR or from the read-back — is the case the tick's `DISPATCH finisher PR#<M>` catches next: settle it `ledger.mjs settle finisher-pr-<M>=labelled` as reported, and `ledger.mjs filed <N> "<subject>"` for each `unrecorded` entry.
57
60
  // merge-bot-report <merge-bot-n>
58
61
  // `ledger.mjs token <pr> held-behind:#<behind>` for each `held[]` entry
59
62
  // of the report the PR's rows do not already carry, then `settle
60
63
  // --from-report`. The reap and the reclaim run under the tick's
61
64
  // `--apply`.
65
+ // The verdict moves no label and leaves nothing in the repo, so the row is the only place the tick can read a `held-behind` from.
66
+ // The reap and the reclaim run once for every merge bot settled `done`, always, even when the pass merged nothing, and again on the next tick after an `APPLY FAILED` line, and on every tick while this run has no controller record to remember the pass by.
67
+ // The bot may also have written `conflict-hold:#<pr>` onto a held PR's own row earlier in the same pass, before reporting: a token the bot wrote in that pass, never one `reap.sh` writes.
62
68
  // review-result <pr> <path>
63
69
  // The review result file at `<path>`, which must be
64
70
  // `<scratch>/pr<pr>/<run>/<file>`, `<run>` a review run root
@@ -66,24 +72,68 @@
66
72
  // `counts` make `ledger.mjs review <pr>
67
73
  // reviewed=<head>:<survived>/<refuted>/<unverified>:<run>`, skipped when
68
74
  // the PR's rows already carry that token.
75
+ // The result file is `<scratch>/pr<pr>/<run>/review.json`, `<run>` the review's own `run-XXXXXXXX` run root.
69
76
  // review-failed <pr> <launch>
70
77
  // `ledger.mjs review <pr> review=<launch>=failed`, `<launch>` as the
71
78
  // PR's row spells it after `review=` (`member:<runner>` or
72
79
  // `wf:<runId>`), skipped when the rows already carry it; the summary
73
80
  // names the runner the PR's next launch takes, as `review` reports it.
81
+ // ci <pr>
82
+ // `ci-state.mjs --pr <pr>`, never `--quiet`, then `ledger.mjs token <pr>
83
+ // ci=<run-id>:<attempt>:<conclusion>` on the PR's row, `<conclusion>`
84
+ // `-` when ci-state reports it as `""` or null (an in-progress run),
85
+ // skipped when the PR's rows already carry that token. The payload is
86
+ // the verdict, never the exit code: not-green exits 1 and is an
87
+ // ordinary state. A payload with no `verdict`, or `verdict:
88
+ // rate-limited`, prints `WATCHER DEGRADED: no usable ci-state reading
89
+ // for #<pr> — silence is NOT green` and writes nothing; a payload that
90
+ // binds no run (`no-ci`) writes nothing either.
91
+ // `token` appends the key to the PR's row and keeps every token already on it, where `row` would replace the whole line.
92
+ // That key cannot be reconstructed once the head is superseded, so a controller holding only the colour cannot later tell an edge it has already spent from one that never fired.
93
+ // label <pr>
94
+ // No write: a `ready-to-merge` label was seen, and the tick is the whole
95
+ // of the event.
96
+ // conflict <pr>
97
+ // The tick's `CONFLICT` line for the PR, recorded: `ledger.mjs token
98
+ // <pr> conflict-hold:#<pr>`, no note beside it (`token` refuses any
99
+ // `conflict-hold` word that is not `conflict-hold:#<number>`, spelled
100
+ // with `:` or `-`). `token` appends the hold and keeps every token the row already carries, where `row` would replace the whole line.
101
+ // Refused, nothing written, exit 2, when the PR's row already carries a
102
+ // hold no fix-applier has answered (the tick's own reading of the row),
103
+ // or both spellings. A row whose one hold a fix-applier answered takes
104
+ // the other spelling, `conflict-hold-#<pr>`: `token` writes no word the
105
+ // row already carries, and the tick reads a fresh hold after an answer
106
+ // as unresolved.
107
+ // heartbeat
108
+ // No write: the tick runs with `--fold-unchanged`, which prints one line
109
+ // instead of the rows when the tick asks for nothing and says what the
110
+ // last one said. The hold itself stays `fleet-heartbeat.mjs`, whose
111
+ // interval-elapsed line names this command.
112
+ // drain --reason "<reason>"
113
+ // `closeout.mjs begin --reason "<reason>"`, its output printed as it
114
+ // stands, then the tick.
115
+ // `closeout.mjs begin` drains (`ledger.mjs drain`), then releases every claim that never became a PR and settles each `impl-<N>=released`. Nothing else in the loop fires for those claims.
116
+ // `begin` answers a second drain with the standing marker, so a second
117
+ // run releases what is left and writes nothing else. Its exit 4 (a
118
+ // `NEED hand-release #<N> <blocker>` line) is this script's exit 4; its
119
+ // exit 2 or 3 is passed through. The rest of the end of a run,
120
+ // `closeout.mjs finish` last, is the controller's.
74
121
  //
75
122
  // A write this script cannot make, and does not refuse, is printed as a
76
123
  // `NEED <what> …` line, at the left margin, for the controller to make by
77
124
  // hand.
78
125
  //
79
126
  // Exit: 0 every write made and the tick exited 0. 2 a usage error, refused
80
- // before anything is written or ticked: an unknown kind or flag, a member of
127
+ // before anything is written or ticked: an unknown kind or flag, a `--reason`
128
+ // that is empty or beside any kind but `drain`, a member of
81
129
  // the wrong family, a review path outside the PR's partition or a file that
82
130
  // is no review result, a ledger or phase-0 receipt that cannot be read. A
83
131
  // ledger write's own refusal — `settle`'s 3 (the report's claim and the world
84
132
  // disagree) or 2, `token`'s or `review`'s 2 — passes its exit and message
85
- // through, and the tick still runs so the controller sees the rows. Else the
86
- // tick's own exit when it is not 0. Else 4 when a NEED line was printed.
133
+ // through, as does `closeout.mjs begin`'s 2 or 3 and the refusal of a second
134
+ // conflict hold (2), and the tick still runs so the controller sees the rows.
135
+ // Else the tick's own exit when it is not 0. Else 4 when a NEED line was
136
+ // printed, `begin`'s own exit 4 included.
87
137
  //
88
138
  // Zero deps: node builtins and sibling scripts only.
89
139
 
@@ -96,7 +146,7 @@ import { FleetDirUnresolvable, fleetFile } from "./fleet-dir.mjs";
96
146
  import { gitEnv } from "./git-env.mjs";
97
147
  import { isCLI } from "./is-cli.mjs";
98
148
  import { BRIEFS, REVIEW, REVIEWED, memberTokens, nextReviewerName, parseDispatchedEntry, parseMember, parseToken, rowNums } from "./ledger-grammar.mjs";
99
- import { dispositionsToken } from "./fleet-tick.mjs";
149
+ import { dispositionsToken, foldLedger } from "./fleet-tick.mjs";
100
150
  import { readRunReceipt, tickCaps } from "./phase0-receipt.mjs";
101
151
  import { defaultScratch, readReportIn, reportsDir } from "./report-files.mjs";
102
152
 
@@ -113,12 +163,17 @@ const KINDS = {
113
163
  "fix-report": { args: ["<member>"], family: "fix-pr" },
114
164
  "finisher-report": { args: ["<member>"], family: "finisher-pr" },
115
165
  "merge-bot-report": { args: ["<member>"], family: "merge-bot" },
116
- "review-result": { args: ["<pr>", "<path>"] },
117
- "review-failed": { args: ["<pr>", "<launch>"] },
166
+ "review-result": { args: ["<pr>", "<path>"], pr: true },
167
+ "review-failed": { args: ["<pr>", "<launch>"], pr: true },
168
+ ci: { args: ["<pr>"], pr: true },
169
+ label: { args: ["<pr>"], pr: true },
170
+ conflict: { args: ["<pr>"], pr: true },
171
+ heartbeat: { args: [] },
172
+ drain: { args: [], flag: "--reason \"<reason>\"" },
118
173
  };
119
- const FLAGS = { "in-flight": "value" };
174
+ const FLAGS = { "in-flight": "value", reason: "value" };
120
175
  const USAGE = `usage: ${NAME}.mjs <kind> <args> [--in-flight <n>] — kinds: `
121
- + Object.entries(KINDS).map(([k, { args }]) => `${k} ${args.join(" ")}`).join(", ");
176
+ + Object.entries(KINDS).map(([k, { args, flag }]) => [k, ...args, ...(flag ? [flag] : [])].join(" ")).join(", ");
122
177
 
123
178
  // The label each `bailCause` demotes to, and the relabel template's kind.
124
179
  const BAILS = {
@@ -501,6 +556,74 @@ function reviewFailed(ev, pr, launch) {
501
556
  : next === null ? "no free runner name left" : `next free runner ${next}`);
502
557
  }
503
558
 
559
+ // The line the CI watcher prints for a PR whose ci-state reading it cannot use.
560
+ const degraded = (pr) => `WATCHER DEGRADED: no usable ci-state reading for #${pr} — silence is NOT green`;
561
+
562
+ function ci(ev, pr) {
563
+ const r = node("ci-state.mjs", ["--pr", String(pr)]);
564
+ let payload = null;
565
+ try {
566
+ payload = JSON.parse(r.stdout);
567
+ } catch {
568
+ // No payload is a reading that cannot be used, judged below.
569
+ }
570
+ // The payload is the verdict, never the exit: not-green exits 1 and is an
571
+ // ordinary state.
572
+ const verdict = payload?.verdict;
573
+ if (typeof verdict !== "string" || verdict === "" || verdict === "rate-limited") {
574
+ ev.print(degraded(pr));
575
+ ev.note(`#${pr} ci: no usable ci-state reading, nothing written`);
576
+ return;
577
+ }
578
+ const { runId, attempt, conclusion } = payload;
579
+ if (!isDigits(String(runId)) || !isDigits(String(attempt))) {
580
+ ev.note(`#${pr} ci: verdict ${verdict} binds no run, nothing to record`);
581
+ return;
582
+ }
583
+ // `""` is an in-progress run, which `//` would pass through as a conclusion.
584
+ const tok = `ci=${runId}:${attempt}:${conclusion === null || conclusion === undefined || conclusion === "" ? "-" : conclusion}`;
585
+ if (prWords(ev.ledger, pr).includes(tok)) {
586
+ ev.note(`#${pr} already ${tok}`);
587
+ return;
588
+ }
589
+ const w = node("ledger.mjs", ["token", String(pr), tok]);
590
+ if (w.status === 0) ev.note(`#${pr} ${tok}`);
591
+ else ev.refuse(`token #${pr} ${tok}`, w);
592
+ }
593
+
594
+ // A second hold on a row that already answered one is the same word spelled
595
+ // the other way the tick reads, because `token` writes no word a row carries.
596
+ const HOLD_SPELLINGS = (pr) => [`conflict-hold:#${pr}`, `conflict-hold-#${pr}`];
597
+
598
+ function conflict(ev, pr) {
599
+ const open = foldLedger(ev.ledger, new Set(), { lenient: true }).byPr.get(pr)?.conflictOpen === true;
600
+ const words = prWords(ev.ledger, pr);
601
+ const tok = HOLD_SPELLINGS(pr).find((t) => !words.includes(t));
602
+ if (open || tok === undefined) {
603
+ const why = open ? "an unresolved conflict hold" : "every spelling of a conflict hold the tick reads";
604
+ writeAll(2, `${NAME}: conflict: PR #${pr}'s row already carries ${why} — nothing written\n`);
605
+ if (ev.refused === null) ev.refused = 2;
606
+ ev.note(`#${pr} conflict hold refused (row already holds)`);
607
+ return;
608
+ }
609
+ const w = node("ledger.mjs", ["token", String(pr), tok]);
610
+ if (w.status === 0) ev.note(`#${pr} ${tok}`);
611
+ else ev.refuse(`token #${pr} ${tok}`, w);
612
+ }
613
+
614
+ function drain(ev, reason) {
615
+ const r = node("closeout.mjs", ["begin", "--reason", reason]);
616
+ ev.print(r.stdout);
617
+ if (r.status === 0) {
618
+ ev.note("drain begun");
619
+ } else if (r.status === 4) {
620
+ ev.needs += 1;
621
+ ev.note("drain begun, a claim to hand-release");
622
+ } else {
623
+ ev.refuse("closeout begin", r);
624
+ }
625
+ }
626
+
504
627
  // ── main ────────────────────────────────────────────────────────────────────
505
628
 
506
629
  function boundArg(F, name) {
@@ -530,13 +653,19 @@ function main() {
530
653
  const [kind, ...args] = positionals();
531
654
  if (!Object.hasOwn(KINDS, kind ?? "")) die(kind === undefined ? USAGE : `unknown kind '${kind}' — ${USAGE}`);
532
655
  const spec = KINDS[kind];
533
- if (args.length !== spec.args.length) die(`${kind} takes ${spec.args.join(" ")} — ${USAGE}`);
656
+ if (args.length !== spec.args.length) die(`${kind} takes ${spec.args.join(" ") || "no arguments"} — ${USAGE}`);
534
657
  const inFlight = boundArg(F, "in-flight");
658
+ const reason = F.arg("reason");
659
+ if (kind === "drain") {
660
+ if (reason === null) die("drain takes --reason \"<reason>\"");
661
+ } else if (reason !== null) {
662
+ die(`--reason belongs to drain, not ${kind}`);
663
+ }
535
664
  let pr = null;
536
665
  if (spec.family !== undefined) {
537
666
  const m = parseMember(args[0]);
538
667
  if (m === null || m.family !== spec.family) die(`${kind} takes a member of the ${spec.family} family, not '${args[0]}'`);
539
- } else {
668
+ } else if (spec.pr) {
540
669
  const digits = args[0].replace(/^#/, "");
541
670
  if (!isDigits(digits) || Number(digits) < 1) die(`${kind}: '${args[0]}' is not a PR number`);
542
671
  pr = Number(digits);
@@ -555,7 +684,7 @@ function main() {
555
684
  }
556
685
  const caps = tickCaps(fleetDir);
557
686
  if (caps.error) die(`${caps.error} — nothing written`);
558
- const tickArgs = ["--apply", ...(inFlight === null ? caps.args : ["--in-flight", inFlight])];
687
+ const tickArgs = ["--apply", ...(inFlight === null ? caps.args : ["--in-flight", inFlight]), ...(kind === "heartbeat" ? ["--fold-unchanged"] : [])];
559
688
 
560
689
  const ev = new Event({ fleetDir, scratch, ledger: readLedger() });
561
690
  if (kind === "impl-report") implReport(ev, args[0]);
@@ -563,7 +692,10 @@ function main() {
563
692
  else if (kind === "finisher-report") finisherReport(ev, args[0]);
564
693
  else if (kind === "merge-bot-report") mergeBotReport(ev, args[0]);
565
694
  else if (kind === "review-result") reviewResult(ev, pr, args[1]);
566
- else reviewFailed(ev, pr, args[1]);
695
+ else if (kind === "review-failed") reviewFailed(ev, pr, args[1]);
696
+ else if (kind === "ci") ci(ev, pr);
697
+ else if (kind === "conflict") conflict(ev, pr);
698
+ else if (kind === "drain") drain(ev, reason);
567
699
 
568
700
  writeAll(1, `${[...ev.lines, `event: ${kind}: ${ev.summary.join("; ") || "nothing to record"}`].join("\n")}\n`);
569
701
  const tick = spawnSync(process.execPath, [join(SCRIPTS, "fleet-tick.mjs"), ...tickArgs], { stdio: ["ignore", "inherit", "inherit"], env: gitEnv() });
@@ -32,7 +32,7 @@
32
32
  // script never reads or reports fleet state: counts captured before a
33
33
  // twenty-minute hold and printed after it are a stale verdict, and a stale
34
34
  // verdict is how a reconcile prints an ACTION nobody can take. The controller
35
- // runs fleet-tick itself at wake time, which reads the run as it stands then.
35
+ // runs `fleet-event.mjs heartbeat` itself at wake time, which ticks and so reads the run as it stands then.
36
36
  // It also makes a late hold harmless: if a member reports at minute two and
37
37
  // the controller acts, the hold that fires afterwards is a free extra tick.
38
38
  //
@@ -277,7 +277,7 @@ function main() {
277
277
  // on every hold until the file is repaired.
278
278
  const skippedNote = now.degraded ? " — the heartbeat file is degraded and was left as it is, so interval progress is not kept and every hold fires" : "";
279
279
  console.log(done
280
- ? `heartbeat: held ${held}s, ${target}s interval elapsed (quiet=${state.quiet}) → run fleet-tick${skippedNote}`
280
+ ? `heartbeat: held ${held}s, ${target}s interval elapsed (quiet=${state.quiet}) → run fleet-event.mjs heartbeat${skippedNote}`
281
281
  : `heartbeat: held ${held}s, ${target - elapsed}s of ${target}s remain (quiet=${state.quiet}) → re-issue this command now, do not end your turn`);
282
282
  }
283
283
 
@@ -1316,44 +1316,53 @@ unconfirmed. Invoking the command was the opt-in. One exception: **a judgement t
1316
1316
  evidence cannot settle**.
1317
1317
 
1318
1318
  **Rule: record, tick, act, beat.** Every wake — a member report, a review
1319
- notification, a label, a CI run reaching a terminal state, a heartbeat — ends in
1320
- one `fleet-tick.mjs` invocation, and you do what it prints. There are no hand-run
1319
+ notification, a label, a CI run reaching a terminal state, a `CONFLICT` line, a
1320
+ heartbeat, the maintainer's drain — is one `fleet-event.mjs` call, which makes
1321
+ the wake's writes and ends in one `fleet-tick.mjs` invocation, and you do what
1322
+ it prints. There are no hand-run
1321
1323
  refill or dispatch edges left. Record first, because the tick reads the run off
1322
1324
  `.fleet/ledger.md` and nothing else of yours: a wake you have not written down is
1323
1325
  one it cannot see, and it names the same dispatch again. Every record goes
1324
- through `ledger.mjs` (**Run ledger**) — `settle` for a member's outcome,
1325
- `review` for a review token on the PR's row, `row` for any other token on a
1326
- ticket's line — never a hand edit.
1326
+ through `ledger.mjs` (**Run ledger**), which `fleet-event.mjs` drives — never a
1327
+ hand edit. What each kind writes is in the header comment of `fleet-event.mjs`.
1327
1328
 
1328
- | Wake | Record, then tick |
1329
+ Run each as `~/.fleet/bin/fleet-run fleet-event.mjs <kind> <args>`, from the main checkout:
1330
+
1331
+ | Wake | Command |
1329
1332
  |---|---|
1330
- | Implementer report | `ledger.mjs settle impl-<N> --from-report`, which runs `verify-sha.sh` and reads the PR itself (**Run ledger**); on `bailed`, relabel by the cause its receipt names (**Implementer bails before implementing**, below) |
1331
- | Review workflow notification / `review-pr-<n>` report | the result file is `<scratch>/pr<pr>/<run>/review.json`, `<run>` the review's own `run-XXXXXXXX` run root; `ledger.mjs review <pr> reviewed=<head>:<survived>/<refuted>/<unverified>:<run>` on the PR's row (**Reviewers**) |
1332
- | Fix-applier report | `ledger.mjs settle fix-pr-<M> --from-report`, which records each `unrecorded` filing and copies to `ruled` each refutation the report defers; for a fix-applier that answered a review — not one that cleared a conflict hold, which has no review file — `~/.fleet/bin/fleet-run dispositions-check.mjs --member <that member> --scratch <scratch>`, from the checkout root: it judges that member's own record `<scratch>/dispositions-<member>.json` against the review file the PR's latest `reviewed=` names, `<scratch>/pr<M>/<run>/review.json`, writes `dispositions-ok=`, `dispositions-mismatch=`, `dispositions-escalate=` or `dispositions-unchecked=<member>:<run>` onto the PR's row itself, and exits 1 on a mismatch, an escalation or an unchecked, naming each violating or escalated entry's bucket and index, a violation its rule too, and each entry whose filed issue `gh` could not read — **Then dispatch a fix-applier** says what a mismatch asks of you, the gate paragraph below what an escalation or an unchecked does; copy any other refutation it reversed — a `refuted` entry of the record the report does not defer — to `ruled` yourself |
1333
- | Finisher report | `ledger.mjs settle finisher-pr-<M> --from-report`, which records each `unrecorded` filing. Its exit 3 on `ready-to-merge` — missing from the PR or from the read-back — is the case the tick's `DISPATCH finisher PR#<M>` catches next: settle it `ledger.mjs settle finisher-pr-<M>=labelled` as reported, and `ledger.mjs filed <N> "<subject>"` for each `unrecorded` entry. A **repair** finisher's (one sent on that line) read-back lacking it also gets `gh pr comment <M>` with both finishers' read-backs: the one-shot escalation, where halts comment |
1334
- | Finisher report (halted) | `ledger.mjs settle finisher-pr-<M> --from-report`, which records each `unrecorded` filing; `gh pr comment <M>` with the finisher's halt report, cause and evidence; then the per-cause rule (**Resolving a finisher halt**, below) |
1335
- | Finisher report (failed / killed) | `ledger.mjs settle finisher-pr-<M>=failed` for a finisher that crashed or gave up, `=killed` for one that was killed; no label, and the tick prints no dispatch for it. The cockpit flags the PR `finisher:failed` / `finisher:killed` at severity 4 and you resolve it by hand (**Resolving a finisher that died**, below) |
1336
- | Label seen (persistent Monitor) | nothing to record |
1337
- | CI run terminal | `ci=<run-id>:<attempt>:<conclusion>` on the row; then the finisher gate (below) |
1338
- | Merge-bot pass report | `held-behind:#<lower>` rows; `ledger.mjs settle merge-bot-<n> --from-report`; `tick --apply` runs the reap and the reclaim. (The bot may also have written `conflict-hold:#<pr>` onto a held PR's own row earlier in this same pass, before reporting — a token the bot wrote in this pass, never one `reap.sh` writes.) |
1339
- | Drain | `ledger.mjs drain "<reason>"`; release the claims (below); `settle impl-<N>=released`; then the rest of **End of run** (below), `--stop` last |
1340
- | Heartbeat | nothing to record |
1341
-
1342
- Then run the tick, act on every line it prints, and arm the beat. What a wake
1343
- owes beyond its row:
1333
+ | Implementer report | `fleet-event.mjs impl-report impl-<N>` |
1334
+ | Review result file written (workflow notification / `review-pr-<n>` report) | `fleet-event.mjs review-result <pr> <path>` |
1335
+ | Review launch failed | `fleet-event.mjs review-failed <pr> <launch>` |
1336
+ | Fix-applier report | `fleet-event.mjs fix-report fix-pr-<M>` |
1337
+ | Finisher report | `fleet-event.mjs finisher-report finisher-pr-<M>` |
1338
+ | Merge-bot pass report | `fleet-event.mjs merge-bot-report merge-bot-<n>` |
1339
+ | CI run terminal | `fleet-event.mjs ci <pr>` |
1340
+ | Label seen (persistent Monitor) | `fleet-event.mjs label <pr>` |
1341
+ | `CONFLICT` line | `fleet-event.mjs conflict <pr>` |
1342
+ | Heartbeat | `fleet-event.mjs heartbeat` |
1343
+ | Drain | `fleet-event.mjs drain --reason "<reason>"` |
1344
+
1345
+ Act on every line the call prints, the tick's last, and arm the beat. What a wake
1346
+ owes beyond its call:
1344
1347
 
1345
1348
  - **Nothing to do right now** → **do not end your turn.** Arm the heartbeat
1346
1349
  below. A turn that ends on a drained queue is #3's stall itself: nothing
1347
1350
  external will wake you, and the level-check you are one command away from
1348
1351
  never runs. Listed first because it is the only wake with no trigger —
1349
1352
  every other row above arrives; this one is the absence of one.
1350
- - **Implementer report** → verify the SHA is reachable on the expected branch,
1351
- settle the member, then run the tick. The PR is owed a review from here on:
1353
+ - **Implementer report** → the PR is owed a review from here on:
1352
1354
  the tick names it as `DISPATCH review PR#<M>` once a reviewer slot is free,
1353
1355
  and it names the next shortlist head for the slot the implementer left. Pull
1354
1356
  nothing the tick did not name.
1355
- - **Implementer bails before implementing** → settle `impl-<N>=bailed`, then
1356
- demote by cause:
1357
+ - **Finisher reports halted** → the per-cause rule (**Resolving a finisher
1358
+ halt**, below).
1359
+ - **A finisher failed or was killed** → `ledger.mjs settle finisher-pr-<M>=failed` for a
1360
+ finisher that crashed or gave up, `=killed` for one that was killed; no label,
1361
+ and the tick prints no dispatch for it. The cockpit flags the PR
1362
+ `finisher:failed` / `finisher:killed` at severity 4 and you resolve it by hand
1363
+ (**Resolving a finisher that died**, below), then run the tick.
1364
+ - **Implementer bails before implementing** → `fleet-event.mjs impl-report impl-<N>`
1365
+ settles `impl-<N>=bailed` and demotes by cause:
1357
1366
 
1358
1367
  | Cause | Label |
1359
1368
  |---|---|
@@ -1361,60 +1370,45 @@ owes beyond its row:
1361
1370
  | genuine fork — options named, none ruled | `ready-for-human` |
1362
1371
  | needs human hands — external access, manual testing, judgment during the work | `ready-for-human` |
1363
1372
 
1364
- `gh issue edit <N> --remove-label ready-for-agent --remove-label in-progress
1365
- --add-label <label>`, comment the cause, release the worktree and branch with
1366
- `release-ticket.sh` (below — `reap.sh` declines a claim that never became a
1367
- PR), then run the tick: the head it names next is a *different* ticket.
1373
+ The call relabels, comments the cause and releases the claim, then ticks:
1374
+ the head the tick names next is a *different* ticket.
1368
1375
  `needs-triage` routes back to `/triage`, which can return it as
1369
1376
  `ready-for-agent`; `ready-for-human` for hands or a fork; `needs-triage` for a
1370
1377
  brief that names no *what*.
1371
1378
 
1372
- **Dropping `in-progress` is the load-bearing half** — phase 1 applied it and
1373
- `candidates.mjs` excludes it, so leaving it makes the ticket invisible to your
1374
- scans *and* the maintainer's. It does not loop; it disappears. The same causes
1375
- relabel an unclaimed ticket at the Pull (phase 1), where there is no
1376
- `in-progress` to drop — the causes and labels are one table, applied at
1379
+ The same causes relabel an unclaimed ticket at the Pull (phase 1), where there
1380
+ is no `in-progress` to drop — the causes and labels are one table, applied at
1377
1381
  whichever point the ticket fails them.
1378
1382
  - **A review result lands** → see the result file written (by you or by the
1379
- runner — **Reviewers** says which, per harness) and record `reviewed=` off its
1380
- digest with `ledger.mjs review <M>`, then run the tick: a PR with survived or unverified findings prints as
1383
+ runner — **Reviewers** says which, per harness), then
1384
+ `fleet-event.mjs review-result <pr> <path>`: a PR with survived or unverified findings prints as
1381
1385
  `DISPATCH fix-pr PR#<M>`. No survived or unverified finding and nothing to file → skip the
1382
1386
  fix-applier and dispatch the **finisher** directly — or, when that head's
1383
1387
  bound conclusion is red and not solely staleness, the red-check fixer
1384
1388
  instead (**Then dispatch a red-check fixer**, below): no member will touch that
1385
1389
  PR, so no push is coming and nothing will wake you. A review that failed is
1386
1390
  not a result — **Reviewers** says who retries it and what takes over.
1387
- - **Monitor: `ready-to-merge` appears** → nothing to record; run the tick, and
1391
+ - **Monitor: `ready-to-merge` appears** → `fleet-event.mjs label <pr>`, and
1388
1392
  on `DISPATCH merge-bot` dispatch the next `merge-bot-<n>` (**Merge bot**).
1389
1393
  Catches hand-added labels as well as a finisher's own. The bot does not wait
1390
1394
  for that finisher's report: its rebase is server-side,
1391
1395
  `gh pr update-branch --rebase`, so nothing on the finisher's worktree has to
1392
1396
  happen first.
1393
- - **Merge-bot pass reports done** → write each `held-behind-#<lower>` it reports
1394
- into that ticket's row as `held-behind:#<lower>` — the verdict moves no label
1395
- and leaves nothing in the repo, so the row is the only place the tick can read
1396
- it from — settle `merge-bot-<n>=done`, and then run the tick: `tick --apply`
1397
- reaps merged branches and worktrees with `reap.sh --apply` (below), then
1398
- reclaims their scratch with `reclaim-scratch.mjs --root <scratch> --apply`
1399
- (below), once for every merge bot settled `done` — always, even when the pass
1400
- merged nothing — and runs both again on the next tick after an `APPLY FAILED`
1401
- line, and on every tick while this run has no controller record to remember
1402
- the pass by. A label that landed at the last moment reads `DISPATCH
1397
+ - **Merge-bot pass reports done** → `fleet-event.mjs merge-bot-report merge-bot-<n>`. A label that
1398
+ landed at the last moment reads `DISPATCH
1403
1399
  merge-bot` again: dispatch the next bot straight away. A `rebase-fallback-#<pr>`
1404
1400
  on a conflict needs no record from you — the bot already appended
1405
1401
  `conflict-hold:#<pr>` to that PR's row, and the tick turns it into `DISPATCH
1406
1402
  fix-pr PR#<pr>` (**Reviewers**).
1407
- - **The run ends, or the maintainer says drain** → `closeout.mjs begin` first
1408
- (below): it drains and releases every claim that never became a PR. Nothing
1409
- else in the loop fires for those claims. The marker is on disk, so the tick
1403
+ - **The run ends, or the maintainer says drain** → `fleet-event.mjs drain --reason "<reason>"`
1404
+ first (below). The marker is on disk, so the tick
1410
1405
  holds the implementer row at `HOLD (draining)` from then on — for a
1411
1406
  replacement controller too — and keeps the review, fix-applier and merge rows
1412
1407
  firing until the open PRs merge. The drain starts the end of the run; it does
1413
1408
  not end it. **End of run**, in this order:
1414
- 1. `~/.fleet/bin/fleet-run closeout.mjs begin --reason "<reason>"` — drains
1415
- (`ledger.mjs drain`), then releases every claim that never became a PR and
1416
- settles each `impl-<N>=released` (**Release the claims that never became
1417
- PRs**). A claim it refuses prints `NEED hand-release #<N> <blocker>`: that
1409
+ 1. `~/.fleet/bin/fleet-run fleet-event.mjs drain --reason "<reason>"` — runs
1410
+ `closeout.mjs begin --reason "<reason>"` (**Release the claims that never became
1411
+ PRs**), then the tick. A claim it refuses prints `NEED hand-release #<N> <blocker>`: that
1418
1412
  refusal is the finding, so run `worktree-audit.sh` and decide by hand.
1419
1413
  `begin` selects a claim with no PR and a live or `bailed` implementer token
1420
1414
  on every run, so a claim you keep leaves `begin` at exit 4 on every run:
@@ -1430,15 +1424,12 @@ owes beyond its row:
1430
1424
  the ledger marks reviewed with no verdict row: append it with the verdict
1431
1425
  you rule (**Guard: accumulate per PR**) and run `finish` again. A step it
1432
1426
  fails is explained in references/close-out.md. Exit 0 is the run closed.
1433
- - **Monitor: CI run completes** → bind it (`ci-state.mjs --pr <N>`) and **record
1434
- it as `ci=<run-id>:<attempt>:<conclusion>`, not just "CI green"** — in the
1435
- ticket's ledger row, which outlives your context: `ledger.mjs token <key>
1436
- ci=<run-id>:<attempt>:<conclusion>` appends it and keeps every token already on
1437
- the row, where `row` would replace the whole line (above).
1438
- That key cannot be reconstructed once the head is superseded, so a
1439
- controller holding only the colour cannot later tell an edge it has already
1440
- spent from one that never fired, and that is the distinction the sibling
1441
- bullet below turns on. The whole key, never the conclusion alone: **a
1427
+ - **Monitor: CI run completes** → `fleet-event.mjs ci <pr>`, which binds the run
1428
+ (`ci-state.mjs --pr <N>`) and **records it as
1429
+ `ci=<run-id>:<attempt>:<conclusion>`, not just "CI green"** — in the
1430
+ ticket's ledger row, which outlives your context. The key is what the sibling
1431
+ bullet below turns on: it tells an edge already spent from one that never
1432
+ fired. The whole key, never the conclusion alone: **a
1442
1433
  conclusion is not stable** (below), because a rerun rewrites the run in
1443
1434
  place. The diff-validating `check` job green with no heavy job (the
1444
1435
  diff-validating suites, not the `rebase-check` currency gate) in `failure`
@@ -1502,7 +1493,7 @@ owes beyond its row:
1502
1493
  repo has no CI configured and no declaration, and stop. Absence never reads as
1503
1494
  pass. See `review-and-fix.md` step 6.
1504
1495
 
1505
- **Every wake ends in the tick.** One invocation, and you act on what it prints:
1496
+ **In one line, every wake is one `fleet-event.mjs` call, which ends in the tick.** One tick invocation, and you act on what it prints:
1506
1497
 
1507
1498
  ```
1508
1499
  ~/.fleet/bin/fleet-run fleet-tick.mjs --apply [--implementer-cap <n>] [--reviewer-cap <n>] [--max-reviews <n>]
@@ -1559,17 +1550,16 @@ depth** guard table applied in code. Act on each line as it reads:
1559
1550
  - `ESCALATE unlabelled PR#<M> …` — a second finisher since the last `label-off=`
1560
1551
  settled `labelled` and the label is still not on: the tick dispatches no
1561
1552
  third. Not actionable; the maintainer's, through the cockpit's `unlabelled`
1562
- flag and the comment the repair finisher's report left (**Finisher report**
1563
- row above).
1553
+ flag and the comment the repair finisher's report left (`fleet-event.mjs`'s
1554
+ `finisher-report` entry).
1564
1555
  - `CONFLICT PR#<M> …` — GitHub reads PR M `mergeable=CONFLICTING`, the ledger
1565
1556
  tracks it, no conflict hold stands on it, no fix-applier, finisher or
1566
1557
  implementer on it is live, and, if it carries `ready-to-merge`, no merge bot
1567
1558
  is live: a queued PR is the bot's while one runs, and its own fallback records
1568
- the hold. Record it with `ledger.mjs token <key> conflict-hold:#<M>`, `<key>`
1569
- the row naming PR M, or M itself: it appends the token and keeps every token
1570
- the row already carries. The row's detail prints the `row` form of that
1571
- write for each PR it names; the `token` form is the one that keeps the row's
1572
- tokens. Then run the tick: the hold reads as `DISPATCH fix-pr
1559
+ the hold. Record it with `fleet-event.mjs conflict <M>`, not with the `ledger.mjs
1560
+ row` form the row's detail prints: `row` replaces the whole line. The call
1561
+ refuses a PR whose row already carries a hold no fix-applier has answered.
1562
+ The tick then reads the hold as `DISPATCH fix-pr
1573
1563
  PR#<M>`, a conflict fix-applier (**A `DISPATCH fix-pr PR#<M>` on a conflict
1574
1564
  hold**), and that row obeys every hold. A review in flight does not stop the
1575
1565
  line: `fix-due` waits for the review to return. It prints under a
@@ -1709,8 +1699,8 @@ exactly the way that gate does:
1709
1699
 
1710
1700
  It blocks, then prints one line. Which line it is, is the whole protocol:
1711
1701
 
1712
- - `… interval elapsed (quiet=<n>) → run fleet-tick` — the level-check is due.
1713
- Run the tick above **with `--fold-unchanged`** and act on what it prints.
1702
+ - `… interval elapsed (quiet=<n>) → run fleet-event.mjs heartbeat` — the level-check
1703
+ is due. Run that command and act on what the tick it ends in prints.
1714
1704
  Then arm the beat again.
1715
1705
  - `… Ns of Ms remain → re-issue this command now, do not end your turn` — no
1716
1706
  command blocks for a whole interval (omp backgrounds one at 60s, which is
@@ -1729,7 +1719,7 @@ not a reason to end the run; they are the state a newly triaged ticket arrives
1729
1719
  into. The run ends when you drain it, when the budget goes, or when this
1730
1720
  context does — not because there was briefly nothing to do.
1731
1721
 
1732
- **`--fold-unchanged` belongs to the heartbeat alone**, never to any other wake.
1722
+ **`--fold-unchanged` belongs to the heartbeat alone** — `fleet-event.mjs heartbeat` passes it, no other kind does.
1733
1723
  It prints one line instead of the rows when a tick asks for nothing AND says
1734
1724
  exactly what the last one said, which is what makes an unattended night
1735
1725
  affordable; a tick on any other wake is read by a controller that just acted and
@@ -1921,7 +1911,7 @@ while :; do # one tick
1921
1911
  echo "WATCHER RECOVERED: ci-state reading #$pr again — CI polling resumed"
1922
1912
  keep=; for b in $(printf '%s\n' "$blind"); do [ "$b" = "$pr" ] || keep="$keep $b"; done; blind=$keep ;;
1923
1913
  esac
1924
- : # your normal handling of $st for this PR
1914
+ : # your normal handling of $st for this PR; a run at a terminal state is the CI wake: fleet-event.mjs ci "$pr"
1925
1915
  done
1926
1916
  fi
1927
1917
  fi
@@ -2180,8 +2170,9 @@ No replay exists for a review that ran in a runner's own kernel — `resume` is
2180
2170
  `refuted` comes back deliberately as well — a refutation is itself a claim, and
2181
2171
  one has been reversed on new evidence. The fix-applier may reverse one; it
2182
2172
  records each reversal as a `refuted` entry in its disposition record, the
2183
- evidence in `reason`, and you copy those entries to the ledger's `ruled` line
2184
- (the Fix-applier report edge).
2173
+ evidence in `reason`, and you copy those entries to the ledger's `ruled` line by
2174
+ running `fleet-event.mjs fix-report`, whose `settle --from-report` records each
2175
+ refutation the report defers.
2185
2176
 
2186
2177
  **`dimensionsRun` is the dispatch; `dimensionsUnrun` is what names a gap.** A
2187
2178
  specialist that dies contributes zero findings while its key stays in
@@ -2487,8 +2478,8 @@ gated like survivors, and the tick prints `DISPATCH fix-pr PR#<M>` for it: that
2487
2478
  fix-applier's `no-op` and its `ok` verdict are what open the finisher. The
2488
2479
  refusal names its cause. `dispositions
2489
2480
  unchecked` — no verdict answers that review: run `dispositions-check.mjs` for
2490
- the fix-applier that answered the review, as the Fix-applier report edge
2491
- states, then dispatch again. It names a `dispositions-unchecked=` verdict too —
2481
+ the fix-applier that answered the review, as `fleet-event.mjs`'s `fix-report`
2482
+ entry states, then dispatch again. It names a `dispositions-unchecked=` verdict too —
2492
2483
  no rule broke, but the check could not read where a deferral was filed, `gh`
2493
2484
  unreachable or an issue unreadable: run the check again for that fix-applier
2494
2485
  once `gh` answers (an issue that does not exist is unreadable too, and no re-run
@@ -358,7 +358,7 @@ token, row}]}`:
358
358
  names. Reconcile them before shortlisting: read `proc://` once, find
359
359
  each `name` among this session's jobs, and act on its state.
360
360
  `running` → keep the token. `completed` or `failed` → record its
361
- result from `agent://<id>` as the **Record, then tick** table records
361
+ result from `agent://<id>` as the wake table of **Rule: record, tick, act, beat** records
362
362
  that member's report; an output you cannot read is a death the
363
363
  Member-killed row confirms. `cancelled` → record it dead. Absent, or a
364
364
  state you cannot read → keep the token live and let the Member-killed