agent-coord-mcp 0.26.6 → 0.26.8

package/src/tools/events.ts

@@ -0,0 +1,199 @@
+/*
+ * Event subscriptions — stop relying on someone CHOOSING to tell you.
+ *
+ * The bus is almost entirely direct messaging: an agent learns something
+ * happened because another agent decided to say so. Every miss this week was a
+ * missing NOTIFICATION rather than a missing capability — two mergeable PRs sat
+ * 17 hours because nobody told the coordinator to gate, the console's trigger
+ * ran zero times because nothing woke it, and `stall_check` runs only when a
+ * human types it.
+ */
+import { createHash, randomUUID } from "node:crypto";
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import path from "node:path";
+import { z } from "zod";
+import { ROOT } from "../store.js";
+
+const subsFile = () => path.join(ROOT, "subscriptions.json");
+
+export type SubKind = "task" | "phase" | "item" | "pr";
+export type Subscription = {
+  id: string;
+  agentId: string;
+  kind: SubKind;
+  target: string;
+  createdAt: number;
+  /** null until this subscription has been EVALUATED at least once. */
+  lastEvaluatedAt: number | null;
+  lastEventAt: number | null;
+  /** Idempotency keys already delivered, for 6.4. */
+  delivered: string[];
+};
+
+export function readSubs(): Subscription[] {
+  const f = subsFile();
+  if (!existsSync(f)) return [];
+  try {
+    return (JSON.parse(readFileSync(f, "utf8")).subscriptions ?? []) as Subscription[];
+  } catch {
+    return [];
+  }
+}
+
+function writeSubs(subs: Subscription[]): void {
+  mkdirSync(ROOT, { recursive: true });
+  writeFileSync(subsFile(), `${JSON.stringify({ subscriptions: subs }, null, 2)}\n`);
+}
+
+/**
+ * 6.3 — A SUBSCRIPTION THAT NEVER FIRES MUST BE DISTINGUISHABLE FROM ONE NEVER
+ * REGISTERED, so never-evaluated is an ERROR rather than a quiet zero.
+ *
+ * We hit the absence of this rule twice in two days: the console's standing
+ * trigger and `stall_check`'s clock both looked healthy while never running. A
+ * subscription with no last-evaluated mark has produced no evidence of
+ * anything, and "no events" is the same output a broken subscription gives.
+ */
+export function subscriptionHealth(s: Subscription): { level: "ok" | "error"; detail: string } {
+  if (s.lastEvaluatedAt === null)
+    return {
+      level: "error",
+      detail: `never evaluated — this subscription has produced no evidence it is wired to anything. "No events yet" and "never ran" are the same output, and only one of them is healthy.`,
+    };
+  return {
+    level: "ok",
+    detail: s.lastEventAt
+      ? `last evaluated ${new Date(s.lastEvaluatedAt).toISOString()}, last event ${new Date(s.lastEventAt).toISOString()}`
+      : `last evaluated ${new Date(s.lastEvaluatedAt).toISOString()}, no events yet — evaluated and quiet, which is different from never run`,
+  };
+}
+
+/**
+ * 6.4 — DELIVERY IS AT-LEAST-ONCE BY DESIGN. Safe for a reader, DOUBLE
+ * EXECUTION for an executor: a callback that triggers work must carry a key, or
+ * the same merge lands twice. The key is derived from the EVENT, never from the
+ * delivery attempt, so a retry produces the same key.
+ */
+export const eventKey = (kind: SubKind, target: string, ref: string): string =>
+  createHash("sha256").update(`${kind}:${target}:${ref}`).digest("hex").slice(0, 16);
+
+export type RecordEvent = { kind: SubKind; target: string; ref: string; summary: string };
+
+/**
+ * 6.2 — EVENTS ARE DERIVED FROM THE RECORD, NEVER PARALLEL TO IT.
+ *
+ * Enforced here rather than promised in a comment: the event's `ref` must
+ * already be present in the record document before anything is emitted. An
+ * event stream that can say "task X complete" while DONE.md does not is a
+ * second source of truth, and record-vs-state divergence is the defect this
+ * fleet hit most this week. ADR-003 keeps markdown authoritative, and this must
+ * not quietly reopen it.
+ *
+ * So the ordering is not a convention: emission READS the record, and an event
+ * whose cause is not in the record cannot be emitted at all.
+ */
+export function eventIsDerived(recordText: string, ev: RecordEvent): { ok: true } | { ok: false; error: string } {
+  if (!ev.ref) return { ok: false, error: `event for ${ev.kind} ${ev.target} carries no ref — nothing ties it to a record entry` };
+  if (!String(recordText).includes(ev.ref))
+    return {
+      ok: false,
+      error:
+        `refusing to emit ${ev.kind} ${ev.target}: its ref ${ev.ref} is NOT in the record. ` +
+        `An event that exists without the record change that caused it is a second source of truth — ` +
+        `the stream would claim something the authoritative document does not.`,
+    };
+  return { ok: true };
+}
+
+/** Subscriptions matching an event. Exact target match; no wildcards yet. */
+export const matching = (subs: Subscription[], ev: RecordEvent): Subscription[] =>
+  subs.filter((s) => s.kind === ev.kind && s.target === ev.target);
+
+export type Delivery = { subscriptionId: string; agentId: string; key: string; status: "delivered" | "duplicate-suppressed" };
+
+/**
+ * Evaluate every subscription against one event and return what to deliver.
+ *
+ * EVALUATION IS RECORDED EVEN WHEN NOTHING MATCHES — that is 6.3's whole point.
+ * A subscription only learns it is alive by being evaluated, so the mark is
+ * written for every subscription of that kind, not only the ones that fired.
+ */
+export function evaluate(subs: Subscription[], ev: RecordEvent, now: number): { subs: Subscription[]; deliveries: Delivery[] } {
+  const key = eventKey(ev.kind, ev.target, ev.ref);
+  const deliveries: Delivery[] = [];
+  const next = subs.map((s) => {
+    if (s.kind !== ev.kind) return s;
+    const evaluated = { ...s, lastEvaluatedAt: now };
+    if (s.target !== ev.target) return evaluated;
+    if (s.delivered.includes(key)) {
+      deliveries.push({ subscriptionId: s.id, agentId: s.agentId, key, status: "duplicate-suppressed" });
+      return evaluated;
+    }
+    deliveries.push({ subscriptionId: s.id, agentId: s.agentId, key, status: "delivered" });
+    return { ...evaluated, lastEventAt: now, delivered: [...s.delivered, key].slice(-200) };
+  });
+  return { subs: next, deliveries };
+}
+
+/* ── verbs ─────────────────────────────────────────────────────────────────── */
+
+export const subscribeSchema = {
+  agentId: z.string().min(1),
+  kind: z.enum(["task", "phase", "item", "pr"]),
+  target: z.string().min(1),
+};
+
+export async function subscribeTool(args: { agentId: string; kind: SubKind; target: string }) {
+  const subs = readSubs();
+  const dupe = subs.find((s) => s.agentId === args.agentId && s.kind === args.kind && s.target === args.target);
+  if (dupe) return { ok: true as const, subscription: dupe, note: "already subscribed — returning the existing registration rather than a second one" };
+  const sub: Subscription = {
+    id: randomUUID(),
+    agentId: args.agentId,
+    kind: args.kind,
+    target: args.target,
+    createdAt: Date.now(),
+    lastEvaluatedAt: null,
+    lastEventAt: null,
+    delivered: [],
+  };
+  writeSubs([...subs, sub]);
+  return { ok: true as const, subscription: sub, health: subscriptionHealth(sub) };
+}
+
+export const unsubscribeSchema = { agentId: z.string().min(1), id: z.string().min(1) };
+
+export async function unsubscribeTool(args: { agentId: string; id: string }) {
+  const subs = readSubs();
+  const sub = subs.find((s) => s.id === args.id);
+  if (!sub) return { ok: false as const, error: `no subscription '${args.id}'` };
+  // Another agent's subscription is not yours to remove: silently dropping
+  // someone else's notification is how a miss is manufactured.
+  if (sub.agentId !== args.agentId) return { ok: false as const, error: `subscription '${args.id}' belongs to '${sub.agentId}', not '${args.agentId}'` };
+  writeSubs(subs.filter((s) => s.id !== args.id));
+  return { ok: true as const, removed: sub };
+}
+
+export const listSubscriptionsSchema = { agentId: z.string().optional() };
+
+export async function listSubscriptionsTool(args: { agentId?: string }) {
+  const all = readSubs();
+  const subs = args.agentId ? all.filter((s) => s.agentId === args.agentId) : all;
+  const rows = subs.map((s) => ({ ...s, health: subscriptionHealth(s) }));
+  const neverEvaluated = rows.filter((r) => r.health.level === "error");
+  return {
+    ok: neverEvaluated.length === 0,
+    // Population beside the verdict, always: "no subscriptions" and "none
+    // listed for you" are different claims.
+    population: { listed: rows.length, total: all.length },
+    subscriptions: rows,
+    ...(neverEvaluated.length
+      ? { error: `${neverEvaluated.length} of ${rows.length} subscription(s) have NEVER been evaluated — they have produced no evidence of being wired to anything.` }
+      : {}),
+  };
+}
+
+/** Persist an evaluation. Callers do this after a record write, never before. */
+export function commitEvaluation(next: Subscription[]): void {
+  writeSubs(next);
+}

package/src/tools/logwatch.ts

@@ -0,0 +1,107 @@
+/*
+ * Task 8 — a watch over an append-only log, keyed on FILE OFFSET.
+ *
+ * A WATCH MUST NOT BE ABLE TO CONSUME. This is Task 7.1's rule at its second
+ * caller, not a second fix: the read cursor records what the AGENT has taken
+ * delivery of, and only the agent reading may advance it. A pusher typing into
+ * a pane is a reader; a watch waiting for traffic is a reader; neither may
+ * consume on the agent's behalf.
+ *
+ * So this keeps its OWN position — `lastLineSeen` — and never touches
+ * `cursors/<id>.json`. A watch that advanced the read cursor would reproduce
+ * exactly the defect Task 7 removed, one component over: the message would be
+ * marked consumed by something that only looked at it.
+ *
+ * WHY THIS DOES NOT VIOLATE 6.2 (8.5). "Events are derived from the record,
+ * never parallel to it." The room and inbox JSONL logs ARE the record — they
+ * are the authoritative store, not a projection of one. `land`'s events are
+ * derived from a document write; these are derived from the log itself. Both
+ * read the authoritative artifact and neither maintains a second source of
+ * truth. The test for a violation is whether the stream could assert something
+ * the record does not, and it cannot: every event here IS a line in the log,
+ * identified by its offset in that log.
+ *
+ * Keyed on OFFSET rather than timestamp or id, because an offset is a property
+ * of the log itself. Two lines can share a `ts`, an id can be rewritten, and a
+ * clock can disagree with another clock — a line's position cannot.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { z } from "zod";
+import { ROOT } from "../store.js";
+
+export type LogKind = "room" | "inbox";
+
+export type LogWatch = {
+  id: string;
+  agentId: string;
+  kind: LogKind;
+  target: string;
+  createdAt: number;
+  /** null until evaluated at least once — never-evaluated is an ERROR (8.3). */
+  lastEvaluatedAt: number | null;
+  /** The offset this watch has REPORTED up to. Never the read cursor. */
+  lastLineSeen: number;
+};
+
+export const logFileFor = (kind: LogKind, target: string): string =>
+  kind === "room" ? path.join(ROOT, "rooms", `${target}.jsonl`) : path.join(ROOT, "inbox", `${target}.jsonl`);
+
+/** Parsed lines of a log. Malformed lines are SKIPPED but still counted. */
+export function readLog(file: string): { entries: unknown[]; total: number } {
+  if (!existsSync(file)) return { entries: [], total: 0 };
+  const lines = readFileSync(file, "utf8").split("\n").filter((l) => l.trim());
+  const entries: unknown[] = [];
+  for (const l of lines) {
+    try {
+      entries.push(JSON.parse(l));
+    } catch {
+      // A malformed line still OCCUPIES an offset. Skipping it without counting
+      // would shift every subsequent line's position by one and silently
+      // re-report the whole tail.
+      entries.push(null);
+    }
+  }
+  return { entries, total: lines.length };
+}
+
+export type LogEvent = { kind: LogKind; target: string; offset: number; line: unknown };
+
+/**
+ * Lines appended since `lastLineSeen`.
+ *
+ * A TRUNCATED LOG IS NOT A QUIET ONE. If the file is SHORTER than the watch's
+ * position, something rewrote or pruned it — reporting "no new lines" would be
+ * indistinguishable from a healthy quiet period. It is surfaced instead.
+ */
+export function newLines(
+  watch: Pick<LogWatch, "kind" | "target" | "lastLineSeen">,
+  log: { entries: unknown[]; total: number },
+): { events: LogEvent[]; truncated: boolean; total: number } {
+  if (log.total < watch.lastLineSeen)
+    return { events: [], truncated: true, total: log.total };
+  const events: LogEvent[] = [];
+  for (let i = watch.lastLineSeen; i < log.total; i++) {
+    events.push({ kind: watch.kind, target: watch.target, offset: i, line: log.entries[i] ?? null });
+  }
+  return { events, truncated: false, total: log.total };
+}
+
+/** 8.3 — health, identical in shape to the record subscriptions, plus lastLineSeen. */
+export function watchHealth(w: LogWatch): { level: "ok" | "error"; detail: string } {
+  if (w.lastEvaluatedAt === null)
+    return {
+      level: "error",
+      detail: `never evaluated — this watch has produced no evidence it is attached to anything. "No lines yet" and "never ran" are the same output, and only one of them is healthy.`,
+    };
+  return {
+    level: "ok",
+    detail: `last evaluated ${new Date(w.lastEvaluatedAt).toISOString()}, reported up to line ${w.lastLineSeen}`,
+  };
+}
+
+export const logWatchSchema = {
+  agentId: z.string().min(1),
+  kind: z.enum(["room", "inbox"]),
+  target: z.string().min(1),
+};

package/src/tools/messaging.ts

@@ -7,6 +7,7 @@ import { promises as fsp } from "node:fs";
 import { spawn, spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { z } from "zod";
+import { readLog } from "./logwatch.js";
 import { renderRecord } from "./render.js";
 import path from "node:path";
 import {
@@ -660,6 +661,30 @@ export async function waitForMessageTool(args: {
   // readMessagesTool now filters out for room/status) doesn't return an empty
   // result — keep waiting until we have something to deliver or time out.
   while (Date.now() < deadline) {
+    // ALREADY-UNREAD CONTENT WAKES THIS IMMEDIATELY.
+    //
+    // The loop below waits for the file to GROW from the size captured at entry,
+    // so anything that arrived before the wait started could not wake it: the
+    // agent sat through the full timeout with messages readable the whole time.
+    // Seven real posts landed across consecutive 60s waits that all returned
+    // `timedOut`, while `read_messages` returned every one.
+    //
+    // Growth is the wrong question on its own — "is there anything for me" is
+    // the right one, and it is also the cheaper check.
+    const pending = await readMessagesTool({ agentId: args.agentId, source: args.source, room: args.room });
+    if (pending.messages.length > 0) return { ...pending, waited: true, timedOut: false };
+
+    // 8.4 — THE SAME POSITION THE WATCH USES, not a second mechanism beside it.
+    //
+    // This compared byte SIZE, which answers "did the file grow" — a proxy for
+    // "is there a new line". The watch keys on LINE OFFSET, which is the thing
+    // itself, and reusing it means the wait and the watch cannot disagree about
+    // what "new" means. A second mechanism beside the first is how two answers
+    // to one question start drifting.
+    //
+    // It still consumes nothing by itself: the offset is read, never written
+    // back to the cursor (8.2).
+    const startLines = readLog(file).total;
     const startSize = await fileSize(file);
     const remaining = deadline - Date.now();
     if (remaining <= 0) break;
@@ -680,6 +705,10 @@ export async function waitForMessageTool(args: {
       };
 
       const check = async () => {
+        // Line count first — a write that changes bytes without adding a line
+        // (a rewrite, a truncation) is not new traffic, and size alone reports
+        // it as such.
+        if (readLog(file).total > startLines) return finish(true);
         const sz = await fileSize(file);
         if (sz > startSize) finish(true);
       };

package/src/tools/records.ts

@@ -27,6 +27,7 @@ import {
 } from "@davidbalzan/groundwork-seam";
 import { ensureWorktreeTool } from "./worktrees.js";
 import { haltState } from "./stall.js";
+import { readSubs, evaluate, commitEvaluation, eventIsDerived, type RecordEvent } from "./events.js";
 
 const QUEUE_DOC = "docs/QUEUE.md";
 const DONE_DOC = "docs/DONE.md";
@@ -198,6 +199,44 @@ export async function nextUnblockedTool(args: { project: string; repo?: string }
 
 // ---------- claim ----------
 
+/**
+ * Insert or replace ONE row in the workstreams table, as TEXT.
+ *
+ * 2.4b: "a verb only fails closed if it is the ONLY path — nothing currently
+ * stops a coordinator editing the board directly instead of calling `claim`."
+ * `claim` used to RETURN a `boardHunk` for someone to paste by hand, which is
+ * the same discipline with a nicer API. Every legacy row on the board today is
+ * hand-written, and that is why `stall_check`'s vcs half has nothing to
+ * resolve: a pasted row carries a path, a `claim`-written row carries a real
+ * branch ref.
+ *
+ * Text insertion rather than a re-render: the rest of the file stays
+ * byte-identical, the same reason `land` appends its DONE line as text. A board
+ * this verb rewrote wholesale would be a diff nobody could review.
+ */
+export function upsertBoardRow(text: string, agentId: string, row: string): { text: string; action: "inserted" | "replaced" | "unchanged" } {
+  const lines = text.split("\n");
+  const header = lines.findIndex((l) => /^\|\s*Stream\s*\|/i.test(l));
+  if (header === -1) return { text, action: "unchanged" };
+  // The table ends at the first line that is not a row.
+  let end = header + 1;
+  while (end < lines.length && /^\s*\|/.test(lines[end])) end++;
+
+  // OWNER MATCHED ON THE CELL, NOT ON THE WHOLE LINE. An agent id appearing in
+  // a "Last note" cell is not that agent's row — the occurrence-vs-position
+  // defect this repo has re-derived at four granularities.
+  const ownerOf = (l: string) => (l.split("|")[2] ?? "").replace(/[`*\s]/g, "");
+  const existing = lines.findIndex((l, i) => i > header + 1 && i < end && ownerOf(l) === agentId);
+
+  if (existing !== -1) {
+    if (lines[existing] === row) return { text, action: "unchanged" };
+    lines[existing] = row;
+    return { text: lines.join("\n"), action: "replaced" };
+  }
+  lines.splice(end, 0, row);
+  return { text: lines.join("\n"), action: "inserted" };
+}
+
 export const claimSchema = {
   project: z.string().min(1),
   agentId: z.string().min(1),
@@ -205,9 +244,10 @@ export const claimSchema = {
   repo: z.string().optional(),
   base: z.string().optional(),
   task: z.string().optional(),
+  write: z.boolean().optional(),
 };
 
-export async function claimTool(args: { project: string; agentId: string; itemId?: string; repo?: string; base?: string; task?: string }) {
+export async function claimTool(args: { project: string; agentId: string; itemId?: string; repo?: string; base?: string; task?: string; write?: boolean }) {
   const halt = haltState();
   if (halt.halted) {
     return {
@@ -255,12 +295,52 @@ export async function claimTool(args: { project: string; agentId: string; itemId
     };
   }
 
+  // A NEW TASK DOES NOT START FROM A STALE TREE.
+  //
+  // `ensure_worktree` is idempotent and reuses the agent's existing tree, which
+  // is right mid-slice (1.3) and wrong here: `claim` MEANS "start something
+  // new", and a tree left on last week's base produces the confidently-wrong
+  // inventories the worker card warns about, with nothing about the result
+  // looking stale.
+  //
+  // A freshly CREATED tree is cut from origin/<base> and needs no check — this
+  // only ever fires on reuse.
+  if (!wt.created && wt.atBase === false) {
+    return {
+      ok: false as const,
+      error:
+        `cannot claim: the worktree at ${wt.path} is NOT at ${wt.base}` +
+        `${wt.behindBy ? ` (${wt.behindBy} commit(s) behind)` : ""} — it is on '${wt.branch}' at ${String(wt.sha).slice(0, 8)}. ` +
+        `A new task started here would be based on stale content, and nothing about the result would look stale. ` +
+        `Run \`refresh_worktrees\` to fast-forward idle trees, or finish and land the work already in it.`,
+      item: { id: item.id, priority: item.priority },
+      worktree: { path: wt.path, branch: wt.branch, sha: wt.sha, base: wt.base, atBase: false },
+    };
+  }
+
+  const boardHunk = `| ${keyOf(item)} | ${args.agentId} | \`${wt.branch}\` · ${wt.path} | 🚧 In Progress | — | claimed |`;
+
+  // 2.4b — THE VERB WRITES THE ROW. Reported by default, applied with
+  // write:true, matching `land`. A returned hunk that a human pastes is the
+  // same discipline with a nicer API, and the pasted rows are why the board
+  // carries paths where a claim would have carried a resolvable branch ref.
+  let board: { action: string; path?: string } = { action: "reported" };
+  const b = readDoc(repo, BOARD_DOC);
+  if (!b) {
+    board = { action: `no ${BOARD_DOC} under '${repo}' — row NOT written` };
+  } else if (args.write) {
+    const next = upsertBoardRow(b.text, args.agentId, boardHunk);
+    if (next.action !== "unchanged") writeFileSync(path.join(repo, BOARD_DOC), next.text);
+    board = { action: next.action, path: BOARD_DOC };
+  }
+
   return {
     ok: true as const,
     project: args.project,
     agentId: args.agentId,
     item: { id: item.id, priority: item.priority, text: item.text },
-    boardHunk: `| ${keyOf(item)} | ${args.agentId} | \`${wt.branch}\` · ${wt.path} | 🚧 In Progress | — | claimed |`,
+    boardHunk,
+    board,
     worktreeEnsured: true,
     worktree: { path: wt.path, sha: wt.sha, branch: wt.branch, created: wt.created, base: wt.base },
   };
@@ -404,6 +484,33 @@ export async function landTool(args: {
     }
   }
 
+  // 6.2 — EMIT ONLY AS A CONSEQUENCE OF THE RECORD CHANGING.
+  //
+  // Read back from disk, AFTER the write, and refuse to emit anything whose ref
+  // is not there. The ordering is the guarantee: an event cannot exist without
+  // the record entry that caused it, because the record is what is consulted to
+  // decide whether to emit. An event stream that can say "task X complete"
+  // while DONE.md does not is a second source of truth, and record-vs-state
+  // divergence is the defect this fleet hit most this week.
+  //
+  // Reported, never thrown: a delivery failure must not undo a merge that has
+  // already happened. `land` is a RECORDER.
+  let events: { emitted: RecordEvent[]; deliveries: unknown[]; refused: string[] } = { emitted: [], deliveries: [], refused: [] };
+  if (args.write && target) {
+    const after = readDoc(repo, DONE_DOC);
+    const recordText = after?.text ?? "";
+    const ev: RecordEvent = { kind: "item", target: target.id, ref: args.pr, summary: summarize(target.text) };
+    const derived = eventIsDerived(recordText, ev);
+    if (!derived.ok) {
+      events.refused.push(derived.error);
+    } else {
+      const now = Date.now();
+      const { subs, deliveries } = evaluate(readSubs(), ev, now);
+      commitEvaluation(subs);
+      events = { emitted: [ev], deliveries, refused: [] };
+    }
+  }
+
   return {
     ok: true as const,
     project: args.project,
@@ -411,6 +518,7 @@ export async function landTool(args: {
     comparedAgainst: ref,
     landedIn: landedIn.slice(0, 8),
     queueItem: target ? { id: target.id, closed: true, textUnchanged: true } : null,
+    events,
     candidates: target
       ? undefined
       : candidates.map((i) => ({ id: i.id, priority: i.priority, key: keyOf(i) })),

package/src/tools/registry.ts

@@ -259,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];