agent-coord-mcp 0.26.15 → 0.26.16

package/src/tools/board-ref.ts

@@ -0,0 +1,194 @@
+/*
+ * IS THIS BOARD CELL'S REF A PER-AGENT ACTIVITY SIGNAL?
+ *
+ * One classifier, used by the CHECKER that reads the cell and the VERB that
+ * writes it. A rule enforced at the read and not the write is a rule the write
+ * defeats: `claim` writes these rows, so if a bad ref is refusable by
+ * `stall_check` and writable by `claim`, the verb the fleet is being pushed
+ * toward becomes the thing that manufactures the bad row.
+ *
+ * FOUR WAYS THIS ONE CELL HAS BEEN WRONG, all measured on this fleet:
+ *
+ *   `docs/*`                     a PATH — refused today, correctly
+ *   `main`                       a SHARED ref — resolved, and reported the
+ *                                whole fleet's activity as one agent's, so the
+ *                                row could never stall
+ *   `worker-3/task13-…`          LOCAL-ONLY — resolved for its author and for
+ *                                nobody else, so the same board read
+ *                                differently from two checkouts
+ *   `worker-1/task16-3-…`        MERGED — resolves everywhere and is FROZEN by
+ *                                construction, so it reports an ever-growing
+ *                                stall on a lane that is finished
+ *
+ * THREE OF THOSE FOUR RESOLVED CLEANLY. So the test cannot be "does it
+ * resolve" — that check passed on every bad case except the path. The property
+ * is narrower and it is the one thing all four violate:
+ *
+ *   THE CELL MUST NAME A REF WHOSE MOVEMENT IS THIS AGENT'S WORK.
+ *
+ * Which decomposes into three questions git can actually answer:
+ *
+ *   scoped    does the ref name begin with this agent's id? That is the ONLY
+ *             per-agent signal this repo carries. Author cannot serve: measured
+ *             on 60 commits of `origin/main`, every one is authored "David
+ *             Balzan", so an `--author` filter would match every agent on every
+ *             ref forever WHILE LOOKING SCOPED.
+ *   shared    is it resolvable from ANY checkout, not just the one that happens
+ *             to have fetched it? That means the remote-tracking form.
+ *   live      is it still ahead of the base? A merged branch's ref never moves
+ *             again, so measuring it produces a number that only grows.
+ *
+ * WHAT THIS DELIBERATELY DOES NOT DO: guess. Every rejection is reported with
+ * the reason and the population it judged, and an UNPUSHED branch is called
+ * unpushed rather than stalled — a freshly claimed lane has no shared evidence
+ * yet, and saying "stalled" there would be the manufactured-narrowing error
+ * pointed at a new lane.
+ */
+import { execFileSync } from "node:child_process";
+
+export type BoardRefVerdict =
+  | { kind: "measurable"; ref: string }
+  | { kind: "empty"; why: string }
+  | { kind: "path"; why: string }
+  | { kind: "shared"; why: string }
+  | { kind: "unscoped"; why: string }
+  | { kind: "local-only"; why: string }
+  | { kind: "unpushed"; why: string }
+  | { kind: "merged"; why: string };
+
+const git = (repo: string, args: string[]): string | null => {
+  try {
+    return execFileSync("git", args, { cwd: repo, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+  } catch {
+    return null;
+  }
+};
+const resolves = (repo: string, ref: string): boolean => !!git(repo, ["rev-parse", "--verify", "--quiet", `${ref}^{commit}`]);
+
+/** The `\`ref\`` inside a `Branch · Worktree` cell, or "". */
+export function refInCell(cell: string): string {
+  return (String(cell ?? "").match(/`([^`]+)`/)?.[1] ?? "").trim();
+}
+
+/** The remote-tracking form a board cell should name for `branch`. */
+export const boardRefFor = (branch: string): string => (branch.startsWith("origin/") ? branch : `origin/${branch}`);
+
+/**
+ * Classify one cell for one agent.
+ *
+ * `base` is the ref a merged branch would be contained in — `origin/main` by
+ * convention, passed rather than assumed so a consumer fleet on another default
+ * branch is not silently misjudged.
+ */
+export function classifyBoardRef(
+  repo: string,
+  agentId: string,
+  cell: string,
+  base = "origin/main",
+): BoardRefVerdict {
+  const raw = refInCell(cell);
+  if (!raw) return { kind: "empty", why: "no ref in the Branch · Worktree cell" };
+
+  const bare = raw.replace(/^origin\//, "");
+
+  // A SHARED REF FIRST, because `main` resolves and would otherwise be measured.
+  // Named explicitly rather than inferred from scoping, so the reason a reader
+  // gets is the real one.
+  const shared = new Set(["main", "master", "develop", "trunk", "HEAD"]);
+  if (shared.has(bare)) {
+    return {
+      kind: "shared",
+      why:
+        `'${raw}' is a SHARED branch — every agent merges into it, so its movement is the fleet's activity and not '${agentId}'s. ` +
+        `A row pointing here can never stall, which is a manufactured green rather than a measurement.`,
+    };
+  }
+
+  // SCOPED BY NAME — but only refusing a ref that belongs to a DIFFERENT agent,
+  // never one that is merely unconventional.
+  //
+  // Authorship cannot carry ownership here (every commit in this repo is
+  // authored by the same person, so `--author` would match every agent on every
+  // ref while looking scoped), which leaves the branch-naming convention
+  // `<agentId>/<slice>`. But REQUIRING that convention would make a repo that
+  // does not use it universally blind — and a narrowing that disables the check
+  // everywhere is worse than the defect it fixes. So a plain `feature-x` is
+  // allowed and `<someone-else>/x` is refused: the second is positively
+  // someone else's work, the first is only unlabelled.
+  const owner = bare.includes("/") ? bare.slice(0, bare.indexOf("/")) : null;
+  if (owner && owner !== agentId && /^[\w.-]+-(worker|aide|qa|ci|coordinator)(-\d+)?$/.test(owner)) {
+    return {
+      kind: "unscoped",
+      why:
+        `'${raw}' is scoped to '${owner}', not '${agentId}' — its movement is that agent's work. ` +
+        `A per-agent signal needs a ref only this agent writes, and the branch name is the only ownership marker this repo carries.`,
+    };
+  }
+
+  const remote = `origin/${bare}`;
+  const remoteResolves = resolves(repo, remote);
+  const localResolves = resolves(repo, bare);
+
+  // NO SHARED FORM CAN EXIST, so the local ref is the best evidence there is.
+  // Without this a repo with no `origin` remote would report every row
+  // unmeasurable forever — the check disabled everywhere by a rule meant to
+  // make it honest. Preferring the shared form is right; requiring one that
+  // cannot exist is not.
+  if (!remoteResolves && !resolves(repo, "origin/HEAD") && git(repo, ["remote", "get-url", "origin"]) === null) {
+    if (!localResolves) {
+      return { kind: "path", why: `'${raw}' does not resolve as a git ref in a repo with no remote — it is a path or glob` };
+    }
+    return { kind: "measurable", ref: bare };
+  }
+
+  if (!remoteResolves) {
+    // Local-only vs never-pushed are different facts and only one is a defect
+    // in the CELL. Both are unmeasurable, and neither is a stall.
+    if (localResolves) {
+      return {
+        kind: "local-only",
+        why:
+          `'${raw}' resolves in THIS checkout and not on the remote, so the same board reads differently from another checkout — ` +
+          `whether it is measurable depends on who last ran \`git fetch\`, which is a property of the reader rather than of the work.`,
+      };
+    }
+    return {
+      kind: "unpushed",
+      why:
+        `'${remote}' does not exist — the branch has not been pushed, so there is no shared evidence of activity yet. ` +
+        `That is an ABSENCE of evidence on a new lane, not a stall.`,
+    };
+  }
+
+  // MERGED IS FROZEN. Its ref can never move again, so any age computed from it
+  // only grows — an ever-worsening stall on a lane that is finished.
+  //
+  // `--is-ancestor` ALONE CANNOT SEE IT, and this fleet is the case that proves
+  // it: we SQUASH-merge, so the branch's commits never become ancestors of the
+  // base. Measured on a branch I knew was merged — `--is-ancestor` said NO
+  // while the work was plainly on main. A merged-detector that cannot detect
+  // this repo's own merge strategy is inert, which is worse than absent because
+  // it reads as covered.
+  //
+  // `git cherry` compares PATCH IDS, so a squashed single-commit branch reports
+  // `-` (already upstream). It is not complete either — squashing several
+  // commits into one changes the patch id — so BOTH tests run and either one
+  // answering yes is enough. Neither is asked to be sufficient alone.
+  if (resolves(repo, base)) {
+    const ancestor = git(repo, ["merge-base", "--is-ancestor", remote, base]) !== null;
+    const cherry = git(repo, ["cherry", base, remote]);
+    const allUpstream =
+      cherry !== null && cherry.length > 0 && cherry.split("\n").every((l) => l.trim().startsWith("-"));
+    if (ancestor || allUpstream) {
+      return {
+        kind: "merged",
+        why:
+          `'${remote}' has already landed in ${base} (${ancestor ? "an ancestor" : "every commit's patch is upstream — a squash merge"}) — ` +
+          `so this ref is FROZEN and can never move again. ` +
+          `Measuring it reports a stall that grows forever on a finished lane. The row needs the agent's current slice, or an idle marker.`,
+      };
+    }
+  }
+
+  return { kind: "measurable", ref: remote };
+}

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