@feigi/fleet-ctl 3.66.1 → 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.1",
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
 
@@ -90,13 +90,17 @@
90
90
  // writes beside the message it sends, for every live member
91
91
  // token. `<scratch>` is the phase-0 receipt's `scratch`, else
92
92
  // `--scratch`; with neither the check is skipped with one stderr
93
- // line. A file on disk prints one `SETTLE <member>` line naming
94
- // the `ledger.mjs settle <member> --from-report` it is for, and
95
- // one whose `member` is not its filename's prints REPORT-MISMATCH
96
- // instead; one that is there but cannot be read prints
97
- // REPORT-UNREADABLE. Advice, like CHECK-LIVENESS: the tick
98
- // settles nothing. A review runner has no report schema and files
99
- // none, so no `review=` token is looked up.
93
+ // line. A file on disk that validates against its member family's
94
+ // report schema prints one `SETTLE <member>` line naming the
95
+ // `ledger.mjs settle <member> --from-report` it is for. One whose
96
+ // `member` is not its filename's prints REPORT-MISMATCH instead;
97
+ // one that is there but cannot be read prints REPORT-UNREADABLE;
98
+ // one that names its own member and fails its family's schema
99
+ // prints REPORT-INVALID with the first violation, because
100
+ // `settle --from-report` refuses such a file. Advice, like
101
+ // CHECK-LIVENESS: the tick settles nothing. A review runner has no
102
+ // report schema and files none, so no `review=` token is looked
103
+ // up; a member with no schema is never checked against one.
100
104
  // session The listing of the session directory omp writes one
101
105
  // `<member>.jsonl` transcript into per dispatched member: this
102
106
  // run's phase-0 receipt's `session`, else `--session`; with
@@ -1135,18 +1139,22 @@ export function livenessLines({ live, seen, thresholds, now }) {
1135
1139
  }
1136
1140
 
1137
1141
  // The report lines: one per name in `reporters` with a report file on disk, as
1138
- // `{member, settle, line, key}`. `reports` maps a name to what main() read off
1139
- // its file — `{path, since, member}`, `since` the file's mtime in ms and
1140
- // `member` the file's own `member` field, undefined when it has none or is
1141
- // not JSON, or `{path, unreadable}`, `unreadable` the error code of a file
1142
- // that is there and cannot be read — and has no entry for a name with no file.
1143
- // A file that names a member other than the one it is filed under prints
1144
- // REPORT-MISMATCH instead, once, and an unreadable one REPORT-UNREADABLE; for
1145
- // both `settle` is false. `reportsFrom`, when set, is the directory the
1146
- // printed settle reads its file from: ledger.mjs reads the default scratch
1147
- // root's `reports/` unless told otherwise. `key` is the line without its age,
1148
- // what the digest `--fold-unchanged` compares takes, so a report waiting on
1149
- // disk folds rather than moving the digest every minute.
1142
+ // `{member, settle, line, key}`, and `invalid: true` on a REPORT-INVALID one.
1143
+ // `reports` maps a name to what main() read off its file — `{path, since,
1144
+ // member, violation}`, `since` the file's mtime in ms, `member` the file's own
1145
+ // `member` field (undefined when it has none or is not JSON) and `violation`
1146
+ // the first violation of the schema of the name's family (undefined when the
1147
+ // file validates, or when no schema covers the name) — or `{path, unreadable}`,
1148
+ // `unreadable` the error code of a file that is there and cannot be read — and
1149
+ // has no entry for a name with no file. A file that names a member other than
1150
+ // the one it is filed under prints REPORT-MISMATCH instead, once, an
1151
+ // unreadable one REPORT-UNREADABLE, and one that names its member and fails
1152
+ // its schema REPORT-INVALID; for all three `settle` is false. `reportsFrom`,
1153
+ // when set, is the directory the printed settle reads its file from:
1154
+ // ledger.mjs reads the default scratch root's `reports/` unless told
1155
+ // otherwise. `key` is the line without its age, what the digest
1156
+ // `--fold-unchanged` compares takes, so a report waiting on disk folds rather
1157
+ // than moving the digest every minute.
1150
1158
  export function reportLines({ reporters, reports, now, reportsFrom = null }) {
1151
1159
  const out = [];
1152
1160
  const from = reportsFrom === null ? "" : ` --reports ${/^[\w./@%+=:,-]+$/.test(reportsFrom) ? reportsFrom : `'${reportsFrom.replaceAll("'", "'\\''")}'`}`;
@@ -1164,6 +1172,11 @@ export function reportLines({ reporters, reports, now, reportsFrom = null }) {
1164
1172
  out.push({ member, settle: false, line, key: line });
1165
1173
  continue;
1166
1174
  }
1175
+ if (r.violation !== undefined) {
1176
+ const line = `REPORT-INVALID ${r.path} (${r.violation})`;
1177
+ out.push({ member, settle: false, invalid: true, line, key: line });
1178
+ continue;
1179
+ }
1167
1180
  const age = Math.floor(Math.max(0, now - r.since) / 60_000);
1168
1181
  out.push({
1169
1182
  member, settle: true, key: `SETTLE ${member}`,
@@ -1287,7 +1300,7 @@ import { statePath, readState, writeState, assessBeat, isStalled, isReported, st
1287
1300
  import { checkMainCheckout, describe } from "./main-checkout.mjs";
1288
1301
  import { readRunReceipt, phase0Gate, IN_FLIGHT_DEFAULT } from "./phase0-receipt.mjs";
1289
1302
  import { judgeRecord, ProcUnreadable } from "./proc.mjs";
1290
- import { reportPath, reportsDir } from "./report-files.mjs";
1303
+ import { reportFamily, readReport, reportPath, reportsDir } from "./report-files.mjs";
1291
1304
 
1292
1305
  const NAME = "fleet-tick";
1293
1306
  const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url));
@@ -1787,10 +1800,12 @@ function reportsScratch(receipt, flag) {
1787
1800
  }
1788
1801
 
1789
1802
  // The report file of each name in `reporters`, as reportLines() takes them:
1790
- // `{path, since, member}` per file on disk, `{path, unreadable}` for one that
1791
- // cannot be read, nothing for a name with none. Only `member` is read out of a
1792
- // file, and a file that is not JSON carries none.
1793
- function readReports(scratch, reporters) {
1803
+ // `{path, since, member, violation}` per file on disk, `{path, unreadable}` for
1804
+ // one that cannot be read, nothing for a name with none. `member` is the file's
1805
+ // own, and a file that is not JSON carries none. `violation` is report-files's
1806
+ // verdict on a file that is there for a name a schema covers, set only when
1807
+ // that verdict is invalid; a name no schema covers is never looked up.
1808
+ export function readReports(scratch, reporters) {
1794
1809
  const out = new Map();
1795
1810
  for (const member of reporters) {
1796
1811
  const path = reportPath(scratch, member);
@@ -1810,7 +1825,12 @@ function readReports(scratch, reporters) {
1810
1825
  } catch {
1811
1826
  named = undefined;
1812
1827
  }
1813
- out.set(member, { path, since, member: named });
1828
+ const entry = { path, since, member: named };
1829
+ if (reportFamily(member) !== null) {
1830
+ const checked = readReport(scratch, member);
1831
+ if (checked.state === "invalid") entry.violation = checked.violation;
1832
+ }
1833
+ out.set(member, entry);
1814
1834
  }
1815
1835
  return out;
1816
1836
  }
@@ -2027,8 +2047,9 @@ function main() {
2027
2047
  // past its threshold. The digest already moves when its bucket does.
2028
2048
  const aged = stale.map((s) => `; CHECK-LIVENESS ${s.member} persists`).join("");
2029
2049
  // A report waiting on disk persists the same way, for as long as its
2030
- // member stays live.
2031
- const settle = reported.filter((r) => r.settle).map((r) => `; SETTLE ${r.member} persists`).join("");
2050
+ // member stays live: the settle it is for, or REPORT-INVALID where that
2051
+ // settle would be refused.
2052
+ const settle = reported.filter((r) => r.settle || r.invalid).map((r) => `; ${r.settle ? "SETTLE" : "REPORT-INVALID"} ${r.member} persists`).join("");
2032
2053
  // A transcript the ledger lacks, or a live token lacking one, the same
2033
2054
  // way, for as long as it holds.
2034
2055
  const unmatched = transcribed.map((t) => `; ${t.kind} ${t.name} persists`).join("");
@@ -55,8 +55,9 @@ named request should state the original's msg_id and that it is a re-send, which
55
55
  is what distinguishes a lost message from a member that never sent one; a
56
56
  controller that skips the ask cannot tell those apart and will guess wrong in
57
57
  whichever direction its expectations point. The tick prints `SETTLE <member>`
58
- for a report file on disk, so a missing message is read off that line before
59
- anyone is pinged.
58
+ for a report file on disk that passes its schema and `REPORT-INVALID` for one
59
+ that fails it, so a missing message is read off those lines before anyone is
60
+ pinged.
60
61
 
61
62
  Note this cuts against the paragraph above only in appearance: the default stays
62
63
  *send once*, because unprompted re-sends were measured 2-to-1 false. The ask is
@@ -1315,44 +1316,53 @@ unconfirmed. Invoking the command was the opt-in. One exception: **a judgement t
1315
1316
  evidence cannot settle**.
1316
1317
 
1317
1318
  **Rule: record, tick, act, beat.** Every wake — a member report, a review
1318
- notification, a label, a CI run reaching a terminal state, a heartbeat — ends in
1319
- 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
1320
1323
  refill or dispatch edges left. Record first, because the tick reads the run off
1321
1324
  `.fleet/ledger.md` and nothing else of yours: a wake you have not written down is
1322
1325
  one it cannot see, and it names the same dispatch again. Every record goes
1323
- through `ledger.mjs` (**Run ledger**) — `settle` for a member's outcome,
1324
- `review` for a review token on the PR's row, `row` for any other token on a
1325
- 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`.
1326
1328
 
1327
- | 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 |
1328
1332
  |---|---|
1329
- | 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) |
1330
- | 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**) |
1331
- | 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 |
1332
- | 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 |
1333
- | 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) |
1334
- | 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) |
1335
- | Label seen (persistent Monitor) | nothing to record |
1336
- | CI run terminal | `ci=<run-id>:<attempt>:<conclusion>` on the row; then the finisher gate (below) |
1337
- | 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.) |
1338
- | Drain | `ledger.mjs drain "<reason>"`; release the claims (below); `settle impl-<N>=released`; then the rest of **End of run** (below), `--stop` last |
1339
- | Heartbeat | nothing to record |
1340
-
1341
- Then run the tick, act on every line it prints, and arm the beat. What a wake
1342
- 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:
1343
1347
 
1344
1348
  - **Nothing to do right now** → **do not end your turn.** Arm the heartbeat
1345
1349
  below. A turn that ends on a drained queue is #3's stall itself: nothing
1346
1350
  external will wake you, and the level-check you are one command away from
1347
1351
  never runs. Listed first because it is the only wake with no trigger —
1348
1352
  every other row above arrives; this one is the absence of one.
1349
- - **Implementer report** → verify the SHA is reachable on the expected branch,
1350
- 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:
1351
1354
  the tick names it as `DISPATCH review PR#<M>` once a reviewer slot is free,
1352
1355
  and it names the next shortlist head for the slot the implementer left. Pull
1353
1356
  nothing the tick did not name.
1354
- - **Implementer bails before implementing** → settle `impl-<N>=bailed`, then
1355
- 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:
1356
1366
 
1357
1367
  | Cause | Label |
1358
1368
  |---|---|
@@ -1360,60 +1370,45 @@ owes beyond its row:
1360
1370
  | genuine fork — options named, none ruled | `ready-for-human` |
1361
1371
  | needs human hands — external access, manual testing, judgment during the work | `ready-for-human` |
1362
1372
 
1363
- `gh issue edit <N> --remove-label ready-for-agent --remove-label in-progress
1364
- --add-label <label>`, comment the cause, release the worktree and branch with
1365
- `release-ticket.sh` (below — `reap.sh` declines a claim that never became a
1366
- 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.
1367
1375
  `needs-triage` routes back to `/triage`, which can return it as
1368
1376
  `ready-for-agent`; `ready-for-human` for hands or a fork; `needs-triage` for a
1369
1377
  brief that names no *what*.
1370
1378
 
1371
- **Dropping `in-progress` is the load-bearing half** — phase 1 applied it and
1372
- `candidates.mjs` excludes it, so leaving it makes the ticket invisible to your
1373
- scans *and* the maintainer's. It does not loop; it disappears. The same causes
1374
- relabel an unclaimed ticket at the Pull (phase 1), where there is no
1375
- `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
1376
1381
  whichever point the ticket fails them.
1377
1382
  - **A review result lands** → see the result file written (by you or by the
1378
- runner — **Reviewers** says which, per harness) and record `reviewed=` off its
1379
- 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
1380
1385
  `DISPATCH fix-pr PR#<M>`. No survived or unverified finding and nothing to file → skip the
1381
1386
  fix-applier and dispatch the **finisher** directly — or, when that head's
1382
1387
  bound conclusion is red and not solely staleness, the red-check fixer
1383
1388
  instead (**Then dispatch a red-check fixer**, below): no member will touch that
1384
1389
  PR, so no push is coming and nothing will wake you. A review that failed is
1385
1390
  not a result — **Reviewers** says who retries it and what takes over.
1386
- - **Monitor: `ready-to-merge` appears** → nothing to record; run the tick, and
1391
+ - **Monitor: `ready-to-merge` appears** → `fleet-event.mjs label <pr>`, and
1387
1392
  on `DISPATCH merge-bot` dispatch the next `merge-bot-<n>` (**Merge bot**).
1388
1393
  Catches hand-added labels as well as a finisher's own. The bot does not wait
1389
1394
  for that finisher's report: its rebase is server-side,
1390
1395
  `gh pr update-branch --rebase`, so nothing on the finisher's worktree has to
1391
1396
  happen first.
1392
- - **Merge-bot pass reports done** → write each `held-behind-#<lower>` it reports
1393
- into that ticket's row as `held-behind:#<lower>` — the verdict moves no label
1394
- and leaves nothing in the repo, so the row is the only place the tick can read
1395
- it from — settle `merge-bot-<n>=done`, and then run the tick: `tick --apply`
1396
- reaps merged branches and worktrees with `reap.sh --apply` (below), then
1397
- reclaims their scratch with `reclaim-scratch.mjs --root <scratch> --apply`
1398
- (below), once for every merge bot settled `done` — always, even when the pass
1399
- merged nothing — and runs both again on the next tick after an `APPLY FAILED`
1400
- line, and on every tick while this run has no controller record to remember
1401
- 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
1402
1399
  merge-bot` again: dispatch the next bot straight away. A `rebase-fallback-#<pr>`
1403
1400
  on a conflict needs no record from you — the bot already appended
1404
1401
  `conflict-hold:#<pr>` to that PR's row, and the tick turns it into `DISPATCH
1405
1402
  fix-pr PR#<pr>` (**Reviewers**).
1406
- - **The run ends, or the maintainer says drain** → `closeout.mjs begin` first
1407
- (below): it drains and releases every claim that never became a PR. Nothing
1408
- 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
1409
1405
  holds the implementer row at `HOLD (draining)` from then on — for a
1410
1406
  replacement controller too — and keeps the review, fix-applier and merge rows
1411
1407
  firing until the open PRs merge. The drain starts the end of the run; it does
1412
1408
  not end it. **End of run**, in this order:
1413
- 1. `~/.fleet/bin/fleet-run closeout.mjs begin --reason "<reason>"` — drains
1414
- (`ledger.mjs drain`), then releases every claim that never became a PR and
1415
- settles each `impl-<N>=released` (**Release the claims that never became
1416
- 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
1417
1412
  refusal is the finding, so run `worktree-audit.sh` and decide by hand.
1418
1413
  `begin` selects a claim with no PR and a live or `bailed` implementer token
1419
1414
  on every run, so a claim you keep leaves `begin` at exit 4 on every run:
@@ -1429,15 +1424,12 @@ owes beyond its row:
1429
1424
  the ledger marks reviewed with no verdict row: append it with the verdict
1430
1425
  you rule (**Guard: accumulate per PR**) and run `finish` again. A step it
1431
1426
  fails is explained in references/close-out.md. Exit 0 is the run closed.
1432
- - **Monitor: CI run completes** → bind it (`ci-state.mjs --pr <N>`) and **record
1433
- it as `ci=<run-id>:<attempt>:<conclusion>`, not just "CI green"** — in the
1434
- ticket's ledger row, which outlives your context: `ledger.mjs token <key>
1435
- ci=<run-id>:<attempt>:<conclusion>` appends it and keeps every token already on
1436
- the row, where `row` would replace the whole line (above).
1437
- That key cannot be reconstructed once the head is superseded, so a
1438
- controller holding only the colour cannot later tell an edge it has already
1439
- spent from one that never fired, and that is the distinction the sibling
1440
- 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
1441
1433
  conclusion is not stable** (below), because a rerun rewrites the run in
1442
1434
  place. The diff-validating `check` job green with no heavy job (the
1443
1435
  diff-validating suites, not the `rebase-check` currency gate) in `failure`
@@ -1501,7 +1493,7 @@ owes beyond its row:
1501
1493
  repo has no CI configured and no declaration, and stop. Absence never reads as
1502
1494
  pass. See `review-and-fix.md` step 6.
1503
1495
 
1504
- **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:
1505
1497
 
1506
1498
  ```
1507
1499
  ~/.fleet/bin/fleet-run fleet-tick.mjs --apply [--implementer-cap <n>] [--reviewer-cap <n>] [--max-reviews <n>]
@@ -1558,17 +1550,16 @@ depth** guard table applied in code. Act on each line as it reads:
1558
1550
  - `ESCALATE unlabelled PR#<M> …` — a second finisher since the last `label-off=`
1559
1551
  settled `labelled` and the label is still not on: the tick dispatches no
1560
1552
  third. Not actionable; the maintainer's, through the cockpit's `unlabelled`
1561
- flag and the comment the repair finisher's report left (**Finisher report**
1562
- row above).
1553
+ flag and the comment the repair finisher's report left (`fleet-event.mjs`'s
1554
+ `finisher-report` entry).
1563
1555
  - `CONFLICT PR#<M> …` — GitHub reads PR M `mergeable=CONFLICTING`, the ledger
1564
1556
  tracks it, no conflict hold stands on it, no fix-applier, finisher or
1565
1557
  implementer on it is live, and, if it carries `ready-to-merge`, no merge bot
1566
1558
  is live: a queued PR is the bot's while one runs, and its own fallback records
1567
- the hold. Record it with `ledger.mjs token <key> conflict-hold:#<M>`, `<key>`
1568
- the row naming PR M, or M itself: it appends the token and keeps every token
1569
- the row already carries. The row's detail prints the `row` form of that
1570
- write for each PR it names; the `token` form is the one that keeps the row's
1571
- 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
1572
1563
  PR#<M>`, a conflict fix-applier (**A `DISPATCH fix-pr PR#<M>` on a conflict
1573
1564
  hold**), and that row obeys every hold. A review in flight does not stop the
1574
1565
  line: `fix-due` waits for the review to return. It prints under a
@@ -1708,8 +1699,8 @@ exactly the way that gate does:
1708
1699
 
1709
1700
  It blocks, then prints one line. Which line it is, is the whole protocol:
1710
1701
 
1711
- - `… interval elapsed (quiet=<n>) → run fleet-tick` — the level-check is due.
1712
- 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.
1713
1704
  Then arm the beat again.
1714
1705
  - `… Ns of Ms remain → re-issue this command now, do not end your turn` — no
1715
1706
  command blocks for a whole interval (omp backgrounds one at 60s, which is
@@ -1728,7 +1719,7 @@ not a reason to end the run; they are the state a newly triaged ticket arrives
1728
1719
  into. The run ends when you drain it, when the budget goes, or when this
1729
1720
  context does — not because there was briefly nothing to do.
1730
1721
 
1731
- **`--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.
1732
1723
  It prints one line instead of the rows when a tick asks for nothing AND says
1733
1724
  exactly what the last one said, which is what makes an unattended night
1734
1725
  affordable; a tick on any other wake is read by a controller that just acted and
@@ -1920,7 +1911,7 @@ while :; do # one tick
1920
1911
  echo "WATCHER RECOVERED: ci-state reading #$pr again — CI polling resumed"
1921
1912
  keep=; for b in $(printf '%s\n' "$blind"); do [ "$b" = "$pr" ] || keep="$keep $b"; done; blind=$keep ;;
1922
1913
  esac
1923
- : # 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"
1924
1915
  done
1925
1916
  fi
1926
1917
  fi
@@ -2179,8 +2170,9 @@ No replay exists for a review that ran in a runner's own kernel — `resume` is
2179
2170
  `refuted` comes back deliberately as well — a refutation is itself a claim, and
2180
2171
  one has been reversed on new evidence. The fix-applier may reverse one; it
2181
2172
  records each reversal as a `refuted` entry in its disposition record, the
2182
- evidence in `reason`, and you copy those entries to the ledger's `ruled` line
2183
- (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.
2184
2176
 
2185
2177
  **`dimensionsRun` is the dispatch; `dimensionsUnrun` is what names a gap.** A
2186
2178
  specialist that dies contributes zero findings while its key stays in
@@ -2486,8 +2478,8 @@ gated like survivors, and the tick prints `DISPATCH fix-pr PR#<M>` for it: that
2486
2478
  fix-applier's `no-op` and its `ok` verdict are what open the finisher. The
2487
2479
  refusal names its cause. `dispositions
2488
2480
  unchecked` — no verdict answers that review: run `dispositions-check.mjs` for
2489
- the fix-applier that answered the review, as the Fix-applier report edge
2490
- 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 —
2491
2483
  no rule broke, but the check could not read where a deferral was filed, `gh`
2492
2484
  unreachable or an issue unreadable: run the check again for that fix-applier
2493
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