agent-coord-mcp 0.26.18 → 0.26.19

package/dist/server.js

@@ -0,0 +1,647 @@
+#!/usr/bin/env node
+import { randomUUID } from "node:crypto";
+import { createServer } 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 { unlinkSync, writeFileSync } from "node:fs";
+import { z } from "zod";
+import { coordAwaySchema, coordAwayTool, readAway, awayRefusal } from "./tools/away.js";
+import { rotateSchema, rotateTool, rotateReconcileSchema, rotateReconcileTool } from "./tools/rotate.js";
+import { subscribeSchema, subscribeTool, unsubscribeSchema, unsubscribeTool, listSubscriptionsSchema, listSubscriptionsTool } from "./tools/events.js";
+import { scanRecordEventsSchema, scanRecordEventsTool } from "./tools/record-events.js";
+import { capabilitiesSchema, capabilitiesTool } from "./capabilities.js";
+import { ensureDirs, getTokenMap, reloadTokenMapSync, sessionFile, listSessionFiles, readJson, } from "./store.js";
+import { liveClaimEvidence, attachAgentSchema, attachAgentTool, clearTransportSchema, clearTransportTool, deleteRoomSchema, deleteRoomTool, detachAgentSchema, detachAgentTool, doctorSchema, doctorTool, forceUnregisterSchema, forceUnregisterTool, heartbeatSchema, heartbeatTool, joinRoomSchema, joinRoomTool, joinSchema, joinTool, leaveRoomSchema, leaveRoomTool, listAgentsSchema, listAgentsTool, pingSchema, pingTool, listRoomsSchema, listRoomsTool, postStatusSchema, postStatusTool, pruneSchema, pruneTool, readMessagesSchema, readMessagesTool, retrieveMessageSchema, retrieveMessageTool, retrieveRoomHistorySchema, retrieveRoomHistoryTool, registerSchema, registerTool, renameAgentSchema, renameAgentTool, reportReceiptSchema, reportReceiptTool, reportTransportSchema, reportTransportTool, sendCommandSchema, sendCommandTool, sendMessageSchema, sendMessageTool, setRoomMotdSchema, setRoomMotdTool, setRoomTopicSchema, setRoomTopicTool, statusSchema, statusTool, unregisterSchema, unregisterTool, quitSchema, quitTool, waitForMessageSchema, waitForMessageTool, listScopesSchema, listScopesTool, importWorkSchema, importWorkTool, stallCheckSchema, stallCheckTool, setHaltSchema, setHaltTool, lastRanSchema, stallClockStatusTool, ensureWorktreeSchema, ensureWorktreeTool, refreshWorktreesSchema, refreshWorktreesTool, releaseWorktreeSchema, releaseWorktreeTool, claimSchema, claimTool, landSchema, landTool, mergeSchema, mergeTool, nextUnblockedSchema, nextUnblockedTool, listWorkSchema, listWorkTool, exportWorkSchema, exportWorkTool, isPidAlive, } from "./tools/index.js";
+function jsonResult(data) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+    };
+}
+// Build a fully-configured McpServer with every tool registered. Returns a
+// fresh instance each call — in HTTP mode we need one server per session so
+// transports don't share Protocol state.
+//
+// Identity binding (v0.7.0 + TOFU in v0.7.1):
+//   - `initialBound` (when set) pre-binds the session — from a bearer token
+//     (HTTP/tokens.json) or AGENT_COORD_BOUND_AGENT env (stdio).
+//   - Otherwise the session starts unbound. The first tool call that carries
+//     an agentId/from field captures that value as the session's binding —
+//     trust-on-first-use. Subsequent calls must match; mid-session identity
+//     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.
+//   - 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 `<project>-liaison`). A live-id claim needs
+//     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
+//     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, opts = {}) {
+    let bound = initialBound;
+    const trackSession = opts.trackSession ?? false;
+    let sessionMarker;
+    let exitHooksInstalled = false;
+    // Task 16.1: the stdio half of the leak `#174` closed for HTTP. `#169`
+    // shipped an idle-timeout version of this and was HELD after a live test
+    // proved the failure mode it risked: killing a session's process out from
+    // under a still-attached client is SILENT, NON-RECOVERABLE loss, and idle
+    // is not abandoned. This reaps on the same signal `#174` uses instead — a
+    // NEW bind for the SAME agent id — which needs no timer and no guess.
+    //
+    // Why a new bind is PROOF rather than a guess, mirroring `#174`'s
+    // `agentSessions` reasoning one process boundary over: `recordSessionBinding`
+    // only runs after `guardFirstClaim` has already authorized this claim —
+    // tofu (verified the id was NOT live), token (the holder's own credential),
+    // force (an explicit override) or same-pane (the same physical seat
+    // restarting). In every one of those four paths, whoever controls this
+    // agent id has already moved to THIS session, so any other live marker for
+    // the same id left over is provably superseded, not merely idle — the
+    // exact distinction `#169` could not make with a timer.
+    async function reapSupersededStdioSessions(agentId) {
+        for (const file of await listSessionFiles()) {
+            const s = await readJson(file, null);
+            if (!s || s.agentId !== agentId || s.pid === process.pid)
+                continue;
+            if (!isPidAlive(s.pid))
+                continue; // already gone; nothing to signal
+            console.error(`[agent-coord-mcp] reaping stdio session pid ${s.pid} for agent '${agentId}' — superseded by this session (pid ${process.pid})`);
+            try {
+                // SIGTERM, not a kill(9): the superseded process's OWN exit hook
+                // (below) unlinks its marker and exits 0 — the same graceful path
+                // an operator's `quit` or Ctrl-C would take, not a hard kill.
+                process.kill(s.pid, "SIGTERM");
+            }
+            catch (err) {
+                console.error(`[agent-coord-mcp] reap FAILED for pid ${s.pid}:`, err);
+            }
+        }
+    }
+    // Best-effort: a marker left behind by SIGKILL has a dead pid, which both
+    // the guard's evidence read and doctor's duplicate-session-binding check
+    // treat as garbage (doctor fix deletes it).
+    function recordSessionBinding(agentId, via) {
+        if (!trackSession)
+            return;
+        try {
+            const file = sessionFile(agentId, process.pid, randomUUID().slice(0, 8));
+            const marker = {
+                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"]) {
+                    process.on(sig, () => { cleanup(); process.exit(0); });
+                }
+            }
+            reapSupersededStdioSessions(agentId).catch((err) => console.error("[agent-coord-mcp] stdio supersession reap threw:", err));
+        }
+        catch { /* marker is observability, never worth failing the bind */ }
+    }
+    // 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;
+    //   - 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
+    //     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, args) {
+        const token = typeof args["token"] === "string" ? args["token"] : 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.`);
+        }
+        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. ` +
+                `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";
+            // A LEFTOVER SESSION IS NAMED AS ONE, AND force NO LONGER REMOVES IT
+            // EITHER — q-314e0187: `force:true` used to be checked BEFORE this
+            // evidence was even gathered (line order, not this message), so a
+            // provably-live incumbent was never actually protected — it just
+            // looked protected to anyone who did not pass `force`. Measured
+            // 2026-08-31: `doctor` found pid 7129 (via FORCE) and pid 9760 (via
+            // same-pane) both live and bound to `groundwork-kit-worker-3`
+            // simultaneously, and the bus log could not tell which one wrote a
+            // disputed message. `force` binding past a live session does not stop
+            // that process — it adds a second claimant to one identity, which is
+            // the condition that produced exactly that incident. So a provably
+            // live incumbent can now be superseded ONLY by its own token; `force`
+            // is refused here regardless of its value.
+            //
+            // A live TRANSPORT marker is a different fact and is not called a leak:
+            // that pid is the pusher daemon, doing its job. Only a live SESSION
+            // binding that is not this process is a leftover.
+            const leaks = ev.leakedSessions ?? [];
+            const leakLine = leaks.length
+                ? ` LEFTOVER PROCESS${leaks.length > 1 ? "ES" : ""} HOLDING THIS IDENTITY: ` +
+                    leaks.map((l) => `pid ${l.pid} (via ${l.via})`).join(", ") +
+                    `. Look at ${leaks.length > 1 ? "them" : "it"} before deciding — \`ps -p ${leaks.map((l) => l.pid).join(",")}\`.`
+                : "";
+            throw new Error(`agent '${claimed}' is live on this bus (${ev.reasons.join("; ")}) — refusing to bind this fresh session to it` +
+                (args["force"] === true ? ", even with force:true" : "") +
+                `.` +
+                leakLine +
+                ` A live incumbent can only be superseded with ITS OWN TOKEN now (mint one: scripts/coord-token.mjs add ${claimed}, then SIGHUP the bus) — ` +
+                `\`force:true\` binds a SECOND session to one identity rather than stopping the first, which is the defect this refusal exists to prevent, not a step past it. ` +
+                `If you ARE '${claimed}' restarting, re-join from its own tmux pane${leaks.length ? " once nothing else holds it" : ""}. ` +
+                `If you are diagnosing, use status/ping (read-only, they never bind) or your own id.`);
+        }
+        if (args["force"] === true)
+            return "force";
+        return "tofu";
+    }
+    // Gate every tool that takes a caller identity. `field: null` (list_agents,
+    // list_rooms, prune) bypasses the check entirely.
+    //
+    // `bindOnClaim: false` (status, ping) means the tool still enforces a
+    // mismatch against an *existing* binding, but a fresh (unbound) session
+    // never claims one just by naming an agentId — a diagnostic status/ping
+    // call must not be able to silently TOFU-bind a session to some other,
+    // already-live agent's identity.
+    function gate(field, handler, { bindOnClaim = true } = {}) {
+        return async (args) => {
+            if (field) {
+                const claimed = args[field];
+                if (typeof claimed === "string") {
+                    if (bound === undefined) {
+                        if (bindOnClaim) {
+                            // 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(`identity bound to '${bound}'; rejected attempt to act as '${claimed}'`);
+                    }
+                }
+            }
+            return jsonResult(await handler(args));
+        };
+    }
+    const server = new McpServer({
+        name: "agent-coord",
+        version: "0.25.5",
+    });
+    const addTool = (name, description, inputSchema, cb) => {
+        server.registerTool(name, { description, inputSchema: z.object(inputSchema) }, async (args) => {
+            const a = (args ?? {});
+            // DUTY-OFFICER ALLOWLIST, ENFORCED IN THE ONE PATH EVERY TOOL IS
+            // REGISTERED THROUGH. Placed here rather than in `gate` because `gate`
+            // does not know the tool's NAME, and because a guard applied per call
+            // site is a guard someone forgets at one call site — where the omission
+            // looks identical to the guarded ones from outside (kit#125).
+            const caller = bound ?? (typeof a["agentId"] === "string" ? a["agentId"] : typeof a["from"] === "string" ? a["from"] : undefined);
+            const refusal = awayRefusal(readAway(), caller, name);
+            if (refusal)
+                throw new Error(refusal);
+            return cb(a);
+        });
+    };
+    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 — `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.
+    async (args) => {
+        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}'`);
+            }
+        }
+        return jsonResult(await joinTool(args));
+    });
+    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. `proseOnly:true` claims the per-agent exemption from the typed-record rule, for a model that cannot reliably pick a record.type; it is visible and counted in list_agents, and it is granted to the SENDER but paid by every READER (an untyped message cannot be slimmed). Omit it to leave any existing exemption untouched; pass false to revoke.", registerSchema, gate("agentId", registerTool));
+    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));
+    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));
+    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, { bindOnClaim: false }));
+    addTool("heartbeat", "Refresh this agent's lastHeartbeat timestamp.", heartbeatSchema, gate("agentId", heartbeatTool));
+    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 (live transport, or a fresh heartbeat ONLY where something writes one — never a local tmux-push transport's, whose heartbeat measures time since it joined rather than activity), reachable (a DM pushed now would land), granular checks including heartbeatValid (whether heartbeatFresh next to it is real evidence for this transport), 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, { bindOnClaim: false }));
+    addTool("list_agents", "List all known agents and whether they appear online (heartbeat <5min). Also reports the prose-only exemptions from the typed-record rule — who holds one, since when, and the count over the total, so a rising exempt share is visible rather than inferred.", listAgentsSchema, gate(null, listAgentsTool));
+    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. Optional 'inReplyTo' is a parent message uuid (a reply that resolves a DAVID_DECISION); malformed id is refused, unknown id is stored with a warning. The 'from' field is enforced against the session's bound identity when binding is configured. EVERY AGENT→AGENT MESSAGE MUST CARRY 'record' with a typed 'type' (decision · verdict · done · blocker · risk · fyi · action · go · scope): a typed multi-line message is delivered as ONE attributed line plus a retrieve_message handle, while an untyped one arrives in full in every reader's context. 'fyi' is the honest catch-all — use it rather than forcing a false 'decision'/'risk'. Untyped sends WARN today and are REFUSED from 2026-09-15. Messages TO a human are exempt (David-facing traffic stays prose), as is a sender that declared proseOnly:true at join.", sendMessageSchema, gate("from", sendMessageTool));
+    addTool("send_command", "Inject a context-management slash command (/clear, /compact or /reload-skills) 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, /compact and /reload-skills; nothing else is accepted. 'from' is enforced against the session's bound identity.", sendCommandSchema, gate("from", sendCommandTool));
+    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));
+    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));
+    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));
+    addTool("post_status", "Append a status broadcast to the shared status stream.", postStatusSchema, gate("agentId", postStatusTool));
+    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. `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));
+    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));
+    addTool("list_rooms", "List all channels with their topic, MOTD (room rules), members, message count, and last activity.", listRoomsSchema, gate(null, listRoomsTool));
+    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));
+    addTool("leave_room", "Leave a channel — removes this agent from its membership. Cannot leave the default 'general' channel.", leaveRoomSchema, gate("agentId", leaveRoomTool));
+    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));
+    addTool("set_room_motd", "Set or EDIT a channel's MOTD / room rules (shown to agents on join). Pass exactly ONE of: `motd` (replace the whole thing), `motdAppend` (add a clause, newline-joined), or `motdPatch:{find,replace}` (replace one unique substring — refuses if `find` matches zero times or more than once, rather than silently no-op'ing or patching the wrong clause). Prefer append/patch: a whole-string rewrite of a large MOTD costs as much as the doctrine it corrects, which is how stale rules survive. The response does NOT echo the MOTD body back (read it with list_rooms) and reports `bytes`/`bytesBefore`, plus a warning past 4096 bytes suggesting the doctrine move to a repo file with a short pointer here. Posts a system notice to the channel.", setRoomMotdSchema, gate("agentId", setRoomMotdTool));
+    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, 
+    // Special: after a successful rename we update the session's bound id
+    // too, so the same session can keep operating under the new name without
+    // the next call being rejected as a binding mismatch.
+    async (args) => {
+        const claimed = args.agentId;
+        if (typeof claimed === "string") {
+            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);
+        if (result && typeof result === "object" && result.ok === true) {
+            const to = result.to;
+            if (typeof to === "string") {
+                bound = to;
+                recordSessionBinding(to, "rename");
+            }
+        }
+        return jsonResult(result);
+    });
+    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));
+    addTool("detach_agent", "Stop the tmux-push transport for an agent: kills the pusher process and clears the transport marker.", detachAgentSchema, gate("agentId", detachAgentTool));
+    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));
+    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));
+    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));
+    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));
+    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));
+    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 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));
+    addTool("list_work", "A re-parsing VIEW over a project's work state, not an index: it re-reads the documents (or the last import_work snapshot, reported as source:\"store\" vs \"markdown\") rather than answering from a maintained store, so treat repeated calls as costing what a fresh parse costs. Queue items come back as IDENTITY ONLY — id, priority, a bounded headline (truncated:true when cut, never silently), blockedBy — never the full body; pass id back on a second call to fetch one item's or one DONE entry's record whole. Done entries, board lane rows, and facts are returned in full. Filter queue by priority; falls back to reading the documents directly when nothing has been imported, so it works with no store at all.", listWorkSchema, gate(null, listWorkTool));
+    addTool("stall_check", "The stall predicate over the board and the bus: a 🚧 In Progress or 🔍 In Review row (both are lanes somebody is working; a review that never gets re-gated is the stall shape of a QA-gated fleet) whose agent's heartbeat is older than the window, or whose claimed branch has no commits in it. HIT returns the hits for the caller to DM; MISS returns none and sends nothing — but EVERY run, hit or miss, leaves a mark, because a check that only speaks when it fires cannot be told from a broken one. Read the mark with stall_clock_status.", stallCheckSchema, gate(null, stallCheckTool));
+    addTool("stall_clock_status", "Is the stall clock alive? Reports when stall_check last ran, how many runs, and how many were misses — so 'no alerts' is distinguishable from 'nothing ran'. Never having run is an ERROR, not a quiet fleet.", lastRanSchema, gate(null, stallClockStatusTool));
+    addTool("set_halt", "Set or clear a NAMED halt. While set, `claim` and `next_unblocked` refuse. The reason is required because a halt blocks every lane in the fleet: it must name a board cutover, a cited BLOCKER: or a documented red pipeline — 'production feels down' is not a halt.", setHaltSchema, gate(null, setHaltTool));
+    addTool("ensure_worktree", "Create or reuse an isolated git worktree for an agent, cut from origin/<base> (never a local branch of the same name, which is whatever the last person left there). Refuses to hand back the PRIMARY checkout as a slice tree — that is the path everyone already has, so it is the one two agents end up editing at once. Idempotent: an existing tree is reported as found, and if it sits on a different branch that is said rather than re-pointed.", ensureWorktreeSchema, gate(null, ensureWorktreeTool));
+    addTool("refresh_worktrees", "Fast-forward IDLE worktrees onto origin/<base>. Never --force and never a mid-slice tree: dirty or holding commits the base does not is REFUSED per tree and named, because staleness is visible in a diff and a clobbered work-in-progress is not. Reports by default; pass apply:true to move them.", refreshWorktreesSchema, gate(null, refreshWorktreesTool));
+    addTool("release_worktree", "GIVE A WORKTREE BACK — the counterpart to ensure_worktree, which created trees while nothing released them, leaving `git worktree remove`/`prune` as a hand step in five role cards. Identify the tree by `agentId` or `path`. REFUSES the primary checkout (the path everyone already has); REFUSES a DIRTY tree with no override, because uncommitted work is what a diff cannot show and git cannot give back; and REFUSES a tree whose commits cannot be shown to have landed. Landedness is decided by PATCH ID, never ancestry — under squash merge a landed branch's shas never enter the base, so ancestry calls every finished tree mid-slice forever and would refuse exactly the trees that are safe to release. A patch-id negative is INCONCLUSIVE rather than a no, so it refuses and says so; `force:true` releases anyway and is recorded in the result. Removing and pruning are ONE act here, not two lines of prose the caller remembers. Reports by default; pass apply:true to remove.", releaseWorktreeSchema, gate(null, releaseWorktreeTool));
+    addTool("next_unblocked", "The next queue item a WORKER can claim: re-reads docs/QUEUE.md via the seam, orders P1>P2>P3 with document order breaking ties, and SKIPS a blocked item rather than stalling the lane on a reorder (returning the board hunk to record the skip). Also skips — as its own reported axis, `notClaimable`, never silently — canon prose (`[SWEEP:canon]`/`[SWEEP:canon.N]`) that the aide/coordinator author directly and no worker takes as code work. Also skips — as its own axis, `awaitingDecision`, never silently — an item that DECLARES it awaits a named human (`**[AWAITS:<who>]**` leading the item line; never inferred from prose): dependency-free and unbuildable at once, so it is reported for the human and not routed to a lane. Also reports items NOTHING WAITS ON as their own axis: an item that blocks nothing announces nothing when it stalls, so its absence is silent and needs an explicit check at a stage boundary.", nextUnblockedSchema, gate(null, nextUnblockedTool));
+    addTool("claim", "Bind a queue item to an agent, ENSURE THE AGENT HAS AN ISOLATED WORKTREE, and produce the \ud83d\udea7 board row. With no itemId it takes next_unblocked. `claim` CALLS `ensure_worktree` rather than telling you to — a worktree that cannot be ensured is a REFUSAL, not a warning, because binding an item to an agent with nowhere isolated to work is the shared-checkout failure this pair exists to prevent. A REUSED tree that is not at origin/<base> is also refused, naming how far behind it is and pointing at `refresh_worktrees`: `claim` means START SOMETHING NEW, and a tree left on last week's base produces confidently-wrong work with nothing about the result looking stale. A freshly created tree is cut from origin/<base> and needs no such check. Returns `worktreeEnsured` with the tree's path and branch, and writes the board cell as the REMOTE-TRACKING ref so the same row reads identically from every checkout.", claimSchema, gate(null, claimTool));
+    addTool("land", "Record a merged PR: refuses without a cited PR number, and refuses unless the PR is on the TARGET TIP (origin/<base>) rather than a merge base — an item merged after your branch was cut is missing from the base too, so the base cannot answer 'what does the thing I am merging into have that I do not?'. Closes the queue item STATUS ONLY (priority and body bytes unchanged), proposes the DONE entry, and reports by default: pass write:true to apply.", landSchema, gate(null, landTool));
+    addTool("merge", "Merge a PR ONLY as the consequence of its check verdict: reads the status rollup and merges in the same call, so there is no ordering in which the check runs and the merge ignores it. Refuses on any failing check, on any check not yet terminal, on a CONFLICTING base, and on ZERO checks \u2014 no checks is not passing checks, an empty rollup has zero failures and evidences nothing. Every return carries the POPULATION it judged. Reports by default; pass write:true to merge.", mergeSchema, gate(null, mergeTool));
+    addTool("coord_away", "Declare that DAVID IS AWAY and the aide LEADS, or RELEASE it. (Redefined 2026-08-30; the old duty-officer meaning is RETIRED, not deprecated \u2014 one label, one meaning.) The lead DECIDES planning, priority, queue curation, roadmap, canon and releases under standing authorisation; NEVER merges, gates, or takes a code lane (enforced: `merge` and `land` are refused with their reason); and PARKS licence, funding, public-vs-private, credentials, anything altering scope or authority, and destructive machine actions \u2014 those are not the aide's to decide and an absence is not a transfer of that authority. Requires a `leadId` (an unnamed lead reports the fleet as led while leaving it unled) and a `decisionLog` path, so David returns to a diff rather than a transcript. THE PRECONDITION IS MEASURED COVERAGE, NOT A CLOCK RUN: it reads `stall_check`'s own unmeasurable list \u2014 never `stall_clock_status`'s green, which cannot express its own blindness \u2014 and REFUSES when the clock would run and see nothing, unless `acknowledgeBlindFleet:true` records that the promise is being made anyway.", coordAwaySchema, gate("agentId", coordAwayTool));
+    addTool("rotate", "Build a handover-to-self packet from LIVE state (git + gh), never chat memory \u2014 memory is the one source that cannot be re-derived after the reset it is meant to survive. REFUSES while the tree is dirty: uncommitted work is the one thing a packet cannot carry, and after /clear nothing can discover it existed. Jobs are an allowlist (reseed-only | phase-boundary); 'archive-done' is deliberately absent. Reports by default; write:true persists the packet.", rotateSchema, gate("agentId", rotateTool));
+    addTool("rotate_reconcile", "FIRST ACT AFTER A RESEED. Re-checks every packet claim against live state and REFUSES to report ready on any divergence \u2014 a PR that merged during the reset is the dangerous direction, because the agent resumes a branch already in main and every next step is coherent and wrong. 'missionHint' is reported as UNVERIFIABLE rather than counted as reconciled.", rotateReconcileSchema, gate("agentId", rotateReconcileTool));
+    addTool("subscribe", "Register for a record event: `task` (a phase checkbox newly ticked), `phase` (the last open box in a phase ticked), `item` (a queue item closed), or `pr` (a PR recorded in DONE.md). Events are DERIVED from the record and refused if the ref is not in it, so the stream can never claim something the authoritative markdown does not \u2014 but the TRIGGER is the record's COMMITTED CHANGE (`scan_record_events`), not any one verb, so a hand-edited DONE.md fires exactly like `land` does. Every offered kind has an emitter: the wire enum is generated from the emitter registry, so an unsatisfiable subscription cannot be registered. Re-subscribing returns the existing registration rather than a duplicate.", subscribeSchema, gate("agentId", subscribeTool));
+    addTool("capabilities", "What THIS SERVER PROCESS can actually do, answered by CALLING each capability rather than by reading a version, an mtime, or a file. No timestamp on the box can answer a capability question: an mtime tracks writes (a reinstall of identical bytes moves it), `serverBuildMtime` is stamped at attach, and a version is a label someone typed — a published tarball has been observed carrying a change its version said it could not. Each probe reports the call it made and what came back, so an absent capability reads as an absence rather than an error. THE ANSWER IS ABOUT ONE PROCESS: a release is delivered only when every live agent's OWN server answers, which is the fifth state (merged \u00b7 published \u00b7 installed \u00b7 restarted \u00b7 observed). A server that has not restarted answers honestly about the old code it still runs.", capabilitiesSchema, gate(null, capabilitiesTool));
+    addTool("scan_record_events", "Turn a repo's COMMITTED record changes into events: new `docs/DONE.md` entries, queue items that left `docs/QUEUE.md`, and newly-ticked phase checkboxes, between the stored watermark and HEAD. The commit is the boundary \u2014 an uncommitted edit is not yet a record. A HAND-EDIT fires exactly like `land` does, which is the point: fleets merge with `gh` and edit DONE.md directly. Reports by default; `write:true` delivers and advances the watermark. Re-scanning a delivered range is safe (the idempotency key comes from the event, so it reports duplicate-suppressed), and a watermark that no longer resolves REFUSES rather than silently narrowing its window.", scanRecordEventsSchema, gate(null, scanRecordEventsTool));
+    addTool("unsubscribe", "Remove one of YOUR subscriptions. Refuses another agent's: silently dropping someone else's notification is how a miss is manufactured.", unsubscribeSchema, gate("agentId", unsubscribeTool));
+    addTool("list_subscriptions", "List subscriptions with their health. A subscription NEVER EVALUATED is an ERROR, not a quiet zero \u2014 'no events yet' and 'never ran' are the same output and only one is healthy. Carries its population, because 'no subscriptions' and 'none listed for you' are different claims.", listSubscriptionsSchema, gate(null, listSubscriptionsTool));
+    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. 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));
+    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));
+    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));
+    // 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;
+}
+// Token map for HTTP identity binding, held in-process via store.ts's
+// shared cache. Hot-reloaded on SIGHUP so operators can rotate / add agents
+// without a server restart; also refreshed automatically by rename_agent
+// (see rotateAgentToken) so a live rename doesn't need one.
+function loadTokenMap(initial) {
+    try {
+        reloadTokenMapSync();
+    }
+    catch (e) {
+        // On initial load a bad file is fatal — refuse to start in a known-bad
+        // auth state. On SIGHUP, log and keep the previous (valid) map.
+        if (initial) {
+            console.error(e.message);
+            process.exit(1);
+        }
+        console.error(`[agent-coord-mcp] SIGHUP: ${e.message} (keeping previous map)`);
+        return;
+    }
+    if (!initial) {
+        console.error(`[agent-coord-mcp] SIGHUP: token map reloaded (${getTokenMap()?.size ?? 0} agents)`);
+    }
+}
+async function main() {
+    ensureDirs();
+    loadTokenMap(true);
+    process.on("SIGHUP", () => loadTokenMap(false));
+    // Transport selector. AGENT_COORD_HTTP_PORT set → run as a long-lived HTTP
+    // daemon (Streamable HTTP transport + bearer-token auth). Otherwise the
+    // historical stdio behavior (per-client subprocess spawned by Claude Code).
+    const httpPort = process.env.AGENT_COORD_HTTP_PORT;
+    if (httpPort) {
+        await startHttp(parseInt(httpPort, 10));
+    }
+    else {
+        const boundAgent = process.env.AGENT_COORD_BOUND_AGENT;
+        if (!boundAgent) {
+            console.error("[agent-coord-mcp] WARNING: AGENT_COORD_BOUND_AGENT is not set.\n" +
+                "  The session identity will be locked to whatever agentId is used in the first\n" +
+                "  tool call (TOFU). This cannot be changed mid-session.\n" +
+                "  To fix: add AGENT_COORD_BOUND_AGENT=<your-agent-id> to the MCP server env\n" +
+                "  in your Claude Code MCP config, then restart. Use the `quit` tool to cleanly\n" +
+                "  unregister before restarting so the new name starts fresh.");
+        }
+        const server = buildServer(boundAgent, { trackSession: true });
+        const transport = new StdioServerTransport();
+        // StdioServerTransport only wires `data`/`error` on stdin — it never
+        // observes EOF. A client that ends the pipe (Claude Code's `/mcp`
+        // reconnect calls `stdin.end()` on the child) leaves this process with
+        // nothing listening for it, so it idles forever: measured as 25 live
+        // servers against 15 registered agents, one pane holding 3 generations.
+        // React to the session ending from EITHER direction — the read side
+        // closing (client done talking to us) or the write side breaking
+        // (client stopped listening, so a reply would EPIPE) — rather than
+        // waiting on the SDK client's own SIGTERM escalation to reach us.
+        const exitOnSessionEnd = (reason) => {
+            console.error(`[agent-coord-mcp] stdio session ended (${reason}) — exiting`);
+            process.exit(0);
+        };
+        process.stdin.on("end", () => exitOnSessionEnd("stdin end"));
+        process.stdin.on("close", () => exitOnSessionEnd("stdin close"));
+        process.stdout.on("error", (err) => {
+            if (err.code === "EPIPE")
+                exitOnSessionEnd("stdout EPIPE");
+        });
+        await server.connect(transport);
+    }
+}
+async function startHttp(port) {
+    const sharedToken = process.env.AGENT_COORD_TOKEN;
+    const bound = getTokenMap() !== null;
+    if (!bound && !sharedToken) {
+        console.error("[agent-coord-mcp] HTTP mode needs auth: either set AGENT_COORD_TOKEN (legacy " +
+            "shared bearer, advisory identity) or create ~/agent-coord/tokens.json (per-agent " +
+            "tokens, enforced identity). Refusing to start an unauthenticated network listener.");
+        process.exit(1);
+    }
+    if (bound && sharedToken) {
+        console.error("[agent-coord-mcp] note: tokens.json is present — AGENT_COORD_TOKEN is ignored " +
+            "(per-agent tokens take precedence).");
+    }
+    if (!bound) {
+        console.error("[agent-coord-mcp] bus identity unbound (HTTP) — shared bearer auths the channel; " +
+            "per-session identity falls back to TOFU (the first agentId/from claim becomes " +
+            "the session's bound id, can't switch mid-stream). Create ~/agent-coord/tokens.json " +
+            "to pre-bind sessions to identities at connect time.");
+    }
+    const bindAddr = process.env.AGENT_COORD_BIND ?? "127.0.0.1";
+    const sharedExpected = sharedToken ? `Bearer ${sharedToken}` : null;
+    // Fail-closed network gate. A non-loopback bind is a real network listener, so
+    // it must have (a) enforced per-agent identity and (b) a secured transport. We
+    // refuse rather than warn: a shared/advisory token lets any node impersonate
+    // any agent, and plaintext leaks bearer tokens to anyone on the path.
+    const isLoopbackBind = bindAddr === "127.0.0.1" || bindAddr === "localhost" || bindAddr === "::1";
+    if (!isLoopbackBind) {
+        if (!bound) {
+            console.error(`[agent-coord-mcp] refusing to bind ${bindAddr} without per-agent tokens: a ` +
+                `shared/advisory token lets any node impersonate any agent. Create ` +
+                `~/agent-coord/tokens.json (per-agent, enforced identity) for network binds.`);
+            process.exit(1);
+        }
+        if (process.env.AGENT_COORD_INSECURE !== "1") {
+            console.error(`[agent-coord-mcp] refusing plaintext bind to ${bindAddr}: bearer tokens would ` +
+                `travel in cleartext. Put the bus behind TLS or a private overlay ` +
+                `(Tailscale/WireGuard), then set AGENT_COORD_INSECURE=1 to acknowledge the ` +
+                `transport is secured out-of-band.`);
+            process.exit(1);
+        }
+    }
+    // One transport+server pair per client session. The SDK exposes session
+    // affinity via the `mcp-session-id` header: a new request without it is
+    // an init (create new pair); follow-ups carry the id (look up the pair).
+    // We cannot share one stateful transport across clients (it errors with
+    // "Server already initialized"), and stateless mode rejects reuse.
+    const sessions = new Map();
+    // Which bound agent each session id belongs to, so a session can't be driven
+    // by a *different* bearer that merely presents its id (session hijack).
+    const sessionAgents = new Map();
+    // Session-orphan reap (docs/DECISIONS.md ADR-015 gate #2, QUEUE.md:175 part
+    // 2). Design history, kept because the rejected shape is as load-bearing as
+    // the shipped one:
+    //
+    // `transport.onclose` — the SDK's only cleanup hook — fires exclusively from
+    // an explicit DELETE (webStandardStreamableHttp.js, "Handles DELETE requests
+    // to terminate sessions"). Measured: `Client.close()` never sends one —
+    // `StreamableHTTPClientTransport.close()` only aborts locally, and the
+    // separate `terminateSession()` method that DOES send DELETE is never
+    // called anywhere in the generic client path (shared/protocol.js). So a
+    // client that reconnects the ordinary way (close + new client, the same
+    // shape as the stdio leak fixed one level up) orphans its session here
+    // forever — confirmed live: a session answered 200 after `client.close()`.
+    //
+    // FIRST DESIGN WAS IDLE-TIMEOUT, AND IT WAS WRONG — kept as the cautionary
+    // case, not deleted: the stdio sibling of this fix (#169) shipped the same
+    // shape and was HELD after a live test proved the failure mode. Killing a
+    // session's process out from under a still-attached client produces
+    // SILENT, NON-RECOVERABLE loss — no transparent respawn, confirmed by
+    // killing this repo's own coord-mcp subprocess and watching every
+    // `mcp__agent-coord__*` tool vanish with no automatic recovery. Idle is not
+    // abandoned: an agent can sit quiet for 128 minutes while working normally.
+    // A timer cannot tell those apart; it was never going to be safe as the
+    // sole signal, on the daemon or on stdio.
+    //
+    // WHAT ACTUALLY DISTINGUISHES ABANDONED FROM QUIET: whether a NEWER session
+    // for the same bound agent already exists. If it does, the OLD session's
+    // own client already reconnected — the exact shape measured live (a fresh
+    // `client.connect()` after `client.close()`) — and closing the superseded
+    // session costs that client nothing, because it already moved on. This
+    // needs no timer and no guess: `agentSessions` tracks the current session
+    // per bound agent, and a session that stops being current is provably
+    // orphaned the instant it is superseded.
+    //
+    // Unbound (TOFU/advisory) sessions have no agent identity to key
+    // supersession on, so they get none of this — deliberately: a mechanism
+    // that cannot tell "superseded" from "just another session" must not guess.
+    const agentSessions = new Map();
+    async function reapSuperseded(agentId, supersededId) {
+        const transport = sessions.get(supersededId);
+        if (!transport)
+            return; // already gone
+        console.error(`[agent-coord-mcp] reaping session ${supersededId} for agent '${agentId}' — superseded by a newer session`);
+        try {
+            await transport.close();
+        }
+        catch (err) {
+            console.error(`[agent-coord-mcp] reap FAILED for session ${supersededId}:`, err);
+        }
+    }
+    async function makeSessionTransport(boundAgent) {
+        // `let` + explicit type lets the SDK callbacks close over the binding
+        // before it's assigned — they only fire after construction completes.
+        let transport;
+        transport = new StreamableHTTPServerTransport({
+            sessionIdGenerator: () => randomUUID(),
+            onsessioninitialized: (id) => {
+                sessions.set(id, transport);
+                sessionAgents.set(id, boundAgent);
+                if (boundAgent) {
+                    const superseded = agentSessions.get(boundAgent);
+                    agentSessions.set(boundAgent, id);
+                    if (superseded && superseded !== id) {
+                        reapSuperseded(boundAgent, superseded).catch((err) => console.error("[agent-coord-mcp] supersession reap threw:", err));
+                    }
+                }
+            },
+        });
+        transport.onclose = () => {
+            if (transport.sessionId) {
+                sessions.delete(transport.sessionId);
+                sessionAgents.delete(transport.sessionId);
+                // Only clear the agent's CURRENT pointer if it still points here — a
+                // superseded session closing after its successor already claimed the
+                // slot must not erase the successor's own entry.
+                if (boundAgent && agentSessions.get(boundAgent) === transport.sessionId) {
+                    agentSessions.delete(boundAgent);
+                }
+            }
+        };
+        const server = buildServer(boundAgent);
+        await server.connect(transport);
+        return transport;
+    }
+    // Reverse-lookup: extract bearer from header, map → bound agent. Returns
+    // undefined if no map is configured (advisory mode); throws-like return of
+    // null if the bearer doesn't match any known agent (caller responds 401).
+    function resolveBoundAgent(authHeader) {
+        if (!authHeader || !authHeader.startsWith("Bearer "))
+            return { ok: false };
+        const bearer = authHeader.slice("Bearer ".length);
+        const tokenMap = getTokenMap();
+        if (tokenMap) {
+            const agent = tokenMap.get(bearer);
+            return agent ? { ok: true, agent } : { ok: false };
+        }
+        // Advisory mode: only check the shared bearer matches.
+        return sharedExpected && authHeader === sharedExpected ? { ok: true } : { ok: false };
+    }
+    const http = createServer(async (req, res) => {
+        try {
+            // Unauthenticated liveness probe so reverse proxies / orchestrators can
+            // health-check without needing a credential.
+            const url = req.url ?? "/";
+            if (req.method === "GET" && (url === "/healthz" || url === "/health")) {
+                res.writeHead(200, { "Content-Type": "text/plain" });
+                res.end("ok\n");
+                return;
+            }
+            // Auth gate. In bound mode the bearer also tells us *which* agent the
+            // session is bound to; in advisory mode it just gates entry. Constant-
+            // time compare isn't worthwhile here — the attacker model for the
+            // LAN/personal case is "someone on the same network" who can already
+            // observe traffic; TLS termination is the answer to that.
+            const resolved = resolveBoundAgent(req.headers.authorization);
+            if (!resolved.ok) {
+                res.writeHead(401, { "Content-Type": "text/plain", "WWW-Authenticate": "Bearer" });
+                res.end("unauthorized\n");
+                return;
+            }
+            // Session routing. Existing session id → reuse its transport; new client
+            // (no id, POST init) → mint a fresh transport+server pair bound to the
+            // bearer's agent; anything else is a protocol error.
+            const sid = req.headers["mcp-session-id"];
+            let transport = typeof sid === "string" ? sessions.get(sid) : undefined;
+            // Re-bind check: a session is pinned to the agent whose bearer opened it.
+            // In bound mode, reject a request whose bearer resolves to a *different*
+            // agent than the session was created for — otherwise any valid token plus
+            // a leaked session id could drive that session's identity (session hijack).
+            if (transport &&
+                getTokenMap() &&
+                typeof sid === "string" &&
+                sessionAgents.get(sid) !== resolved.agent) {
+                res.writeHead(403, { "Content-Type": "text/plain" });
+                res.end("session/identity mismatch\n");
+                return;
+            }
+            if (!transport) {
+                if (req.method !== "POST") {
+                    res.writeHead(400, { "Content-Type": "text/plain" });
+                    res.end("missing or unknown mcp-session-id\n");
+                    return;
+                }
+                transport = await makeSessionTransport(resolved.agent);
+            }
+            await transport.handleRequest(req, res);
+        }
+        catch (err) {
+            console.error("[agent-coord-mcp] http request failed:", err);
+            if (!res.headersSent) {
+                res.writeHead(500, { "Content-Type": "text/plain" });
+                res.end("internal error\n");
+            }
+        }
+    });
+    http.listen(port, bindAddr, () => {
+        const mode = bound ? `pre-bound (${getTokenMap()?.size ?? 0} agents)` : "TOFU";
+        console.error(`[agent-coord-mcp] http listening on ${bindAddr}:${port} — identity ${mode}`);
+        if (bindAddr !== "127.0.0.1" && bindAddr !== "localhost") {
+            console.error(`[agent-coord-mcp] WARNING: bound to ${bindAddr} without TLS. Front with a TLS reverse proxy ` +
+                `(or restrict to a private network e.g. Tailscale/WireGuard) before exposing publicly.`);
+        }
+    });
+}
+main().catch((err) => {
+    console.error("[agent-coord-mcp] fatal:", err);
+    process.exit(1);
+});
+//# sourceMappingURL=server.js.map