agent-coord-mcp 0.26.5 → 0.26.7

package/src/tools/registry.ts

@@ -1,4 +1,5 @@
 import { detachAgentTool } from "./transport.js";
+import { readAway, secondCoordinatorRefusal } from "./away.js";
 import { randomUUID } from "node:crypto";
 import { existsSync, openSync, watch } from "node:fs";
 import { promises as fsp } from "node:fs";
@@ -60,6 +61,7 @@ import {
   type Cursor,
   type Source,
   type TransportMarker,
+  roomFeedOf,
   sourceFile,
   getOffset,
   setOffset,
@@ -123,6 +125,13 @@ export async function registerTool(args: { agentId: string; project?: string; ro
   const roleUpdate = resolveRoleUpdate(args.agentId, before[args.agentId], args.role);
   if (!roleUpdate.ok) return { ok: false as const, error: roleUpdate.error };
 
+  // 4.2 — a SECOND coordinator may not register while the first is away.
+  // Checked on the RESOLVED role, not the string the caller passed: the refusal
+  // has to see what the registry will actually record, or a spelling slips past
+  // the guard and lands as `coordinator` anyway.
+  const second = secondCoordinatorRefusal(readAway(), args.agentId, roleUpdate.roleId);
+  if (second) return { ok: false as const, error: second };
+
   const reg = await updateJson<AgentRegistry>(AGENTS_FILE, {}, (current) => {
     const now = Date.now();
     const existing = current[args.agentId];
@@ -250,10 +259,29 @@ export async function listAgentsTool() {
 
   const reg = await updateJson<AgentRegistry>(AGENTS_FILE, {}, (current) => {
     for (const [id, entry] of Object.entries(current)) {
-      if (liveTransports.has(id)) {
-        entry.lastHeartbeat = now;
-        continue;
-      }
+      // A LIVE TRANSPORT PROTECTS AN AGENT FROM EVICTION. IT DOES NOT STAMP IT.
+      //
+      // This loop used to write `entry.lastHeartbeat = now` here, and
+      // `agents.json` is ONE store shared by every fleet on the machine while
+      // `list_agents` takes no project argument — so a call from one fleet
+      // rewrote every other fleet's timestamps. Another fleet did not ask for
+      // that, cannot see it, and it is not ours to write.
+      //
+      // kit#105 removed the fabricated value from the RESPONSE; the WRITE
+      // stayed, so every consumer reading the file directly still saw
+      // freshness this call had invented.
+      //
+      // AND IT MASKED STALL DETECTION. `stall_check` reads `lastHeartbeat` to
+      // find agents that have gone quiet. Because any `list_agents` call
+      // refreshed every live-transport agent, that clock could never age past
+      // the threshold, so no-heartbeat could not fire for exactly the agents
+      // most likely to be stuck — alive, attached, and doing nothing.
+      //
+      // Nothing is lost: the pusher calls `heartbeat` every 60s
+      // (scripts/coord-pusher.mjs:181), so an attached agent has a REAL
+      // heartbeat. This stamp only ever overwrote a true value with a
+      // simultaneous one.
+      if (liveTransports.has(id)) continue;
       if (now - entry.lastHeartbeat > EVICT_MS) {
         evicted.push(id);
         delete current[id];
@@ -300,7 +328,19 @@ export async function listAgentsTool() {
       ...heartbeatFields,
       capabilities: merged.length > 0 ? merged : undefined,
       transport: transport
-        ? { kind: transport.transport, tmuxTarget: transport.tmuxTarget, pid: transport.pid }
+        ? {
+            kind: transport.transport,
+            tmuxTarget: transport.tmuxTarget,
+            pid: transport.pid,
+            // `attached` alone said nothing about WHAT is attached. A pusher
+            // started `--no-room` delivers DMs only, and its marker used to be
+            // indistinguishable from a full one — so an agent could sit with
+            // its room feed off while status read healthy (worker-2).
+            //
+            // Absent is UNKNOWN, never "on": an older pusher's marker cannot
+            // answer, and answering for it is how the original defect worked.
+            rooms: roomFeedOf(transport),
+          }
         : undefined,
     };
   });

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,311 @@
+/*
+ * `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";
+import { loadLiveTransports } from "./registry.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. */
+/**
+ * Record a run that FAILED.
+ *
+ * Acceptance from the queue item, and the clause most easily skipped: "a
+ * scheduled check reports its FETCH FAILURES, or a broken check is
+ * indistinguishable from a quiet registry". Without this, a clock that fires
+ * every 30 minutes and throws every time leaves NO marks at all — identical on
+ * disk to a clock that was never installed.
+ */
+export function markRunFailure(reason: string): void {
+  mkdirSync(ROOT, { recursive: true });
+  let history: RunMark[] = [];
+  try {
+    history = JSON.parse(readFileSync(runFile(), "utf8")).history ?? [];
+  } catch {
+    /* first run */
+  }
+  history.push({ at: Date.now(), hits: 0, checked: 0, failed: reason });
+  writeFileSync(runFile(), JSON.stringify({ history: history.slice(-200) }, null, 2));
+}
+
+type RunMark = { at: number; hits: number; checked: number; failed?: string };
+
+function markRun(result: { hits: StallHit[]; checked: number }) {
+  mkdirSync(ROOT, { recursive: true });
+  let history: RunMark[] = [];
+  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: RunMark[] = [];
+  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];
+  // A RUN THAT FAILED IS NOT A RUN THAT PASSED. Without this the clock reads
+  // "fresh" off a mark it wrote while erroring — the age is honest and the
+  // health is not, which is the same shape as a fresh heartbeat from a stuck
+  // agent.
+  const failures = history.filter((h) => h.failed);
+  const lastFailed = last?.failed;
+  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.failed && h.hits === 0).length;
+  const hits = history.filter((h) => !h.failed && h.hits > 0).length;
+  return {
+    // A FAILING CLOCK IS NOT A HEALTHY ONE. It writes marks on schedule, so the
+    // age looks fresh while nothing is being measured — a fresh heartbeat from
+    // a stuck agent, one level up.
+    ok: !stale && !lastFailed,
+    ...(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.`,
+        }
+      : lastFailed
+        ? {
+            error: `the clock is RUNNING but its last run FAILED: ${lastFailed}. It is firing on schedule and measuring nothing, which reads as fresh and is not.`,
+          }
+        : {}),
+    lastRanMinutesAgo: Math.round(age / 60000),
+    runs: history.length,
+    misses,
+    hits,
+    failures: failures.length,
+  };
+}
+
+// ---------- 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 liveTransports = await loadLiveTransports();
+  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[] = [];
+  /** Rows whose VCS activity could not be measured. NOT stall claims. */
+  const unmeasurable: { agentId: string; value: string; why: string }[] = [];
+
+  for (const row of inFlight) {
+    const agentId = row.owner.replace(/[`*]/g, "").trim();
+    const entry = reg[agentId];
+    if (entry) {
+      const age = now - entry.lastHeartbeat;
+      // A HEARTBEAT IS ONLY EVIDENCE WHERE SOMETHING WRITES ONE.
+      //
+      // `heartbeat` is called by the PUSHER, never by the agent. Only
+      // `coord-pusher.mjs` (the REMOTE pusher) calls it, and it must: a remote
+      // marker cannot be pid-probed across machines, so its liveness IS the
+      // heartbeat. `hooks/tmux-pusher.mjs` — what this fleet actually runs —
+      // never calls it, because a LOCAL marker's liveness is `isPidAlive`.
+      //
+      // So for a local transport there is no heartbeat SOURCE at all. Before
+      // kit#137, `list_agents` stamped these agents and that fabrication was
+      // the only thing keeping the field moving; removing it left the field
+      // honest and empty. Measured: three attached, working agents at an
+      // IDENTICAL 44.7m — the uniform signature of one shared cause, not three
+      // stalls.
+      //
+      // WHY NOT JUST MAKE tmux-pusher HEARTBEAT: because the signal would mean
+      // "the pusher process is alive", which `isPidAlive` already answers for
+      // local markers. During the 17-hour stall every transport was live the
+      // whole time, so a pusher heartbeat would have read FRESH for all 17
+      // hours. It would restore a field without restoring a detector — and the
+      // case this verb exists for is exactly the one it would miss. The vcs
+      // half is what catches "alive and not progressing"; saying so is more
+      // honest than a green field.
+      //
+      // Unknown is not stalled (kit#138). This does NOT narrow Task 3.5: an
+      // agent with no transport, or a REMOTE one where the heartbeat genuinely
+      // is the liveness mechanism, still HITs on a dead heartbeat.
+      const marker = liveTransports.get(agentId);
+      if (age > limit && marker && marker.transport === "tmux-push") {
+        unmeasurable.push({
+          agentId,
+          value: marker.transport,
+          why: `heartbeat is ${Math.round(age / 60000)}m old, but nothing writes heartbeats for a local 'tmux-push' transport — hooks/tmux-pusher.mjs does not call heartbeat, and this marker's liveness is its pid. There is no heartbeat SOURCE here, so the age measures nothing about this agent`,
+        });
+        continue;
+      }
+      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.
+    //
+    // RESOLVE A REF, AND SAY SO WHEN THE VALUE IS NOT ONE.
+    //
+    // `git log -1 <value>` accepts a PATHSPEC exactly as readily as a ref, and
+    // the old guard only required a `/` — which every path has. So the board's
+    // `Branch · Worktree` cells, which hold PATHS, were fed to git and silently
+    // measured as paths: the aide was reported at 2,271 minutes, the age of
+    // `docs/phases/phase5`'s last commit, not of any activity by that agent.
+    // Verified: `docs/phases/phase5` does not resolve as a ref, yet
+    // `git log -1 --format=%cI docs/phases/phase5` returns a date.
+    //
+    // Other rows read plausibly only by coincidence — a path that happens to be
+    // committed often looks like an active branch.
+    //
+    // UNKNOWN IS NOT STALLED, which this verb already gets right for
+    // heartbeats. An unresolvable value is REPORTED as unmeasurable rather than
+    // skipped in silence: a silent `continue` and a healthy agent produce the
+    // same output, which is the failure this whole verb exists to avoid.
+    const raw = (row.branchWorktree.match(/`([^`]+)`/)?.[1] ?? "").trim();
+    if (!raw) {
+      unmeasurable.push({ agentId, value: "", why: "no value in the Branch · Worktree cell" });
+      continue;
+    }
+    let sha = "";
+    try {
+      sha = execFileSync("git", ["rev-parse", "--verify", "--quiet", `${raw}^{commit}`], {
+        cwd: repo, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"],
+      }).trim();
+    } catch {
+      sha = "";
+    }
+    if (!sha) {
+      unmeasurable.push({
+        agentId,
+        value: raw,
+        why: `'${raw}' does not resolve as a git ref — it is a path or glob, and \`git log <path>\` would silently report that PATH's last commit as this agent's activity`,
+      });
+      continue;
+    }
+    try {
+      // The resolved SHA, and `--`: a ref can then never be re-read as a
+      // pathspec, which is the ambiguity that produced the wrong number.
+      const iso = execFileSync("git", ["log", "-1", "--format=%cI", sha, "--"], {
+        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: raw, minutes: Math.round(age / 60000) });
+      }
+    } catch {
+      unmeasurable.push({ agentId, value: raw, why: "resolved as a ref but its log could not be read" });
+    }
+  }
+
+  const result = { hits, checked: inFlight.length, unmeasurable };
+  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${unmeasurable.length ? `; ${unmeasurable.length} row(s) UNMEASURABLE for VCS activity (${unmeasurable.map((u) => u.agentId).join(", ")}) — reported, not counted as healthy` : ""}. No DM. The run IS recorded: read it with stall_clock_status, because no alert and nothing running look identical from here.`
+        : undefined,
+  };
+}