agent-coord-mcp 0.26.6 → 0.26.7

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];

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 { loadLiveTransports } from "./registry.js";
 
 const BOARD_DOC = "docs/WORKSTREAMS.md";
 const STALL_MS = 30 * 60 * 1000;
@@ -71,9 +72,32 @@ export function haltState(): { halted: boolean; reason?: string; by?: string; at
 // ---------- the run mark ----------
 
 /** Every run leaves this, HIT or MISS. It is what makes a dead clock visible. */
+/**
+ * Record a run that FAILED.
+ *
+ * Acceptance from the queue item, and the clause most easily skipped: "a
+ * scheduled check reports its FETCH FAILURES, or a broken check is
+ * indistinguishable from a quiet registry". Without this, a clock that fires
+ * every 30 minutes and throws every time leaves NO marks at all — identical on
+ * disk to a clock that was never installed.
+ */
+export function markRunFailure(reason: string): void {
+  mkdirSync(ROOT, { recursive: true });
+  let history: RunMark[] = [];
+  try {
+    history = JSON.parse(readFileSync(runFile(), "utf8")).history ?? [];
+  } catch {
+    /* first run */
+  }
+  history.push({ at: Date.now(), hits: 0, checked: 0, failed: reason });
+  writeFileSync(runFile(), JSON.stringify({ history: history.slice(-200) }, null, 2));
+}
+
+type RunMark = { at: number; hits: number; checked: number; failed?: string };
+
 function markRun(result: { hits: StallHit[]; checked: number }) {
   mkdirSync(ROOT, { recursive: true });
-  let history: { at: number; hits: number; checked: number }[] = [];
+  let history: RunMark[] = [];
   try {
     history = JSON.parse(readFileSync(runFile(), "utf8")).history ?? [];
   } catch {
@@ -94,7 +118,7 @@ export const lastRanSchema = { maxAgeMinutes: z.number().optional() };
  */
 export async function stallClockStatusTool(args: { maxAgeMinutes?: number }) {
   const maxAge = (args.maxAgeMinutes ?? 60) * 60 * 1000;
-  let history: { at: number; hits: number; checked: number }[] = [];
+  let history: RunMark[] = [];
   try {
     history = JSON.parse(readFileSync(runFile(), "utf8")).history ?? [];
   } catch {
@@ -105,6 +129,12 @@ export async function stallClockStatusTool(args: { maxAgeMinutes?: number }) {
     };
   }
   const last = history[history.length - 1];
+  // A RUN THAT FAILED IS NOT A RUN THAT PASSED. Without this the clock reads
+  // "fresh" off a mark it wrote while erroring — the age is honest and the
+  // health is not, which is the same shape as a fresh heartbeat from a stuck
+  // agent.
+  const failures = history.filter((h) => h.failed);
+  const lastFailed = last?.failed;
   const age = Date.now() - (last?.at ?? 0);
   // `>=`, NOT `>`, AND THE DIFFERENCE IS A REAL RACE RATHER THAN PEDANTRY.
   //
@@ -118,18 +148,27 @@ export async function stallClockStatusTool(args: { maxAgeMinutes?: number }) {
   // 0-minute window means nothing is ever fresh, which is what a caller asking
   // for one means.
   const stale = age >= maxAge;
-  const misses = history.filter((h) => h.hits === 0).length;
+  const misses = history.filter((h) => !h.failed && h.hits === 0).length;
+  const hits = history.filter((h) => !h.failed && h.hits > 0).length;
   return {
-    ok: !stale,
+    // 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,
     ...(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.`,
         }
-      : {}),
+      : lastFailed
+        ? {
+            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.`,
+          }
+        : {}),
     lastRanMinutesAgo: Math.round(age / 60000),
     runs: history.length,
     misses,
-    hits: history.length - misses,
+    hits,
+    failures: failures.length,
   };
 }
 
@@ -143,17 +182,56 @@ export async function stallCheckTool(args: { repo?: string; stallMinutes?: numbe
   const board = path.join(repo, BOARD_DOC);
   if (!existsSync(board)) return { ok: false as const, error: `no ${BOARD_DOC} under '${repo}'` };
 
+  const liveTransports = await loadLiveTransports();
   const rows = workstreamsV1RowsOf(parseWorkDoc(readFileSync(board, "utf8")));
   const inFlight = rows.filter((r) => /🚧/.test(r.status));
   const reg = await readJson<Record<string, { lastHeartbeat: number }>>(AGENTS_FILE, {});
   const now = Date.now();
   const hits: StallHit[] = [];
+  /** Rows whose VCS activity could not be measured. NOT stall claims. */
+  const unmeasurable: { agentId: string; value: string; why: string }[] = [];
 
   for (const row of inFlight) {
     const agentId = row.owner.replace(/[`*]/g, "").trim();
     const entry = reg[agentId];
     if (entry) {
       const age = now - entry.lastHeartbeat;
+      // A HEARTBEAT IS ONLY EVIDENCE WHERE SOMETHING WRITES ONE.
+      //
+      // `heartbeat` is called by the PUSHER, never by the agent. Only
+      // `coord-pusher.mjs` (the REMOTE pusher) calls it, and it must: a remote
+      // marker cannot be pid-probed across machines, so its liveness IS the
+      // heartbeat. `hooks/tmux-pusher.mjs` — what this fleet actually runs —
+      // never calls it, because a LOCAL marker's liveness is `isPidAlive`.
+      //
+      // So for a local transport there is no heartbeat SOURCE at all. Before
+      // kit#137, `list_agents` stamped these agents and that fabrication was
+      // the only thing keeping the field moving; removing it left the field
+      // honest and empty. Measured: three attached, working agents at an
+      // IDENTICAL 44.7m — the uniform signature of one shared cause, not three
+      // stalls.
+      //
+      // WHY NOT JUST MAKE tmux-pusher HEARTBEAT: because the signal would mean
+      // "the pusher process is alive", which `isPidAlive` already answers for
+      // local markers. During the 17-hour stall every transport was live the
+      // whole time, so a pusher heartbeat would have read FRESH for all 17
+      // hours. It would restore a field without restoring a detector — and the
+      // case this verb exists for is exactly the one it would miss. The vcs
+      // half is what catches "alive and not progressing"; saying so is more
+      // honest than a green field.
+      //
+      // Unknown is not stalled (kit#138). This does NOT narrow Task 3.5: an
+      // agent with no transport, or a REMOTE one where the heartbeat genuinely
+      // is the liveness mechanism, still HITs on a dead heartbeat.
+      const marker = liveTransports.get(agentId);
+      if (age > limit && marker && marker.transport === "tmux-push") {
+        unmeasurable.push({
+          agentId,
+          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) {
         hits.push({ kind: "no-heartbeat", agentId, stream: row.stream.slice(0, 60), minutes: Math.round(age / 60000) });
         continue;
@@ -162,22 +240,61 @@ export async function stallCheckTool(args: { repo?: string; stallMinutes?: numbe
     // 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
     // looks. Ask the branch instead.
-    const branch = (row.branchWorktree.match(/`([^`]+)`/)?.[1] ?? "").trim();
-    if (!branch || !/\//.test(branch)) continue;
+    //
+    // RESOLVE A REF, AND SAY SO WHEN THE VALUE IS NOT ONE.
+    //
+    // `git log -1 <value>` accepts a PATHSPEC exactly as readily as a ref, and
+    // the old guard only required a `/` — which every path has. So the board's
+    // `Branch · Worktree` cells, which hold PATHS, were fed to git and silently
+    // measured as paths: the aide was reported at 2,271 minutes, the age of
+    // `docs/phases/phase5`'s last commit, not of any activity by that agent.
+    // Verified: `docs/phases/phase5` does not resolve as a ref, yet
+    // `git log -1 --format=%cI docs/phases/phase5` returns a date.
+    //
+    // Other rows read plausibly only by coincidence — a path that happens to be
+    // committed often looks like an active branch.
+    //
+    // UNKNOWN IS NOT STALLED, which this verb already gets right for
+    // 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" });
+      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`,
+      });
+      continue;
+    }
     try {
-      const iso = execFileSync("git", ["log", "-1", "--format=%cI", branch], {
+      // 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 iso = execFileSync("git", ["log", "-1", "--format=%cI", sha, "--"], {
         cwd: repo, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"],
       }).trim();
       const age = now - Date.parse(iso);
       if (age > limit) {
-        hits.push({ kind: "no-vcs-activity", agentId, branch, minutes: Math.round(age / 60000) });
+        hits.push({ kind: "no-vcs-activity", agentId, branch: raw, minutes: Math.round(age / 60000) });
       }
     } catch {
-      /* unknown branch: not a stall claim we can make */
+      unmeasurable.push({ agentId, value: raw, why: "resolved as a ref but its log could not be read" });
     }
   }
 
-  const result = { hits, checked: inFlight.length };
+  const result = { hits, checked: inFlight.length, unmeasurable };
   markRun(result);
   return {
     ok: true as const,
@@ -188,7 +305,7 @@ export async function stallCheckTool(args: { repo?: string; stallMinutes?: numbe
     dm: hits.length > 0,
     note:
       hits.length === 0
-        ? `MISS — ${inFlight.length} in-flight row(s), none stalled. No DM. The run IS recorded: read it with stall_clock_status, because no alert and nothing running look identical from here.`
+        ? `MISS — ${inFlight.length} in-flight row(s), none stalled${unmeasurable.length ? `; ${unmeasurable.length} row(s) UNMEASURABLE for VCS activity (${unmeasurable.map((u) => u.agentId).join(", ")}) — reported, not counted as healthy` : ""}. No DM. The run IS recorded: read it with stall_clock_status, because no alert and nothing running look identical from here.`
         : undefined,
   };
 }

package/src/tools/worktrees.ts

@@ -173,6 +173,28 @@ async function create(a: {
     // made: a verb that silently returns a tree on a different branch than asked
     // for is the adjacent-answer shape.
     const head = git(existing.path, ["rev-parse", "HEAD"]);
+    // IS THE REUSED TREE ACTUALLY AT THE BASE IT CLAIMS?
+    //
+    // The verb warned when an existing tree was on a different BRANCH and said
+    // nothing about it being behind the BASE — so a tree left on last week's
+    // main was handed back as ready. Starting a new task there produces the
+    // "stale main -> confidently-wrong inventories" failure the worker card
+    // already warns about, and nothing about the result looks stale.
+    //
+    // Reported here, not refused: an existing tree legitimately holds
+    // in-progress work mid-slice (1.3). The refusal belongs to `claim`, which
+    // is the verb that means "start something new".
+    let atBase = false;
+    let behindBy: number | null = null;
+    try {
+      const baseSha = git(repo, ["rev-parse", "--verify", `${ref}^{commit}`]);
+      atBase = head === baseSha;
+      if (!atBase) behindBy = Number(git(existing.path, ["rev-list", "--count", `HEAD..${ref}`])) || 0;
+    } catch {
+      // NOT MEASURED IS NOT AT-BASE. Leaving `atBase` false is the safe
+      // direction: it makes `claim` ask rather than assume.
+      atBase = false;
+    }
     return {
       ok: true as const,
       path: existing.path,
@@ -180,6 +202,8 @@ async function create(a: {
       branch: existing.branch,
       created: false,
       base: ref,
+      atBase,
+      behindBy: behindBy ?? 0,
       ...(existing.branch !== branch
         ? { warning: `existing tree is on '${existing.branch}', not the '${branch}' this call would have created — reusing it, NOT re-pointing it` }
         : {}),
@@ -198,6 +222,10 @@ async function create(a: {
     branch,
     created: true,
     base: ref,
+    // Cut from `sha`, which IS origin/<base> — true by construction here, and
+    // stated so callers need not special-case "created" to know it.
+    atBase: true,
+    behindBy: 0,
     ...(a.ephemeral
       ? { ephemeral: true, removeWith: `git -C ${repo} worktree remove --force ${target} && git -C ${repo} branch -D ${branch}` }
       : {}),