agent-comm-hub 0.5.0 → 0.6.0

package/lib/cli.js

@@ -2,6 +2,8 @@
 
 // src/index.ts
 import { createServer } from "node:http";
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
 
 // src/herdr-ctl.ts
 import { execFile } from "node:child_process";
@@ -418,6 +420,7 @@ function socketSend(socketPath, method, params) {
 import { randomUUID } from "node:crypto";
 
 // src/protocol.ts
+var PEER_ID_PATTERN = /^[A-Za-z0-9._:-]{1,64}$/;
 var BROADCAST = "all";
 function decodeContent(kind, content) {
   if (kind !== "task" && kind !== "ack") return content;
@@ -430,6 +433,7 @@ function decodeContent(kind, content) {
 }
 
 // src/hub.ts
+var MAX_PROFILES = 512;
 var AgentHub = class {
   constructor(options) {
     this.options = options;
@@ -444,6 +448,8 @@ var AgentHub = class {
   waiters = /* @__PURE__ */ new Map();
   historyRing = [];
   lastSeen = /* @__PURE__ */ new Map();
+  /** Identity metadata keyed by peer id; outlives registration (see {@link PeerProfile}). */
+  profiles = /* @__PURE__ */ new Map();
   gcTimer;
   /** Stop the idle GC (call when the hub shuts down). */
   dispose() {
@@ -463,13 +469,25 @@ var AgentHub = class {
   peers() {
     return [...this.lastSeen.keys()];
   }
-  /** Register a peer; throws if the id is already taken. */
-  register(peerId) {
+  /** Register a peer; throws if the id is already taken. Client metadata
+   * (when provided) refreshes the profile — with same-name sessions sharing a
+   * peer, the freshest connect wins, which self-heals stale metadata. */
+  register(peerId, client) {
     if (this.lastSeen.has(peerId)) throw new Error(`peer already registered: ${peerId}`);
     this.lastSeen.set(peerId, Date.now());
+    const existing = this.profiles.get(peerId);
+    this.profiles.set(peerId, {
+      ...existing,
+      id: peerId,
+      registeredAt: existing?.registeredAt ?? Date.now(),
+      ...client?.name !== void 0 ? { clientName: client.name } : existing?.clientName !== void 0 ? { clientName: existing.clientName } : {},
+      ...client?.version !== void 0 ? { clientVersion: client.version } : existing?.clientVersion !== void 0 ? { clientVersion: existing.clientVersion } : {}
+    });
+    this.evictOverflowProfiles();
     this.options.onPeersChanged?.(this.peers());
   }
-  /** Remove a peer and its queued messages; pending waiters resolve as timeouts. */
+  /** Remove a peer and its queued messages; pending waiters resolve as
+   * timeouts. The profile is kept so a reconnecting peer keeps its alias. */
   unregister(peerId) {
     this.queues.delete(peerId);
     for (const waiter of this.waiters.get(peerId) ?? []) {
@@ -480,6 +498,110 @@ var AgentHub = class {
     this.lastSeen.delete(peerId);
     this.options.onPeersChanged?.(this.peers());
   }
+  /** Identity metadata for `peerId`, if the hub ever saw it. */
+  profileOf(peerId) {
+    return this.profiles.get(peerId);
+  }
+  /** Snapshot of every known profile (registered or not) for persistence. */
+  exportProfiles() {
+    return [...this.profiles.values()].map((profile) => ({ ...profile }));
+  }
+  /** Load persisted profiles at boot. Invalid entries are dropped; `null`-ish
+   * and non-finite fields are sanitized. Returns the imported count. Silent
+   * for roster observers — this runs before the server accepts requests. */
+  importProfiles(profiles) {
+    if (!Array.isArray(profiles)) return 0;
+    let count = 0;
+    for (const raw of profiles) {
+      if (typeof raw !== "object" || raw === null) continue;
+      const candidate = raw;
+      const id = candidate.id;
+      if (typeof id !== "string" || !PEER_ID_PATTERN.test(id) || id === BROADCAST) continue;
+      if (this.profiles.has(id)) continue;
+      const profile = {
+        id,
+        registeredAt: typeof candidate.registeredAt === "number" && Number.isFinite(candidate.registeredAt) ? candidate.registeredAt : Date.now()
+      };
+      if (typeof candidate.alias === "string" && candidate.alias !== "") profile.alias = candidate.alias;
+      if (typeof candidate.clientName === "string" && candidate.clientName !== "") profile.clientName = candidate.clientName;
+      if (typeof candidate.clientVersion === "string" && candidate.clientVersion !== "") profile.clientVersion = candidate.clientVersion;
+      this.profiles.set(id, profile);
+      count++;
+    }
+    this.evictOverflowProfiles();
+    return count;
+  }
+  /** Set (or clear with `undefined`) the display alias of a registered peer.
+   * Routing state is untouched — this only changes how the peer is shown. */
+  setAlias(peerId, alias) {
+    if (!this.lastSeen.has(peerId)) throw new Error(`unknown peer: ${peerId}`);
+    const profile = this.profiles.get(peerId);
+    if (profile !== void 0) {
+      this.profiles.set(peerId, alias === void 0 ? omit(profile, "alias") : { ...profile, alias });
+    }
+    this.options.onPeersChanged?.(this.peers());
+  }
+  /**
+   * Atomically re-key a registered peer: mailbox, waiters, last-seen,
+   * profile, session bindings (via the caller's registry), and history
+   * attribution move from `oldId` to `newId` in one step, so queued
+   * messages, pending waits, ack routing, and history continuity all
+   * survive the rename. All validation happens before the first mutation.
+   */
+  renamePeer(oldId, newId) {
+    if (oldId === newId) return;
+    if (!this.lastSeen.has(oldId)) throw new Error(`unknown peer: ${oldId}`);
+    if (newId === BROADCAST) throw new Error(`reserved peer id: ${newId}`);
+    if (!PEER_ID_PATTERN.test(newId)) throw new Error(`invalid peerId: ${newId} (expected [A-Za-z0-9._:-]{1,64})`);
+    if (this.lastSeen.has(newId)) throw new Error(`peer already registered: ${newId}`);
+    const queue = this.queues.get(oldId);
+    const waiters = this.waiters.get(oldId);
+    const seen = this.lastSeen.get(oldId) ?? Date.now();
+    const profile = this.profiles.get(oldId);
+    const stale = this.profiles.get(newId);
+    this.queues.delete(oldId);
+    this.waiters.delete(oldId);
+    this.lastSeen.delete(oldId);
+    this.profiles.delete(oldId);
+    if (queue !== void 0) this.queues.set(newId, queue);
+    if (waiters !== void 0) this.waiters.set(newId, waiters);
+    this.lastSeen.set(newId, seen);
+    if (profile !== void 0) {
+      const merged = {
+        ...stale,
+        ...profile,
+        id: newId,
+        registeredAt: stale !== void 0 && stale.registeredAt < profile.registeredAt ? stale.registeredAt : profile.registeredAt
+      };
+      this.profiles.set(newId, merged);
+    } else if (stale !== void 0) {
+      this.profiles.set(newId, stale);
+    } else {
+      this.profiles.set(newId, { id: newId, registeredAt: Date.now() });
+    }
+    for (const list of this.waiters.values()) {
+      for (const waiter of list) {
+        if (waiter.from === oldId) waiter.from = newId;
+      }
+    }
+    for (const message of this.historyRing) {
+      if (message.from === oldId) message.from = newId;
+      if (message.to === oldId) message.to = newId;
+    }
+    this.options.onPeersChanged?.(this.peers());
+  }
+  /** Keep the profile map bounded: drop the oldest profiles of peers that are
+   * NOT currently registered (live peers are never evicted). */
+  evictOverflowProfiles() {
+    if (this.profiles.size <= MAX_PROFILES) return;
+    const evictable = [...this.profiles.values()].filter((profile) => !this.lastSeen.has(profile.id)).sort((a, b) => a.registeredAt - b.registeredAt);
+    let overflow = this.profiles.size - MAX_PROFILES;
+    for (const profile of evictable) {
+      if (overflow <= 0) break;
+      this.profiles.delete(profile.id);
+      overflow--;
+    }
+  }
   /** Mark activity for `peer` (called on every tool call from that peer). */
   touch(peerId) {
     if (this.lastSeen.has(peerId)) this.lastSeen.set(peerId, Date.now());
@@ -526,13 +648,17 @@ var AgentHub = class {
     const now = Date.now();
     return {
       server: "agent-comm-hub",
-      peers: this.peers().map((peer) => ({
-        id: peer,
-        connected: this.isActive(peer) || livePeers?.has(peer) === true,
-        lastSeenMs: this.lastSeen.get(peer) ?? 0,
-        queued: (this.queues.get(peer) ?? []).length,
-        waiting: (this.waiters.get(peer) ?? []).length
-      })),
+      peers: this.peers().map((peer) => {
+        const alias = this.profiles.get(peer)?.alias;
+        return {
+          id: peer,
+          ...alias !== void 0 ? { alias } : {},
+          connected: this.isActive(peer) || livePeers?.has(peer) === true,
+          lastSeenMs: this.lastSeen.get(peer) ?? 0,
+          queued: (this.queues.get(peer) ?? []).length,
+          waiting: (this.waiters.get(peer) ?? []).length
+        };
+      }),
       historyLimit: this.options.historyLimit,
       maxQueue: this.options.maxQueue
     };
@@ -624,7 +750,7 @@ var AgentHub = class {
     if (queue.length >= this.options.maxQueue) queue.shift();
     queue.push(message);
     this.queues.set(target, queue);
-    this.options.onQueued?.(message);
+    this.options.onQueued?.(message, target);
   }
   /** Append a delivered message to the history ring. */
   remember(message) {
@@ -642,6 +768,10 @@ function drainFrom(queue, from) {
   queue.splice(0, queue.length, ...kept);
   return drained;
 }
+function omit(value, key) {
+  const { [key]: _dropped, ...rest } = value;
+  return rest;
+}
 
 // src/hub-tools.ts
 var DEFAULT_WAIT_MS = 3e4;
@@ -657,13 +787,25 @@ function sanitizePeerId(name) {
   const cleaned = name.toLowerCase().replace(/[^a-z0-9._:-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 64);
   return cleaned === "" ? "agent" : cleaned;
 }
-function autoRegisterPeer(hub, registry, sessionId, clientName) {
+function sanitizeAlias(alias) {
+  const cleaned = alias.trim();
+  if (cleaned === "") throw new Error("alias must not be empty");
+  if (cleaned.length > 64) throw new Error(`alias too long: ${cleaned.length} chars (max 64)`);
+  if (/[\u0000-\u001f\u007f]/.test(cleaned)) throw new Error("alias must not contain control characters");
+  return cleaned;
+}
+function autoRegisterPeer(hub, registry, sessionId, clientName, clientVersion) {
   if (sessionId === void 0) return void 0;
   const bound = registry.peerFor(sessionId);
   if (bound !== void 0) return bound;
   if (registry.isSuppressed(sessionId)) return void 0;
   const peerId = sanitizePeerId(clientName ?? "agent");
-  if (!hub.has(peerId)) hub.register(peerId);
+  if (!hub.has(peerId)) {
+    hub.register(peerId, {
+      ...clientName !== void 0 ? { name: clientName } : {},
+      ...clientVersion !== void 0 ? { version: clientVersion } : {}
+    });
+  }
   registry.bindPeer(sessionId, peerId);
   hub.touch(peerId);
   return peerId;
@@ -676,6 +818,23 @@ function livePeersFor(registry) {
   }
   return live;
 }
+function rosterFor(hub, registry) {
+  const status = hub.status(livePeersFor(registry));
+  return status.peers.map((peer) => {
+    const profile = hub.profileOf(peer.id);
+    const alias = profile?.alias;
+    const clientName = profile?.clientName;
+    const clientVersion = profile?.clientVersion;
+    return {
+      id: peer.id,
+      ...alias !== void 0 ? { alias } : {},
+      ...clientName !== void 0 ? { clientName } : {},
+      ...clientVersion !== void 0 ? { clientVersion } : {},
+      connected: peer.connected,
+      lastSeenMs: peer.lastSeenMs
+    };
+  });
+}
 function hubTools(hub, registry, options) {
   const schema = (properties, required = []) => ({
     type: "object",
@@ -719,6 +878,12 @@ function hubTools(hub, registry, options) {
     }
     return herdr;
   };
+  const requireManager = (peer, action) => {
+    const managers = options.managerPeers ?? "all";
+    if (managers !== "all" && !managers.has(peer)) {
+      throw new Error(`peer '${peer}' is not a hub manager \u2014 ${action} requires manager rights`);
+    }
+  };
   const asStatuses = (value) => {
     if (!Array.isArray(value)) return void 0;
     const statuses = value.map(String).filter((status) => AGENT_STATUSES.includes(status));
@@ -731,42 +896,108 @@ function hubTools(hub, registry, options) {
   return [
     {
       name: "bridge_register",
-      description: 'Claim or rename your identity on the hub. Sessions auto-share a peer id derived from the client name; call this to switch to a readable unique peerId such as "mavis" or "opencode:myproject". Rejects when the id is claimed by another connection. Returns the current peer list.',
-      inputSchema: schema({ peerId: str("Unique peer id: letters/digits/._:- , 1-64 chars.") }, ["peerId"]),
+      description: 'Claim or rename your identity on the hub. Sessions auto-share a peer id derived from the client name; call this to switch to a readable unique peerId such as "mavis" or "opencode:myproject". Optionally set your display alias (shown to other agents and the desktop roster; message routing keeps using the immutable peerId). Rejects when the id is claimed by another connection. Returns the current peer list.',
+      inputSchema: schema({
+        peerId: str("Unique peer id: letters/digits/._:- , 1-64 chars."),
+        alias: optStr("Optional display name (1-64 chars, spaces/CJK allowed). Routing still uses peerId.")
+      }, ["peerId"]),
       handler: async (args, sessionId) => {
         const peerId = String(args.peerId);
-        if (!/^[A-Za-z0-9._:-]{1,64}$/.test(peerId)) {
+        if (!PEER_ID_PATTERN.test(peerId)) {
           throw new Error(`invalid peerId: ${peerId} (expected [A-Za-z0-9._:-]{1,64})`);
         }
+        if (peerId === BROADCAST) {
+          throw new Error(`reserved peer id: ${peerId} (it is the broadcast address)`);
+        }
+        const alias = args.alias === void 0 ? void 0 : sanitizeAlias(String(args.alias));
         if (hub.has(peerId) && registry.peerFor(sessionId) !== peerId) {
           throw new Error(`peer already registered by another connection: ${peerId}`);
         }
         const current = registry.peerFor(sessionId);
         if (current !== void 0 && current !== peerId) {
-          registry.unbindPeer(sessionId);
-          if (registry.attachedCount(current) === 0) hub.unregister(current);
+          if (registry.attachedCount(current) === 1) {
+            hub.renamePeer(current, peerId);
+            registry.rebindPeerId(current, peerId);
+          } else {
+            registry.unbindPeer(sessionId);
+            if (registry.attachedCount(current) === 0) hub.unregister(current);
+          }
         }
-        registry.bindPeer(sessionId, peerId);
         if (!hub.has(peerId)) hub.register(peerId);
+        registry.bindPeer(sessionId, peerId);
         registry.clearSuppress(sessionId);
         hub.touch(peerId);
-        return { ok: true, peerId, peers: hub.peers() };
+        if (alias !== void 0) hub.setAlias(peerId, alias);
+        const finalAlias = hub.profileOf(peerId)?.alias;
+        return { ok: true, peerId, ...finalAlias !== void 0 ? { alias: finalAlias } : {}, peers: hub.peers() };
       }
     },
     {
       name: "bridge_unregister",
-      description: "Leave the hub: detaches your session (and drops the peer when no other session shares it); auto-registration stays off until an explicit bridge_register. Idempotent.",
-      inputSchema: schema({}),
-      handler: async (_args, sessionId) => {
-        const peer = registry.peerFor(sessionId);
-        if (peer !== void 0) {
-          registry.unbindPeer(sessionId);
-          if (registry.attachedCount(peer) === 0) hub.unregister(peer);
+      description: "Leave the hub: detaches your session (and drops the peer when no other session shares it); auto-registration stays off until an explicit bridge_register. With `peer`, a hub MANAGER can kick another peer: its queue is dropped and every session attached to it is detached and kept from auto-re-registering. Idempotent.",
+      inputSchema: schema({
+        peer: optStr("Kick this peer instead of yourself. Requires manager rights (hub managerPeers).")
+      }),
+      handler: async (args, sessionId) => {
+        if (args.peer === void 0) {
+          const peer = registry.peerFor(sessionId);
+          if (peer !== void 0) {
+            registry.unbindPeer(sessionId);
+            if (registry.attachedCount(peer) === 0) hub.unregister(peer);
+          }
+          registry.suppressAuto(sessionId);
+          return { ok: true, peerId: peer ?? null };
         }
-        registry.suppressAuto(sessionId);
-        return { ok: true, peerId: peer ?? null };
+        const caller = registry.peerFor(sessionId);
+        if (caller === void 0) throw new Error("not registered \u2014 call bridge_register(peerId) first");
+        const target = String(args.peer);
+        requireManager(caller, `kicking '${target}'`);
+        if (!hub.has(target)) {
+          return { ok: true, peerId: null, kicked: false };
+        }
+        hub.unregister(target);
+        const detached = registry.unbindPeerId(target, { suppress: true });
+        return { ok: true, peerId: target, kicked: true, detachedSessions: detached.length };
       }
     },
+    {
+      name: "bridge_rename",
+      description: "Rename on the hub, two layers: (1) `alias` sets a display name \u2014 cosmetic only, it shows up in bridge_peers / bridge_status and the desktop roster while routing, mailboxes, and history keep the immutable peer id; renaming yourself is open to everyone. (2) `peerId` truly re-keys another registered peer (manager rights required): mailbox, waiters, session bindings, and history attribution move atomically, so queued messages and acks stay continuous. Renaming ANOTHER peer (either layer) requires manager rights (hub managerPeers).",
+      inputSchema: schema({
+        alias: optStr("New display name (1-64 chars, spaces/CJK allowed; empty string clears back to no alias)."),
+        peerId: optStr("New routing id for `peer` \u2014 a true rename that moves all state (manager only). Target must be a registered peer."),
+        peer: optStr("Whose name/id to change; default yourself. Changing another peer requires manager rights.")
+      }),
+      handler: wrap(true, async (args, peer) => {
+        const hasAlias = args.alias !== void 0;
+        const hasPeerId = args.peerId !== void 0;
+        if (!hasAlias && !hasPeerId) {
+          throw new Error("nothing to rename: pass alias and/or peerId");
+        }
+        let target = args.peer === void 0 ? peer : String(args.peer);
+        if (target !== peer) requireManager(peer, `renaming '${target}'`);
+        let previousId;
+        if (hasPeerId) {
+          if (args.peer === void 0) {
+            throw new Error("peerId requires peer \u2014 to change your own id, call bridge_register(newId)");
+          }
+          const newId = String(args.peerId);
+          if (!PEER_ID_PATTERN.test(newId)) {
+            throw new Error(`invalid peerId: ${newId} (expected [A-Za-z0-9._:-]{1,64})`);
+          }
+          previousId = target;
+          hub.renamePeer(target, newId);
+          registry.rebindPeerId(target, newId);
+          target = newId;
+        }
+        if (hasAlias) {
+          const alias = String(args.alias).trim();
+          hub.setAlias(target, alias === "" ? void 0 : sanitizeAlias(alias));
+        }
+        const applied = hub.profileOf(target)?.alias;
+        return { ok: true, peerId: target, ...previousId !== void 0 ? { previousId } : {}, ...applied !== void 0 ? { alias: applied } : {} };
+      })
+    },
     {
       name: "bridge_chat",
       description: 'Send a chat message to another agent on the hub. Use bridge_wait (long-poll) or bridge_poll to receive replies. `to` is the target peerId, or "all" to broadcast.',
@@ -837,20 +1068,21 @@ function hubTools(hub, registry, options) {
     },
     {
       name: "bridge_peers",
-      description: "List registered peers and whether each is connected (recent activity or a live SSE channel).",
+      description: "List registered peers with their display identity and connection state: id (immutable routing name), optional alias (display name), client name/version reported at connect, whether connected (recent activity or a live SSE channel), and lastSeenMs.",
       inputSchema: schema({}),
-      handler: wrap(true, async () => {
-        const status = hub.status(livePeersFor(registry));
-        return { peers: hub.peers().map((id) => ({ id, connected: status.peers.find((peer) => peer.id === id)?.connected ?? false })) };
-      })
+      handler: wrap(true, async () => ({ peers: rosterFor(hub, registry) }))
     },
     {
       name: "bridge_history",
-      description: 'Recent messages involving you (newest first); pass `peer` to inspect another peer\'s conversation, or `peer: "all"` for the unfiltered tail across every peer. Use to refresh context after a reconnect.',
-      inputSchema: schema({ peer: optStr('PeerId whose conversation to inspect; "all" = every peer; default: yourself.'), limit: int("How many messages to return (default 20).") }),
+      description: 'Recent messages involving you (newest first). Use to refresh context after a reconnect. Reading ANOTHER peer\'s conversation \u2014 or `peer: "all"` for the unfiltered tail \u2014 requires manager rights (hub managerPeers).',
+      inputSchema: schema({ peer: optStr('PeerId whose conversation to inspect; "all" = every peer; default: yourself. Other peers / "all" require manager rights.'), limit: int("How many messages to return (default 20).") }),
       handler: wrap(true, async (args, peer) => {
         const limit = Math.min(args.limit === void 0 ? 20 : Number(args.limit), 1e3);
-        const messages = args.peer === "all" ? hub.historyAll(limit) : hub.history(args.peer === void 0 ? peer : String(args.peer), limit);
+        const target = args.peer === void 0 ? peer : String(args.peer);
+        if (target !== peer) {
+          requireManager(peer, `reading ${target === BROADCAST ? "the full history" : `peer '${target}' history`} requires manager rights`);
+        }
+        const messages = target === BROADCAST ? hub.historyAll(limit) : hub.history(target, limit);
         return { messages: messages.map(present) };
       })
     },
@@ -1096,15 +1328,23 @@ var SessionRegistry = class {
   }
   /** Client-reported name per session (from the initialize clientInfo). */
   clientNames = /* @__PURE__ */ new Map();
-  /** Remember the client name reported by a session (on initialize). */
-  noteClient(sessionId, name) {
+  /** Client-reported version per session (undefined when not reported). */
+  clientVersions = /* @__PURE__ */ new Map();
+  /** Remember the client name/version reported by a session (on initialize). */
+  noteClient(sessionId, name, version) {
     this.clientNames.set(sessionId, name);
+    if (version !== void 0) this.clientVersions.set(sessionId, version);
   }
   /** Client-reported name for a session, if any. */
   clientName(sessionId) {
     if (sessionId === void 0) return void 0;
     return this.clientNames.get(sessionId);
   }
+  /** Client-reported version for a session, if any. */
+  clientVersion(sessionId) {
+    if (sessionId === void 0) return void 0;
+    return this.clientVersions.get(sessionId);
+  }
   /** Sessions whose owner explicitly unregistered; auto-registration is
    * suppressed for them until an explicit `bridge_register`. */
   suppressedAuto = /* @__PURE__ */ new Set();
@@ -1134,11 +1374,39 @@ var SessionRegistry = class {
   liveSessions() {
     return this.liveStreams;
   }
-  /** Drop every binding that points at `peerId` (used by the idle GC). */
-  unbindPeerId(peerId) {
+  /** Drop every binding that points at `peerId` (used by the idle GC). With
+   * `suppress`, the detached sessions also stop auto-re-registering — the
+   * manager-kick path, so a kicked agent stays out until it explicitly
+   * `bridge_register`s or reconnects with a fresh session. */
+  unbindPeerId(peerId, options) {
+    const detached = [];
     for (const [sessionId, bound] of this.peerBindings) {
-      if (bound === peerId) this.peerBindings.delete(sessionId);
+      if (bound === peerId) {
+        this.peerBindings.delete(sessionId);
+        detached.push(sessionId);
+        if (options?.suppress === true) this.suppressedAuto.add(sessionId);
+      }
+    }
+    return detached;
+  }
+  /** Session ids currently attached to `peerId` (any binding direction). */
+  sessionsForPeer(peerId) {
+    const sessions = [];
+    for (const [sessionId, bound] of this.peerBindings) {
+      if (bound === peerId) sessions.push(sessionId);
     }
+    return sessions;
+  }
+  /** Re-point every session bound to `oldId` at `newId` (true rename). */
+  rebindPeerId(oldId, newId) {
+    let count = 0;
+    for (const [sessionId, bound] of this.peerBindings) {
+      if (bound === oldId) {
+        this.peerBindings.set(sessionId, newId);
+        count++;
+      }
+    }
+    return count;
   }
   /** How many sessions are currently attached to `peerId`. */
   attachedCount(peerId) {
@@ -1188,6 +1456,30 @@ var McpStreamableHttpServer = class {
     for (const stream of this.sseStreams.values()) stream.end();
     this.sseStreams.clear();
   }
+  /** Push a JSON-RPC notification to every open SSE stream (roster events are
+   * public — any peer could poll bridge_peers for the same information).
+   * Write failures drop the dead stream silently; SSE is best-effort and
+   * long-poll (bridge_wait) remains the reliable delivery path. */
+  notifyAll(method, params) {
+    this.notify([...this.sseStreams.keys()], method, params);
+  }
+  /** Push a JSON-RPC notification to the SSE streams of specific sessions. */
+  notify(sessionIds, method, params) {
+    const frame = `event: message
+data: ${JSON.stringify({ jsonrpc: "2.0", method, params })}
+
+`;
+    for (const sessionId of sessionIds) {
+      const stream = this.sseStreams.get(sessionId);
+      if (stream === void 0) continue;
+      try {
+        stream.write(frame);
+      } catch {
+        this.sseStreams.delete(sessionId);
+        this.registry.markSseClosed(sessionId);
+      }
+    }
+  }
   handleGet(req, res) {
     const sessionId = this.registry.ensureSession(this.registry.sessionIdFor(req));
     res.writeHead(200, {
@@ -1251,10 +1543,11 @@ var McpStreamableHttpServer = class {
         const newSessionId = this.registry.ensureSession(sessionId);
         const clientInfo = message.params?.clientInfo;
         const clientName = typeof clientInfo?.name === "string" && clientInfo.name !== "" ? clientInfo.name : void 0;
+        const clientVersion = typeof clientInfo?.version === "string" && clientInfo.version !== "" ? clientInfo.version : void 0;
         if (clientName !== void 0) {
-          this.registry.noteClient(newSessionId, clientName);
+          this.registry.noteClient(newSessionId, clientName, clientVersion);
         }
-        this.onInitialize(newSessionId, clientName);
+        this.onInitialize(newSessionId, clientName, clientVersion);
         const requested = message.params?.protocolVersion;
         const protocolVersion = typeof requested === "string" && SUPPORTED_VERSIONS.includes(requested) ? requested : LATEST_VERSION;
         return {
@@ -1344,7 +1637,7 @@ function readBody(req) {
 
 // src/index.ts
 var SERVER_NAME = "agent-comm-hub";
-var SERVER_VERSION = "0.5.0";
+var SERVER_VERSION = "0.6.0";
 var DEFAULT_HOST = "127.0.0.1";
 var DEFAULT_PORT = 18764;
 var DEFAULT_PATH = "/mcp";
@@ -1360,11 +1653,57 @@ var DEFAULT_CONFIG = {
   waitTimeoutMs: 6e4,
   defaultWaitMs: 3e4,
   connectedWindowMs: 3e4,
-  peerIdleTimeoutMs: 6e5
+  peerIdleTimeoutMs: 6e5,
+  // The companion desktop app (and `agent-comm-hub status` probe) registers
+  // as `agent-hub-cli`; it is the natural roster manager. Agents themselves
+  // are NOT managers — they keep chatting, a GUI manages.
+  managerPeers: ["agent-hub-cli"]
 };
+function writeRosterFile(file, profiles) {
+  mkdirSync(dirname(file), { recursive: true });
+  const tmp = `${file}.tmp`;
+  writeFileSync(tmp, JSON.stringify({ version: 1, savedAt: Date.now(), profiles }), "utf8");
+  renameSync(tmp, file);
+}
 function startHub(config = {}, log2 = console) {
   const overrides = Object.fromEntries(Object.entries(config).filter(([, value]) => value !== void 0));
   const resolved = { ...DEFAULT_CONFIG, ...overrides };
+  let mcp;
+  const pushRoster = () => {
+    mcp.notifyAll("notifications/message", {
+      level: "info",
+      logger: "bridge",
+      data: { event: "peers_changed", peers: rosterFor(hub, registry) }
+    });
+  };
+  const pushQueued = (message, target) => {
+    mcp.notify(registry.sessionsForPeer(target), "notifications/message", {
+      level: "info",
+      logger: "bridge",
+      data: { event: "message", message: present(message) }
+    });
+  };
+  let saveTimer;
+  let rosterDirty = false;
+  const flushRoster = () => {
+    if (resolved.stateFile === void 0 || !rosterDirty) return;
+    rosterDirty = false;
+    try {
+      writeRosterFile(resolved.stateFile, hub.exportProfiles());
+    } catch (error) {
+      log2.warn(`roster save failed: ${error.message}`);
+    }
+  };
+  const scheduleRosterSave = () => {
+    if (resolved.stateFile === void 0) return;
+    rosterDirty = true;
+    if (saveTimer !== void 0) return;
+    saveTimer = setTimeout(() => {
+      saveTimer = void 0;
+      flushRoster();
+    }, 500);
+    saveTimer.unref?.();
+  };
   const hub = new AgentHub({
     maxQueue: resolved.maxQueue,
     historyLimit: resolved.historyLimit,
@@ -1373,9 +1712,37 @@ function startHub(config = {}, log2 = console) {
     peerIdleTimeoutMs: resolved.peerIdleTimeoutMs,
     onPeerGc: (peerId) => registry.unbindPeerId(peerId),
     // The idle GC must never evict a peer whose session has a live SSE channel.
-    isPeerLive: (peerId) => livePeersFor(registry).has(peerId)
+    isPeerLive: (peerId) => livePeersFor(registry).has(peerId),
+    // SSE event push: roster changes and queued-mail hints. Best-effort — a
+    // notification failure must never break routing, so swallow and log.
+    onPeersChanged: () => {
+      try {
+        pushRoster();
+      } catch (error) {
+        log2.warn(`peers_changed notification failed: ${error.message}`);
+      }
+      scheduleRosterSave();
+    },
+    onQueued: (message, target) => {
+      try {
+        pushQueued(message, target);
+      } catch (error) {
+        log2.warn(`message notification failed: ${error.message}`);
+      }
+    }
   });
   const registry = new SessionRegistry();
+  if (resolved.stateFile !== void 0) {
+    try {
+      const parsed = JSON.parse(readFileSync(resolved.stateFile, "utf8"));
+      const imported = hub.importProfiles(parsed.profiles);
+      if (imported > 0) log2.info(`roster restored: ${imported} profile(s) from ${resolved.stateFile}`);
+    } catch (error) {
+      if (error.code !== "ENOENT") {
+        log2.warn(`roster load failed: ${error.message}`);
+      }
+    }
+  }
   const herdr = new HerdrCtl({
     bin: resolved.herdrBin,
     baseArgs: resolved.herdrBaseArgs,
@@ -1383,19 +1750,20 @@ function startHub(config = {}, log2 = console) {
     socketPath: resolved.herdrSocketPath,
     sendRequest: resolved.herdrSendRequest
   });
-  const mcp = new McpStreamableHttpServer(
+  mcp = new McpStreamableHttpServer(
     hubTools(hub, registry, {
       defaultWaitMs: resolved.defaultWaitMs,
       waitTimeoutMs: resolved.waitTimeoutMs,
       herdr,
-      herdrControlPeers: resolved.herdrControlPeers === "all" || resolved.herdrControlPeers === void 0 ? "all" : new Set(resolved.herdrControlPeers)
+      herdrControlPeers: resolved.herdrControlPeers === "all" || resolved.herdrControlPeers === void 0 ? "all" : new Set(resolved.herdrControlPeers),
+      managerPeers: resolved.managerPeers === "all" ? "all" : new Set(resolved.managerPeers ?? DEFAULT_CONFIG.managerPeers)
     }),
     { name: SERVER_NAME, version: SERVER_VERSION },
     registry,
     (message) => log2.warn(message),
-    (sessionId, clientName) => {
+    (sessionId, clientName, clientVersion) => {
       try {
-        const peer = autoRegisterPeer(hub, registry, sessionId, clientName);
+        const peer = autoRegisterPeer(hub, registry, sessionId, clientName, clientVersion);
         if (peer !== void 0) log2.info(`peer joined: ${peer}`);
       } catch (error) {
         log2.warn(`auto-register failed: ${error.message}`);
@@ -1416,6 +1784,11 @@ function startHub(config = {}, log2 = console) {
     close: () => {
       hub.dispose();
       mcp.close();
+      if (saveTimer !== void 0) {
+        clearTimeout(saveTimer);
+        saveTimer = void 0;
+      }
+      flushRoster();
       server.closeAllConnections?.();
       server.close();
     }
@@ -1426,17 +1799,17 @@ function startHub(config = {}, log2 = console) {
 import { copyFile, mkdir, readFile, writeFile } from "node:fs/promises";
 import { existsSync as existsSync2 } from "node:fs";
 import { homedir as homedir2 } from "node:os";
-import { dirname as dirname2, join as join2 } from "node:path";
+import { dirname as dirname3, join as join2 } from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 
 // src/discover.ts
 import { execFileSync } from "node:child_process";
-import { existsSync, readdirSync, accessSync, readFileSync, constants as fsConstants } from "node:fs";
+import { existsSync, readdirSync, accessSync, readFileSync as readFileSync2, constants as fsConstants } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, join, sep } from "node:path";
+import { dirname as dirname2, join, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 function registryFile() {
-  return join(dirname(fileURLToPath(import.meta.url)), "..", "agents", "registry.json");
+  return join(dirname2(fileURLToPath(import.meta.url)), "..", "agents", "registry.json");
 }
 function expandHome(file, home) {
   return file.startsWith("~/") ? join(home, file.slice(2)) : file;
@@ -1492,7 +1865,7 @@ function validateRegistry(registry) {
   }
 }
 function loadRegistry(file = registryFile()) {
-  const registry = JSON.parse(readFileSync(file, "utf8"));
+  const registry = JSON.parse(readFileSync2(file, "utf8"));
   validateRegistry(registry);
   return registry;
 }
@@ -1606,7 +1979,7 @@ function runDiscover(options = {}) {
 var DEFAULT_URL = "http://127.0.0.1:18764/mcp";
 var DEFAULT_SERVER = "agent-hub";
 function defaultSkillSrc() {
-  return join2(dirname2(fileURLToPath2(import.meta.url)), "..", "agents", "SKILL.md");
+  return join2(dirname3(fileURLToPath2(import.meta.url)), "..", "agents", "SKILL.md");
 }
 function stamp() {
   const now = /* @__PURE__ */ new Date();
@@ -1622,7 +1995,7 @@ async function readJson(file) {
   }
 }
 async function writeJsonNoBom(file, doc) {
-  await mkdir(dirname2(file), { recursive: true });
+  await mkdir(dirname3(file), { recursive: true });
   await writeFile(file, JSON.stringify(doc, null, 2) + "\n", "utf8");
 }
 async function backup(file) {
@@ -1690,12 +2063,13 @@ function escapeRegExp(value) {
   return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 var DSH_PATCH_MARKER = "# \u2500\u2500 agent-comm-hub MCP client";
+var DSH_PLUGIN_NAME = "@deepseek-ai/dsh-mcp-client";
 function dshPatchBlock(url, serverName) {
   return `
 ${DSH_PATCH_MARKER} (installed by \`agent-comm-hub setup\`; undo with \`setup --remove\`) \u2500
 - insert:
     - id: ${serverName}
-      name: '@deepseek-ai/dsh-mcp-client'
+      name: '${DSH_PLUGIN_NAME}'
       config:
         serverName: ${serverName}
         transport: streamable-http
@@ -1706,55 +2080,47 @@ async function mergeDshPatch(file, opts) {
   if (!existsSync2(file)) return "skipped";
   const text = await readFile(file, "utf8");
   const lines = text.split("\n");
-  const markerLine = lines.findIndex((line) => line.includes(DSH_PATCH_MARKER));
-  const hasBlock = markerLine >= 0;
-  const blockRange = () => {
-    let entryStart = -1;
-    for (let i = markerLine + 1; i < lines.length; i++) {
-      if (/^- /.test(lines[i])) {
-        entryStart = i;
-        break;
-      }
+  const hubEntryRanges = () => {
+    const tops = [];
+    for (let i = 0; i < lines.length; i++) {
+      if (/^- /.test(lines[i])) tops.push(i);
     }
-    let end = lines.length;
-    if (entryStart >= 0) {
-      for (let i = entryStart + 1; i < lines.length; i++) {
-        if (/^- /.test(lines[i])) {
-          end = i;
-          break;
-        }
-      }
+    const ranges2 = [];
+    for (let k = 0; k < tops.length; k++) {
+      const end = k + 1 < tops.length ? tops[k + 1] : lines.length;
+      if (!lines.slice(tops[k], end).some((line) => line.includes(DSH_PLUGIN_NAME))) continue;
+      let start = tops[k];
+      while (start > 0 && lines[start - 1].trim() === "") start--;
+      if (start > 0 && lines[start - 1].includes(DSH_PATCH_MARKER)) start--;
+      ranges2.push({ start, end });
     }
-    let start = markerLine;
-    while (start > 0 && lines[start - 1].trim() === "") start--;
-    return { start, end };
+    return ranges2;
   };
-  const withoutBlock = () => {
-    const { start, end } = blockRange();
-    return lines.slice(0, start).concat(lines.slice(end)).join("\n");
+  const withoutHubEntries = () => {
+    let out = lines;
+    for (const range of hubEntryRanges().reverse()) {
+      out = out.slice(0, range.start).concat(out.slice(range.end));
+    }
+    return out.join("\n");
   };
   if (opts.remove) {
-    if (!hasBlock) return "absent";
-    const cleaned = withoutBlock();
+    if (hubEntryRanges().length === 0) return "absent";
     await backup(file);
-    await writeFile(file, cleaned, "utf8");
+    await writeFile(file, withoutHubEntries(), "utf8");
     return "removed";
   }
-  if (hasBlock) {
-    if (lines.some((line) => line.includes(`url: ${opts.url}`))) return "unchanged";
-    const replaced = withoutBlock();
-    await backup(file);
-    await writeFile(file, replaced.trimEnd() + dshPatchBlock(opts.url, opts.serverName), "utf8");
-    return "changed";
+  const ranges = hubEntryRanges();
+  if (ranges.length === 1 && lines.slice(ranges[0].start, ranges[0].end).some((line) => line.includes(`url: ${opts.url}`))) {
+    return "unchanged";
   }
   await backup(file);
-  await writeFile(file, text.trimEnd() + dshPatchBlock(opts.url, opts.serverName), "utf8");
+  await writeFile(file, withoutHubEntries().trimEnd() + dshPatchBlock(opts.url, opts.serverName), "utf8");
   return "changed";
 }
 async function syncSkill(skillDir, skillSrc, remove, log2) {
   if (remove) {
     if (existsSync2(skillDir)) {
-      await mkdir(dirname2(skillDir), { recursive: true });
+      await mkdir(dirname3(skillDir), { recursive: true });
       await rmRecursive(skillDir);
       log2(`  skill removed: ${skillDir}`);
     }
@@ -1846,9 +2212,9 @@ async function runSetup(options = {}) {
 // src/ops.ts
 import { execFileSync as execFileSync2 } from "node:child_process";
 import { request } from "node:http";
-import { mkdirSync, readFileSync as readFileSync2, rmSync, writeFileSync } from "node:fs";
+import { mkdirSync as mkdirSync2, readFileSync as readFileSync3, rmSync, writeFileSync as writeFileSync2 } from "node:fs";
 import { homedir as homedir3 } from "node:os";
-import { dirname as dirname3, join as join3 } from "node:path";
+import { dirname as dirname4, join as join3 } from "node:path";
 import { fileURLToPath as fileURLToPath3 } from "node:url";
 async function runStatus(options = {}) {
   const host = options.host ?? "127.0.0.1";
@@ -1901,8 +2267,8 @@ async function runStatus(options = {}) {
 function runUpdate() {
   const messages = [];
   try {
-    const pkgFile = join3(dirname3(fileURLToPath3(import.meta.url)), "..", "package.json");
-    const before = JSON.parse(readFileSync2(pkgFile, "utf8")).version ?? "?";
+    const pkgFile = join3(dirname4(fileURLToPath3(import.meta.url)), "..", "package.json");
+    const before = JSON.parse(readFileSync3(pkgFile, "utf8")).version ?? "?";
     messages.push(`current version: ${before}`);
     const script = [
       "import { execFileSync } from 'node:child_process'",
@@ -1958,8 +2324,8 @@ function runService(options) {
           messages.push(`[dry-run] write ${vbs}`);
           messages.push(`[dry-run] reg add "${runKey}" /v ${valueName} /t REG_SZ /d "wscript.exe \\"${vbs}\\"" /f`);
         } else {
-          mkdirSync(launcherDir, { recursive: true });
-          writeFileSync(vbs, vbsContent);
+          mkdirSync2(launcherDir, { recursive: true });
+          writeFileSync2(vbs, vbsContent);
           execFileSync2("reg", ["add", runKey, "/v", valueName, "/t", "REG_SZ", "/d", `wscript.exe "${vbs}"`, "/f"], { encoding: "utf8", windowsHide: true });
           messages.push(`auto-start registered: HKCU Run '${valueName}' -> hidden wscript launcher "${vbs}"`);
           messages.push(`start it now with: wscript.exe "${vbs}"`);
@@ -1998,8 +2364,8 @@ WantedBy=default.target
           messages.push(`[dry-run] would write ${unitFile}`);
           messages.push(`[dry-run] systemctl --user daemon-reload && systemctl --user enable --now agent-comm-hub`);
         } else {
-          mkdirSync(unitDir, { recursive: true });
-          writeFileSync(unitFile, unit);
+          mkdirSync2(unitDir, { recursive: true });
+          writeFileSync2(unitFile, unit);
           run("systemctl", ["--user", "daemon-reload"], false);
           const out = run("systemctl", ["--user", "enable", "--now", "agent-comm-hub"], false);
           messages.push(out || `systemd user unit installed and enabled: ${unitFile}`);
@@ -2052,8 +2418,8 @@ WantedBy=default.target
           messages.push(`[dry-run] write ${plist}`);
           messages.push(`[dry-run] launchctl bootstrap gui/${uid} ${plist}`);
         } else {
-          mkdirSync(launchAgentsDir, { recursive: true });
-          writeFileSync(plist, plistContent);
+          mkdirSync2(launchAgentsDir, { recursive: true });
+          writeFileSync2(plist, plistContent);
           try {
             execFileSync2("launchctl", ["bootstrap", `gui/${uid}`, plist], { encoding: "utf8", windowsHide: true });
           } catch {
@@ -2088,10 +2454,13 @@ WantedBy=default.target
 }
 
 // src/cli.ts
+import { homedir as homedir4 } from "node:os";
+import { join as join4 } from "node:path";
+var DEFAULT_STATE_FILE = join4(homedir4(), ".agent-comm-hub", "roster.json");
 function parseArgs(argv) {
   const args = {};
   const numeric = /* @__PURE__ */ new Set(["--port", "--max-queue", "--history-limit", "--wait-timeout-ms", "--default-wait-ms", "--connected-window-ms", "--peer-idle-timeout-ms", "--herdr-timeout-ms"]);
-  const string = /* @__PURE__ */ new Set(["--host", "--path", "--url", "--server-name", "--agent", "--herdr-bin"]);
+  const string = /* @__PURE__ */ new Set(["--host", "--path", "--url", "--server-name", "--agent", "--herdr-bin", "--manager-peers", "--state-file"]);
   for (let i = 0; i < argv.length; i++) {
     const flag = argv[i];
     if (flag === "--help" || flag === "-h" || flag === "--version" || flag === "-V") {
@@ -2151,6 +2520,13 @@ Hub options:
   --herdr-bin <path>         herdr CLI binary for bridge_agent_* control tools
                              (default herdr, resolved via PATH)
   --herdr-timeout-ms <n>     Default cap for one herdr call in ms (default 30000)
+  --manager-peers <ids>      Comma-separated peer ids allowed to manage the
+                             roster (rename others / kick), or "all".
+                             (default agent-hub-cli \u2014 the desktop GUI identity)
+  --state-file <path>        Persist the peer roster (aliases, client info) to
+                             this JSON file so identities survive restarts
+                             (default ~/.agent-comm-hub/roster.json; "off"
+                             keeps everything in memory)
 
 Setup options:
   --url <url>              Hub endpoint to register (default http://127.0.0.1:18764/mcp)
@@ -2208,7 +2584,8 @@ try {
       console.log("no peers online yet \u2014 start an agent session to see it appear");
     } else {
       for (const peer of result.peers) {
-        console.log(`  ${peer.id.padEnd(32)} ${peer.connected ? "connected" : "offline"}`);
+        const label = peer.alias !== void 0 && peer.alias !== peer.id ? `${peer.id} (${peer.alias})` : peer.id;
+        console.log(`  ${label.padEnd(32)} ${peer.connected ? "connected" : "offline"}`);
       }
     }
     process.exit(0);
@@ -2268,7 +2645,9 @@ try {
     connectedWindowMs: args["--connected-window-ms"],
     peerIdleTimeoutMs: args["--peer-idle-timeout-ms"],
     herdrBin: args["--herdr-bin"],
-    herdrTimeoutMs: args["--herdr-timeout-ms"]
+    herdrTimeoutMs: args["--herdr-timeout-ms"],
+    managerPeers: args["--manager-peers"] === void 0 ? void 0 : args["--manager-peers"] === "all" ? "all" : String(args["--manager-peers"]).split(",").map((id) => id.trim()).filter((id) => id !== ""),
+    stateFile: args["--state-file"] === void 0 ? DEFAULT_STATE_FILE : args["--state-file"] === "off" ? void 0 : String(args["--state-file"])
   }, log);
   const shutdown = () => {
     log.info("agent-comm-hub shutting down");