agent-coord-mcp 0.19.0 → 0.23.0

package/src/server.ts

@@ -4,8 +4,17 @@ 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 { z, type ZodRawShape } from "zod";
 import {
+  ensureDirs,
+  getTokenMap,
+  reloadTokenMapSync,
+  sessionFile,
+  type SessionBinding,
+} from "./store.js";
+import {
+  liveClaimEvidence,
   attachAgentSchema,
   attachAgentTool,
   clearTransportSchema,
@@ -95,8 +104,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 +221,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(
@@ -132,12 +241,23 @@ function buildServer(initialBound?: string): McpServer {
 
   const server = new McpServer({
     name: "agent-coord",
-    version: "0.1.0",
+    version: "0.23.0",
   });
 
-  server.tool(
+  const addTool = (
+    name: string,
+    description: string,
+    inputSchema: ZodRawShape,
+    cb: (args: Record<string, unknown>) => Promise<ReturnType<typeof jsonResult>>,
+  ) => {
+    server.registerTool(name, { description, inputSchema: z.object(inputSchema) }, async (args) =>
+      cb((args ?? {}) as Record<string, unknown>),
+    );
+  };
+
+  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.",
+    "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 +265,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}'`,
@@ -156,147 +278,147 @@ function buildServer(initialBound?: string): McpServer {
     },
   );
 
-  server.tool(
+  addTool(
     "register",
     "Register this agent in the shared registry. Lower-level than `join` — does not attach a transport or drain the inbox. Prefer `join` unless you need explicit control.",
     registerSchema,
     gate("agentId", registerTool as (a: Record<string, unknown>) => Promise<unknown>),
   );
 
-  server.tool(
+  addTool(
     "unregister",
     "Tear down this agent: detach any attached transport (kills the pusher) and remove the registry entry. Clean shutdown counterpart to `join`.",
     unregisterSchema,
     gate("agentId", unregisterTool as (a: Record<string, unknown>) => Promise<unknown>),
   );
 
-  server.tool(
+  addTool(
     "quit",
     "Clean shutdown: unregister this agent (detach transport, leave rooms, remove registry entry) then exit the MCP process. Only callable by the session's bound identity. Use this to cleanly hand off before a restart with a new name.",
     quitSchema,
     gate("agentId", quitTool as unknown as (a: Record<string, unknown>) => Promise<unknown>),
   );
 
-  server.tool(
+  addTool(
     "status",
     "Introspect this agent's coord state: registration, attached transport, inbox depth and unread count, and whether this MCP server is running inside tmux. Useful for debugging 'why isn't my DM landing'. Read-only — naming an agentId here never binds this session's identity.",
     statusSchema,
     gate("agentId", statusTool as (a: Record<string, unknown>) => Promise<unknown>, { bindOnClaim: false }),
   );
 
-  server.tool(
+  addTool(
     "heartbeat",
     "Refresh this agent's lastHeartbeat timestamp.",
     heartbeatSchema,
     gate("agentId", heartbeatTool as (a: Record<string, unknown>) => Promise<unknown>),
   );
 
-  server.tool(
+  addTool(
     "ping",
     "Liveness probe for another agent, answered entirely from server-side state (registry entry, transport marker, pusher pid, tmux pane) — it never touches the target's session, so a fleet-wide sweep costs zero model tokens on the targets. Returns alive (fresh heartbeat or live transport), reachable (a DM pushed now would land), granular checks, and latencyMs. Distinct from heartbeat, which is an agent refreshing its OWN activity timestamp. Pass echo:true (default off) to additionally drop a PING DM into the target's inbox — that wakes the target's model, so use it sparingly and only when you need an agent-level acknowledgement. 'from' is enforced against the session's bound identity, but read-only — naming 'from' here never binds this session's identity.",
     pingSchema,
     gate("from", pingTool as (a: Record<string, unknown>) => Promise<unknown>, { bindOnClaim: false }),
   );
 
-  server.tool(
+  addTool(
     "list_agents",
     "List all known agents and whether they appear online (heartbeat <5min).",
     listAgentsSchema,
     gate(null, listAgentsTool as () => Promise<unknown>),
   );
 
-  server.tool(
+  addTool(
     "send_message",
     "Send a message. If 'to' is set, goes to that agent's inbox (DM); otherwise to a channel — pass 'room' (e.g. 'seo' or '#seo') to target a specific channel, or omit it for the default 'general' channel. For channel posts, tag 'kind': 'decision' for GOs/verdicts/agreements that must outlive routine cleanup (kept ~30 days, quoted verbatim in digests), 'status' for progress notes, omit for ordinary chatter. The 'from' field is enforced against the session's bound identity when binding is configured.",
     sendMessageSchema,
     gate("from", sendMessageTool as (a: Record<string, unknown>) => Promise<unknown>),
   );
 
-  server.tool(
+  addTool(
     "send_command",
     "Inject a context-management slash command (/clear or /compact) directly into a sub-agent's live tmux session — delivered RAW with no banner or prefix, so the agent's CLI runs it as a real slash command. Target one agent with 'to' or broadcast to a channel's tmux-attached members with 'room' (never the sender). Hard-gated to tmux: returns ok:false if the target has no live tmux-push(-remote) transport. By default BLOCKS until the receiving pusher confirms it actually typed the command into the pane (out-of-band delivery receipt, no added agent context) and returns delivery:'confirmed' with deliveredAt, or delivery:'pending'+warning if no receipt arrived within deliveryTimeoutMs (default 8000) — a stale/wedged pusher. Pass waitForDelivery:false for fire-and-forget. Intended for a lead agent to clear/compact sub-agent context and save tokens. The command allowlist is locked to /clear and /compact; nothing else is accepted. 'from' is enforced against the session's bound identity.",
     sendCommandSchema,
     gate("from", sendCommandTool as (a: Record<string, unknown>) => Promise<unknown>),
   );
 
-  server.tool(
+  addTool(
     "read_messages",
     "Read new messages from inbox|room|status. For source='room', pass 'room' to read a specific channel (default 'general'). Room and status reads return the most recent 50 entries per call — pass limit to override (max 500). When the backlog exceeds the window, the older overflow is replaced by a compact `history` digest carrying a retrieval hash; call retrieve_room_history(hash) to expand it. Inbox drains fully by default. Advances the per-channel cursor unless peek=true.",
     readMessagesSchema,
     gate("agentId", readMessagesTool as (a: Record<string, unknown>) => Promise<unknown>),
   );
 
-  server.tool(
+  addTool(
     "retrieve_room_history",
     "Expand a compressed channel-history digest returned by read_messages. Pass the `hash` from the `history` field; optionally pass `query` to return only matching messages (case-insensitive substring). Entries are scoped to the agent that produced them and expire after 30 minutes — if expired, re-read the channel with a higher limit instead.",
     retrieveRoomHistorySchema,
     gate("agentId", retrieveRoomHistoryTool as (a: Record<string, unknown>) => Promise<unknown>),
   );
 
-  server.tool(
+  addTool(
     "retrieve_message",
     "Expand a `retrieve_message id=<uuid>` handle from a pane digest into the full message and its typed `record`. A record whose text rendering spans multiple lines (a DAVID_DECISION packet) is delivered to a pane as ONE attributed line plus this handle; call it to get the structured record back. Reads the message by id from the channels you can read (your inbox and rooms you belong to), falling through to the append-only archive if compaction moved it — so unlike retrieve_room_history there is no TTL and nothing to expire. A handle for a message never delivered to you is simply not found.",
     retrieveMessageSchema,
     gate("agentId", retrieveMessageTool as (a: Record<string, unknown>) => Promise<unknown>),
   );
 
-  server.tool(
+  addTool(
     "post_status",
     "Append a status broadcast to the shared status stream.",
     postStatusSchema,
     gate("agentId", postStatusTool as (a: Record<string, unknown>) => Promise<unknown>),
   );
 
-  server.tool(
+  addTool(
     "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>),
   );
 
-  server.tool(
+  addTool(
     "wait_for_message",
     "Block (max 60s) until a new message appears on the given source, then return it. For source='room', pass 'room' to wait on a specific channel (default 'general').",
     waitForMessageSchema,
     gate("agentId", waitForMessageTool as (a: Record<string, unknown>) => Promise<unknown>),
   );
 
-  server.tool(
+  addTool(
     "list_rooms",
     "List all channels with their topic, MOTD (room rules), members, message count, and last activity.",
     listRoomsSchema,
     gate(null, listRoomsTool as () => Promise<unknown>),
   );
 
-  server.tool(
+  addTool(
     "join_room",
     "Join a channel (creating it if new). Adds this agent to the channel's membership so the notification hooks push its messages. Posts a system join notice to the channel. Returns the channel's topic, MOTD, member list, and unread message count — but not the messages themselves. Call read_messages to fetch history if needed.",
     joinRoomSchema,
     gate("agentId", joinRoomTool as (a: Record<string, unknown>) => Promise<unknown>),
   );
 
-  server.tool(
+  addTool(
     "leave_room",
     "Leave a channel — removes this agent from its membership. Cannot leave the default 'general' channel.",
     leaveRoomSchema,
     gate("agentId", leaveRoomTool as (a: Record<string, unknown>) => Promise<unknown>),
   );
 
-  server.tool(
+  addTool(
     "set_room_topic",
     "Set a channel's topic (a short one-line description). Posts a system notice to the channel.",
     setRoomTopicSchema,
     gate("agentId", setRoomTopicTool as (a: Record<string, unknown>) => Promise<unknown>),
   );
 
-  server.tool(
+  addTool(
     "set_room_motd",
     "Set a channel's MOTD / room rules (shown to agents on join). Posts a system notice to the channel.",
     setRoomMotdSchema,
     gate("agentId", setRoomMotdTool as (a: Record<string, unknown>) => Promise<unknown>),
   );
 
-  server.tool(
+  addTool(
     "rename_agent",
     "Rename an agent (NICK): migrates its registry entry, inbox, cursor, and channel memberships to the new id, then broadcasts a rename notice to its channels. When tokens.json identity binding is on, the caller's bearer token is atomically rotated to the new id so the same session keeps authenticating after rename. If a live tmux-push transport is attached it is detached first (the pusher is bound to the old id) — re-attach as the new id (join/attach_agent) to restore real-time delivery; the response sets detachedTransport + a warning when this happens.",
     renameAgentSchema,
@@ -306,104 +428,116 @@ 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);
     },
   );
 
-  server.tool(
+  addTool(
     "attach_agent",
     "Start the tmux-push transport for an agent: spawns hooks/tmux-pusher.mjs as a background process so peer DMs (and optionally room messages) get typed into the agent's tmux pane in real time. tmuxTarget defaults to the MCP server's own $TMUX_PANE if this server is running inside tmux. allowlist restricts which peer agentIds can push. Updates list_agents to show transport=tmux-push.",
     attachAgentSchema,
     gate("agentId", attachAgentTool as (a: Record<string, unknown>) => Promise<unknown>),
   );
 
-  server.tool(
+  addTool(
     "detach_agent",
     "Stop the tmux-push transport for an agent: kills the pusher process and clears the transport marker.",
     detachAgentSchema,
     gate("agentId", detachAgentTool as (a: Record<string, unknown>) => Promise<unknown>),
   );
 
-  server.tool(
+  addTool(
     "report_transport",
     "Publish a transport marker for an agent (used by the remote tmux pusher, scripts/coord-pusher.mjs, to surface itself in list_agents). Set transport='tmux-push-remote' and optionally host/tmuxTarget. Liveness for remote markers is heartbeat-based — keep calling heartbeat or this marker gets GC'd after staleness.",
     reportTransportSchema,
     gate("agentId", reportTransportTool as (a: Record<string, unknown>) => Promise<unknown>),
   );
 
-  server.tool(
+  addTool(
     "clear_transport",
     "Idempotent delete of an agent's transport marker. The wire-callable counterpart to detach_agent for remote pushers: it only removes the marker — there's no local process to kill.",
     clearTransportSchema,
     gate("agentId", clearTransportTool as (a: Record<string, unknown>) => Promise<unknown>),
   );
 
-  server.tool(
+  addTool(
     "report_receipt",
     "Append a delivery receipt for a message this agent's pusher just typed into its pane — the wire-callable counterpart to the local pusher's receipts/<id>.jsonl stamp, for remote pushers (scripts/coord-pusher.mjs) that cannot write this host's filesystem. This is what lets send_command to a tmux-push-remote agent return delivery:'confirmed'. For control commands pass exactly what submit verification observed (submitted/verified/reason); omitting 'submitted' means 'typed but unverified' and is reported as delivery:'pending', never 'confirmed'. 'agentId' (the receiving agent) is enforced against the session's bound identity, so a pusher can only stamp its own agent's receipt file.",
     reportReceiptSchema,
     gate("agentId", reportReceiptTool as (a: Record<string, unknown>) => Promise<unknown>),
   );
 
-  server.tool(
+  addTool(
     "doctor",
     "Bus-wide health check: inspects the whole state dir and reports drift, leaks, and corruption (orphan transport markers / memberships / inboxes, cursor offsets past EOF, malformed JSONL, stale agents, oversized files, stale locks, channel/registry mismatches, environment). Read-only by default; pass fix=true to apply the safe, reversible repairs (malformed-line rewrites are backed up to .bak first). A clean report (healthy=true) means the bus is internally consistent.",
     doctorSchema,
     gate(null, doctorTool as (a: Record<string, unknown>) => Promise<unknown>),
   );
 
-  server.tool(
+  addTool(
     "list_scopes",
     "Read the declared write scopes for managed documents (~/agent-coord/scopes.json). Call it with 'path' (and your 'agentId') to ask \"may I write this?\" BEFORE editing a shared doc like docs/QUEUE.md; call it bare to list every declared document and its owning role. ADVISORY ONLY: the bus does not mediate file writes, so this answers who owns a document, it does not stop anyone — enforcement arrives when work state moves into the store. Absent scopes.json means nothing is owned and nothing warns (opt-in).",
     listScopesSchema,
     gate(null, listScopesTool as (a: Record<string, unknown>) => Promise<unknown>),
   );
 
-  server.tool(
+  addTool(
     "import_work",
-    "Read a project's work documents (docs/QUEUE.md + docs/DONE.md, or the legacy docs/BACKLOG.md, plus docs/WORKSTREAMS.md) into typed records: queue items {priority,text,done}, done entries {text,ref,date} and board rows. The markdown stays authoritative — this store is a derived index, and export_work renders it back byte-identically.",
+    "Read a project's work documents (docs/QUEUE.md + docs/DONE.md, or the legacy docs/BACKLOG.md, plus docs/WORKSTREAMS.md and optional docs/FACTS.md) into typed records: queue items {priority,text,done}, done entries {text,ref,date}, board rows, and facts {id,claim,verified,by,method}. The markdown stays authoritative — this store is a derived index, and export_work renders queue/done/board back byte-identically (FACTS is not an export write target).",
     importWorkSchema,
     gate(null, importWorkTool as (a: Record<string, unknown>) => Promise<unknown>),
   );
 
-  server.tool(
+  addTool(
     "list_work",
-    "Query a project's work state as records instead of parsing markdown: open queue items (filter by priority), done entries with their ref and date as separate fields, and the board's lane rows. Falls back to reading the documents directly when nothing has been imported, so it works with no store at all.",
+    "Query a project's work state as records instead of parsing markdown: open queue items (filter by priority), done entries with their ref and date as separate fields, the board's lane rows, and facts. Falls back to reading the documents directly when nothing has been imported, so it works with no store at all.",
     listWorkSchema,
     gate(null, listWorkTool as (a: Record<string, unknown>) => Promise<unknown>),
   );
 
-  server.tool(
+  addTool(
     "export_work",
-    "Render a project's work documents back out of the store, reproducing the pinned glyph contract exactly (ref after the last ' \u2014 ', date after a trailing ' \u00b7 '). Reports by default; pass write:true to rewrite the files. Refuses to export from an empty store rather than blanking a document. Any declared Task 4 write scope is REPORTED alongside the write, never enforced.",
+    "Render a project's work documents back out of the store, reproducing the pinned glyph contract exactly (ref after the last ' \u2014 ', date after a trailing ' \u00b7 '). Reports by default; pass write:true to rewrite the files. Refuses to export from an empty store rather than blanking a document. Refuses write:true when that write would emit a new 5-col lanes-v0 table (parse-only; write grammar is workstreams.v1). Any declared Task 4 write scope is REPORTED alongside the write, never enforced.",
     exportWorkSchema,
     gate(null, exportWorkTool as (a: Record<string, unknown>) => Promise<unknown>),
   );
 
-  server.tool(
+  addTool(
     "delete_room",
     "Permanently delete a channel: removes it from the registry, deletes its JSONL file, and clears all agent cursor offsets for that channel. Refuses if agents are still joined unless force=true. Cannot delete the default 'general' channel. Posts a system notice to #general on success.",
     deleteRoomSchema,
     gate("agentId", deleteRoomTool as (a: Record<string, unknown>) => Promise<unknown>),
   );
 
-  server.tool(
+  addTool(
     "force_unregister",
     "Admin eviction: unregisters any agent by targetAgentId regardless of the caller's identity. Detaches the agent's transport, removes it from all channel memberships, and drops its registry entry. Use after a reboot to clean up stale agents that can no longer unregister themselves.",
     forceUnregisterSchema,
     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 +586,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");

package/src/tools/admin.ts

@@ -118,11 +118,22 @@ export async function pruneTool(args: {
   const cutoff = Date.now() - days * 24 * 60 * 60 * 1000;
   const decisionCutoff = Date.now() - decisionDays * 24 * 60 * 60 * 1000;
   const dryRun = args.dryRun ?? false;
-  // room-scoped prune touches only that channel's messages; targets narrows
-  // the sweep otherwise. Default remains "everything".
+  // `room` scopes every sweep to that channel; `targets` narrows which sweeps
+  // run. They compose: `room` only changes the DEFAULT target set, so an
+  // explicit `targets` always wins.
+  //
+  // WHY (regression): this previously read `scopedRoom ? ["rooms"] : args.targets`,
+  // which silently DISCARDED an explicit `targets` whenever `room` was passed.
+  // `prune {room, targets:["members"], dryRun:true}` therefore reported
+  // `orphanMembers: []` because the member sweep never ran — a caller asking
+  // "which members are phantoms in this room" got a clean bill of health that
+  // had not been computed, while `roomMessages` (the one target the override
+  // left enabled) reported real messages a live run would have archived. Field
+  // report: two members that `ping` called `unregistered` were invisible here.
+  // A sweep must never answer a question it did not evaluate.
   const scopedRoom = args.room ? normalizeRoom(args.room) : undefined;
   const targets = new Set<PruneTarget>(
-    scopedRoom ? ["rooms"] : args.targets ?? [...PRUNE_TARGETS]
+    args.targets ?? (scopedRoom ? ["rooms"] : [...PRUNE_TARGETS])
   );
   const keep = (e: { ts: number; kind?: string }) => keepEntry(e, cutoff, decisionCutoff);
 
@@ -133,6 +144,10 @@ export async function pruneTool(args: {
   const staleAgent = (m: string) => !knownAgents.has(m) || (reg[m]?.lastHeartbeat ?? 0) <= cutoff;
 
   const channels = scopedRoom ? [scopedRoom] : Object.keys(await getRooms());
+  // The membership sweeps walk the room registry rather than `channels`, so they
+  // need the scope predicate explicitly — without it, `room` scoped the message
+  // sweep while membership silently swept EVERY room.
+  const inScope = (chan: string) => !scopedRoom || chan === scopedRoom;
 
   if (dryRun) {
     let roomMessages = 0;
@@ -159,6 +174,7 @@ export async function pruneTool(args: {
     if (targets.has("members")) {
       const rooms = await getRooms();
       for (const [chan, e] of Object.entries(rooms)) {
+        if (!inScope(chan)) continue;
         const remaining: string[] = [];
         for (const m of e.members ?? []) {
           if (!knownAgents.has(m)) orphanMembers.add(m);
@@ -264,7 +280,8 @@ export async function pruneTool(args: {
   const archivedRooms: string[] = [];
   if (targets.has("members")) {
     await updateJson<RoomRegistry>(ROOMS_FILE, {}, (current) => {
-      for (const e of Object.values(current)) {
+      for (const [chan, e] of Object.entries(current)) {
+        if (!inScope(chan)) continue;
         if ((e.members?.length ?? 0) === 0) continue;
         e.members = (e.members ?? []).filter((m) => {
           if (!knownAgents.has(m)) {
@@ -284,7 +301,7 @@ export async function pruneTool(args: {
     if (args.archiveEmptyRooms ?? true) {
       const rooms = await getRooms();
       for (const [chan, e] of Object.entries(rooms)) {
-        if (chan === DEFAULT_ROOM || (e.members?.length ?? 0) > 0) continue;
+        if (chan === DEFAULT_ROOM || !inScope(chan) || (e.members?.length ?? 0) > 0) continue;
         const file = roomFile(chan);
         const msgs = await readJsonl<Message>(file);
         const lastTs = msgs[msgs.length - 1]?.ts ?? 0;