agent-coord-mcp 0.26.14 → 0.26.16

package/src/capabilities.ts

@@ -0,0 +1,188 @@
+/*
+ * Phase 5.1 Task 11 — CLOSE THE LOOP: answer a capability question by
+ * EXERCISING the capability, in the process that would serve it.
+ *
+ * 11.1: NO TIMESTAMP ON THIS BOX CAN ANSWER A CAPABILITY QUESTION. Every
+ * artefact people reach for is a proxy that fails differently:
+ *
+ *   an mtime          tracks WRITES. A reinstall of byte-identical code moves
+ *                     it, and an edit that never got built does not.
+ *   serverBuildMtime  is stamped at ATTACH, so it tells you when a transport
+ *                     started, not what the running process contains.
+ *   a version string  is a LABEL someone typed into package.json. Measured
+ *                     today: a tarball published as 0.5.23 contained a change
+ *                     the version numbering said it could not, and the number
+ *                     was believed over the artefact for an hour.
+ *   `npm view`        answers from a cache, and told this fleet the wrong
+ *                     published version twice in one morning.
+ *
+ * Each is honest about something and dishonest about capability, and the
+ * failure is always the same shape: an ANSWER ABOUT A LABEL read as an answer
+ * about behaviour.
+ *
+ * 11.2: A RELEASE IS NOT DELIVERED UNTIL A SERVER THAT RESTARTED ANSWERS.
+ * `merged · published · installed · restarted · observed` — five states, and
+ * the last two are the ones that keep being skipped. A probe run INSIDE the
+ * server process is the only artefact that speaks for the loaded code: it
+ * cannot be satisfied by a file that exists, a version that matches, or a
+ * package that installed, because it calls the code and reports what happened.
+ *
+ * WHY A PROBE MAY NEVER READ A VERSION: if a probe branched on a version
+ * string it would inherit that string's dishonesty, and a fleet would then
+ * have a capability check that passes on a restarted-but-not-upgraded server.
+ * Probes call behaviour. The version travels beside the answer as CONTEXT and
+ * is labelled as such.
+ */
+import { prRefsIn } from "./tools/record-events.js";
+import { EVENT_KIND_IDS } from "./tools/event-kinds.js";
+import { suggestRecordType, typedRecordMode } from "./typed-records.js";
+import { LEAD_REFUSED, PARKED_CATEGORIES } from "./tools/away.js";
+import { recordAuthorityFor } from "./roles.js";
+import { subscriptionHealth } from "./tools/events.js";
+
+export type ProbeResult = {
+  id: string;
+  /** The release the behaviour arrived in — reported, never TESTED against. */
+  since: string;
+  present: boolean;
+  /** What was actually called and what came back. The evidence, not a claim. */
+  evidence: string;
+};
+
+type Probe = { id: string; since: string; run: () => { present: boolean; evidence: string } };
+
+/**
+ * Each probe calls a behaviour that did not exist before its release and
+ * reports what it observed. A probe that could pass without the code being
+ * loaded is not a probe — it is a restatement of the version.
+ */
+const PROBES: Probe[] = [
+  {
+    id: "typed-records-obligatory",
+    since: "0.26.10",
+    run: () => {
+      const s = suggestRecordType("DONE: shipped it", []);
+      const mode = typedRecordMode();
+      return {
+        present: s.type === "done" && (mode === "warn" || mode === "refuse"),
+        evidence: `suggestRecordType("DONE: …") -> '${s.type}', policy mode '${mode}'`,
+      };
+    },
+  },
+  {
+    id: "record-events-all-kinds",
+    since: "0.26.12",
+    run: () => {
+      const kinds = [...EVENT_KIND_IDS].sort();
+      const present = ["item", "phase", "pr", "task"].every((k) => kinds.includes(k as never));
+      return { present, evidence: `subscribable kinds: ${kinds.join(", ")}` };
+    },
+  },
+  {
+    id: "multi-pr-citation",
+    since: "0.26.14",
+    run: () => {
+      const refs = prRefsIn("owner/repo#170, #173");
+      return {
+        present: refs.length === 2 && refs[1] === "owner/repo#173",
+        evidence: `prRefsIn("owner/repo#170, #173") -> [${refs.join(", ")}]`,
+      };
+    },
+  },
+  {
+    id: "away-means-david-away",
+    since: "0.26.13",
+    run: () => {
+      const present = "merge" in LEAD_REFUSED && PARKED_CATEGORIES.includes("licence" as never);
+      return {
+        present,
+        evidence: `coord_away refuses [${Object.keys(LEAD_REFUSED).join(", ")}] for the lead; parks ${PARKED_CATEGORIES.length} categories`,
+      };
+    },
+  },
+  {
+    id: "subscription-scanned-vs-evaluated",
+    since: "0.26.15",
+    run: () => {
+      // The capability is that "the machinery ran" and "your kind fired" are
+      // separable. Probed by asking for the state that used to be reported as
+      // broken: scanned, never evaluated — a healthy idle watch.
+      const base = { id: "p", agentId: "p", kind: "item", target: "t", createdAt: 0, lastEvaluatedAt: null, lastEventAt: null, delivered: [] } as never;
+      const quiet = subscriptionHealth({ ...(base as object), lastScannedAt: Date.now() } as never);
+      const unscanned = subscriptionHealth({ ...(base as object), lastScannedAt: null } as never);
+      return {
+        present: quiet.level === "ok" && unscanned.level === "error",
+        evidence: `scanned+quiet -> '${quiet.level}', never-scanned -> '${unscanned.level}'`,
+      };
+    },
+  },
+  {
+    id: "record-authority",
+    since: "0.24.0",
+    run: () => {
+      const worker = recordAuthorityFor({ roleId: "worker" });
+      return {
+        present: worker.mayNotEmit.includes("verdict"),
+        evidence: `a worker mayNotEmit: [${worker.mayNotEmit.join(", ")}]`,
+      };
+    },
+  },
+];
+
+export type CapabilityReport = {
+  /**
+   * WHICH PROCESS ANSWERED. Not evidence of anything — context, so a reader can
+   * tell two servers apart when their answers disagree. Deliberately beside the
+   * probe results rather than above them: the temptation this whole verb exists
+   * to remove is reading the identity INSTEAD of the answers.
+   */
+  answeredBy: { pid: number; startedAtIso: string; module: string; versionLabel: string };
+  probes: ProbeResult[];
+  missing: string[];
+  ok: boolean;
+  note: string;
+};
+
+export function probeCapabilities(context: { module: string; versionLabel: string }): CapabilityReport {
+  const probes: ProbeResult[] = PROBES.map((p) => {
+    try {
+      const r = p.run();
+      return { id: p.id, since: p.since, present: r.present, evidence: r.evidence };
+    } catch (e) {
+      // A THROWN PROBE IS AN ABSENT CAPABILITY, NOT A BROKEN CHECK. Older code
+      // that lacks the symbol throws exactly here, and reporting that as an
+      // error rather than an absence would make the common case look like a
+      // malfunction.
+      return { id: p.id, since: p.since, present: false, evidence: `probe threw: ${(e as Error).message}` };
+    }
+  });
+  const missing = probes.filter((p) => !p.present).map((p) => p.id);
+  return {
+    answeredBy: {
+      pid: process.pid,
+      startedAtIso: new Date(Date.now() - Math.round(process.uptime() * 1000)).toISOString(),
+      module: context.module,
+      versionLabel: context.versionLabel,
+    },
+    probes,
+    missing,
+    ok: missing.length === 0,
+    note:
+      "Every line above was produced by CALLING the code in this process. `versionLabel` is a label someone typed " +
+      "into package.json and is context, never evidence — a published tarball has already been observed carrying a " +
+      "change its version said it could not. THIS ANSWER IS ABOUT ONE PROCESS: a release is delivered when every " +
+      "live agent's OWN server answers, which is the fifth state (merged · published · installed · restarted · observed). " +
+      "A server that has not restarted answers honestly about the old code it is still running.",
+  };
+}
+
+/* ── the verb ──────────────────────────────────────────────────────────────── */
+
+import { resolveServerIdentity } from "./server-identity.js";
+
+export const capabilitiesSchema = {} as const;
+
+export async function capabilitiesTool() {
+  const id = resolveServerIdentity();
+  return probeCapabilities({ module: id.path, versionLabel: id.version });
+}

package/src/server-identity.ts

@@ -0,0 +1,83 @@
+/*
+ * WHICH SERVER PACKAGE IS RUNNING — a LEAF module, importing nothing from
+ * `tools/`.
+ *
+ * It lived in `transport.ts`, and `capabilities.ts` imported it from there. The
+ * moment `status` needs to REPORT capabilities, that becomes
+ * transport -> capabilities -> transport: a cycle, and the same one Task 9
+ * produced when the kind registry sat inside `record-events.ts`. That one only
+ * worked because `tools/index.ts` happened to import in the surviving order —
+ * a load-ORDER dependency, invisible until something imported a module
+ * directly, which is what a consumer or a test does.
+ *
+ * A cycle that works by luck is not a working cycle, so the shared fact moves
+ * out rather than the edge being added on top of it.
+ *
+ * NOTE WHAT THIS REPORTS AND WHAT IT DOES NOT. `version` is the label in the
+ * package.json this process loaded from — CONTEXT for a reader, never evidence
+ * of a capability. A published tarball has already been observed carrying a
+ * change its version said it could not. Capability questions are answered by
+ * `capabilities`, which CALLS the code.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { isGitRepo } from "./tools/scopes.js";
+
+/** 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;
+}

package/src/server.ts

@@ -10,11 +10,14 @@ import { coordAwaySchema, coordAwayTool, readAway, awayRefusal, secondCoordinato
 import { rotateSchema, rotateTool, rotateReconcileSchema, rotateReconcileTool } from "./tools/rotate.js";
 import { subscribeSchema, subscribeTool, unsubscribeSchema, unsubscribeTool, listSubscriptionsSchema, listSubscriptionsTool } from "./tools/events.js";
 import { scanRecordEventsSchema, scanRecordEventsTool } from "./tools/record-events.js";
+import { capabilitiesSchema, capabilitiesTool } from "./capabilities.js";
 import {
   ensureDirs,
   getTokenMap,
   reloadTokenMapSync,
   sessionFile,
+  listSessionFiles,
+  readJson,
   type SessionBinding,
 } from "./store.js";
 import {
@@ -105,6 +108,7 @@ import {
   listWorkTool,
   exportWorkSchema,
   exportWorkTool,
+  isPidAlive,
 } from "./tools/index.js";
 
 function jsonResult(data: unknown) {
@@ -145,6 +149,41 @@ function buildServer(initialBound?: string, opts: { trackSession?: boolean } = {
   let sessionMarker: string | undefined;
   let exitHooksInstalled = false;
 
+  // Task 16.1: the stdio half of the leak `#174` closed for HTTP. `#169`
+  // shipped an idle-timeout version of this and was HELD after a live test
+  // proved the failure mode it risked: killing a session's process out from
+  // under a still-attached client is SILENT, NON-RECOVERABLE loss, and idle
+  // is not abandoned. This reaps on the same signal `#174` uses instead — a
+  // NEW bind for the SAME agent id — which needs no timer and no guess.
+  //
+  // Why a new bind is PROOF rather than a guess, mirroring `#174`'s
+  // `agentSessions` reasoning one process boundary over: `recordSessionBinding`
+  // only runs after `guardFirstClaim` has already authorized this claim —
+  // tofu (verified the id was NOT live), token (the holder's own credential),
+  // force (an explicit override) or same-pane (the same physical seat
+  // restarting). In every one of those four paths, whoever controls this
+  // agent id has already moved to THIS session, so any other live marker for
+  // the same id left over is provably superseded, not merely idle — the
+  // exact distinction `#169` could not make with a timer.
+  async function reapSupersededStdioSessions(agentId: string): Promise<void> {
+    for (const file of await listSessionFiles()) {
+      const s = await readJson<SessionBinding | null>(file, null);
+      if (!s || s.agentId !== agentId || s.pid === process.pid) continue;
+      if (!isPidAlive(s.pid)) continue; // already gone; nothing to signal
+      console.error(
+        `[agent-coord-mcp] reaping stdio session pid ${s.pid} for agent '${agentId}' — superseded by this session (pid ${process.pid})`,
+      );
+      try {
+        // SIGTERM, not a kill(9): the superseded process's OWN exit hook
+        // (below) unlinks its marker and exits 0 — the same graceful path
+        // an operator's `quit` or Ctrl-C would take, not a hard kill.
+        process.kill(s.pid, "SIGTERM");
+      } catch (err) {
+        console.error(`[agent-coord-mcp] reap FAILED for pid ${s.pid}:`, err);
+      }
+    }
+  }
+
   // Best-effort: a marker left behind by SIGKILL has a dead pid, which both
   // the guard's evidence read and doctor's duplicate-session-binding check
   // treat as garbage (doctor fix deletes it).
@@ -176,6 +215,9 @@ function buildServer(initialBound?: string, opts: { trackSession?: boolean } = {
           process.on(sig, () => { cleanup(); process.exit(0); });
         }
       }
+      reapSupersededStdioSessions(agentId).catch((err) =>
+        console.error("[agent-coord-mcp] stdio supersession reap threw:", err),
+      );
     } catch { /* marker is observability, never worth failing the bind */ }
   }
 
@@ -215,9 +257,28 @@ function buildServer(initialBound?: string, opts: { trackSession?: boolean } = {
     }
     if (ev.live) {
       if (ev.samePane && ev.boundElsewhere === 0) return "same-pane";
+      // A LEFTOVER SESSION IS NAMED AS ONE, AND force DOES NOT REMOVE IT.
+      //
+      // The old wording reported the same evidence and then offered `force:true`
+      // as the way through, which reads as a procedural step. It is not: forcing
+      // past a live session does not stop that process — it adds a second
+      // claimant to one identity, which is the condition that had two sessions
+      // holding worker-3's yesterday. The refusal papered over the thing it had
+      // just detected.
+      //
+      // A live TRANSPORT marker is a different fact and is not called a leak:
+      // that pid is the pusher daemon, doing its job. Only a live SESSION
+      // binding that is not this process is a leftover.
+      const leaks = ev.leakedSessions ?? [];
+      const leakLine = leaks.length
+        ? ` LEFTOVER PROCESS${leaks.length > 1 ? "ES" : ""} HOLDING THIS IDENTITY: ` +
+          leaks.map((l) => `pid ${l.pid} (via ${l.via})`).join(", ") +
+          `. Look at ${leaks.length > 1 ? "them" : "it"} before deciding — \`ps -p ${leaks.map((l) => l.pid).join(",")}\` — because force:true does NOT stop ${leaks.length > 1 ? "those processes" : "that process"}; it binds a SECOND session to one identity, and two sessions on one id is the defect this refusal exists to surface, not a step past it.`
+        : "";
       throw new Error(
-        `agent '${claimed}' is live on this bus (${ev.reasons.join("; ")}) — refusing to bind this fresh session to it. ` +
-          `If you ARE '${claimed}' restarting, re-join from its tmux pane, or pass its token or force:true (join/register). ` +
+        `agent '${claimed}' is live on this bus (${ev.reasons.join("; ")}) — refusing to bind this fresh session to it.` +
+          leakLine +
+          ` If you ARE '${claimed}' restarting, re-join from its own tmux pane${leaks.length ? " once nothing else holds it" : ""}, or pass its token. ` +
           `If you are diagnosing, use status/ping (read-only, they never bind) or your own id.`,
       );
     }
@@ -635,6 +696,13 @@ function buildServer(initialBound?: string, opts: { trackSession?: boolean } = {
     gate("agentId", subscribeTool as (a: Record<string, unknown>) => Promise<unknown>),
   );
 
+  addTool(
+    "capabilities",
+    "What THIS SERVER PROCESS can actually do, answered by CALLING each capability rather than by reading a version, an mtime, or a file. No timestamp on the box can answer a capability question: an mtime tracks writes (a reinstall of identical bytes moves it), `serverBuildMtime` is stamped at attach, and a version is a label someone typed — a published tarball has been observed carrying a change its version said it could not. Each probe reports the call it made and what came back, so an absent capability reads as an absence rather than an error. THE ANSWER IS ABOUT ONE PROCESS: a release is delivered only when every live agent's OWN server answers, which is the fifth state (merged \u00b7 published \u00b7 installed \u00b7 restarted \u00b7 observed). A server that has not restarted answers honestly about the old code it still runs.",
+    capabilitiesSchema,
+    gate(null, capabilitiesTool as () => Promise<unknown>),
+  );
+
   addTool(
     "scan_record_events",
     "Turn a repo's COMMITTED record changes into events: new `docs/DONE.md` entries, queue items that left `docs/QUEUE.md`, and newly-ticked phase checkboxes, between the stored watermark and HEAD. The commit is the boundary \u2014 an uncommitted edit is not yet a record. A HAND-EDIT fires exactly like `land` does, which is the point: fleets merge with `gh` and edit DONE.md directly. Reports by default; `write:true` delivers and advances the watermark. Re-scanning a delivered range is safe (the idempotency key comes from the event, so it reports duplicate-suppressed), and a watermark that no longer resolves REFUSES rather than silently narrowing its window.",

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 };
+}