agent-comm-hub 0.5.0 → 0.7.0

package/lib/index.js

@@ -1,5 +1,8 @@
 // src/index.ts
 import { createServer } from "node:http";
+import { randomBytes as randomBytes2 } from "node:crypto";
+import { mkdirSync as mkdirSync2, readFileSync as readFileSync3, renameSync as renameSync2, writeFileSync as writeFileSync2 } from "node:fs";
+import { dirname as dirname2 } from "node:path";
 
 // src/herdr-ctl.ts
 import { execFile } from "node:child_process";
@@ -433,6 +436,7 @@ function decodeContent(kind, content) {
 }
 
 // src/hub.ts
+var MAX_PROFILES = 512;
 var AgentHub = class {
   constructor(options) {
     this.options = options;
@@ -447,6 +451,10 @@ 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();
+  /** Named channels (group channel), keyed by group id. */
+  groups = /* @__PURE__ */ new Map();
   gcTimer;
   /** Stop the idle GC (call when the hub shuts down). */
   dispose() {
@@ -466,14 +474,27 @@ 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) {
+    if ((this.queues.get(peerId) ?? []).length > 0) this.options.onMailboxesChanged?.();
     this.queues.delete(peerId);
     for (const waiter of this.waiters.get(peerId) ?? []) {
       clearTimeout(waiter.timer);
@@ -483,6 +504,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());
@@ -510,9 +635,20 @@ var AgentHub = class {
     if (!original) throw new Error(`cannot ack unknown message: ${ref}`);
     return this.route(from, original.from, "ack", JSON.stringify(ack), ref);
   }
-  /** Recent messages involving `peer` (inbound and outbound), newest first. */
+  /** Recent messages involving `peer` (inbound and outbound, plus group
+   * channels the peer belongs to), newest first. */
   history(peerId, limit) {
-    const filtered = this.historyRing.filter((message) => message.from === peerId || message.to === peerId || message.to === BROADCAST);
+    const memberOf = new Set(
+      [...this.groups.values()].filter((group) => group.members.includes(peerId)).map((group) => group.id)
+    );
+    const filtered = this.historyRing.filter(
+      (message) => message.from === peerId || message.to === peerId || message.to === BROADCAST || message.channel !== void 0 && memberOf.has(message.channel)
+    );
+    return filtered.slice(-Math.max(0, limit)).reverse();
+  }
+  /** Recent messages of one group channel, newest first. */
+  historyChannel(groupId, limit) {
+    const filtered = this.historyRing.filter((message) => message.channel === groupId || message.to === groupId && message.channel === void 0 && this.groups.has(groupId));
     return filtered.slice(-Math.max(0, limit)).reverse();
   }
   /** Most recent messages across every peer, unfiltered (newest first).
@@ -521,21 +657,190 @@ var AgentHub = class {
   historyAll(limit) {
     return this.historyRing.slice(-Math.max(0, limit)).reverse();
   }
+  // ---- groups (group channel) ------------------------------------------------
+  /** Create a channel; throws when the id is taken or a member is unknown. */
+  createGroup(id, members, createdBy, name) {
+    if (this.groups.has(id)) throw new Error(`group already exists: ${id}`);
+    if (!PEER_ID_PATTERN.test(id)) throw new Error(`invalid group id: ${id} (expected [A-Za-z0-9._:-]{1,64})`);
+    const unique = [...new Set(members)];
+    if (unique.length === 0) throw new Error("a group needs at least one member");
+    for (const member of unique) {
+      if (!this.lastSeen.has(member)) throw new Error(`unknown member peer: ${member}`);
+    }
+    if (!unique.includes(createdBy)) unique.unshift(createdBy);
+    const group = { id, members: unique, createdBy, createdAt: Date.now(), ...name !== void 0 && name !== "" ? { name } : {} };
+    this.groups.set(id, group);
+    this.options.onGroupsChanged?.();
+    return group;
+  }
+  /** Remove a channel (its history rows stay — attribution is unchanged). */
+  deleteGroup(id) {
+    if (!this.groups.delete(id)) return false;
+    this.options.onGroupsChanged?.();
+    return true;
+  }
+  groupOf(id) {
+    return this.groups.get(id);
+  }
+  /** Add a registered peer to an existing channel, so they can send and read
+   * it like any other member. Throws when the group is unknown, the peer is
+   * not registered, or it is already inside. */
+  addGroupMember(groupId, member) {
+    const group = this.groups.get(groupId);
+    if (group === void 0) throw new Error(`unknown group: ${groupId}`);
+    if (group.members.includes(member)) throw new Error(`peer '${member}' is already a member of group '${groupId}'`);
+    if (!this.lastSeen.has(member)) throw new Error(`unknown member peer: ${member}`);
+    group.members.push(member);
+    this.options.onGroupsChanged?.();
+    return group;
+  }
+  /** Remove a member from a channel. The creator cannot be removed (it would
+   * orphan the channel's management). Throws when the group or the membership
+   * is missing. */
+  removeGroupMember(groupId, member) {
+    const group = this.groups.get(groupId);
+    if (group === void 0) throw new Error(`unknown group: ${groupId}`);
+    if (member === group.createdBy) throw new Error(`cannot remove the group creator '${member}'`);
+    const index = group.members.indexOf(member);
+    if (index === -1) throw new Error(`peer '${member}' is not a member of group '${groupId}'`);
+    group.members.splice(index, 1);
+    this.options.onGroupsChanged?.();
+    return group;
+  }
+  /** All groups (snapshot copy), insertion order. */
+  allGroups() {
+    return [...this.groups.values()].map((group) => ({ ...group, members: [...group.members] }));
+  }
+  /** Send a chat message to every member of a group except the sender;
+   * members that went offline are skipped (they read the group history).
+   * The message carries `to` and `channel` = the group id. */
+  sendToGroup(from, groupId, content) {
+    const group = this.groups.get(groupId);
+    if (group === void 0) throw new Error(`unknown group: ${groupId}`);
+    if (!group.members.includes(from)) throw new Error(`peer '${from}' is not a member of group '${groupId}'`);
+    const message = {
+      id: randomUUID(),
+      from,
+      to: groupId,
+      kind: "chat",
+      content,
+      channel: groupId,
+      ts: Date.now()
+    };
+    this.lastSeen.set(from, message.ts);
+    for (const member of group.members) {
+      if (member !== from && this.lastSeen.has(member)) this.deliver(member, message);
+    }
+    return message;
+  }
+  /** Snapshot of every group for persistence. */
+  exportGroups() {
+    return this.allGroups();
+  }
+  /** Load persisted groups at boot (same validation as createGroup, minus
+   * the "members must be online" rule — members reconnect later). */
+  importGroups(groups) {
+    if (!Array.isArray(groups)) return 0;
+    let count = 0;
+    for (const raw of groups) {
+      if (typeof raw !== "object" || raw === null) continue;
+      const candidate = raw;
+      if (typeof candidate.id !== "string" || !PEER_ID_PATTERN.test(candidate.id) || this.groups.has(candidate.id)) continue;
+      if (!Array.isArray(candidate.members) || candidate.members.length === 0) continue;
+      const members = [...new Set(candidate.members.filter((m) => typeof m === "string" && PEER_ID_PATTERN.test(m)))];
+      if (members.length === 0) continue;
+      this.groups.set(candidate.id, {
+        id: candidate.id,
+        members,
+        createdBy: typeof candidate.createdBy === "string" && PEER_ID_PATTERN.test(candidate.createdBy) ? candidate.createdBy : members[0],
+        createdAt: typeof candidate.createdAt === "number" && Number.isFinite(candidate.createdAt) ? candidate.createdAt : Date.now(),
+        ...typeof candidate.name === "string" && candidate.name !== "" ? { name: candidate.name } : {}
+      });
+      count++;
+    }
+    return count;
+  }
+  // ---- persistence import/export (remote-mode SQLite store) -----------
+  /** Restore the history ring at boot. Shape-invalid rows are dropped; only
+   * the newest {@link HubOptions.historyLimit} survive. */
+  importHistory(messages) {
+    if (!Array.isArray(messages)) return 0;
+    const valid = [];
+    for (const raw of messages) {
+      if (typeof raw !== "object" || raw === null) continue;
+      const m = raw;
+      if (typeof m.id !== "string" || typeof m.from !== "string" || typeof m.to !== "string" || typeof m.content !== "string" || typeof m.ts !== "number") continue;
+      if (KINDS.includes(m.kind) === false) continue;
+      valid.push({
+        id: m.id,
+        from: m.from,
+        to: m.to,
+        kind: m.kind,
+        content: m.content,
+        ...typeof m.ref === "string" ? { ref: m.ref } : {},
+        ...typeof m.channel === "string" ? { channel: m.channel } : {},
+        ts: m.ts
+      });
+    }
+    for (const message of valid.slice(-this.options.historyLimit)) this.historyRing.push(message);
+    return Math.min(valid.length, this.options.historyLimit);
+  }
+  /** Snapshot of every offline mailbox, keyed by peer (persistence). */
+  exportMailboxes() {
+    const out = {};
+    for (const [peer, queue] of this.queues) {
+      if (queue.length > 0) out[peer] = queue.map((message) => ({ ...message }));
+    }
+    return out;
+  }
+  /** Restore offline mailboxes at boot (peer reconnects and drains later). */
+  importMailboxes(mailboxes) {
+    if (typeof mailboxes !== "object" || mailboxes === null) return 0;
+    let count = 0;
+    for (const [peer, queue] of Object.entries(mailboxes)) {
+      if (!Array.isArray(queue) || queue.length === 0) continue;
+      const restored = [];
+      for (const raw of queue) {
+        if (typeof raw !== "object" || raw === null) continue;
+        const m = raw;
+        if (typeof m.id !== "string" || typeof m.from !== "string" || typeof m.content !== "string" || typeof m.ts !== "number") continue;
+        restored.push({
+          id: m.id,
+          from: m.from,
+          to: typeof m.to === "string" ? m.to : peer,
+          kind: KINDS.includes(m.kind) ? m.kind : "chat",
+          content: m.content,
+          ...typeof m.ref === "string" ? { ref: m.ref } : {},
+          ...typeof m.channel === "string" ? { channel: m.channel } : {},
+          ts: m.ts
+        });
+      }
+      if (restored.length > 0) {
+        this.queues.set(peer, restored.slice(-this.options.maxQueue));
+        count += restored.length;
+      }
+    }
+    return count;
+  }
   /**
-   * Live summary for the status tool. `livePeers` (sessions with a live SSE
-   * stream) count as connected even without recent tool activity.
-   */
+  * Live summary for the status tool. `livePeers` (sessions with a live SSE
+  * stream) count as connected even without recent tool activity.
+  */
   status(livePeers) {
     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
     };
@@ -544,7 +849,7 @@ var AgentHub = class {
   poll(peerId, from) {
     const queue = this.queues.get(peerId) ?? [];
     const drained = from === void 0 ? queue.splice(0, queue.length) : drainFrom(queue, from);
-    for (const message of drained) this.remember(message);
+    if (drained.length > 0) this.options.onMailboxesChanged?.();
     return drained;
   }
   /**
@@ -627,12 +932,15 @@ var AgentHub = class {
     if (queue.length >= this.options.maxQueue) queue.shift();
     queue.push(message);
     this.queues.set(target, queue);
-    this.options.onQueued?.(message);
+    this.remember(message);
+    this.options.onQueued?.(message, target);
   }
-  /** Append a delivered message to the history ring. */
+  /** Append a delivered message to the history ring (and fire the
+   * persistence hook — one call per message, delivered or queued). */
   remember(message) {
     this.historyRing.push(message);
     if (this.historyRing.length > this.options.historyLimit) this.historyRing.splice(0, this.historyRing.length - this.options.historyLimit);
+    this.options.onMessage?.(message);
   }
 };
 function drainFrom(queue, from) {
@@ -645,14 +953,164 @@ function drainFrom(queue, from) {
   queue.splice(0, queue.length, ...kept);
   return drained;
 }
+function omit(value, key) {
+  const { [key]: _dropped, ...rest } = value;
+  return rest;
+}
+
+// src/auth.ts
+import { randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+var ANON_JOIN_PEER = "__join__";
+var TOKEN_PATTERN = /^[A-Za-z0-9._:-]{16,128}$/;
+function loadTokenFile(file) {
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(file, "utf8"));
+  } catch (error) {
+    throw new Error(`auth token file unreadable: ${file} (${error.message})`);
+  }
+  const rows = parsed?.tokens;
+  if (!Array.isArray(rows)) throw new Error(`auth token file ${file}: expected {"tokens":[...]}`);
+  const table = /* @__PURE__ */ new Map();
+  const peers = /* @__PURE__ */ new Set();
+  rows.forEach((row, index) => {
+    const msg = (why) => `auth token file ${file}: entry #${index + 1} ${why}`;
+    if (typeof row !== "object" || row === null) throw new Error(msg("is not an object"));
+    const { token, peer, role, owner } = row;
+    if (typeof token !== "string" || !TOKEN_PATTERN.test(token)) {
+      throw new Error(msg("has an invalid token (expect 16-128 chars of [A-Za-z0-9._:-])"));
+    }
+    if (typeof peer !== "string" || !PEER_ID_PATTERN.test(peer) || peer === "all") {
+      throw new Error(msg(`has an invalid peer id '${String(peer)}'`));
+    }
+    if (role !== "agent" && role !== "manager") {
+      throw new Error(msg(`has an invalid role '${String(role)}' (expected 'agent' | 'manager')`));
+    }
+    if (owner !== void 0 && typeof owner !== "string") throw new Error(msg("has a non-string owner"));
+    if (table.has(token)) throw new Error(msg("duplicates a token"));
+    if (peers.has(peer)) {
+      throw new Error(msg(`maps a second token to peer '${peer}' (two tokens sharing a peer share its mailbox)`));
+    }
+    table.set(token, { peer, role, ...typeof owner === "string" && owner !== "" ? { owner } : {} });
+    peers.add(peer);
+  });
+  if (table.size === 0) throw new Error(`auth token file ${file}: no tokens defined`);
+  return table;
+}
+function tokenTable(map) {
+  return {
+    authenticate: (token) => token === void 0 ? void 0 : map.get(token)
+  };
+}
+function watchTokenFile(file, log) {
+  let table = loadTokenFile(file);
+  const reload = () => {
+    try {
+      const next = loadTokenFile(file);
+      table = next;
+      log.info(`auth tokens reloaded: ${table.size} entr(ies)`);
+    } catch (error) {
+      log.warn(`auth token reload ignored, keeping previous table: ${error.message}`);
+    }
+  };
+  log.info(`auth tokens loaded: ${table.size} entr(ies) from ${file}`);
+  let mtime = statMtime(file);
+  const timer = setInterval(() => {
+    const current = statMtime(file);
+    if (current === mtime) return;
+    mtime = current;
+    reload();
+  }, 2e3);
+  timer.unref?.();
+  return { authenticate: (token) => token === void 0 ? void 0 : table.get(token), reload };
+}
+function statMtime(file) {
+  try {
+    return statSync(file).mtimeMs;
+  } catch {
+    return 0;
+  }
+}
+function bearerFromHeaders(headers) {
+  const raw = Array.isArray(headers.authorization) ? headers.authorization[0] : headers.authorization;
+  if (raw === void 0) return void 0;
+  const match = /^Bearer\s+(.+)$/.exec(raw.trim());
+  return match === null ? void 0 : match[1];
+}
+function generateToken() {
+  return randomBytes(24).toString("base64url");
+}
+function readTokens(file) {
+  if (!existsSync(file)) return [];
+  try {
+    return [...loadTokenFile(file).entries()].map(([token, id]) => ({
+      token,
+      peer: id.peer,
+      role: id.role,
+      ...id.owner !== void 0 ? { owner: id.owner } : {}
+    }));
+  } catch (error) {
+    try {
+      const parsed = JSON.parse(readFileSync(file, "utf8"));
+      if (Array.isArray(parsed.tokens) && parsed.tokens.length === 0) return [];
+    } catch {
+    }
+    throw error;
+  }
+}
+function writeTokenFile(file, rows) {
+  mkdirSync(dirname(file), { recursive: true });
+  const tmp = `${file}.tmp`;
+  writeFileSync(tmp, JSON.stringify({ tokens: rows }, null, 2) + "\n", "utf8");
+  renameSync(tmp, file);
+}
+function addToken(file, row) {
+  const token = row.token ?? generateToken();
+  if (!TOKEN_PATTERN.test(token)) {
+    throw new Error(`invalid token provided (expect 16-128 chars of [A-Za-z0-9._:-])`);
+  }
+  const peers = new Set(readTokens(file).map((t) => t.peer));
+  if (peers.has(row.peer)) {
+    throw new Error(`peer '${row.peer}' already has a token \u2014 remove it first to rotate (see \`auth remove\`)`);
+  }
+  const owner = row.owner !== void 0 && row.owner !== "" ? row.owner : void 0;
+  const identity = { token, peer: row.peer, role: row.role, ...owner !== void 0 ? { owner } : {} };
+  const next = [...readTokens(file), identity];
+  loadTokenFileVoid(next);
+  writeTokenFile(file, next);
+  return identity;
+}
+function removeToken(file, peer) {
+  const tokens = readTokens(file);
+  const kept = tokens.filter((t) => t.peer !== peer);
+  if (kept.length === tokens.length) return false;
+  writeTokenFile(file, kept);
+  return true;
+}
+function loadTokenFileVoid(rows) {
+  const table = /* @__PURE__ */ new Map();
+  const peers = /* @__PURE__ */ new Set();
+  for (const { token, peer, role, owner } of rows) {
+    if (!TOKEN_PATTERN.test(token)) throw new Error(`invalid token for peer '${peer}'`);
+    if (!PEER_ID_PATTERN.test(peer) || peer === "all") throw new Error(`invalid peer id '${peer}'`);
+    if (role !== "agent" && role !== "manager") throw new Error(`invalid role '${role}'`);
+    if (table.has(token)) throw new Error("duplicate token");
+    if (peers.has(peer)) throw new Error(`duplicate peer '${peer}'`);
+    table.set(token, { peer, role, ...owner !== void 0 && owner !== "" ? { owner } : {} });
+    peers.add(peer);
+  }
+}
 
 // src/hub-tools.ts
 var DEFAULT_WAIT_MS = 3e4;
 function present(message) {
-  const { ref, ...rest } = message;
+  const { ref, channel, ...rest } = message;
   return {
     ...rest,
     ...ref !== void 0 ? { ref } : {},
+    ...channel !== void 0 ? { channel } : {},
     content: decodeContent(message.kind, message.content)
   };
 }
@@ -660,13 +1118,26 @@ 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);
+  const tokenPeer = registry.tokenFor(sessionId)?.peer;
+  const peerId = tokenPeer === ANON_JOIN_PEER ? `join-${sanitizePeerId(clientName ?? "agent")}-${Math.random().toString(36).slice(2, 6)}` : tokenPeer ?? sanitizePeerId(clientName ?? "agent");
+  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;
@@ -679,6 +1150,38 @@ function livePeersFor(registry) {
   }
   return live;
 }
+function rosterFor(hub, registry) {
+  const status = hub.status(livePeersFor(registry));
+  const peerIps = /* @__PURE__ */ new Map();
+  const peerAnon = /* @__PURE__ */ new Map();
+  for (const [session, peer] of registry.peerBindings) {
+    const ip = registry.sessionIps.get(session);
+    if (ip !== void 0) {
+      const list = peerIps.get(peer) ?? [];
+      if (!list.includes(ip)) list.push(ip);
+      peerIps.set(peer, list);
+    }
+    const identity = registry.tokenFor(session);
+    if (identity?.anonymous === true) peerAnon.set(peer, true);
+  }
+  return status.peers.map((peer) => {
+    const profile = hub.profileOf(peer.id);
+    const alias = profile?.alias;
+    const clientName = profile?.clientName;
+    const clientVersion = profile?.clientVersion;
+    const ips = peerIps.get(peer.id);
+    return {
+      id: peer.id,
+      ...alias !== void 0 ? { alias } : {},
+      ...clientName !== void 0 ? { clientName } : {},
+      ...clientVersion !== void 0 ? { clientVersion } : {},
+      ...peerAnon.get(peer.id) === true ? { anonymous: true } : {},
+      ...ips !== void 0 && ips.length > 0 ? { clientIps: ips } : {},
+      connected: peer.connected,
+      lastSeenMs: peer.lastSeenMs
+    };
+  });
+}
 function hubTools(hub, registry, options) {
   const schema = (properties, required = []) => ({
     type: "object",
@@ -708,6 +1211,7 @@ function hubTools(hub, registry, options) {
     from: message.from,
     to: message.to,
     kind: message.kind,
+    ...message.channel !== void 0 ? { channel: message.channel } : {},
     ts: message.ts
   });
   const presentWait = (result) => result.type === "timeout" ? result : { type: "message", message: present(result.message) };
@@ -722,6 +1226,13 @@ function hubTools(hub, registry, options) {
     }
     return herdr;
   };
+  const requireManager = (peer, action, sessionId) => {
+    if (registry.tokenFor(sessionId)?.role === "manager") return;
+    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));
@@ -734,42 +1245,112 @@ 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));
+        const tokenPeer = registry.tokenFor(sessionId)?.peer;
+        if (tokenPeer !== void 0 && peerId !== tokenPeer) {
+          throw new Error(`your identity is bound to your access token ('${tokenPeer}') \u2014 ask a hub manager to rename you`);
+        }
         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 };
+        }
+        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}'`, sessionId);
+        if (!hub.has(target)) {
+          return { ok: true, peerId: null, kicked: false };
         }
-        registry.suppressAuto(sessionId);
-        return { ok: true, peerId: peer ?? null };
+        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, sessionId) => {
+        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}'`, sessionId);
+        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.',
@@ -840,23 +1421,106 @@ 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).") }),
-      handler: wrap(true, async (args, peer) => {
+      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, sessionId) => {
         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`}`, sessionId);
+        }
+        if (args.channel !== void 0) {
+          const groupId = String(args.channel);
+          const group = hub.groupOf(groupId);
+          if (group === void 0) throw new Error(`unknown group: ${groupId}`);
+          if (!group.members.includes(peer)) requireManager(peer, `reading group '${groupId}' history`, sessionId);
+          return { messages: hub.historyChannel(groupId, limit).map(present) };
+        }
+        const messages = target === BROADCAST ? hub.historyAll(limit) : hub.history(target, limit);
         return { messages: messages.map(present) };
       })
     },
+    // ---- group tools (group channel) ---------------------------------------------
+    // A group routes one message to several members; the message carries
+    // channel = group id. Offline members are skipped (they read history) —
+    // unlike direct sends, which fail on unknown recipients.
+    {
+      name: "bridge_group_create",
+      description: "Create a group channel. You become a member automatically; `members` lists additional peerIds (each must be registered). Members exchange messages via bridge_group_send; anyone in the group reads its history with bridge_history { channel }. Use bridge_group_delete to remove (creator or manager).",
+      inputSchema: schema(
+        {
+          group: str("Unique group id: letters/digits/._:- , 1-64 chars."),
+          name: optStr("Optional display name."),
+          members: { type: "array", items: { type: "string" }, description: "Member peerIds (you are added automatically; duplicates ignored)." }
+        },
+        ["group"]
+      ),
+      handler: wrap(true, async (args, peer) => {
+        const groupId = String(args.group);
+        const members = Array.isArray(args.members) ? args.members.map(String) : [];
+        const group = hub.createGroup(groupId, members, peer, args.name === void 0 ? void 0 : String(args.name));
+        return { ok: true, group: { id: group.id, ...group.name !== void 0 ? { name: group.name } : {}, members: group.members, createdBy: group.createdBy } };
+      })
+    },
+    {
+      name: "bridge_group_send",
+      description: "Send a chat message to every member of a group channel except yourself. Offline members are skipped (they catch up via bridge_history { channel }). You must be a member.",
+      inputSchema: schema({ group: str("Group id from bridge_group_create / bridge_group_list."), message: str("The message text.") }, ["group", "message"]),
+      handler: wrap(true, async (args, peer) => receipt(hub.sendToGroup(peer, String(args.group), String(args.message))))
+    },
+    {
+      name: "bridge_group_list",
+      description: "List every group channel with its members and creator.",
+      inputSchema: schema({}),
+      handler: wrap(true, async () => ({ groups: hub.allGroups() }))
+    },
+    {
+      name: "bridge_group_delete",
+      description: "Delete a group channel (history rows are kept). The creator or a hub manager may delete.",
+      inputSchema: schema({ group: str("Group id to delete.") }, ["group"]),
+      handler: wrap(true, async (args, peer, sessionId) => {
+        const groupId = String(args.group);
+        const group = hub.groupOf(groupId);
+        if (group === void 0) throw new Error(`unknown group: ${groupId}`);
+        if (group.createdBy !== peer) requireManager(peer, `deleting group '${groupId}'`, sessionId);
+        hub.deleteGroup(groupId);
+        return { ok: true, group: groupId };
+      })
+    },
+    {
+      name: "bridge_group_add_member",
+      description: "Add a registered peer to a group channel; the new member can then send to it and read its history. The creator or a hub manager may add.",
+      inputSchema: schema({ group: str("Group id from bridge_group_create / bridge_group_list."), member: str("peerId of the new member.") }, ["group", "member"]),
+      handler: wrap(true, async (args, peer, sessionId) => {
+        const groupId = String(args.group);
+        const member = String(args.member);
+        const group = hub.groupOf(groupId);
+        if (group === void 0) throw new Error(`unknown group: ${groupId}`);
+        if (group.createdBy !== peer) requireManager(peer, `adding a member to group '${groupId}'`, sessionId);
+        const updated = hub.addGroupMember(groupId, member);
+        return { ok: true, group: { id: updated.id, members: updated.members } };
+      })
+    },
+    {
+      name: "bridge_group_remove_member",
+      description: "Remove a member from a group channel; they stop receiving its messages (history rows are kept). The creator or a hub manager may remove; the creator itself cannot be removed.",
+      inputSchema: schema({ group: str("Group id from bridge_group_create / bridge_group_list."), member: str("peerId to remove.") }, ["group", "member"]),
+      handler: wrap(true, async (args, peer, sessionId) => {
+        const groupId = String(args.group);
+        const member = String(args.member);
+        const group = hub.groupOf(groupId);
+        if (group === void 0) throw new Error(`unknown group: ${groupId}`);
+        if (group.createdBy !== peer) requireManager(peer, `removing a member from group '${groupId}'`, sessionId);
+        const updated = hub.removeGroupMember(groupId, member);
+        return { ok: true, group: { id: updated.id, members: updated.members } };
+      })
+    },
     // ---- herdr control tools ------------------------------------------
     // These type into real agent terminals via the herdr runtime. They are
     // gated by checkControl and documented as physical input: unlike
@@ -1059,6 +1723,16 @@ function hubTools(hub, registry, options) {
 
 // src/mcp-server.ts
 import { randomUUID as randomUUID2 } from "node:crypto";
+import { readFileSync as readFileSync2 } from "node:fs";
+var ADMIN_PATH = "/admin";
+var ADMIN_API_PATH = "/admin/api";
+var adminPageCache;
+function adminPage() {
+  if (adminPageCache === void 0) {
+    adminPageCache = readFileSync2(new URL("../assets/admin.html", import.meta.url), "utf8");
+  }
+  return adminPageCache;
+}
 var SUPPORTED_VERSIONS = ["2025-06-18", "2025-03-26", "2024-11-05"];
 var LATEST_VERSION = SUPPORTED_VERSIONS[0];
 var MAX_BODY_BYTES = 1048576;
@@ -1099,15 +1773,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();
@@ -1123,8 +1805,24 @@ var SessionRegistry = class {
   isSuppressed(sessionId) {
     return sessionId !== void 0 && this.suppressedAuto.has(sessionId);
   }
+  /** Session → client IP (remote mode: the admin roster shows where a peer
+   * connects from, so the operator can tell Zhang San's kimi-code from Li Si's). */
+  sessionIps = /* @__PURE__ */ new Map();
   /** Sessions with a live SSE stream (server→client channel). */
   liveStreams = /* @__PURE__ */ new Set();
+  /** Session → token identity (remote auth mode only; see src/auth.ts).
+   * The TOKEN, not the client-reported name, decides the peer id, so two
+   * users running the same client get distinct peers. */
+  tokenBindings = /* @__PURE__ */ new Map();
+  /** Bind a session to its token identity (at initialize / SSE open). */
+  bindToken(sessionId, identity) {
+    this.tokenBindings.set(sessionId, identity);
+  }
+  /** Token identity bound to a session, if remote auth is in use. */
+  tokenFor(sessionId) {
+    if (sessionId === void 0) return void 0;
+    return this.tokenBindings.get(sessionId);
+  }
   /** Mark a session's SSE stream open (server→client channel alive). */
   markSseOpen(sessionId) {
     this.liveStreams.add(sessionId);
@@ -1137,11 +1835,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);
+        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) this.peerBindings.delete(sessionId);
+      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) {
@@ -1155,18 +1881,29 @@ var SessionRegistry = class {
 var McpStreamableHttpServer = class {
   constructor(tools, info, registry, log = () => {
   }, onInitialize = () => {
-  }) {
+  }, authenticate, adminApi) {
     this.tools = tools;
     this.info = info;
     this.registry = registry;
     this.log = log;
     this.onInitialize = onInitialize;
+    this.authenticate = authenticate;
+    this.adminApi = adminApi;
   }
   sseStreams = /* @__PURE__ */ new Map();
   /** Attach request handling for `path` (e.g. `/mcp`) to an http server. */
   attach(server, path2) {
     server.on("request", (req, res) => {
       const url = new URL(req.url ?? "/", "http://localhost");
+      if (url.pathname === ADMIN_PATH && req.method === "GET") {
+        res.writeHead(200, { "Content-Type": "text/html; charset=utf-8", "Cache-Control": "no-cache" });
+        res.end(adminPage());
+        return;
+      }
+      if (url.pathname.startsWith(ADMIN_API_PATH) && this.adminApi !== void 0) {
+        void this.handleAdminApi(req, res, url);
+        return;
+      }
       if (url.pathname !== path2) {
         res.writeHead(404, { "Content-Type": "application/json" }).end(JSON.stringify({ error: "not found" }));
         return;
@@ -1191,8 +1928,39 @@ 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) {
+    if (this.authenticate !== void 0 && this.authenticate(req) === void 0) {
+      res.writeHead(401, { ...corsHeaders(), "Content-Type": "application/json; charset=utf-8" });
+      res.end(JSON.stringify({ error: "unauthorized: missing or invalid bearer token" }));
+      return;
+    }
     const sessionId = this.registry.ensureSession(this.registry.sessionIdFor(req));
+    const identity = this.authenticate?.(req);
+    if (identity !== void 0) this.registry.bindToken(sessionId, identity);
     res.writeHead(200, {
       ...corsHeaders(),
       "Content-Type": "text/event-stream; charset=utf-8",
@@ -1208,7 +1976,79 @@ var McpStreamableHttpServer = class {
       this.registry.markSseClosed(sessionId);
     });
   }
+  /** Reject a request without a valid token (remote auth mode). */
+  unauthorized(res, id, why) {
+    res.writeHead(401, { ...corsHeaders(), "Content-Type": "application/json; charset=utf-8" });
+    res.end(JSON.stringify({ jsonrpc: "2.0", id, error: { code: -32001, message: `unauthorized: ${why}` } }));
+  }
+  /** Management API for the bundled admin page: issue/revoke tokens and list
+   * them. Like everything else, each call is authenticated by `authenticate`
+   * and must resolve to a MANAGER role — an agent token gets 403. */
+  async handleAdminApi(req, res, url) {
+    const respond = (status, body) => {
+      res.writeHead(status, { ...corsHeaders(), "Content-Type": "application/json; charset=utf-8" });
+      res.end(JSON.stringify(body));
+    };
+    const identity = this.authenticate?.(req);
+    if (identity === void 0) {
+      respond(401, { error: "unauthorized: manager token required" });
+      return;
+    }
+    if (identity.role !== "manager") {
+      respond(403, { error: "forbidden: this API needs a manager-role token" });
+      return;
+    }
+    const api = this.adminApi;
+    const seg = url.pathname.slice(ADMIN_API_PATH.length).replace(/^\/+|\/+$/g, "").split("/");
+    if (req.method === "GET" && seg[0] === "tokens") {
+      respond(200, { tokens: api.listTokens(url.searchParams.get("reveal") === "1") });
+      return;
+    }
+    if (req.method === "POST" && seg[0] === "tokens" && seg[1] === "add") {
+      let input;
+      try {
+        input = JSON.parse((await readBody(req)).toString("utf8"));
+      } catch (error) {
+        respond(400, { error: `bad json: ${error.message}` });
+        return;
+      }
+      try {
+        const created = api.addToken({
+          peer: String(input.peer ?? ""),
+          role: String(input.role ?? "agent"),
+          owner: input.owner === void 0 ? void 0 : String(input.owner)
+        });
+        respond(200, { created });
+      } catch (error) {
+        respond(400, { error: error.message });
+      }
+      return;
+    }
+    if (req.method === "DELETE" && seg[0] === "tokens" && seg[1] === "remove" && seg[2] !== void 0) {
+      respond(200, { removed: api.removeToken(decodeURIComponent(seg[2])) });
+      return;
+    }
+    respond(404, { error: "not found" });
+  }
   async handlePost(req, res) {
+    let authIdentity;
+    if (this.authenticate !== void 0) {
+      authIdentity = this.authenticate(req);
+      if (authIdentity === void 0) {
+        this.unauthorized(res, null, "missing or invalid bearer token");
+        return;
+      }
+      const existingSession = this.registry.sessionIdFor(req);
+      const bound = existingSession === void 0 ? void 0 : this.registry.tokenFor(existingSession);
+      const bothAnonymous = bound?.anonymous === true && authIdentity.anonymous === true;
+      if (bound !== void 0 && !bothAnonymous && (bound.peer !== authIdentity.peer || bound.role !== authIdentity.role)) {
+        this.unauthorized(res, null, "token does not match this session");
+        return;
+      }
+      if (existingSession !== void 0 && bound === void 0 && !authIdentity.anonymous) {
+        this.registry.bindToken(existingSession, authIdentity);
+      }
+    }
     let body;
     try {
       body = await readBody(req);
@@ -1229,12 +2069,13 @@ var McpStreamableHttpServer = class {
     }
     const id = message.id ?? null;
     const sessionId = this.registry.sessionIdFor(req);
+    if (sessionId !== void 0) this.registry.sessionIps.set(sessionId, clientIp(req));
     if (id === null) {
       res.writeHead(202, { ...corsHeaders(), "Content-Length": "0" }).end();
       return;
     }
     try {
-      const { result, extraHeaders } = await this.dispatch(message, sessionId);
+      const { result, extraHeaders } = await this.dispatch(message, sessionId, authIdentity);
       res.writeHead(200, {
         ...corsHeaders(),
         "Content-Type": "application/json; charset=utf-8",
@@ -1247,17 +2088,21 @@ var McpStreamableHttpServer = class {
       this.jsonRpcError(res, id, code, error.message, void 0, messageProtocolVersion(req));
     }
   }
-  async dispatch(message, sessionId) {
+  async dispatch(message, sessionId, authIdentity) {
     const method = message.method ?? "";
     switch (method) {
       case "initialize": {
         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);
+        if (authIdentity !== void 0) {
+          this.registry.bindToken(newSessionId, authIdentity);
+        }
+        this.onInitialize(newSessionId, clientName, clientVersion);
         const requested = message.params?.protocolVersion;
         const protocolVersion = typeof requested === "string" && SUPPORTED_VERSIONS.includes(requested) ? requested : LATEST_VERSION;
         return {
@@ -1320,6 +2165,14 @@ function rpcError(code, message) {
 function messageProtocolVersion(req) {
   return req.headers["mcp-protocol-version"] ?? LATEST_VERSION;
 }
+function clientIp(req) {
+  const forwarded = req.headers["x-forwarded-for"];
+  const raw = Array.isArray(forwarded) ? forwarded[0] : forwarded;
+  if (typeof raw === "string" && raw.trim() !== "") {
+    return raw.split(",")[0].trim();
+  }
+  return (req.socket.remoteAddress ?? "?").replace(/^::ffff:/, "");
+}
 function corsHeaders() {
   return {
     "Access-Control-Allow-Origin": "*",
@@ -1345,9 +2198,149 @@ function readBody(req) {
   });
 }
 
+// src/persist.ts
+import { DatabaseSync } from "node:sqlite";
+var KIND_NAMES = ["chat", "task", "notice", "ack"];
+function messageToRow(message) {
+  return [message.id, message.from, message.to, message.kind, message.content, message.ref ?? null, message.channel ?? null, message.ts];
+}
+function rowToMessage(row) {
+  const id = row.id;
+  const from = row.from_peer;
+  const to = row.to_peer;
+  const kind = row.kind;
+  const content = row.content;
+  const ts = row.ts;
+  if (typeof id !== "string" || typeof from !== "string" || typeof to !== "string" || typeof content !== "string" || typeof ts !== "number") return void 0;
+  if (!KIND_NAMES.includes(kind)) return void 0;
+  return {
+    id,
+    from,
+    to,
+    kind,
+    content,
+    ...typeof row.ref === "string" && row.ref !== "" ? { ref: row.ref } : {},
+    ...typeof row.channel === "string" && row.channel !== "" ? { channel: row.channel } : {},
+    ts
+  };
+}
+var SQLiteStateStore = class {
+  constructor(file, historyLimit, log) {
+    this.historyLimit = historyLimit;
+    this.db = new DatabaseSync(file);
+    this.db.exec("PRAGMA journal_mode = WAL");
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS profiles (
+        id TEXT PRIMARY KEY, alias TEXT, client_name TEXT, client_version TEXT, registered_at INTEGER
+      );
+      CREATE TABLE IF NOT EXISTS messages (
+        seq INTEGER PRIMARY KEY AUTOINCREMENT, id TEXT NOT NULL, from_peer TEXT NOT NULL,
+        to_peer TEXT NOT NULL, kind TEXT NOT NULL, content TEXT NOT NULL, ref TEXT, channel TEXT, ts INTEGER NOT NULL
+      );
+      CREATE TABLE IF NOT EXISTS mailboxes (
+        peer TEXT NOT NULL, seq INTEGER PRIMARY KEY AUTOINCREMENT, id TEXT NOT NULL, from_peer TEXT NOT NULL,
+        to_peer TEXT NOT NULL, kind TEXT NOT NULL, content TEXT NOT NULL, ref TEXT, channel TEXT, ts INTEGER NOT NULL
+      );
+      CREATE TABLE IF NOT EXISTS groups (
+        id TEXT PRIMARY KEY, name TEXT, members TEXT NOT NULL, created_by TEXT NOT NULL, created_at INTEGER NOT NULL
+      );
+    `);
+    log.warn(`sqlite state open: ${file}`);
+  }
+  db;
+  buffer = [];
+  /** Buffer one history message (called per message via the hub hook). */
+  appendMessage(message) {
+    this.buffer.push(message);
+  }
+  /** Insert buffered messages and re-snapshot mailboxes/profiles/groups. */
+  flush(snapshot) {
+    const insert = this.db.prepare(
+      "INSERT INTO messages (id, from_peer, to_peer, kind, content, ref, channel, ts) VALUES (?, ?, ?, ?, ?, ?, ?, ?)"
+    );
+    for (const message of this.buffer.splice(0, this.buffer.length)) {
+      insert.run(...messageToRow(message));
+    }
+    this.db.exec("DELETE FROM mailboxes");
+    const insertMail = this.db.prepare(
+      "INSERT INTO mailboxes (peer, id, from_peer, to_peer, kind, content, ref, channel, ts) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)"
+    );
+    for (const [peer, queue] of Object.entries(snapshot.mailboxes)) {
+      for (const message of queue) insertMail.run(peer, ...messageToRow(message));
+    }
+    this.db.exec("DELETE FROM profiles");
+    const insertProfile = this.db.prepare(
+      "INSERT INTO profiles (id, alias, client_name, client_version, registered_at) VALUES (?, ?, ?, ?, ?)"
+    );
+    for (const profile of snapshot.profiles) {
+      insertProfile.run(profile.id, profile.alias ?? null, profile.clientName ?? null, profile.clientVersion ?? null, profile.registeredAt);
+    }
+    this.db.exec("DELETE FROM groups");
+    const insertGroup = this.db.prepare(
+      "INSERT INTO groups (id, name, members, created_by, created_at) VALUES (?, ?, ?, ?, ?)"
+    );
+    for (const group of snapshot.groups) {
+      insertGroup.run(group.id, group.name ?? null, JSON.stringify(group.members), group.createdBy, group.createdAt);
+    }
+    const row = this.db.prepare("SELECT COUNT(*) AS n FROM messages").get();
+    const total = Number(row.n);
+    if (total > this.historyLimit * 2) {
+      this.db.exec(`DELETE FROM messages WHERE seq <= (SELECT MAX(seq) FROM messages) - ${this.historyLimit}`);
+    }
+  }
+  /** Read everything persisted so far (boot restore). */
+  load() {
+    const profiles = [];
+    for (const row of this.db.prepare("SELECT * FROM profiles").all()) {
+      if (typeof row.id !== "string") continue;
+      profiles.push({
+        id: row.id,
+        ...typeof row.alias === "string" && row.alias !== "" ? { alias: row.alias } : {},
+        ...typeof row.client_name === "string" && row.client_name !== "" ? { clientName: row.client_name } : {},
+        ...typeof row.client_version === "string" && row.client_version !== "" ? { clientVersion: row.client_version } : {},
+        registeredAt: typeof row.registered_at === "number" ? row.registered_at : Date.now()
+      });
+    }
+    const messages = [];
+    for (const row of this.db.prepare("SELECT * FROM messages ORDER BY seq").all()) {
+      const message = rowToMessage(row);
+      if (message !== void 0) messages.push(message);
+    }
+    const mailboxes = {};
+    for (const row of this.db.prepare("SELECT * FROM mailboxes ORDER BY seq").all()) {
+      if (typeof row.peer !== "string") continue;
+      const message = rowToMessage(row);
+      if (message === void 0) continue;
+      (mailboxes[row.peer] ??= []).push(message);
+    }
+    const groups = [];
+    for (const row of this.db.prepare("SELECT * FROM groups").all()) {
+      if (typeof row.id !== "string" || typeof row.members !== "string") continue;
+      try {
+        const members = JSON.parse(row.members);
+        if (!Array.isArray(members) || members.length === 0) continue;
+        groups.push({
+          id: row.id,
+          members: members.filter((m) => typeof m === "string"),
+          createdBy: typeof row.created_by === "string" ? row.created_by : "",
+          createdAt: typeof row.created_at === "number" ? row.created_at : Date.now(),
+          ...typeof row.name === "string" && row.name !== "" ? { name: row.name } : {}
+        });
+      } catch {
+      }
+    }
+    return { profiles, messages, mailboxes, groups };
+  }
+  /** Final flush + close (hub shutdown). */
+  close(snapshot) {
+    this.flush(snapshot);
+    this.db.close();
+  }
+};
+
 // src/index.ts
 var SERVER_NAME = "agent-comm-hub";
-var SERVER_VERSION = "0.5.0";
+var SERVER_VERSION = "0.7.0";
 var DEFAULT_HOST = "127.0.0.1";
 var DEFAULT_PORT = 18764;
 var DEFAULT_PATH = "/mcp";
@@ -1363,11 +2356,107 @@ 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 authTokensAdmin(file, reloadAuth) {
+  if (file === void 0) return void 0;
+  return {
+    listTokens: (reveal) => readTokens(file).map((r) => ({
+      token: reveal ? r.token : `${r.token.slice(0, 6)}\u2026${r.token.slice(-4)}`,
+      peer: r.peer,
+      role: r.role,
+      ...r.owner !== void 0 ? { owner: r.owner } : {}
+    })),
+    addToken: (input) => {
+      const row = addToken(file, { peer: input.peer, role: input.role, owner: input.owner });
+      reloadAuth?.();
+      return { token: row.token, peer: row.peer, role: row.role, ...row.owner !== void 0 ? { owner: row.owner } : {} };
+    },
+    removeToken: (peer) => {
+      const ok = removeToken(file, peer);
+      if (ok) reloadAuth?.();
+      return ok;
+    },
+    reloadAuth: () => reloadAuth?.()
+  };
+}
+function writeRosterFile(file, profiles) {
+  mkdirSync2(dirname2(file), { recursive: true });
+  const tmp = `${file}.tmp`;
+  writeFileSync2(tmp, JSON.stringify({ version: 1, savedAt: Date.now(), profiles }), "utf8");
+  renameSync2(tmp, file);
+}
 function startHub(config = {}, log = console) {
   const overrides = Object.fromEntries(Object.entries(config).filter(([, value]) => value !== void 0));
   const resolved = { ...DEFAULT_CONFIG, ...overrides };
+  let mcp;
+  let dbStore;
+  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) }
+    });
+  };
+  const managerSet = resolved.managerPeers === "all" ? void 0 : new Set(resolved.managerPeers);
+  const pushRelay = (message) => {
+    const managers = [];
+    for (const sessionId of registry.liveSessions()) {
+      const peer = registry.peerFor(sessionId);
+      if (peer === void 0) continue;
+      if (registry.tokenFor(sessionId)?.role === "manager" || managerSet === void 0 || managerSet.has(peer)) {
+        managers.push(sessionId);
+      }
+    }
+    if (managers.length > 0) {
+      mcp.notify(managers, "notifications/message", {
+        level: "info",
+        logger: "bridge",
+        data: { event: "message", message: present(message) }
+      });
+    }
+  };
+  let saveTimer;
+  let rosterDirty = false;
+  let dbDirty = false;
+  const flushSaves = () => {
+    if (rosterDirty && resolved.stateFile !== void 0) {
+      rosterDirty = false;
+      try {
+        writeRosterFile(resolved.stateFile, hub.exportProfiles());
+      } catch (error) {
+        log.warn(`roster save failed: ${error.message}`);
+      }
+    }
+    if (dbDirty && dbStore !== void 0) {
+      dbDirty = false;
+      try {
+        dbStore.flush({ mailboxes: hub.exportMailboxes(), profiles: hub.exportProfiles(), groups: hub.exportGroups() });
+      } catch (error) {
+        log.warn(`sqlite flush failed: ${error.message}`);
+      }
+    }
+  };
+  const scheduleSave = () => {
+    if (resolved.stateFile === void 0 && dbStore === void 0) return;
+    if (saveTimer !== void 0) return;
+    saveTimer = setTimeout(() => {
+      saveTimer = void 0;
+      flushSaves();
+    }, 500);
+    saveTimer.unref?.();
+  };
   const hub = new AgentHub({
     maxQueue: resolved.maxQueue,
     historyLimit: resolved.historyLimit,
@@ -1375,10 +2464,94 @@ function startHub(config = {}, log = console) {
     connectedWindowMs: resolved.connectedWindowMs,
     peerIdleTimeoutMs: resolved.peerIdleTimeoutMs,
     onPeerGc: (peerId) => registry.unbindPeerId(peerId),
+    // Remote persistence: buffer every history append; re-snapshot when a
+    // mailbox is consumed so drained messages cannot resurrect on restart.
+    // Also relay every message to manager sessions (the relay stream view) —
+    // best-effort; a notification failure must never break routing.
+    onMessage: (message) => {
+      if (dbStore !== void 0) {
+        dbStore.appendMessage(message);
+        dbDirty = true;
+      }
+      try {
+        pushRelay(message);
+      } catch (error) {
+        log.warn(`relay notification failed: ${error.message}`);
+      }
+    },
+    onMailboxesChanged: () => {
+      if (dbStore === void 0) return;
+      dbDirty = true;
+    },
+    onGroupsChanged: () => {
+      if (dbStore === void 0) return;
+      dbDirty = true;
+      scheduleSave();
+    },
     // 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) {
+        log.warn(`peers_changed notification failed: ${error.message}`);
+      }
+      rosterDirty = true;
+      dbDirty = true;
+      scheduleSave();
+    },
+    onQueued: (message, target) => {
+      try {
+        pushQueued(message, target);
+      } catch (error) {
+        log.warn(`message notification failed: ${error.message}`);
+      }
+    }
   });
   const registry = new SessionRegistry();
+  if (resolved.db !== void 0) {
+    try {
+      dbStore = new SQLiteStateStore(resolved.db, resolved.historyLimit, log);
+      const state = dbStore.load();
+      const importedProfiles = hub.importProfiles(state.profiles);
+      if (state.profiles.length === 0 && resolved.stateFile !== void 0) {
+        try {
+          const legacy = JSON.parse(readFileSync3(resolved.stateFile, "utf8"));
+          const migrated = hub.importProfiles(legacy.profiles);
+          if (migrated > 0) log.info(`roster migrated: ${migrated} profile(s) from ${resolved.stateFile} into ${resolved.db}`);
+        } catch (error) {
+          if (error.code !== "ENOENT") {
+            log.warn(`legacy roster import failed: ${error.message}`);
+          }
+        }
+      } else if (importedProfiles > 0) {
+        log.info(`roster restored: ${importedProfiles} profile(s) from ${resolved.db}`);
+      }
+      const restoredMessages = hub.importHistory(state.messages);
+      const restoredQueued = hub.importMailboxes(state.mailboxes);
+      const restoredGroups = hub.importGroups(state.groups);
+      if (restoredMessages + restoredQueued + restoredGroups > 0) {
+        log.info(`state restored from ${resolved.db}: ${restoredMessages} message(s), ${restoredQueued} queued, ${restoredGroups} group(s)`);
+        dbDirty = true;
+      }
+    } catch (error) {
+      dbStore = void 0;
+      log.warn(`sqlite state unavailable (${error.message}); running memory-only`);
+    }
+  }
+  if (dbStore === void 0 && resolved.stateFile !== void 0) {
+    try {
+      const parsed = JSON.parse(readFileSync3(resolved.stateFile, "utf8"));
+      const imported = hub.importProfiles(parsed.profiles);
+      if (imported > 0) log.info(`roster restored: ${imported} profile(s) from ${resolved.stateFile}`);
+    } catch (error) {
+      if (error.code !== "ENOENT") {
+        log.warn(`roster load failed: ${error.message}`);
+      }
+    }
+  }
   const herdr = new HerdrCtl({
     bin: resolved.herdrBin,
     baseArgs: resolved.herdrBaseArgs,
@@ -1386,24 +2559,58 @@ function startHub(config = {}, log = console) {
     socketPath: resolved.herdrSocketPath,
     sendRequest: resolved.herdrSendRequest
   });
-  const mcp = new McpStreamableHttpServer(
+  let auth;
+  let authReload;
+  if (resolved.authTokens !== void 0) {
+    const table = watchTokenFile(resolved.authTokens, {
+      info: (message) => log.info(message),
+      warn: (message) => log.warn(message)
+    });
+    authReload = table.reload;
+    auth = (req) => {
+      const presented = bearerFromHeaders(req.headers);
+      if (presented !== void 0) return table.authenticate(presented);
+      if (resolved.allowJoin === true) {
+        return { peer: ANON_JOIN_PEER, role: "agent", anonymous: true };
+      }
+      return void 0;
+    };
+  } else if (resolved.allowJoin === true) {
+    auth = (req) => ({ peer: ANON_JOIN_PEER, role: "agent", anonymous: true });
+  }
+  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) => log.warn(message),
-    (sessionId, clientName) => {
+    (sessionId, clientName, clientVersion) => {
       try {
-        const peer = autoRegisterPeer(hub, registry, sessionId, clientName);
-        if (peer !== void 0) log.info(`peer joined: ${peer}`);
+        const identity = registry.tokenFor(sessionId);
+        if (identity?.anonymous === true && identity.peer === ANON_JOIN_PEER) {
+          let candidate = `join-${sanitizePeerId(clientName ?? "agent")}-${randomBytes2(2).toString("hex")}`;
+          while (hub.has(candidate)) {
+            candidate = `join-${sanitizePeerId(clientName ?? "agent")}-${randomBytes2(2).toString("hex")}`;
+          }
+          registry.bindToken(sessionId, { ...identity, peer: candidate });
+        }
+        const peer = autoRegisterPeer(hub, registry, sessionId, clientName, clientVersion);
+        if (peer !== void 0) {
+          const owner = registry.tokenFor(sessionId)?.owner;
+          const anon = registry.tokenFor(sessionId)?.anonymous === true ? " (anonymous join)" : "";
+          log.info(`peer joined: ${peer}${owner !== void 0 ? ` (owner: ${owner})` : ""}${anon}`);
+        }
       } catch (error) {
         log.warn(`auto-register failed: ${error.message}`);
       }
-    }
+    },
+    auth,
+    authTokensAdmin(resolved.authTokens, authReload)
   );
   const server = createServer();
   mcp.attach(server, resolved.path);
@@ -1419,6 +2626,19 @@ function startHub(config = {}, log = console) {
     close: () => {
       hub.dispose();
       mcp.close();
+      if (saveTimer !== void 0) {
+        clearTimeout(saveTimer);
+        saveTimer = void 0;
+      }
+      flushSaves();
+      if (dbStore !== void 0) {
+        try {
+          dbStore.close({ mailboxes: hub.exportMailboxes(), profiles: hub.exportProfiles(), groups: hub.exportGroups() });
+        } catch (error) {
+          log.warn(`sqlite close failed: ${error.message}`);
+        }
+        dbStore = void 0;
+      }
       server.closeAllConnections?.();
       server.close();
     }
@@ -1438,12 +2658,21 @@ export {
   PEER_ID_PATTERN,
   SERVER_NAME,
   SERVER_VERSION,
+  SQLiteStateStore,
   SessionRegistry,
+  addToken,
   autoRegisterPeer,
   decodeContent,
   encodeContent,
+  generateToken,
   hubTools,
+  loadTokenFile,
   present,
+  readTokens,
+  removeToken,
+  sanitizeAlias,
   sanitizePeerId,
-  startHub
+  startHub,
+  tokenTable,
+  watchTokenFile
 };