agent-coord-mcp 0.26.11 → 0.26.13

package/src/tools/record-events.ts

@@ -0,0 +1,390 @@
+/*
+ * Phase 5.1 Task 9 — the four subscribable kinds all emit, and the TRIGGER is
+ * the record's COMMITTED CHANGE rather than the `land` verb (David's ruling,
+ * option (b), 2026-08-30).
+ *
+ * WHY NOT (a), "emit from the verbs": it bets on every fleet adopting the
+ * workflow layer, and the only evidence available says they do not — a consumer fleet called
+ * `claim`/`land`/`merge`/`next_unblocked`/`rotate`/`set_halt` ZERO times in a day
+ * of heavy use. A `pr` subscription tested against a real PR came back
+ * `health: error — never evaluated`, and the fleet unsubscribed. Kinds that can
+ * be subscribed to and can never fire are a permanent, honestly-reported error.
+ *
+ * WHAT (b) CHANGES, AND WHAT IT DOES NOT: the record stays the source — only the
+ * trigger moves from the verb to the change. That still satisfies 6.2 ("events
+ * derived from the record, never parallel to it"), because the derivation still
+ * reads the record; it just no longer requires that a particular verb performed
+ * the write. THE POINT IS THAT A HAND-EDIT BECOMES A FIRST-CLASS CAUSE rather
+ * than an invisible one, which is what fleets actually do: they merge with `gh`
+ * and edit `docs/DONE.md` by hand. `land` keeps emitting, as ONE WRITER AMONG
+ * SEVERAL rather than as the gate — the idempotency key makes the overlap safe,
+ * since both paths derive the same key from the same event.
+ *
+ * THE COMMIT IS THE BOUNDARY, not the working tree. An uncommitted edit is not
+ * yet a record: it can be reverted, rebased away, or never pushed, and a
+ * notification for work that then vanishes is worse than a late one.
+ */
+import { execFileSync } from "node:child_process";
+import { newlyTickedInDiff, parseWorkDoc, queueItemsOf, doneEntriesOf } from "@davidbalzan/groundwork-seam";
+import { EVENT_KINDS, type RecordEvent, type SubKind } from "./event-kinds.js";
+export { EVENT_KINDS, EVENT_KIND_IDS } from "./event-kinds.js";
+export type { RecordEvent, SubKind } from "./event-kinds.js";
+
+
+/**
+ * One pass over the diff → per-file added and removed lines.
+ *
+ * Per FILE, not per predicate: the phase rule needs to know WHICH document a
+ * tick came from, and a flat "all added lines" view cannot answer that. It
+ * emitted `phase 5 complete` off a tick in the phase 5.1 document on the first
+ * real-data run.
+ */
+export function diffByFile(diff: string): Map<string, { added: string[]; removed: string[] }> {
+  const out = new Map<string, { added: string[]; removed: string[] }>();
+  let cur: { added: string[]; removed: string[] } | null = null;
+  for (const line of String(diff ?? "").split("\n")) {
+    if (line.startsWith("diff --git ")) { cur = null; continue; }
+    if (line.startsWith("+++ b/")) {
+      const p = line.slice(6).trim();
+      if (p === "/dev/null") { cur = null; continue; }
+      cur = out.get(p) ?? { added: [], removed: [] };
+      out.set(p, cur);
+      continue;
+    }
+    if (line.startsWith("--- a/") || line.startsWith("@@")) continue;
+    if (!cur) continue;
+    if (line.startsWith("+")) cur.added.push(line.slice(1));
+    else if (line.startsWith("-")) cur.removed.push(line.slice(1));
+  }
+  return out;
+}
+
+const isDone = (p: string) => /(^|\/)DONE\.md$/.test(p);
+const isQueue = (p: string) => /(^|\/)QUEUE\.md$/.test(p);
+const isPhaseDoc = (p: string) => /PHASE[^/]*TASKS\.md$/i.test(p);
+
+const linesWhere = (byFile: ReturnType<typeof diffByFile>, match: (p: string) => boolean, side: "added" | "removed") =>
+  [...byFile.entries()].filter(([p]) => match(p)).flatMap(([, v]) => v[side]);
+
+/**
+ * A ref that actually identifies a pull request.
+ *
+ * MEASURED ON REAL DATA, and this is why the check exists: the done-entry
+ * parser splits on the LAST ` — `, so an entry whose own text contains an em
+ * dash yields a "ref" of `aide-verified, coordinator-closed`. Emitting that as
+ * a `pr` event would put a target on the bus that names no PR, and a
+ * subscription could never match it — a silent, permanent miss dressed as a
+ * delivery. Parsing correctly is not the same as the parse MEANING what you
+ * assumed.
+ */
+const PR_REF = /^(?:[\w.-]+\/[\w.-]+#\d+|#\d+|https:\/\/github\.com\/[\w.-]+\/[\w.-]+\/pull\/\d+)$/;
+
+
+/**
+ * EVERY pr ref in a citation field, not "is the whole field one ref".
+ *
+ * MEASURED, and it is the mirror image of the garbage-ref defect: an anchored
+ * whole-field match rejects `owner/repo#170, #173` — a perfectly good citation
+ * that happens to name TWO PRs. A real closure was reported unattributed for
+ * exactly this, and a pair of PRs is the repo's normal house style for work
+ * that landed across two.
+ *
+ * Tightening to reject prose was right. Rejecting a real citation because it
+ * cites more than one thing was not, and from inside a function that only asks
+ * "does the field EQUAL a ref" the two failures are indistinguishable.
+ *
+ * A BARE `#N` IS EXPANDED against a qualified ref in the same field: in
+ * `owner/repo#170, #173` the second plainly means the same repository, and
+ * emitting a bare `#173` would be an under-qualified target that no
+ * subscription written against `owner/repo#173` could ever match.
+ */
+export function prRefsIn(field: string | undefined): string[] {
+  const text = String(field ?? "");
+  const out: string[] = [];
+  for (const m of text.matchAll(/(?:[\w.-]+\/[\w.-]+#\d+|https:\/\/github\.com\/[\w.-]+\/[\w.-]+\/pull\/\d+)/g)) out.push(m[0]);
+  const owner = out[0]?.match(/^([\w.-]+\/[\w.-]+)#/)?.[1];
+  for (const m of text.matchAll(/(?:^|[\s,\u00b7;])#(\d+)\b/g)) {
+    const ref = owner ? `${owner}#${m[1]}` : `#${m[1]}`;
+    if (!out.includes(ref)) out.push(ref);
+  }
+  return out;
+}
+
+/** A citation that closes an item without naming a PR — `owner/repo@sha`. */
+const COMMIT_REF = /@[0-9a-f]{7,40}\b/;
+/** Queue and done text, compared for the pairing below. */
+const norm = (s: string) => String(s).toLowerCase().replace(/[`*_]/g, "").replace(/\s+/g, " ").trim();
+
+/**
+ * Events implied by one committed change.
+ *
+ * `after` carries the documents AS THEY NOW STAND — every event is checked
+ * against them by the caller (`eventIsDerived`), so a diff that has since been
+ * reverted cannot produce an event that outlives the record.
+ */
+export function eventsFromCommittedChange(
+  diff: string,
+  after: { done?: string; phases?: Record<string, string> } = {},
+): RecordEvent[] {
+  const events: RecordEvent[] = [];
+  const unattributedItems: string[] = [];
+  const byFile = diffByFile(diff);
+
+  // ── pr: a new DONE.md entry naming a PR ───────────────────────────────────
+  // Parsed, never regexed off the raw line: the glyph contract (` — ` U+2014,
+  // ` · ` U+00B7) is exact, and a hand-written entry using a plain hyphen must
+  // NOT quietly become an event with a mangled ref. It fails to parse, and a
+  // line that does not parse is not a record entry.
+  const addedDone = linesWhere(byFile, isDone, "added");
+  const newEntries = doneEntriesOf(parseWorkDoc(`## Done\n${addedDone.join("\n")}\n`)) as Array<{ ref?: string; text?: string }>;
+
+  for (const entry of newEntries) {
+    // ONE EVENT PER PR NAMED. An entry closing work that spanned two PRs should
+    // wake a subscriber to either; collapsing to the first makes the second
+    // silently unwatchable.
+    for (const ref of prRefsIn(entry.ref)) {
+      events.push({ kind: "pr", target: ref, ref, summary: entry.text?.slice(0, 120) || ref });
+    }
+  }
+
+  // ── item: a queue item that closed ────────────────────────────────────────
+  //
+  // ATTRIBUTION IS THE WHOLE PROBLEM, and the markdown does not carry it. A
+  // queue item and the DONE entry that closes it share no id and, on real data,
+  // no wording either: the item states what to do and the entry states what was
+  // done. `land` only knows because its caller passed `queueItemId`.
+  //
+  // So: pair on text when the texts DO correspond, otherwise pair only when the
+  // commit is unambiguous — exactly one item removed and exactly one entry
+  // added. Anything else is reported as unattributed rather than guessed. The
+  // naive version attributed all 15 items removed in one real commit to the
+  // first PR it saw, which is a wrong claim about fourteen of them, and a wrong
+  // claim on this bus is worse than a missing one.
+  const removedQueue = linesWhere(byFile, isQueue, "removed");
+  const removedItems = (queueItemsOf(parseWorkDoc(`## Queue\n${removedQueue.join("\n")}\n`)) as Array<{ id?: string; text?: string }>)
+    .filter((i) => i.id);
+  // An entry qualifies to CLOSE an item if it cites anything resolvable — a PR,
+  // or an `@sha` commit. `land` requires a PR by rule; the scan reads what the
+  // record actually says, and a commit-cited entry is still the record stating
+  // that the item closed.
+  const citedEntries = newEntries.filter((e) => prRefsIn(e.ref).length > 0 || COMMIT_REF.test(e.ref ?? ""));
+  const unattributed: string[] = [];
+
+  for (const item of removedItems) {
+    const itemText = norm(item.text ?? "");
+    let entry = itemText
+      ? citedEntries.find((e) => {
+          const t = norm(e.text ?? "");
+          return t && (t === itemText || t.startsWith(itemText) || itemText.startsWith(t));
+        })
+      : undefined;
+    // The unambiguous-commit case: one out, one in. This is the shape the fleet
+    // actually commits ("close its queue item"), and it is the case the aide's
+    // dead `item` subscriptions need.
+    if (!entry && removedItems.length === 1 && citedEntries.length === 1) entry = citedEntries[0];
+    if (!entry) {
+      unattributed.push(item.id!);
+      continue;
+    }
+    // The FIRST pr ref is the item's, falling back to the commit citation: an
+    // item closes once, so it gets one ref, and it is the one a reader follows.
+    const ref = prRefsIn(entry.ref)[0] ?? entry.ref?.trim();
+    if (!ref) {
+      unattributed.push(item.id!);
+      continue;
+    }
+    events.push({ kind: "item", target: item.id!, ref, summary: entry.text?.slice(0, 120) ?? item.id! });
+  }
+  if (unattributed.length) unattributedItems.push(...unattributed);
+
+  // ── task: checkbox transitions ────────────────────────────────────────────
+  // `newlyTickedInDiff` requires BOTH a removed open box and an added ticked one
+  // for the same id, so a moved or reformatted line cannot manufacture a
+  // completion — that rule is the seam's and is reused rather than re-derived.
+  const ticked = [...newlyTickedInDiff(diff)];
+  const tickedLines = linesWhere(byFile, isPhaseDoc, "added");
+  for (const key of ticked) {
+    const id = key.split(":")[1] ?? "";
+    // Ref is the ticked LINE, not the bare id: `12.1` appears in prose all over
+    // a phase doc, so a bare id would pass the derivation check against a
+    // document that never ticked anything.
+    const line = tickedLines.find((l) => new RegExp(`^\\s*-\\s*\\[x\\]\\s*\\*{0,2}${id.replace(".", "\\.")}\\b`, "i").test(l));
+    if (!line) continue;
+    events.push({ kind: "task", target: key, ref: line.trim(), summary: line.trim().slice(0, 120) });
+  }
+
+  // ── phase: the last open box in ONE document ──────────────────────────────
+  // Keyed on the FILE, both for "is it complete" and for "did this change close
+  // it". `newlyTickedInDiff` keys ticks by the integer in the path, so
+  // `phase5.1` and `phase5` collapse to the same `5:` — the first real-data run
+  // announced PHASE 5 COMPLETE on the strength of a tick in the 5.1 document.
+  // A false completion is worse than a missing one: it closes a phase nobody
+  // finished.
+  for (const [rel, text] of Object.entries(after.phases ?? {})) {
+    if (!isPhaseDoc(rel)) continue;
+    const boxes = [...String(text).matchAll(/^\s*-\s*\[( |x)\]\s*\*{0,2}(\d+\.\d+[a-z]?)\b/gim)];
+    if (!boxes.length || boxes.some((m) => m[1] !== "x")) continue;
+    // This commit must have ticked a box IN THIS FILE.
+    const closedHere = (byFile.get(rel)?.added ?? []).some((l) => /^\s*-\s*\[x\]\s*\*{0,2}\d+\.\d+/.test(l));
+    if (!closedHere) continue;
+    const phase = /phase(\d+(?:\.\d+)?)/i.exec(rel)?.[1];
+    if (!phase) continue;
+    events.push({ kind: "phase", target: phase, ref: boxes[boxes.length - 1]![0].trim(), summary: `phase ${phase} — every task box ticked` });
+  }
+
+  lastUnattributedItems = unattributedItems;
+  return events;
+}
+
+/**
+ * Queue item ids removed in the last scanned change that could NOT be tied to a
+ * done entry. Reported by `scan_record_events` rather than dropped: "we saw
+ * items close and could not say which PR closed them" and "nothing closed" are
+ * different facts, and only one of them needs a human.
+ */
+export let lastUnattributedItems: string[] = [];
+
+/** `git` in a repo, returning "" rather than throwing — a scan is read-only. */
+export function git(repo: string, args: string[]): string {
+  try {
+    return execFileSync("git", args, { cwd: repo, encoding: "utf8", maxBuffer: 32 * 1024 * 1024 });
+  } catch {
+    return "";
+  }
+}
+
+/* ── the verb ──────────────────────────────────────────────────────────────── */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import path from "node:path";
+import { z } from "zod";
+import { ROOT } from "../store.js";
+import { readSubs, evaluate, commitEvaluation, eventIsDerived } from "./events.js";
+
+/**
+ * The watermark: the last commit whose record change has been turned into
+ * events, per repo.
+ *
+ * It is stored rather than inferred, because "what have I already emitted" is
+ * not derivable from the repo — and the alternative, re-deriving from some
+ * fixed point every time, would re-announce a year of closures on first run.
+ * Losing the file is safe in the direction that matters: the idempotency key is
+ * derived from the EVENT, so a re-scan of already-delivered events reports
+ * `duplicate-suppressed` rather than waking anyone twice.
+ */
+const watermarkFile = () => path.join(ROOT, "record-events.json");
+
+type Watermarks = Record<string, { sha: string; at: number }>;
+
+function readWatermarks(): Watermarks {
+  const f = watermarkFile();
+  if (!existsSync(f)) return {};
+  try {
+    return (JSON.parse(readFileSync(f, "utf8")).repos ?? {}) as Watermarks;
+  } catch {
+    return {};
+  }
+}
+
+function writeWatermark(repo: string, sha: string): void {
+  mkdirSync(ROOT, { recursive: true });
+  const all = readWatermarks();
+  all[repo] = { sha, at: Date.now() };
+  writeFileSync(watermarkFile(), `${JSON.stringify({ repos: all }, null, 2)}\n`);
+}
+
+export const scanRecordEventsSchema = {
+  repo: z.string().min(1),
+  /** Defaults to the stored watermark; first run with none scans HEAD~1..HEAD. */
+  since: z.string().optional(),
+  /** Report only. Default true — same posture as `land` and `next_unblocked`. */
+  write: z.boolean().optional(),
+};
+
+export async function scanRecordEventsTool(args: { repo: string; since?: string; write?: boolean }) {
+  const repo = path.resolve(args.repo);
+  if (!existsSync(path.join(repo, ".git"))) {
+    return { ok: false as const, error: `'${repo}' is not a git repository — the commit is the boundary for a record change, so there is nothing to scan` };
+  }
+
+  const head = git(repo, ["rev-parse", "HEAD"]).trim();
+  if (!head) return { ok: false as const, error: `could not resolve HEAD in ${repo}` };
+
+  const stored = readWatermarks()[repo]?.sha;
+  const since = args.since ?? stored ?? `${head}~1`;
+  // A watermark from a rebased-away commit resolves to nothing. Say so rather
+  // than silently falling back to HEAD~1 and reporting a one-commit scan as if
+  // it covered the gap — that is the shape where a miss looks like a clean run.
+  if (!git(repo, ["cat-file", "-e", `${since}^{commit}`]) && !git(repo, ["rev-parse", "--verify", `${since}^{commit}`]).trim()) {
+    return {
+      ok: false as const,
+      error:
+        `base '${since}' does not resolve in ${repo} — it was probably rebased away. ` +
+        `Nothing was scanned and the watermark was NOT advanced: a scan that silently narrows its window ` +
+        `reports a clean run over the commits it never looked at. Pass an explicit 'since'.`,
+    };
+  }
+
+  const diff = git(repo, ["diff", "--unified=0", `${since}..${head}`, "--", "docs/"]);
+  const doneText = existsSync(path.join(repo, "docs/DONE.md")) ? readFileSync(path.join(repo, "docs/DONE.md"), "utf8") : "";
+  const phases: Record<string, string> = {};
+  for (const rel of git(repo, ["ls-files", "docs/phases/"]).split("\n").filter((p) => /PHASE[^/]*TASKS\.md$/i.test(p))) {
+    const p = path.join(repo, rel);
+    if (existsSync(p)) phases[rel] = readFileSync(p, "utf8");
+  }
+
+  const candidates = eventsFromCommittedChange(diff, { done: doneText, phases });
+  const unattributed = [...lastUnattributedItems];
+
+  // Every event is checked against the record AS IT NOW STANDS (6.2). A change
+  // that has since been reverted produces a candidate the record no longer
+  // supports, and it is refused — the stream can never claim what the
+  // authoritative markdown does not.
+  const emitted: RecordEvent[] = [];
+  const refused: string[] = [];
+  for (const ev of candidates) {
+    const recordText = ev.kind === "task" || ev.kind === "phase" ? Object.values(phases).join("\n") : doneText;
+    const derived = eventIsDerived(recordText, ev);
+    if (derived.ok) emitted.push(ev);
+    else refused.push(derived.error);
+  }
+
+  const deliveries: unknown[] = [];
+  if (args.write) {
+    let subs = readSubs();
+    const now = Date.now();
+    for (const ev of emitted) {
+      const r = evaluate(subs, ev, now);
+      subs = r.subs;
+      deliveries.push(...r.deliveries);
+    }
+    commitEvaluation(subs);
+    writeWatermark(repo, head);
+  }
+
+  return {
+    ok: true as const,
+    repo,
+    scanned: { from: since, to: head },
+    emitted,
+    refused,
+    deliveries,
+    ...(unattributed.length
+      ? {
+          unattributedItems: unattributed,
+          unattributedNote:
+            `${unattributed.length} queue item(s) left docs/QUEUE.md in this range without a done entry they could be tied to. ` +
+            `They emitted NOTHING: the markdown carries no link between an item and the entry that closes it, so attributing them ` +
+            `would be a guess. "Closed by an unknown PR" and "not closed" are different facts and this is the first.`,
+        }
+      : {}),
+    ...(args.write
+      ? { watermark: head }
+      : {
+          note:
+            "REPORT ONLY — nothing was delivered and the watermark was not advanced. Pass write:true to deliver. " +
+            "Re-scanning an already-delivered range is safe: the idempotency key is derived from the event, so it reports duplicate-suppressed.",
+        }),
+    kinds: EVENT_KINDS,
+  };
+}

package/src/tools/registry.ts

@@ -363,8 +363,17 @@ export async function listAgentsTool() {
     const { lastHeartbeat, ...rest } = a;
     const heartbeatFields = transport
       ? {
+          // NOT "refreshed BY this call" — that write was removed in #137
+          // precisely because it stamped every OTHER fleet's agents too
+          // (agents.json is shared, list_agents takes no project argument).
+          // Measured after the removal (Task 13.5): calling list_agents and
+          // re-reading agents.json directly leaves lastHeartbeat UNCHANGED.
+          // The field is omitted because the value is STALE-BY-DESIGN for a
+          // live-transport agent, not because this call would overwrite it —
+          // an explanation that outlived the code it explained is the same
+          // carrier-gap shape as a stated cause nobody re-checked.
           heartbeatSource:
-            "omitted — this agent has a live transport, so its heartbeat is refreshed BY this call and would report the caller's own timestamp. Liveness is `online`/`transport`; for per-agent freshness read from server state, use `ping`.",
+            "omitted — a live-transport agent's raw lastHeartbeat measures time since it last JOINED, not activity (nothing else writes it for a local transport; Task 13.3/13.4). Liveness is `online`/`transport`; for per-agent freshness read from server state, use `ping`.",
         }
       : { lastHeartbeat, secondsSinceHeartbeat: Math.floor((now - lastHeartbeat) / 1000) };
     return {

package/src/tools/stall.ts

@@ -93,9 +93,9 @@ export function markRunFailure(reason: string): void {
   writeFileSync(runFile(), JSON.stringify({ history: history.slice(-200) }, null, 2));
 }
 
-type RunMark = { at: number; hits: number; checked: number; failed?: string };
+type RunMark = { at: number; hits: number; checked: number; measurable?: number; failed?: string };
 
-function markRun(result: { hits: StallHit[]; checked: number }) {
+function markRun(result: { hits: StallHit[]; checked: number; measurable?: number }) {
   mkdirSync(ROOT, { recursive: true });
   let history: RunMark[] = [];
   try {
@@ -103,7 +103,12 @@ function markRun(result: { hits: StallHit[]; checked: number }) {
   } catch {
     /* first run */
   }
-  history.push({ at: Date.now(), hits: result.hits.length, checked: result.checked });
+  // COVERAGE IS RECORDED WITH THE RUN, because a status tool that cannot
+  // express its own blindness is worse than no status tool. Measured: the clock
+  // reported `runs 8, failures 0` — all green — while every one of those runs
+  // had covered 0 of 3 agents. Nothing in the mark could say so, and this is the
+  // instrument meant to cover an absence.
+  history.push({ at: Date.now(), hits: result.hits.length, checked: result.checked, measurable: result.measurable ?? 0 });
   // 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.
@@ -114,7 +119,7 @@ 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.
+ * MISS is silent to the WATCHER, not to the record.
  */
 export async function stallClockStatusTool(args: { maxAgeMinutes?: number }) {
   const maxAge = (args.maxAgeMinutes ?? 60) * 60 * 1000;
@@ -150,11 +155,19 @@ export async function stallClockStatusTool(args: { maxAgeMinutes?: number }) {
   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;
+  // A RUN THAT COVERED NOTHING IS NOT A RUN THAT FOUND NOTHING. Marks written
+  // before coverage was recorded carry no `measurable` field: they are reported
+  // as UNKNOWN rather than assumed covered, because assuming is what produced
+  // the green this exists to correct.
+  const graded = history.filter((h) => !h.failed && typeof h.measurable === "number");
+  const blindRuns = graded.filter((h) => h.checked > 0 && h.measurable === 0).length;
+  const ungraded = history.filter((h) => !h.failed && typeof h.measurable !== "number").length;
+  const lastBlind = last && !last.failed && (last.checked ?? 0) > 0 && last.measurable === 0;
   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,
+    ok: !stale && !lastFailed && !lastBlind,
     ...(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.`,
@@ -163,12 +176,28 @@ export async function stallClockStatusTool(args: { maxAgeMinutes?: number }) {
         ? {
             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.`,
           }
-        : {}),
+        : lastBlind
+          ? {
+              error:
+                `the clock is RUNNING and BLIND: its last run checked ${last?.checked} in-flight row(s) and could measure ${last?.measurable} of them. ` +
+                `It fires on schedule, reports no hits, and that "no hits" is not evidence of a healthy fleet — it is evidence of nothing. ` +
+                `Read stall_check's own 'unmeasurable' list for the cause; the usual one is a board 'Branch · Worktree' cell holding a PATH rather than a branch ref.`,
+            }
+          : {}),
     lastRanMinutesAgo: Math.round(age / 60000),
     runs: history.length,
     misses,
     hits,
     failures: failures.length,
+    // The number the old shape could not express.
+    coverage: {
+      lastRun: last && !last.failed ? { checked: last.checked, measurable: last.measurable ?? null } : null,
+      blindRuns,
+      ungraded,
+      note:
+        "blindRuns are runs that checked rows and measured none of them — green by every other field. " +
+        "ungraded are marks written before coverage was recorded: UNKNOWN, never assumed covered.",
+    },
   };
 }
 
@@ -190,10 +219,27 @@ export async function stallCheckTool(args: { repo?: string; stallMinutes?: numbe
   const hits: StallHit[] = [];
   /** Rows whose VCS activity could not be measured. NOT stall claims. */
   const unmeasurable: { agentId: string; value: string; why: string }[] = [];
+  /**
+   * Rows a predicate actually reached a VERDICT about — hit or clean.
+   *
+   * Tracked explicitly rather than inferred from "2 predicates minus the
+   * unmeasurable ones", because a predicate that is SKIPPED pushes no
+   * unmeasurable entry and the arithmetic then counts it as having measured.
+   * That is the same defect as the `continue` above, one level up: a silent
+   * skip and a clean pass produce the same number.
+   */
+  const measured = new Set<string>();
 
   for (const row of inFlight) {
     const agentId = row.owner.replace(/[`*]/g, "").trim();
     const entry = reg[agentId];
+    if (!entry) {
+      // NOT SKIPPED IN SILENCE. An owner with no registry entry has no
+      // heartbeat to read, which is a missing signal and must be reported as
+      // one — a row whose owner the bus has never heard of is exactly the row
+      // you would want named before going away.
+      unmeasurable.push({ agentId, value: "", why: "no registry entry for this owner — there is no heartbeat to read, and the name may not be an agent id at all" });
+    }
     if (entry) {
       const age = now - entry.lastHeartbeat;
       // A HEARTBEAT IS ONLY EVIDENCE WHERE SOMETHING WRITES ONE.
@@ -230,12 +276,51 @@ export async function stallCheckTool(args: { repo?: string; stallMinutes?: numbe
           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) {
+        // FALL THROUGH TO THE VCS PREDICATE — do not `continue`.
+        //
+        // This used to skip the row entirely, and the consequence was total: on
+        // this fleet, 3 of 3 in-flight rows were local tmux-push agents, so
+        // EVERY row exited here and the check reported `checked 3 · measurable
+        // 0`. The half that was blind (heartbeat, deliberately, for the reason
+        // above) was taking the half that works (vcs activity) down with it.
+        //
+        // The two predicates answer different questions and only one of them is
+        // unanswerable for a local transport. "Is it alive" has no source here;
+        // "is its branch moving" has a perfectly good one, and it is the half
+        // that catches the case this verb exists for — alive and not
+        // progressing. An unmeasurable heartbeat is a missing signal, not a
+        // reason to stop measuring the signal that is present.
+      } else if (age > limit) {
         hits.push({ kind: "no-heartbeat", agentId, stream: row.stream.slice(0, 60), minutes: Math.round(age / 60000) });
+        measured.add(agentId);
         continue;
       }
+      // A FRESH HEARTBEAT IS *NOT* A VERDICT, AND THIS IS A CORRECTION TO WHAT
+      // THIS CODE CLAIMED WHEN IT MERGED.
+      //
+      // It read "a fresh heartbeat IS a verdict — alive" and credited coverage
+      // for it. Measured since, by reading agents.json directly (`list_agents`
+      // refreshes the CALLER's mark, so it cannot be used to measure the
+      // caller): an agent's mark aged from 9611s to 9623s across a `post_status`
+      // call. BUS TOOL CALLS DO NOT WRITE HEARTBEATS.
+      //
+      // `heartbeat` age is TIME SINCE JOIN. Not activity, and not even
+      // time-since-restart — a server can restart mid-session without the mark
+      // moving, because nothing rejoined. So freshness says "recently joined",
+      // and crediting it as coverage lets `/coord-away` arm on a fleet whose
+      // only evidence is that somebody reconnected.
+      //
+      // The inverse is worse and is why this is not merely tidiness: reading
+      // age as activity marks the two most CONTINUOUSLY ACTIVE agents on a bus
+      // as stale at 2.6h, while a freshly-rejoined idle agent reads healthy —
+      // a false-stall generator aimed at exactly the agents that must not be
+      // false-stalled while nobody is watching.
+      //
+      // The HIT above is kept: for an agent with no transport at all, "has not
+      // rejoined and has no live marker" is still the death signal Task 3.5
+      // specifies. What is removed is the coverage credit for freshness, which
+      // leaves coverage resting on the vcs predicate — the one that measures
+      // something the agent DID.
     }
     // 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
@@ -286,6 +371,7 @@ export async function stallCheckTool(args: { repo?: string; stallMinutes?: numbe
         cwd: repo, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"],
       }).trim();
       const age = now - Date.parse(iso);
+      measured.add(agentId);
       if (age > limit) {
         hits.push({ kind: "no-vcs-activity", agentId, branch: raw, minutes: Math.round(age / 60000) });
       }
@@ -294,8 +380,15 @@ export async function stallCheckTool(args: { repo?: string; stallMinutes?: numbe
     }
   }
 
-  const result = { hits, checked: inFlight.length, unmeasurable };
-  markRun(result);
+  // COVERAGE, not "did it run". A row is COVERED when at least one predicate
+  // produced a verdict about it; a row where every predicate came back
+  // unmeasurable was looked at and not measured, and counting it as checked is
+  // how "the clock ran" gets mistaken for "the fleet is observed".
+  const owners = inFlight.map((r) => r.owner.replace(/[`*]/g, "").trim()).filter(Boolean);
+  const blind = [...new Set(owners)].filter((id) => !measured.has(id));
+  const measurable = Math.max(0, inFlight.length - blind.length);
+  const result = { hits, checked: inFlight.length, unmeasurable, measurable, blind };
+  markRun({ hits, checked: inFlight.length, measurable });
   return {
     ok: true as const,
     ...result,

package/src/tools/transport.ts

@@ -124,7 +124,20 @@ export async function pingTool(args: { from: string; to: string; echo?: boolean
   }
 
   const reachable = transportLive && paneAlive !== false;
-  const alive = reachable || heartbeatFresh;
+  // heartbeatFresh is only valid EVIDENCE where something writes a heartbeat.
+  // A local tmux-push transport's liveness is its pid (isPidAlive) —
+  // hooks/tmux-pusher.mjs never calls `heartbeat`, so the field measures time
+  // since JOIN, not activity (Task 13.3/13.4, stall.ts's own established
+  // rule for exactly this transport type). Crediting it here for a
+  // tmux-push agent produced the incident this fix exists for: `alive` and
+  // `reachable` read fully healthy, `heartbeatFresh` sat in `checks` reading
+  // false, and the top-line boolean never surfaced the disagreement — a
+  // status layer discarding what its own lower layer already reported, the
+  // same shape as `stall_clock_status` before Task 13.1. A REMOTE pusher, or
+  // an agent with no probeable marker at all, has no pid to fall back on —
+  // there heartbeat genuinely IS the liveness mechanism, unchanged.
+  const heartbeatIsValidSignal = !marker || marker.transport !== "tmux-push";
+  const alive = reachable || (heartbeatIsValidSignal && heartbeatFresh);
 
   let echoSent = false;
   if (args.echo && alive) {
@@ -146,6 +159,11 @@ export async function pingTool(args: { from: string; to: string; echo?: boolean
       registered: true,
       heartbeatFresh,
       heartbeatAgeSec,
+      // Whether heartbeatFresh above is real evidence for this transport, or
+      // just time-since-join. A reader who sees `heartbeatFresh: false` next
+      // to `heartbeatValid: false` should not read that as a dissenting
+      // signal — there is no signal there to dissent.
+      heartbeatValid: heartbeatIsValidSignal,
       transport: marker?.transport ?? null,
       transportLive,
       ...(paneAlive !== undefined ? { paneAlive, tmuxTarget: marker?.tmuxTarget } : {}),