@feigi/fleet-ctl 3.85.0 → 3.86.1

package/commands/review-and-fix.md

@@ -76,7 +76,7 @@ jq '.refuted' "$R"                                               # refuted: your
 
 `eval` loading `scripts/review-eval.mjs` through the Resolver (`fleet-run --path review-eval.mjs`) and calling `runReviewOnOmp({pr, branch, worktree, testCmd, scratch})` is the fleet's **default** review path. Its `scratch` is the scratch root, never `<scratch>/pr<N>`: the review creates that partition itself and refuses a `scratch` already ending in one, or one that is not an absolute path.
 
-`$(~/.fleet/bin/fleet-run --root)/skills/run-team/SKILL.md`'s Reviewers section owns its dispatch. It cuts the snapshot, sizes the fan-out, adversarially verifies every **critical/important** finding, and has `agent()` return **into the script**, so no report can go undelivered, the failure that cost one fleet five reports on one PR and four on another. It does **not** verify the `suggestion` band — that gets 0 refuters by policy, which is why step 2 checks each one itself — an in-scope one before applying it, an out-of-scope one above the claim bar before filing it. **You cannot run it** — the one member that runs it is the `review-pr-<pr#>` runner (`agents/fleet-review-runner.agent.md`), never a reader of this file.
+`$(~/.fleet/bin/fleet-run --root)/skills/run-team/SKILL.md`'s **The reviewer** bullet owns its dispatch, and `references/reviewers.md` (**A review runs off your turn and relays nothing**) says what it does. It cuts the snapshot, sizes the fan-out, adversarially verifies every **critical/important** finding, and has `agent()` return **into the script**, so no report can go undelivered, the failure that cost one fleet five reports on one PR and four on another. It does **not** verify the `suggestion` band — that gets 0 refuters by policy, which is why step 2 checks each one itself — an in-scope one before applying it, an out-of-scope one above the claim bar before filing it. **You cannot run it** — the one member that runs it is the `review-pr-<pr#>` runner (`agents/fleet-review-runner.agent.md`), never a reader of this file.
 
 It cannot ask the user anything and cannot wait on CI — rebasing, watching checks, binding and labelling stay here.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feigi/fleet-ctl",
-  "version": "3.85.0",
+  "version": "3.86.1",
   "description": "Agent fleet: run-team controller, merge bot, PR reviewer, and the ticket pipeline they share",
   "license": "Apache-2.0",
   "repository": {

package/scripts/compute-spend.mjs

@@ -167,8 +167,8 @@ function roleFromNamePatterns(hay) {
   // dispatch against an ALREADY-OPEN PR, not new ticket work — measured
   // meta.json descriptions "Resolve conflict on PR <n>" and "Rebase and
   // resolve conflicts for PR #<n>", the same rebase/conflict-resolver shape
-  // `run-team/SKILL.md` calls "a rebase-resolver" sent into an open PR's
-  // worktree. It carries no ticket, no dispatch counter and no new-work verb —
+  // `run-team/references/isolation.md` calls "a rebase-resolver" in a prior-run
+  // worktree, here sent into an open PR's worktree. It carries no ticket, no dispatch counter and no new-work verb —
   // only a PR number — so it is remediation on that PR's path to merge,
   // exactly the category `fix-pr-<n>`'s applier already occupies here. It is
   // NOT `merge-bot`: that bucket's number is a per-run dispatch counter, never

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/fleet-heartbeat.mjs

@@ -13,7 +13,7 @@
 // WHY A HOLD AND NOT A WATCHER — the ruling, measured before it was made:
 //
 //   A backgrounded watcher does not wake an idle agent. Measured twice in one
-//   run (run-team/SKILL.md, "A member runs its test suite in the foreground"):
+//   run (run-team/references/member-lifecycle.md, "A member runs its test suite in the foreground"):
 //   `fix-pr-1184` backgrounded its suite plus a Monitor and sat idle for
 //   roughly two hours; neither ever woke it. run-merge-bot.md's CI gate states
 //   the same rule as a rule — "whatever wakes you is external and may never
@@ -28,7 +28,7 @@
 //   do.
 //
 // WHY IT TAKES NO CONTROLLER STATE — every flag below has a default. A monitor
-// event is a wake-up, never a verdict (SKILL.md's Monitor rules), so this
+// event is a wake-up, never a verdict (run-team/SKILL.md, "A monitor event is a wake-up, never a verdict"), so this
 // script never reads or reports fleet state: counts captured before a
 // twenty-minute hold and printed after it are a stale verdict, and a stale
 // verdict is how a reconcile prints an ACTION nobody can take. The controller

package/scripts/fleet-tick.mjs

@@ -239,8 +239,9 @@ const mkRow = (role, actual, target, detail) => (action, { acts = false, extra =
 // transcript; the session directory is the phase-0 receipt's, which
 // tier-check.mjs reads itself when an entry omits it. Without a receipt of
 // this run, `<session>` stays a placeholder the controller fills in, as
-// `<file>` does — one batch file, one entry per held member (SKILL.md's
-// phase-2 tier check).
+// `<file>` does — one batch file, one entry per held member, the shape under
+// **The batch file is a JSON array, one entry per dispatched member** in
+// run-team/references/tick-rows.md.
 const tierCheckStep = (members, session) => "run ~/.fleet/bin/fleet-run tier-check.mjs --batch <file> with "
   + JSON.stringify(members.map((member) => (session ? { member } : { member, session: "<session>" })));
 

package/scripts/ledger.mjs

@@ -293,15 +293,16 @@ if (!cmd) die("usage: ledger.mjs [--file <path>] [--require-file] row|token|file
 // the documented convention IS one quoted argument, and `check` is the only
 // subcommand where it is: every caller that instructs running it spells it
 // `ledger.mjs check "<subject>"` (the finisher's deferred-finding filing duty,
-// review-and-fix's filing step), while run-team/SKILL.md's ledger section
-// spells the other three `filed <issue> <subject>`, `row <ticket> <text>` and
-// `ruled <pr> <decision>` — a bare multi-word tail, as did this file's own
-// usage strings for them. Applied there, the rule refused what the docs
-// prescribe: measured on the tree ahead of this narrowing, `filed 999 the
+// review-and-fix's filing step), while run-team/SKILL.md, as it stood when
+// this was measured, spelled the other three `filed <issue> <subject>`,
+// `row <ticket> <text>` and `ruled <pr> <decision>` — a bare multi-word tail,
+// as did this file's own usage strings for them. Applied there, the rule
+// refused what the docs prescribed: measured on the tree ahead of this
+// narrowing, `filed 999 the
 // --basee flag is unread`, `row 42 the --basee flag is unread` and `ruled 77
 // the --basee flag is unread` each exited 2, where the tree before this guard
 // existed answered all three at exit 0. The guard was ruled back to
-// `check` rather than respelling three conventions SKILL.md carries, two
+// `check` rather than respelling three conventions SKILL.md then carried, two
 // other tickets holding that file open.
 //
 // Stated here and nowhere else. This paragraph is the one copy of why
@@ -329,9 +330,9 @@ if (!cmd) die("usage: ledger.mjs [--file <path>] [--require-file] row|token|file
 // 2 now. Quoting the subject accepts it unchanged. The trade taken
 // is that this refusal is loud and recoverable where the wrong-subject
 // answer it replaces was silent. One residual of that trade is not this
-// file's to close: SKILL.md's ledger section spells `check <subject>`
-// unquoted inside the same entry that spells `filed <issue> <subject>`, where
-// the instructions that tell a caller to RUN it quote the subject.
+// file's to close: run-team/references/ledger.md's `filed and ruled` section
+// spells `check <subject>` unquoted, where the instructions that tell a caller
+// to RUN it quote the subject.
 //
 // Narrowed on `check` too, not closed: a lone stray with no subject beside it
 // is a one-element tail, so it is still taken as the subject and answered at
@@ -652,15 +653,15 @@ async function acquireLock() {
       // indistinguishable at this instant from a live reaper mid-takeover.
       // Naming the pid alone points an operator at a process that no longer
       // exists; naming `${REAP}` is what lets them find the file
-      // `run-team/SKILL.md`'s runbook tells them to remove by hand, once
-      // nothing is writing.
+      // run-team/references/ledger.md's Writer policy section tells them to
+      // remove by hand, once nothing is writing.
       if (dead) {
         die(`cannot lock ${file} — held by pid ${pid}, which is dead; ${REAP} is blocking its takeover — if nothing is currently writing, remove it by hand`);
       }
       // No pid at all is the other permanent wedge pid-lock.mjs's header describes: an
       // empty or partial `${LOCK}` whose writer died before writing its pid,
       // read as live forever by design. There is no process to point at, so
-      // name `${LOCK}` itself — the file the same runbook says to remove.
+      // name `${LOCK}` itself — the file the same Writer policy section says to remove.
       if (pid === null) {
         die(`cannot lock ${file} — ${LOCK} holds ${JSON.stringify(holder)}, not a pid, so it is never taken over — if nothing is currently writing, remove it by hand`);
       }
@@ -2087,8 +2088,9 @@ function runDispatch() {
     line = `#${member.number} ${member.name}`;
     data.rows.push(line);
   } else if (i !== -1) {
-    // A row `row` already wrote the live token into (SKILL.md's phase 2
-    // does) keeps it as it is rather than gaining a second copy.
+    // A row `row` already wrote the live token into (run-team/SKILL.md's
+    // `NEED resume` bullet records the row with `ledger.mjs row` before
+    // `ledger.mjs dispatch`) keeps it as it is rather than gaining a second copy.
     const row = data.rows[i];
     line = carries(row, member.name, true) ? row : `${row} · ${member.name}`;
     data.rows[i] = line;

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/staleness.mjs

@@ -125,8 +125,8 @@ if (!path) die("--path <path> is required");
 // both would refuse, the more specific wording wins, and nothing above here
 // has run a git call.
 //
-// One consequence the caller has to be told about, so run-team/SKILL.md says
-// it too: a needle that starts with `--`, given BARE, never reaches this
+// One consequence the caller has to be told about, so run-team/references/pull.md
+// says it too: a needle that starts with `--`, given BARE, never reaches this
 // script's question — `arg()` refuses it as a missing value, at exit 2, which
 // is the verdict that keeps the ticket in the queue. `--gone -- '<value>'`
 // (separatedNeedles() above) is the opt-in past that, one flag at a time.

package/scripts/tier-check.mjs

@@ -5,7 +5,7 @@
 // what omp's own record says it RESOLVED, for every member dispatched by
 // named definition. Not a lint — a refusal, run after every Pull's dispatch,
 // whose verdict on an implementer lands on the ledger, where fleet-tick.mjs
-// holds the next Pull until there is one (run-team/SKILL.md's phase 2).
+// holds the next Pull until there is one (run-team/SKILL.md, **The tier check**).
 //
 // Declared is the definition's own frontmatter — `model: "@<role>:<level>"`,
 // a fleet tier route, never a vendor id. Resolved is read back
@@ -48,10 +48,11 @@
 // A batch file, not one member: `--batch` takes a JSON array, and the
 // failure line — `member: declared <m>/<l> resolved <m>/<l>` — is printed
 // once per member that mismatched, not once per invocation. Under Pull,
-// run-team's phase 2 calls this after every Pull's dispatch with a batch of
-// one, the member just dispatched. See run-team/SKILL.md's phase-2 dispatch
-// paragraph for the batch file's exact entry shape and how the controller
-// obtains each field.
+// run-team runs this after every Pull's dispatch with a batch of one, the
+// member just dispatched (run-team/SKILL.md, **The tier check**). The batch
+// file's exact entry shape and how the controller obtains each field are under
+// **The batch file is a JSON array, one entry per dispatched member** in
+// run-team/references/tick-rows.md.
 //
 // An implementer (`impl-<N>`, ledger-grammar.mjs's name) is judged on the
 // ledger's terms, not the caller's: the definition it should have
@@ -194,12 +195,14 @@ export function formatOmpExpectation(r) {
 // held rather than replacing it, since `row` rewrites the whole line
 // (ledger.mjs's `data.rows[i] = line`) and a bare mismatch note would drop
 // `class=`, `KILLED` or `→ PR#` tokens a prior `row` call wrote for the same
-// ticket. Idempotent on the identical note: the documented loop is check,
-// fix, re-check (SKILL.md's "fix the definition or the dispatch and re-run
-// the check before continuing"), and a member that still mismatches for the
-// SAME reason on a later run must not grow the row a second time — a
-// DIFFERENT note (a changed pair) still appends, since that is new
-// information the row does not carry yet.
+// ticket. Idempotent on the identical note: the check can run again for a
+// member it already judged, while what clears a mismatch is a new member
+// (run-team/SKILL.md, **The tier check**: "Clear a mismatch by fixing the
+// definition or the dispatch and dispatching the replacement at the right
+// tier"), so a re-run that finds the SAME pair for the SAME member adds
+// nothing and must not grow the row a second time — a DIFFERENT note (a
+// changed pair, or the replacement's own line, which names the replacement)
+// still appends, since that is new information the row does not carry yet.
 export function appendedLedgerText(existingText, mismatchNote) {
   const trimmed = String(existingText ?? "").trim();
   if (!trimmed) return mismatchNote;

package/scripts/tier-outcomes.mjs

@@ -92,7 +92,8 @@ const LEDGER_SCRIPT = join(SCRIPT_DIR, "ledger.mjs");
 // ---------------------------------------------------------------------------
 
 // APPENDED TO, never inserted into: every awk read-out in the file's header
-// and in run-team/SKILL.md indexes by position.
+// and in run-team/references/pull.md (**Accumulate per PR, never conclude a
+// tier result inside one run**) indexes by position.
 export const COLUMNS = Object.freeze([
   "run_date", "pr", "ticket", "class", "tier", "closed_own_ticket",
   "minted_false_claim", "note", "sizing", "profile", "loc", "files",

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/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