agent-coord-mcp 0.26.4 → 0.26.6

package/src/tools/rotate.ts

@@ -0,0 +1,180 @@
+/*
+ * `rotate` — handover-to-self across a context clear (Phase 5 Task 5).
+ *
+ * THE PACKET IS A SNAPSHOT, AND A CONTEXT RESET IS PRECISELY WHEN NOBODY CAN
+ * CHECK IT. After `/clear` the agent has no memory to contradict the packet
+ * with: whatever it says becomes the world. So the packet is written from
+ * TOOLS AND `gh`, never from chat memory — memory is the one source that
+ * cannot be re-derived after the reset it is meant to survive — and on the
+ * far side it is RECONCILED against live state before any work is done.
+ *
+ * A packet that is merely READ on resume is a stale world restored with
+ * confidence. That is the failure this verb exists to prevent, so `missionHint`
+ * is named a HINT in the type and treated as one in code: it is the only field
+ * that cannot be verified, and it never gets to assert anything.
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import path from "node:path";
+import { z } from "zod";
+import { ROOT } from "../store.js";
+
+/*
+ * 5.4 — JOB IDS ARE AN ALLOWLIST.
+ *
+ * `archive-done` is deliberately ABSENT and stays absent: it is an arithmetic
+ * job over DONE.md that belongs to Groundwork and an existing QUEUE item, and
+ * a rotation is the worst possible moment to run one. Rotation exists to carry
+ * state ACROSS a reset intact; a verb that also rewrites the records it is
+ * carrying cannot be checked afterwards by the agent that ran it.
+ */
+export const ROTATE_JOBS = ["reseed-only", "phase-boundary"] as const;
+export type RotateJob = (typeof ROTATE_JOBS)[number];
+
+export type OpenPr = { n: number; headRefOid: string };
+export type RotatePacket = {
+  agentId: string;
+  job: RotateJob;
+  rooms: string[];
+  name: string;
+  /** A HINT, never an assertion — the one field nothing can verify. */
+  missionHint: string;
+  atSha: string;
+  openPrs: OpenPr[];
+  at: string;
+};
+
+const packetFile = (agentId: string) => path.join(ROOT, "rotate", `${agentId}.json`);
+
+export type RepoFacts = { dirty: string; sha: string; openPrs: OpenPr[] };
+const realFacts = (repo: string): RepoFacts => {
+  const git = (args: string[]) => execFileSync("git", args, { cwd: repo, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+  const out = execFileSync("gh", ["pr", "list", "--state", "open", "--json", "number,headRefOid"], { cwd: repo, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+  return {
+    dirty: git(["status", "--porcelain"]),
+    sha: git(["rev-parse", "HEAD"]),
+    openPrs: (JSON.parse(out) as { number: number; headRefOid: string }[]).map((p) => ({ n: p.number, headRefOid: p.headRefOid })),
+  };
+};
+
+export const rotateSchema = {
+  agentId: z.string().min(1),
+  job: z.string().min(1),
+  repo: z.string().optional(),
+  rooms: z.array(z.string()).optional(),
+  missionHint: z.string().optional(),
+  write: z.boolean().optional(),
+};
+
+export async function rotateTool(
+  args: { agentId: string; job: string; repo?: string; rooms?: string[]; missionHint?: string; write?: boolean },
+  facts: (repo: string) => RepoFacts = realFacts,
+) {
+  const repo = args.repo ?? process.cwd();
+
+  // 5.4 — unknown job refused BY NAME, and `archive-done` gets its own reason
+  // so the refusal reads as a decision rather than a typo.
+  if (!(ROTATE_JOBS as readonly string[]).includes(args.job)) {
+    const extra = args.job === "archive-done" ? ` 'archive-done' is deliberately not a rotation job: it rewrites the records the rotation is carrying, and a reset is the one moment nobody can check the result. It belongs to Groundwork and its existing QUEUE item.` : "";
+    return { ok: false as const, error: `'${args.job}' is not a rotate job. Allowed: ${ROTATE_JOBS.join(", ")}.${extra}` };
+  }
+
+  let f: RepoFacts;
+  try {
+    f = facts(repo);
+  } catch (e) {
+    return { ok: false as const, error: `could not read live state (${String((e as Error).message).split("\n")[0]}) — a packet built from anything but live state is chat memory with a filename.` };
+  }
+
+  // 5.2 — MID-SLICE DIRTY REFUSES THE CLEAR.
+  //
+  // Uncommitted work is the one thing a packet cannot carry: it is not in the
+  // repo, not on a branch, and not in any tool's answer, so after `/clear` no
+  // reconciliation can discover it ever existed. It does not get lost loudly —
+  // it gets lost silently, which is why this is a refusal and not a warning.
+  if (f.dirty) {
+    const n = f.dirty.split("\n").filter(Boolean).length;
+    return {
+      ok: false as const,
+      error: `${n} uncommitted change(s) — refusing to rotate mid-slice. Uncommitted work is the one thing a packet cannot carry: after the clear, nothing can discover it existed. Commit it or stash it deliberately, then rotate.`,
+      dirty: f.dirty.split("\n").filter(Boolean),
+    };
+  }
+
+  const packet: RotatePacket = {
+    agentId: args.agentId,
+    job: args.job as RotateJob,
+    rooms: args.rooms ?? [],
+    name: args.agentId,
+    missionHint: args.missionHint ?? "",
+    atSha: f.sha,
+    openPrs: f.openPrs,
+    at: new Date().toISOString(),
+  };
+
+  if (!args.write) return { ok: true as const, written: false as const, packet, note: `packet built from live state; pass write:true to persist it before /clear.` };
+  mkdirSync(path.dirname(packetFile(args.agentId)), { recursive: true });
+  writeFileSync(packetFile(args.agentId), `${JSON.stringify(packet, null, 2)}\n`);
+  return { ok: true as const, written: true as const, packet, path: packetFile(args.agentId) };
+}
+
+/* ── 5.3 / 5.5 — reconcile before working, or refuse to work ───────────────── */
+
+export type Divergence = { field: string; packet: string; live: string; note: string };
+
+export const rotateReconcileSchema = { agentId: z.string().min(1), repo: z.string().optional() };
+
+export async function rotateReconcileTool(
+  args: { agentId: string; repo?: string },
+  facts: (repo: string) => RepoFacts = realFacts,
+) {
+  const repo = args.repo ?? process.cwd();
+  const f0 = packetFile(args.agentId);
+  if (!existsSync(f0)) return { ok: false as const, error: `no rotate packet for '${args.agentId}'. A reseeded agent with no packet has nothing to reconcile against and must not infer its state — ask for a GO.` };
+
+  let packet: RotatePacket;
+  try {
+    packet = JSON.parse(readFileSync(f0, "utf8")) as RotatePacket;
+  } catch (e) {
+    return { ok: false as const, error: `packet for '${args.agentId}' is unreadable (${String((e as Error).message).split("\n")[0]}) — an unparseable packet is not an empty one; do not proceed as if there were no prior state.` };
+  }
+
+  let f: RepoFacts;
+  try {
+    f = facts(repo);
+  } catch (e) {
+    // NOT RECONCILED IS NOT RECONCILED-CLEAN.
+    return { ok: false as const, error: `could not read live state to reconcile (${String((e as Error).message).split("\n")[0]}) — NOT checked, which is not the same as checked and matching.`, packet };
+  }
+
+  const live = new Map(f.openPrs.map((p) => [p.n, p.headRefOid]));
+  const divergences: Divergence[] = [];
+
+  // 5.5 — THE PACKET'S OPEN PRs ARE CLAIMS, NOT FACTS.
+  //
+  // A PR that merged during the reset is the dangerous direction: the packet
+  // says "open", the agent resumes and keeps working a branch that is already
+  // in main, and every one of its next steps is coherent and wrong.
+  for (const p of packet.openPrs ?? []) {
+    if (!live.has(p.n)) divergences.push({ field: `pr#${p.n}`, packet: "open", live: "not open", note: `#${p.n} is no longer open — it merged or closed during the reset. Do NOT resume work on it as open.` });
+    else if (live.get(p.n) !== p.headRefOid) divergences.push({ field: `pr#${p.n}`, packet: p.headRefOid, live: String(live.get(p.n)), note: `#${p.n} advanced during the reset — the packet's head is stale; re-read before acting.` });
+  }
+
+  if (packet.atSha && f.sha !== packet.atSha)
+    divergences.push({ field: "atSha", packet: packet.atSha, live: f.sha, note: `the repo moved during the reset; anything the packet said about the tree may be stale.` });
+
+  // The verdict names its POPULATION, and `missionHint` is excluded from it on
+  // purpose: it is unverifiable, so counting it as "reconciled" would be a
+  // clean report over something never checked.
+  const verdict = {
+    reconciled: (packet.openPrs?.length ?? 0) + (packet.atSha ? 1 : 0),
+    divergences,
+    unverifiable: ["missionHint"],
+    missionHint: packet.missionHint,
+  };
+
+  if (divergences.length)
+    return { ok: false as const, error: `${divergences.length} divergence(s) between packet and live state — REFUSING to report ready. A packet read without reconciliation is a stale world restored with confidence.`, verdict, packet };
+
+  return { ok: true as const, ready: true as const, verdict, packet, note: `packet matches live state. 'missionHint' is a HINT and was NOT verified — treat it as a prompt, never as an instruction you have confirmed.` };
+}

package/src/tools/shared.ts

@@ -97,8 +97,32 @@ export type TransportMarker = {
   // it for a session restart + re-attach. Absent on markers written by older
   // versions (treated as "unknown, skip", deliberately mirroring scriptMtime).
   serverBuildMtime?: number;
+  // Does this transport carry ROOM traffic, or DMs only?
+  //
+  // A pusher started with `--no-room` delivers inbox messages and nothing
+  // else, and until this field existed the marker looked identical to a full
+  // one — so `status` said `attached: true` and an agent sat with its room
+  // feed off while every reading said healthy. That is how worker-2 missed
+  // its channel traffic.
+  //
+  // ABSENT MEANS UNKNOWN, NEVER "ON" — deliberately mirroring scriptMtime and
+  // serverBuildMtime above. A marker from an older pusher cannot tell us, and
+  // reporting an unasked question as full capability is the defect this field
+  // exists to remove.
+  rooms?: boolean;
 };
 
+/**
+ * How to REPORT a transport's room capability.
+ *
+ * Three states, not two. `undefined` is a marker written before the field
+ * existed: it cannot answer, and "unknown" is the only truthful report. The
+ * defect being fixed is precisely a two-state reading of a three-state world —
+ * `attached: true` covered "full", "DM-only", and "cannot say" alike.
+ */
+export const roomFeedOf = (m: { rooms?: boolean } | null | undefined): "on" | "off" | "unknown" =>
+  !m || m.rooms === undefined ? "unknown" : m.rooms ? "on" : "off";
+
 export type AgentRegistry = Record<string, AgentEntry>;
 
 export type {

package/src/tools/stall.ts

@@ -0,0 +1,194 @@
+/*
+ * `stall_check` — a predicate over the board and the bus, plus a HALT flag.
+ *
+ * Stall has been "notice the room" until now, which means it is noticed when
+ * somebody happens to look. The measured cost elsewhere: ~42 hours of dead merge
+ * path across four incidents in three days, with `main` advancing throughout so
+ * every commit-based liveness check read green.
+ *
+ * A MISS IS SILENT TO THE DUTY OFFICER AND NEVER SILENT TO THE RECORD.
+ *
+ * This is the whole design constraint (3.3b). "HIT DMs, MISS silent" answers the
+ * noise question and makes a DEAD CLOCK look exactly like a healthy fleet — the
+ * absence-read-as-evidence rule, inside the verb built to watch for absence. So
+ * every run leaves a mark, HIT or MISS, and "no alert" becomes distinguishable
+ * from "nothing ran". A check that only speaks when it fires cannot be told from
+ * a broken one.
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import path from "node:path";
+import { z } from "zod";
+import { parseWorkDoc, workstreamsV1RowsOf } from "@davidbalzan/groundwork-seam";
+import { ROOT, AGENTS_FILE, readJson } from "../store.js";
+
+const BOARD_DOC = "docs/WORKSTREAMS.md";
+const STALL_MS = 30 * 60 * 1000;
+
+const runFile = () => path.join(ROOT, "stall-check.json");
+const haltFile = () => path.join(ROOT, "halt.json");
+
+export type StallHit =
+  | { kind: "no-heartbeat"; agentId: string; stream: string; minutes: number }
+  | { kind: "no-vcs-activity"; agentId: string; branch: string; minutes: number };
+
+// ---------- halt ----------
+
+export const setHaltSchema = {
+  reason: z.string().min(1),
+  by: z.string().min(1),
+  clear: z.boolean().optional(),
+};
+
+/**
+ * A NAMED state, never a mood.
+ *
+ * "Production feels down" is not a halt: a halt blocks every claim in the fleet,
+ * so the thing that sets it must be nameable and therefore arguable — a board
+ * cutover, a cited `BLOCKER:`, a documented red pipeline. The reason is required
+ * for that reason, not for the log.
+ */
+export async function setHaltTool(args: { reason: string; by: string; clear?: boolean }) {
+  mkdirSync(ROOT, { recursive: true });
+  if (args.clear) {
+    writeFileSync(haltFile(), JSON.stringify({ halted: false, clearedBy: args.by, clearedAt: Date.now(), lastReason: args.reason }, null, 2));
+    return { ok: true as const, halted: false, clearedBy: args.by };
+  }
+  const state = { halted: true, reason: args.reason, by: args.by, at: Date.now() };
+  writeFileSync(haltFile(), JSON.stringify(state, null, 2));
+  return { ok: true as const, ...state };
+}
+
+export function haltState(): { halted: boolean; reason?: string; by?: string; at?: number } {
+  try {
+    const raw = JSON.parse(readFileSync(haltFile(), "utf8"));
+    return raw?.halted ? raw : { halted: false };
+  } catch {
+    return { halted: false };
+  }
+}
+
+// ---------- the run mark ----------
+
+/** Every run leaves this, HIT or MISS. It is what makes a dead clock visible. */
+function markRun(result: { hits: StallHit[]; checked: number }) {
+  mkdirSync(ROOT, { recursive: true });
+  let history: { at: number; hits: number; checked: number }[] = [];
+  try {
+    history = JSON.parse(readFileSync(runFile(), "utf8")).history ?? [];
+  } catch {
+    /* first run */
+  }
+  history.push({ at: Date.now(), hits: result.hits.length, checked: result.checked });
+  // A RUN OF MISSES MUST BE VISIBLE AS RUNS, not as absence — so the marks are a
+  // list, not a single timestamp. "Ten quiet checks" and "one check ten hours ago"
+  // are different states and only the first is a healthy fleet.
+  writeFileSync(runFile(), JSON.stringify({ history: history.slice(-200) }, null, 2));
+}
+
+export const lastRanSchema = { maxAgeMinutes: z.number().optional() };
+
+/**
+ * Is the clock alive? Readable by a human or another check, which is the point —
+ * MISS is silent to the duty officer, not to the record.
+ */
+export async function stallClockStatusTool(args: { maxAgeMinutes?: number }) {
+  const maxAge = (args.maxAgeMinutes ?? 60) * 60 * 1000;
+  let history: { at: number; hits: number; checked: number }[] = [];
+  try {
+    history = JSON.parse(readFileSync(runFile(), "utf8")).history ?? [];
+  } catch {
+    return {
+      ok: false as const,
+      error:
+        "stall_check has NEVER run — no run mark exists. That is not a quiet fleet, it is an unwatched one: a check that only speaks when it fires cannot be told from a broken one.",
+    };
+  }
+  const last = history[history.length - 1];
+  const age = Date.now() - (last?.at ?? 0);
+  // `>=`, NOT `>`, AND THE DIFFERENCE IS A REAL RACE RATHER THAN PEDANTRY.
+  //
+  // With `>`, a window of 0 and a mark written in the SAME MILLISECOND gives
+  // `0 > 0` = false: the clock reads FRESH at the instant it was asked to treat
+  // everything as stale. It passed locally and on one CI run and failed on
+  // another — green in two environments, red in one — because it depended on at
+  // least a millisecond elapsing.
+  //
+  // The window having ELAPSED is the condition, so equality is inside it: a
+  // 0-minute window means nothing is ever fresh, which is what a caller asking
+  // for one means.
+  const stale = age >= maxAge;
+  const misses = history.filter((h) => h.hits === 0).length;
+  return {
+    ok: !stale,
+    ...(stale
+      ? {
+          error: `stall_check last ran ${Math.round(age / 60000)}m ago, past the ${args.maxAgeMinutes ?? 60}m window — THE CLOCK IS STOPPED. No alerts is not the same as no stalls.`,
+        }
+      : {}),
+    lastRanMinutesAgo: Math.round(age / 60000),
+    runs: history.length,
+    misses,
+    hits: history.length - misses,
+  };
+}
+
+// ---------- the predicate ----------
+
+export const stallCheckSchema = { repo: z.string().optional(), stallMinutes: z.number().optional() };
+
+export async function stallCheckTool(args: { repo?: string; stallMinutes?: number }) {
+  const repo = args.repo ?? process.cwd();
+  const limit = (args.stallMinutes ?? 30) * 60 * 1000;
+  const board = path.join(repo, BOARD_DOC);
+  if (!existsSync(board)) return { ok: false as const, error: `no ${BOARD_DOC} under '${repo}'` };
+
+  const rows = workstreamsV1RowsOf(parseWorkDoc(readFileSync(board, "utf8")));
+  const inFlight = rows.filter((r) => /🚧/.test(r.status));
+  const reg = await readJson<Record<string, { lastHeartbeat: number }>>(AGENTS_FILE, {});
+  const now = Date.now();
+  const hits: StallHit[] = [];
+
+  for (const row of inFlight) {
+    const agentId = row.owner.replace(/[`*]/g, "").trim();
+    const entry = reg[agentId];
+    if (entry) {
+      const age = now - entry.lastHeartbeat;
+      if (age > limit) {
+        hits.push({ kind: "no-heartbeat", agentId, stream: row.stream.slice(0, 60), minutes: Math.round(age / 60000) });
+        continue;
+      }
+    }
+    // A FRESH HEARTBEAT IS NOT PROGRESS. An agent can be alive and stuck, which is
+    // the case "notice the room" never catches: the pane is responsive, so nobody
+    // looks. Ask the branch instead.
+    const branch = (row.branchWorktree.match(/`([^`]+)`/)?.[1] ?? "").trim();
+    if (!branch || !/\//.test(branch)) continue;
+    try {
+      const iso = execFileSync("git", ["log", "-1", "--format=%cI", branch], {
+        cwd: repo, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"],
+      }).trim();
+      const age = now - Date.parse(iso);
+      if (age > limit) {
+        hits.push({ kind: "no-vcs-activity", agentId, branch, minutes: Math.round(age / 60000) });
+      }
+    } catch {
+      /* unknown branch: not a stall claim we can make */
+    }
+  }
+
+  const result = { hits, checked: inFlight.length };
+  markRun(result);
+  return {
+    ok: true as const,
+    ...result,
+    halted: haltState().halted,
+    // MISS is silent to the DUTY OFFICER — the caller decides whether to DM — and
+    // never silent to the record, which markRun just wrote.
+    dm: hits.length > 0,
+    note:
+      hits.length === 0
+        ? `MISS — ${inFlight.length} in-flight row(s), none stalled. No DM. The run IS recorded: read it with stall_clock_status, because no alert and nothing running look identical from here.`
+        : undefined,
+  };
+}

package/src/tools/transport.ts

@@ -1,5 +1,7 @@
 import { loadLiveTransports, isMarkerLive, isPidAlive } from "./registry.js";
 import { newestMtimeUnder, onDiskBuildMtime, onDiskSourceMtime, SERVER_BUILD_MTIME, SERVER_BUILD_SHA, BUILD_DIR } from "../build.js";
+import { prefixOf, prefixVerdict } from "../prefix.js";
+import { execFileSync } from "node:child_process";
 import { registerTool } from "./registry.js";
 import { roleInputSchema, type RoleArg } from "../roles.js";
 import { attributeWriter, isGitRepo, lastWriterOf, loadScopes, ownsDocument } from "./scopes.js";
@@ -307,13 +309,69 @@ function defaultReminderText(agentId: string): string {
   );
 }
 
+/*
+ * REMINDERS ARE OBSERVABLE, because "scheduled" is not "delivered".
+ *
+ * `send_command` returns `reminderScheduled` the instant the timer is set, and
+ * the delivery is an async lockfile-protected append whose only failure path
+ * was a line on stderr. So a reminder could be LATE or LOST and the caller had
+ * already been told it was handled — the same claim-without-a-completion-signal
+ * shape as an empty check rollup reading green.
+ *
+ * MEASURED: `withLock` is configured `retries: 10, minTimeout: 20,
+ * maxTimeout: 200`, so the append is PERMITTED well over a second of backoff.
+ * Under sustained inbox contention the reminder lands at ~420ms. Any assertion
+ * with a wall-clock budget below the lock's own policy is asserting something
+ * the system never promised — which is what made tools.test.mjs:156 fail under
+ * full-suite load and pass everywhere else.
+ *
+ * A longer sleep would convert that race into a slower race. This gives the
+ * work a real completion signal instead, so callers and tests can await the
+ * thing itself rather than guess at a duration.
+ */
+type PendingReminder = { done: Promise<void>; timer: NodeJS.Timeout };
+const pendingReminders = new Set<PendingReminder>();
+
+/** Reminders whose delivery FAILED, kept so a drop is observable, not stderr-only. */
+export const reminderFailures: { to: string; error: string; at: number }[] = [];
+
+/**
+ * Resolves once every scheduled reminder has been delivered or has failed.
+ *
+ * Re-`ref`s the pending timers for the duration of the wait. The reminder timer
+ * is deliberately `unref`d so it never holds the MCP server open on its own —
+ * but that also means the event loop will not wait for it, and awaiting an
+ * unref'd timer's promise hangs until the loop drains. A caller that has
+ * explicitly asked to wait is stating the opposite intent, so the ref is
+ * restored for exactly that window and dropped again afterwards.
+ *
+ * (The unref has a production consequence worth naming: if the server's
+ * transport closes before the timer fires, the reminder is dropped. That is a
+ * separate defect from the one this function fixes — reported, not silently
+ * papered over.)
+ */
+export function remindersSettled(): Promise<void> {
+  const pending = [...pendingReminders];
+  for (const p of pending) p.timer.ref();
+  return Promise.all(pending.map((p) => p.done)).then(() => {
+    for (const p of pending) p.timer.unref();
+  });
+}
+
 function scheduleReminders(
   from: string,
   recipients: string[],
   delayMs: number,
   override: string | undefined,
 ): void {
+  // Registered BEFORE the timer fires, so awaiting settlement covers the delay
+  // as well as the write — otherwise a caller could observe "nothing pending"
+  // during the window between scheduling and firing.
+  let markDone: () => void = () => {};
+  const done = new Promise<void>((resolve) => { markDone = resolve; });
+  let entry: PendingReminder;
   const t = setTimeout(async () => {
+   try {
     for (const r of recipients) {
       try {
         const reminder: Message = {
@@ -328,12 +386,20 @@ function scheduleReminders(
         };
         await appendJsonl(inboxFile(r), reminder);
       } catch (e) {
-        process.stderr.write(
-          `[send_command] post-/clear reminder to '${r}' failed: ${(e as Error)?.message ?? e}\n`,
-        );
+        const error = (e as Error)?.message ?? String(e);
+        // Recorded, not just printed: a dropped reminder leaves a just-cleared
+        // agent contextless, and stderr is not somewhere anyone looks for that.
+        reminderFailures.push({ to: r, error, at: Date.now() });
+        process.stderr.write(`[send_command] post-/clear reminder to '${r}' failed: ${error}\n`);
       }
     }
+   } finally {
+    pendingReminders.delete(entry);
+    markDone();
+   }
   }, delayMs);
+  entry = { done, timer: t };
+  pendingReminders.add(entry);
   // Don't keep the event loop alive solely for the reminder — the MCP server's
   // transport already holds it open as long as it's connected.
   if (typeof t.unref === "function") t.unref();
@@ -639,6 +705,11 @@ export async function attachAgentTool(args: {
     // code, and after an in-place rebuild the two differ (that difference is
     // exactly what doctor's provenance check exists to surface).
     serverBuildMtime: SERVER_BUILD_MTIME,
+    // WHAT this transport carries, recorded by the code that decides it.
+    // `includeRoom` is what the pusher is actually spawned with a few lines
+    // above, so the marker cannot claim a capability the process was not
+    // given — the marker and the spawn come from one value, not two.
+    rooms: includeRoom,
   };
   // Use updateJson so it lockfile-protects and creates the file atomically.
   await updateJson<TransportMarker>(transportFile(args.agentId), marker, () => marker);
@@ -941,6 +1012,10 @@ export const reportTransportSchema = {
   // counterpart has been upgraded since. The remote pusher passes
   // `(await fsp.stat(__filename)).mtimeMs`; absent → doctor skips the check.
   scriptMtime: z.number().optional(),
+  // Whether this pusher carries room traffic as well as DMs. Absent → the
+  // marker cannot say, and every reader reports UNKNOWN rather than assuming
+  // a full transport (the worker-2 shape).
+  rooms: z.boolean().optional(),
 };
 
 // Called by an external push daemon (typically scripts/coord-pusher.mjs on a
@@ -954,6 +1029,7 @@ export async function reportTransportTool(args: {
   host?: string;
   since?: number;
   scriptMtime?: number;
+  rooms?: boolean;
 }) {
   const marker: TransportMarker = {
     agentId: args.agentId,
@@ -963,6 +1039,7 @@ export async function reportTransportTool(args: {
     host: args.host,
     since: args.since ?? Date.now(),
     scriptMtime: args.scriptMtime,
+    rooms: args.rooms,
   };
   await updateJson<TransportMarker>(transportFile(args.agentId), marker, () => marker);
   return { ok: true, marker };
@@ -1212,6 +1289,25 @@ export async function doctorTool(args: { fix?: boolean; maxFileBytes?: number })
     });
   }
 
+  // 1b³. WHERE A NEW GLOBAL INSTALL WOULD LAND, which is a different question
+  //      from which copy is running (1b² above) and neither substitutes. On
+  //      this box `npm prefix -g` and the fleet's actual load path pointed at
+  //      two different nvm versions, so an install that printed success would
+  //      have updated a copy nothing loads.
+  {
+    const loadPrefix = prefixOf(BUILD_DIR);
+    let installPrefix: string | null = null;
+    let npmPath: string | undefined;
+    try {
+      installPrefix = execFileSync("npm", ["prefix", "-g"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim() || null;
+      npmPath = execFileSync("which", ["npm"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim() || undefined;
+    } catch {
+      installPrefix = null;
+    }
+    const v = prefixVerdict(loadPrefix, installPrefix, npmPath);
+    findings.push({ check: "install-prefix", level: v.level, detail: v.detail, fixable: false });
+  }
+
   // 1b²ᵇ. The affirmative catch for merged-but-never-rebuilt: src/ newer than
   //       the compiled build means no restart can help — the artifact every
   //       future session will load is already behind the code. Distinct from
@@ -1633,6 +1729,85 @@ export async function doctorTool(args: { fix?: boolean; maxFileBytes?: number })
     });
   }
 
+  // 6b. STALENESS HAS TWO CAUSES AND THEY LOOK IDENTICAL IN A FLAT LIST.
+  //
+  // Check 6 reports "these N agents are stale", which is the detection half and
+  // leaves the reader to infer the cause. The inference is the expensive part: a
+  // coordinator misdiagnosed a billing outage as a coordination failure for want
+  // of exactly this distinction, and spent the incident chasing agents.
+  //
+  //   UNIFORM   every agent stale by roughly the same interval. Agents do not
+  //             fail in lockstep — something they SHARE did: the machine slept,
+  //             the API key expired, billing lapsed, the host lost network. The
+  //             remedy is the environment, and touching the agents does nothing.
+  //   DIVERGENT some stale, some fresh, on the same bus at the same moment. The
+  //             shared substrate is demonstrably working, so the fault is the
+  //             stale agent's. The remedy is that agent.
+  //
+  // CLASSIFICATION IS THE DELIVERABLE, NOT DETECTION — the same finding as
+  // `transport-build-split`: two states with different remedies reported as one
+  // warning leave the reader to guess, and the guess is made under incident
+  // pressure.
+  //
+  // WITH FEWER THAN TWO AGENTS THE QUESTION IS UNANSWERABLE and it says so. One
+  // stale agent on a bus of one is uniform and divergent simultaneously; there is
+  // no second observation to compare against. Naming a cause there would be the
+  // confident-wrong-answer shape this whole class is about.
+  {
+    const live = new Set<string>();
+    for (const fname of await listTransportFiles()) {
+      const marker = await readJson<TransportMarker | null>(path.join(TRANSPORT_DIR, fname), null);
+      if (marker && isMarkerLive(marker, reg, now)) live.add(marker.agentId);
+    }
+    const entries = Object.entries(reg).map(([id, a]) => ({
+      id,
+      live: live.has(id),
+      ageMs: now - a.lastHeartbeat,
+      stale: !live.has(id) && now - a.lastHeartbeat > STALE_MS,
+    }));
+    const stale = entries.filter((e) => e.stale);
+    const fresh = entries.filter((e) => !e.stale);
+    const mins = (ms: number) => Math.round(ms / 60000);
+
+    let level: "ok" | "warn" = "ok";
+    let detail: string;
+    let items: string[] | undefined;
+
+    if (entries.length === 0) {
+      detail = "no registered agents — nothing to classify";
+    } else if (stale.length === 0) {
+      detail = `${entries.length} agent(s), none stale (threshold ${mins(STALE_MS)}m)`;
+    } else if (entries.length < 2) {
+      level = "warn";
+      detail =
+        `1 agent and it is stale (${mins(stale[0]!.ageMs)}m) — UNCLASSIFIABLE. Uniform and divergent are the same ` +
+        `picture with one observation, so the cause is not named here rather than guessed.`;
+      items = [`${stale[0]!.id} (${mins(stale[0]!.ageMs)}m)`];
+    } else if (fresh.length === 0) {
+      // Spread across the stale set decides it: a shared cause stops everything at
+      // once, so the ages cluster. Independent failures do not.
+      const ages = stale.map((e) => e.ageMs).sort((a, b) => a - b);
+      const spread = ages[ages.length - 1]! - ages[0]!;
+      const tight = spread <= Math.max(2 * 60 * 1000, ages[ages.length - 1]! * 0.1);
+      level = "warn";
+      detail = tight
+        ? `UNIFORM: all ${stale.length} agent(s) stale within ${mins(spread)}m of each other (${mins(ages[0]!)}–${mins(ages[ages.length - 1]!)}m). ` +
+          `Agents do not fail in lockstep — suspect something they SHARE (machine asleep, credentials, billing, network). ` +
+          `Restarting agents will not help.`
+        : `ALL ${stale.length} agent(s) are stale but their ages span ${mins(spread)}m — NOT uniform, so a single shared cause does not explain it. ` +
+          `Treat as ${stale.length} independent failures until something ties them together.`;
+      items = stale.map((e) => `${e.id} (${mins(e.ageMs)}m)`);
+    } else {
+      level = "warn";
+      detail =
+        `DIVERGENT: ${stale.length} stale, ${fresh.length} fresh on the same bus at the same moment. ` +
+        `The shared substrate is demonstrably working — the fault is the stale agent's, not the environment's.`;
+      items = stale.map((e) => `${e.id} (${mins(e.ageMs)}m stale)`);
+    }
+
+    findings.push({ check: "staleness-class", level, detail, fixable: false, ...(items ? { items } : {}) });
+  }
+
   // 7. Oversized JSONL files. Report only (suggest prune).
   {
     const big: string[] = [];