agent-coord-mcp 0.26.15 → 0.26.17

package/src/server.ts

@@ -16,6 +16,8 @@ import {
   getTokenMap,
   reloadTokenMapSync,
   sessionFile,
+  listSessionFiles,
+  readJson,
   type SessionBinding,
 } from "./store.js";
 import {
@@ -106,6 +108,7 @@ import {
   listWorkTool,
   exportWorkSchema,
   exportWorkTool,
+  isPidAlive,
 } from "./tools/index.js";
 
 function jsonResult(data: unknown) {
@@ -132,8 +135,13 @@ function jsonResult(data: unknown) {
 //     transport, or another live bound session) — that silently created a
 //     second session acting as an already-running agent (hit live 2026-07-06:
 //     a dev session bound itself to `<project>-liaison`). A live-id claim needs
-//     the agent's token or an explicit force (join/register params). See
-//     guardFirstClaim for how absent vs unreadable evidence is decided.
+//     the agent's TOKEN — `force` alone is refused against a provably live
+//     incumbent (q-314e0187, v0.26.0: `force` used to bypass this evidence
+//     check entirely, which is what let two live sessions hold
+//     `groundwork-kit-worker-3` at once on 2026-08-31). `force` still works
+//     for evidence the guard cannot verify at all, or an id verified absent.
+//     See guardFirstClaim for how absent vs unreadable vs live-but-unproven
+//     evidence is decided.
 //   - `trackSession` (stdio only): each successful bind writes a
 //     sessions/<id>.<pid>.<nonce>.json marker so doctor can SEE two live
 //     sessions bound to one id — closure state alone cannot be inspected
@@ -146,6 +154,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).
@@ -177,6 +220,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 */ }
   }
 
@@ -186,9 +232,14 @@ function buildServer(initialBound?: string, opts: { trackSession?: boolean } = {
   //   - a presented token must MATCH or the claim fails loudly, even when the
   //     id is not live — a wrong credential silently succeeding via the
   //     not-live path would teach callers that garbage tokens work;
-  //   - force is an explicit human/agent decision, honored before evidence;
-  //   - evidence that exists but cannot be read REFUSES (cannot-verify ≠
-  //     verified-absent; unreadable state must not disable the guard);
+  //   - evidence is gathered BEFORE `force` is consulted (q-314e0187): a live
+  //     PROVABLE incumbent can no longer be superseded by `force` alone — see
+  //     below. `force` is still honored, but only where it was never the
+  //     defect: unverifiable evidence, or a verified-absent id;
+  //   - evidence that exists but cannot be read REFUSES unless `force` is
+  //     passed (cannot-verify ≠ verified-absent; unreadable state must not
+  //     silently disable the guard, but an explicit override still works —
+  //     there is no incumbent to protect from being duplicated here);
   //   - a live id refuses, except when its live pusher types into THIS
   //     process's own tmux pane — two sessions cannot share a pane, so that
   //     is the same seat restarting (the routine fleet-restart case), not a
@@ -205,9 +256,9 @@ function buildServer(initialBound?: string, opts: { trackSession?: boolean } = {
           `Mint one with scripts/coord-token.mjs add ${claimed} (then SIGHUP the bus), or pass force:true if you are certain.`,
       );
     }
-    if (args["force"] === true) return "force";
     const ev = await liveClaimEvidence(claimed, Date.now());
     if (!ev.verifiable) {
+      if (args["force"] === true) return "force";
       throw new Error(
         `cannot verify whether '${claimed}' is live: ${ev.reasons.join("; ")}. ` +
           `Refusing to bind rather than treating unreadable evidence as absence. ` +
@@ -216,12 +267,41 @@ 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 NO LONGER REMOVES IT
+      // EITHER — q-314e0187: `force:true` used to be checked BEFORE this
+      // evidence was even gathered (line order, not this message), so a
+      // provably-live incumbent was never actually protected — it just
+      // looked protected to anyone who did not pass `force`. Measured
+      // 2026-08-31: `doctor` found pid 7129 (via FORCE) and pid 9760 (via
+      // same-pane) both live and bound to `groundwork-kit-worker-3`
+      // simultaneously, and the bus log could not tell which one wrote a
+      // disputed message. `force` binding past a live session does not stop
+      // that process — it adds a second claimant to one identity, which is
+      // the condition that produced exactly that incident. So a provably
+      // live incumbent can now be superseded ONLY by its own token; `force`
+      // is refused here regardless of its value.
+      //
+      // 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(",")}\`.`
+        : "";
       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` +
+          (args["force"] === true ? ", even with force:true" : "") +
+          `.` +
+          leakLine +
+          ` A live incumbent can only be superseded with ITS OWN TOKEN now (mint one: scripts/coord-token.mjs add ${claimed}, then SIGHUP the bus) — ` +
+          `\`force:true\` binds a SECOND session to one identity rather than stopping the first, which is the defect this refusal exists to prevent, not a step past it. ` +
+          `If you ARE '${claimed}' restarting, re-join from its own tmux pane${leaks.length ? " once nothing else holds it" : ""}. ` +
           `If you are diagnosing, use status/ping (read-only, they never bind) or your own id.`,
       );
     }
+    if (args["force"] === true) return "force";
     return "tofu";
   }
 
@@ -289,7 +369,7 @@ function buildServer(initialBound?: string, opts: { trackSession?: boolean } = {
 
   addTool(
     "join",
-    "Recommended session-start call. Does register + auto-attach (if running inside tmux) + read inbox in one round-trip. Pass attach=false to skip the transport, attach={...overrides} to customize, or omit it to let the server auto-detect $TMUX_PANE. Returns the registration, attach result, any unread inbox messages, and the default channel's topic + MOTD (room rules) so you see them on connect. Calling join binds this MCP process's identity to agentId for the lifetime of the session — no env var or config needed. Each Claude Code session runs its own stdio process so bindings are naturally isolated. Claiming an id that is currently LIVE on the bus (fresh heartbeat, live pusher, or another bound session) is refused unless the claim comes from that agent's own tmux pane or carries the agent's token or force:true — diagnosing someone else's agent is what status/ping are for. `proseOnly:true` claims the per-agent exemption from the typed-record rule — see `register`.",
+    "Recommended session-start call. Does register + auto-attach (if running inside tmux) + read inbox in one round-trip. Pass attach=false to skip the transport, attach={...overrides} to customize, or omit it to let the server auto-detect $TMUX_PANE. Returns the registration, attach result, any unread inbox messages, and the default channel's topic + MOTD (room rules) so you see them on connect. Calling join binds this MCP process's identity to agentId for the lifetime of the session — no env var or config needed. Each Claude Code session runs its own stdio process so bindings are naturally isolated. Claiming an id that is currently LIVE on the bus (fresh heartbeat, live pusher, or another bound session) is refused unless the claim comes from that agent's own tmux pane or carries the agent's token — `force:true` no longer overrides a provably live incumbent (only the token does); it still works when liveness cannot be verified at all or the id is verified absent. Diagnosing someone else's agent is what status/ping are for. `proseOnly:true` claims the per-agent exemption from the typed-record rule — see `register`.",
     joinSchema,
     // join explicitly sets the session binding when unset, so each agent can
     // declare its identity via join rather than relying on env vars.

package/src/tools/board-ref.ts

@@ -0,0 +1,239 @@
+/*
+ * 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}`]);
+
+// Task 5.3/22.1's confirmation half: `docs/*` — a real historical cell value
+// — is a GLOB, and `git check-ref-format` refuses it as a branch name (a `*`
+// is not legal in a ref). A plain path like `docs/QUEUE.md` is, frustratingly,
+// ALSO a syntactically valid ref name (slashes and dots are both legal), so
+// this catches the glob shape precisely and does not claim to catch every
+// path — an honest partial fix is the property this task's own title asks
+// for ("every classifier can say I cannot tell"), not a heuristic that
+// pretends to be exhaustive.
+// Pure syntax check — never needs to run INSIDE a repo, so no `cwd` (unlike
+// every other helper here, which resolves refs against `repo`'s history).
+const isSyntacticallyValidRef = (name: string): boolean => {
+  try {
+    execFileSync("git", ["check-ref-format", "--branch", name], { stdio: ["ignore", "pipe", "ignore"] });
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+/** 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\//, "");
+
+  // Task 5.3/22.1: CHECKED FIRST AND UNCONDITIONALLY — the original defect
+  // (`docs/*`) was previously only caught in a repo with NO origin remote at
+  // all (further down); confirmed live that in a repo WITH an origin — the
+  // normal case for every worktree this fleet actually runs — the same
+  // value fell through to the "unpushed" branch instead and was reported as
+  // "the branch has not been pushed", which is a confidently WRONG diagnosis
+  // for a path. `git check-ref-format` answers "could this even syntactically
+  // be a branch name" without touching the repo's history at all, so a glob
+  // is caught regardless of what else is true about this checkout.
+  if (!isSyntacticallyValidRef(bare)) {
+    return { kind: "path", why: `'${raw}' is not a syntactically valid branch name — it is a path or glob` };
+  }
+
+  // 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.`,
+      };
+    }
+    // Task 5.3/22.2's fourth cause: "a pushed branch absent from this
+    // checkout" is NOT the same fact as "never pushed", and this check has
+    // no way to tell them apart without a network call it deliberately does
+    // not make (every other verdict here is a local git op only — adding
+    // one here would trade the offline property for one more cause). SAYING
+    // SO is the fix Task 22's own title asks for: a classifier that names
+    // an ABSENCE of evidence as a specific, confident cause is the exact
+    // shape "it is a path or glob" was wrong in — just moved one branch
+    // over. `'${remote}' does not exist` is the one fact this DOES know;
+    // everything past it is now framed as what it cannot distinguish rather
+    // than a guess dressed as a finding.
+    return {
+      kind: "unpushed",
+      why:
+        `'${remote}' does not resolve in THIS checkout — either the branch has never been pushed, or it WAS pushed and this ` +
+        `checkout's remote-tracking ref is simply stale (nobody has run \`git fetch\` here since). Cannot distinguish the two ` +
+        `without asking the remote, which this check deliberately does not do. Either way there is no LOCAL evidence of ` +
+        `activity, so it is not scored as 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/messaging.ts

@@ -14,6 +14,11 @@ import { spawn, spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { z } from "zod";
 import { readLog } from "./logwatch.js";
+// The replay grammar is single-sourced in hooks/replay.mjs and shared with both
+// pushers — see the note at the annotation site below. `hooks/` ships beside
+// `dist/`, so this resolves the same in the built package as in source.
+// @ts-expect-error — untyped .mjs sibling, deliberately not duplicated in TS
+import { priorDeliveries, replayInfo } from "../../hooks/replay.mjs";
 import { renderRecord } from "./render.js";
 import path from "node:path";
 import {
@@ -270,6 +275,21 @@ async function messageIdExists(id: string): Promise<boolean> {
   return false;
 }
 
+// q-314e0187: `process.pid` is this MCP process's own pid — the process
+// writing the entry right now, always known, no lookup needed. It is what a
+// disputed message can be cross-referenced against (sessions/*.json,
+// `ps -p <pid>`) when two live sessions hold one identity. In stdio mode this
+// pid uniquely identifies the session (one process per session); in HTTP mode
+// many sessions can share a process, so it identifies the SERVER handling the
+// call rather than the caller — still strictly more than nothing, and the
+// same scoping `trackSession` already applies to session markers.
+function messageProvenance(): { pid: number; tmuxPane?: string } {
+  return {
+    pid: process.pid,
+    ...(process.env.TMUX_PANE ? { tmuxPane: process.env.TMUX_PANE } : {}),
+  };
+}
+
 export async function sendMessageTool(args: {
   from: string;
   to?: string;
@@ -375,6 +395,7 @@ export async function sendMessageTool(args: {
       text,
       ...(args.record ? { record: args.record } : {}),
       ...(args.inReplyTo ? { inReplyTo: args.inReplyTo } : {}),
+      provenance: messageProvenance(),
     };
     const target = inboxFile(args.to);
     await appendJsonl(target, msg);
@@ -400,6 +421,7 @@ export async function sendMessageTool(args: {
     ...(args.kind ? { kind: args.kind } : {}),
     ...(args.record ? { record: args.record } : {}),
     ...(args.inReplyTo ? { inReplyTo: args.inReplyTo } : {}),
+    provenance: messageProvenance(),
   };
   const target = roomFile(chan);
   await appendJsonl(target, msg);
@@ -540,11 +562,30 @@ export async function readMessagesTool(args: {
       ? recent.filter((e) => entryAuthor(e) !== args.agentId)
       : recent;
 
+  // Phase 5.3 Task 21.2 — ANNOTATE A MESSAGE THAT HAS ALREADY BEEN DELIVERED.
+  //
+  // The REMOTE pusher (scripts/coord-pusher.mjs) consumes the bus over the wire
+  // and cannot read this host's receipts/, so it cannot see for itself that a
+  // message it is about to paste was pasted before. Without this, the replay
+  // marker would appear in local panes only — HALF THE FLEET, and the half a
+  // reader could not identify from inside the pane, which is worse than no
+  // marker because its absence would read as "live".
+  //
+  // The two routes compute the same DATA and share ONE renderer
+  // (hooks/replay.mjs `replayMarker`), so neither pane can be handed a
+  // different vocabulary for the same fact.
+  const priorText = await fsp.readFile(receiptFile(args.agentId), "utf8").catch(() => "");
+  const prior = priorDeliveries(priorText);
+  const annotated = visible.map((e) => {
+    const replay = "id" in e ? replayInfo(prior, (e as Message).id) : undefined;
+    return replay ? { ...e, replay } : e;
+  });
+
   return {
     ok: true,
-    messages: visible,
+    messages: annotated,
     totalNew,
-    returned: visible.length,
+    returned: annotated.length,
     room: args.source === "room" ? normalizeRoom(args.room) : undefined,
     ...(history ? { history } : {}),
   };

package/src/tools/records.ts

@@ -22,11 +22,12 @@ import {
   doneEntriesOf,
   type QueueItem,
   type WorkDoc,
-  phaseCitationsIn,
+  phaseCitationsDetailed,
   newlyTickedInDiff,
   sweepTagOf,
 } from "@davidbalzan/groundwork-seam";
 import { ensureWorktreeTool } from "./worktrees.js";
+import { boardRefFor, classifyBoardRef } from "./board-ref.js";
 import { haltState } from "./stall.js";
 import { readSubs, evaluate, commitEvaluation, eventIsDerived, type RecordEvent } from "./events.js";
 
@@ -146,7 +147,34 @@ export async function nextUnblockedTool(args: { project: string; repo?: string }
   const q = readDoc(repo, QUEUE_DOC);
   if (!q) return { ok: false as const, error: `no ${QUEUE_DOC} under '${repo}'` };
   const items = queueItemsOf(q.doc);
-  const open = items.filter((i) => !i.done);
+
+  // ALREADY-DELIVERED ITEMS ARE NEVER RE-OFFERED, and `!i.done` alone does not
+  // establish that.
+  //
+  // MEASURED, 2026-09-01: an item whose work had merged in #196 was still `[ ]`
+  // in the queue — closing it is a separate act from landing it — so it stayed
+  // eligible. A compaction then re-issued its id, it surfaced as the top item,
+  // and it was routed back to the worker that had closed it an hour earlier.
+  // That worker declined because it recognised its own acceptance criteria:
+  // RETAINED CONTEXT, which is not a control and which a `/clear` or a
+  // compaction removes silently.
+  //
+  // So delivery is read from the RECORD instead: an item cited in docs/DONE.md,
+  // or already carrying a 🚧 row on the board, has been handed out. Stable ids
+  // (Task 21.1) are what make this join reliable — with a content-hash id the
+  // board row and the DONE entry stopped matching the moment anyone reworded
+  // the item, which is how the memory was lost in the first place.
+  const delivered = new Set<string>();
+  const doneDoc = readDoc(repo, DONE_DOC);
+  const doneText = doneDoc?.text ?? "";
+  const boardDoc = readDoc(repo, BOARD_DOC);
+  const boardText = boardDoc?.text ?? "";
+  for (const i of items) {
+    // The id as written, so a recorded id matches the same token in either doc.
+    if (doneText.includes(i.id) || boardText.includes(i.id)) delivered.add(i.id);
+  }
+
+  const open = items.filter((i) => !i.done && !delivered.has(i.id));
   const ranked = open
     .map((i, idx) => ({ i, idx }))
     .sort((a, b) => (PRIORITY_ORDER[a.i.priority ?? "P3"] ?? 3) - (PRIORITY_ORDER[b.i.priority ?? "P3"] ?? 3) || a.idx - b.idx);
@@ -340,7 +368,61 @@ 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.
+  const intendedRef = boardRefFor(wt.branch ?? "");
+
+  /*
+   * AND NOW ACTUALLY ENFORCED AT THE WRITE.
+   *
+   * The comment here used to claim exactly that — "enforced at the WRITE as well
+   * as the read, a rule the writer can defeat is a rule the writer defeats" —
+   * and it was FALSE. `boardRefFor` PREFIXES `origin/`; it refuses nothing. So
+   * `claim` could still write `origin/main` into a board cell, which
+   * `stall_check` then correctly refuses to measure, leaving a row that can
+   * never stall and never be measured. board-ref.ts's own header states the
+   * rule; #197 shipped the read half and I wrote the sentence and did not do it.
+   *
+   * A rule carrying a false mechanism is worse than an absent rule: the next
+   * reader derives from the mechanism, and this one asserted the very coverage
+   * it lacked.
+   *
+   * REFUSED: the four kinds that are structurally wrong however fresh the lane
+   * is — a shared ref (measures the fleet), a path (not a ref at all), another
+   * agent's branch (measures their work), and an empty cell.
+   *
+   * ALLOWED: `unpushed` and `local-only`, deliberately. A freshly cut branch is
+   * ALWAYS unpushed, so refusing those would refuse every legitimate claim —
+   * the over-narrowing I have now made twice in this classifier's history, where
+   * a rule meant to make a check honest disabled it instead. `merged` is allowed
+   * too but noted, since re-claiming onto a landed branch is unusual rather than
+   * structurally broken.
+   */
+  const refusable = new Set(["shared", "path", "unscoped", "empty"]);
+  const cellVerdict = classifyBoardRef(repo, args.agentId, `\`${intendedRef}\``, `origin/${args.base ?? "main"}`);
+  if (refusable.has(cellVerdict.kind)) {
+    return {
+      ok: false as const,
+      error:
+        `cannot claim: the board cell would name '${intendedRef}', which is not a per-agent activity signal ` +
+        `(${cellVerdict.kind}) — ${"why" in cellVerdict ? cellVerdict.why : ""} ` +
+        `The row would be unmeasurable the moment it was written, so it is refused here rather than reported later.`,
+      item: { id: item.id, priority: item.priority },
+      worktree: { path: wt.path, branch: wt.branch },
+    };
+  }
+
+  const boardHunk = `| ${keyOf(item)} | ${args.agentId} | \`${intendedRef}\` · ${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
@@ -743,15 +825,47 @@ export async function mergeTool(
   // copied, because a copied grammar is two grammars the moment one is fixed.
   const ticked = newlyTickedInDiff(f.diff ?? "");
   if (ticked.size) {
-    const cited = phaseCitationsIn(f.citationText ?? "");
-    const uncited = [...ticked].filter((k) => !cited.has(k));
+    /*
+     * A RELATIONAL CITATION DOES NOT EVIDENCE A TICK.
+     *
+     * "unblocks Phase 5.2 Task 15.6" names the task without claiming it is done,
+     * so a PR that ticks 15.6's box and cites it that way is exactly as
+     * unevidenced as one that never mentioned it. Measured on the other side of
+     * this grammar the same day: doctor read that sentence in DONE.md as a
+     * completion claim and red-gated main.
+     *
+     * The two cases are REPORTED SEPARATELY, because they need different fixes
+     * and "UNCITED" would send someone looking for a citation that is already
+     * there. A relational citation needs REWORDING; an absent one needs ADDING.
+     */
+    const detail = phaseCitationsDetailed(f.citationText ?? "");
+    const closes = new Set(detail.filter((c) => c.relation === "claim").map((c) => c.key));
+    const relational = new Map(detail.filter((c) => c.relation === "reference").map((c) => [c.key, c.marker]));
+    const uncited = [...ticked].filter((k) => !closes.has(k));
     if (uncited.length) {
-      const names = uncited.map((k) => { const [p, id] = k.split(":"); return `Phase ${p} Task ${id}`; });
+      const nameOf = (k: string) => { const [p, id] = k.split(":"); return `Phase ${p} Task ${id}`; };
+      const names = uncited.map(nameOf);
+      const worded = uncited.filter((k) => relational.has(k));
+      const missing = uncited.filter((k) => !relational.has(k));
+      const parts: string[] = [];
+      if (missing.length) {
+        parts.push(
+          `${missing.length} NOT CITED AT ALL: ${missing.map(nameOf).join(", ")} — name them in the PR title or a commit ` +
+            `subject (e.g. "${nameOf(missing[0] as string)}"), the subject being what survives a squash merge`,
+        );
+      }
+      if (worded.length) {
+        parts.push(
+          `${worded.length} cited only RELATIONALLY: ` +
+            worded.map((k) => `${nameOf(k)} (after '${relational.get(k)}')`).join(", ") +
+            ` — that names the task without claiming it is done, so it evidences nothing. Reword it, or drop the tick`,
+        );
+      }
       return {
         ok: false as const,
         error:
-          `#${n} ticks ${ticked.size} phase checkbox(es) and ${uncited.length} of them are UNCITED: ${names.join(", ")}. ` +
-          `Once this merges, the tick claims progress that nothing in history evidences. Name them in the PR title or a commit subject (e.g. "${names[0]}") — the subject is what survives a squash merge.`,
+          `#${n} ticks ${ticked.size} phase checkbox(es) and ${uncited.length} of them are UNEVIDENCED. ` +
+          `${parts.join(". ")}. Once this merges, the tick claims progress nothing in history supports.`,
         verdict,
         uncited: names,
       };