@feigi/fleet-ctl 3.83.2 → 3.85.0

package/agents/fleet-merge-bot.agent.md

@@ -15,7 +15,9 @@ Your scratch directory is `<scratch>/`; you write only under
 `<scratch>/pr<N>/merge-bot-<n>/`.
 
 Your report is the one file you write outside it: `<scratch>/reports/merge-bot-<n>.json`,
-the path your brief names, holding every PR you merged in `merged`. Your final
+the path your brief names, giving every PR queued when you were dispatched
+exactly one verdict — `merged`, `held`, `conflictHold` or `refused` — as
+run-merge-bot.md's **One verdict per queued PR** says. Your final
 message is the one line your brief gives, `merge-bot-<n>: done <path>`.
 
 The shell traps below are copied from the controller's skill, `run-team`. In

package/commands/run-merge-bot.md

@@ -283,6 +283,7 @@ Measured over one three-merge pass: the next queue member went 0 → 2 → 7 →
 **A PR whose heavy jobs have only ever `skipped` is getting its first real verification from your rebase.** Reviewers may legitimately have labelled on the checks that did run plus local evidence, saying so explicitly. When your post-rebase run finally executes those suites, treat a red there as a **genuine first result**, not a regression you caused — read the failing job before concluding, and do not hand it back as "the rebase broke it".
 
 Report merged / skipped-unlabeled / held-behind-#X / worktree-diverged-#X / head-moved-after-label-#X / rebase-carry-#X (merged or not, with the labelled and accepted SHAs) / main-gain-removed:<path>-#X / label-drop-failed-#X / label-read-failed-#X / branch-delete-failed-#X / branch-kept-#X (X the open PR that keeps the merged branch — a keep, not a failure) / rebase-fallback-#X / instrument-set-changed-#X / ci-wait-timeout-#X (with the run id and its `status`) / `<reason>-#X` for any other gate refusal / blocked after the pass — a dispatched bot once, at exit, after its grace (**Grace, then one report**, below). Every acknowledged main-gain removal the gate passed is named in the report, with its reason.
+In the report file, every PR queued when you were dispatched is listed under exactly one of `merged`, `held`, `conflictHold` or `refused` — those four lists are its verdict, the tokens above are not — and a settle check refuses a report that leaves one out (**One verdict per queued PR**, under **Grace, then one report**).
 
 ## No-undo audit (before every rebase)
 
@@ -324,6 +325,8 @@ The wait:
 
 **One report, at exit, and none before it** — every PR this pass touched, in the vocabulary above, a pass that merged nothing included. The controller reaps on that report and records each `held-behind-#<lower>` on the held ticket's row, so a report sent mid-pass is one it acts on too early.
 
+**One verdict per queued PR, in the report file.** A dispatched bot's report file (`<scratch>/reports/merge-bot-<n>.json`) gives every PR that carried `ready-to-merge` when you were dispatched exactly one verdict — the last it reached in the pass: `merged`, `held` (a `held-behind-#<lower>`), `conflictHold` (a `conflict-held-#<pr>`, or a `rebase-fallback-#<pr>` you recorded as a conflict hold), or `refused` with the token above as its `reason` (`main-gain-removed:<path>`, `head-moved-after-label`, `ci-wait-timeout`, any other gate refusal). A PR you never reached is still `refused`, with the reason you stopped short of it; a PR refused `behind:<n>` and merged later in the same pass is only `merged`. `branchKept` is not a verdict. Two checks enforce this, not the rule alone: `report-schema.mjs validate merge-bot` answers `invalid` for a PR named twice, in one list or in two, and for a `refused` entry whose `reason` is empty or only whitespace; and `ledger.mjs settle merge-bot-<n> --from-report`, which `fleet-event.mjs merge-bot-report` runs, judges the report against the queue `ledger.mjs dispatch merge-bot` recorded on your `## Dispatched` entry — never a list your report supplies — and refuses it, naming each PR, when a PR from that queue that is still open and carries `ready-to-merge` has no verdict. A PR labelled after your dispatch, or one that left the queue before the settle, never fails it. Each `refused` entry lands in the ledger's `## Ruled` as `merge-bot-<n> refused #<pr>: <reason>`, the reason trimmed, a record only: it moves no label and holds nothing.
+
 Your `task` result is the report, delivered when you exit.
 
 ## Then stay armed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feigi/fleet-ctl",
-  "version": "3.83.2",
+  "version": "3.85.0",
   "description": "Agent fleet: run-team controller, merge bot, PR reviewer, and the ticket pipeline they share",
   "license": "Apache-2.0",
   "repository": {
@@ -19,7 +19,8 @@
   ],
   "omp": {
     "extensions": [
-      "scripts/member-write-guard.mjs"
+      "scripts/member-write-guard.mjs",
+      "scripts/controller-alarm.mjs"
     ]
   }
 }

package/scripts/controller-alarm.mjs

@@ -0,0 +1,138 @@
+// The run-team controller's alarm. An omp extension: `plugin/package.json#omp.extensions`
+// names this file beside `member-write-guard.mjs`, and a native install loads it
+// into every omp session on the box — the controller's, every member's, and
+// every unrelated session's — so it is inert unless its gate passes and it
+// never throws.
+//
+// WHAT IT DOES. Nothing outside the omp process can start a turn in an idle
+// session, and a controller that has ended its turn is idle. From inside the
+// process `ctx.setInterval` plus `pi.sendUserMessage` can: every 30 s this
+// checks whether the controller's beat has fallen due and, when it has, sends
+// the one line that tells the controller to run the level-check
+// (`fleet-event.mjs heartbeat`). The line is an ordinary user turn, told apart
+// from a typed message by its `[fleet-alarm]` marker.
+//
+// THE GATE, `alarmDue()` — pure, no I/O, no clock read. All of these hold:
+//   - the session is idle;
+//   - `ctx.agent.kind` is `main`: a subagent's session never alarms;
+//   - `.fleet/heartbeat.json`'s `controller.pid` is this process's pid, so two
+//     omp sessions in one checkout alarm only the one the ledger recorded, and
+//     a session in an unrelated repository alarms nothing;
+//   - a `beat` is recorded and its `stopped` is empty: a stopped beat is a run
+//     that ended on purpose, and `""` — what every ordinary beat carries — is
+//     as empty as `null`;
+//   - `now >= beat.at + beat.interval * 1000`;
+//   - this beat has not already been alarmed within the last interval. A
+//     controller that never re-marks is alarmed again once per interval, not
+//     once per poll.
+// A poll that cannot read or judge the file is "not due", and writes nothing
+// to stderr on any poll: `readState` is handed a sink that drops its warnings,
+// because the default would repeat the same line in the TUI every 30 s.
+//
+// IT NEVER ASKS TO QUEUE. The message goes out only when the session is idle at
+// the check, with no `deliverAs`. A queued follow-up is lost when the
+// maintainer presses Esc, and a steer backgrounds the controller's running bash
+// call. A busy controller is skipped until the next poll, and nothing is held
+// for it. omp's `sendUserMessage` still awaits before it dispatches, and a turn
+// that starts in that gap takes the line as a steer: idle at the check narrows
+// that window and does not close it.
+//
+// IT ONLY READS `beat`. `fleet-heartbeat.mjs` is the one writer of the mark and
+// the one place the back-off is computed; this file never marks, never stops
+// and never writes `.fleet/`. It does not suppress itself while the maintainer
+// is typing: a draft in the editor survives the turn it starts.
+//
+// THE PROOF IT IS ARMED. At `session_start`, for the main session only, and
+// only AFTER the timer is set, it writes `~/.fleet/alarm/<pid>.json` holding
+// `{ pid, lstart, fleet }`: this process's pid, its start time as `proc.mjs`
+// reads it, and the `.fleet/` path it resolved. The file is for run-team's
+// phase 0 to check, and nothing reads it yet: this file only writes it. A
+// session that set no timer writes no file, so the file proves the timer is
+// armed against that repository's `.fleet/` and not only that the extension
+// loaded. A start time that cannot be read writes no file, the safe direction:
+// a missing file can only read as a timer not armed. The `.fleet/` path is
+// resolved once, from `ctx.cwd`; outside a git repository, or where git fails
+// or times out, no timer is set and no file is written. A leftover file from a
+// dead session is harmless — its start time never matches a live process.
+//
+// Zero deps: node builtins and sibling scripts only.
+
+import { mkdirSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { fleetFile, FleetDirUnresolvable } from "./fleet-dir.mjs";
+import { readState, stateFileIn } from "./fleet-state.mjs";
+import { processSource } from "./proc.mjs";
+
+export const POLL_MS = 30_000;
+export const ALARM_LINE = "[fleet-alarm] run ~/.fleet/bin/fleet-run fleet-event.mjs heartbeat";
+
+/**
+ * Whether the alarm fires now. `beat` is `{ at, interval, stopped }` (`at` in
+ * ms, `interval` in seconds) or null; `controller` is `{ pid }` or null;
+ * `firedFor` is null or `{ at, firedAt }`, the beat the last fire answered and
+ * when.
+ */
+export function alarmDue({ kind, pid, controller, beat, idle, now, firedFor }) {
+  if (idle !== true) return false;
+  if (kind !== "main") return false;
+  if (pid == null || controller?.pid !== pid) return false;
+  if (!beat || beat.stopped) return false;
+  const intervalMs = beat.interval * 1000;
+  if (!(now >= beat.at + intervalMs)) return false;
+  if (firedFor && firedFor.at === beat.at && now < firedFor.firedAt + intervalMs) return false;
+  return true;
+}
+
+/** The extension factory omp calls once per session. */
+export default function controllerAlarm(pi) {
+  let latched = false;
+  pi.on("session_start", async (_event, ctx) => {
+    try {
+      if (latched || ctx?.agent?.kind !== "main") return;
+      latched = true;
+      arm(pi, ctx);
+    } catch {
+      // Loads into every session on the box: a fault here must cost that
+      // session nothing.
+    }
+  });
+}
+
+function arm(pi, ctx) {
+  let fleetDir;
+  try {
+    fleetDir = fleetFile(null, { cwd: ctx.cwd });
+  } catch (e) {
+    if (e instanceof FleetDirUnresolvable) return;
+    throw e;
+  }
+  const beatFile = stateFileIn(fleetDir);
+  let firedFor = null;
+
+  const poll = () => {
+    try {
+      const { controller, beat } = readState(beatFile, "fleet-alarm", () => {});
+      const now = Date.now();
+      const due = alarmDue({ kind: ctx.agent.kind, pid: process.pid, controller, beat, idle: ctx.isIdle(), now, firedFor });
+      if (!due) return;
+      // A send that rejects later must not surface as an unhandled rejection in a session that is not ours.
+      Promise.resolve(pi.sendUserMessage(ALARM_LINE)).catch(() => {});
+      firedFor = { at: beat.at, firedAt: now };
+    } catch {
+      // Cannot read or judge: not due.
+    }
+  };
+  ctx.setInterval(poll, POLL_MS);
+
+  let lstart = null;
+  try {
+    lstart = processSource().startTime(process.pid);
+  } catch {
+    // An unreadable process table is an unreadable start time.
+  }
+  if (typeof lstart !== "string" || lstart === "") return;
+  const dir = join(homedir(), ".fleet", "alarm");
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, `${process.pid}.json`), `${JSON.stringify({ pid: process.pid, lstart, fleet: fleetDir })}\n`);
+}

package/scripts/fleet-state.mjs

@@ -123,7 +123,12 @@ const PRIORS = ["dead", "ancestor", "none"];
 // below accepts: it reads as no record, and the next write would drop the
 // key. All of them come back flagged `degraded`, for the one caller that
 // must not read them as a file with nothing in it.
-export function readState(path, name) {
+//
+// `warn` is where those announcements go, `console.error` by default so every
+// caller that passes nothing is unchanged. A caller that polls on a timer and
+// must not repeat a degraded read on a screen every few seconds passes its own
+// sink instead of copying the validation below.
+export function readState(path, name, warn = console.error) {
   // `beat: null` is the absent MARK, and it is not the same value as a mark
   // whose fields are zero: nothing has been seen beating, so there is nothing
   // to judge and nothing to report. A zeroed mark would date the beat to the
@@ -149,7 +154,7 @@ export function readState(path, name) {
     // degraded read reported as a fresh run, which is the failure class this
     // whole ticket exists to close.
     if (e.code !== "ENOENT") {
-      console.error(`${name}: WARNING could not read ${path} (${e.message}) — restarting at the base interval`);
+      warn(`${name}: WARNING could not read ${path} (${e.message}) — restarting at the base interval`);
       return makeDegraded("exists but cannot be read");
     }
     return fresh;
@@ -158,11 +163,11 @@ export function readState(path, name) {
   try {
     parsed = JSON.parse(raw);
   } catch (e) {
-    console.error(`${name}: WARNING ${path} is not JSON (${e.message}) — restarting at the base interval`);
+    warn(`${name}: WARNING ${path} is not JSON (${e.message}) — restarting at the base interval`);
     return makeDegraded("is not JSON");
   }
   if (!isRecord(parsed)) {
-    console.error(`${name}: WARNING ${path} is not an object — restarting at the base interval`);
+    warn(`${name}: WARNING ${path} is not an object — restarting at the base interval`);
     return makeDegraded("is not a JSON object");
   }
   // Per-field validation, not all-or-nothing: a file carrying a good `quiet`
@@ -254,7 +259,7 @@ export function readState(path, name) {
   // causes, and flagged.
   const record = ctl(controller);
   if ("controller" in parsed && record === null) {
-    console.error(`${name}: WARNING ${path} holds a controller record that cannot be judged — restarting at the base interval`);
+    warn(`${name}: WARNING ${path} holds a controller record that cannot be judged — restarting at the base interval`);
     return makeDegraded("holds a controller record that cannot be judged");
   }
   return {

package/scripts/ledger-grammar.mjs

@@ -117,27 +117,37 @@ export function memberRole(family) {
 
 // A `## Dispatched` entry is a member token, followed by `brief=<hash>` when
 // `ledger.mjs dispatch` recorded the brief the member was dispatched with:
-// the first 8 hex of the sha256 the brief's sidecar carries. `settle`
-// rewrites the token and keeps the word beside it.
-const BRIEF_WORD = /^brief=([0-9a-f]{8})$/;
+// the first 8 hex of the sha256 the brief's sidecar carries. A merge bot's
+// entry then carries `queued=<pr>,<pr>…` — `queued=none` for an empty queue —
+// the open `ready-to-merge` PRs `dispatch` read when it dispatched the bot,
+// which its report is judged against at `settle --from-report`. `settle`
+// rewrites the token and keeps the words beside it.
+const DISPATCHED_ENTRY = /^([^ ]*) brief=([0-9a-f]{8})(?: queued=(none|[1-9][0-9]*(?:,[1-9][0-9]*)*))?$/;
 
 /**
- * `{token, brief}` for one `## Dispatched` entry: the member token and the
- * brief's hash, or null for an entry without one. An entry that is not a
- * member token plus one well-formed `brief=` word is returned whole as
- * `token`, so a reader parsing it with parseToken() refuses it exactly as it
- * refuses any other entry this grammar cannot parse.
+ * `{token, brief, queued}` for one `## Dispatched` entry: the member token,
+ * the brief's hash or null, and the PR numbers of its `queued=` word or null
+ * for an entry without one. An entry that is not a member token plus a
+ * well-formed `brief=` word, optionally followed by a well-formed `queued=`
+ * word, is returned whole as `token`, so a reader parsing it with
+ * parseToken() refuses it exactly as it refuses any other entry this grammar
+ * cannot parse.
  */
 export function parseDispatchedEntry(entry) {
-  const words = entry.split(" ");
-  const m = words.length === 2 ? BRIEF_WORD.exec(words[1]) : null;
-  if (m === null || parseToken(words[0]) === null) return { token: entry, brief: null };
-  return { token: words[0], brief: m[1] };
+  const m = DISPATCHED_ENTRY.exec(entry);
+  if (m === null || parseToken(m[1]) === null) return { token: entry, brief: null, queued: null };
+  const queued = m[3] === undefined ? null : m[3] === "none" ? [] : m[3].split(",").map(Number);
+  return { token: m[1], brief: m[2], queued };
 }
 
-/** The `## Dispatched` entry for `token`, with `brief=<brief>` unless brief is null. */
-export function dispatchedEntry(token, brief) {
-  return brief === null ? token : `${token} brief=${brief}`;
+/**
+ * The `## Dispatched` entry for `token`, with `brief=<brief>` unless brief is
+ * null and, after it, `queued=…` unless queued is null.
+ */
+export function dispatchedEntry(token, brief, queued = null) {
+  if (brief === null) return token;
+  const entry = `${token} brief=${brief}`;
+  return queued === null ? entry : `${entry} queued=${queued.join(",") || "none"}`;
 }
 
 // `PR#<n>` as a word of a row's text, `PR #<n>` too.

package/scripts/ledger.mjs

@@ -13,7 +13,9 @@
 // every liveness count from this file alone, rather than from row text a
 // controller typed by hand: `dispatch` writes a member's live token onto its
 // row and appends it to `## Dispatched` with `brief=<hash>`, the brief it
-// refuses to dispatch without; when that brief's sidecar names an absolute
+// refuses to dispatch without — and, for a merge bot, `queued=<pr>,…`, the
+// open `ready-to-merge` PRs gh lists at dispatch, which its report must give
+// a verdict each; when that brief's sidecar names an absolute
 // scratch, it also clears the member's report file there, so a prior run's
 // report is not read as this run's; `settle` rewrites that token to
 // `<member>=<outcome>` in both places (an implementer's settle to `PR#M` also
@@ -59,6 +61,7 @@ import { stateFileIn, readState, writeState, assessBeat, stallsAt } from "./flee
 import { processSource, ancestry, controllerOf, judgeController, ProcUnreadable } from "./proc.mjs";
 import { attemptLock, releaseLockFile, reapPathOf } from "./pid-lock.mjs";
 import { readCheckRecordIn, readReportIn, reportsDir, reportFamily, defaultScratch, reportPath } from "./report-files.mjs";
+import { mergeBotVerdicts } from "./report-schema.mjs";
 
 const NAME = "ledger";
 // The plugin's own agent definitions — the directory tier-check.mjs reads
@@ -494,7 +497,7 @@ function sectionOf(text, name) {
 }
 
 function load() {
-  if (!existsSync(file)) return { rows: [], filed: [], ruled: [], dispatched: [], briefs: {}, drain: null, retired: [] };
+  if (!existsSync(file)) return { rows: [], filed: [], ruled: [], dispatched: [], briefs: {}, queued: {}, drain: null, retired: [] };
   let text;
   try {
     text = readFileSync(file, "utf8");
@@ -526,15 +529,14 @@ function load() {
 }
 
 // `## Dispatched` held as its tokens, which is what every reader of `read`
-// parses, and `briefs`, each member's `brief=` hash by name: one token per
-// member name for the session, so a settle that rewrites the token keeps the
-// name its brief is filed under. save() joins them back.
+// parses, `briefs`, each member's `brief=` hash by name, and `queued`, each
+// merge bot's `queued=` PR numbers by name: one token per member name for
+// the session, so a settle that rewrites the token keeps the name its brief
+// and its queue are filed under. save() joins them back.
 function dispatchedOf(entries) {
   const parsed = entries.map(parseDispatchedEntry);
-  return {
-    dispatched: parsed.map((p) => p.token),
-    briefs: Object.fromEntries(parsed.filter((p) => p.brief !== null).map((p) => [parseToken(p.token).name, p.brief])),
-  };
+  const byName = (field) => Object.fromEntries(parsed.filter((p) => p[field] !== null).map((p) => [parseToken(p.token).name, p[field]]));
+  return { dispatched: parsed.map((p) => p.token), briefs: byName("brief"), queued: byName("queued") };
 }
 
 // `## Drain` is written only once there is a marker to hold: an empty section
@@ -547,7 +549,10 @@ function save(d) {
   const list = (entries) => entries.map((r) => `- ${escapeText(r)}`).join("\n");
   const out =
     `# Fleet run ledger\n\n${ROWS}\n\n` + list(d.rows) +
-    `\n\n${DISPATCHED}\n\n` + list(d.dispatched.map((t) => dispatchedEntry(t, d.briefs[parseToken(t)?.name] ?? null))) +
+    `\n\n${DISPATCHED}\n\n` + list(d.dispatched.map((t) => {
+      const name = parseToken(t)?.name;
+      return dispatchedEntry(t, d.briefs[name] ?? null, d.queued[name] ?? null);
+    })) +
     `\n\n${FILED}\n\n` + list(d.filed) +
     `\n\n${RULED}\n\n` + list(d.ruled) +
     (d.drain === null ? "" : `\n\n${DRAIN}\n\n` + list([d.drain])) +
@@ -694,6 +699,9 @@ const WRITE_COMMANDS = new Set(["row", "token", "filed", "ruled", "dispatch", "s
 // `settle --from-report` takes the lock itself, once its checks have run —
 // see runSettleFromReport().
 const FROM_REPORT = cmd === "settle" && rest.includes("--from-report");
+// A merge bot's dispatch reads the queue it records before the lock, for the
+// same reason: a gh call held under the lock stalls every other writer.
+const QUEUED = cmd === "dispatch" && rest.length === 1 && /^merge-bot(-[0-9]+)?$/.test(rest[0]) ? queueSnapshot() : null;
 if (WRITE_COMMANDS.has(cmd) && !FROM_REPORT) await acquireLock();
 // `rotate` never load()s: a ledger load() would refuse is still the previous
 // run's record, and it is archived as-is — and read line by line when it
@@ -1630,7 +1638,7 @@ function runRotate() {
   }
   // Read before anything moves: a ledger whose live tokens cannot be read is
   // refused with nothing moved, never archived with those tokens dropped.
-  let carry = { rows: [], dispatched: [], briefs: {}, retired: [], skipped: [] };
+  let carry = { rows: [], dispatched: [], briefs: {}, queued: {}, retired: [], skipped: [] };
   if (prior === "ancestor" && exists) {
     let text;
     try {
@@ -1691,7 +1699,7 @@ function runRotate() {
   // Nothing to carry writes nothing, so the next write starts the skeleton
   // exactly as after any other verdict.
   if (carrying) {
-    save({ rows: carry.rows, dispatched: carry.dispatched, briefs: carry.briefs, filed: [], ruled: [], drain: null, retired: carry.retired });
+    save({ ...carry, filed: [], ruled: [], drain: null });
   }
   if (archive !== null) console.error(`    rotated ${file} -> ${archive}`);
   for (const { line, why } of carry.skipped) {
@@ -1751,10 +1759,11 @@ function carryOf(text) {
       return false;
     }
   });
-  // An entry's `brief=` travels with it: save() writes a brief only beside
-  // the token it writes, so a carried member's record still names the brief
-  // it was dispatched with and a dropped member's does not.
-  const { dispatched: allDispatched, briefs: allBriefs } = dispatchedOf(sectionOf(text, DISPATCHED));
+  // An entry's `brief=` and `queued=` travel with it: save() writes them only
+  // beside the token it writes, so a carried member's record still names the
+  // brief it was dispatched with — and a carried merge bot the queue it is
+  // judged against — and a dropped member's does not.
+  const { dispatched: allDispatched, briefs: allBriefs, queued: allQueued } = dispatchedOf(sectionOf(text, DISPATCHED));
   const dispatched = allDispatched.filter((e) => {
     const t = parseToken(e);
     if (t !== null && t.error === null) return true;
@@ -1777,7 +1786,7 @@ function carryOf(text) {
   const live = liveOnLedger(rows, dispatched);
   const carried = { rows: live.rows.map((i) => rows[i]), dispatched: live.dispatched };
   const retired = retiredOnLedger([...rows, ...skippedRows], allDispatched, archivedRetired, carried);
-  return { ...carried, briefs: allBriefs, retired, skipped };
+  return { ...carried, briefs: allBriefs, queued: allQueued, retired, skipped };
 }
 
 // ── dispatch / settle ────────────────────────────────────────────────────────
@@ -1884,6 +1893,37 @@ function dispositionsRefusal(pr, review) {
   return null;
 }
 
+// The open `ready-to-merge` PRs, ascending, as gh answers from the ledger's
+// own directory with runCheck()'s environment: the queue a merge bot is
+// dispatched against, recorded on its `## Dispatched` entry. Anything but a
+// JSON array of PR numbers, or an answer filling the limit — gh stops there
+// at exit 0 — could not read the queue: refused, nothing written.
+function queueSnapshot() {
+  const limit = 1000;
+  const what = `gh pr list --state open --label ready-to-merge --limit ${limit} --json number`;
+  const env = { ...process.env, GH_REPO: "" };
+  delete env.GIT_DIR;
+  delete env.GIT_WORK_TREE;
+  let dir = dirname(resolve(file));
+  while (!existsSync(dir) && dirname(dir) !== dir) dir = dirname(dir);
+  const r = spawnSync("gh", what.split(" ").slice(1), { encoding: "utf8", cwd: dir, env, timeout: 60_000, stdio: ["ignore", "pipe", "pipe"] });
+  const refuse = (why) => die(`dispatch merge-bot: could not read the queue to record — ${what}${why}; nothing written`);
+  if (r.status !== 0) {
+    const why = cause(r.error && r.error.message, r.stderr);
+    refuse(`${r.error ? "" : r.signal ? ` killed by ${r.signal}` : ` exited ${r.status}`}${why ? `: ${why}` : ""}`);
+  }
+  let list = null;
+  try {
+    list = JSON.parse(r.stdout);
+  } catch {
+    // Refused below.
+  }
+  const prs = Array.isArray(list) ? list.map((p) => p?.number) : null;
+  if (prs === null || !prs.every((n) => Number.isSafeInteger(n) && n > 0)) refuse(` printed no list of PR numbers: ${cause(r.stdout)}`);
+  if (prs.length >= limit) refuse(` answered ${prs.length} PRs, the limit, so the queue may be longer`);
+  return [...new Set(prs)].sort((a, b) => a - b);
+}
+
 function runDispatch() {
   const usage = "usage: ledger.mjs dispatch <ticket|pr> <member>, or dispatch merge-bot";
   if (rest.length === 0 || rest.length > 2) die(usage);
@@ -2055,10 +2095,14 @@ function runDispatch() {
   }
   data.dispatched.push(member.name);
   data.briefs[member.name] = brief.sha256.slice(0, 8);
+  // A merge bot's queue is recorded here, beside its brief, where nothing in
+  // its report can reach: `settle --from-report` judges the report against it.
+  if (QUEUED !== null) data.queued[member.name] = QUEUED;
   save(data);
   console.error(`    dispatched ${member.name}`);
   console.log(JSON.stringify({
     member: member.name, agent, ticket: line === null ? null : rowKey(line), line, created, total: data.dispatched.length, brief,
+    queued: QUEUED,
   }));
 }
 
@@ -2292,7 +2336,11 @@ function recordFiled(id, subject) {
 //                             the report's labelsReadBack
 //   finisher-pr-M=halted:<c>  cause is in the halted:<cause> vocabulary and
 //                             evidence is not empty
-//   merge-bot-n=done          every merged[].pr reads MERGED
+//   merge-bot-n=done          every merged[].pr reads MERGED; every PR the
+//                             bot's `## Dispatched` entry records as queued=
+//                             at dispatch has a verdict in merged, held,
+//                             conflictHold or refused, or no longer reads
+//                             OPEN with ready-to-merge
 //
 // THE CHECK-STEP RECORD, for `impl-N=PR#M` and `fix-pr-M=applied:<head>`:
 // recipe-check.mjs writes `<reports>/<member>.check.json` on the member's
@@ -2312,15 +2360,21 @@ function recordFiled(id, subject) {
 // stderr names each failed check; nothing written. Exit 2: the report is
 // absent, unreadable or invalid, a check could not look (a `gh`, `git` or
 // verify-sha.sh call that failed, printed what it was not asked for, or never
-// finished), or a refusal the bare form makes; nothing written either.
+// finished), a merge bot's `## Dispatched` entry records no queued=, or a
+// refusal the bare form makes; nothing written either.
 //
 // After the settle, in the same write: every `unrecorded` entry goes to `##
-// Filed` the way `filed` records one, and for a fix-applier every `deferred`
+// Filed` the way `filed` records one, for a fix-applier every `deferred`
 // entry in the `refuted` bucket goes to `## Ruled` as `#M reversed refutation
-// <index>: <reason>`. A line already there is not written again, so a second
-// run of the same settle writes nothing. The receipt on stdout is `{member,
-// outcome, checks: [{name, ok}], filed, ruled}`, `filed` and `ruled` the
-// lines this call added.
+// <index>: <reason>`, and for a merge bot every `refused` entry goes to `##
+// Ruled` as `merge-bot-n refused #<pr>: <reason>`, the reason trimmed — a
+// record, which moves no label and writes no row token. It is led by the bot,
+// never by `#<pr>`: compute-board.mjs reads a `## Ruled` line led by `#<n>` as
+// the controller's ruling on PR n, the last such line winning, so a refusal
+// led by its PR would replace that ruling on the board. A line already there
+// is not written again, so a second run of the same settle writes nothing.
+// The receipt on stdout is `{member, outcome, checks: [{name, ok}], filed,
+// ruled}`, `filed` and `ruled` the lines this call added.
 //
 // The checks run before the write lock is taken, against the ledger as read
 // without it, because they are network calls and every other writer waits
@@ -2558,6 +2612,22 @@ async function runSettleFromReport() {
   } else {
     outcome = "done";
     for (const { pr } of report.merged) check(`PR #${pr} reads MERGED`, prView(pr, "state").state === "MERGED");
+    // Every PR queued when the bot was dispatched has a verdict, unless it has
+    // left the queue since — merged by someone else, closed or unlabelled. The
+    // queue is the one `dispatch` recorded, never one the report names, so a
+    // PR the report leaves out cannot shrink it; a PR labelled after dispatch
+    // is not in it.
+    const queued = data.queued[member];
+    if (queued === undefined) {
+      die(`${where}: ## Dispatched records no queued= for ${member}, so whether its report gives every PR queued at dispatch a verdict cannot be judged — settle it by hand; nothing written`);
+    }
+    const given = new Set(mergeBotVerdicts(report).map((v) => v.pr));
+    for (const pr of queued.filter((n) => !given.has(n))) {
+      const v = prView(pr, "state,labels");
+      const left = v.state !== "OPEN" || !v.labels.some((l) => l?.name === ready);
+      check(`PR #${pr}, queued at dispatch, has a verdict in merged, held, conflictHold or refused, or has left the queue`, left);
+    }
+    for (const { pr, reason } of report.refused) ruledLines.push(`${member} refused #${pr}: ${reason.trim()}`);
   }
 
   const failed = checks.filter((c) => !c.ok);

package/scripts/report-files.mjs

@@ -6,8 +6,9 @@
 // (flat: no per-run directory), `<member>` being its ledger name (`impl-412`,
 // `impl-412-b`, `fix-pr-88`, `finisher-pr-88`, `merge-bot-3`). The file is
 // checked against the schema of the member's family, report-schema.mjs's
-// SCHEMAS. The review runner and every member outside those four families
-// have no schema, so no file to look up.
+// SCHEMAS, and the rule reportViolation() adds to it. The review runner and
+// every member outside those four families have no schema, so no file to
+// look up.
 //
 // The Check-step record beside a report, `<reports>/<member>.check.json`, is
 // looked up here the same way: recipe-check.mjs writes it, and this module
@@ -18,7 +19,7 @@
 
 import { readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-import { SCHEMAS, parseReport, validate } from "./report-schema.mjs";
+import { parseReport, reportViolation } from "./report-schema.mjs";
 import { parseMember } from "./ledger-grammar.mjs";
 import { scratchRoot } from "./fleet-dir.mjs";
 
@@ -113,7 +114,7 @@ export function readReportIn(dir, member) {
   const read = readAt(path);
   if (read.text === undefined) return read;
   const parsed = parseReport(read.text);
-  const violation = parsed.violation ?? validate(SCHEMAS[family], parsed.value);
+  const violation = parsed.violation ?? reportViolation(family, parsed.value);
   return violation === null ? { state: "ok", path, report: parsed.value } : { state: "invalid", path, violation };
 }
 

package/scripts/report-schema.mjs

@@ -18,7 +18,9 @@
 //   0  print: the schema is on stdout. validate: `valid` on stdout
 //   1  validate: `invalid: <violation>` on stdout, naming the FIRST violation;
 //      a file that is not JSON is invalid too, as `$: not JSON (...)`, and so
-//      is one that repeats a key, as `$.merged: duplicate key "merged"`
+//      is one that repeats a key, as `$.merged: duplicate key "merged"`, and
+//      a merge-bot report giving one PR two verdicts, as
+//      `$.refused[0].pr: PR #<pr> already has a verdict at $.merged[0].pr`
 //   2  usage: no or unknown subcommand, a wrong argument count, an unknown
 //      family, any flag; or <file> could not be read; or print could not
 //      write the schema to stdout. Refused on stderr, nothing on stdout
@@ -153,11 +155,41 @@ export const SCHEMAS = {
     merged: listOf({ pr: id, sha }),
     held: listOf({ pr: id, behind: id }),
     conflictHold: { type: "array", items: id },
-    refused: listOf({ pr: id, reason: str }),
+    // A refusal is a verdict only with a reason: the reason is the record
+    // `## Ruled` gets, so one with no text but whitespace is invalid.
+    refused: listOf({ pr: id, reason: { type: "string", pattern: "\\S" } }),
     branchKept: listOf({ pr: id, by: id }),
   }),
 };
 
+// Every verdict a merge-bot report gives, as `{pr, path}`, `path` the entry's
+// PR field: `merged`, `held`, `conflictHold`, then `refused`, each in report
+// order. `branchKept` gives none: it names a merged PR's branch and the open
+// PR keeping it.
+export function mergeBotVerdicts(report) {
+  return [
+    ...["merged", "held"].flatMap((k) => report[k].map((e, i) => ({ pr: e.pr, path: `$.${k}[${i}].pr` }))),
+    ...report.conflictHold.map((pr, i) => ({ pr, path: `$.conflictHold[${i}]` })),
+    ...report.refused.map((e, i) => ({ pr: e.pr, path: `$.refused[${i}].pr` })),
+  ];
+}
+
+// The first violation of `family`'s schema by `value`, or null; for a
+// merge-bot report then the rule no schema keyword states: each PR gets one
+// verdict — merged, held, conflict-held or refused — the last it reached in
+// the pass, so a PR named twice, in one list or in two, is a violation at
+// its second entry.
+export function reportViolation(family, value) {
+  const found = validate(SCHEMAS[family], value);
+  if (found !== null || family !== "merge-bot") return found;
+  const first = new Map();
+  for (const { pr, path } of mergeBotVerdicts(value)) {
+    if (first.has(pr)) return `${path}: PR #${pr} already has a verdict at ${first.get(pr)}`;
+    first.set(pr, path);
+  }
+  return null;
+}
+
 const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
 
 function typeOf(v) {
@@ -279,7 +311,7 @@ function main() {
   }
   if (cmd !== "validate" || path === undefined) die(USAGE);
 
-  const schema = familyOf(family);
+  familyOf(family);
   let text;
   try {
     text = readFileSync(path, "utf8");
@@ -287,7 +319,7 @@ function main() {
     die(`cannot read ${path}: ${e.code ?? e.message}`);
   }
   const parsed = parseReport(text);
-  const violation = parsed.violation ?? validate(schema, parsed.value);
+  const violation = parsed.violation ?? reportViolation(family, parsed.value);
   if (violation !== null) {
     writeAll(1, `invalid: ${violation}\n`);
     process.exit(1);

package/skills/run-team/references/ledger.md

@@ -76,11 +76,13 @@ One line per ticket, rewritten in place (`ledger.mjs row <ticket> <text>`; `ledg
 
 A member that dies between spawn and write is invisible — and members die in batches.
 
+`dispatch merge-bot` also records the queue the bot is dispatched against: its `## Dispatched` entry carries `queued=<pr>,<pr>…` (`queued=none` for an empty queue), the open `ready-to-merge` PRs gh lists at that moment. A gh that cannot answer refuses the dispatch, nothing written. `settle merge-bot-<n> --from-report` judges the bot's report against that queue, not against anything the report names: a PR from it that is still open and carries the label, with no verdict in `merged`, `held`, `conflictHold` or `refused`, fails the settle at exit 3, naming the PR, and an entry without `queued=` cannot be judged (exit 2) — settle that bot by hand.
+
 ## filed and ruled
 
 `filed` is checked with `ledger.mjs check <subject>` before every `gh issue create`, so a finding already recorded this run is not filed twice. That is not a guarantee against duplicates at large; the tracker query, described under `check`'s exits and its `verdict` above, is what covers those.
 
-`ruled` records PR + decision + one-line reason, so a replacement controller does not re-litigate a settled call.
+`ruled` records PR + decision + one-line reason, so a replacement controller does not re-litigate a settled call. A merge bot's settle adds one line per `refused[]` entry of its report, `merge-bot-<n> refused #<pr>: <reason>`: a record of the refusal and nothing more — no label moves and no row token is written. It is led by the bot, not by `#<pr>`, because the board reads a `#<pr>`-led line as your ruling on that PR, the last one winning, and a refusal must not replace it.
 
 ## Label-off and conflict holds