agent-coord-mcp 0.18.0 → 0.19.1

package/hooks/submit.mjs

@@ -64,6 +64,27 @@ export const PROMPT_PATTERN = () => envStr("AGENT_COORD_PROMPT_PATTERN", "^\\s*[
 export const PLACEHOLDER_PATTERN = () =>
   envStr("AGENT_COORD_PLACEHOLDER_PATTERN", '^(Try ".*"|Press up to edit queued messages|)$');
 
+// GHOST TEXT — the ONE place the rendering assumption lives.
+//
+// Claude Code renders a session-derived SUGGESTED next prompt ("ghost text")
+// inside the input box while idle: `❯ ` + ESC[2m + suggestion + ESC[0m. It is
+// chrome, not content: nobody typed it, the first keystroke replaces it, and
+// it never reaches scrollback. To a plain `capture-pane` it is byte-for-byte
+// indistinguishable from a real draft — which made this guard refuse control
+// commands against EMPTY inputs fleet-wide (2026-07-29: three live refusals,
+// every quoted "draft" was the suggestion; /clear and /compact were
+// undeliverable to exactly the agents they were built for). The placeholder
+// regex above cannot help: the suggestion is derived from session state, so
+// its space of values is unbounded — no content pattern can enumerate it.
+// Styling is the only channel that carries the distinction, hence
+// `capture-pane -e` below.
+//
+// SGR 2 (dim/faint) is Claude Code's CURRENT rendering of the suggestion — a
+// per-harness rendering detail, not a protocol guarantee. If a harness styles
+// suggestions differently, or a release changes it, override or edit HERE and
+// nowhere else.
+export const GHOST_TEXT_SGR = () => envStr("AGENT_COORD_GHOST_TEXT_SGR", "2");
+
 function envStr(name, fallback) {
   const v = process.env[name];
   return v === undefined ? fallback : v;
@@ -80,6 +101,65 @@ function squash(s) {
   return String(s ?? "").replace(/\s+/g, " ").trim();
 }
 
+// Terminal escape sequences as they appear in `capture-pane -e` output:
+// CSI (colors/attributes, cursor) and OSC (hyperlinks, titles). Anything not
+// matched stays in the text — unrecognized bytes read as content, and content
+// fails toward refusing, never toward delivering.
+const CSI_RE = /\x1b\[[0-9;:?]*[A-Za-z]/g;
+const OSC_RE = /\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)/g;
+
+export function stripAnsi(s) {
+  return String(s ?? "").replace(OSC_RE, "").replace(CSI_RE, "");
+}
+
+// Split ONE styled line into real (typed) and ghost (suggestion) text by
+// walking its SGR state. Dim-attributed spans are ghost; everything else —
+// including any styling we do not recognize — is real. See GHOST_TEXT_SGR for
+// why dim, and for the asymmetry that makes "unrecognized = real" the safe
+// default.
+export function partitionStyledLine(styledLine) {
+  const ghostAttr = GHOST_TEXT_SGR();
+  const src = String(styledLine ?? "");
+  let real = "";
+  let ghost = "";
+  let dim = false;
+  let i = 0;
+  while (i < src.length) {
+    if (src[i] === "\x1b") {
+      const rest = src.slice(i);
+      const om = /^\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)/.exec(rest);
+      if (om) {
+        i += om[0].length;
+        continue;
+      }
+      const cm = /^\x1b\[([0-9;:?]*)([A-Za-z])/.exec(rest);
+      if (cm) {
+        if (cm[2] === "m") {
+          // SGR: parameters separated by ; or :. Empty list means reset.
+          const params = cm[1] === "" ? ["0"] : cm[1].split(/[;:]/);
+          for (const p of params) {
+            if (p === "0" || p === "") dim = false; // full reset
+            else if (p === "22") dim = false; // "normal intensity" clears dim
+            else if (p === ghostAttr) dim = true;
+            // 38;5;N color runs share the list; a bare "5"/"2" inside a color
+            // spec could false-trigger — handle the extended-color form:
+            if (p === "38" || p === "48") break; // rest of list is a color spec
+          }
+        }
+        i += cm[0].length;
+        continue;
+      }
+      // Lone ESC we do not understand: drop the ESC byte, keep going.
+      i += 1;
+      continue;
+    }
+    if (dim) ghost += src[i];
+    else real += src[i];
+    i += 1;
+  }
+  return { real, ghost };
+}
+
 // Is `payload` still sitting in the pane's INPUT LINE?
 //
 // It asks the input line specifically, and nothing else. The first version
@@ -109,32 +189,49 @@ export function stillInInput(paneText, payload) {
 
 // Read the pane's input state: is the TUI busy, and is there unsent text?
 //
-// `null` for either field means UNKNOWN — the pane could not be captured, or
+// Accepts BOTH plain and styled (`capture-pane -e`) text — on styled input the
+// ghost suggestion is partitioned out of `draft` (see GHOST_TEXT_SGR); plain
+// text has no style layer, so everything on the input line reads as content,
+// which is the conservative side. `ghost` and `styledInputLine` are null on
+// plain input.
+//
+// `null` for busy/draft means UNKNOWN — the pane could not be captured, or
 // this TUI does not look like the one we know how to read. Unknown is never
 // treated as "fine": callers either proceed and fall back to verify-by-absence
 // or report the uncertainty, but they never upgrade it to a confirmation.
 export function readPaneState(paneText) {
-  if (paneText === null || paneText === undefined) return { busy: null, draft: null };
+  if (paneText === null || paneText === undefined) {
+    return { busy: null, draft: null, ghost: null, styledInputLine: null };
+  }
   const text = String(paneText);
   const busyRe = BUSY_PATTERN();
-  const busy = busyRe ? new RegExp(busyRe).test(text) : null;
+  // Busy markers live in the status chrome; match on the de-styled text.
+  const busy = busyRe ? new RegExp(busyRe).test(stripAnsi(text)) : null;
 
   const promptRe = PROMPT_PATTERN();
   let draft = null;
+  let ghost = null;
+  let styledInputLine = null;
   if (promptRe) {
     const re = new RegExp(promptRe);
-    const lines = text.split("\n").map((l) => l.replace(/\s+$/, ""));
+    const lines = text.split("\n");
     // The LAST prompt line is the live input; earlier ones are history.
     for (let i = lines.length - 1; i >= 0; i--) {
-      const m = re.exec(lines[i]);
+      // Partition FIRST: the prompt char renders undimmed, so it stays in
+      // `real` and the prompt regex matches the de-styled real text. Ghost
+      // spans never reach the draft no matter what they contain.
+      const { real, ghost: ghostText } = partitionStyledLine(lines[i]);
+      const m = re.exec(real.replace(/\s+$/, ""));
       if (!m) continue;
       const content = (m[1] ?? "").trim();
       const placeholder = PLACEHOLDER_PATTERN();
       draft = placeholder && new RegExp(placeholder).test(content) ? "" : content;
+      ghost = squash(ghostText) || null;
+      styledInputLine = lines[i];
       break;
     }
   }
-  return { busy, draft };
+  return { busy, draft, ghost, styledInputLine };
 }
 
 // Submit a CONTROL command (/clear, /compact) — the path that must actually
@@ -146,12 +243,22 @@ export function readPaneState(paneText) {
 // delivery:"confirmed". Waiting briefly and then declining is slower and
 // louder — deliberately, because a control command that silently becomes a
 // chat message is worse than one that says it did not run.
+// The ONE place a pane is captured for guard/verify decisions. `-e` is
+// load-bearing: it keeps the style layer, the only channel that distinguishes
+// a real draft from the TUI's ghost suggestion (see GHOST_TEXT_SGR). Without
+// it every ghost reads as a draft again — and the SUITE CANNOT NOTICE,
+// because the parser tests inject styled text below this call. That is the
+// scriptMtime family of failure: the subject of a check silently disabling
+// it. A source lock in control-submit.test.mjs pins the flag here and counts
+// capture sites, so a new capture call added without `-e` trips it too.
+function captureStyled(run, target) {
+  const cap = run(["capture-pane", "-e", "-p", "-t", target]);
+  return cap.status === 0 ? String(cap.stdout ?? "") : null;
+}
+
 export async function submitControl(deps, payload) {
   const { run, target } = deps;
-  const capture = () => {
-    const cap = run(["capture-pane", "-p", "-t", target]);
-    return cap.status === 0 ? String(cap.stdout ?? "") : null;
-  };
+  const capture = () => captureStyled(run, target);
 
   const idleBudget = CONTROL_IDLE_WAIT_MS();
   const deadline = Date.now() + idleBudget;
@@ -172,6 +279,14 @@ export async function submitControl(deps, payload) {
     };
   }
   if (state.draft) {
+    // ASYMMETRY — do not "fix" this branch toward delivering. A false REFUSAL
+    // costs one control command: retryable, visible, and self-diagnosing via
+    // the styled quote below. A false DELIVERY types keystrokes into someone's
+    // real unsent text and submits the concatenation to their model — the
+    // exact harm this guard exists to prevent. A harness whose ghost text is
+    // NOT dim-styled therefore lands here and refuses; that is the intended
+    // conservative direction, and the remedy is teaching GHOST_TEXT_SGR its
+    // rendering, never loosening this check.
     return {
       submitted: false,
       verified: true,
@@ -179,7 +294,10 @@ export async function submitControl(deps, payload) {
       attempts: 0,
       reason:
         `pane '${target}' has unsent text in its input (${JSON.stringify(state.draft.slice(0, 40))}…) — not pasted. ` +
-        `The command would have been appended to that draft and sent to the model as an ordinary message.`,
+        `The command would have been appended to that draft and sent to the model as an ordinary message. ` +
+        `Rule: non-dim input-line content is a draft; dim (SGR ${GHOST_TEXT_SGR()}) spans are the TUI's ghost ` +
+        `suggestion and are ignored (AGENT_COORD_GHOST_TEXT_SGR overrides). ` +
+        `Styled input line: ${JSON.stringify(String(state.styledInputLine ?? "").slice(0, 160))}`,
     };
   }
   return pasteAndSubmit(deps, payload, { bracketed: false, verify: true });
@@ -259,9 +377,13 @@ async function pollUntilGone(deps, payload) {
   const deadline = Date.now() + VERIFY_TIMEOUT_MS();
   let readInput = false;
   for (;;) {
-    const cap = run(["capture-pane", "-p", "-t", target]);
-    if (cap.status === 0) {
-      const verdict = stillInInput(String(cap.stdout ?? ""), payload);
+    // Styled capture here too: a ghost suggestion CONTAINING the payload
+    // (e.g. the TUI suggesting "/compact" right after it ran) would otherwise
+    // read as "still in the input" — a false non-submit whose retry path
+    // sends extra Enters into a live pane on the strength of chrome.
+    const pane = captureStyled(run, target);
+    if (pane !== null) {
+      const verdict = stillInInput(pane, payload);
       if (verdict === false) return false;
       if (verdict === true) readInput = true; // we could read the input line
     }

package/hooks/tmux-pusher.mjs

@@ -461,6 +461,12 @@ function writeReceipts(msgs, outcome) {
         ts: Date.now(),
         from: m.from,
         control: m.control === true,
+        // Build identity of the pusher that did the typing/verifying — the
+        // same module-graph stamp the transport marker carries (SCRIPT_MTIME
+        // covers hooks/*.mjs, not just this file). Lets deliveryOutcome note
+        // a "confirmed" issued by pre-upgrade verification logic. Omitted
+        // when unknown: absence reads as UNKNOWN downstream, never as fresh.
+        ...(SCRIPT_MTIME !== undefined ? { scriptMtime: SCRIPT_MTIME } : {}),
         ...(outcome
           ? {
               submitted: outcome.submitted === true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-coord-mcp",
-  "version": "0.18.0",
+  "version": "0.19.1",
   "description": "File-backed MCP server for coordinating multiple AI coding agents (Claude Code, Cursor, Cline, etc.). Local stdio or networked over Streamable HTTP.",
   "type": "module",
   "bin": {

package/scripts/check-self-dependency.mjs

@@ -1,13 +1,23 @@
 #!/usr/bin/env node
-// Guards against a recurring defect (see docs/QUEUE.md P1): this package's
-// own name has twice been reintroduced into its own dependency graph —
-// once manually, once by an `npm audit fix` run (commit de4e1ee added
-// "agent-coord-mcp": "^0.8.0" back into dependencies while patching
-// fast-uri/hono/ip-address/qs). A self-dependency makes `npm install`
-// resolve against an old published copy of this package instead of the
-// local source, silently breaking dev installs. Run on every `npm install`
-// (via the "prepare" script) so a reintroduction fails loudly and
-// immediately instead of sitting unnoticed until the next audit.
+// Guards against this package's own name appearing in its own dependency
+// graph. A self-dependency makes `npm install` resolve against an old
+// published copy instead of the local source, silently breaking dev installs.
+//
+// It has happened ONCE, not repeatedly — verified 2026-07-29 by `git log -S`
+// over the whole history under both the current name and the pre-rename
+// `claude-coord-mcp`: commit de4e1ee (2026-06-06) added
+// "agent-coord-mcp": "^0.8.0" to dependencies, and 3bce3ce removed it six
+// days later. An earlier version of this comment claimed two reintroductions,
+// one of them manual; that second one is not in the history.
+//
+// What made the one occurrence dangerous is worth keeping, because it
+// generalises: de4e1ee is titled `chore: npm audit fix` and its body says
+// "Lockfile-only dependency bumps, non-breaking" — while also rewriting a
+// dependency block. It passed review BECAUSE the message said the manifest
+// was untouched; a reviewer reads the claim, not the diff. This guard is
+// cheap insurance against that class, not evidence of a recurring bug.
+//
+// Runs on `prepare` (every install), `pretest`, and `prepublishOnly`.
 import { readFileSync } from "node:fs";
 
 const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
@@ -35,7 +45,9 @@ if (offenders.length || lockOffender) {
     `[check-self-dependency] "${pkg.name}" depends on itself` +
       (offenders.length ? ` in package.json's ${offenders.join(", ")}` : "") +
       (lockOffender ? `${offenders.length ? " and" : " in"} package-lock.json's root package` : "") +
-      `.\nThis has recurred before — a prior "npm audit fix" run reintroduced it (see docs/QUEUE.md P1). ` +
+      `.\nThis happened once before, added by an "npm audit fix" whose commit message said it was ` +
+      `lockfile-only (de4e1ee, removed in 3bce3ce — see docs/DONE.md). If you just ran an audit or ` +
+      `dependency update, check what else it changed in package.json. ` +
       `Remove the self-reference from both files and re-run "npm install".`,
   );
   process.exit(1);

package/scripts/check-test-count.mjs

@@ -22,7 +22,7 @@
 
 import { spawn } from "node:child_process";
 
-const EXPECTED_TESTS = 218;
+const EXPECTED_TESTS = 262;
 
 const expected = Number(process.env.AGENT_COORD_EXPECTED_TESTS ?? EXPECTED_TESTS);
 // Same glob the suite always used — `--test test/` would recurse differently

package/scripts/coord-pusher.mjs

@@ -114,15 +114,41 @@ try {
 } catch (e) {
   die(`register failed: ${e?.message ?? e}`);
 }
-// Stamp the mtime of THIS process's loaded script so doctor() can spot a
-// stale remote pusher after a remote-side upgrade (see v0.8.2 stale-pusher
-// check — same hazard as the local tmux-pusher).
-let scriptMtime;
-try {
-  const { statSync } = await import("node:fs");
-  const { fileURLToPath } = await import("node:url");
-  scriptMtime = statSync(fileURLToPath(import.meta.url)).mtimeMs;
-} catch { /* non-fatal */ }
+// Build identity of THIS pusher process: newest mtime across the entry file
+// AND its ../hooks/*.mjs imports, sampled once at startup. The entry file
+// alone is not enough — the paste/submit pipeline lives in hooks/submit.mjs,
+// so a fix landing there alone would leave a single-file stamp unchanged and
+// a still-running pusher on the old code would read as fresh (#28's lesson,
+// carried across the wire). Over-covering hooks siblings we don't import is
+// the safe direction: a spurious stale flag is loud and cheap, a false fresh
+// silently invalidates rollout verification. Stamped on the transport marker
+// AND on every receipt this process reports; undefined on failure — an
+// absent stamp reads as UNKNOWN downstream, never as fresh, and a partial
+// (entry-only) value could read fresh while submit.mjs is exactly the stale
+// part.
+const scriptMtime = await (async () => {
+  try {
+    const { statSync, readdirSync } = await import("node:fs");
+    const { fileURLToPath } = await import("node:url");
+    const path = await import("node:path");
+    const self = fileURLToPath(import.meta.url);
+    let newest = statSync(self).mtimeMs;
+    const hooksDir = path.join(path.dirname(self), "..", "hooks");
+    for (const f of readdirSync(hooksDir)) {
+      if (!f.endsWith(".mjs")) continue;
+      let m;
+      try {
+        m = statSync(path.join(hooksDir, f)).mtimeMs;
+      } catch {
+        continue; // deleted mid-scan
+      }
+      if (m > newest) newest = m;
+    }
+    return newest;
+  } catch {
+    return undefined; // non-fatal — absence stays honest
+  }
+})();
 try {
   await call(
     "report_transport",
@@ -323,6 +349,10 @@ async function reportReceipts(msgs, outcome) {
           id: m.id,
           ...(m.from !== undefined ? { from: m.from } : {}),
           control: m.control === true,
+          // Our build identity (module-graph mtime, see the startup stamp) —
+          // ties this receipt to the code that typed/verified the delivery.
+          // Omitted when unknown; the server must not default it.
+          ...(scriptMtime !== undefined ? { scriptMtime } : {}),
           ...(outcome
             ? {
                 submitted: outcome.submitted === true,

package/src/server.ts

@@ -4,8 +4,16 @@ import { createServer, IncomingMessage, ServerResponse } from "node:http";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
-import { ensureDirs, getTokenMap, reloadTokenMapSync } from "./store.js";
+import { unlinkSync, writeFileSync } from "node:fs";
 import {
+  ensureDirs,
+  getTokenMap,
+  reloadTokenMapSync,
+  sessionFile,
+  type SessionBinding,
+} from "./store.js";
+import {
+  liveClaimEvidence,
   attachAgentSchema,
   attachAgentTool,
   clearTransportSchema,
@@ -95,8 +103,103 @@ function jsonResult(data: unknown) {
 //     switching (the PR #45 spoof shape) is rejected.
 //   - rename_agent updates the binding to the new id on success so the
 //     renamed session keeps working.
-function buildServer(initialBound?: string): McpServer {
+//   - First-claim guard (v0.20.0): TOFU no longer lets a fresh session claim
+//     an id that is currently LIVE on the bus (fresh heartbeat, live
+//     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 `disavow-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.
+//   - `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
+//     from outside the process. Not tracked for HTTP sessions: tokens.json
+//     already enforces their identity and many share one pid, which would
+//     make pid-liveness meaningless.
+function buildServer(initialBound?: string, opts: { trackSession?: boolean } = {}): McpServer {
   let bound = initialBound;
+  const trackSession = opts.trackSession ?? false;
+  let sessionMarker: string | undefined;
+  let exitHooksInstalled = false;
+
+  // 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).
+  function recordSessionBinding(agentId: string, via: string): void {
+    if (!trackSession) return;
+    try {
+      const file = sessionFile(agentId, process.pid, randomUUID().slice(0, 8));
+      const marker: SessionBinding = {
+        agentId,
+        pid: process.pid,
+        boundAt: Date.now(),
+        via,
+        ...(process.env.TMUX_PANE ? { tmuxPane: process.env.TMUX_PANE } : {}),
+      };
+      writeFileSync(file, JSON.stringify(marker, null, 2) + "\n");
+      if (sessionMarker) {
+        try { unlinkSync(sessionMarker); } catch { /* already gone */ }
+      }
+      sessionMarker = file;
+      if (!exitHooksInstalled) {
+        exitHooksInstalled = true;
+        const cleanup = () => {
+          try { if (sessionMarker) unlinkSync(sessionMarker); } catch { /* already gone */ }
+        };
+        process.on("exit", cleanup);
+        // Default signal death skips 'exit' handlers; SIGHUP stays reserved
+        // for the token-map reload in loadTokenMap.
+        for (const sig of ["SIGTERM", "SIGINT"] as const) {
+          process.on(sig, () => { cleanup(); process.exit(0); });
+        }
+      }
+    } catch { /* marker is observability, never worth failing the bind */ }
+  }
+
+  // Decide whether a fresh session may claim `claimed` as its identity, and
+  // how. Returns the bind provenance ("tofu" | "token" | "force" |
+  // "same-pane") or throws. Ordering is deliberate:
+  //   - 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);
+  //   - 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
+  //     second session. The exception never applies when another live
+  //     session is already bound to the id.
+  //   - verified-not-live binds freely: refusing absent evidence would break
+  //     every first onboarding, and the guard exists to protect LIVE ids.
+  async function guardFirstClaim(claimed: string, args: Record<string, unknown>): Promise<string> {
+    const token = typeof args["token"] === "string" ? (args["token"] as string) : undefined;
+    if (token !== undefined) {
+      if (getTokenMap()?.get(token) === claimed) return "token";
+      throw new Error(
+        `token presented for '${claimed}' does not match tokens.json (or no token map is loaded). ` +
+          `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) {
+      throw new Error(
+        `cannot verify whether '${claimed}' is live: ${ev.reasons.join("; ")}. ` +
+          `Refusing to bind rather than treating unreadable evidence as absence. ` +
+          `Repair the state (doctor), or pass the agent's token or force:true (join/register).`,
+      );
+    }
+    if (ev.live) {
+      if (ev.samePane && ev.boundElsewhere === 0) return "same-pane";
+      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). ` +
+          `If you are diagnosing, use status/ping (read-only, they never bind) or your own id.`,
+      );
+    }
+    return "tofu";
+  }
 
   // Gate every tool that takes a caller identity. `field: null` (list_agents,
   // list_rooms, prune) bypasses the check entirely.
@@ -117,7 +220,12 @@ function buildServer(initialBound?: string): McpServer {
         if (typeof claimed === "string") {
           if (bound === undefined) {
             if (bindOnClaim) {
-              bound = claimed; // TOFU: first claim wins, then sticky.
+              // TOFU: first claim wins, then sticky — but only after the
+              // first-claim guard agrees the id isn't someone else's live
+              // session (see guardFirstClaim).
+              const via = await guardFirstClaim(claimed, args);
+              bound = claimed;
+              recordSessionBinding(claimed, via);
             }
           } else if (bound !== claimed) {
             throw new Error(
@@ -137,7 +245,7 @@ function buildServer(initialBound?: string): McpServer {
 
   server.tool(
     "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.",
+    "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.",
     joinSchema,
     // join explicitly sets the session binding when unset, so each agent can
     // declare its identity via join rather than relying on env vars.
@@ -145,7 +253,9 @@ function buildServer(initialBound?: string): McpServer {
       const claimed = args["agentId"];
       if (typeof claimed === "string") {
         if (bound === undefined) {
+          const via = await guardFirstClaim(claimed, args);
           bound = claimed;
+          recordSessionBinding(claimed, via);
         } else if (bound !== claimed) {
           throw new Error(
             `identity bound to '${bound}'; rejected attempt to act as '${claimed}'`,
@@ -249,7 +359,7 @@ function buildServer(initialBound?: string): McpServer {
 
   server.tool(
     "prune",
-    "Trim room/status/inbox JSONL to entries newer than `olderThanDays` (default 7); kind='decision' posts keep a longer `decisionDays` retention (default 30). Nothing is lost: aged-out entries are archived under archive/ (rooms/<chan>.jsonl, status.jsonl, inbox/<agent>.jsonl) — only receipts are truly deleted. Pass `room` to prune a single channel, or `targets` (rooms|status|inbox|receipts|members) to narrow the sweep. Sweeps room members that are unregistered or haven't heartbeated since the cutoff, and archives+removes non-default rooms left empty and inactive (disable via archiveEmptyRooms=false). Removes inbox files for agents no longer in the registry unless removeOrphanInboxes=false. Pass dryRun=true to preview.",
+    "Trim room/status/inbox JSONL to entries newer than `olderThanDays` (default 7); kind='decision' posts keep a longer `decisionDays` retention (default 30). Nothing is lost: aged-out entries are archived under archive/ (rooms/<chan>.jsonl, status.jsonl, inbox/<agent>.jsonl) — only receipts are truly deleted. `room` and `targets` compose: `room` scopes every sweep to that channel (and, alone, defaults the sweep to `rooms` only), while `targets` (rooms|status|inbox|receipts|members) selects which sweeps run and always wins over that default — so `{room, targets:['members']}` sweeps membership in that one channel. Sweeps room members that are unregistered or haven't heartbeated since the cutoff, and archives+removes non-default rooms left empty and inactive (disable via archiveEmptyRooms=false). Removes inbox files for agents no longer in the registry unless removeOrphanInboxes=false. Pass dryRun=true to preview.",
     pruneSchema,
     gate(null, pruneTool as (a: Record<string, unknown>) => Promise<unknown>),
   );
@@ -306,15 +416,23 @@ function buildServer(initialBound?: string): McpServer {
     async (args: Record<string, unknown>) => {
       const claimed = args.agentId;
       if (typeof claimed === "string") {
-        if (bound === undefined) bound = claimed;
-        else if (bound !== claimed) {
+        if (bound === undefined) {
+          // Renaming a live agent from a fresh session is still a first
+          // claim of that agent's identity — same guard as any other.
+          const via = await guardFirstClaim(claimed, args);
+          bound = claimed;
+          recordSessionBinding(claimed, via);
+        } else if (bound !== claimed) {
           throw new Error(`identity bound to '${bound}'; rejected attempt to act as '${claimed}'`);
         }
       }
       const result = await renameAgentTool(args as { agentId: string; newAgentId: string });
       if (result && typeof result === "object" && (result as { ok?: unknown }).ok === true) {
         const to = (result as { to?: unknown }).to;
-        if (typeof to === "string") bound = to;
+        if (typeof to === "string") {
+          bound = to;
+          recordSessionBinding(to, "rename");
+        }
       }
       return jsonResult(result);
     },
@@ -404,6 +522,10 @@ function buildServer(initialBound?: string): McpServer {
     gate(null, forceUnregisterTool as (a: Record<string, unknown>) => Promise<unknown>),
   );
 
+  // An env pre-bound session is just as live as a TOFU-bound one — record it
+  // so doctor's duplicate check sees it too. (No-op unless trackSession.)
+  if (initialBound) recordSessionBinding(initialBound, "env");
+
   return server;
 }
 
@@ -452,7 +574,7 @@ async function main() {
           "  unregister before restarting so the new name starts fresh.",
       );
     }
-    const server = buildServer(boundAgent);
+    const server = buildServer(boundAgent, { trackSession: true });
     const transport = new StdioServerTransport();
     await server.connect(transport);
   }

package/src/store.ts

@@ -55,6 +55,37 @@ export const ARCHIVE_ROOMS_DIR = path.join(ARCHIVE_DIR, "rooms");
 export const ARCHIVE_INBOX_DIR = path.join(ARCHIVE_DIR, "inbox");
 export const ARCHIVE_STATUS_FILE = path.join(ARCHIVE_DIR, "status.jsonl");
 
+// Live session-binding markers (v0.20.0). One small file per *bound* stdio MCP
+// session: which agentId the session claimed, which pid holds it, and how the
+// bind was established. Written at bind time, removed on clean exit; a file
+// whose pid is dead is garbage doctor can clean. This is what makes two live
+// sessions bound to the same id VISIBLE (doctor `duplicate-session-binding`)
+// — in-process closure state can't be, by definition. HTTP sessions are not
+// tracked here: with tokens.json they are already identity-enforced, and many
+// share one pid, so pid-liveness would be meaningless for them.
+export const SESSIONS_DIR = path.join(ROOT, "sessions");
+
+export type SessionBinding = {
+  agentId: string;
+  pid: number;
+  boundAt: number;
+  // How the bind was established: "tofu" (first claim, id verified not live),
+  // "env" (AGENT_COORD_BOUND_AGENT), "token", "force", "same-pane" (live
+  // marker types into this session's own tmux pane), "rename".
+  via: string;
+  tmuxPane?: string;
+};
+
+export function sessionFile(agentId: string, pid: number, nonce: string): string {
+  return path.join(SESSIONS_DIR, `${sanitize(agentId)}.${pid}.${nonce}.json`);
+}
+
+export async function listSessionFiles(): Promise<string[]> {
+  if (!existsSync(SESSIONS_DIR)) return [];
+  const names = await fs.readdir(SESSIONS_DIR);
+  return names.filter((n) => n.endsWith(".json")).map((n) => path.join(SESSIONS_DIR, n));
+}
+
 // Per-agent token map for identity-bound bus auth (v0.7.0). Shape on disk:
 //   { "alice": "tk_<random-secret>", "bob": "tk_<another-secret>" }
 // HTTP transport reverse-looks-up the bearer to bind the session to an
@@ -82,7 +113,7 @@ export function workFile(project: string): string {
 }
 
 export function ensureDirs(): void {
-  for (const d of [ROOT, INBOX_DIR, CURSOR_DIR, TRANSPORT_DIR, PID_DIR, LOG_DIR, ROOMS_DIR, RECEIPTS_DIR, HISTORY_DIR, WORK_DIR]) {
+  for (const d of [ROOT, INBOX_DIR, CURSOR_DIR, TRANSPORT_DIR, PID_DIR, LOG_DIR, ROOMS_DIR, RECEIPTS_DIR, HISTORY_DIR, WORK_DIR, SESSIONS_DIR]) {
     if (!existsSync(d)) mkdirSync(d, { recursive: true });
   }
   for (const f of [ROOM_FILE, STATUS_FILE]) {
@@ -330,6 +361,19 @@ export async function readJson<T>(file: string, fallback: T): Promise<T> {
   }
 }
 
+// Like readJson, but a file that EXISTS and cannot be parsed THROWS instead of
+// silently returning the fallback. For callers whose decision flips on
+// "verified absent" vs "cannot verify": the first-claim binding guard must
+// refuse when evidence is unreadable, because a guard that treats unreadable
+// evidence as absent is disabled by the very corruption it should be
+// reporting (the absence-is-not-exemption class, #36).
+export async function readJsonStrict<T>(file: string, fallback: T): Promise<T> {
+  if (!existsSync(file)) return fallback;
+  const raw = await fs.readFile(file, "utf8");
+  if (!raw.trim()) return fallback;
+  return JSON.parse(raw) as T;
+}
+
 export async function writeJson(file: string, data: unknown): Promise<void> {
   await withLock(file, async () => {
     await fs.writeFile(file, JSON.stringify(data, null, 2), "utf8");