agent-coord-mcp 0.19.1 → 0.24.0

package/hooks/tmux-pusher.mjs

@@ -75,6 +75,7 @@ import { fileURLToPath } from "node:url";
 import path from "node:path";
 import { spawn, spawnSync } from "node:child_process";
 import { effectiveTier, isGateRunnerRole, TierQueue, formatBatch } from "./tier.mjs";
+import { isCi } from "./roles.mjs";
 import { mergeTransportMarker } from "./marker.mjs";
 import { pasteAndSubmit as sharedPasteAndSubmit, submitControl as sharedSubmitControl } from "./submit.mjs";
 
@@ -113,9 +114,10 @@ const MAX_QUEUE_MS = parseInt(process.env.AGENT_COORD_MAX_QUEUE_MS || "15000", 1
 // SCOPE: changes are honored only from these trusted ids. Re-resolved from
 // the registry every 30s so a role change doesn't strand a stale pusher;
 // AGENT_COORD_GATE_RUNNER=1|0 overrides in both directions.
-let tierCtx = { enabled: TIERS_ENABLED, gateRunner: false, trustedSenders: new Set() };
+let tierCtx = { enabled: TIERS_ENABLED, gateRunner: false, ci: false, trustedSenders: new Set() };
 function refreshTierCtx() {
   let gateRunner = false;
+  let ci = false;
   const trusted = new Set();
   try {
     const reg = JSON.parse(readFileSync(path.join(ROOT, "agents.json"), "utf8"));
@@ -123,18 +125,21 @@ function refreshTierCtx() {
       // Pass the whole entry: the frozen roleId lives beside `role`, and
       // reading only the display string would throw the identity away.
       if (isGateRunnerRole(entry)) trusted.add(id);
+      if (id === AGENT_ID) ci = isCi(entry);
     }
     gateRunner = trusted.has(AGENT_ID);
   } catch {
-    // No registry yet — conservative default (not a gate runner).
+    // No registry yet — conservative default (not a gate runner, not ci).
   }
   const env = process.env.AGENT_COORD_GATE_RUNNER;
   if (env === "1" || env === "true") gateRunner = true;
   if (env === "0" || env === "false") gateRunner = false;
-  if (gateRunner !== tierCtx.gateRunner) {
-    process.stderr.write(`[tmux-pusher] gate-runner resolved: ${gateRunner}\n`);
+  // AGENT_COORD_GATE_RUNNER must not flip ci — that would look like a
+  // verdict grant. Express-lane wake is roleId === ci only.
+  if (gateRunner !== tierCtx.gateRunner || ci !== tierCtx.ci) {
+    process.stderr.write(`[tmux-pusher] gate-runner resolved: ${gateRunner} ci: ${ci}\n`);
   }
-  tierCtx = { enabled: TIERS_ENABLED, gateRunner, trustedSenders: trusted };
+  tierCtx = { enabled: TIERS_ENABLED, gateRunner, ci, trustedSenders: trusted };
 }
 refreshTierCtx();
 setInterval(refreshTierCtx, 30_000).unref();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-coord-mcp",
-  "version": "0.19.1",
+  "version": "0.24.0",
   "description": "File-backed MCP server for coordinating multiple AI coding agents (Claude Code, Cursor, Cline, etc.). Local stdio or networked over Streamable HTTP.",
   "type": "module",
   "bin": {
@@ -8,15 +8,6 @@
     "coord-chat": "scripts/coord-chat.mjs",
     "coord-pusher": "scripts/coord-pusher.mjs"
   },
-  "scripts": {
-    "build": "tsc",
-    "prepare": "node scripts/check-self-dependency.mjs && tsc",
-    "start": "node dist/server.js",
-    "dev": "tsx src/server.ts",
-    "pretest": "node scripts/check-self-dependency.mjs && tsc",
-    "test": "node scripts/check-test-count.mjs",
-    "test:raw": "node --test \"test/*.test.mjs\""
-  },
   "files": [
     "dist",
     "src",
@@ -52,14 +43,23 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.4",
+    "@modelcontextprotocol/sdk": "^1.30.0",
     "proper-lockfile": "^4.1.2",
-    "zod": "^4.4.3"
+    "zod": "^4.4.3",
+    "@davidbalzan/groundwork-seam": "0.1.1"
   },
   "devDependencies": {
-    "@types/node": "^25.9.2",
+    "@types/node": "^26.2.0",
     "@types/proper-lockfile": "^4.1.4",
-    "tsx": "^4.19.2",
-    "typescript": "^6.0.3"
+    "tsx": "^4.23.12",
+    "typescript": "^7.0.2"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/server.js",
+    "dev": "tsx src/server.ts",
+    "pretest": "node scripts/check-self-dependency.mjs && tsc",
+    "test": "node scripts/check-test-count.mjs",
+    "test:raw": "node --test \"test/*.test.mjs\""
   }
-}
+}

package/scripts/check-self-dependency.mjs

@@ -17,10 +17,13 @@
 // was untouched; a reviewer reads the claim, not the diff. This guard is
 // cheap insurance against that class, not evidence of a recurring bug.
 //
-// Runs on `prepare` (every install), `pretest`, and `prepublishOnly`.
-import { readFileSync } from "node:fs";
+// Runs on `prepare` (every install) and `pretest`.
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
 
-const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+const pkgDir = fileURLToPath(new URL("..", import.meta.url));
+const pkg = JSON.parse(readFileSync(join(pkgDir, "package.json"), "utf8"));
 const DEP_FIELDS = ["dependencies", "devDependencies", "optionalDependencies", "peerDependencies"];
 
 function selfDepFields(manifest) {
@@ -29,26 +32,71 @@ function selfDepFields(manifest) {
   );
 }
 
-const offenders = selfDepFields(pkg);
+function walkFor(name, start) {
+  let dir = start;
+  for (let i = 0; i < 6; i++) {
+    const candidate = join(dir, name);
+    if (existsSync(candidate)) return { file: candidate, root: dir };
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+function npmLockSelfDep() {
+  const sibling = join(pkgDir, "package-lock.json");
+  if (!existsSync(sibling)) return false;
+  try {
+    const lock = JSON.parse(readFileSync(sibling, "utf8"));
+    const rootPkg = lock.packages?.[""];
+    return Boolean(rootPkg && selfDepFields(rootPkg).length);
+  } catch {
+    return false;
+  }
+}
 
-let lockOffender = false;
-try {
-  const lock = JSON.parse(readFileSync(new URL("../package-lock.json", import.meta.url), "utf8"));
-  const rootPkg = lock.packages?.[""];
-  if (rootPkg && selfDepFields(rootPkg).length) lockOffender = true;
-} catch {
-  /* no lockfile yet (fresh checkout pre-install) — nothing to check */
+// pnpm-lock.yaml has no JSON root package. Check this package's importer
+// block for a key named after the package (a self-dep).
+function pnpmLockSelfDep() {
+  const found = walkFor("pnpm-lock.yaml", pkgDir);
+  if (!found) return false;
+  let text;
+  try {
+    text = readFileSync(found.file, "utf8");
+  } catch {
+    return false;
+  }
+  const rel = relative(found.root, pkgDir).split("\\").join("/") || ".";
+  const key = rel === "." ? "." : rel;
+  const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const header = new RegExp(`(?<=^|\\n)  ${escaped}:\\n`);
+  const start = text.search(header);
+  if (start === -1) return false;
+  const from = text.indexOf("\n", start) + 1;
+  const next = text.slice(from).search(/\n  [^ \n]/);
+  const block = next === -1 ? text.slice(from) : text.slice(from, from + next);
+  const selfKey = new RegExp(`^[ \\t]+${pkg.name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}:\\s*$`, "m");
+  return selfKey.test(block);
 }
 
-if (offenders.length || lockOffender) {
+const offenders = selfDepFields(pkg);
+const npmLockOffender = npmLockSelfDep();
+const pnpmLockOffender = pnpmLockSelfDep();
+
+if (offenders.length || npmLockOffender || pnpmLockOffender) {
+  const lockBits = [
+    npmLockOffender && "package-lock.json's root package",
+    pnpmLockOffender && "pnpm-lock.yaml's importer for this package",
+  ].filter(Boolean);
   console.error(
     `[check-self-dependency] "${pkg.name}" depends on itself` +
       (offenders.length ? ` in package.json's ${offenders.join(", ")}` : "") +
-      (lockOffender ? `${offenders.length ? " and" : " in"} package-lock.json's root package` : "") +
+      (lockBits.length ? `${offenders.length ? " and" : " in"} ${lockBits.join(" and ")}` : "") +
       `.\nThis happened once before, added by an "npm audit fix" whose commit message said it was ` +
       `lockfile-only (de4e1ee, removed in 3bce3ce — see docs/DONE.md). If you just ran an audit or ` +
       `dependency update, check what else it changed in package.json. ` +
-      `Remove the self-reference from both files and re-run "npm install".`,
+      `Remove the self-reference from the manifest and lockfile.`,
   );
   process.exit(1);
 }

package/scripts/check-test-count.mjs

@@ -22,7 +22,7 @@
 
 import { spawn } from "node:child_process";
 
-const EXPECTED_TESTS = 262;
+const EXPECTED_TESTS = 279;
 
 const expected = Number(process.env.AGENT_COORD_EXPECTED_TESTS ?? EXPECTED_TESTS);
 // Same glob the suite always used — `--test test/` would recurse differently
@@ -41,9 +41,9 @@ child.stdout.on("data", (chunk) => {
 
 child.on("exit", (code, signal) => {
   if (signal) process.exit(1);
-  // The TAP summary lines the runner prints once, at the end.
+  // TAP (`# pass N`) on Node 20–22; spec reporter (`ℹ pass N`) on newer Node.
   const num = (label) => {
-    const m = out.match(new RegExp(`^# ${label} (\\d+)$`, "m"));
+    const m = out.match(new RegExp(`^(?:#|ℹ) ${label} (\\d+)\\s*$`, "m"));
     return m ? Number(m[1]) : null;
   };
   const tests = num("tests");

package/src/roles.ts

@@ -33,6 +33,10 @@ export function slugifyRole(role: unknown): string {
 
 export const GATE_RUNNER_ROLE_IDS = new Set(["qa", "quality", "coordinator", "gate"]);
 export const COORDINATOR_ROLE_IDS = new Set(["coordinator"]);
+// CI receives express-lane DONE: wake. Not a gate-runner — must not grant verdict.
+export const CI_ROLE_IDS = new Set(["ci"]);
+// Console / watchers. May send prefixed messages. Not a gate-runner.
+export const AUTOMATION_ROLE_IDS = new Set(["automation"]);
 
 export function resolveRole(role: RoleInput): ResolvedRole | undefined {
   if (role === null || role === undefined) return undefined;
@@ -70,6 +74,14 @@ export function isCoordinator(role: RoleInput): boolean {
   return roleMatches(role, COORDINATOR_ROLE_IDS);
 }
 
+export function isCi(role: RoleInput): boolean {
+  return roleMatches(role, CI_ROLE_IDS);
+}
+
+export function isAutomation(role: RoleInput): boolean {
+  return roleMatches(role, AUTOMATION_ROLE_IDS);
+}
+
 // Which roles may emit which record.type at the send path. Enforcement lives
 // in messaging.ts (checkRecordAuthority); the table lives here so register/join
 // can ECHO the consequence back at onboarding — a role that cannot emit `go`

package/src/server.ts

@@ -5,6 +5,7 @@ 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, type ZodRawShape } from "zod";
 import {
   ensureDirs,
   getTokenMap,
@@ -240,10 +241,21 @@ function buildServer(initialBound?: string, opts: { trackSession?: boolean } = {
 
   const server = new McpServer({
     name: "agent-coord",
-    version: "0.1.0",
+    version: "0.24.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. 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,
@@ -266,147 +278,147 @@ function buildServer(initialBound?: string, opts: { trackSession?: boolean } = {
     },
   );
 
-  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.",
+    "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.",
     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. `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,
@@ -438,84 +450,84 @@ function buildServer(initialBound?: string, opts: { trackSession?: boolean } = {
     },
   );
 
-  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,