agent-coord-mcp 0.4.9 → 0.5.0

package/src/server.ts

@@ -9,10 +9,16 @@ import {
   detachAgentTool,
   heartbeatSchema,
   heartbeatTool,
+  joinRoomSchema,
+  joinRoomTool,
   joinSchema,
   joinTool,
+  leaveRoomSchema,
+  leaveRoomTool,
   listAgentsSchema,
   listAgentsTool,
+  listRoomsSchema,
+  listRoomsTool,
   postStatusSchema,
   postStatusTool,
   pruneSchema,
@@ -21,8 +27,14 @@ import {
   readMessagesTool,
   registerSchema,
   registerTool,
+  renameAgentSchema,
+  renameAgentTool,
   sendMessageSchema,
   sendMessageTool,
+  setRoomMotdSchema,
+  setRoomMotdTool,
+  setRoomTopicSchema,
+  setRoomTopicTool,
   statusSchema,
   statusTool,
   unregisterSchema,
@@ -89,14 +101,14 @@ async function main() {
 
   server.tool(
     "send_message",
-    "Send a message. If 'to' is set, goes to that agent's inbox; otherwise to the shared room.",
+    "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.",
     sendMessageSchema,
     async (args) => jsonResult(await sendMessageTool(args))
   );
 
   server.tool(
     "read_messages",
-    "Read new messages from inbox|room|status. Advances the cursor unless peek=true.",
+    "Read new messages from inbox|room|status. For source='room', pass 'room' to read a specific channel (default 'general'). Advances the per-channel cursor unless peek=true.",
     readMessagesSchema,
     async (args) => jsonResult(await readMessagesTool(args))
   );
@@ -117,11 +129,53 @@ async function main() {
 
   server.tool(
     "wait_for_message",
-    "Block (max 60s) until a new message appears on the given source, then return it.",
+    "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,
     async (args) => jsonResult(await waitForMessageTool(args))
   );
 
+  server.tool(
+    "list_rooms",
+    "List all channels with their topic, MOTD (room rules), members, message count, and last activity.",
+    listRoomsSchema,
+    async () => jsonResult(await listRoomsTool())
+  );
+
+  server.tool(
+    "join_room",
+    "Join a channel (creating it if new). Adds this agent to the channel's membership so the notification hooks push its messages, and returns the channel's topic, MOTD, members, and unread count.",
+    joinRoomSchema,
+    async (args) => jsonResult(await joinRoomTool(args))
+  );
+
+  server.tool(
+    "leave_room",
+    "Leave a channel — removes this agent from its membership. Cannot leave the default 'general' channel.",
+    leaveRoomSchema,
+    async (args) => jsonResult(await leaveRoomTool(args))
+  );
+
+  server.tool(
+    "set_room_topic",
+    "Set a channel's topic (a short one-line description). Posts a system notice to the channel.",
+    setRoomTopicSchema,
+    async (args) => jsonResult(await setRoomTopicTool(args))
+  );
+
+  server.tool(
+    "set_room_motd",
+    "Set a channel's MOTD / room rules (shown to agents on join). Posts a system notice to the channel.",
+    setRoomMotdSchema,
+    async (args) => jsonResult(await setRoomMotdTool(args))
+  );
+
+  server.tool(
+    "rename_agent",
+    "Rename an agent (NICK): migrates its registry entry, inbox, cursor, transport marker, and channel memberships to the new id, then broadcasts a rename notice to its channels. Note: a running attached pusher keeps its old id until restarted.",
+    renameAgentSchema,
+    async (args) => jsonResult(await renameAgentTool(args))
+  );
+
   server.tool(
     "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.",

package/src/store.ts

@@ -16,8 +16,16 @@ export const TRANSPORT_DIR = path.join(ROOT, "transports");
 export const PID_DIR = path.join(ROOT, "pids");
 export const LOG_DIR = path.join(ROOT, "logs");
 
+// Channels. The default channel `general` keeps using the legacy single-room
+// file (room.jsonl) + the flat `roomOffset` cursor key, so existing agents and
+// the notification hooks keep working with zero migration. Every other channel
+// lives in rooms/<chan>.jsonl with its offset under cursor.roomOffsets[chan].
+export const ROOMS_DIR = path.join(ROOT, "rooms");
+export const ROOMS_FILE = path.join(ROOT, "rooms.json");
+export const DEFAULT_ROOM = "general";
+
 export function ensureDirs(): void {
-  for (const d of [ROOT, INBOX_DIR, CURSOR_DIR, TRANSPORT_DIR, PID_DIR, LOG_DIR]) {
+  for (const d of [ROOT, INBOX_DIR, CURSOR_DIR, TRANSPORT_DIR, PID_DIR, LOG_DIR, ROOMS_DIR]) {
     if (!existsSync(d)) mkdirSync(d, { recursive: true });
   }
   for (const f of [ROOM_FILE, STATUS_FILE]) {
@@ -25,6 +33,87 @@ export function ensureDirs(): void {
   }
 }
 
+export type RoomEntry = {
+  topic?: string;
+  motd?: string;
+  createdAt: number;
+  createdBy: string;
+  members: string[];
+};
+export type RoomRegistry = Record<string, RoomEntry>;
+
+// Normalize a channel name: strip leading '#', lowercase, restrict to a safe
+// charset, empty → the default channel. Display layers re-add the '#'.
+export function normalizeRoom(name?: string): string {
+  if (!name) return DEFAULT_ROOM;
+  const n = name.trim().replace(/^#+/, "").toLowerCase().replace(/[^a-z0-9._-]/g, "");
+  return n || DEFAULT_ROOM;
+}
+
+// Resolve a channel to its physical JSONL file. `general` maps to the legacy
+// room.jsonl for backward compatibility; everything else to rooms/<chan>.jsonl.
+export function roomFile(chan: string): string {
+  const c = normalizeRoom(chan);
+  return c === DEFAULT_ROOM ? ROOM_FILE : path.join(ROOMS_DIR, `${sanitize(c)}.jsonl`);
+}
+
+function blankRoom(createdBy: string): RoomEntry {
+  return { createdAt: Date.now(), createdBy, members: [] };
+}
+
+// Read the channel registry, always surfacing `general` even before it has been
+// explicitly persisted (it exists implicitly via room.jsonl).
+export async function getRooms(): Promise<RoomRegistry> {
+  const reg = await readJson<RoomRegistry>(ROOMS_FILE, {});
+  if (!reg[DEFAULT_ROOM]) reg[DEFAULT_ROOM] = { createdAt: 0, createdBy: "system", members: [] };
+  return reg;
+}
+
+export async function ensureRoom(chan: string, createdBy: string): Promise<void> {
+  const c = normalizeRoom(chan);
+  await updateJson<RoomRegistry>(ROOMS_FILE, {}, (cur) => {
+    if (!cur[c]) cur[c] = blankRoom(createdBy);
+    return cur;
+  });
+}
+
+export async function setRoomMeta(chan: string, meta: { topic?: string; motd?: string }, by = "system"): Promise<void> {
+  const c = normalizeRoom(chan);
+  await updateJson<RoomRegistry>(ROOMS_FILE, {}, (cur) => {
+    const e = (cur[c] ??= blankRoom(by));
+    if (meta.topic !== undefined) e.topic = meta.topic;
+    if (meta.motd !== undefined) e.motd = meta.motd;
+    return cur;
+  });
+}
+
+export async function addMember(chan: string, agentId: string): Promise<void> {
+  const c = normalizeRoom(chan);
+  await updateJson<RoomRegistry>(ROOMS_FILE, {}, (cur) => {
+    const e = (cur[c] ??= blankRoom(agentId));
+    if (!e.members.includes(agentId)) e.members.push(agentId);
+    return cur;
+  });
+}
+
+export async function removeMember(chan: string, agentId: string): Promise<void> {
+  const c = normalizeRoom(chan);
+  await updateJson<RoomRegistry>(ROOMS_FILE, {}, (cur) => {
+    if (cur[c]) cur[c].members = cur[c].members.filter((m) => m !== agentId);
+    return cur;
+  });
+}
+
+// Channels this agent has joined (always includes the default channel).
+export async function memberRooms(agentId: string): Promise<string[]> {
+  const reg = await getRooms();
+  const out = new Set<string>([DEFAULT_ROOM]);
+  for (const [chan, e] of Object.entries(reg)) {
+    if (e.members?.includes(agentId)) out.add(chan);
+  }
+  return [...out];
+}
+
 export function transportFile(agentId: string): string {
   return path.join(TRANSPORT_DIR, `${sanitize(agentId)}.json`);
 }

package/src/tools.ts

@@ -8,24 +8,34 @@ import path from "node:path";
 import {
   AGENTS_FILE,
   CURSOR_DIR,
+  DEFAULT_ROOM,
   INBOX_DIR,
-  ROOM_FILE,
+  ROOMS_FILE,
   STATUS_FILE,
+  addMember,
   appendJsonl,
   cursorFile,
   deleteFile,
+  ensureRoom,
   fileSize,
+  getRooms,
   inboxFile,
   listCursorFiles,
   listInboxFiles,
   listTransportFiles,
   logFile,
+  memberRooms,
+  normalizeRoom,
   pidFile,
   readJson,
   readJsonl,
+  removeMember,
   rewriteJsonl,
+  roomFile,
+  setRoomMeta,
   transportFile,
   updateJson,
+  type RoomRegistry,
 } from "./store.js";
 
 type AgentEntry = {
@@ -54,6 +64,8 @@ type Message = {
   to?: string;
   room?: string;
   text: string;
+  // System notices (join/part/topic/nick) — rendered distinctly by clients.
+  system?: boolean;
 };
 
 type StatusEntry = {
@@ -66,10 +78,42 @@ type StatusEntry = {
 
 type Cursor = {
   inboxOffset?: number;
-  roomOffset?: 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;
@@ -224,17 +268,33 @@ export async function sendMessageTool(args: {
   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);
+    return { ok: true, id: msg.id, target, room: undefined };
+  }
+
+  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,
-    to: args.to,
-    room: args.room,
+    room: chan,
     text: args.text,
   };
-  const target = args.to ? inboxFile(args.to) : ROOM_FILE;
+  const target = roomFile(chan);
   await appendJsonl(target, msg);
-  return { ok: true, id: msg.id, target };
+  return { ok: true, id: msg.id, target, room: chan };
 }
 
 // ---------- read_messages ----------
@@ -242,6 +302,7 @@ export async function sendMessageTool(args: {
 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(),
@@ -249,13 +310,13 @@ export const readMessagesSchema = {
 
 export async function readMessagesTool(args: {
   agentId: string;
-  source: "inbox" | "room" | "status";
+  source: Source;
+  room?: string;
   limit?: number;
   peek?: boolean;
   sinceTs?: number;
 }) {
-  const file = sourceFile(args.source, args.agentId);
-  const offsetKey = offsetKeyFor(args.source);
+  const file = sourceFile(args.source, args.agentId, args.room);
   const all = await readJsonl<Message | StatusEntry>(file);
 
   let limited: (Message | StatusEntry)[] = [];
@@ -263,19 +324,19 @@ export async function readMessagesTool(args: {
 
   if (args.peek) {
     const cursor = await readJson<Cursor>(cursorFile(args.agentId), {});
-    const startOffset = cursor[offsetKey] ?? 0;
+    const startOffset = getOffset(cursor, args.source, args.room);
     let entries = all.slice(startOffset);
     if (args.sinceTs !== undefined) entries = entries.filter((e) => e.ts > args.sinceTs!);
     totalNew = entries.length;
     limited = args.limit ? entries.slice(0, args.limit) : entries;
   } else {
     await updateJson<Cursor>(cursorFile(args.agentId), {}, (current) => {
-      const startOffset = current[offsetKey] ?? 0;
+      const startOffset = getOffset(current, args.source, args.room);
       let entries = all.slice(startOffset);
       if (args.sinceTs !== undefined) entries = entries.filter((e) => e.ts > args.sinceTs!);
       totalNew = entries.length;
       limited = args.limit ? entries.slice(0, args.limit) : entries;
-      if (limited.length > 0) current[offsetKey] = startOffset + limited.length;
+      if (limited.length > 0) setOffset(current, args.source, args.room, startOffset + limited.length);
       return current;
     });
   }
@@ -288,7 +349,12 @@ export async function readMessagesTool(args: {
       ? limited.filter((e) => entryAuthor(e) !== args.agentId)
       : limited;
 
-  return { messages: visible, totalNew, returned: visible.length };
+  return {
+    messages: visible,
+    totalNew,
+    returned: visible.length,
+    room: args.source === "room" ? normalizeRoom(args.room) : undefined,
+  };
 }
 
 function entryAuthor(e: Message | StatusEntry): string | undefined {
@@ -320,16 +386,18 @@ export async function postStatusTool(args: { agentId: string; status: string; de
 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: "inbox" | "room" | "status";
+  source: Source;
+  room?: string;
   timeoutMs?: number;
 }) {
   const totalTimeout = Math.min(args.timeoutMs ?? 30_000, MAX_WAIT_MS);
-  const file = sourceFile(args.source, args.agentId);
+  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
@@ -373,7 +441,7 @@ export async function waitForMessageTool(args: {
     });
 
     if (!changed) break;
-    const result = await readMessagesTool({ agentId: args.agentId, source: args.source });
+    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
   }
@@ -401,8 +469,14 @@ export async function pruneTool(args: {
   const reg = await readJson<AgentRegistry>(AGENTS_FILE, {});
   const knownAgents = new Set(Object.keys(reg));
 
+  const channels = Object.keys(await getRooms());
+
   if (dryRun) {
-    const room = await readJsonl<Message>(ROOM_FILE);
+    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;
@@ -418,7 +492,7 @@ export async function pruneTool(args: {
       cutoff,
       olderThanDays: days,
       wouldRemove: {
-        roomMessages: room.filter((e) => e.ts <= cutoff).length,
+        roomMessages,
         statusEntries: status.filter((e) => e.ts <= cutoff).length,
         inboxMessages: inboxRemoved,
         orphanInboxes: orphans,
@@ -426,7 +500,17 @@ export async function pruneTool(args: {
     };
   }
 
-  const roomResult = await rewriteJsonl<Message>(ROOM_FILE, (e) => e.ts > cutoff);
+  // 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();
@@ -460,9 +544,16 @@ export async function pruneTool(args: {
     const cursorPath = path.join(CURSOR_DIR, cname);
     let touched = false;
     await updateJson<Cursor>(cursorPath, {}, (current) => {
-      if (current.roomOffset !== undefined && roomResult.removed > 0) {
-        current.roomOffset = Math.max(0, current.roomOffset - roomResult.removed);
-        touched = true;
+      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);
@@ -483,7 +574,7 @@ export async function pruneTool(args: {
     cutoff,
     olderThanDays: days,
     removed: {
-      roomMessages: roomResult.removed,
+      roomMessages: roomRemovedTotal,
       statusEntries: statusResult.removed,
       inboxMessages: inboxRemoved,
       orphanInboxes: deletedOrphans,
@@ -747,16 +838,156 @@ export async function joinTool(args: {
   };
 }
 
-// ---------- helpers ----------
+// ---------- 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 };
+}
 
-function sourceFile(source: "inbox" | "room" | "status", agentId: string): string {
-  if (source === "inbox") return inboxFile(agentId);
-  if (source === "room") return ROOM_FILE;
-  return STATUS_FILE;
+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);
+  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,
+  };
 }
 
-function offsetKeyFor(source: "inbox" | "room" | "status"): keyof Cursor {
-  if (source === "inbox") return "inboxOffset";
-  if (source === "room") return "roomOffset";
-  return "statusOffset";
+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);
+
+  // 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, transport marker.
+  await moveFile(inboxFile(oldId), inboxFile(newId));
+  await moveFile(cursorFile(oldId), cursorFile(newId));
+  await moveFile(transportFile(oldId), transportFile(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 };
+}
+
+// ---------- 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;
 }