agent-coord-mcp 0.26.15 → 0.26.17

package/src/tools/registry.ts

@@ -79,8 +79,11 @@ export const registerSchema = {
   project: z.string().optional(),
   role: roleInputSchema.optional(),
   // First-claim guard overrides (server.ts guardFirstClaim): claiming an id
-  // that is LIVE on the bus refuses unless the call presents that agent's
-  // token (tokens.json / coord-token) or force:true. Ignored once bound.
+  // that is PROVABLY LIVE on the bus refuses unless the call presents that
+  // agent's token (tokens.json / coord-token) — `force` alone no longer
+  // overrides a provably live incumbent (q-314e0187). `force` still bypasses
+  // the guard when liveness cannot be verified, or the id is verified absent.
+  // Both ignored once bound.
   token: z.string().optional(),
   force: z.boolean().optional(),
   // PROSE-ONLY EXEMPTION (Phase 5.1 Task 12.8). `true` grants it, `false`
@@ -472,10 +475,25 @@ export type ClaimEvidence = {
   samePane: boolean;
   boundElsewhere: number;
   reasons: string[];
+  /**
+   * SESSION processes still holding this identity, structured rather than
+   * buried in `reasons` prose.
+   *
+   * A live SESSION binding is not the same fact as a live TRANSPORT marker, and
+   * conflating them is what let a refusal read as routine. The marker's pid is
+   * the pusher daemon — expected, and doing its job. A session binding for this
+   * id, alive, that is not this process, is a LEFTOVER PROCESS holding an
+   * identity: yesterday two sessions held worker-3's, and the refusal that
+   * reported it sent the reader to re-join.
+   *
+   * Named so the reader can look at the pid instead of routing around it.
+   */
+  leakedSessions: { pid: number; via: string }[];
 };
 
 export async function liveClaimEvidence(agentId: string, now: number): Promise<ClaimEvidence> {
   const reasons: string[] = [];
+  const leakedSessions: { pid: number; via: string }[] = [];
   let verifiable = true;
   let samePane = false;
   let heartbeatFresh = false;
@@ -529,6 +547,7 @@ export async function liveClaimEvidence(agentId: string, now: number): Promise<C
     if (!s || s.agentId !== agentId || s.pid === process.pid) continue;
     if (isPidAlive(s.pid)) {
       boundElsewhere++;
+      leakedSessions.push({ pid: s.pid, via: String(s.via ?? "unknown") });
       reasons.push(`another live session (pid ${s.pid}, via ${s.via}) is already bound to this id`);
     }
   }
@@ -539,6 +558,7 @@ export async function liveClaimEvidence(agentId: string, now: number): Promise<C
     samePane,
     boundElsewhere,
     reasons,
+    leakedSessions,
   };
 }
 

package/src/tools/shared.ts

@@ -182,6 +182,16 @@ export type Message = {
   // (or any other message) carries the parent message id so consumers can
   // mark the packet answered. Absent on every v1/v2 message — those stay valid.
   inReplyTo?: string;
+  // PROVENANCE (q-314e0187): the pid of the process that wrote this entry,
+  // and its tmux pane when known. `from` names an IDENTITY, not a PROCESS —
+  // two live sessions bound to the same agent id write byte-identical `from`
+  // values, and that is exactly the condition that let worker-3 truthfully
+  // deny sending a message that exists under its name on 2026-08-31: both
+  // sessions' accounts were true, and nothing on the message could say which
+  // wrote it. Cross-reference against sessions/*.json (SessionBinding) or
+  // `ps -p <pid>` to attribute a disputed entry. Absent on every message
+  // written before this field existed — that is UNKNOWN, not "same process".
+  provenance?: { pid: number; tmuxPane?: string };
 };
 
 // THE retention predicate — one definition, three call sites (prune,

package/src/tools/stall.ts

@@ -21,6 +21,7 @@ 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 { classifyBoardRef, refInCell } from "./board-ref.js";
 import { loadLiveTransports } from "./registry.js";
 
 const BOARD_DOC = "docs/WORKSTREAMS.md";
@@ -31,7 +32,19 @@ 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 };
+  | { kind: "no-vcs-activity"; agentId: string; branch: string; minutes: number }
+  /**
+   * A 🚧 row whose branch HAS ALREADY LANDED. Not a stall — the opposite: the
+   * work finished and nobody closed the row.
+   *
+   * It exists because the VCS axis was catching this BY ACCIDENT and is about to
+   * stop. A merged ref is frozen, so it reported an ever-growing "no activity"
+   * age, and that false stall was the only thing surfacing a real routing
+   * failure: a lane sitting In Progress with nothing routed to it. Making the
+   * stall honest would have silently removed the signal, so the signal gets its
+   * own name instead of inheriting a wrong one.
+   */
+  | { kind: "stale-row"; agentId: string; branch: string; why: string };
 
 // ---------- halt ----------
 
@@ -343,47 +356,48 @@ export async function stallCheckTool(args: { repo?: string; stallMinutes?: numbe
     // 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" });
+    // ONE CLASSIFIER, SHARED WITH `claim` (board-ref.ts). The old block asked
+    // only "does it resolve", and three of the four ways this cell has been
+    // wrong resolved cleanly — a shared ref, a local-only ref, and a merged
+    // ref. Resolution was never the property; the property is whether the ref's
+    // movement is THIS AGENT'S WORK.
+    const verdict = classifyBoardRef(repo, agentId, row.branchWorktree);
+    if (verdict.kind === "merged") {
+      // A VERDICT, NOT AN ABSENCE — and it counts as coverage, because the check
+      // did learn something about this lane: its work landed and its row is
+      // stale. Reported as its own kind rather than as a stall, which is what
+      // the frozen ref was reporting it as.
+      hits.push({ kind: "stale-row", agentId, branch: refInCell(row.branchWorktree), why: verdict.why });
+      measured.add(agentId);
       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`,
-      });
+    if (verdict.kind !== "measurable") {
+      unmeasurable.push({ agentId, value: refInCell(row.branchWorktree), why: verdict.why });
       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 sha = execFileSync("git", ["rev-parse", "--verify", "--quiet", `${verdict.ref}^{commit}`], {
+        cwd: repo, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"],
+      }).trim();
       const iso = execFileSync("git", ["log", "-1", "--format=%cI", sha, "--"], {
         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) });
+        hits.push({ kind: "no-vcs-activity", agentId, branch: verdict.ref, minutes: Math.round(age / 60000) });
       }
     } catch {
-      unmeasurable.push({ agentId, value: raw, why: "resolved as a ref but its log could not be read" });
+      unmeasurable.push({ agentId, value: verdict.ref, why: "resolved as a ref but its log could not be read" });
     }
   }
 
-  // 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".
+  // COVERAGE, not "did it run". A row is COVERED when a 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);

package/src/tools/transport.ts

@@ -927,8 +927,11 @@ export const joinSchema = {
   attach: z.union([z.boolean(), joinAttachOptionsSchema]).optional(),
   readInbox: z.boolean().optional(),
   // First-claim guard overrides (server.ts guardFirstClaim): claiming an id
-  // that is LIVE on the bus refuses unless the call presents that agent's
-  // token (tokens.json / coord-token) or force:true. Ignored once bound.
+  // that is PROVABLY LIVE on the bus refuses unless the call presents that
+  // agent's token (tokens.json / coord-token) — `force` alone no longer
+  // overrides a provably live incumbent (q-314e0187). `force` still bypasses
+  // the guard when liveness cannot be verified, or the id is verified absent.
+  // Both ignored once bound.
   token: z.string().optional(),
   force: z.boolean().optional(),
   // Prose-only exemption from the typed-record rule — see registerSchema.
@@ -1724,27 +1727,85 @@ export async function doctorTool(args: { fix?: boolean; maxFileBytes?: number })
   }
 
   // 6. Stale agents (registered, no live transport, heartbeat past EVICT_MS). Report only.
+  //
+  // Task 5.3/22.1: "27 stale" collapsed two different populations that look
+  // identical in a flat heartbeat-age list — 14 agents whose PANE was still
+  // genuinely current (their marker's pid had died, e.g. a `/mcp` reconnect
+  // spawned a new process in the SAME pane, but the pane itself never went
+  // anywhere) and 13 agents that were ORPHANS with no pane behind them at
+  // all, aged 19–45h. An orphan is stale by construction and can NEVER
+  // clear — reporting it beside a merely-slow-heartbeat agent manufactures a
+  // permanent false alarm in the same bucket as a real one.
+  //
+  // THE DISCRIMINATOR: a marker file that still exists on disk (even though
+  // its own pid/heartbeat check already failed `isMarkerLive`) and names a
+  // `tmuxTarget` `tmux has-session` still confirms. `has-session` checks the
+  // PANE, not the recorded pid — so it survives exactly the reconnect shape
+  // above, the same probe `wedged-local-pushers` already uses one direction
+  // over (there: a live pid whose pane died; here: a dead/expired marker
+  // whose pane did not). No marker at all, or a marker whose pane is
+  // confirmed gone, is the only shape left — and that is a genuine orphan.
   {
     // Compute liveness WITHOUT deleting dead markers — loadLiveTransports
     // prunes as a side effect, which would make this read-only check mutate
     // state (and pre-empt the orphan-marker fix in check 1).
     const live = new Set<string>();
+    const markerByAgent = new Map<string, TransportMarker>();
     for (const fname of await listTransportFiles()) {
       const marker = await readJson<TransportMarker | null>(path.join(TRANSPORT_DIR, fname), null);
-      if (marker && isMarkerLive(marker, reg, now)) live.add(marker.agentId);
+      if (!marker) continue;
+      markerByAgent.set(marker.agentId, marker);
+      if (isMarkerLive(marker, reg, now)) live.add(marker.agentId);
     }
-    const stale: string[] = [];
+    // Without a tmux binary we cannot probe a pane at all — every stale
+    // agent is reported as an orphan candidate rather than silently split,
+    // same posture `wedged-local-pushers` takes.
+    const tmuxAvailable = spawnSync("tmux", ["-V"]).status === 0;
+    const paneAlive = (target: string): boolean =>
+      tmuxAvailable && spawnSync("tmux", ["has-session", "-t", target]).status === 0;
+
+    const paneConfirmed: string[] = [];
+    const orphans: string[] = [];
     for (const [id, a] of Object.entries(reg)) {
       if (live.has(id)) continue;
-      if (now - a.lastHeartbeat > EVICT_MS) stale.push(`${id} (${Math.floor((now - a.lastHeartbeat) / 3600000)}h)`);
+      if (now - a.lastHeartbeat <= EVICT_MS) continue;
+      const age = `${Math.floor((now - a.lastHeartbeat) / 3600000)}h`;
+      const marker = markerByAgent.get(id);
+      if (marker?.transport === "tmux-push" && marker.tmuxTarget && paneAlive(marker.tmuxTarget)) {
+        paneConfirmed.push(`${id} (${age}, pane '${marker.tmuxTarget}' still current)`);
+      } else {
+        orphans.push(`${id} (${age})`);
+      }
     }
+    const stale = [...paneConfirmed, ...orphans];
     findings.push({
       check: "stale-agents",
       level: stale.length ? "warn" : "ok",
-      detail: stale.length ? `${stale.length} agent(s) past the eviction window — next list_agents will drop them` : "no stale agents",
+      detail: stale.length
+        ? `${stale.length} agent(s) past the eviction window — next list_agents will drop them ` +
+          `(${paneConfirmed.length} pane-confirmed current, ${orphans.length} genuine orphan(s) with no live pane behind them)`
+        : "no stale agents",
       fixable: false,
       items: stale.length ? stale : undefined,
     });
+    // A SEPARATE finding, not a sub-line: "stale-agents" answers "how many
+    // will list_agents drop", which is true of both buckets equally — an
+    // orphan and a pane-confirmed agent are dropped from the SAME list the
+    // same way. "orphan-agents" answers the different question this task is
+    // actually about — which of those, if any, can never clear on their
+    // own — and reports it even when it is empty, so a checker that only
+    // speaks when it fires cannot be told from one that never ran.
+    findings.push({
+      check: "orphan-agents",
+      level: orphans.length ? "warn" : "ok",
+      detail: orphans.length
+        ? `${orphans.length} stale agent(s) have no live tmux pane behind them — permanent, will not clear on their own (unregister or let eviction drop them)`
+        : tmuxAvailable
+          ? `no orphans among ${stale.length} stale agent(s)${stale.length ? " — all pane-confirmed current" : ""}`
+          : "tmux not available — could not distinguish orphans from pane-confirmed stale agents",
+      fixable: false,
+      items: orphans.length ? orphans : undefined,
+    });
   }
 
   // 6b. STALENESS HAS TWO CAUSES AND THEY LOOK IDENTICAL IN A FLAT LIST.