agent-coord-mcp 0.26.14 → 0.26.16

package/src/tools/events.ts

@@ -29,8 +29,26 @@ export type Subscription = {
   kind: SubKind;
   target: string;
   createdAt: number;
-  /** null until this subscription has been EVALUATED at least once. */
+  /**
+   * null until an event OF THIS KIND was evaluated against this subscription.
+   *
+   * NOT "the machinery ran" — see lastScannedAt. Those were one field, and the
+   * collapse is the defect: `evaluate()` only touches subscriptions whose kind
+   * matches the event, so an `item` subscriber sat at `never evaluated` for a
+   * week while `pr` events flowed past it. Its health said the wiring was dead;
+   * the wiring was fine and nothing of its kind had happened.
+   */
   lastEvaluatedAt: number | null;
+  /**
+   * null until a scan RAN with this subscription registered — regardless of
+   * kind. A scan that ran is evidence the wiring works; it says nothing about
+   * whether your kind fired, which is the other field.
+   *
+   * Optional on disk: subscriptions written before this existed have no value,
+   * and absent must read as UNKNOWN rather than as "never scanned". Fabricating
+   * a scan nobody observed is the failure this whole phase is about.
+   */
+  lastScannedAt?: number | null;
   lastEventAt: number | null;
   /** Idempotency keys already delivered, for 6.4. */
   delivered: string[];
@@ -60,17 +78,53 @@ function writeSubs(subs: Subscription[]): void {
  * 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)
+export function subscriptionHealth(s: Subscription): { level: "ok" | "error" | "unknown"; detail: string } {
+  const iso = (n: number) => new Date(n).toISOString();
+
+  // THREE STATES, BECAUSE THERE ARE THREE FACTS. They were two, and the
+  // collapse cost a week: an `item` subscriber read `error — never evaluated`
+  // the whole time, because `evaluate()` only touches subscriptions whose kind
+  // matches the event and no `item` event had fired. The wiring was fine. The
+  // health field said it was dead, and the agent holding it believed the field.
+  //
+  // Same shape as `alive` swallowing `heartbeatFresh`, and as
+  // `stall_clock_status` reporting green while covering nothing: one field
+  // answering two questions always answers the easier one.
+  if (s.lastScannedAt === undefined && s.lastEvaluatedAt === null) {
+    // Written before this field existed AND never evaluated. Absent is UNKNOWN,
+    // never "never scanned" — inventing a scan nobody observed is the failure
+    // this phase is about, and asserting one never happened is the same error
+    // pointed the other way.
+    return {
+      level: "unknown",
+      detail:
+        "predates scan tracking and has never been evaluated — whether the machinery has run for it CANNOT be determined from this record. " +
+        "It will resolve to ok or error on the next scan; until then this is an absence of evidence, not evidence of absence.",
+    };
+  }
+  if (!s.lastScannedAt) {
     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.`,
+      detail:
+        "NEVER SCANNED — no scan has run with this subscription registered, so it has produced no evidence of being wired to anything. " +
+        "This is the state that means broken.",
+    };
+  }
+  if (s.lastEvaluatedAt === null) {
+    // THE STATE THAT USED TO READ AS BROKEN. The machinery ran and nothing of
+    // this kind happened, which is a healthy idle watch.
+    return {
+      level: "ok",
+      detail:
+        `scanned ${iso(s.lastScannedAt)}, never evaluated — the machinery RAN and no '${s.kind}' event has occurred yet. ` +
+        "Scanned-and-quiet is healthy; it is not the same as never run, and those shared a field until now.",
     };
+  }
   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`,
+      ? `scanned ${iso(s.lastScannedAt)}, last evaluated ${iso(s.lastEvaluatedAt)}, last event ${iso(s.lastEventAt)}`
+      : `scanned ${iso(s.lastScannedAt)}, last evaluated ${iso(s.lastEvaluatedAt)}, no events yet`,
   };
 }
 
@@ -122,12 +176,26 @@ export type Delivery = { subscriptionId: string; agentId: string; key: string; s
  * 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.
  */
+/**
+ * Record that a scan RAN, for every live subscription regardless of kind.
+ *
+ * Called once per scan — including a scan that produced NO events, which is
+ * exactly the case that starved the old field: no events of your kind means
+ * `evaluate` never touches you, and a subscription that is never touched cannot
+ * be told from one that is not wired to anything.
+ */
+export function markScanned(subs: Subscription[], now: number): Subscription[] {
+  return subs.map((s) => ({ ...s, lastScannedAt: now }));
+}
+
 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 };
+    // Every subscription observed this scan, whatever its kind.
+    const scanned = { ...s, lastScannedAt: now };
+    if (s.kind !== ev.kind) return scanned;
+    const evaluated = { ...scanned, 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" });
@@ -157,6 +225,12 @@ export async function subscribeTool(args: { agentId: string; kind: SubKind; targ
     kind: args.kind,
     target: args.target,
     createdAt: Date.now(),
+    // EXPLICIT null, never left absent. `null` means "we know no scan has run
+    // for this"; `undefined` means "this record predates the field and we
+    // cannot say". A subscription created now is the first case, and writing it
+    // explicitly is what keeps a brand-new registration from being reported as
+    // unknowable.
+    lastScannedAt: null,
     lastEvaluatedAt: null,
     lastEventAt: null,
     delivered: [],
@@ -185,6 +259,7 @@ export async function listSubscriptionsTool(args: { agentId?: string }) {
   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");
+  const undetermined = rows.filter((r) => r.health.level === "unknown");
   return {
     ok: neverEvaluated.length === 0,
     // Population beside the verdict, always: "no subscriptions" and "none
@@ -192,7 +267,12 @@ export async function listSubscriptionsTool(args: { agentId?: string }) {
     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.` }
+      ? { error: `${neverEvaluated.length} of ${rows.length} subscription(s) have NEVER BEEN SCANNED — no scan has run with them registered, so they have produced no evidence of being wired to anything.` }
+      : {}),
+    ...(undetermined.length
+      ? {
+          undetermined: `${undetermined.length} of ${rows.length} subscription(s) predate scan tracking and cannot be judged yet — they resolve on the next scan. Reported rather than counted as either healthy or broken.`,
+        }
       : {}),
   };
 }

package/src/tools/record-events.ts

@@ -257,7 +257,7 @@ 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";
+import { readSubs, evaluate, commitEvaluation, eventIsDerived, markScanned } from "./events.js";
 
 /**
  * The watermark: the last commit whose record change has been turned into
@@ -349,8 +349,15 @@ export async function scanRecordEventsTool(args: { repo: string; since?: string;
 
   const deliveries: unknown[] = [];
   if (args.write) {
-    let subs = readSubs();
+    // MARK THE SCAN BEFORE THE EVENTS, and unconditionally.
+    //
+    // A scan that produced NO events is exactly the case that starved the old
+    // health field: `evaluate` is per-event, so a quiet scan touched nothing
+    // and every subscription kept reading "never evaluated" — indistinguishable
+    // from unwired. The scan RAN; that is a fact about the machinery and it is
+    // recorded whether or not anything fired.
     const now = Date.now();
+    let subs = markScanned(readSubs(), now);
     for (const ev of emitted) {
       const r = evaluate(subs, ev, now);
       subs = r.subs;

package/src/tools/records.ts

@@ -27,6 +27,7 @@ import {
   sweepTagOf,
 } from "@davidbalzan/groundwork-seam";
 import { ensureWorktreeTool } from "./worktrees.js";
+import { boardRefFor } from "./board-ref.js";
 import { haltState } from "./stall.js";
 import { readSubs, evaluate, commitEvaluation, eventIsDerived, type RecordEvent } from "./events.js";
 
@@ -340,7 +341,20 @@ export async function claimTool(args: { project: string; agentId: string; itemId
     };
   }
 
-  const boardHunk = `| ${keyOf(item)} | ${args.agentId} | \`${wt.branch}\` · ${wt.path} | 🚧 In Progress | — | claimed |`;
+  // THE CELL NAMES THE REMOTE-TRACKING REF, not the bare local branch.
+  //
+  // A bare name resolves in the checkout that created it and nowhere else, so
+  // the same board read differently from two checkouts and whether a row was
+  // measurable depended on who last ran `git fetch` — a property of the reader
+  // rather than of the work. Writing `origin/<branch>` makes the cell mean the
+  // same thing everywhere.
+  //
+  // It does not resolve YET, because a freshly cut branch is unpushed. That is
+  // correct and `stall_check` says so in those words: an unpushed lane has no
+  // shared evidence of activity, which is an absence of evidence rather than a
+  // stall. Enforced at the WRITE as well as the read (board-ref.ts) — a rule the
+  // writer can defeat is a rule the writer defeats.
+  const boardHunk = `| ${keyOf(item)} | ${args.agentId} | \`${boardRefFor(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

package/src/tools/registry.ts

@@ -472,10 +472,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 +544,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 +555,7 @@ export async function liveClaimEvidence(agentId: string, now: number): Promise<C
     samePane,
     boundElsewhere,
     reasons,
+    leakedSessions,
   };
 }
 

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

@@ -5,6 +5,15 @@ import { execFileSync } from "node:child_process";
 import { registerTool } from "./registry.js";
 import { roleInputSchema, type RoleArg } from "../roles.js";
 import { attributeWriter, isGitRepo, lastWriterOf, loadScopes, ownsDocument } from "./scopes.js";
+// Moved to a LEAF so `status` can report capabilities without a cycle — see
+// src/server-identity.ts. Re-exported so every existing importer is untouched.
+export { resolveServerIdentity } from "../server-identity.js";
+import { resolveServerIdentity } from "../server-identity.js";
+// ONE-WAY EDGE, and the direction is the point: `status` CALLS the capabilities
+// verb rather than re-deriving its probes. Two probes of the same thing is the
+// four-matchers defect committed deliberately, which is why 17.4 was deferred
+// behind 13.7 instead of built beside it.
+import { capabilitiesTool } from "../capabilities.js";
 import { sendMessageTool, readMessagesTool } from "./messaging.js";
 import { randomUUID } from "node:crypto";
 import { existsSync, openSync, readFileSync, watch } from "node:fs";
@@ -835,63 +844,6 @@ function resolvePusherPath(): string {
   return path.resolve(here, "..", "..", "hooks", "tmux-pusher.mjs");
 }
 
-/** Running server package + optional git identity. `fromDir` is a test seam. */
-export function resolveServerIdentity(fromDir?: string): {
-  path: string;
-  version: string;
-  branch?: string;
-  sha?: string;
-} {
-  const start = fromDir ?? path.dirname(fileURLToPath(import.meta.url));
-  let dir = start;
-  let pkgFile: string | undefined;
-  for (let i = 0; i < 8; i++) {
-    const candidate = path.join(dir, "package.json");
-    if (existsSync(candidate)) {
-      pkgFile = candidate;
-      break;
-    }
-    const parent = path.dirname(dir);
-    if (parent === dir) break;
-    dir = parent;
-  }
-  const pkgPath = pkgFile ?? path.resolve(start, "..", "..", "package.json");
-  const pkgDir = path.dirname(pkgPath);
-  let version = "unknown";
-  try {
-    const raw = JSON.parse(readFileSync(pkgPath, "utf8")) as { version?: string };
-    if (typeof raw.version === "string" && raw.version) version = raw.version;
-  } catch {
-    /* leave unknown — never invent a version */
-  }
-
-  const out: { path: string; version: string; branch?: string; sha?: string } = {
-    path: pkgDir,
-    version,
-  };
-
-  dir = pkgDir;
-  let gitRoot: string | undefined;
-  for (let i = 0; i < 10; i++) {
-    if (existsSync(path.join(dir, ".git"))) {
-      gitRoot = dir;
-      break;
-    }
-    const parent = path.dirname(dir);
-    if (parent === dir) break;
-    dir = parent;
-  }
-  if (gitRoot && isGitRepo(gitRoot)) {
-    const branch = spawnSync("git", ["-C", gitRoot, "rev-parse", "--abbrev-ref", "HEAD"], { encoding: "utf8" });
-    const sha = spawnSync("git", ["-C", gitRoot, "rev-parse", "HEAD"], { encoding: "utf8" });
-    const b = branch.status === 0 ? String(branch.stdout).trim() : "";
-    const s = sha.status === 0 ? String(sha.stdout).trim() : "";
-    if (b) out.branch = b;
-    if (s) out.sha = s;
-  }
-  return out;
-}
-
 /** An epoch-ms stamp as ISO-8601 UTC, or an explicit absence — never a blank. */
 function stamp(ms: number | undefined): string {
   return ms === undefined ? "(no stamp)" : new Date(ms).toISOString();
@@ -925,6 +877,22 @@ export async function statusTool(args: { agentId: string }) {
   const cursor = await readJson<Cursor>(cursorFile(args.agentId), {});
   const inboxOffset = cursor.inboxOffset ?? 0;
   const unread = Math.max(0, inbox.length - inboxOffset);
+  // WHAT THIS PROCESS CAN ACTUALLY DO, embedded WHOLE.
+  //
+  // A new tool otherwise lands silently: an agent reading an old listing
+  // asserts the tool does not exist, and it is right about its own listing and
+  // wrong about the world. Three wrong conclusions in two days came from
+  // exactly that, each about which build a pane was running.
+  //
+  // The full report travels, not a summary. Flattening it to a boolean would
+  // hand the caller a tidier answer and a worse one: `versionLabel` stays
+  // CONTEXT rather than evidence, a THROWN probe stays an absent capability
+  // rather than a broken check, and `answeredBy` keeps naming which pid
+  // answered — two servers disagreeing mid-rollout is the normal case, and it
+  // is the case every other instrument here reports as if the fleet were one
+  // thing.
+  const capabilities = await capabilitiesTool();
+
   return {
     agentId: args.agentId,
     registered: !!entry,
@@ -935,6 +903,7 @@ export async function statusTool(args: { agentId: string }) {
     inboxUnread: unread,
     inTmux: !!process.env.TMUX_PANE,
     tmuxPane: process.env.TMUX_PANE,
+    capabilities,
   };
 }