agent-coord-mcp 0.26.12 → 0.26.14

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

package/src/tools/work.ts

@@ -17,10 +17,11 @@ import {
   workDocLegacyWriteIssues,
   LANES_V0_WRITE_ISSUE,
 } from "../work.js";
-import { parseFactsDoc, type FactEntry } from "@davidbalzan/groundwork-seam";
+import { parseFactsDoc, type FactEntry, type Priority } from "@davidbalzan/groundwork-seam";
 import { loadScopes, ownsDocument } from "./scopes.js";
 import { AGENTS_FILE } from "../store.js";
 import type { AgentRegistry } from "./shared.js";
+import { summarize, blockedBy } from "./records.js";
 
 // ---------- work state as data (Phase 8 Task 5) ----------
 //
@@ -189,8 +190,42 @@ export const listWorkSchema = {
   // native (default): discriminated v1 | lanes-v0. lanes: lossy projection of v1.
   view: z.enum(["native", "lanes"]).optional(),
   repo: z.string().optional(),
+  // Fetch ONE full record by id — the second call Task 15.1 asks for.
+  // Identity rows (below) never carry the body; this is how a caller gets it,
+  // and only for the one row it actually needs rather than every row's.
+  id: z.string().optional(),
 };
 
+// A queue row without its body — id, priority, a bounded headline, and
+// blocked-by, the fields the doc names. `owner` is NOT included: QueueItem
+// carries no structured owner field, and the free-text `origin:` phrase some
+// items end with ("origin: coordinator retracting its own broadcast canon…")
+// is prose, not an id — extracting one heuristically would fabricate a field
+// this data model does not have. Omitted rather than guessed, same
+// discipline as `list_agents`' heartbeatSource (Task 13.5).
+export type QueueIdentityRow = {
+  id: string;
+  priority: Priority | null;
+  headline: string;
+  truncated: boolean;
+  blockedBy: string | null;
+};
+
+function identityRowOf(item: QueueItem): QueueIdentityRow {
+  const flat = String(item.text).replace(/\s+/g, " ").replace(/\*\*/g, "").trim();
+  return {
+    id: item.id,
+    priority: item.priority,
+    headline: summarize(item.text),
+    // `summarize` itself decides where to cut; re-deriving "did it cut" here
+    // from a second pass over the same text would be the two-matchers-one-
+    // question shape this phase keeps finding elsewhere (refsIn, COMMIT_REF).
+    // Comparing against its own bound is exact and free.
+    truncated: flat.length > 96,
+    blockedBy: blockedBy(item),
+  };
+}
+
 export async function listWorkTool(args: {
   project: string;
   kind?: "queue" | "done" | "board" | "facts";
@@ -198,6 +233,7 @@ export async function listWorkTool(args: {
   includeDone?: boolean;
   view?: "native" | "lanes";
   repo?: string;
+  id?: string;
 }) {
   // No import yet (or the store was deleted) → read the documents directly.
   // This is the fallback that makes "the markdown stands alone" true in code
@@ -231,6 +267,17 @@ export async function listWorkTool(args: {
   }
   if (args.view === "lanes") board = board.map(projectV1ToLanes);
 
+  // THE SECOND CALL — one row, whole. Searches queue then done (a done entry
+  // shares the id space; an id is unique within a project's work state), so
+  // the caller does not have to know which kind its own id belongs to.
+  if (args.id !== undefined) {
+    const queueHit = queue.find((q) => q.id === args.id);
+    if (queueHit) return { ok: true as const, project: state.project, repo: state.repo, source, kind: "queue" as const, item: queueHit };
+    const doneHit = done.find((d) => d.id === args.id);
+    if (doneHit) return { ok: true as const, project: state.project, repo: state.repo, source, kind: "done" as const, item: doneHit };
+    return { ok: false as const, error: `no queue item or DONE entry with id '${args.id}' in project '${state.project}'` };
+  }
+
   const openQueue = args.includeDone ? queue : queue.filter((q) => !q.done);
   const filtered = args.priority ? openQueue.filter((q) => q.priority === args.priority) : openQueue;
 
@@ -239,7 +286,12 @@ export async function listWorkTool(args: {
     project: state.project,
     repo: state.repo,
     source,
-    ...(args.kind === "queue" || args.kind === undefined ? { queue: filtered } : {}),
+    // IDENTITY ONLY (Task 15.1) — id, priority, a bounded headline, and
+    // blocked-by; never the full item text. Call again with `id` for one
+    // row's body. This is the change that makes the tool cheap: the same
+    // question that used to return every open item's ~1,500-char body now
+    // returns a fixed-width row per item.
+    ...(args.kind === "queue" || args.kind === undefined ? { queue: filtered.map(identityRowOf) } : {}),
     ...(args.kind === "done" || args.kind === undefined ? { done } : {}),
     ...(args.kind === "board" || args.kind === undefined ? { board } : {}),
     ...(args.kind === "facts" || args.kind === undefined ? { facts } : {}),

package/src/tools/worktrees.ts

@@ -268,7 +268,51 @@ export async function refreshWorktreesTool(args: { repo: string; base: string; a
   for (const w of listWorktrees(repo)) {
     const at = w.path;
     if (samePath(at, primaryOf(repo) ?? "")) {
-      results.push({ path: w.path, action: "skipped", why: "primary checkout — not a slice tree" });
+      // THE PRIMARY CHECKOUT IS REPORTED, ALWAYS — it used to be skipped with
+      // "not a slice tree", which is true and useless. It is the tree David
+      // reads, the one every hand-run measurement runs in, and a silent skip
+      // let it sit arbitrarily far behind while this verb reported a clean
+      // sweep. "Not ours to fast-forward" and "nothing to say about it" are
+      // different claims and only the first one was intended.
+      let behind = "unknown";
+      let ahead = "unknown";
+      try {
+        behind = git(at, ["rev-list", "--count", `HEAD..${tip}`]);
+        ahead = git(at, ["rev-list", "--count", `${tip}..HEAD`]);
+      } catch {
+        /* left as unknown — an unreadable count must not read as zero */
+      }
+      const dirty = isDirty(at);
+      // FAST-FORWARD ONLY, AND ONLY WHEN CLEAN. A ff-only merge cannot rewrite
+      // history or resolve a conflict, so the worst case is a refusal. Dirty is
+      // refused for the same reason a slice tree is: uncommitted work is what a
+      // diff cannot show and git cannot give back.
+      const canFf = !dirty && ahead === "0" && behind !== "0" && behind !== "unknown";
+      if (args.apply && canFf) {
+        try {
+          git(at, ["merge", "--ff-only", ref]);
+          results.push({ path: w.path, action: "fast-forwarded", why: `primary checkout advanced ${behind} commit(s) to ${ref}` });
+          continue;
+        } catch (e) {
+          results.push({ path: w.path, action: "refused", why: `primary checkout: ff-only merge failed — ${(e as Error).message}` });
+          continue;
+        }
+      }
+      results.push({
+        path: w.path,
+        action: behind === "0" ? "current" : "stale",
+        why:
+          behind === "0"
+            ? `primary checkout is at ${ref}`
+            : `primary checkout is ${behind} commit(s) behind ${ref}` +
+              (dirty
+                ? " and DIRTY — not fast-forwarded; uncommitted work is what a diff cannot show"
+                : ahead !== "0"
+                  ? ` and ${ahead} ahead — not fast-forwarded; it has commits ${ref} does not`
+                  : args.apply
+                    ? ""
+                    : " — pass apply:true to fast-forward it"),
+      });
       continue;
     }
     if (isDirty(at)) {