agent-comm-hub 0.6.0 → 0.7.1

package/lib/cli.js

@@ -2,8 +2,9 @@
 
 // src/index.ts
 import { createServer } from "node:http";
-import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
-import { dirname } from "node:path";
+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";
@@ -420,6 +421,7 @@ 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) {
@@ -450,6 +452,8 @@ var AgentHub = class {
   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() {
@@ -489,6 +493,7 @@ var AgentHub = class {
   /** 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);
@@ -629,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).
@@ -640,10 +656,175 @@ 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 {
@@ -667,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;
   }
   /**
@@ -750,12 +931,15 @@ var AgentHub = class {
     if (queue.length >= this.options.maxQueue) queue.shift();
     queue.push(message);
     this.queues.set(target, queue);
+    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) {
@@ -773,13 +957,154 @@ function omit(value, key) {
   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)
   };
 }
@@ -799,7 +1124,8 @@ function autoRegisterPeer(hub, registry, sessionId, clientName, clientVersion) {
   const bound = registry.peerFor(sessionId);
   if (bound !== void 0) return bound;
   if (registry.isSuppressed(sessionId)) return void 0;
-  const peerId = sanitizePeerId(clientName ?? "agent");
+  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 } : {},
@@ -820,16 +1146,31 @@ function livePeersFor(registry) {
 }
 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
     };
@@ -864,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) };
@@ -878,7 +1220,8 @@ function hubTools(hub, registry, options) {
     }
     return herdr;
   };
-  const requireManager = (peer, action) => {
+  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`);
@@ -910,6 +1253,10 @@ function hubTools(hub, registry, options) {
           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}`);
         }
@@ -951,7 +1298,7 @@ function hubTools(hub, registry, options) {
         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}'`);
+        requireManager(caller, `kicking '${target}'`, sessionId);
         if (!hub.has(target)) {
           return { ok: true, peerId: null, kicked: false };
         }
@@ -968,14 +1315,14 @@ function hubTools(hub, registry, options) {
         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) => {
+      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}'`);
+        if (target !== peer) requireManager(peer, `renaming '${target}'`, sessionId);
         let previousId;
         if (hasPeerId) {
           if (args.peer === void 0) {
@@ -1076,16 +1423,98 @@ function hubTools(hub, registry, options) {
       name: "bridge_history",
       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) => {
+      handler: wrap(true, async (args, peer, sessionId) => {
         const limit = Math.min(args.limit === void 0 ? 20 : Number(args.limit), 1e3);
         const target = args.peer === void 0 ? peer : String(args.peer);
         if (target !== peer) {
-          requireManager(peer, `reading ${target === BROADCAST ? "the full history" : `peer '${target}' history`} requires manager rights`);
+          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
@@ -1288,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;
@@ -1360,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);
@@ -1420,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;
@@ -1481,7 +1947,14 @@ data: ${JSON.stringify({ jsonrpc: "2.0", method, params })}
     }
   }
   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",
@@ -1497,7 +1970,79 @@ data: ${JSON.stringify({ jsonrpc: "2.0", method, params })}
       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);
@@ -1518,12 +2063,13 @@ data: ${JSON.stringify({ jsonrpc: "2.0", method, params })}
     }
     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",
@@ -1536,7 +2082,7 @@ data: ${JSON.stringify({ jsonrpc: "2.0", method, params })}
       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": {
@@ -1547,6 +2093,9 @@ data: ${JSON.stringify({ jsonrpc: "2.0", method, params })}
         if (clientName !== void 0) {
           this.registry.noteClient(newSessionId, clientName, clientVersion);
         }
+        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;
@@ -1610,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": "*",
@@ -1635,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.info(`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.6.0";
+var SERVER_VERSION = "0.7.1";
 var DEFAULT_HOST = "127.0.0.1";
 var DEFAULT_PORT = 18764;
 var DEFAULT_PATH = "/mcp";
@@ -1659,16 +2356,39 @@ var DEFAULT_CONFIG = {
   // 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) {
-  mkdirSync(dirname(file), { recursive: true });
+  mkdirSync2(dirname2(file), { recursive: true });
   const tmp = `${file}.tmp`;
-  writeFileSync(tmp, JSON.stringify({ version: 1, savedAt: Date.now(), profiles }), "utf8");
-  renameSync(tmp, file);
+  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",
@@ -1683,24 +2403,51 @@ function startHub(config = {}, log2 = console) {
       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;
-  const flushRoster = () => {
-    if (resolved.stateFile === void 0 || !rosterDirty) return;
-    rosterDirty = false;
-    try {
-      writeRosterFile(resolved.stateFile, hub.exportProfiles());
-    } catch (error) {
-      log2.warn(`roster save failed: ${error.message}`);
+  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 scheduleRosterSave = () => {
-    if (resolved.stateFile === void 0) return;
-    rosterDirty = true;
+  const scheduleSave = () => {
+    if (resolved.stateFile === void 0 && dbStore === void 0) return;
     if (saveTimer !== void 0) return;
     saveTimer = setTimeout(() => {
       saveTimer = void 0;
-      flushRoster();
+      flushSaves();
     }, 500);
     saveTimer.unref?.();
   };
@@ -1711,6 +2458,30 @@ 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),
     // SSE event push: roster changes and queued-mail hints. Best-effort — a
@@ -1721,7 +2492,9 @@ function startHub(config = {}, log2 = console) {
       } catch (error) {
         log2.warn(`peers_changed notification failed: ${error.message}`);
       }
-      scheduleRosterSave();
+      rosterDirty = true;
+      dbDirty = true;
+      scheduleSave();
     },
     onQueued: (message, target) => {
       try {
@@ -1732,9 +2505,39 @@ function startHub(config = {}, log2 = console) {
     }
   });
   const registry = new SessionRegistry();
-  if (resolved.stateFile !== void 0) {
+  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(readFileSync(resolved.stateFile, "utf8"));
+      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) {
@@ -1750,6 +2553,25 @@ function startHub(config = {}, log2 = console) {
     socketPath: resolved.herdrSocketPath,
     sendRequest: resolved.herdrSendRequest
   });
+  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,
@@ -1763,12 +2585,26 @@ function startHub(config = {}, log2 = console) {
     (message) => log2.warn(message),
     (sessionId, clientName, clientVersion) => {
       try {
+        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) log2.info(`peer joined: ${peer}`);
+        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);
@@ -1788,7 +2624,15 @@ function startHub(config = {}, log2 = console) {
         clearTimeout(saveTimer);
         saveTimer = void 0;
       }
-      flushRoster();
+      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();
     }
@@ -1797,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 dirname3, 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 as readFileSync2, 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 as dirname2, join, sep } from "node:path";
+import { dirname as dirname3, join, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 function registryFile() {
-  return join(dirname2(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;
@@ -1821,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) {
@@ -1865,7 +2709,7 @@ function validateRegistry(registry) {
   }
 }
 function loadRegistry(file = registryFile()) {
-  const registry = JSON.parse(readFileSync2(file, "utf8"));
+  const registry = JSON.parse(readFileSync4(file, "utf8"));
   validateRegistry(registry);
   return registry;
 }
@@ -1916,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 = {}) {
@@ -1927,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;
           }
@@ -1948,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";
         }
@@ -1979,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(dirname3(fileURLToPath2(import.meta.url)), "..", "agents", "SKILL.md");
+  return join2(dirname4(fileURLToPath2(import.meta.url)), "..", "agents", "SKILL.md");
 }
 function stamp() {
   const now = /* @__PURE__ */ new Date();
@@ -1987,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) {
@@ -1995,7 +2839,7 @@ async function readJson(file) {
   }
 }
 async function writeJsonNoBom(file, doc) {
-  await mkdir(dirname3(file), { recursive: true });
+  await mkdir(dirname4(file), { recursive: true });
   await writeFile(file, JSON.stringify(doc, null, 2) + "\n", "utf8");
 }
 async function backup(file) {
@@ -2016,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);
@@ -2038,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");
@@ -2077,7 +2921,7 @@ ${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 hubEntryRanges = () => {
@@ -2119,14 +2963,14 @@ async function mergeDshPatch(file, opts) {
 }
 async function syncSkill(skillDir, skillSrc, remove, log2) {
   if (remove) {
-    if (existsSync2(skillDir)) {
-      await mkdir(dirname3(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;
   }
@@ -2212,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 as mkdirSync2, readFileSync as readFileSync3, rmSync, writeFileSync as writeFileSync2 } 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 dirname4, 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";
@@ -2267,8 +3111,8 @@ async function runStatus(options = {}) {
 function runUpdate() {
   const messages = [];
   try {
-    const pkgFile = join3(dirname4(fileURLToPath3(import.meta.url)), "..", "package.json");
-    const before = JSON.parse(readFileSync3(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'",
@@ -2324,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 {
-          mkdirSync2(launcherDir, { recursive: true });
-          writeFileSync2(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}"`);
@@ -2364,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 {
-          mkdirSync2(unitDir, { recursive: true });
-          writeFileSync2(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}`);
@@ -2418,8 +3262,8 @@ WantedBy=default.target
           messages.push(`[dry-run] write ${plist}`);
           messages.push(`[dry-run] launchctl bootstrap gui/${uid} ${plist}`);
         } else {
-          mkdirSync2(launchAgentsDir, { recursive: true });
-          writeFileSync2(plist, plistContent);
+          mkdirSync3(launchAgentsDir, { recursive: true });
+          writeFileSync3(plist, plistContent);
           try {
             execFileSync2("launchctl", ["bootstrap", `gui/${uid}`, plist], { encoding: "utf8", windowsHide: true });
           } catch {
@@ -2456,18 +3300,21 @@ 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", "--manager-peers", "--state-file"]);
+  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;
     }
@@ -2506,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)
@@ -2527,6 +3378,27 @@ Hub options:
                              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)
@@ -2611,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"]) {
@@ -2647,7 +3590,10 @@ try {
     herdrBin: args["--herdr-bin"],
     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"])
+    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");