@cohortapp/agent-sdk 2.17.0 → 2.18.5

package/scripts/fleet/rollout.mjs

@@ -0,0 +1,1151 @@
+#!/usr/bin/env node
+/**
+ * scripts/fleet/rollout.mjs — publish one SDK version to the fleet, then PROVE
+ * every seat took it.
+ *
+ * ── WHY THIS EXISTS ───────────────────────────────────────────────────────────
+ * Propagation across the fleet has exactly one live path: publish to npm, and
+ * each seat's hourly `scripts/local-triggers/autoupdate.sh` installs @latest.
+ * There is no fan-out, no ssh, no push. That path is fine — what was missing is
+ * the OPERATOR half of it:
+ *
+ *   · the publish is gated on facts nobody re-checked at the moment of publish
+ *     (auth, a clean tree, a pushed tag, green check+test), so "I ran the tests
+ *     an hour ago" stood in for "the tests pass on the bytes I am about to
+ *     publish";
+ *   · and nothing ever ASKED whether the fleet took it. One seat ran six days
+ *     behind (2026-09-15..21) while its own log said "up to date" every hour;
+ *     the org noticed nothing, because nobody was looking at the fleet's
+ *     versions as a set.
+ *
+ * So: one command, three stages, and a non-zero exit while any seat is behind.
+ *
+ *   1. PRE-FLIGHT  — refuse unless `npm whoami` succeeds, the local version is
+ *      strictly greater than the registry's @latest, the working tree is clean,
+ *      the version's tag exists locally AND on the remote, and `npm run check`
+ *      + `npm test` pass. The gates are RE-RUN here; a log from an earlier run
+ *      is not evidence about the bytes being published.
+ *   2. PUBLISH     — `npm publish`, then poll the registry until @latest IS the
+ *      new version. A 404/stale read in the first seconds after a publish is
+ *      REGISTRY READ LAG, not failure (this has been mistaken for a failed
+ *      publish before), so the poll retries on a stale answer and only fails
+ *      when the deadline passes.
+ *   3. VERIFY      — poll the org directory (hq's server-stamped presence-beat
+ *      derivation) for every fleet seat until each reports the new version or
+ *      the deadline passes. A per-seat table prints every round; the run exits
+ *      non-zero naming exactly which seats are behind.
+ *
+ * ── WHAT IT WILL NEVER DO ─────────────────────────────────────────────────────
+ * NO SSH. Not as a fallback, not with `--force`, not "just to check". Seats are
+ * updated by their own autoupdater; this tool publishes and then OBSERVES. It
+ * also takes NO credential as an argument or environment variable of its own:
+ * npm auth comes from the operator's own `npm login`, org auth from the agent
+ * config the rest of lib/org reads.
+ *
+ * Both promises are enforced twice, because a source-reading test can only see
+ * the shapes it was taught: {@link commandRefusal} refuses any command but npm
+ * and git at RUNTIME, on the value, and {@link parseArgs} drops everything
+ * after the first `=` before any error string is built, so no branch can echo a
+ * credential back. The structural tests in scripts/fleet/rollout.test.mjs sit
+ * on top of those, pinning the import surface of node:child_process so nothing
+ * can spawn a process without going through the one guarded seam.
+ *
+ * ── `unverifiable` NOW MEANS THE SEAT IS SILENT, NOT THE READ ─────────────────
+ * Stage 3 wants each seat's RUNNING version. This used to be unanswerable from
+ * outside the machines: the beat carried `machine.sdkVersion` and hq persisted
+ * it, but `directory` (src/server/rpc/reads.ts#directory) selected five
+ * AgentStatus columns and `machine` was not among them — so every seat in a
+ * perfect fleet read `unverifiable` and the run exited 3. That read now
+ * projects the identity fields (`sdkVersion`, `sdkVersionRunning`, `hostname`),
+ * narrowed deliberately: the rest of `machine` carries per-seat spend and a
+ * private-network address, which stay behind `fleet.view`.
+ *
+ * So `unverifiable` has changed meaning, and the new meaning is a finding. A
+ * seat reads unverifiable when IT reports no version — which, in this fleet,
+ * means its copied tree predates SDK 2.12, the release that first put identity
+ * on the beat. The field that would announce the staleness is the field the
+ * staleness removes, so such a seat cannot be told from a healthy one by its
+ * version alone; what gives it away is that its beat also carries no
+ * `frontDoor`/`sessionLive`, which every 2.12+ collector emits unconditionally.
+ * Either way it still exits non-zero: an unverified seat is not a verified one,
+ * and "it beat, so it must be current" is exactly the substitution that hid a
+ * six-day-stale seat.
+ *
+ * INSTALLED IS NOT RUNNING. {@link seatVersions} keeps the two apart and judges
+ * on `running` whenever the seat reports it (`machine.daemon.sdkVersion`, SDK
+ * 2.18+), because autoupdate installs into node_modules while the old daemon
+ * keeps executing the code it booted on. A seat whose two disagree is `stale`.
+ *
+ * ── USAGE ─────────────────────────────────────────────────────────────────────
+ *     node scripts/fleet/rollout.mjs [--dry-run] [--deadline <min>]
+ *                                    [--interval <s>] [--seat-window <min>]
+ *                                    [--agent-root <path>] [--json] [--help]
+ *
+ * `--dry-run` does everything except the publish itself (pre-flight gates run
+ * for real, including check+test) and then verifies propagation against the
+ * version in package.json — which is how you see, today, exactly which seats
+ * would still be behind.
+ *
+ * Idempotent: when the registry's @latest already equals the local version the
+ * run prints "already published, verifying propagation" and goes straight to
+ * stage 3. Re-running it is the supported way to watch a rollout land.
+ *
+ * Exit codes: 0 verified · 1 pre-flight refusal · 2 publish/registry failure ·
+ * 3 propagation deadline passed with seats behind or unverifiable.
+ *
+ * @module scripts/fleet/rollout
+ */
+
+"use strict";
+
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { dirname, join, resolve as resolvePath } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const REPO_ROOT = resolvePath(dirname(__filename), "..", "..");
+
+/** Package this tool publishes. Read from package.json, never hardcoded. */
+export function readLocalPackage(repoRoot = REPO_ROOT) {
+  const doc = JSON.parse(readFileSync(join(repoRoot, "package.json"), "utf-8"));
+  return { name: String(doc.name || ""), version: String(doc.version || "") };
+}
+
+// ---------------------------------------------------------------------------
+// PURE: version comparison
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse a semver-ish string into comparable parts. Tolerant: a leading `v`, and
+ * missing minor/patch, are accepted; anything unparseable yields null so the
+ * caller can refuse rather than guess.
+ * @param {string} v
+ * @returns {{major:number,minor:number,patch:number,pre:string[]}|null}
+ */
+export function parseVersion(v) {
+  const s = String(v == null ? "" : v).trim().replace(/^v/i, "");
+  const m = /^(\d+)(?:\.(\d+))?(?:\.(\d+))?(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/.exec(s);
+  if (!m) return null;
+  return {
+    major: Number(m[1]),
+    minor: Number(m[2] || 0),
+    patch: Number(m[3] || 0),
+    pre: m[4] ? m[4].split(".") : [],
+  };
+}
+
+/**
+ * Compare two versions: -1 (a<b), 0 (equal), 1 (a>b). An unparseable version
+ * sorts BELOW a parseable one (and two unparseable ones compare equal), so a
+ * garbage registry answer can never read as "newer than mine" and wave a
+ * publish through.
+ * @param {string} a
+ * @param {string} b
+ * @returns {-1|0|1}
+ */
+export function compareVersions(a, b) {
+  const pa = parseVersion(a);
+  const pb = parseVersion(b);
+  if (!pa && !pb) return 0;
+  if (!pa) return -1;
+  if (!pb) return 1;
+  for (const k of ["major", "minor", "patch"]) {
+    if (pa[k] !== pb[k]) return pa[k] < pb[k] ? -1 : 1;
+  }
+  // 1.0.0-rc.1 < 1.0.0 : a release with no prerelease outranks one with.
+  if (pa.pre.length === 0 && pb.pre.length === 0) return 0;
+  if (pa.pre.length === 0) return 1;
+  if (pb.pre.length === 0) return -1;
+  const n = Math.max(pa.pre.length, pb.pre.length);
+  for (let i = 0; i < n; i++) {
+    const x = pa.pre[i];
+    const y = pb.pre[i];
+    if (x === undefined) return -1;
+    if (y === undefined) return 1;
+    const xn = /^\d+$/.test(x);
+    const yn = /^\d+$/.test(y);
+    if (xn && yn) {
+      if (Number(x) !== Number(y)) return Number(x) < Number(y) ? -1 : 1;
+    } else if (x !== y) {
+      return x < y ? -1 : 1;
+    }
+  }
+  return 0;
+}
+
+/** True when `a` is a strictly greater version than `b`. */
+export function isNewer(a, b) {
+  return compareVersions(a, b) === 1;
+}
+
+// ---------------------------------------------------------------------------
+// PURE: pre-flight verdict
+// ---------------------------------------------------------------------------
+
+/**
+ * Decide whether a publish may proceed, from already-gathered FACTS. Pure: it
+ * runs nothing, so every refusal is unit-testable and the order of refusals is
+ * stable (cheapest, most-likely-human-fixable first).
+ *
+ * @param {object} f
+ * @param {{ok:boolean, user?:string, error?:string}} f.whoami
+ * @param {string} f.localVersion
+ * @param {{ok:boolean, version:string|null, error?:string}} f.registryLatest
+ * @param {{clean:boolean, dirty:string[]}} f.worktree
+ * @param {{local:boolean, remote:boolean, name:string}} f.tag
+ * @param {{ok:boolean, code:number}} f.check
+ * @param {{ok:boolean, code:number}} f.test
+ * @returns {{ok:boolean, refusals:string[]}}
+ */
+export function evaluatePreflight(f) {
+  const refusals = [];
+  const local = String(f.localVersion || "");
+
+  if (!f.whoami || !f.whoami.ok) {
+    refusals.push(
+      `npm auth: \`npm whoami\` failed${f.whoami && f.whoami.error ? ` (${f.whoami.error})` : ""} — run \`npm login\` as the publisher. This tool never accepts a token as an argument.`
+    );
+  }
+
+  if (!parseVersion(local)) {
+    refusals.push(`local version: package.json version ${JSON.stringify(local)} is not a version this tool can compare.`);
+  } else if (!f.registryLatest || !f.registryLatest.ok) {
+    refusals.push(
+      `registry read: could not read the published @latest${f.registryLatest && f.registryLatest.error ? ` (${f.registryLatest.error})` : ""} — refusing to publish blind.`
+    );
+  } else if (!isNewer(local, f.registryLatest.version)) {
+    refusals.push(
+      `version: local ${local} is not greater than the registry's @latest ${f.registryLatest.version || "(none)"} — bump package.json first.`
+    );
+  }
+
+  if (!f.worktree || !f.worktree.clean) {
+    const dirty = (f.worktree && f.worktree.dirty) || [];
+    const shown = dirty.slice(0, 5).join(", ");
+    refusals.push(
+      `working tree: ${dirty.length} uncommitted path(s)${shown ? ` (${shown}${dirty.length > 5 ? ", …" : ""})` : ""} — publish only what is committed.`
+    );
+  }
+
+  if (!f.tag || !f.tag.local) {
+    refusals.push(`tag: ${f.tag && f.tag.name ? f.tag.name : `v${local}`} does not exist locally — tag the release commit.`);
+  } else if (!f.tag.remote) {
+    refusals.push(`tag: ${f.tag.name} is not on the remote — \`git push origin ${f.tag.name}\` so the published bytes stay findable.`);
+  }
+
+  for (const g of [{ k: "check", cmd: "npm run check" }, { k: "test", cmd: "npm test" }]) {
+    const r = f[g.k];
+    if (!r) { refusals.push(`gate: \`${g.cmd}\` was not run.`); continue; }
+    if (r.ok) continue;
+    // Could not run vs ran and failed: the operator's next move differs, so the
+    // refusal must not blur them (ENOBUFS once made a passing suite read as a
+    // failing one).
+    if (r.ran === false) refusals.push(`gate: \`${g.cmd}\` could not be run (${r.failure || "unknown"}) — this is NOT a test failure; the harness could not capture its output.`);
+    else refusals.push(`gate: \`${g.cmd}\` failed (exit ${r.code}).`);
+  }
+
+  return { ok: refusals.length === 0, refusals };
+}
+
+/**
+ * One gate's line in the pre-flight table. Pure.
+ *
+ * Three outcomes, not two: passed, ran and failed, or never got to answer.
+ * The third used to print as the second.
+ */
+export function gateLine(r) {
+  if (!r) return "not run";
+  if (r.ok) return "pass";
+  if (r.ran === false) return `COULD NOT RUN (${r.failure || "unknown"}) — not a test failure`;
+  return `FAILED (exit ${r.code})`;
+}
+
+/**
+ * A note about paths the GATES themselves dirtied. `npm test` appends to a
+ * tracked runtime ledger (.claude-flow/policy/state.json), so a second run in a
+ * row would refuse on a file the first run wrote. The clean-tree gate is NOT
+ * weakened for this — publishing a tree you cannot describe stays a refusal —
+ * the run just says which paths are the gates' own leavings so the operator
+ * reverts them instead of hunting them. Pure.
+ *
+ * @param {string[]} before dirty paths before the gates ran
+ * @param {string[]} after  dirty paths after
+ * @returns {string|null}
+ */
+export function gateDirtNote(before, after) {
+  const was = new Set(before || []);
+  const added = (after || []).filter((p) => !was.has(p));
+  if (added.length === 0) return null;
+  return (
+    `the gates just dirtied ${added.length} tracked path(s): ${added.join(", ")}. ` +
+    `They are runtime artefacts, not your change — \`git checkout --\` them before re-running, ` +
+    `or the clean-tree gate will refuse the next run.`
+  );
+}
+
+// ---------------------------------------------------------------------------
+// PURE: registry read-lag retry decision
+// ---------------------------------------------------------------------------
+
+/**
+ * Decide what to do with one post-publish registry read. The registry is
+ * eventually consistent: for a few seconds after a successful publish a read
+ * can 404 the version or still answer with the PREVIOUS @latest. That is READ
+ * LAG, not a failed publish — treating it as failure has previously sent people
+ * hunting a publish that had in fact worked.
+ *
+ * @param {object} o
+ * @param {number} o.attempt          1-based attempt number
+ * @param {number} o.maxAttempts
+ * @param {string} o.target           version just published
+ * @param {{ok:boolean, version:string|null, error?:string}} o.read
+ * @returns {{action:"done"|"retry"|"fail", reason:string}}
+ */
+export function readLagDecision(o) {
+  const { attempt, maxAttempts, target, read } = o;
+  if (read && read.ok && read.version && compareVersions(read.version, target) === 0) {
+    return { action: "done", reason: `registry @latest is ${target}` };
+  }
+  const why = !read || !read.ok
+    ? `registry read failed (${(read && read.error) || "unknown"})`
+    : `registry @latest is ${read.version || "(none)"}, not ${target}`;
+  if (attempt < maxAttempts) return { action: "retry", reason: `${why} — read lag, retrying` };
+  return { action: "fail", reason: `${why} after ${maxAttempts} attempt(s)` };
+}
+
+// ---------------------------------------------------------------------------
+// PURE: seats, versions, staleness table
+// ---------------------------------------------------------------------------
+
+/** Default window in which a beat makes a member a FLEET SEAT (ms). */
+export const DEFAULT_SEAT_WINDOW_MS = 30 * 60 * 1000;
+
+/** First non-blank string among the candidates, trimmed; null when none is. */
+function firstString(candidates) {
+  for (const c of candidates) {
+    if (typeof c === "string" && c.trim()) return c.trim();
+  }
+  return null;
+}
+
+/**
+ * The two versions a directory entry reports, kept APART.
+ *
+ *   installed — what `npm install` put on the seat (`machine.sdkVersion`)
+ *   running   — what the beating process actually executes
+ *               (`machine.daemon.sdkVersion`, SDK 2.18+)
+ *
+ * They are different facts and a rollout is about the second one. autoupdate
+ * installs into node_modules while the old daemon keeps executing the code it
+ * booted on, and a hand-run `maestro upgrade` never restarts the daemon at all
+ * — so "installed" is where a propagation check goes wrong quietly: the seat is
+ * carrying the new package and running the old one, and a checker that only
+ * reads `installed` calls that done.
+ *
+ * `version` is therefore RUNNING when the seat reports it, and falls back to
+ * installed only when it does not — with `basis` naming which, so no reader has
+ * to infer it. A seat whose two disagree is `stale`, correctly: it has the fix
+ * on disk and is not running it.
+ *
+ * Several shapes are accepted because the field has travelled: the directory
+ * read now projects it as `status.sdkVersion` / `status.sdkVersionRunning`,
+ * `presence.fleetVersions` returns `installed` / `running`, and the raw
+ * `machine` record is what both are read from.
+ *
+ * EXPECT EVERY ROW TO SAY `(installed)` UNTIL 2.18.x IS ON THE SEATS. `running`
+ * comes from `machine.daemon`, which only an SDK 2.18+ daemon emits, and no
+ * seat in the fleet writes that block today — so `basis` is `"installed"` for
+ * every row and the table prints the suffix everywhere. That is the check
+ * reporting honestly about what it can see, NOT a defect and NOT a reason to
+ * drop the suffix: the suffix disappears seat by seat as the daemons restart
+ * onto a version that reports what it is running, and a table that went quiet
+ * about the difference would be back to the failure this file exists to catch.
+ *
+ * @param {object} entry
+ * @returns {{installed:string|null, running:string|null, version:string|null, basis:"running"|"installed"|null}}
+ */
+export function seatVersions(entry) {
+  const e = entry && typeof entry === "object" ? entry : {};
+  const st = (e.status && typeof e.status === "object" && e.status) || {};
+  const mach = (st.machine && typeof st.machine === "object" && st.machine) || (e.machine && typeof e.machine === "object" && e.machine) || {};
+  const daemon = (mach.daemon && typeof mach.daemon === "object" && mach.daemon) || {};
+
+  const installed = firstString([
+    mach.sdkVersion,
+    st.sdkVersion,
+    e.presence && e.presence.sdkVersion,
+    e.installed,
+    e.sdkVersion,
+  ]);
+  const running = firstString([
+    daemon.sdkVersion,
+    st.sdkVersionRunning,
+    e.running,
+  ]);
+  const version = running || installed;
+  return { installed, running, version, basis: version === null ? null : running ? "running" : "installed" };
+}
+
+/**
+ * The single version a seat is judged on, or null when the read carries none.
+ * Kept as its own export because it is the whole of what `classifySeat` needs;
+ * {@link seatVersions} is what a caller reaches for when it wants to SAY which
+ * of the two it got.
+ * @param {object} entry
+ * @returns {string|null}
+ */
+export function seatVersion(entry) {
+  return seatVersions(entry).version;
+}
+
+/**
+ * Turn a directory `members` array into the rollout's seat rows. A member is a
+ * SEAT when it is an AI colleague whose server-stamped beat is inside
+ * `seatWindowMs`: an agent with no machine (LLM-responder mode) never takes an
+ * SDK version and must not be counted as behind. Pure.
+ *
+ * `readCarriesVersionField` is the tool's answer to "am I blind, or is the
+ * fleet silent?" — the two produce an identical table and want opposite
+ * responses. It is true when ANY member's status object OWNS an sdkVersion key,
+ * even set to null: a read that projects the field says so by carrying it,
+ * whatever the value. Without this the tool would have to assert a cause it
+ * cannot see, and it would be wrong on whichever side of the hq deploy it was
+ * not written for.
+ *
+ * @param {object[]} members
+ * @param {{seatWindowMs?:number}} [o]
+ * @returns {{seats:object[], nonSeats:object[], readCarriesVersionField:boolean}}
+ */
+export function toSeats(members, o = {}) {
+  const windowMs = Number.isFinite(o.seatWindowMs) ? o.seatWindowMs : DEFAULT_SEAT_WINDOW_MS;
+  const seats = [];
+  const nonSeats = [];
+  let readCarriesVersionField = false;
+  for (const m of Array.isArray(members) ? members : []) {
+    if (!m || typeof m !== "object") continue;
+    if (m.kind && m.kind !== "AI_AGENT") continue;
+    const st = m.status;
+    if (st && typeof st === "object" && ("sdkVersion" in st || "sdkVersionRunning" in st || (st.machine && typeof st.machine === "object"))) {
+      readCarriesVersionField = true;
+    }
+    const p = m.presence && typeof m.presence === "object" ? m.presence : null;
+    const beatMs = p && Number.isFinite(p.lastBeatMs) ? p.lastBeatMs : null;
+    const row = {
+      id: String(m.id || ""),
+      slug: String(m.slug || ""),
+      name: String(m.displayName || m.name || m.slug || m.id || ""),
+      lane: (p && p.lane) || "unknown",
+      detail: (p && p.detail) || "",
+      lastBeatMs: beatMs,
+      ...seatVersions(m),
+    };
+    if (beatMs !== null && beatMs <= windowMs) seats.push(row);
+    else nonSeats.push(row);
+  }
+  const bySlug = (a, b) => (a.slug < b.slug ? -1 : a.slug > b.slug ? 1 : 0);
+  return { seats: seats.sort(bySlug), nonSeats: nonSeats.sort(bySlug), readCarriesVersionField };
+}
+
+/**
+ * Verdict for one seat against the target version. Pure.
+ *   current      — reported version equals the target
+ *   stale        — reported a different (older or newer) version
+ *   unverifiable — beating, but the read carries no version at all
+ * @param {object} seat
+ * @param {string} target
+ * @returns {"current"|"stale"|"unverifiable"}
+ */
+export function classifySeat(seat, target) {
+  const v = seat && seat.version;
+  if (!v) return "unverifiable";
+  return compareVersions(v, target) === 0 ? "current" : "stale";
+}
+
+/**
+ * Summarise a fleet read against the target. `done` is true only when every
+ * seat is `current` — an unverifiable seat is never counted as done. Pure.
+ * @param {{seats:object[], nonSeats:object[]}} fleet
+ * @param {string} target
+ * @returns {object}
+ */
+export function summarise(fleet, target) {
+  const rows = (fleet.seats || []).map((s) => ({ ...s, verdict: classifySeat(s, target) }));
+  const counts = { current: 0, stale: 0, unverifiable: 0 };
+  for (const r of rows) counts[r.verdict] += 1;
+  return {
+    target,
+    rows,
+    counts,
+    nonSeats: fleet.nonSeats || [],
+    stale: rows.filter((r) => r.verdict === "stale"),
+    unverifiable: rows.filter((r) => r.verdict === "unverifiable"),
+    readCarriesVersionField: fleet.readCarriesVersionField === true,
+    done: rows.length > 0 && counts.current === rows.length,
+  };
+}
+
+/** Human "27ms"/"18s"/"4m"/"2h" age. */
+export function ageLabel(ms) {
+  if (!Number.isFinite(ms)) return "never";
+  if (ms < 1000) return `${Math.round(ms)}ms`;
+  const s = Math.round(ms / 1000);
+  if (s < 90) return `${s}s`;
+  const m = Math.round(s / 60);
+  if (m < 90) return `${m}m`;
+  const h = Math.round(m / 60);
+  if (h < 48) return `${h}h`;
+  return `${Math.round(h / 24)}d`;
+}
+
+/**
+ * Render the per-seat table. Pure (returns a string; prints nothing).
+ * @param {object} summary  from {@link summarise}
+ * @param {{round?:number, elapsedMs?:number}} [o]
+ * @returns {string}
+ */
+export function renderSeatTable(summary, o = {}) {
+  const head = ["SEAT", "ID", "BEAT", "REPORTS", "VERDICT"];
+  const body = summary.rows.map((r) => [
+    r.name,
+    r.slug,
+    ageLabel(r.lastBeatMs),
+    r.version ? (r.basis === "installed" ? `${r.version} (installed)` : r.version) : "unknown",
+    r.verdict,
+  ]);
+  const widths = head.map((h, i) => Math.max(h.length, ...body.map((row) => row[i].length), 0));
+  const line = (cells) => cells.map((c, i) => c.padEnd(widths[i])).join("  ").trimEnd();
+  const out = [];
+  const stamp = [
+    o.round ? `round ${o.round}` : null,
+    Number.isFinite(o.elapsedMs) ? `${ageLabel(o.elapsedMs)} elapsed` : null,
+  ].filter(Boolean).join(" · ");
+  out.push(`Fleet vs ${summary.target}${stamp ? `  (${stamp})` : ""}`);
+  out.push(line(head));
+  out.push(widths.map((w) => "-".repeat(w)).join("  "));
+  for (const row of body) out.push(line(row));
+  out.push(
+    `${summary.rows.length} seat(s): ${summary.counts.current} current · ${summary.counts.stale} stale · ${summary.counts.unverifiable} unverifiable` +
+      (summary.nonSeats.length ? `  (+${summary.nonSeats.length} agent(s) with no beating machine — not rollout targets)` : "")
+  );
+  return out.join("\n");
+}
+
+/** The closing sentence naming exactly which seats are behind. Pure. */
+export function renderVerdict(summary) {
+  if (summary.done) return `All ${summary.rows.length} seat(s) report ${summary.target}.`;
+  const parts = [];
+  if (summary.stale.length) {
+    parts.push(
+      `${summary.stale.length} seat(s) still behind ${summary.target}: ` +
+        summary.stale.map((r) => `${r.name} (${r.slug}, reports ${r.version})`).join(", ")
+    );
+  }
+  if (summary.unverifiable.length) {
+    parts.push(
+      `${summary.unverifiable.length} seat(s) could not be verified — the org read carries no sdkVersion: ` +
+        summary.unverifiable.map((r) => `${r.name} (${r.slug})`).join(", ")
+    );
+  }
+  if (!summary.rows.length) parts.push("no beating seats found in the org directory — nothing to verify.");
+  return parts.join("\n");
+}
+
+/**
+ * What stage 3's exit code will be, and WHY — as data, so a caller can tell the
+ * three very different things a `3` means apart.
+ *
+ * This exists because of an asymmetry that is easy to mistake for a bug. An
+ * unverified seat is deliberately NOT counted as done, so a run can exit 3 with
+ * no seat known to be behind. That is the honest call and it is not going to
+ * change: "it beat, so it must be current" is exactly the substitution that hid
+ * a six-day-stale seat.
+ *
+ * What changed is why a seat goes unverified. It used to be every seat, because
+ * hq's directory read did not project the column; that read carries the
+ * identity fields now, so `unverifiable` is a statement about THE SEAT — it
+ * reports no version, which means a copied tree older than SDK 2.12. A caller
+ * that wants to branch on "is anything behind" still reads `reason`, not the
+ * exit code: `behind` and `unverifiable` are different problems with different
+ * fixes, and only the first is answered by waiting.
+ *
+ * Pure.
+ *
+ * @param {ReturnType<typeof summarise>|null|undefined} summary
+ * @returns {{code:number, reason:"verified"|"behind"|"unverifiable"|"empty-fleet"|"no-fleet-read", note:string|null}}
+ */
+export function propagationOutcome(summary) {
+  if (!summary || !Array.isArray(summary.rows)) {
+    return {
+      code: 3,
+      reason: "no-fleet-read",
+      note: "No successful org read before the deadline — this says nothing about the fleet's versions.",
+    };
+  }
+  if (summary.done) return { code: 0, reason: "verified", note: null };
+  if (!summary.rows.length) {
+    return {
+      code: 3,
+      reason: "empty-fleet",
+      note: "No beating seats were found, so nothing was verified. An empty fleet is never 'done'.",
+    };
+  }
+  if (summary.counts.stale === 0 && summary.counts.unverifiable > 0) {
+    const head = "Exit 3 here does NOT mean a seat is behind — no seat is known to be. ";
+    const seatIsSilent =
+      "The directory read DOES project sdkVersion and these seats carry none, so the silence is theirs: a " +
+      "copied tree older than SDK 2.12, the release that first put the field on the beat. Waiting will not fix " +
+      "that — the code that would report the version is the code that is missing. Confirm it by checking " +
+      "whether those seats' beats also lack frontDoor/sessionLive (every 2.12+ collector emits those " +
+      "unconditionally); if so, the seat's autoupdater has not merged a release in weeks and someone has to " +
+      "reach the machine.";
+    const readIsBlind =
+      "No member in this read carried an sdkVersion field AT ALL — not even null — so the blindness is the " +
+      "READ's, not the fleet's, and this run says nothing about any seat's version. The projection lives in " +
+      "hq's src/server/rpc/reads.ts#directory; an hq old enough to predate it, or one deployed behind the " +
+      "branch that added it, answers exactly like this. Check what hq is actually serving before reading " +
+      "anything into the table above.";
+    return {
+      code: 3,
+      reason: "unverifiable",
+      note: head + (summary.readCarriesVersionField ? seatIsSilent : readIsBlind),
+    };
+  }
+  return {
+    code: 3,
+    reason: "behind",
+    note: `${summary.counts.stale} seat(s) are provably behind ${summary.target}.`,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// EFFECTS: shelling out, reading the org, sleeping
+// ---------------------------------------------------------------------------
+
+/**
+ * The only commands this tool may ever run. An allowlist, not a denylist: a
+ * denylist has to predict the name of the thing it is trying to stop, and
+ * `ssh` has plenty of spellings (`/usr/bin/ssh`, `sshpass`, a wrapper on PATH).
+ */
+export const ROLLOUT_ALLOWED_COMMANDS = ["npm", "git"];
+
+/**
+ * Commands this tool must never run. Remote execution is not a fallback. Kept
+ * as an explicit list because the refusal message should be able to say "this
+ * looks like remote execution" rather than only "not on the allowlist".
+ */
+export const ROLLOUT_FORBIDDEN_COMMANDS = ["ssh", "scp", "rsync", "sshpass", "expect"];
+
+/**
+ * Refuse any command that is not on {@link ROLLOUT_ALLOWED_COMMANDS}. Pure —
+ * returns the refusal rather than throwing it, so it can be tested without a
+ * process.
+ *
+ * This is the guard that actually holds. The structural test over this file's
+ * source can only see call sites it recognises, and a call site can be written
+ * not to look like one (`execSync("ssh …")`, `deps.exec(cmd, [])` where `cmd`
+ * is a variable). Everything still has to come through here to reach a process,
+ * so the check lives here, at runtime, on the value.
+ *
+ * @param {unknown} cmd
+ * @returns {string|null} the refusal, or null when the command is allowed
+ */
+export function commandRefusal(cmd) {
+  if (typeof cmd !== "string" || !cmd.length) return `refusing to run a non-string command (${typeof cmd})`;
+  if (ROLLOUT_ALLOWED_COMMANDS.includes(cmd)) return null;
+  const base = cmd.split("/").pop() || cmd;
+  if (ROLLOUT_FORBIDDEN_COMMANDS.includes(base) || /\bssh\b/.test(cmd)) {
+    return `refusing to run "${cmd}": this tool never executes anything remotely — seats update themselves.`;
+  }
+  return `refusing to run "${cmd}": only ${ROLLOUT_ALLOWED_COMMANDS.join(" and ")} may be run from here.`;
+}
+
+/**
+ * Run a command, capturing output. The only process-spawning seam in this file;
+ * {@link commandRefusal} is applied to every command before it can reach a
+ * process, and a test asserts no call site violates it either.
+ *
+ * A refused command THROWS rather than returning `{ok:false}`: a call site
+ * asking for `ssh` is a defect in this file, not an expected failure of a
+ * rollout, and must not be swallowed by a caller's error handling.
+ */
+export function runCommand(cmd, args, o = {}) {
+  const refusal = commandRefusal(cmd);
+  if (refusal) throw new Error(`rollout: ${refusal}`);
+  const r = spawnSync(cmd, args, {
+    cwd: o.cwd || REPO_ROOT,
+    encoding: "utf-8",
+    stdio: o.inherit ? "inherit" : "pipe",
+    env: process.env,
+    // Node's default maxBuffer is 1 MiB and `npm test` prints ~1.04 MiB of TAP.
+    // Exceeding it makes spawnSync KILL the child and report status null — the
+    // green suite arrived here as "npm test FAILED (exit -1)" and refused a
+    // sound release. A gate that cannot be run must never read as a gate that
+    // failed, so this is raised well past any plausible gate and the two
+    // outcomes are reported separately below.
+    maxBuffer: o.maxBuffer ?? 256 * 1024 * 1024,
+  });
+  // `error` set (ENOBUFS, ENOENT, a signal) means the command did not get to
+  // answer. `ran:false` says so; callers must not read it as a failing gate.
+  return {
+    ok: !r.error && r.status === 0,
+    ran: !r.error,
+    failure: r.error ? r.error.code || r.error.message : null,
+    code: r.status == null ? -1 : r.status,
+    stdout: (r.stdout || "").trim(),
+    stderr: (r.stderr || "").trim(),
+  };
+}
+
+const defaultDeps = {
+  exec: runCommand,
+  sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
+  now: () => Date.now(),
+  log: (s) => process.stdout.write(`${s}\n`),
+};
+
+/** `npm whoami` → {ok,user?,error?}. Never prints or returns a token. */
+export function npmWhoami(deps) {
+  const r = deps.exec("npm", ["whoami"]);
+  if (r.ok && r.stdout) return { ok: true, user: r.stdout.split("\n").pop().trim() };
+  const err = (r.stderr || r.stdout || "").split("\n").find((l) => /E401|401|ENEEDAUTH|error/i.test(l));
+  return { ok: false, error: (err || `exit ${r.code}`).trim() };
+}
+
+/**
+ * `npm view <pkg> version` → {ok,version,error?}. Needs no auth.
+ *
+ * `--prefer-online` is load-bearing, not tidiness. npm caches registry metadata
+ * and revalidates it lazily, so straight after a successful publish this read
+ * kept answering with the PREVIOUS version from the local cache: 2.18.4 went to
+ * the registry, and all ten read-lag retries reported 2.17.0 from ~/.npm while
+ * a fresh shell already saw 2.18.4. The run then declared the publish stage
+ * failed on a package it had just published correctly. The retry loop cannot
+ * out-wait a cache that is never re-fetched.
+ */
+export function npmLatest(pkg, deps) {
+  const r = deps.exec("npm", ["view", "--prefer-online", pkg, "version"]);
+  if (r.ok && r.stdout) return { ok: true, version: r.stdout.split("\n").pop().trim() };
+  return { ok: false, version: null, error: ((r.stderr || r.stdout || `exit ${r.code}`).split("\n")[0] || "").trim() };
+}
+
+/** Working-tree cleanliness from `git status --porcelain`. */
+export function gitWorktree(deps) {
+  const r = deps.exec("git", ["status", "--porcelain"]);
+  if (!r.ok) return { clean: false, dirty: [`git status failed: ${r.stderr || r.code}`] };
+  const dirty = r.stdout.split("\n").map((l) => l.trim()).filter(Boolean);
+  return { clean: dirty.length === 0, dirty };
+}
+
+/** Whether `v<version>` exists locally and on the remote. */
+export function gitTag(version, deps) {
+  const name = `v${version}`;
+  const local = deps.exec("git", ["tag", "--list", name]);
+  const remote = deps.exec("git", ["ls-remote", "--tags", "origin", name]);
+  return {
+    name,
+    local: local.ok && local.stdout.includes(name),
+    remote: remote.ok && remote.stdout.includes(`refs/tags/${name}`),
+  };
+}
+
+/**
+ * Read the fleet from the org directory — hq's server-stamped presence
+ * derivation, i.e. the same beats the human /fleet page paints. Fail-soft:
+ * a failed read yields `ok:false` and the caller keeps polling rather than
+ * declaring the fleet dark.
+ *
+ * @param {object} o - { agentRoot, client?, seatWindowMs? }
+ * @returns {Promise<{ok:boolean, error?:string, seats:object[], nonSeats:object[]}>}
+ */
+/**
+ * Which enrolled agent directory this run reads the org through.
+ *
+ * This script lives in the SDK repo, which is NOT an agent seat: it has no
+ * config/org.yaml. Run from ~/maestro with nothing set, `loadOrgConfig(undefined)`
+ * threw `The "path" argument must be of type string`, the verify loop treated
+ * that as a transient read failure, and it retried ninety times over two hours
+ * before reporting nothing — about a fleet that had in fact taken the release.
+ *
+ * Order: an explicit --agent-root / AGENT_ROOT / AGENT_DIR, then the cwd if it
+ * is itself a seat, then the one enrolled directory under $HOME. Several
+ * candidates is ambiguity, not a default: it says so and asks for the flag.
+ *
+ * @returns {{ok:true, root:string, how:string} | {ok:false, error:string}}
+ */
+export function resolveAgentRoot(explicit, deps = {}) {
+  const exists = deps.exists || ((p) => existsSync(p));
+  const home = deps.home || process.env.HOME || "";
+  const cwd = deps.cwd || process.cwd();
+  const isSeat = (dir) => Boolean(dir) && exists(join(dir, "config", "org.yaml"));
+
+  if (explicit) {
+    if (isSeat(explicit)) return { ok: true, root: explicit, how: "given" };
+    return { ok: false, error: `--agent-root ${explicit} has no config/org.yaml — that is not an enrolled agent directory.` };
+  }
+  if (isSeat(cwd)) return { ok: true, root: cwd, how: "cwd" };
+
+  const found = (deps.listHome || (() => { try { return readdirSync(home); } catch { return []; } }))()
+    .map((name) => join(home, name))
+    .filter(isSeat);
+  if (found.length === 1) return { ok: true, root: found[0], how: "discovered under $HOME" };
+  if (found.length === 0) {
+    return { ok: false, error: `no enrolled agent directory found (looked at ${cwd} and $HOME/*/config/org.yaml) — pass --agent-root <dir>.` };
+  }
+  return { ok: false, error: `several enrolled agent directories (${found.join(", ")}) — pass --agent-root <dir> to say which one reads the fleet.` };
+}
+
+export async function readFleet(o = {}) {
+  const client = o.client || (await import("../../lib/org/client.mjs"));
+  const root = resolveAgentRoot(o.agentRoot);
+  // `fatal` means polling cannot help: the fault is in how this run was invoked,
+  // not in a momentarily unreachable server. The loop stops on it.
+  if (!root.ok) return { ok: false, fatal: true, error: root.error, seats: [], nonSeats: [] };
+  let cfg;
+  try {
+    cfg = client.loadOrgConfig(root.root);
+  } catch (err) {
+    return { ok: false, fatal: true, error: `org config unreadable at ${root.root} (${err && err.message})`, seats: [], nonSeats: [] };
+  }
+  if (!client.isEnabled(cfg)) {
+    return { ok: false, fatal: true, error: `org integration is not enabled for ${root.root} — cannot read the fleet`, seats: [], nonSeats: [] };
+  }
+  let r;
+  try {
+    r = await client.read("directory", client.configFromAgent(cfg));
+  } catch (err) {
+    return { ok: false, error: `directory read threw (${err && err.message})`, seats: [], nonSeats: [] };
+  }
+  if (!r || !r.ok || !r.payload) {
+    return { ok: false, error: `directory read failed (${(r && r.error) || "no payload"})`, seats: [], nonSeats: [] };
+  }
+  const members = Array.isArray(r.payload) ? r.payload : r.payload.members || [];
+  return { ok: true, ...toSeats(members, { seatWindowMs: o.seatWindowMs }) };
+}
+
+// ---------------------------------------------------------------------------
+// STAGES
+// ---------------------------------------------------------------------------
+
+/**
+ * Stage 1 — gather the facts (running the gates for real) and apply
+ * {@link evaluatePreflight}.
+ */
+export function preflight(o) {
+  const deps = { ...defaultDeps, ...(o.deps || {}) };
+  const { name, version } = o.pkg;
+  deps.log(`\n── pre-flight ──────────────────────────────────────────────`);
+
+  const whoami = npmWhoami(deps);
+  deps.log(`npm whoami          ${whoami.ok ? `ok (${whoami.user})` : `FAILED — ${whoami.error}`}`);
+
+  const registryLatest = o.registryLatest || npmLatest(name, deps);
+  deps.log(`registry @latest    ${registryLatest.ok ? registryLatest.version : `unreadable — ${registryLatest.error}`}  (local ${version})`);
+
+  const worktree = gitWorktree(deps);
+  deps.log(`working tree        ${worktree.clean ? "clean" : `${worktree.dirty.length} uncommitted path(s)`}`);
+
+  const tag = gitTag(version, deps);
+  deps.log(`tag ${tag.name}${" ".repeat(Math.max(1, 16 - tag.name.length))}${tag.local ? (tag.remote ? "local + pushed" : "local only — NOT pushed") : "missing"}`);
+
+  // The cheap facts first. If any of them already blocks the publish, the two
+  // multi-minute gates are NOT run — there is nothing they could unblock, and
+  // an operator staring at a 401 should not wait three minutes to be told so.
+  // They are never SKIPPED on a run that could publish: see below.
+  const cheap = {
+    whoami,
+    localVersion: version,
+    registryLatest,
+    worktree,
+    tag,
+    check: { ok: true, code: 0 },
+    test: { ok: true, code: 0 },
+  };
+  const cheapVerdict = evaluatePreflight(cheap);
+  if (!cheapVerdict.ok) {
+    deps.log(`npm run check       not run (publish already blocked)`);
+    deps.log(`npm test            not run (publish already blocked)`);
+    return {
+      ok: false,
+      refusals: cheapVerdict.refusals,
+      notes: ["`npm run check` and `npm test` were not run: the blockers above stop the publish regardless. They are re-run in full on any run that could publish."],
+      facts: { whoami, registryLatest, worktree, tag, check: null, test: null },
+    };
+  }
+
+  // The gates are re-run, never trusted from a log: they must pass on the bytes
+  // about to be published, not on whatever was in the tree an hour ago.
+  deps.log(`npm run check       running…`);
+  const check = deps.exec("npm", ["run", "check"], { inherit: Boolean(o.inheritGates) });
+  deps.log(`npm run check       ${gateLine(check)}`);
+  deps.log(`npm test            running…`);
+  const test = deps.exec("npm", ["test"], { inherit: Boolean(o.inheritGates) });
+  deps.log(`npm test            ${gateLine(test)}`);
+
+  const verdict = evaluatePreflight({
+    ...cheap,
+    check: { ok: check.ok, ran: check.ran, failure: check.failure, code: check.code },
+    test: { ok: test.ok, ran: test.ran, failure: test.failure, code: test.code },
+  });
+  const notes = [];
+  const dirt = gateDirtNote(worktree.dirty, gitWorktree(deps).dirty);
+  if (dirt) {
+    notes.push(dirt);
+    deps.log(`note: ${dirt}`);
+  }
+  return { ...verdict, notes, facts: { whoami, registryLatest, worktree, tag, check, test } };
+}
+
+/**
+ * Stage 2 — publish, then poll the registry through the read lag.
+ * @returns {Promise<{ok:boolean, published:boolean, reason:string}>}
+ */
+export async function publish(o) {
+  const deps = { ...defaultDeps, ...(o.deps || {}) };
+  const { name, version } = o.pkg;
+  deps.log(`\n── publish ─────────────────────────────────────────────────`);
+  if (o.dryRun) {
+    deps.log(`--dry-run: NOT publishing ${name}@${version}. Everything else ran for real.`);
+    return { ok: true, published: false, reason: "dry run" };
+  }
+  const r = deps.exec("npm", ["publish"], { inherit: true });
+  if (!r.ok) return { ok: false, published: false, reason: `npm publish failed (exit ${r.code})` };
+  deps.log(`published ${name}@${version} — waiting for the registry to serve it`);
+
+  const maxAttempts = Number.isFinite(o.registryAttempts) ? o.registryAttempts : 10;
+  const waitMs = Number.isFinite(o.registryWaitMs) ? o.registryWaitMs : 6000;
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    const read = npmLatest(name, deps);
+    const d = readLagDecision({ attempt, maxAttempts, target: version, read });
+    deps.log(`  registry check ${attempt}/${maxAttempts}: ${d.reason}`);
+    if (d.action === "done") return { ok: true, published: true, reason: d.reason };
+    if (d.action === "fail") return { ok: false, published: true, reason: d.reason };
+    await deps.sleep(waitMs);
+  }
+  return { ok: false, published: true, reason: "registry never served the new version" };
+}
+
+/**
+ * Stage 3 — poll the org until every seat reports `target`, or the deadline
+ * passes. Prints the table every round.
+ * @returns {Promise<{ok:boolean, summary:object|null, rounds:number}>}
+ */
+export async function verifyPropagation(o) {
+  const deps = { ...defaultDeps, ...(o.deps || {}) };
+  const target = o.target;
+  const started = deps.now();
+  const deadlineMs = Number.isFinite(o.deadlineMs) ? o.deadlineMs : 90 * 60 * 1000;
+  const intervalMs = Number.isFinite(o.intervalMs) ? o.intervalMs : 60 * 1000;
+  deps.log(`\n── verify propagation ──────────────────────────────────────`);
+  deps.log(`target ${target} · deadline ${ageLabel(deadlineMs)} · poll every ${ageLabel(intervalMs)}`);
+  deps.log(`seats update themselves from npm on their own hourly autoupdater; nothing is pushed from here.`);
+
+  let round = 0;
+  let summary = null;
+  let saidWhyUnknown = false;
+  for (;;) {
+    round += 1;
+    const fleet = await (o.readFleet || readFleet)({
+      agentRoot: o.agentRoot,
+      client: o.client,
+      seatWindowMs: o.seatWindowMs,
+    });
+    if (!fleet.ok && fleet.fatal) {
+      // Not transient: retrying changes nothing and the deadline would only
+      // delay the answer. Say what to do and stop.
+      deps.log(`\nfleet read cannot succeed as invoked — ${fleet.error}`);
+      return { ok: false, summary: null, rounds: round, fatal: true, error: fleet.error };
+    }
+    if (!fleet.ok) {
+      deps.log(`round ${round}: fleet read failed — ${fleet.error}`);
+    } else {
+      summary = summarise(fleet, target);
+      deps.log("");
+      deps.log(renderSeatTable(summary, { round, elapsedMs: deps.now() - started }));
+      if (!saidWhyUnknown && summary.counts.unverifiable > 0) {
+        saidWhyUnknown = true;
+        deps.log(
+          `\n  ${propagationOutcome(summary).note}\n`
+        );
+      }
+      if (summary.done) {
+        deps.log(`\n${renderVerdict(summary)}`);
+        return { ok: true, summary, rounds: round };
+      }
+    }
+    const elapsed = deps.now() - started;
+    if (elapsed + intervalMs > deadlineMs) {
+      deps.log(`\ndeadline (${ageLabel(deadlineMs)}) reached.`);
+      if (summary) deps.log(renderVerdict(summary));
+      else deps.log("no successful fleet read before the deadline.");
+      return { ok: false, summary, rounds: round };
+    }
+    await deps.sleep(intervalMs);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// CLI
+// ---------------------------------------------------------------------------
+
+/**
+ * Flag names that must never be accepted — and whose VALUE must never be
+ * echoed. Deliberately wider than the flags this tool knows about: the point is
+ * not to enumerate our own options, it is that an operator who types a secret
+ * at this CLI must not find it in their scrollback (or in a tee'd log) after the
+ * refusal. `--token` and `--registry-token` and `--npmAuthToken` are all the
+ * same mistake.
+ */
+const CREDENTIAL_FLAG = /(token|auth|pass|secret|otp|key|credential|cookie|session|bearer|api[-_]?k)/i;
+
+/**
+ * The flag name alone. Everything from the first `=` onwards is dropped
+ * unread, so no code path downstream of parsing can echo a `--flag=value`
+ * value — not the credential branch, not the unknown-argument branch.
+ * @param {string} a
+ * @returns {string}
+ */
+function flagName(a) {
+  const eq = a.indexOf("=");
+  return eq === -1 ? a : a.slice(0, eq);
+}
+
+/**
+ * Parse argv. Pure. Rejects anything that smells like a credential, and never
+ * puts an argument's VALUE into an error string — see {@link CREDENTIAL_FLAG}.
+ * A bare (non-flag) argument is reported by shape and length only, because a
+ * pasted secret most often arrives as one.
+ */
+export function parseArgs(argv) {
+  const o = {
+    dryRun: false,
+    verifyOnly: false,
+    deadlineMs: 90 * 60 * 1000,
+    intervalMs: 60 * 1000,
+    seatWindowMs: DEFAULT_SEAT_WINDOW_MS,
+    agentRoot: process.env.AGENT_ROOT || process.env.AGENT_DIR || undefined,
+    json: false,
+    help: false,
+    errors: [],
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--dry-run") o.dryRun = true;
+    else if (a === "--verify-only") o.verifyOnly = true;
+    else if (a === "--json") o.json = true;
+    else if (a === "--help" || a === "-h") o.help = true;
+    else if (a === "--deadline") o.deadlineMs = Math.max(0, Number(argv[++i]) * 60 * 1000);
+    else if (a === "--interval") o.intervalMs = Math.max(1000, Number(argv[++i]) * 1000);
+    else if (a === "--seat-window") o.seatWindowMs = Math.max(0, Number(argv[++i]) * 60 * 1000);
+    else if (a === "--agent-root") o.agentRoot = argv[++i];
+    else if (a.startsWith("-")) {
+      const name = flagName(a);
+      if (CREDENTIAL_FLAG.test(name)) {
+        o.errors.push(`${name}: this tool never takes a credential as an argument — run \`npm login\` instead.`);
+        // `--token secret` (space-separated) would otherwise reach the next
+        // iteration as a bare argument. Swallow it so it is never echoed.
+        if (a.indexOf("=") === -1 && i + 1 < argv.length && !argv[i + 1].startsWith("-")) i++;
+      } else {
+        o.errors.push(`unknown argument ${name}`);
+      }
+    } else {
+      o.errors.push(`unknown argument: a bare value of ${a.length} character(s) — every option here starts with \`--\``);
+    }
+  }
+  return o;
+}
+
+const USAGE = `rollout — publish one SDK version and prove the fleet took it
+
+  node scripts/fleet/rollout.mjs [--dry-run] [--deadline <min>] [--interval <s>]
+                                 [--seat-window <min>] [--agent-root <path>] [--json]
+
+  --dry-run       run every gate for real, skip only the publish itself
+  --verify-only   skip pre-flight and publish; just watch the fleet take a version
+  --deadline min  how long to wait for the fleet (default 90)
+  --interval s    seconds between fleet polls (default 60)
+  --seat-window m a member counts as a seat if it beat within this window (default 30)
+  --json          print the verdict as JSON: {code, reason, note, summary}
+
+Exit: 0 verified · 1 pre-flight refusal · 2 publish/registry failure ·
+      3 deadline passed with seats behind or unverifiable.
+
+UNVERIFIED IS NOT DONE. A seat that reports no version is never counted as
+current, so a run can exit 3 with nothing known to be behind. Branch on the
+--json 'reason' field ("verified" | "behind" | "unverifiable" | "empty-fleet" |
+"no-fleet-read"), not on the exit code: 'behind' is fixed by waiting,
+'unverifiable' is a seat whose copied tree predates SDK 2.12 and is not.
+
+Never ssh's anywhere and never accepts a credential as an argument — a
+credential-shaped flag is refused and its value is never echoed back.`;
+
+/** @returns {Promise<number>} process exit code */
+export async function main(argv = process.argv.slice(2), injected = {}) {
+  const deps = { ...defaultDeps, ...(injected.deps || {}) };
+  const args = parseArgs(argv);
+  if (args.help) {
+    deps.log(USAGE);
+    return 0;
+  }
+  if (args.errors.length) {
+    for (const e of args.errors) deps.log(`rollout: ${e}`);
+    return 1;
+  }
+  const pkg = injected.pkg || readLocalPackage();
+  deps.log(`rollout ${pkg.name}@${pkg.version}${args.dryRun ? "  [dry run]" : ""}`);
+
+  const latest = npmLatest(pkg.name, deps);
+  const already = latest.ok && latest.version && compareVersions(latest.version, pkg.version) === 0;
+
+  if (args.verifyOnly) {
+    deps.log(
+      `--verify-only: not publishing. Registry @latest is ${latest.ok ? latest.version : `unreadable (${latest.error})`}; ` +
+        `checking which seats are running ${pkg.version}.`
+    );
+  } else if (already) {
+    deps.log(`already published — registry @latest is ${latest.version}. Verifying propagation.`);
+  } else {
+    const pre = preflight({ pkg, deps, registryLatest: latest, ...injected.preflight });
+    if (!pre.ok) {
+      deps.log(`\nREFUSING TO PUBLISH — ${pre.refusals.length} blocker(s):`);
+      for (const r of pre.refusals) deps.log(`  · ${r}`);
+      for (const n of pre.notes || []) deps.log(`  (${n})`);
+      deps.log(`\nNothing was published and nothing was changed. Fix the blockers and re-run.`);
+      return 1;
+    }
+    deps.log(`\npre-flight clear.`);
+    const pub = await publish({ pkg, deps, dryRun: args.dryRun, ...injected.publishOpts });
+    if (!pub.ok) {
+      deps.log(`publish stage failed: ${pub.reason}`);
+      return 2;
+    }
+  }
+
+  const v = await verifyPropagation({
+    target: pkg.version,
+    deps,
+    agentRoot: args.agentRoot,
+    deadlineMs: args.deadlineMs,
+    intervalMs: args.intervalMs,
+    seatWindowMs: args.seatWindowMs,
+    readFleet: injected.readFleet,
+    client: injected.client,
+  });
+  const outcome = propagationOutcome(v.summary);
+  if (outcome.note) deps.log(`\n${outcome.note}`);
+  if (args.json) deps.log(JSON.stringify({ ...outcome, summary: v.summary ?? null }, null, 2));
+  // A failed verify never exits 0, whatever the outcome says.
+  return v.ok ? 0 : outcome.code || 3;
+}
+
+if (process.argv[1] && resolvePath(process.argv[1]) === resolvePath(__filename)) {
+  main().then(
+    (code) => { process.exitCode = code; },
+    (err) => {
+      process.stderr.write(`rollout failed: ${(err && err.stack) || err}\n`);
+      process.exitCode = 2;
+    }
+  );
+}
+
+export default { main, preflight, publish, verifyPropagation, readFleet, propagationOutcome, commandRefusal };