agent-coord-mcp 0.14.0 → 0.16.0

package/src/{tools.ts → tools/transport.ts}

@@ -1,3 +1,6 @@
+import { loadLiveTransports, isMarkerLive, isPidAlive } from "./registry.js";
+import { registerTool } from "./registry.js";
+import { sendMessageTool, readMessagesTool } from "./messaging.js";
 import { randomUUID } from "node:crypto";
 import { existsSync, openSync, watch } from "node:fs";
 import { promises as fsp } from "node:fs";
@@ -46,278 +49,24 @@ import {
   TRANSPORT_DIR,
   updateJson,
   type RoomRegistry,
-} from "./store.js";
-
-type AgentEntry = {
-  agentId: string;
-  project?: string;
-  role?: string;
-  registeredAt: number;
-  lastHeartbeat: number;
-  capabilities?: string[];
-};
-
-type TransportMarker = {
-  agentId: string;
-  transport: string;
-  pid: number;
-  tmuxTarget?: string;
-  since: number;
-  // Remote pushers run on a different machine; the local pid is meaningless,
-  // so we tag the host and use heartbeat-based liveness instead of pidAlive.
-  host?: string;
-  // mtime of the pusher script the daemon loaded into memory at spawn time
-  // (epoch ms). When the on-disk script is upgraded but the daemon isn't
-  // restarted, doctor() compares this to the current mtime to flag a stale
-  // pusher — the class of bug that silently dropped /clear /compact in v0.8.1.
-  // Absent on markers written by older versions (treated as "unknown, skip").
-  scriptMtime?: number;
-};
-
-type AgentRegistry = Record<string, AgentEntry>;
-
-type Message = {
-  id: string;
-  ts: number;
-  from: string;
-  to?: string;
-  room?: string;
-  text: string;
-  // System notices (join/part/topic/nick) — rendered distinctly by clients.
-  system?: boolean;
-  // Control commands (`/clear`, `/compact`) addressed at the agent's CLI, not
-  // its operator. The tmux pushers inject these RAW (no banner/prefix) so the
-  // TUI runs them as real slash commands; every other consumer ignores them.
-  control?: boolean;
-  // Server-generated push-now override (e.g. the post-/clear identity
-  // reminder). Only server code can set this — send_message constructs the
-  // Message from fixed fields, so peers cannot smuggle it in.
-  urgent?: boolean;
-};
-
-type StatusEntry = {
-  id: string;
-  ts: number;
-  agentId: string;
-  status: string;
-  detail?: string;
-};
-
-type Cursor = {
-  inboxOffset?: number;
-  roomOffset?: number; // the default channel (`general` → room.jsonl)
-  statusOffset?: number;
-  // Per-channel read offsets for every non-default channel.
-  roomOffsets?: Record<string, number>;
-};
-
-type Source = "inbox" | "room" | "status";
-
-// Resolve the physical file for a (source, agent, channel) tuple.
-function sourceFile(source: Source, agentId: string, room?: string): string {
-  if (source === "inbox") return inboxFile(agentId);
-  if (source === "status") return STATUS_FILE;
-  return roomFile(room ?? DEFAULT_ROOM);
-}
-
-// Read/write the cursor offset for a (source, channel). `general` keeps using
-// the flat roomOffset key (hook compat); other channels use roomOffsets[chan].
-function getOffset(cursor: Cursor, source: Source, room?: string): number {
-  if (source === "inbox") return cursor.inboxOffset ?? 0;
-  if (source === "status") return cursor.statusOffset ?? 0;
-  const chan = normalizeRoom(room);
-  return chan === DEFAULT_ROOM ? cursor.roomOffset ?? 0 : cursor.roomOffsets?.[chan] ?? 0;
-}
-
-function setOffset(cursor: Cursor, source: Source, room: string | undefined, n: number): void {
-  if (source === "inbox") { cursor.inboxOffset = n; return; }
-  if (source === "status") { cursor.statusOffset = n; return; }
-  const chan = normalizeRoom(room);
-  if (chan === DEFAULT_ROOM) cursor.roomOffset = n;
-  else (cursor.roomOffsets ??= {})[chan] = n;
-}
-
-function sysMsg(from: string, room: string, text: string): Message {
-  return { id: randomUUID(), ts: Date.now(), from, room, text, system: true };
-}
-
-const STALE_MS = 5 * 60 * 1000;
-const EVICT_MS = 24 * 60 * 60 * 1000;
-const MAX_WAIT_MS = 60_000;
-
-// ---------- register ----------
-
-export const registerSchema = {
-  agentId: z.string().min(1),
-  project: z.string().optional(),
-  role: z.string().optional(),
-};
-
-export async function registerTool(args: { agentId: string; project?: string; role?: string }) {
-  const reg = await updateJson<AgentRegistry>(AGENTS_FILE, {}, (current) => {
-    const now = Date.now();
-    const existing = current[args.agentId];
-    current[args.agentId] = {
-      agentId: args.agentId,
-      project: args.project ?? existing?.project,
-      role: args.role ?? existing?.role,
-      registeredAt: existing?.registeredAt ?? now,
-      lastHeartbeat: now,
-      capabilities: existing?.capabilities,
-    };
-    return current;
-  });
-  return { ok: true, agent: reg[args.agentId] };
-}
-
-// ---------- unregister ----------
-
-export const unregisterSchema = { agentId: z.string().min(1) };
-
-export async function unregisterTool(args: { agentId: string }) {
-  // If a transport is attached, take it down first so the pusher doesn't keep
-  // re-publishing the marker after we drop the registry entry.
-  const detach = await detachAgentTool(args);
-
-  let existed = false;
-  await updateJson<AgentRegistry>(AGENTS_FILE, {}, (current) => {
-    if (current[args.agentId]) {
-      existed = true;
-      delete current[args.agentId];
-    }
-    return current;
-  });
-
-  // Drop the agent from every channel's membership so it doesn't linger as a
-  // ghost in list_rooms / joinedRooms() after it's gone from the registry.
-  const leftRooms: string[] = [];
-  await updateJson<RoomRegistry>(ROOMS_FILE, {}, (current) => {
-    for (const [chan, e] of Object.entries(current)) {
-      if (e.members?.includes(args.agentId)) {
-        e.members = e.members.filter((m) => m !== args.agentId);
-        leftRooms.push(chan);
-      }
-    }
-    return current;
-  });
-  return { ok: true, removed: existed, detach, leftRooms };
-}
-
-// ---------- quit ----------
-// Clean shutdown: unregister (detach transport + leave rooms + remove registry
-// entry) then exit the MCP process. Only the bound identity can call this —
-// prevents one agent from killing another agent's session.
-
-export const quitSchema = { agentId: z.string().min(1) };
-
-export async function quitTool(args: { agentId: string }): Promise<never> {
-  await unregisterTool(args);
-  // Give stdio a moment to flush the JSON response before exiting
-  setTimeout(() => process.exit(0), 150);
-  // Return a result so the MCP framework sends the response before the
-  // setTimeout fires — the caller will see this before the process dies.
-  return { ok: true, message: `'${args.agentId}' unregistered — MCP process exiting` } as never;
-}
-
-// ---------- heartbeat ----------
-
-export const heartbeatSchema = { agentId: z.string().min(1) };
-
-export async function heartbeatTool(args: { agentId: string }) {
-  let missing = false;
-  await updateJson<AgentRegistry>(AGENTS_FILE, {}, (current) => {
-    if (!current[args.agentId]) {
-      missing = true;
-      return current;
-    }
-    current[args.agentId].lastHeartbeat = Date.now();
-    return current;
-  });
-  if (missing) return { ok: false, error: `agent '${args.agentId}' not registered` };
-  return { ok: true };
-}
-
-// ---------- list_agents ----------
-
-export const listAgentsSchema = {} as const;
-
-export async function listAgentsTool() {
-  const now = Date.now();
-  const evicted: string[] = [];
-
-  // Load live transport markers first so we can refresh heartbeats for agents
-  // whose pusher (or other transport daemon) is alive — the live process IS
-  // the heartbeat, no separate ping needed.
-  const liveTransports = await loadLiveTransports();
-
-  const reg = await updateJson<AgentRegistry>(AGENTS_FILE, {}, (current) => {
-    for (const [id, entry] of Object.entries(current)) {
-      if (liveTransports.has(id)) {
-        entry.lastHeartbeat = now;
-        continue;
-      }
-      if (now - entry.lastHeartbeat > EVICT_MS) {
-        evicted.push(id);
-        delete current[id];
-      }
-    }
-    return current;
-  });
-
-  const agents = Object.values(reg).map((a) => {
-    const transport = liveTransports.get(a.agentId);
-    const merged = [...(a.capabilities ?? [])];
-    if (transport && !merged.includes(transport.transport)) merged.push(transport.transport);
-    return {
-      ...a,
-      online: transport ? true : now - a.lastHeartbeat < STALE_MS,
-      secondsSinceHeartbeat: Math.floor((now - a.lastHeartbeat) / 1000),
-      capabilities: merged.length > 0 ? merged : undefined,
-      transport: transport
-        ? { kind: transport.transport, tmuxTarget: transport.tmuxTarget, pid: transport.pid }
-        : undefined,
-    };
-  });
-  return { agents, evicted };
-}
-
-async function loadLiveTransports(): Promise<Map<string, TransportMarker>> {
-  const out = new Map<string, TransportMarker>();
-  const reg = await readJson<AgentRegistry>(AGENTS_FILE, {});
-  const now = Date.now();
-  for (const fname of await listTransportFiles()) {
-    const file = path.join(TRANSPORT_DIR, fname);
-    const marker = await readJson<TransportMarker | null>(file, null);
-    if (!marker || !isMarkerLive(marker, reg, now)) {
-      await deleteFile(file);
-      continue;
-    }
-    out.set(marker.agentId, marker);
-  }
-  return out;
-}
-
-// Liveness for a transport marker. Local markers carry a real pid we can probe;
-// remote markers (tmux-push-remote, pid 0 on a foreign host) can't be — so we
-// trust the registry heartbeat the remote pusher refreshes (within STALE_MS).
-function isMarkerLive(marker: TransportMarker, reg: AgentRegistry, now: number): boolean {
-  if (marker.transport === "tmux-push-remote") {
-    const entry = reg[marker.agentId];
-    return !!entry && now - entry.lastHeartbeat < STALE_MS;
-  }
-  return isPidAlive(marker.pid);
-}
-
-function isPidAlive(pid: number): boolean {
-  if (!pid || pid <= 0) return false;
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch (err) {
-    const code = (err as NodeJS.ErrnoException).code;
-    return code === "EPERM"; // EPERM = exists but not ours; ESRCH = gone
-  }
-}
+} from "../store.js";
+import {
+  type AgentEntry,
+  type AgentRegistry,
+  type Message,
+  type StatusEntry,
+  type Cursor,
+  type Source,
+  type TransportMarker,
+  sourceFile,
+  getOffset,
+  setOffset,
+  sysMsg,
+  moveFile,
+  STALE_MS,
+  EVICT_MS,
+  MAX_WAIT_MS,
+} from "./shared.js";
 
 // ---------- ping ----------
 
@@ -392,57 +141,6 @@ export async function pingTool(args: { from: string; to: string; echo?: boolean
   };
 }
 
-// ---------- send_message ----------
-
-export const sendMessageSchema = {
-  from: z.string().min(1),
-  to: z.string().optional(),
-  room: z.string().optional(),
-  text: z.string().min(1),
-};
-
-export async function sendMessageTool(args: {
-  from: string;
-  to?: string;
-  room?: string;
-  text: string;
-}) {
-  // DM → inbox. Otherwise resolve the channel (default `general`), make sure it
-  // exists in the registry, and tag the message with its channel.
-  if (args.to) {
-    const msg: Message = {
-      id: randomUUID(),
-      ts: Date.now(),
-      from: args.from,
-      to: args.to,
-      text: args.text,
-    };
-    const target = inboxFile(args.to);
-    await appendJsonl(target, msg);
-    // Offline delivery is intentional (the inbox is created on demand), but a
-    // typo'd recipient shouldn't vanish silently — surface a warning when the
-    // target isn't a known agent so the caller can catch the mistake.
-    const reg = await readJson<AgentRegistry>(AGENTS_FILE, {});
-    const warning = reg[args.to]
-      ? undefined
-      : `recipient '${args.to}' is not a registered agent — message stored in their inbox but no one may be listening`;
-    return { ok: true, id: msg.id, target, room: undefined, warning };
-  }
-
-  const chan = normalizeRoom(args.room);
-  if (chan !== DEFAULT_ROOM) await ensureRoom(chan, args.from);
-  const msg: Message = {
-    id: randomUUID(),
-    ts: Date.now(),
-    from: args.from,
-    room: chan,
-    text: args.text,
-  };
-  const target = roomFile(chan);
-  await appendJsonl(target, msg);
-  return { ok: true, id: msg.id, target, room: chan };
-}
-
 // ---------- send_command (context-management control commands) ----------
 
 // The only slash commands a lead may inject into a sub-agent's CLI. Locked on
@@ -704,439 +402,6 @@ export async function sendCommandTool(args: {
   };
 }
 
-// ---------- read_messages ----------
-
-export const readMessagesSchema = {
-  agentId: z.string().min(1),
-  source: z.enum(["inbox", "room", "status"]),
-  room: z.string().optional(),
-  limit: z.number().int().positive().max(500).optional(),
-  peek: z.boolean().optional(),
-  sinceTs: z.number().optional(),
-};
-
-export async function readMessagesTool(args: {
-  agentId: string;
-  source: Source;
-  room?: string;
-  limit?: number;
-  peek?: boolean;
-  sinceTs?: number;
-}) {
-  const file = sourceFile(args.source, args.agentId, args.room);
-  const all = await readJsonl<Message | StatusEntry>(file);
-
-  let entries: (Message | StatusEntry)[] = [];
-  let totalNew = 0;
-
-  // Room and status reads default to 50 entries to prevent agents flooding
-  // themselves with full history on join — the status stream grows unbounded
-  // across the fleet. Inbox drains fully since it is targeted by nature.
-  const effectiveLimit = args.limit ?? (args.source === "inbox" ? undefined : 50);
-
-  if (args.peek) {
-    const cursor = await readJson<Cursor>(cursorFile(args.agentId), {});
-    const startOffset = getOffset(cursor, args.source, args.room);
-    entries = all.slice(startOffset);
-    if (args.sinceTs !== undefined) entries = entries.filter((e) => e.ts > args.sinceTs!);
-    totalNew = entries.length;
-  } else {
-    await updateJson<Cursor>(cursorFile(args.agentId), {}, (current) => {
-      const startOffset = getOffset(current, args.source, args.room);
-      let e = all.slice(startOffset);
-      if (args.sinceTs !== undefined) e = e.filter((x) => x.ts > args.sinceTs!);
-      totalNew = e.length;
-      entries = e;
-      // Advance past EVERYTHING we account for here (recent window + any
-      // overflow we stash below). The overflow is recoverable via the history
-      // hash, so it must not requeue for the next read — that would re-flood.
-      if (e.length > 0) setOffset(current, args.source, args.room, startOffset + e.length);
-      return current;
-    });
-  }
-
-  // CCR overflow handling (room and status sources). When the backlog exceeds
-  // the window, return the RECENT slice raw and replace the older overflow with
-  // a compact digest carrying a retrieval hash. The agent expands it on demand
-  // via retrieve_room_history. Peek is side-effect-free, so it never stashes —
-  // it reports the count and tells the agent to do a real read to get a hash.
-  let recent = entries;
-  let history: { digest: string; hash?: string; older: number } | undefined;
-  if (args.source !== "inbox" && effectiveLimit && entries.length > effectiveLimit) {
-    const overflow = entries.slice(0, entries.length - effectiveLimit);
-    recent = entries.slice(entries.length - effectiveLimit);
-    const stashKey = args.source === "room" ? normalizeRoom(args.room) : "status";
-    if (args.peek) {
-      history = { digest: digestOverflow(overflow, undefined), older: overflow.length };
-    } else {
-      const hash = await stashHistory(stashKey, args.agentId, overflow);
-      history = { digest: digestOverflow(overflow, hash), hash, older: overflow.length };
-    }
-  } else if (effectiveLimit && entries.length > effectiveLimit) {
-    // Inbox keeps the legacy oldest-first chunking (no stash) — targeted
-    // messages must never be skipped over.
-    recent = entries.slice(0, effectiveLimit);
-  }
-
-  // Drop the agent's own posts on shared channels — reading your own broadcast
-  // back is never useful and confuses turn-based agents into self-replies.
-  // Cursor has already advanced past them, so they won't reappear.
-  const visible =
-    args.source === "room" || args.source === "status"
-      ? recent.filter((e) => entryAuthor(e) !== args.agentId)
-      : recent;
-
-  return {
-    ok: true,
-    messages: visible,
-    totalNew,
-    returned: visible.length,
-    room: args.source === "room" ? normalizeRoom(args.room) : undefined,
-    ...(history ? { history } : {}),
-  };
-}
-
-// Lossless summary of a stashed backlog slice: surfaces error/failure posts
-// verbatim (the lines that usually matter most in a flood) and collapses the
-// rest to counts. Mirrors headroom's content-aware digest, kept deliberately
-// simple — the full originals are one retrieve_room_history call away.
-function digestOverflow(over: (Message | StatusEntry)[], hash: string | undefined): string {
-  const authors = new Set(over.map(entryAuthor).filter(Boolean));
-  const errorRe = /\b(error|fatal|fail(ed|ure)?|panic|exception)\b/i;
-  const errors = over.filter((m) => errorRe.test(JSON.stringify(m)));
-  const first = over[0]?.ts;
-  const last = over[over.length - 1]?.ts;
-  const span =
-    first && last && last > first ? ` over ${Math.round((last - first) / 60000)}m` : "";
-  const parts = [
-    `[${over.length} earlier message${over.length === 1 ? "" : "s"} compressed`,
-    `${authors.size} agent${authors.size === 1 ? "" : "s"}${span}`,
-  ];
-  if (errors.length) parts.push(`${errors.length} error post${errors.length === 1 ? "" : "s"}`);
-  const head = parts.join(", ");
-  const tail = hash
-    ? ` hash=${hash}] — call retrieve_room_history(hash="${hash}") to expand`
-    : `] — read without peek to get an expandable hash`;
-  return head + tail;
-}
-
-// ---------- retrieve_room_history ----------
-
-export const retrieveRoomHistorySchema = {
-  agentId: z.string().min(1),
-  hash: z.string().min(1),
-  query: z.string().optional(),
-};
-
-export async function retrieveRoomHistoryTool(args: {
-  agentId: string;
-  hash: string;
-  query?: string;
-}) {
-  const res = await retrieveHistory<Message | StatusEntry>(args.hash, args.agentId, args.query);
-  if (!res.ok) {
-    const reason =
-      res.reason === "expired"
-        ? "That history entry has expired (30m TTL). Re-read the channel with a higher limit to fetch it again."
-        : res.reason === "forbidden"
-          ? "That history hash was produced for a different agent and cannot be retrieved by you."
-          : "No history entry for that hash. It may have expired or never existed.";
-    return { ok: false, reason: res.reason, message: reason };
-  }
-  return {
-    ok: true,
-    room: res.room,
-    hash: args.hash,
-    total: res.total,
-    returned: res.messages.length,
-    messages: res.messages,
-  };
-}
-
-function entryAuthor(e: Message | StatusEntry): string | undefined {
-  return "from" in e ? e.from : e.agentId;
-}
-
-// ---------- post_status ----------
-
-export const postStatusSchema = {
-  agentId: z.string().min(1),
-  status: z.string().min(1),
-  detail: z.string().optional(),
-};
-
-export async function postStatusTool(args: { agentId: string; status: string; detail?: string }) {
-  const entry: StatusEntry = {
-    id: randomUUID(),
-    ts: Date.now(),
-    agentId: args.agentId,
-    status: args.status,
-    detail: args.detail,
-  };
-  await appendJsonl(STATUS_FILE, entry);
-  return { ok: true, id: entry.id };
-}
-
-// ---------- wait_for_message ----------
-
-export const waitForMessageSchema = {
-  agentId: z.string().min(1),
-  source: z.enum(["inbox", "room", "status"]),
-  room: z.string().optional(),
-  timeoutMs: z.number().int().positive().max(MAX_WAIT_MS).optional(),
-};
-
-export async function waitForMessageTool(args: {
-  agentId: string;
-  source: Source;
-  room?: string;
-  timeoutMs?: number;
-}) {
-  const totalTimeout = Math.min(args.timeoutMs ?? 30_000, MAX_WAIT_MS);
-  const file = sourceFile(args.source, args.agentId, args.room);
-  const deadline = Date.now() + totalTimeout;
-
-  // Loop so that file growth caused only by the agent's own self-posts (which
-  // readMessagesTool now filters out for room/status) doesn't return an empty
-  // result — keep waiting until we have something to deliver or time out.
-  while (Date.now() < deadline) {
-    const startSize = await fileSize(file);
-    const remaining = deadline - Date.now();
-    if (remaining <= 0) break;
-
-    const changed = await new Promise<boolean>((resolve) => {
-      let settled = false;
-      const finish = (v: boolean) => {
-        if (settled) return;
-        settled = true;
-        clearInterval(poll);
-        try {
-          watcher?.close();
-        } catch {
-          // ignore
-        }
-        clearTimeout(t);
-        resolve(v);
-      };
-
-      const check = async () => {
-        const sz = await fileSize(file);
-        if (sz > startSize) finish(true);
-      };
-
-      let watcher: ReturnType<typeof watch> | undefined;
-      try {
-        watcher = watch(file, () => {
-          void check();
-        });
-      } catch {
-        // file may not exist; polling will handle
-      }
-      const poll = setInterval(() => void check(), 500);
-      const t = setTimeout(() => finish(false), remaining);
-    });
-
-    if (!changed) break;
-    const result = await readMessagesTool({ agentId: args.agentId, source: args.source, room: args.room });
-    if (result.returned > 0) return result;
-    // otherwise, only self-posts arrived; keep waiting on the remaining budget
-  }
-
-  return { ok: false, timedOut: true };
-}
-
-// ---------- prune ----------
-
-export const pruneSchema = {
-  olderThanDays: z.number().positive().max(365).optional(),
-  removeOrphanInboxes: z.boolean().optional(),
-  dryRun: z.boolean().optional(),
-};
-
-export async function pruneTool(args: {
-  olderThanDays?: number;
-  removeOrphanInboxes?: boolean;
-  dryRun?: boolean;
-}) {
-  const days = args.olderThanDays ?? 7;
-  const cutoff = Date.now() - days * 24 * 60 * 60 * 1000;
-  const dryRun = args.dryRun ?? false;
-
-  const reg = await readJson<AgentRegistry>(AGENTS_FILE, {});
-  const knownAgents = new Set(Object.keys(reg));
-
-  const channels = Object.keys(await getRooms());
-
-  if (dryRun) {
-    let roomMessages = 0;
-    for (const chan of channels) {
-      const msgs = await readJsonl<Message>(roomFile(chan));
-      roomMessages += msgs.filter((e) => e.ts <= cutoff).length;
-    }
-    const status = await readJsonl<StatusEntry>(STATUS_FILE);
-    const inboxFiles = await listInboxFiles();
-    let inboxRemoved = 0;
-    const orphans: string[] = [];
-    for (const fname of inboxFiles) {
-      const id = fname.replace(/\.jsonl$/, "");
-      if (!knownAgents.has(id) && (args.removeOrphanInboxes ?? true)) orphans.push(fname);
-      const entries = await readJsonl<Message>(path.join(INBOX_DIR, fname));
-      inboxRemoved += entries.filter((e) => e.ts <= cutoff).length;
-    }
-    const rooms = await getRooms();
-    const orphanMembers = new Set<string>();
-    for (const e of Object.values(rooms)) {
-      for (const m of e.members ?? []) if (!knownAgents.has(m)) orphanMembers.add(m);
-    }
-    let receiptsRemoved = 0;
-    const orphanReceipts: string[] = [];
-    for (const filePath of await listReceiptFiles()) {
-      const id = path.basename(filePath).replace(/\.jsonl$/, "");
-      const entries = await readJsonl<{ ts: number }>(filePath);
-      if (!knownAgents.has(id) && (args.removeOrphanInboxes ?? true)) orphanReceipts.push(id);
-      receiptsRemoved += entries.filter((e) => e.ts <= cutoff).length;
-    }
-    return {
-      dryRun: true,
-      cutoff,
-      olderThanDays: days,
-      wouldRemove: {
-        roomMessages,
-        statusEntries: status.filter((e) => e.ts <= cutoff).length,
-        inboxMessages: inboxRemoved,
-        orphanInboxes: orphans,
-        orphanMembers: [...orphanMembers],
-        receipts: receiptsRemoved,
-        orphanReceipts,
-      },
-    };
-  }
-
-  // Per-channel removed counts so we can shift the matching offset in each
-  // cursor (default channel → roomOffset, others → roomOffsets[chan]).
-  const roomRemovedByChan: Record<string, number> = {};
-  let roomRemovedTotal = 0;
-  for (const chan of channels) {
-    const r = await rewriteJsonl<Message>(roomFile(chan), (e) => e.ts > cutoff);
-    if (r.removed > 0) {
-      roomRemovedByChan[chan] = r.removed;
-      roomRemovedTotal += r.removed;
-    }
-  }
-  const statusResult = await rewriteJsonl<StatusEntry>(STATUS_FILE, (e) => e.ts > cutoff);
-
-  const inboxFiles = await listInboxFiles();
-  let inboxRemoved = 0;
-  const deletedOrphans: string[] = [];
-  // perAgentInboxRemoved: how many entries were stripped from each *kept* agent's
-  // inbox, so we can shift only that agent's inboxOffset cursor below.
-  const perAgentInboxRemoved: Record<string, number> = {};
-  for (const fname of inboxFiles) {
-    const id = fname.replace(/\.jsonl$/, "");
-    const filePath = path.join(INBOX_DIR, fname);
-    if (!knownAgents.has(id) && (args.removeOrphanInboxes ?? true)) {
-      const entries = await readJsonl<Message>(filePath);
-      inboxRemoved += entries.length;
-      await deleteFile(filePath);
-      deletedOrphans.push(id);
-      continue;
-    }
-    const r = await rewriteJsonl<Message>(filePath, (e) => e.ts > cutoff);
-    inboxRemoved += r.removed;
-    perAgentInboxRemoved[id] = r.removed;
-  }
-
-  // Cursor adjustment: appendJsonl is time-ordered and rewriteJsonl removes
-  // the oldest entries (ts <= cutoff). Any cursor offset shifts down by the
-  // removed count, clamped at 0. Without this, an offset past the new file
-  // length would make read_messages return [] forever.
-  const cursorsAdjusted: string[] = [];
-  for (const cname of await listCursorFiles()) {
-    const id = cname.replace(/\.json$/, "");
-    const cursorPath = path.join(CURSOR_DIR, cname);
-    let touched = false;
-    await updateJson<Cursor>(cursorPath, {}, (current) => {
-      for (const [chan, removed] of Object.entries(roomRemovedByChan)) {
-        if (chan === DEFAULT_ROOM) {
-          if (current.roomOffset !== undefined) {
-            current.roomOffset = Math.max(0, current.roomOffset - removed);
-            touched = true;
-          }
-        } else if (current.roomOffsets?.[chan] !== undefined) {
-          current.roomOffsets[chan] = Math.max(0, current.roomOffsets[chan] - removed);
-          touched = true;
-        }
-      }
-      if (current.statusOffset !== undefined && statusResult.removed > 0) {
-        current.statusOffset = Math.max(0, current.statusOffset - statusResult.removed);
-        touched = true;
-      }
-      const myInboxRemoved = perAgentInboxRemoved[id] ?? 0;
-      if (current.inboxOffset !== undefined && myInboxRemoved > 0) {
-        current.inboxOffset = Math.max(0, current.inboxOffset - myInboxRemoved);
-        touched = true;
-      }
-      return current;
-    });
-    if (touched) cursorsAdjusted.push(id);
-  }
-
-  // Compact channel memberships: drop any member no longer in the registry so
-  // list_rooms / joinedRooms() stop surfacing ghosts (mirrors orphan-inbox
-  // cleanup). Empty non-default channels are left in place — their history may
-  // still matter and `general` must always persist.
-  const orphanMembers = new Set<string>();
-  await updateJson<RoomRegistry>(ROOMS_FILE, {}, (current) => {
-    for (const e of Object.values(current)) {
-      const before = e.members?.length ?? 0;
-      if (before === 0) continue;
-      e.members = (e.members ?? []).filter((m) => {
-        const keep = knownAgents.has(m);
-        if (!keep) orphanMembers.add(m);
-        return keep;
-      });
-    }
-    return current;
-  });
-
-  // Receipts are out-of-band proof logs with no cursor — trim old entries by ts
-  // and delete logs for agents no longer registered. No offset adjustment needed.
-  let receiptsRemoved = 0;
-  const deletedOrphanReceipts: string[] = [];
-  for (const filePath of await listReceiptFiles()) {
-    const id = path.basename(filePath).replace(/\.jsonl$/, "");
-    if (!knownAgents.has(id) && (args.removeOrphanInboxes ?? true)) {
-      const entries = await readJsonl<{ ts: number }>(filePath);
-      receiptsRemoved += entries.length;
-      await deleteFile(filePath);
-      deletedOrphanReceipts.push(id);
-      continue;
-    }
-    const r = await rewriteJsonl<{ ts: number }>(filePath, (e) => e.ts > cutoff);
-    receiptsRemoved += r.removed;
-  }
-
-  // Sweep expired reversible-history entries (TTL'd cache; also self-prunes on
-  // every read, so this just catches entries on a server with few reads).
-  await pruneHistory();
-
-  return {
-    dryRun: false,
-    cutoff,
-    olderThanDays: days,
-    removed: {
-      roomMessages: roomRemovedTotal,
-      statusEntries: statusResult.removed,
-      inboxMessages: inboxRemoved,
-      orphanInboxes: deletedOrphans,
-      orphanMembers: [...orphanMembers],
-      receipts: receiptsRemoved,
-      orphanReceipts: deletedOrphanReceipts,
-    },
-    cursorsAdjusted,
-  };
-}
-
 // ---------- attach_agent / detach_agent (tmux push transport) ----------
 
 export const attachAgentSchema = {
@@ -1307,9 +572,9 @@ export async function detachAgentTool(args: { agentId: string }) {
 }
 
 function resolvePusherPath(): string {
-  // tools.js (compiled) lives in dist/; pusher lives in hooks/ at repo root.
+  // transport.js (compiled) lives in dist/tools/; pusher lives in hooks/ at repo root.
   const here = path.dirname(fileURLToPath(import.meta.url));
-  return path.resolve(here, "..", "hooks", "tmux-pusher.mjs");
+  return path.resolve(here, "..", "..", "hooks", "tmux-pusher.mjs");
 }
 
 // ---------- status / whoami ----------
@@ -1407,172 +672,6 @@ export async function joinTool(args: {
   };
 }
 
-// ---------- room / channel tools ----------
-
-export const listRoomsSchema = {} as const;
-
-export async function listRoomsTool() {
-  const reg = await getRooms();
-  const rooms = [];
-  for (const [room, e] of Object.entries(reg)) {
-    const msgs = await readJsonl<Message>(roomFile(room));
-    rooms.push({
-      room,
-      topic: e.topic,
-      motd: e.motd,
-      members: e.members ?? [],
-      memberCount: (e.members ?? []).length,
-      messageCount: msgs.length,
-      lastTs: msgs.length ? msgs[msgs.length - 1].ts : undefined,
-      createdAt: e.createdAt,
-      createdBy: e.createdBy,
-    });
-  }
-  return { rooms };
-}
-
-export const joinRoomSchema = {
-  agentId: z.string().min(1),
-  room: z.string().min(1),
-};
-
-export async function joinRoomTool(args: { agentId: string; room: string }) {
-  const chan = normalizeRoom(args.room);
-  await ensureRoom(chan, args.agentId);
-  await addMember(chan, args.agentId);
-  await appendJsonl(roomFile(chan), sysMsg(args.agentId, chan, `${args.agentId} has joined`));
-  const reg = await getRooms();
-  const e = reg[chan];
-  const all = await readJsonl<Message>(roomFile(chan));
-  const cursor = await readJson<Cursor>(cursorFile(args.agentId), {});
-  const unread = Math.max(0, all.length - getOffset(cursor, "room", chan));
-  return {
-    ok: true,
-    room: chan,
-    topic: e?.topic,
-    motd: e?.motd,
-    members: e?.members ?? [],
-    unread,
-  };
-}
-
-export const leaveRoomSchema = {
-  agentId: z.string().min(1),
-  room: z.string().min(1),
-};
-
-export async function leaveRoomTool(args: { agentId: string; room: string }) {
-  const chan = normalizeRoom(args.room);
-  if (chan === DEFAULT_ROOM) {
-    return { ok: false, error: "cannot leave the default channel" };
-  }
-  await removeMember(chan, args.agentId);
-  return { ok: true, room: chan };
-}
-
-export const setRoomTopicSchema = {
-  agentId: z.string().min(1),
-  room: z.string().min(1),
-  topic: z.string(),
-};
-
-export async function setRoomTopicTool(args: { agentId: string; room: string; topic: string }) {
-  const chan = normalizeRoom(args.room);
-  await ensureRoom(chan, args.agentId);
-  await setRoomMeta(chan, { topic: args.topic }, args.agentId);
-  await appendJsonl(roomFile(chan), sysMsg(args.agentId, chan, `changed topic to: ${args.topic}`));
-  return { ok: true, room: chan, topic: args.topic };
-}
-
-export const setRoomMotdSchema = {
-  agentId: z.string().min(1),
-  room: z.string().min(1),
-  motd: z.string(),
-};
-
-export async function setRoomMotdTool(args: { agentId: string; room: string; motd: string }) {
-  const chan = normalizeRoom(args.room);
-  await ensureRoom(chan, args.agentId);
-  await setRoomMeta(chan, { motd: args.motd }, args.agentId);
-  await appendJsonl(roomFile(chan), sysMsg(args.agentId, chan, `updated the room rules (MOTD)`));
-  return { ok: true, room: chan, motd: args.motd };
-}
-
-// ---------- rename_agent (NICK) ----------
-
-export const renameAgentSchema = {
-  agentId: z.string().min(1),
-  newAgentId: z.string().min(1),
-};
-
-export async function renameAgentTool(args: { agentId: string; newAgentId: string }) {
-  const oldId = args.agentId;
-  const newId = args.newAgentId;
-  if (oldId === newId) return { ok: false, error: "new id is identical to the current id" };
-
-  const reg = await readJson<AgentRegistry>(AGENTS_FILE, {});
-  if (!reg[oldId]) return { ok: false, error: `agent '${oldId}' not registered` };
-  if (reg[newId]) return { ok: false, error: `agent '${newId}' already exists` };
-
-  const joined = await memberRooms(oldId);
-
-  // A running pusher has the OLD agentId (and its file paths) baked into its
-  // env, so after we migrate the inbox/cursor below it would keep tailing the
-  // now-empty old inbox while new DMs land in the new one — silently breaking
-  // delivery and orphaning the moved marker. Take it down first; the caller
-  // must re-attach under the new id (join/attach_agent) to restore push.
-  const liveTransport = await readJson<TransportMarker | null>(transportFile(oldId), null);
-  let detachedTransport = false;
-  if (liveTransport && isPidAlive(liveTransport.pid)) {
-    await detachAgentTool({ agentId: oldId });
-    detachedTransport = true;
-  }
-
-  // Registry: move the entry under the new key.
-  await updateJson<AgentRegistry>(AGENTS_FILE, {}, (current) => {
-    if (current[oldId]) {
-      current[newId] = { ...current[oldId], agentId: newId };
-      delete current[oldId];
-    }
-    return current;
-  });
-
-  // Channel memberships: rename in place.
-  await updateJson<RoomRegistry>(ROOMS_FILE, {}, (current) => {
-    for (const e of Object.values(current)) {
-      if (e.members?.includes(oldId)) e.members = e.members.map((m) => (m === oldId ? newId : m));
-    }
-    return current;
-  });
-
-  // Per-agent files: inbox, cursor. (The transport marker was already removed
-  // above if a pusher was live; nothing to move otherwise.)
-  await moveFile(inboxFile(oldId), inboxFile(newId));
-  await moveFile(cursorFile(oldId), cursorFile(newId));
-  await moveFile(transportFile(oldId), transportFile(newId));
-
-  // Identity-binding token rotation: if tokens.json exists and had the old
-  // id, move its token to the new id atomically. Lets the same bearer keep
-  // authenticating after rename — no-op if binding isn't configured.
-  await rotateAgentToken(oldId, newId);
-
-  // Broadcast a NICK notice to every channel the agent was in.
-  for (const chan of joined) {
-    await appendJsonl(roomFile(chan), sysMsg(newId, chan, `is now known as ${newId} (was ${oldId})`));
-  }
-
-  return {
-    ok: true,
-    from: oldId,
-    to: newId,
-    rooms: joined,
-    detachedTransport,
-    ...(detachedTransport
-      ? { warning: `the live tmux-push transport was detached during rename — re-attach as '${newId}' (e.g. join/attach_agent) to restore real-time delivery` }
-      : {}),
-  };
-}
-
 // ---------- transport markers (for remote pushers) ----------
 
 export const reportTransportSchema = {
@@ -2035,87 +1134,3 @@ export async function doctorTool(args: { fix?: boolean; maxFileBytes?: number })
   };
 }
 
-// ---------- delete_room ----------
-
-export const deleteRoomSchema = {
-  agentId: z.string().min(1),
-  room: z.string().min(1),
-  // When true, kick remaining members instead of refusing.
-  force: z.boolean().optional(),
-};
-
-export async function deleteRoomTool(args: { agentId: string; room: string; force?: boolean }) {
-  const chan = normalizeRoom(args.room);
-  if (chan === DEFAULT_ROOM) return { ok: false, error: "cannot delete the default channel" };
-
-  const rooms = await getRooms();
-  const entry = rooms[chan];
-  if (!entry) return { ok: false, error: `room '${chan}' does not exist` };
-
-  const members = entry.members ?? [];
-  if (members.length > 0 && !args.force) {
-    return {
-      ok: false,
-      error: `room '${chan}' still has ${members.length} member(s): ${members.join(", ")}. Pass force=true to delete anyway.`,
-      members,
-    };
-  }
-
-  // Remove from rooms registry.
-  await updateJson<RoomRegistry>(ROOMS_FILE, {}, (current) => {
-    delete current[chan];
-    return current;
-  });
-
-  // Delete the backing JSONL file.
-  const file = roomFile(chan);
-  const fileDeleted = await deleteFile(file);
-
-  // Drop the channel offset from every agent's cursor so no offset points into
-  // a now-deleted file.
-  const cursorsAdjusted: string[] = [];
-  for (const fname of await listCursorFiles()) {
-    const id = fname.replace(/\.json$/, "");
-    const cursorPath = path.join(CURSOR_DIR, fname);
-    let touched = false;
-    await updateJson<Cursor>(cursorPath, {}, (current) => {
-      if (current.roomOffsets?.[chan] !== undefined) {
-        delete current.roomOffsets[chan];
-        touched = true;
-      }
-      return current;
-    });
-    if (touched) cursorsAdjusted.push(id);
-  }
-
-  await appendJsonl(ROOM_FILE, sysMsg(args.agentId, DEFAULT_ROOM, `deleted channel #${chan}`));
-  return { ok: true, room: chan, fileDeleted, members, cursorsAdjusted };
-}
-
-// ---------- force_unregister ----------
-
-export const forceUnregisterSchema = {
-  targetAgentId: z.string().min(1),
-};
-
-// Admin eviction — same logic as unregister but bypasses the identity gate
-// so the caller does not need to be the target agent.
-export async function forceUnregisterTool(args: { targetAgentId: string }) {
-  return unregisterTool({ agentId: args.targetAgentId });
-}
-
-// ---------- helpers ----------
-
-async function moveFile(from: string, to: string): Promise<boolean> {
-  if (!existsSync(from)) return false;
-  await fsp.mkdir(path.dirname(to), { recursive: true });
-  try {
-    await fsp.rename(from, to);
-  } catch {
-    // Cross-device or other rename failure — fall back to copy + unlink.
-    const data = await fsp.readFile(from);
-    await fsp.writeFile(to, data);
-    await fsp.unlink(from);
-  }
-  return true;
-}