agent-coord-mcp 0.26.16 → 0.26.17

package/src/server.ts

@@ -135,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
@@ -227,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
@@ -246,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. ` +
@@ -257,14 +267,19 @@ 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 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
@@ -273,15 +288,20 @@ function buildServer(initialBound?: string, opts: { trackSession?: boolean } = {
       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.`
+          `. 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.` +
+        `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 +
-          ` If you ARE '${claimed}' restarting, re-join from its own tmux pane${leaks.length ? " once nothing else holds it" : ""}, or pass its token. ` +
+          ` 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";
   }
 
@@ -349,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

@@ -65,6 +65,25 @@ const git = (repo: string, args: string[]): string | 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();
@@ -91,6 +110,19 @@ export function classifyBoardRef(
 
   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.
@@ -152,11 +184,24 @@ export function classifyBoardRef(
           `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 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.`,
+        `'${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.`,
     };
   }
 

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,12 +22,12 @@ import {
   doneEntriesOf,
   type QueueItem,
   type WorkDoc,
-  phaseCitationsIn,
+  phaseCitationsDetailed,
   newlyTickedInDiff,
   sweepTagOf,
 } from "@davidbalzan/groundwork-seam";
 import { ensureWorktreeTool } from "./worktrees.js";
-import { boardRefFor } from "./board-ref.js";
+import { boardRefFor, classifyBoardRef } from "./board-ref.js";
 import { haltState } from "./stall.js";
 import { readSubs, evaluate, commitEvaluation, eventIsDerived, type RecordEvent } from "./events.js";
 
@@ -147,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);
@@ -352,9 +379,50 @@ export async function claimTool(args: { project: string; agentId: string; itemId
   // 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 |`;
+  // 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
@@ -757,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,
       };

package/src/tools/registry.ts

@@ -79,8 +79,11 @@ export const registerSchema = {
   project: z.string().optional(),
   role: roleInputSchema.optional(),
   // First-claim guard overrides (server.ts guardFirstClaim): claiming an id
-  // that is LIVE on the bus refuses unless the call presents that agent's
-  // token (tokens.json / coord-token) or force:true. Ignored once bound.
+  // that is PROVABLY LIVE on the bus refuses unless the call presents that
+  // agent's token (tokens.json / coord-token) — `force` alone no longer
+  // overrides a provably live incumbent (q-314e0187). `force` still bypasses
+  // the guard when liveness cannot be verified, or the id is verified absent.
+  // Both ignored once bound.
   token: z.string().optional(),
   force: z.boolean().optional(),
   // PROSE-ONLY EXEMPTION (Phase 5.1 Task 12.8). `true` grants it, `false`

package/src/tools/shared.ts

@@ -182,6 +182,16 @@ export type Message = {
   // (or any other message) carries the parent message id so consumers can
   // mark the packet answered. Absent on every v1/v2 message — those stay valid.
   inReplyTo?: string;
+  // PROVENANCE (q-314e0187): the pid of the process that wrote this entry,
+  // and its tmux pane when known. `from` names an IDENTITY, not a PROCESS —
+  // two live sessions bound to the same agent id write byte-identical `from`
+  // values, and that is exactly the condition that let worker-3 truthfully
+  // deny sending a message that exists under its name on 2026-08-31: both
+  // sessions' accounts were true, and nothing on the message could say which
+  // wrote it. Cross-reference against sessions/*.json (SessionBinding) or
+  // `ps -p <pid>` to attribute a disputed entry. Absent on every message
+  // written before this field existed — that is UNKNOWN, not "same process".
+  provenance?: { pid: number; tmuxPane?: string };
 };
 
 // THE retention predicate — one definition, three call sites (prune,

package/src/tools/transport.ts

@@ -927,8 +927,11 @@ export const joinSchema = {
   attach: z.union([z.boolean(), joinAttachOptionsSchema]).optional(),
   readInbox: z.boolean().optional(),
   // First-claim guard overrides (server.ts guardFirstClaim): claiming an id
-  // that is LIVE on the bus refuses unless the call presents that agent's
-  // token (tokens.json / coord-token) or force:true. Ignored once bound.
+  // that is PROVABLY LIVE on the bus refuses unless the call presents that
+  // agent's token (tokens.json / coord-token) — `force` alone no longer
+  // overrides a provably live incumbent (q-314e0187). `force` still bypasses
+  // the guard when liveness cannot be verified, or the id is verified absent.
+  // Both ignored once bound.
   token: z.string().optional(),
   force: z.boolean().optional(),
   // Prose-only exemption from the typed-record rule — see registerSchema.
@@ -1724,27 +1727,85 @@ export async function doctorTool(args: { fix?: boolean; maxFileBytes?: number })
   }
 
   // 6. Stale agents (registered, no live transport, heartbeat past EVICT_MS). Report only.
+  //
+  // Task 5.3/22.1: "27 stale" collapsed two different populations that look
+  // identical in a flat heartbeat-age list — 14 agents whose PANE was still
+  // genuinely current (their marker's pid had died, e.g. a `/mcp` reconnect
+  // spawned a new process in the SAME pane, but the pane itself never went
+  // anywhere) and 13 agents that were ORPHANS with no pane behind them at
+  // all, aged 19–45h. An orphan is stale by construction and can NEVER
+  // clear — reporting it beside a merely-slow-heartbeat agent manufactures a
+  // permanent false alarm in the same bucket as a real one.
+  //
+  // THE DISCRIMINATOR: a marker file that still exists on disk (even though
+  // its own pid/heartbeat check already failed `isMarkerLive`) and names a
+  // `tmuxTarget` `tmux has-session` still confirms. `has-session` checks the
+  // PANE, not the recorded pid — so it survives exactly the reconnect shape
+  // above, the same probe `wedged-local-pushers` already uses one direction
+  // over (there: a live pid whose pane died; here: a dead/expired marker
+  // whose pane did not). No marker at all, or a marker whose pane is
+  // confirmed gone, is the only shape left — and that is a genuine orphan.
   {
     // Compute liveness WITHOUT deleting dead markers — loadLiveTransports
     // prunes as a side effect, which would make this read-only check mutate
     // state (and pre-empt the orphan-marker fix in check 1).
     const live = new Set<string>();
+    const markerByAgent = new Map<string, TransportMarker>();
     for (const fname of await listTransportFiles()) {
       const marker = await readJson<TransportMarker | null>(path.join(TRANSPORT_DIR, fname), null);
-      if (marker && isMarkerLive(marker, reg, now)) live.add(marker.agentId);
+      if (!marker) continue;
+      markerByAgent.set(marker.agentId, marker);
+      if (isMarkerLive(marker, reg, now)) live.add(marker.agentId);
     }
-    const stale: string[] = [];
+    // Without a tmux binary we cannot probe a pane at all — every stale
+    // agent is reported as an orphan candidate rather than silently split,
+    // same posture `wedged-local-pushers` takes.
+    const tmuxAvailable = spawnSync("tmux", ["-V"]).status === 0;
+    const paneAlive = (target: string): boolean =>
+      tmuxAvailable && spawnSync("tmux", ["has-session", "-t", target]).status === 0;
+
+    const paneConfirmed: string[] = [];
+    const orphans: string[] = [];
     for (const [id, a] of Object.entries(reg)) {
       if (live.has(id)) continue;
-      if (now - a.lastHeartbeat > EVICT_MS) stale.push(`${id} (${Math.floor((now - a.lastHeartbeat) / 3600000)}h)`);
+      if (now - a.lastHeartbeat <= EVICT_MS) continue;
+      const age = `${Math.floor((now - a.lastHeartbeat) / 3600000)}h`;
+      const marker = markerByAgent.get(id);
+      if (marker?.transport === "tmux-push" && marker.tmuxTarget && paneAlive(marker.tmuxTarget)) {
+        paneConfirmed.push(`${id} (${age}, pane '${marker.tmuxTarget}' still current)`);
+      } else {
+        orphans.push(`${id} (${age})`);
+      }
     }
+    const stale = [...paneConfirmed, ...orphans];
     findings.push({
       check: "stale-agents",
       level: stale.length ? "warn" : "ok",
-      detail: stale.length ? `${stale.length} agent(s) past the eviction window — next list_agents will drop them` : "no stale agents",
+      detail: stale.length
+        ? `${stale.length} agent(s) past the eviction window — next list_agents will drop them ` +
+          `(${paneConfirmed.length} pane-confirmed current, ${orphans.length} genuine orphan(s) with no live pane behind them)`
+        : "no stale agents",
       fixable: false,
       items: stale.length ? stale : undefined,
     });
+    // A SEPARATE finding, not a sub-line: "stale-agents" answers "how many
+    // will list_agents drop", which is true of both buckets equally — an
+    // orphan and a pane-confirmed agent are dropped from the SAME list the
+    // same way. "orphan-agents" answers the different question this task is
+    // actually about — which of those, if any, can never clear on their
+    // own — and reports it even when it is empty, so a checker that only
+    // speaks when it fires cannot be told from one that never ran.
+    findings.push({
+      check: "orphan-agents",
+      level: orphans.length ? "warn" : "ok",
+      detail: orphans.length
+        ? `${orphans.length} stale agent(s) have no live tmux pane behind them — permanent, will not clear on their own (unregister or let eviction drop them)`
+        : tmuxAvailable
+          ? `no orphans among ${stale.length} stale agent(s)${stale.length ? " — all pane-confirmed current" : ""}`
+          : "tmux not available — could not distinguish orphans from pane-confirmed stale agents",
+      fixable: false,
+      items: orphans.length ? orphans : undefined,
+    });
   }
 
   // 6b. STALENESS HAS TWO CAUSES AND THEY LOOK IDENTICAL IN A FLAT LIST.