@feigi/fleet-ctl 3.84.0 → 3.86.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.84.0",
+  "version": "3.86.0",
   "description": "Agent fleet: run-team controller, merge bot, PR reviewer, and the ticket pipeline they share",
   "license": "Apache-2.0",
   "repository": {

package/scripts/controller-alarm.mjs

@@ -45,8 +45,8 @@
 // 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
+// reads it, and the `.fleet/` path it resolved. Phase 0's `alarm` step reads
+// the file and refuses unless it names this omp and this `.fleet/`. 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:
@@ -59,13 +59,15 @@
 
 import { mkdirSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { dirname, 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";
+// Where the extension running as `pid` records that its timer is armed; phase 0 reads it there.
+export const alarmFile = (pid) => join(homedir(), ".fleet", "alarm", `${pid}.json`);
 
 /**
  * Whether the alarm fires now. `beat` is `{ at, interval, stopped }` (`at` in
@@ -132,7 +134,7 @@ function arm(pi, ctx) {
     // 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`);
+  const file = alarmFile(process.pid);
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, `${JSON.stringify({ pid: process.pid, lstart, fleet: fleetDir })}\n`);
 }

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/phase0-receipt.mjs

@@ -18,7 +18,7 @@ const isRecord = (x) => x !== null && typeof x === "object" && !Array.isArray(x)
 // a step not yet run being `pending`. A receipt missing one was not written
 // by a finished phase 0.
 export const STEP_NAMES = Object.freeze([
-  "branch", "fast-forward", "pin", "baseline", "preflight", "ruleset", "tier-roles", "metrics",
+  "alarm", "branch", "fast-forward", "pin", "baseline", "preflight", "ruleset", "tier-roles", "metrics",
   "cockpit", "rotate", "reclaim", "recipe", "fold-in", "stranded", "shortlist",
 ]);
 

package/scripts/phase0.mjs

@@ -20,6 +20,9 @@
 // reclaim straight after the rotation, the metrics refresh before the first
 // Pull is routed:
 //
+//   alarm         `~/.fleet/alarm/<pid>.json` names this omp's pid and start time
+//                 and this `.fleet/`. Missing, malformed or mismatched, or no omp
+//                 above the script, refuses: restart omp.
 //   branch        `git symbolic-ref -q HEAD` is refs/heads/main. A checkout left
 //                 on a branch whose PR has merged would fast-forward that branch
 //                 and the baseline would record it as the run's ref.
@@ -82,29 +85,31 @@
 // is the In-flight bound this run used — `--in-flight`, or its default.
 //
 // RESUMABLE. A re-run reads the receipt. It continues it — skipping every `ok`
-// step and re-running the rest — only when its `run` equals the `at` the
-// controller record holds now AND its `session` equals this run's session. That
-// comparison alone does not separate two runs before the new run's rotation:
-// the record still carries the previous run's `at` until `ledger.mjs rotate`
-// writes the next, so the previous run's receipt still matches it, and a
-// re-run that trusted `run` alone would skip `rotate`. The session rule closes
-// a new session. A receipt of any other run (a `run` that is set and does not
-// match, or a different session) is held as `phase0.previous.json`, where
-// `closeout.mjs finish` also leaves a finished run's receipt, and the
-// script starts at `branch`; this run's own receipt is written at
-// `phase0.json` after every step. A receipt whose rotation has not run is
-// simply overwritten: every step before `rotate` is idempotent and is re-run
-// on every invocation until the rotation has run.
+// step but `alarm` and re-running the rest — only when its `run` equals the
+// `at` the controller record holds now AND its `session` equals this run's
+// session. That comparison alone does not separate two runs before the new
+// run's rotation: the record still carries the previous run's `at` until
+// `ledger.mjs rotate` writes the next, so the previous run's receipt still
+// matches it, and a re-run that trusted `run` alone would skip `rotate`. The
+// session rule closes a new session. `alarm` is re-run on every invocation,
+// `ok` or not: it proves something about the omp running this invocation, and
+// a resumed receipt may have been written under another. A receipt of any
+// other run (a `run` that is set and does not match, or a different session)
+// is held as `phase0.previous.json`, where `closeout.mjs finish` also leaves a
+// finished run's receipt, and the script starts at `alarm`; this run's own
+// receipt is written at `phase0.json` after every step. A receipt whose
+// rotation has not run is simply overwritten: every step before `rotate` is
+// idempotent and is re-run on every invocation until the rotation has run.
 //
 // THE ROTATION FILES THE PREVIOUS RUN'S RECEIPT. The `rotate` step takes this
 // run's partial receipt off disk, puts the held one back at `phase0.json` and
 // runs `ledger.mjs rotate`, which archives it as `phase0.<UTC stamp>.json`
 // beside `ledger.<UTC stamp>.md`, one stamp for both. A rotation that refused
 // leaves it held for the next attempt; one that archived the ledger and not
-// the receipt files it under a stamp of this script's own. With no omp process
-// above the run the rotation writes no controller record and `run` stays
-// null; a receipt whose `rotate` step is `ok` is then resumed on the session
-// alone.
+// the receipt files it under a stamp of this script's own. A rotation that
+// writes no controller record (the ledger finds no omp above itself) leaves
+// `run` null; a receipt whose `rotate` step is `ok` is then resumed on the
+// session alone.
 //
 // A step that fails stops the script; so does a pending one — nothing after
 // the recipe may run before it is proven, and the shortlist waits for the
@@ -133,16 +138,19 @@ import { existsSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync,
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { makeDie, defineFlags, isDigits } from "./arg.mjs";
+import { alarmFile } from "./controller-alarm.mjs";
 import { FleetDirUnresolvable, fleetFile } from "./fleet-dir.mjs";
 import { readState, stateFileIn } from "./fleet-state.mjs";
 import { gitEnv } from "./git-env.mjs";
 import { isCLI } from "./is-cli.mjs";
 import { RECEIPT, RECEIPT_HELD, archiveStamp, receiptArchiveName, rowNums } from "./ledger-grammar.mjs";
+import { ancestry, controllerOf, processSource, ProcUnreadable } from "./proc.mjs";
 import { IN_FLIGHT_DEFAULT } from "./phase0-receipt.mjs";
 
 const NAME = "phase0";
 const SCRIPTS = dirname(fileURLToPath(import.meta.url));
 const MAX_BUFFER = 64 * 1024 * 1024;
+const isRecord = (x) => x !== null && typeof x === "object" && !Array.isArray(x);
 const NETWORK_TIMEOUT_MS = 120_000;
 const PR_LIMIT = 1000;
 // The tail of a child's output is the part that says why it stopped.
@@ -419,8 +427,46 @@ function shortlist({ cwd }) {
   return ok("shortlist built");
 }
 
+// The controller alarm: this omp's own record that its timer is armed against
+// this checkout's `.fleet/` (controller-alarm.mjs writes it at session_start).
+// The record is read, not trusted: it must name this omp's pid and start time
+// and this `.fleet/`.
+function alarm({ fleetDir }) {
+  const tail = " — restart omp";
+  let controller;
+  try {
+    const source = processSource();
+    controller = controllerOf(source, ancestry(source));
+  } catch (e) {
+    if (!(e instanceof ProcUnreadable)) throw e;
+    return failed(`${e.message}${tail}`);
+  }
+  if (controller === null) return failed(`no omp process above phase 0: the controller alarm cannot be checked${tail}`);
+  const path = alarmFile(controller.pid);
+  let text;
+  try {
+    text = readFileSync(path, "utf8");
+  } catch (e) {
+    if (e.code === "ENOENT") return failed(`controller alarm is not armed: ${path} does not exist${tail}`);
+    return failed(`controller alarm file ${path} cannot be read (${e.code ?? e.message})${tail}`);
+  }
+  let rec;
+  try {
+    rec = JSON.parse(text);
+  } catch (e) {
+    return failed(`controller alarm file ${path} is not JSON (${e.message})${tail}`);
+  }
+  if (!isRecord(rec)) return failed(`controller alarm file ${path} is not an object${tail}`);
+  const missing = ["pid", "lstart", "fleet"].filter((k) => !Object.hasOwn(rec, k));
+  if (missing.length > 0) return failed(`controller alarm file ${path} lacks ${missing.join(", ")}${tail}`);
+  if (rec.pid !== controller.pid) return failed(`controller alarm file ${path} names pid ${rec.pid}, but this omp is pid ${controller.pid}${tail}`);
+  if (rec.lstart !== controller.lstart) return failed(`controller alarm file ${path} was written by a process started at "${rec.lstart}", but this omp started at "${controller.lstart}"${tail}`);
+  if (rec.fleet !== fleetDir) return failed(`controller alarm file ${path} names fleet "${rec.fleet}", not ${fleetDir}${tail}`);
+  return ok(`controller alarm armed: pid ${controller.pid}, ${fleetDir}`);
+}
+
 const STEPS = {
-  "branch": branch, "fast-forward": fastForward, "pin": pin, "baseline": baseline, "preflight": preflight,
+  "alarm": alarm, "branch": branch, "fast-forward": fastForward, "pin": pin, "baseline": baseline, "preflight": preflight,
   "ruleset": ruleset, "tier-roles": tierRoles, "metrics": metrics, "cockpit": cockpit, "rotate": rotate,
   "reclaim": reclaim, "recipe": recipe, "fold-in": foldIn, "stranded": stranded, "shortlist": shortlist,
 };
@@ -445,8 +491,7 @@ function readReceipt(path) {
   } catch (e) {
     throw new Error(`the receipt ${path} is not JSON (${e.message}) — move it aside and re-run`);
   }
-  const record = (x) => x !== null && typeof x === "object" && !Array.isArray(x);
-  if (!(record(r) && record(r.steps) && Object.hasOwn(r, "run") && typeof r.session === "string")) {
+  if (!(isRecord(r) && isRecord(r.steps) && Object.hasOwn(r, "run") && typeof r.session === "string")) {
     throw new Error(`the receipt ${path} has no steps, run and session — move it aside and re-run`);
   }
   return r;
@@ -548,9 +593,9 @@ function main() {
     return;
   }
   // A receipt belongs to a rotated run when the rotation wrote a controller
-  // record it can be keyed on, or, with no omp process above the run to write
-  // one, when its rotation is recorded `ok`. Either way it is this run's only
-  // if the record now holds the `at` it names and the session is the same.
+  // record it can be keyed on, or, when it wrote none, when its rotation is
+  // recorded `ok`. Either way it is this run's only if the record now holds
+  // the `at` it names and the session is the same.
   const rotated = previous !== null && (previous.run !== null || previous.steps.rotate?.status === "ok");
   const resumed = rotated && previous.run === (record?.at ?? null) && previous.session === session;
   if (rotated && !resumed) {
@@ -564,7 +609,8 @@ function main() {
 
   const receipt = { run: resumed ? previous.run : null, session, scratch, inFlight, steps: {} };
   for (const name of STEP_NAMES) {
-    const was = resumed ? previous.steps[name] : undefined;
+    // `alarm` checks the omp running this invocation, so its `ok` is never carried.
+    const was = resumed && name !== "alarm" ? previous.steps[name] : undefined;
     receipt.steps[name] = was?.status === "ok" ? was : { status: "pending", at: now, output: "not run" };
   }
 

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/SKILL.md

@@ -50,8 +50,8 @@ phase, or in any later one, asks the maintainer which tickets to take.
    when the repository has no workflow named CI. Its steps and receipt: See
    references/phase-0.md. Dispatch nothing before it exits 0. Exit 4 is a
    step that needs you: act on each `NEED` line below, then run it again. Once
-   `rotate` has run, a re-run skips every `ok` step and resumes where the last
-   one stopped; before it, a re-run runs every step again.
+   `rotate` has run, a re-run skips every `ok` step but `alarm` and resumes
+   where the last one stopped; before it, a re-run runs every step again.
 
    The `tier-roles` step runs `~/.fleet/bin/fleet-run tier-roles.mjs --check
    --in-flight <B>`, `<B>` being the `--in-flight` given, else the default.

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
 

package/skills/run-team/references/phase-0.md

@@ -13,13 +13,17 @@ Exit 3 is a step that failed: its line carries the refusal, so fix the cause
 and run it again.
 
 `phase0.mjs` runs the start sequence in
-its fixed order — branch, fast-forward, pin, baseline, preflight, ruleset,
+its fixed order — alarm, branch, fast-forward, pin, baseline, preflight, ruleset,
 tier-roles, metrics, cockpit, rotate, reclaim, recipe, fold-in, stranded,
 shortlist — prints one `phase0: <step>: <status>` line per step with the
 `NEED` lines last, and records each step in `.fleet/phase0.json`, which the
 tick reads: it prints `PHASE0-INCOMPLETE` and holds every dispatching row
 until the receipt is whole.
 
+## Check the controller alarm
+
+**Check the controller alarm first. Phase 0's first step refuses when this omp's timer is not armed.** The `alarm` step reads `~/.fleet/alarm/<pid>.json`, where `<pid>` is the omp process above the script, and checks that the file names that pid, that process's start time, and this checkout's `.fleet/`. A file that is missing, not JSON, or names something else, and no omp process above the script, each fail the step with exit 3 and a message ending `restart omp`. Restart omp, then run phase 0 again. The step runs on every run of phase 0, one its receipt records `ok` included, because it checks the omp running that run; nothing after it runs until it passes.
+
 ## Fast-forward the checkout
 
 **Fast-forward the checkout before you trust these rules — you are reading