agent-coord-mcp 0.26.12 → 0.26.13

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 } : {}),