agent-comm-hub 0.5.0 → 0.7.0

package/lib/cli.js

@@ -2,6 +2,9 @@
 
 // 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";
@@ -418,6 +421,8 @@ function socketSend(socketPath, method, params) {
 import { randomUUID } from "node:crypto";
 
 // src/protocol.ts
+var KINDS = ["chat", "task", "notice", "ack"];
+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 +435,7 @@ function decodeContent(kind, content) {
 }
 
 // src/hub.ts
+var MAX_PROFILES = 512;
 var AgentHub = class {
   constructor(options) {
     this.options = options;
@@ -444,6 +450,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() {
@@ -463,14 +473,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);
@@ -480,6 +503,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());
@@ -507,9 +634,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).
@@ -518,21 +656,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
     };
@@ -541,7 +848,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;
   }
   /**
@@ -624,12 +931,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) {
@@ -642,14 +952,159 @@ 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 watchTokenFile(file, log2) {
+  let table = loadTokenFile(file);
+  const reload = () => {
+    try {
+      const next = loadTokenFile(file);
+      table = next;
+      log2.info(`auth tokens reloaded: ${table.size} entr(ies)`);
+    } catch (error) {
+      log2.warn(`auth token reload ignored, keeping previous table: ${error.message}`);
+    }
+  };
+  log2.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)
   };
 }
@@ -657,13 +1112,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;
@@ -676,6 +1144,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",
@@ -705,6 +1205,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) };
@@ -719,6 +1220,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));
@@ -731,42 +1239,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.',
@@ -837,23 +1415,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
@@ -1056,6 +1717,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;
@@ -1096,15 +1767,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();
@@ -1120,8 +1799,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);
@@ -1134,11 +1829,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) {
@@ -1152,18 +1875,29 @@ var SessionRegistry = class {
 var McpStreamableHttpServer = class {
   constructor(tools, info, registry, log2 = () => {
   }, onInitialize = () => {
-  }) {
+  }, authenticate, adminApi) {
     this.tools = tools;
     this.info = info;
     this.registry = registry;
     this.log = log2;
     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;
@@ -1188,8 +1922,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",
@@ -1205,7 +1970,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);
@@ -1226,12 +2063,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",
@@ -1244,17 +2082,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 {
@@ -1317,6 +2159,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": "*",
@@ -1342,9 +2192,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, log2) {
+    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
+      );
+    `);
+    log2.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";
@@ -1360,11 +2350,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 = {}, log2 = 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) {
+        log2.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) {
+        log2.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,
@@ -1372,10 +2458,94 @@ function startHub(config = {}, log2 = 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) {
+        log2.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) {
+        log2.warn(`peers_changed notification failed: ${error.message}`);
+      }
+      rosterDirty = true;
+      dbDirty = true;
+      scheduleSave();
+    },
+    onQueued: (message, target) => {
+      try {
+        pushQueued(message, target);
+      } catch (error) {
+        log2.warn(`message notification failed: ${error.message}`);
+      }
+    }
   });
   const registry = new SessionRegistry();
+  if (resolved.db !== void 0) {
+    try {
+      dbStore = new SQLiteStateStore(resolved.db, resolved.historyLimit, log2);
+      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) log2.info(`roster migrated: ${migrated} profile(s) from ${resolved.stateFile} into ${resolved.db}`);
+        } catch (error) {
+          if (error.code !== "ENOENT") {
+            log2.warn(`legacy roster import failed: ${error.message}`);
+          }
+        }
+      } else if (importedProfiles > 0) {
+        log2.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) {
+        log2.info(`state restored from ${resolved.db}: ${restoredMessages} message(s), ${restoredQueued} queued, ${restoredGroups} group(s)`);
+        dbDirty = true;
+      }
+    } catch (error) {
+      dbStore = void 0;
+      log2.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) 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,24 +2553,58 @@ function startHub(config = {}, log2 = 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) => log2.info(message),
+      warn: (message) => log2.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) => log2.warn(message),
-    (sessionId, clientName) => {
+    (sessionId, clientName, clientVersion) => {
       try {
-        const peer = autoRegisterPeer(hub, registry, sessionId, clientName);
-        if (peer !== void 0) log2.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)" : "";
+          log2.info(`peer joined: ${peer}${owner !== void 0 ? ` (owner: ${owner})` : ""}${anon}`);
+        }
       } catch (error) {
         log2.warn(`auto-register failed: ${error.message}`);
       }
-    }
+    },
+    auth,
+    authTokensAdmin(resolved.authTokens, authReload)
   );
   const server = createServer();
   mcp.attach(server, resolved.path);
@@ -1416,6 +2620,19 @@ function startHub(config = {}, log2 = 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) {
+          log2.warn(`sqlite close failed: ${error.message}`);
+        }
+        dbStore = void 0;
+      }
       server.closeAllConnections?.();
       server.close();
     }
@@ -1424,19 +2641,19 @@ function startHub(config = {}, log2 = console) {
 
 // src/setup.ts
 import { copyFile, mkdir, readFile, writeFile } from "node:fs/promises";
-import { existsSync as existsSync2 } from "node:fs";
+import { existsSync as existsSync3 } from "node:fs";
 import { homedir as homedir2 } from "node:os";
-import { dirname as dirname2, join as join2 } from "node:path";
+import { dirname as dirname4, 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 as existsSync2, readdirSync, accessSync, readFileSync as readFileSync4, constants as fsConstants } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, join, sep } from "node:path";
+import { dirname as dirname3, join, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 function registryFile() {
-  return join(dirname(fileURLToPath(import.meta.url)), "..", "agents", "registry.json");
+  return join(dirname3(fileURLToPath(import.meta.url)), "..", "agents", "registry.json");
 }
 function expandHome(file, home) {
   return file.startsWith("~/") ? join(home, file.slice(2)) : file;
@@ -1448,7 +2665,7 @@ function expandConfigFile(file, home) {
   const prefix = expanded.slice(0, star);
   const suffix = expanded.slice(star + 1);
   const base = prefix.slice(0, prefix.lastIndexOf(sep));
-  if (!existsSync(base)) return [];
+  if (!existsSync2(base)) return [];
   return readdirSync(base, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => join(base, entry.name, suffix));
 }
 function validateRegistry(registry) {
@@ -1492,7 +2709,7 @@ function validateRegistry(registry) {
   }
 }
 function loadRegistry(file = registryFile()) {
-  const registry = JSON.parse(readFileSync(file, "utf8"));
+  const registry = JSON.parse(readFileSync4(file, "utf8"));
   validateRegistry(registry);
   return registry;
 }
@@ -1543,7 +2760,7 @@ function npmFallbackRoots(home, platform) {
   return [
     "/usr/local/lib/node_modules",
     "/usr/lib/node_modules",
-    ...existsSync(join(home, ".nvm", "versions", "node")) ? readdirSync(join(home, ".nvm", "versions", "node")).map((dir) => join(home, ".nvm", "versions", "node", dir, "lib", "node_modules")) : []
+    ...existsSync2(join(home, ".nvm", "versions", "node")) ? readdirSync(join(home, ".nvm", "versions", "node")).map((dir) => join(home, ".nvm", "versions", "node", dir, "lib", "node_modules")) : []
   ];
 }
 function discover(registry, options = {}) {
@@ -1554,15 +2771,15 @@ function discover(registry, options = {}) {
   let npmNames = null;
   if (!options.noNpm) {
     if (options.npmRoot !== void 0 && options.npmRoot !== null) {
-      npmNames = existsSync(options.npmRoot) ? readNpmNames(options.npmRoot) : [];
+      npmNames = existsSync2(options.npmRoot) ? readNpmNames(options.npmRoot) : [];
     } else if (options.npmRoot !== null) {
       const root = npmGlobalRoot(platform);
-      if (root && existsSync(root)) {
+      if (root && existsSync2(root)) {
         npmNames = readNpmNames(root);
       } else {
         npmNames = [];
         for (const fallback of npmFallbackRoots(home, platform)) {
-          if (existsSync(fallback)) {
+          if (existsSync2(fallback)) {
             npmNames = readNpmNames(fallback);
             break;
           }
@@ -1575,7 +2792,7 @@ function discover(registry, options = {}) {
     const configFiles = [];
     for (const config of agent.configs) {
       for (const file of expandConfigFile(config.file, home)) {
-        if (existsSync(file)) {
+        if (existsSync2(file)) {
           configFiles.push(file);
           if (source === "none") source = "config";
         }
@@ -1606,7 +2823,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(dirname4(fileURLToPath2(import.meta.url)), "..", "agents", "SKILL.md");
 }
 function stamp() {
   const now = /* @__PURE__ */ new Date();
@@ -1614,7 +2831,7 @@ function stamp() {
   return `${now.getFullYear()}${pad(now.getMonth() + 1)}${pad(now.getDate())}-${pad(now.getHours())}${pad(now.getMinutes())}${pad(now.getSeconds())}`;
 }
 async function readJson(file) {
-  if (!existsSync2(file)) return null;
+  if (!existsSync3(file)) return null;
   try {
     return JSON.parse(await readFile(file, "utf8"));
   } catch (error) {
@@ -1622,7 +2839,7 @@ async function readJson(file) {
   }
 }
 async function writeJsonNoBom(file, doc) {
-  await mkdir(dirname2(file), { recursive: true });
+  await mkdir(dirname4(file), { recursive: true });
   await writeFile(file, JSON.stringify(doc, null, 2) + "\n", "utf8");
 }
 async function backup(file) {
@@ -1643,7 +2860,7 @@ function resolveSection(doc, section) {
   return node;
 }
 async function mergeJsonServer(file, section, entry, opts) {
-  if (!existsSync2(file)) return "skipped";
+  if (!existsSync3(file)) return "skipped";
   const doc = await readJson(file);
   if (doc === null) return "skipped";
   const servers = resolveSection(doc, section);
@@ -1665,7 +2882,7 @@ async function mergeJsonServer(file, section, entry, opts) {
   return "changed";
 }
 async function mergeTomlSection(file, opts) {
-  if (!existsSync2(file)) return "skipped";
+  if (!existsSync3(file)) return "skipped";
   const text = await readFile(file, "utf8");
   const marker = `[mcp_servers.${opts.serverName}]`;
   const markerRe = new RegExp(`^\\[mcp_servers\\.${escapeRegExp(opts.serverName)}\\]`, "m");
@@ -1690,12 +2907,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
@@ -1703,64 +2921,56 @@ ${DSH_PATCH_MARKER} (installed by \`agent-comm-hub setup\`; undo with \`setup --
 `;
 }
 async function mergeDshPatch(file, opts) {
-  if (!existsSync2(file)) return "skipped";
+  if (!existsSync3(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;
-      }
-    }
-    let end = lines.length;
-    if (entryStart >= 0) {
-      for (let i = entryStart + 1; i < lines.length; i++) {
-        if (/^- /.test(lines[i])) {
-          end = i;
-          break;
-        }
-      }
+  const hubEntryRanges = () => {
+    const tops = [];
+    for (let i = 0; i < lines.length; i++) {
+      if (/^- /.test(lines[i])) tops.push(i);
+    }
+    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 });
+    if (existsSync3(skillDir)) {
+      await mkdir(dirname4(skillDir), { recursive: true });
       await rmRecursive(skillDir);
       log2(`  skill removed: ${skillDir}`);
     }
     return;
   }
-  if (!existsSync2(skillSrc)) {
+  if (!existsSync3(skillSrc)) {
     log2(`  SKILL.md source missing: ${skillSrc} (skipped)`);
     return;
   }
@@ -1846,9 +3056,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 mkdirSync3, readFileSync as readFileSync5, rmSync, writeFileSync as writeFileSync3 } from "node:fs";
 import { homedir as homedir3 } from "node:os";
-import { dirname as dirname3, join as join3 } from "node:path";
+import { dirname as dirname5, 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 +3111,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(dirname5(fileURLToPath3(import.meta.url)), "..", "package.json");
+    const before = JSON.parse(readFileSync5(pkgFile, "utf8")).version ?? "?";
     messages.push(`current version: ${before}`);
     const script = [
       "import { execFileSync } from 'node:child_process'",
@@ -1958,8 +3168,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);
+          mkdirSync3(launcherDir, { recursive: true });
+          writeFileSync3(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 +3208,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);
+          mkdirSync3(unitDir, { recursive: true });
+          writeFileSync3(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 +3262,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);
+          mkdirSync3(launchAgentsDir, { recursive: true });
+          writeFileSync3(plist, plistContent);
           try {
             execFileSync2("launchctl", ["bootstrap", `gui/${uid}`, plist], { encoding: "utf8", windowsHide: true });
           } catch {
@@ -2088,17 +3298,23 @@ WantedBy=default.target
 }
 
 // src/cli.ts
+import { homedir as homedir4 } from "node:os";
+import { join as join4 } from "node:path";
+var STRING_FLAGS = /* @__PURE__ */ new Set(["--host", "--path", "--url", "--server-name", "--agent", "--herdr-bin", "--manager-peers", "--state-file", "--auth-tokens", "--db", "--file", "--role", "--owner", "--token"]);
+var DEFAULT_STATE_FILE = join4(homedir4(), ".agent-comm-hub", "roster.json");
+var DEFAULT_DB = join4(homedir4(), ".agent-comm-hub", "state.db");
+var DEFAULT_AUTH_FILE = join4(homedir4(), ".agent-comm-hub", "tokens.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", "--auth-tokens", "--db", "--file", "--role", "--owner", "--token"]);
   for (let i = 0; i < argv.length; i++) {
     const flag = argv[i];
     if (flag === "--help" || flag === "-h" || flag === "--version" || flag === "-V") {
       args[flag] = true;
       continue;
     }
-    if (flag === "--remove" || flag === "--dry-run") {
+    if (flag === "--remove" || flag === "--dry-run" || flag === "--reveal" || flag === "--allow-join") {
       args[flag] = true;
       continue;
     }
@@ -2137,6 +3353,10 @@ Usage:
   agent-comm-hub update                  self-update from the npm registry
                                            (files updated in place; restart
                                            the hub afterwards)
+  agent-comm-hub auth add <peer> [flags] manage the remote-mode token table
+  agent-comm-hub auth remove <peer>      (add prints the generated token ONCE)
+  agent-comm-hub auth list [--reveal]
+  agent-comm-hub auth gen                print a fresh random token
 
 Hub options:
   --host <addr>            Bind address (default 127.0.0.1)
@@ -2151,6 +3371,34 @@ 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)
+  --auth-tokens <file>       REMOTE MODE: require "Authorization: Bearer <token>"
+                             on every MCP request; each token maps to a fixed
+                             peer id + role (agent|manager). See server/README.md
+                             for the token table format and deployment recipes.
+  --db <path>                REMOTE MODE: SQLite state DB persisting history,
+                             mailboxes, profiles and groups across restarts
+                             (default ~/.agent-comm-hub/state.db; "off" = memory)
+
+Auth options (agent-comm-hub auth <action>):
+  --file <path>              Token table to manage
+                             (default ~/.agent-comm-hub/tokens.json)
+  --role <r>                 auth add: agent | manager (default agent)
+  --owner <name>             auth add: optional owner label
+  --token <t>                auth add: supply your own token instead of
+                             generating one (16-128 chars [A-Za-z0-9._:-])
+  --allow-join               Start the hub in allow-join mode: agents without
+                             a token may connect (LAN/VPN only; keep OFF on
+                             the public internet). Each gets a unique peer id
+                             + source IP shown in the admin roster for you to
+                             claim (rename) or issue a token to.
+  --reveal                   auth list: include the plaintext tokens
 
 Setup options:
   --url <url>              Hub endpoint to register (default http://127.0.0.1:18764/mcp)
@@ -2208,7 +3456,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);
@@ -2234,6 +3483,77 @@ try {
     }
     process.exit(0);
   }
+  if (command === "auth") {
+    const [action, ...authRest] = rest;
+    const splitArgs = (args2) => {
+      const positional = [];
+      const flags = [];
+      for (let i = 0; i < args2.length; i++) {
+        if (args2[i].startsWith("--")) {
+          flags.push(args2[i]);
+          if (STRING_FLAGS.has(args2[i]) && args2[i + 1] !== void 0 && !args2[i + 1].startsWith("--")) flags.push(args2[++i]);
+        } else positional.push(args2[i]);
+      }
+      return { positional, flags };
+    };
+    const file = () => {
+      const { flags } = splitArgs(authRest);
+      return parseArgs(flags)["--file"] ?? DEFAULT_AUTH_FILE;
+    };
+    if (action === "add") {
+      const { positional, flags } = splitArgs(authRest);
+      const args2 = parseArgs(flags);
+      const peerId = positional[0];
+      if (peerId === void 0) {
+        console.error("auth add: missing <peer> \u2014 usage: agent-comm-hub auth add <peer> [--role agent|manager] [--owner name]");
+        process.exit(1);
+      }
+      const role = args2["--role"] ?? "agent";
+      if (role !== "agent" && role !== "manager") {
+        console.error(`auth add: invalid role '${role}' (expected agent | manager)`);
+        process.exit(1);
+      }
+      const row = addToken(file(), {
+        peer: peerId,
+        role,
+        owner: args2["--owner"],
+        token: args2["--token"]
+      });
+      console.log(`token created for ${peerId}${row.owner ? ` (${row.owner})` : ""} [${row.role}]`);
+      console.log(`  ${row.token}`);
+      console.log("The MCP config to pass to that agent (Authorization header) \u2014 not echoed here;");
+      console.log(`Table written to ${file()} (hub hot-reloads; takes effect in ~2s)`);
+      process.exit(0);
+    }
+    if (action === "remove") {
+      const peerId = splitArgs(authRest).positional[0];
+      if (peerId === void 0) {
+        console.error("auth remove: missing <peer>");
+        process.exit(1);
+      }
+      console.log(removeToken(file(), peerId) ? `removed peer ${peerId}` : `peer ${peerId} not found`);
+      process.exit(0);
+    }
+    if (action === "list") {
+      const args2 = parseArgs(splitArgs(authRest).flags);
+      const reveal = args2["--reveal"] === true;
+      const rows = readTokens(file());
+      if (rows.length === 0) {
+        console.log("token table is empty \u2014 add one with: agent-comm-hub auth add <peer>");
+      }
+      for (const row of rows) {
+        const t = reveal ? row.token : row.token.slice(0, 6) + "\u2026" + row.token.slice(-4);
+        console.log(`${row.peer.padEnd(24)} ${row.role.padEnd(8)} ${row.owner ?? ""}  ${t}`);
+      }
+      process.exit(0);
+    }
+    if (action === "gen") {
+      console.log(generateToken());
+      process.exit(0);
+    }
+    console.error(`auth: unknown action '${action ?? ""}' (expected add | remove | list | gen)`);
+    process.exit(1);
+  }
   if (command === "update") {
     const args2 = parseArgs(rest);
     if (args2["--help"] || args2["-h"]) {
@@ -2268,7 +3588,12 @@ 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"]),
+    authTokens: args["--auth-tokens"] === void 0 ? void 0 : String(args["--auth-tokens"]),
+    allowJoin: args["--allow-join"] === true,
+    db: args["--db"] === void 0 ? DEFAULT_DB : args["--db"] === "off" ? void 0 : String(args["--db"])
   }, log);
   const shutdown = () => {
     log.info("agent-comm-hub shutting down");