agent-comm-hub 0.9.0 → 0.10.0

package/lib/index.js

@@ -2,7 +2,7 @@
 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";
+import { dirname as dirname2, join } from "node:path";
 
 // src/herdr-ctl.ts
 import { execFile } from "node:child_process";
@@ -415,6 +415,104 @@ function socketSend(socketPath, method, params) {
   });
 }
 
+// src/runner.ts
+import { execFile as execFile2 } from "node:child_process";
+var DEFAULT_RUN_TIMEOUT_MS = 12e4;
+var MAX_RUN_NOTE_CHARS = 4e3;
+function validateRunnerConfig(config, index) {
+  const where = `runners[${index}]`;
+  if (typeof config.peer !== "string" || config.peer === "") throw new Error(`${where}: peer must be a non-empty string`);
+  if (config.kind !== "cli" && config.kind !== "herdr") throw new Error(`${where}: kind must be 'cli' or 'herdr'`);
+  if (config.kind === "cli") {
+    if (typeof config.command !== "string" || config.command === "") throw new Error(`${where}: cli needs a command`);
+    if (config.args !== void 0 && (!Array.isArray(config.args) || config.args.some((arg) => typeof arg !== "string"))) {
+      throw new Error(`${where}: args must be an array of strings`);
+    }
+  }
+  if (config.timeoutMs !== void 0 && (!Number.isFinite(config.timeoutMs) || config.timeoutMs <= 0)) {
+    throw new Error(`${where}: timeoutMs must be a positive number`);
+  }
+}
+var truncate = (text) => text.length > MAX_RUN_NOTE_CHARS ? `${text.slice(0, MAX_RUN_NOTE_CHARS)}\u2026 (truncated)` : text;
+function substitute(arg, request) {
+  const values = {
+    prompt: request.prompt,
+    context: request.context,
+    deliverable: request.deliverable,
+    taskId: request.taskId,
+    peer: request.peer
+  };
+  return arg.replace(/\{(\w+)\}/g, (whole, key) => values[key] ?? whole);
+}
+function cliRunner(config) {
+  const command = config.command;
+  const args = config.args ?? [];
+  const timeout = config.timeoutMs ?? DEFAULT_RUN_TIMEOUT_MS;
+  return {
+    name: `cli:${command}`,
+    run: (request) => new Promise((resolve) => {
+      execFile2(
+        command,
+        args.map((arg) => substitute(arg, request)),
+        // No shell, a bounded buffer, and a hard timeout: a hung runner must
+        // not hold the task open forever.
+        { timeout, maxBuffer: 4 * 1024 * 1024, windowsHide: true },
+        (error, stdout, stderr) => {
+          const out = stdout.trim();
+          if (error !== null) {
+            const detail = stderr.trim() !== "" ? stderr.trim() : error.message;
+            resolve({ status: "failed", note: truncate(`runner failed: ${detail}${out !== "" ? `
+${out}` : ""}`) });
+            return;
+          }
+          resolve({ status: "done", note: truncate(out === "" ? "(runner produced no output)" : out) });
+        }
+      );
+    })
+  };
+}
+function herdrRunner(config, ctl) {
+  const target = config.target ?? config.peer;
+  const timeout = config.timeoutMs ?? DEFAULT_RUN_TIMEOUT_MS;
+  return {
+    name: `herdr:${target}`,
+    run: async (request) => {
+      try {
+        const text = [request.prompt, request.context].filter((part) => part !== void 0 && part !== "").join("\n\n");
+        await ctl.promptSmart(target, text, { wait: true, timeoutMs: timeout });
+        const read = await ctl.readSmart(target, { lines: 200 });
+        return { status: "done", note: truncate(read.text.trim() === "" ? "(no output read back)" : read.text) };
+      } catch (error) {
+        return { status: "failed", note: truncate(`herdr runner failed: ${error.message}`) };
+      }
+    }
+  };
+}
+function createRunner(config, deps = {}) {
+  if (config.kind === "cli") return cliRunner(config);
+  if (deps.herdr === void 0) throw new Error(`runner for '${config.peer}': kind 'herdr' needs herdr to be enabled`);
+  return herdrRunner(config, deps.herdr);
+}
+var RunnerRegistry = class {
+  runners = /* @__PURE__ */ new Map();
+  constructor(configs = [], deps = {}) {
+    configs.forEach((config, index) => {
+      validateRunnerConfig(config, index);
+      this.runners.set(config.peer, createRunner(config, deps));
+    });
+  }
+  get(peer) {
+    return this.runners.get(peer);
+  }
+  /** Peer ids that have a runner (for startup logging). */
+  peers() {
+    return [...this.runners.keys()];
+  }
+  get size() {
+    return this.runners.size;
+  }
+};
+
 // src/hub.ts
 import { randomUUID } from "node:crypto";
 
@@ -422,8 +520,34 @@ import { randomUUID } from "node:crypto";
 var KINDS = ["chat", "task", "notice", "ack"];
 var PEER_ID_PATTERN = /^[A-Za-z0-9._:-]{1,64}$/;
 var BROADCAST = "all";
+var HUB_PEER = "hub";
+var SSE_METHOD = "notifications/message";
+var SSE_EVENT_PEERS_CHANGED = "peers_changed";
+var SSE_EVENT_MESSAGE = "message";
 var MAX_HOP = 5;
-var TERMINAL_TASK_STATUSES = ["rejected", "done", "failed", "timeout"];
+var MAX_REPLY_CHAIN = 50;
+function a2aState(status) {
+  switch (status) {
+    case "pending":
+    case "accepted":
+      return "submitted";
+    case "working":
+      return "working";
+    case "input-required":
+      return "input-required";
+    case "done":
+      return "completed";
+    case "canceled":
+      return "canceled";
+    case "failed":
+    case "timeout":
+      return "failed";
+    case "rejected":
+      return "rejected";
+  }
+}
+var CLIENT_ACK_STATUSES = ["accepted", "working", "input-required", "rejected", "done", "failed"];
+var TERMINAL_TASK_STATUSES = ["rejected", "done", "failed", "timeout", "canceled"];
 function ackToTaskStatus(ack) {
   return ack;
 }
@@ -438,6 +562,9 @@ function nextTaskStatus(current, ack) {
     case "working":
       if (next === "accepted") return "working";
       return next;
+    case "input-required":
+      if (next === "accepted") return "input-required";
+      return next;
     default:
       return null;
   }
@@ -445,6 +572,7 @@ function nextTaskStatus(current, ack) {
 function aggregateTaskStatus(assignees) {
   if (assignees.length === 0) return "pending";
   const statuses = assignees.map((a) => a.status);
+  if (statuses.some((s) => s === "input-required")) return "input-required";
   const active = statuses.filter((s) => s === "pending" || s === "accepted" || s === "working");
   if (active.length > 0) {
     if (active.some((s) => s === "working")) return "working";
@@ -454,13 +582,14 @@ function aggregateTaskStatus(assignees) {
   if (statuses.every((s) => s === "done")) return "done";
   if (statuses.some((s) => s === "failed")) return "failed";
   if (statuses.some((s) => s === "timeout")) return "timeout";
+  if (statuses.some((s) => s === "canceled")) return "canceled";
   return "rejected";
 }
 function encodeContent(payload) {
   return JSON.stringify(payload);
 }
 function decodeContent(kind, content) {
-  if (kind !== "task" && kind !== "ack") return content;
+  if (kind !== "task" && kind !== "ack" && kind !== "notice") return content;
   try {
     const parsed = JSON.parse(content);
     if (parsed !== null && typeof parsed === "object") return parsed;
@@ -472,19 +601,103 @@ function decodeContent(kind, content) {
 // src/hub.ts
 var MAX_PROFILES = 512;
 var MAX_TASKS = 1024;
-var AgentHub = class {
+var MAX_TIMER_DELAY_MS = 2147483647;
+var DEFAULT_PARKED_TTL_MS = 7 * 24 * 60 * 60 * 1e3;
+var DEFAULT_LEASE_TTL_MS = 6e4;
+var DEFAULT_MAX_ATTEMPTS = 5;
+var MAX_EVENTS = 500;
+var AgentHub = class _AgentHub {
   constructor(options) {
     this.options = options;
     const idle = options.peerIdleTimeoutMs ?? 6e5;
+    const parkedTtl = options.parkedTtlMs ?? DEFAULT_PARKED_TTL_MS;
     if (idle > 0) {
       const interval = Math.min(6e4, Math.max(1e3, idle / 2));
       this.gcTimer = setInterval(() => this.gcTick(idle), interval);
       this.gcTimer.unref?.();
+    } else if (parkedTtl > 0) {
+      const interval = Math.min(6e4, Math.max(1e3, parkedTtl / 2));
+      this.gcTimer = setInterval(() => this.expireParkedMailboxes(Date.now()), interval);
+      this.gcTimer.unref?.();
     }
   }
   queues = /* @__PURE__ */ new Map();
+  /** When each parked (peer-gone-but-kept) mailbox was parked, for the TTL sweep.
+   * A queue in this map has no registered peer; see {@link unregister}. */
+  parkedAt = /* @__PURE__ */ new Map();
+  /** Highest {@link BridgeMessage.seq} handed out so far. Restored history can
+   * raise it (see importHistory) but nothing lowers it: a client's `since` cursor
+   * has to keep meaning the same thing across a restart. */
+  seqCounter = 0;
+  /**
+   * Record one operational event.
+   *
+   * Deliberately NOT the same thing as history: history is the messages that
+   * flowed (what peers said to each other), this is what the HUB did — a peer
+   * joined, a mailbox was dropped, a task moved. History can be read per peer and
+   * is persisted; events are global, per-run, and never persisted, because they
+   * describe the life of this process.
+   */
+  recordEvent(kind, input = {}) {
+    this.eventRing.push({
+      seq: ++this.eventSeq,
+      ts: Date.now(),
+      kind,
+      ...input.peer !== void 0 ? { peer: input.peer } : {},
+      detail: input.detail ?? {}
+    });
+    while (this.eventRing.length > MAX_EVENTS) this.eventRing.shift();
+  }
+  /**
+   * Read recorded events, oldest first.
+   *
+   * `since` is exclusive ("give me what happened after seq N"), which makes it the
+   * natural cursor: pass the `lastSeq` of the previous call. `truncated` says the
+   * requested window is no longer in the ring, so the caller knows it missed
+   * entries instead of assuming it saw everything.
+   */
+  events(options = {}) {
+    const limit = Math.max(1, Math.min(options.limit ?? 100, MAX_EVENTS));
+    const since = options.since ?? 0;
+    const available = this.eventRing.filter((event) => event.seq > since);
+    const truncated = since > 0 && available.length > 0 && available[0].seq > since + 1;
+    return {
+      events: available.slice(-limit),
+      lastSeq: this.eventSeq,
+      truncated
+    };
+  }
+  /** The task hook, plus the event it implies.
+   *
+   *  Every status change in this class already reports through
+   *  `options.onTaskChanged`, so recording the event HERE needs no new call sites:
+   *  the hook IS the transition signal. That is also why the event can carry the
+   *  aggregate status without the caller having to say what changed — it is read
+   *  from the record at the moment the transition is announced. */
+  taskChanged(record) {
+    if (record !== void 0) {
+      this.recordEvent("task_transition", {
+        peer: record.from,
+        detail: { taskId: record.id, status: record.status, assignees: record.assignees.length }
+      });
+    }
+    this.options.onTaskChanged?.(record);
+  }
+  /** Record an event from outside the hub.
+   *
+   *  The runner layer lives in `index.ts` and knows when a run starts and ends,
+   *  which the hub cannot see. Deliberately narrow: a caller can ADD an event but
+   *  cannot read or clear the ring through this.
+   */
+  noteEvent(kind, input = {}) {
+    this.recordEvent(kind, input);
+  }
   waiters = /* @__PURE__ */ new Map();
   historyRing = [];
+  /** Structured operational events, newest last. A ring, not a log: the hub is a
+   *  long-running process and an unbounded event list is a leak. See {@link events}. */
+  eventRing = [];
+  eventSeq = 0;
   lastSeen = /* @__PURE__ */ new Map();
   /** Identity metadata keyed by peer id; outlives registration (see {@link PeerProfile}). */
   profiles = /* @__PURE__ */ new Map();
@@ -507,9 +720,69 @@ var AgentHub = class {
       if (now - (this.lastSeen.get(peerId) ?? 0) > idleTimeoutMs) {
         if (this.options.isPeerLive?.(peerId) === true) continue;
         this.options.onPeerGc?.(peerId);
-        this.unregister(peerId);
+        this.unregister(peerId, { keepMailbox: true });
       }
     }
+    for (const peerId of [...this.leases.keys()]) this.reapLeases(peerId, now);
+    this.expireParkedMailboxes(now);
+  }
+  /** Drop parked mailboxes older than `parkedTtlMs` (0 disables expiry). */
+  expireParkedMailboxes(now) {
+    const ttl = this.options.parkedTtlMs ?? DEFAULT_PARKED_TTL_MS;
+    if (ttl <= 0) return;
+    for (const [peerId, parkedMs] of [...this.parkedAt]) {
+      if (this.lastSeen.has(peerId)) {
+        this.parkedAt.delete(peerId);
+        continue;
+      }
+      if (now - parkedMs <= ttl) continue;
+      const queue = this.queues.get(peerId) ?? [];
+      this.queues.delete(peerId);
+      this.parkedAt.delete(peerId);
+      for (const message of queue) {
+        if (message.kind === "task") this.failTaskForGoneAssignee(message.id, peerId, now, ttl);
+      }
+      const dropped = queue.length;
+      if (dropped > 0) {
+        this.options.onMailboxesChanged?.();
+        this.recordEvent("mailbox_dropped", { peer: peerId, detail: { reason: "expired", dropped, ttlMs: ttl } });
+        this.options.onMailboxExpired?.(peerId, dropped);
+      }
+    }
+  }
+  /** Reconcile the task ledger after `peerId`'s parked mailbox was destroyed with
+   *  the task still inside it.
+   *
+   *  The task fails as a SYSTEM event, not as an ack: nobody acked anything, the
+   *  peer simply never came back. Marking only this assignee's row keeps a
+   *  broadcast task's other recipients intact, and the aggregate status is
+   *  recomputed the same way every other transition does it. */
+  failTaskForGoneAssignee(taskId, peerId, now, ttl) {
+    const record = this.taskLedger.get(taskId);
+    if (record === void 0) return;
+    if (TERMINAL_TASK_STATUSES.includes(record.status)) return;
+    const assignee = record.assignees.find((a) => a.peerId === peerId);
+    if (assignee === void 0 || TERMINAL_TASK_STATUSES.includes(assignee.status)) return;
+    const event = {
+      from: peerId,
+      status: "failed",
+      note: `recipient '${peerId}' never came back: its parked mailbox expired after ${ttl}ms and the task was dropped with it`,
+      ts: now,
+      messageId: `expired-${taskId}`,
+      applied: true,
+      system: true
+    };
+    record.acks.push(event);
+    assignee.status = "failed";
+    assignee.acks.push({ ...event });
+    record.status = aggregateTaskStatus(record.assignees);
+    record.updatedAt = now;
+    const timer = this.taskTimers.get(taskId);
+    if (timer !== void 0) {
+      clearTimeout(timer);
+      this.taskTimers.delete(taskId);
+    }
+    this.taskChanged(this.taskOf(taskId));
   }
   /** All registered peer ids, insertion order. */
   peers() {
@@ -521,6 +794,7 @@ var AgentHub = class {
   register(peerId, client) {
     if (this.lastSeen.has(peerId)) throw new Error(`peer already registered: ${peerId}`);
     this.lastSeen.set(peerId, Date.now());
+    this.parkedAt.delete(peerId);
     const existing = this.profiles.get(peerId);
     this.profiles.set(peerId, {
       ...existing,
@@ -530,13 +804,28 @@ var AgentHub = class {
       ...client?.version !== void 0 ? { clientVersion: client.version } : existing?.clientVersion !== void 0 ? { clientVersion: existing.clientVersion } : {}
     });
     this.evictOverflowProfiles();
+    this.recordEvent("peer_joined", { peer: peerId, detail: { clientName: client?.name } });
     this.options.onPeersChanged?.(this.peers());
   }
-  /** 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);
+  /** Remove a peer; pending waiters resolve as timeouts. The profile is kept so
+   * a reconnecting peer keeps its alias.
+   *
+   * `keepMailbox` is what the idle GC passes: the peer's queued messages stay in
+   * `queues` (marked parked) so a returning agent drains what was sent while it
+   * was away. An explicit `bridge_unregister` and a manager kick leave it off,
+   * i.e. they still drop the mail — leaving the hub is a deliberate act. */
+  unregister(peerId, options) {
+    const queue = this.queues.get(peerId) ?? [];
+    const keep = options?.keepMailbox === true;
+    if (queue.length > 0) this.options.onMailboxesChanged?.();
+    if (keep) {
+      this.parkedAt.set(peerId, Date.now());
+      this.recordEvent("peer_parked", { peer: peerId, detail: { queued: queue.length } });
+    } else {
+      this.recordEvent("peer_left", { peer: peerId, detail: { queued: queue.length } });
+      this.queues.delete(peerId);
+      this.parkedAt.delete(peerId);
+    }
     for (const waiter of this.waiters.get(peerId) ?? []) {
       clearTimeout(waiter.timer);
       waiter.onAbort();
@@ -553,6 +842,44 @@ var AgentHub = class {
   exportProfiles() {
     return [...this.profiles.values()].map((profile) => ({ ...profile }));
   }
+  /** Record what a peer says about itself. Creates the profile if the peer is
+   *  new: a card is identity, and identity outlives a connection. */
+  announceCard(peerId, card) {
+    const existing = this.profiles.get(peerId);
+    const profile = { ...existing, id: peerId, registeredAt: existing?.registeredAt ?? Date.now(), card };
+    this.profiles.set(peerId, profile);
+    this.evictOverflowProfiles();
+    this.options.onPeersChanged?.(this.peers());
+    return profile;
+  }
+  /** Every peer whose announced card matches `filter`, with the load a caller
+   *  needs to pick one.
+   *
+   *  `acceptsTasks` defaults to TRUE — and that default is the point: discover is
+   *  for finding somebody to HAND WORK TO, and "has a skill" is not "wants a
+   *  task". Pass `false` to drop the requirement and list peers regardless. */
+  discover(filter = {}) {
+    const requireAccept = filter.acceptsTasks !== false;
+    const out = [];
+    for (const profile of this.profiles.values()) {
+      const card = profile.card;
+      if (card === void 0) continue;
+      if (requireAccept && card.acceptsTasks !== true) continue;
+      const skills = card.skills ?? [];
+      if (filter.skill !== void 0 && !skills.some((skill) => skill.id === filter.skill)) continue;
+      if (filter.tag !== void 0 && !skills.some((skill) => (skill.tags ?? []).includes(filter.tag))) continue;
+      const load = {
+        queued: this.queues.get(profile.id)?.length ?? 0,
+        waiting: this.waiters.get(profile.id)?.length ?? 0,
+        running: [...this.taskLedger.values()].filter(
+          (record) => !TERMINAL_TASK_STATUSES.includes(record.status) && record.assignees.some((a) => a.peerId === profile.id)
+        ).length
+      };
+      if (filter.idleOnly === true && (load.queued > 0 || load.waiting > 0 || load.running > 0)) continue;
+      out.push({ peerId: profile.id, ...profile.alias !== void 0 ? { alias: profile.alias } : {}, card, load });
+    }
+    return out;
+  }
   /** 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. */
@@ -572,6 +899,7 @@ var AgentHub = class {
       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;
+      if (candidate.card !== null && typeof candidate.card === "object") profile.card = candidate.card;
       this.profiles.set(id, profile);
       count++;
     }
@@ -599,6 +927,7 @@ var AgentHub = class {
     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 (newId === HUB_PEER) 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);
@@ -606,6 +935,8 @@ var AgentHub = class {
     const seen = this.lastSeen.get(oldId) ?? Date.now();
     const profile = this.profiles.get(oldId);
     const stale = this.profiles.get(newId);
+    this.parkedAt.delete(oldId);
+    this.parkedAt.delete(newId);
     this.queues.delete(oldId);
     this.waiters.delete(oldId);
     this.lastSeen.delete(oldId);
@@ -657,6 +988,13 @@ var AgentHub = class {
   has(peerId) {
     return this.lastSeen.has(peerId);
   }
+  /** Is the peer parked — gone from the live registry through idle GC, but still
+   *  holding its mailbox and still addressable? `has()` is false for it, so a
+   *  guard written only as `has()` will decide there is nothing to do and leave
+   *  the peer reachable. A manager kick has to cover this state explicitly. */
+  isParked(peerId) {
+    return this.parkedAt.has(peerId);
+  }
   /** Is the peer "active" (tool/activity within the connected window)? */
   isActive(peerId) {
     const last = this.lastSeen.get(peerId);
@@ -664,15 +1002,21 @@ var AgentHub = class {
   }
   /** Send a chat/notice text message to `to` (or {@link BROADCAST}). */
   send(from, to, kind, content, opts) {
-    return this.route(from, to, kind, content, opts?.ref, opts?.threadId);
+    return this.route(from, to, kind, content, opts?.ref, opts?.threadId, opts?.expiresAt, false, opts?.priority);
   }
   /** Send a structured task message to `to` (peer, {@link BROADCAST}, or a
    * group id). Records a ledger entry so the sender can later query status /
-   * wait for acks. */
-  sendTask(from, to, task) {
+   * wait for acks.
+   *
+   * `ref` marks the task this one answers. When the parent is itself a task the
+   * new one is a **re-delegation**, and that chain is capped at {@link MAX_HOP}
+   * — without a way to express the parent, the cap would be unreachable and a
+   * hand-off loop unobservable. */
+  sendTask(from, to, task, ref, expiresAt) {
     const threadId = task.threadId;
-    const message = this.route(from, to, "task", JSON.stringify(task), void 0, threadId);
+    const message = this.compose(from, to, "task", JSON.stringify(task), ref, threadId, expiresAt, false, task.priority);
     this.recordTask(message, task);
+    this.dispatch(message);
     return message;
   }
   /** Send an acknowledgement back to the sender of `ref`. Updates the task
@@ -681,20 +1025,126 @@ var AgentHub = class {
   sendAck(from, ref, ack) {
     const task = this.taskLedger.get(ref);
     let target;
+    let threadId;
     if (task !== void 0) {
       target = task.from;
+      threadId = task.threadId;
     } else {
       const original = this.historyRing.findLast((message2) => message2.id === ref);
       if (!original) throw new Error(`cannot ack unknown message: ${ref}`);
       target = original.from;
+      threadId = original.threadId;
     }
-    const message = this.route(from, target, "ack", JSON.stringify(ack), ref);
+    const message = this.route(from, target, "ack", JSON.stringify(ack), ref, threadId);
     this.applyAckToLedger(message, from, ref, ack);
     return message;
   }
+  /** Record an ack the hub produced ON BEHALF of a peer whose runner finished
+   *  its task (see `src/runner.ts`).
+   *
+   *  Unlike {@link sendAck} the sender is not a live session — it may be parked,
+   *  or not connected at all — so the "sender must be registered" check does not
+   *  apply. This is the hub acting for a peer it is executing for, never a
+   *  caller-supplied identity; nothing from a request reaches `from` here.
+   *  Everything else (ledger update, routing to the task's sender) is identical. */
+  ackForRunner(peer, ref, ack) {
+    const task = this.taskLedger.get(ref);
+    if (task === void 0) throw new Error(`runner cannot ack unknown task: ${ref}`);
+    const message = this.route(peer, task.from, "ack", JSON.stringify(ack), ref, void 0, void 0, true);
+    this.applyAckToLedger(message, peer, ref, ack);
+    return message;
+  }
+  /** Cancel a task. EITHER side may do it — the sender stops work it no longer
+   *  wants, an assignee reports it will not finish — and the cancel is both
+   *  recorded on the ledger and routed to the OTHER side, so whoever did not
+   *  press the button finds out. Cancelling an already-terminal task is an error
+   *  rather than a silent no-op: the caller asked for something that did not
+   *  happen. */
+  cancelTask(from, ref, reason) {
+    const record = this.taskLedger.get(ref);
+    if (record === void 0) throw new Error(`cannot cancel unknown task: ${ref}`);
+    const isSender = from === record.from;
+    if (!isSender && !record.assignees.some((a) => a.peerId === from)) {
+      throw new Error(`only the sender or an assignee can cancel task ${ref}`);
+    }
+    if (TERMINAL_TASK_STATUSES.includes(record.status)) {
+      throw new Error(`task ${ref} is already ${record.status}`);
+    }
+    const ack = { status: "canceled", ...reason !== void 0 ? { note: reason } : {} };
+    if (!isSender) {
+      return this.sendAck(from, ref, ack);
+    }
+    let last;
+    for (const assignee of record.assignees) {
+      if (TERMINAL_TASK_STATUSES.includes(assignee.status)) continue;
+      const message = this.route(from, assignee.peerId, "ack", JSON.stringify(ack), ref, record.threadId);
+      const event = {
+        from,
+        status: "canceled",
+        ...reason !== void 0 ? { note: reason } : {},
+        ts: message.ts,
+        messageId: message.id,
+        applied: true
+      };
+      record.acks.push(event);
+      assignee.status = "canceled";
+      assignee.acks.push({ ...event });
+      last = message;
+    }
+    if (last === void 0) throw new Error(`task ${ref} has no assignee left to cancel`);
+    record.status = aggregateTaskStatus(record.assignees);
+    record.updatedAt = last.ts;
+    this.taskChanged(this.taskOf(ref));
+    return last;
+  }
+  /** Answer an `input-required` interrupt. Only the task's SENDER can answer — it
+   *  is the side the assignee asked. The answer is delivered to the waiting
+   *  assignee as an `ack` carrying the task id, so a `bridge_wait { ref }` picks
+   *  it up, and the task resumes (`working`). */
+  taskInput(from, ref, input) {
+    const record = this.taskLedger.get(ref);
+    if (record === void 0) throw new Error(`cannot answer unknown task: ${ref}`);
+    if (from !== record.from) {
+      throw new Error(`only the sender of task ${ref} can answer it (an assignee resumes by acking 'working')`);
+    }
+    if (TERMINAL_TASK_STATUSES.includes(record.status)) {
+      throw new Error(`task ${ref} is already ${record.status}`);
+    }
+    const waiting = record.assignees.filter((a) => a.status === "input-required");
+    const targets = waiting.length > 0 ? waiting : record.assignees;
+    const ack = { status: "working", note: input };
+    let last;
+    for (const assignee of targets) {
+      const message = this.route(from, assignee.peerId, "ack", JSON.stringify(ack), ref, record.threadId);
+      const event = { from, status: "working", note: input, ts: message.ts, messageId: message.id, applied: true };
+      record.acks.push(event);
+      if (assignee.status === "input-required") {
+        assignee.status = "working";
+        assignee.acks.push({ ...event });
+      }
+      last = message;
+    }
+    if (last === void 0) throw new Error(`task ${ref} has no assignee to answer`);
+    record.status = aggregateTaskStatus(record.assignees);
+    record.updatedAt = last.ts;
+    this.taskChanged(this.taskOf(ref));
+    return last;
+  }
+  /** Every peer a fan-out can reach: the live registry **plus** parked peers.
+   *
+   *  Parked peers keep their mailbox and stay addressable (that is the point of
+   *  parking, see {@link isParked}), and a group send already delivered to its
+   *  parked members because it reads the member list rather than the live roster.
+   *  Broadcast read the live roster, so `peer-x` showed up in `bridge_peers` as
+   *  addressable yet silently missed every broadcast. Both resolve here now. */
+  audience() {
+    const ids = new Set(this.lastSeen.keys());
+    for (const id of this.parkedAt.keys()) ids.add(id);
+    return [...ids];
+  }
   /** Resolve the peer ids a task is assigned to (broadcast / group fan-out). */
   resolveAssignees(from, to) {
-    if (to === BROADCAST) return this.peers().filter((peer) => peer !== from);
+    if (to === BROADCAST) return this.audience().filter((peer) => peer !== from);
     const group = this.groups.get(to);
     if (group !== void 0) return group.members.filter((member) => member !== from);
     return [to];
@@ -723,13 +1173,19 @@ var AgentHub = class {
     this.taskLedger.set(message.id, record);
     this.scheduleTaskTimeout(record);
     this.evictOverflowTasks();
-    this.options.onTaskChanged?.(this.taskOf(record.id));
+    this.taskChanged(this.taskOf(record.id));
   }
-  /** Arm the SLA timer for a task that supplied `timeoutMs`. */
+  /** Arm the SLA timer for a task that supplied `timeoutMs`. A deadline
+   * beyond {@link MAX_TIMER_DELAY_MS} cannot be expressed as one delay — the
+   * timer would overflow and fire after ~1 ms — so it is re-armed in segments
+   * of that size. `deadlineAt` stays the authoritative deadline and each
+   * segment recomputes the remaining time, so a long SLA is honored exactly
+   * (no drift); settling or evicting the task clears the pending segment, and
+   * clearing the timer is what ends the chain. */
   scheduleTaskTimeout(record) {
     if (record.deadlineAt === void 0) return;
-    const delay = Math.max(0, record.deadlineAt - Date.now());
-    const timer = setTimeout(() => this.fireTaskTimeout(record.id), delay);
+    const remaining = record.deadlineAt - Date.now();
+    const timer = remaining > MAX_TIMER_DELAY_MS ? setTimeout(() => this.scheduleTaskTimeout(record), MAX_TIMER_DELAY_MS) : setTimeout(() => this.fireTaskTimeout(record.id), Math.max(0, remaining));
     timer.unref?.();
     this.taskTimers.set(record.id, timer);
   }
@@ -759,7 +1215,7 @@ var AgentHub = class {
     record.status = "timeout";
     record.updatedAt = now;
     this.clearTaskTimer(taskId);
-    this.options.onTaskChanged?.(this.taskOf(taskId));
+    this.taskChanged(this.taskOf(taskId));
   }
   clearTaskTimer(taskId) {
     const timer = this.taskTimers.get(taskId);
@@ -776,7 +1232,7 @@ var AgentHub = class {
     if (assignee === void 0 || assignee.deliveredMs !== void 0) return;
     assignee.deliveredMs = ts;
     record.updatedAt = ts;
-    this.options.onTaskChanged?.(this.taskOf(taskId));
+    this.taskChanged(this.taskOf(taskId));
   }
   /**
    * Fold an ack into the task's timeline and (when legal) its status.
@@ -796,11 +1252,15 @@ var AgentHub = class {
       status: ack.status,
       ...ack.note !== void 0 ? { note: ack.note } : {},
       ...typeof ack.progress === "number" && Number.isFinite(ack.progress) ? { progress: Math.max(0, Math.min(100, ack.progress)) } : {},
+      ...ack.artifacts !== void 0 && ack.artifacts.length > 0 ? { artifacts: ack.artifacts } : {},
       ts: message.ts,
       messageId: message.id,
       applied
     };
     record.acks.push(event);
+    if (applied && event.artifacts !== void 0) {
+      record.artifacts = [...record.artifacts ?? [], ...event.artifacts];
+    }
     if (assignee !== void 0 && assigneeNext !== null) {
       assignee.status = assigneeNext;
       assignee.acks.push({ ...event });
@@ -812,7 +1272,7 @@ var AgentHub = class {
     }
     record.updatedAt = message.ts;
     if (TERMINAL_TASK_STATUSES.includes(record.status)) this.clearTaskTimer(record.id);
-    this.options.onTaskChanged?.(this.taskOf(record.id));
+    this.taskChanged(this.taskOf(record.id));
   }
   /** Keep the ledger bounded: drop oldest terminal tasks first. */
   evictOverflowTasks() {
@@ -936,27 +1396,38 @@ var AgentHub = class {
     this.evictOverflowTasks();
     return count;
   }
+  /** Highest sequence number handed out so far — a client's "start from now"
+   *  cursor (`bridge_status.lastSeq`). */
+  lastSeq() {
+    return this.seqCounter;
+  }
   /** Recent messages involving `peer` (inbound and outbound, plus group
-   * channels the peer belongs to), newest first. */
-  history(peerId, limit) {
+   * channels the peer belongs to), newest first. `since` restricts the result to
+   * messages newer than that sequence number (a resume cursor); omitting it keeps
+   * the original behaviour, which includes history recorded before cursors
+   * existed. */
+  history(peerId, limit, since) {
     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)
+      (message) => (since === void 0 || (message.seq ?? 0) > since) && (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));
+  historyChannel(groupId, limit, since) {
+    const filtered = this.historyRing.filter(
+      (message) => (since === void 0 || (message.seq ?? 0) > since) && (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).
    * Backs `bridge_history { peer: "all" }` — lets an archiver (the desktop
    * app) capture peer-to-peer traffic it is not a party of. */
-  historyAll(limit) {
-    return this.historyRing.slice(-Math.max(0, limit)).reverse();
+  historyAll(limit, since) {
+    const filtered = since === void 0 ? this.historyRing : this.historyRing.filter((message) => (message.seq ?? 0) > since);
+    return filtered.slice(-Math.max(0, limit)).reverse();
   }
   // ---- groups (group channel) ------------------------------------------------
   /** Create a channel; throws when the id is taken or a member is unknown. */
@@ -1059,6 +1530,7 @@ var AgentHub = class {
       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;
+      const hop = importHop(m.hop);
       valid.push({
         id: m.id,
         from: m.from,
@@ -1068,9 +1540,18 @@ var AgentHub = class {
         ...typeof m.ref === "string" ? { ref: m.ref } : {},
         ...typeof m.channel === "string" ? { channel: m.channel } : {},
         ...typeof m.threadId === "string" ? { threadId: m.threadId } : {},
+        ...hop !== void 0 ? { hop } : {},
+        // Absent in databases written before the column existed; such a message
+        // is simply unreachable through a `since` cursor, which is the honest
+        // state for history that predates the cursor.
+        ...typeof m.seq === "number" && Number.isFinite(m.seq) && m.seq > 0 ? { seq: m.seq } : {},
+        ...typeof m.expiresAt === "number" && Number.isFinite(m.expiresAt) && m.expiresAt > 0 ? { expiresAt: m.expiresAt } : {},
         ts: m.ts
       });
     }
+    for (const message of valid) {
+      if (message.seq !== void 0 && message.seq > this.seqCounter) this.seqCounter = message.seq;
+    }
     for (const message of valid.slice(-this.options.historyLimit)) this.historyRing.push(message);
     return Math.min(valid.length, this.options.historyLimit);
   }
@@ -1093,6 +1574,7 @@ var AgentHub = class {
         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;
+        const hop = importHop(m.hop);
         restored.push({
           id: m.id,
           from: m.from,
@@ -1102,11 +1584,18 @@ var AgentHub = class {
           ...typeof m.ref === "string" ? { ref: m.ref } : {},
           ...typeof m.channel === "string" ? { channel: m.channel } : {},
           ...typeof m.threadId === "string" ? { threadId: m.threadId } : {},
+          ...hop !== void 0 ? { hop } : {},
+          // Restored mail must keep its deadline and its sequence number: the
+          // deadline decides whether it is still deliverable at all, and the
+          // cursor has to stay continuous across a restart.
+          ...typeof m.seq === "number" && Number.isFinite(m.seq) && m.seq > 0 ? { seq: m.seq } : {},
+          ...typeof m.expiresAt === "number" && Number.isFinite(m.expiresAt) && m.expiresAt > 0 ? { expiresAt: m.expiresAt } : {},
           ts: m.ts
         });
       }
       if (restored.length > 0) {
         this.queues.set(peer, restored.slice(-this.options.maxQueue));
+        if (!this.lastSeen.has(peer)) this.parkedAt.set(peer, Date.now());
         count += restored.length;
       }
     }
@@ -1120,27 +1609,321 @@ var AgentHub = class {
     const now = Date.now();
     return {
       server: "agent-comm-hub",
-      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
-        };
-      }),
+      peers: this.rosterRows(livePeers),
       historyLimit: this.options.historyLimit,
-      maxQueue: this.options.maxQueue
+      maxQueue: this.options.maxQueue,
+      // A client that wants only what happened since it last looked reads this
+      // and passes it back as `bridge_history { since }`.
+      lastSeq: this.seqCounter
+    };
+  }
+  /** Registered peers plus parked ones (gone but still holding mail).
+   * Parked rows are what lets a sender tell "queued, will be delivered when it
+   * comes back" apart from "vanished" — without them the message just looks lost.
+   */
+  rosterRows(livePeers) {
+    const rows = this.peers().map((peer) => {
+      const alias = this.profiles.get(peer)?.alias;
+      const connected = this.isActive(peer) || livePeers?.has(peer) === true;
+      return {
+        id: peer,
+        ...alias !== void 0 ? { alias } : {},
+        connected,
+        reachable: connected ? "online" : "idle",
+        lastSeenMs: this.lastSeen.get(peer) ?? 0,
+        queued: (this.queues.get(peer) ?? []).length,
+        waiting: (this.waiters.get(peer) ?? []).length,
+        ...this.leases.get(peer) !== void 0 ? { inFlight: this.leases.get(peer).length } : {},
+        ...this.drops.get(peer) !== void 0 && this.drops.get(peer).overflow > 0 ? { droppedOverflow: this.drops.get(peer).overflow } : {},
+        ...this.drops.get(peer) !== void 0 && this.drops.get(peer).expired > 0 ? { droppedExpired: this.drops.get(peer).expired } : {},
+        ...this.drops.get(peer) !== void 0 && this.drops.get(peer).rate > 0 ? { droppedRate: this.drops.get(peer).rate } : {},
+        ...this.deadLetters.get(peer) !== void 0 ? { deadLettered: this.deadLetters.get(peer).length } : {}
+      };
+    });
+    for (const [peerId, parkedMs] of this.parkedAt) {
+      if (this.lastSeen.has(peerId)) continue;
+      const alias = this.profiles.get(peerId)?.alias;
+      rows.push({
+        id: peerId,
+        ...alias !== void 0 ? { alias } : {},
+        connected: false,
+        reachable: "parked",
+        lastSeenMs: parkedMs,
+        queued: (this.queues.get(peerId) ?? []).length,
+        waiting: 0,
+        ...this.leases.get(peerId) !== void 0 ? { inFlight: this.leases.get(peerId).length } : {},
+        ...this.deadLetters.get(peerId) !== void 0 ? { deadLettered: this.deadLetters.get(peerId).length } : {}
+      });
+    }
+    return rows;
+  }
+  // ---- manual-ack leases -----------------------------------------------------
+  /** A message handed out but not yet committed, and when its lease ends. */
+  leases = /* @__PURE__ */ new Map();
+  /** Hand-out count per (peer, message). Kept OUTSIDE the message so requeueing
+   *  preserves it and so it is never persisted as part of the message. */
+  leaseAttempts = /* @__PURE__ */ new Map();
+  /** Messages that ran out of attempts; `nack` revives them. */
+  deadLetters = /* @__PURE__ */ new Map();
+  // ---- drop accounting --------------------------------------------------------
+  /** Per-peer drop counters, surfaced in the roster. Memory-only on purpose:
+   *  these are operational counters for the current run, not durable state. */
+  drops = /* @__PURE__ */ new Map();
+  /** Per-peer token bucket for the MAILBOX. See {@link HubOptions.ratePerMin}. */
+  buckets = /* @__PURE__ */ new Map();
+  /** Traffic counters, per peer: how much this peer sent, was sent, and acked.
+   *  Deliberately separate from the mailbox — "how much has this peer sent" is not
+   *  "how much is queued", and a drained queue must not erase the history of what
+   *  went through it. Memory-only, like {@link drops}: operational, not durable. */
+  traffic = /* @__PURE__ */ new Map();
+  bumpTraffic(peerId, field) {
+    const row = this.traffic.get(peerId) ?? { sent: 0, received: 0, acked: 0 };
+    row[field]++;
+    this.traffic.set(peerId, row);
+  }
+  /**
+   * Observability snapshot: per-peer and global counters.
+   *
+   * Everything here is either derived from live state or from a counter the hub
+   * already keeps — nothing is estimated, and nothing is sampled. `messagesTotal`
+   * is the history `seq` (monotonic, never resets in a run), so it is a true count
+   * of composed messages rather than a rolling window.
+   */
+  metrics() {
+    const tasksByStatus = {};
+    for (const record of this.taskLedger.values()) {
+      tasksByStatus[record.status] = (tasksByStatus[record.status] ?? 0) + 1;
+    }
+    const ids = /* @__PURE__ */ new Set([
+      ...this.lastSeen.keys(),
+      ...this.parkedAt.keys(),
+      ...this.queues.keys(),
+      ...this.traffic.keys()
+    ]);
+    const peers = [...ids].map((peerId) => {
+      const row = this.traffic.get(peerId) ?? { sent: 0, received: 0, acked: 0 };
+      const drop = this.drops.get(peerId) ?? { overflow: 0, expired: 0, rate: 0 };
+      return {
+        peerId,
+        sent: row.sent,
+        received: row.received,
+        acked: row.acked,
+        queued: this.queues.get(peerId)?.length ?? 0,
+        inFlight: this.leases.get(peerId)?.length ?? 0,
+        deadLettered: this.deadLetters.get(peerId)?.length ?? 0,
+        droppedOverflow: drop.overflow,
+        droppedExpired: drop.expired,
+        droppedRate: drop.rate,
+        // Same definition the roster uses: recent activity OR a live SSE channel.
+        connected: this.isActive(peerId) || this.options.isPeerLive?.(peerId) === true
+      };
+    });
+    return {
+      global: {
+        messagesTotal: this.seqCounter,
+        peers: peers.length,
+        connectedPeers: peers.filter((p) => p.connected).length,
+        parkedPeers: peers.filter((p) => !p.connected && this.parkedAt.has(p.peerId)).length,
+        waitersNow: [...this.waiters.values()].reduce((sum, list) => sum + list.length, 0),
+        queuedTotal: peers.reduce((sum, p) => sum + p.queued, 0),
+        tasksByStatus,
+        droppedOverflow: peers.reduce((sum, p) => sum + p.droppedOverflow, 0),
+        droppedExpired: peers.reduce((sum, p) => sum + p.droppedExpired, 0),
+        droppedRate: peers.reduce((sum, p) => sum + p.droppedRate, 0),
+        deadLettered: peers.reduce((sum, p) => sum + p.deadLettered, 0),
+        inFlight: peers.reduce((sum, p) => sum + p.inFlight, 0)
+      },
+      peers: peers.sort((a, b) => a.peerId.localeCompare(b.peerId))
+    };
+  }
+  /** Count a dropped message for `peerId` and, if that peer is waiting right
+   *  now, tell it. The notice is NOT queued: the mailbox is either full
+   *  (overflow) or the message already expired, and queueing the notice would
+   *  push yet another message out. An offline peer just sees the counters. */
+  /** May this peer's mailbox accept one more message right now?
+   *
+   *  Applied on the QUEUE path only, never on a waiter handoff: a waiting peer
+   *  already controls its own rate (it gets one message per `bridge_wait`), while a
+   *  mailbox is filled by traffic the recipient never asked for. That is the whole
+   *  point of the bucket.
+   */
+  takeToken(peerId, now) {
+    const rate = this.options.ratePerMin ?? 0;
+    if (rate <= 0) return true;
+    const bucket = this.buckets.get(peerId) ?? { tokens: rate, last: now };
+    const elapsed = Math.max(0, now - bucket.last);
+    bucket.tokens = Math.min(rate, bucket.tokens + elapsed * rate / 6e4);
+    bucket.last = now;
+    if (bucket.tokens < 1) {
+      this.buckets.set(peerId, bucket);
+      return false;
+    }
+    bucket.tokens -= 1;
+    this.buckets.set(peerId, bucket);
+    return true;
+  }
+  countDrop(peerId, kind, now) {
+    const stats = this.drops.get(peerId) ?? { overflow: 0, expired: 0, rate: 0 };
+    stats[kind] += 1;
+    this.drops.set(peerId, stats);
+    const total = stats.overflow + stats.expired + stats.rate;
+    this.recordEvent("mailbox_dropped", { peer: peerId, detail: { reason: kind, total } });
+    const notice = {
+      id: randomUUID(),
+      seq: ++this.seqCounter,
+      from: HUB_PEER,
+      to: peerId,
+      kind: "notice",
+      content: encodeContent({
+        message: kind === "overflow" ? `mailbox overflow: an older message was dropped before you read it (${total} dropped so far)` : kind === "rate" ? `rate limit: messages addressed to you arrived faster than ${this.options.ratePerMin ?? 0}/min and were dropped (${total} dropped so far)` : `a message addressed to you expired before delivery and was dropped (${total} dropped so far)`,
+        level: "warn"
+      }),
+      ts: now
     };
+    if (kind === "expired") {
+      const queue = this.queues.get(peerId) ?? [];
+      if (queue.length < this.options.maxQueue) {
+        queue.push(notice);
+        this.queues.set(peerId, queue);
+        this.options.onQueued?.(notice, peerId);
+        this.options.onMailboxesChanged?.();
+        return;
+      }
+    }
+    this.deliverToWaiter(peerId, notice);
+  }
+  /** Drop counters for `peerId` (undefined when nothing was ever dropped). */
+  dropsFor(peerId) {
+    return this.drops.get(peerId);
+  }
+  /** Hand `message` to a matching live waiter, if there is one. Never queues —
+   *  used for notices about a mailbox that must not grow. Returns whether it
+   *  was handed over. */
+  deliverToWaiter(target, message) {
+    const list = this.waiters.get(target) ?? [];
+    const index = list.findIndex((waiter2) => {
+      if (waiter2.from !== void 0 && waiter2.from !== message.from) return false;
+      if (waiter2.ref !== void 0 && !(message.kind === "ack" && message.ref === waiter2.ref)) return false;
+      if (waiter2.threadId !== void 0 && message.threadId !== waiter2.threadId) return false;
+      return true;
+    });
+    if (index < 0) return false;
+    const [waiter] = list.splice(index, 1);
+    this.waiters.set(target, list);
+    clearTimeout(waiter.timer);
+    waiter.resolve({ type: "message", message: this.handOut(target, message, waiter.manual === true, message.ts) });
+    return true;
+  }
+  static leaseKey(peerId, messageId) {
+    return `${peerId}\0${messageId}`;
+  }
+  /** Return expired leases to the FRONT of the queue (order preserved), or
+   *  dead-letter them once they have been handed out too many times. Called
+   *  before every take, so expiry needs no timer of its own. */
+  reapLeases(peerId, now) {
+    const list = this.leases.get(peerId);
+    if (list === void 0 || list.length === 0) return;
+    const max = this.options.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
+    const still = [];
+    const back = [];
+    for (const lease of list) {
+      if (lease.expiresAt > now) {
+        still.push(lease);
+        continue;
+      }
+      const attempts = this.leaseAttempts.get(_AgentHub.leaseKey(peerId, lease.message.id)) ?? 0;
+      if (max > 0 && attempts >= max) {
+        const dead = this.deadLetters.get(peerId) ?? [];
+        dead.push(lease.message);
+        this.deadLetters.set(peerId, dead);
+        continue;
+      }
+      back.push(lease.message);
+    }
+    if (still.length > 0) this.leases.set(peerId, still);
+    else this.leases.delete(peerId);
+    if (back.length > 0) {
+      const queue = this.queues.get(peerId) ?? [];
+      insertByPriority(queue, back);
+      this.queues.set(peerId, queue);
+      this.options.onMailboxesChanged?.();
+    }
+  }
+  /** Hand a message to `peerId`. Without `manual` it is gone; with it the hub
+   *  keeps a lease and the peer must `commit` or `nack` before it expires. */
+  handOut(peerId, message, manual, now) {
+    if (!manual) return message;
+    const key = _AgentHub.leaseKey(peerId, message.id);
+    const attempts = (this.leaseAttempts.get(key) ?? 0) + 1;
+    this.leaseAttempts.set(key, attempts);
+    const expiresAt = now + (this.options.leaseTtlMs ?? DEFAULT_LEASE_TTL_MS);
+    const list = this.leases.get(peerId) ?? [];
+    list.push({ message, expiresAt });
+    this.leases.set(peerId, list);
+    return { ...message, attempts, leaseExpiresAt: expiresAt };
+  }
+  /** Mark leased messages as consumed; returns how many leases were released. */
+  commit(peerId, ids) {
+    const wanted = new Set(ids);
+    const list = this.leases.get(peerId);
+    if (list === void 0) return 0;
+    const still = list.filter((lease) => !wanted.has(lease.message.id));
+    const released = list.length - still.length;
+    for (const id of wanted) this.leaseAttempts.delete(_AgentHub.leaseKey(peerId, id));
+    if (still.length > 0) this.leases.set(peerId, still);
+    else this.leases.delete(peerId);
+    return released;
+  }
+  /** Give messages back NOW — from live leases or from the dead letters. Attempts
+   *  are kept, so a message that keeps failing still eventually dead-letters;
+   *  reviving a dead letter resets its count, which is the point of reviving it. */
+  nack(peerId, ids) {
+    const wanted = new Set(ids);
+    const back = [];
+    const list = this.leases.get(peerId);
+    if (list !== void 0) {
+      const still = [];
+      for (const lease of list) {
+        if (wanted.has(lease.message.id)) back.push(lease.message);
+        else still.push(lease);
+      }
+      if (still.length > 0) this.leases.set(peerId, still);
+      else this.leases.delete(peerId);
+    }
+    const dead = this.deadLetters.get(peerId);
+    if (dead !== void 0) {
+      const still = [];
+      for (const message of dead) {
+        if (wanted.has(message.id)) {
+          back.push(message);
+          this.leaseAttempts.delete(_AgentHub.leaseKey(peerId, message.id));
+        } else still.push(message);
+      }
+      if (still.length > 0) this.deadLetters.set(peerId, still);
+      else this.deadLetters.delete(peerId);
+    }
+    if (back.length === 0) return 0;
+    const queue = this.queues.get(peerId) ?? [];
+    insertByPriority(queue, back);
+    this.queues.set(peerId, queue);
+    this.options.onMailboxesChanged?.();
+    return back.length;
   }
   /** Non-blocking drain of everything queued for `peer` (optionally from one sender). */
-  poll(peerId, from) {
+  poll(peerId, from, options) {
+    const now = Date.now();
+    this.reapLeases(peerId, now);
     const queue = this.queues.get(peerId) ?? [];
+    for (let i = queue.length - 1; i >= 0; i--) {
+      const queued = queue[i];
+      if (queued.expiresAt !== void 0 && queued.expiresAt <= now) {
+        queue.splice(i, 1);
+        this.countDrop(peerId, "expired", now);
+      }
+    }
     const drained = from === void 0 ? queue.splice(0, queue.length) : drainFrom(queue, from);
     if (drained.length > 0) this.options.onMailboxesChanged?.();
-    return drained;
+    return drained.map((message) => this.handOut(peerId, message, options?.manual === true, now));
   }
   /**
    * Long-poll for the next message addressed to `peer`: resolves immediately
@@ -1153,7 +1936,7 @@ var AgentHub = class {
    * a multi-message burst (or a reconnect with a full queue) would silently
    * lose messages that never reach wait/poll again.
    */
-  wait(peerId, timeoutMs, from, signal, ref, threadId) {
+  wait(peerId, timeoutMs, from, signal, ref, threadId, manual, maxMessages = 1) {
     const startedAt = Date.now();
     const matches = (message) => {
       if (from !== void 0 && message.from !== from) return false;
@@ -1161,13 +1944,28 @@ var AgentHub = class {
       if (threadId !== void 0 && message.threadId !== threadId) return false;
       return true;
     };
+    this.reapLeases(peerId, startedAt);
     const queue = this.queues.get(peerId);
+    if (queue !== void 0) {
+      for (let i = queue.length - 1; i >= 0; i--) {
+        const queued = queue[i];
+        if (queued.expiresAt !== void 0 && queued.expiresAt <= startedAt) {
+          queue.splice(i, 1);
+          this.countDrop(peerId, "expired", startedAt);
+        }
+      }
+    }
     if (queue !== void 0 && queue.length > 0) {
-      const index = queue.findIndex(matches);
-      if (index >= 0) {
-        const [queued] = queue.splice(index, 1);
+      const take = Math.max(1, Math.floor(maxMessages));
+      const taken = [];
+      for (let i = 0; i < queue.length && taken.length < take; ) {
+        if (matches(queue[i])) taken.push(...queue.splice(i, 1));
+        else i++;
+      }
+      if (taken.length > 0) {
         this.options.onMailboxesChanged?.();
-        return Promise.resolve({ type: "message", message: queued });
+        const delivered = taken.map((queued) => this.handOut(peerId, queued, manual === true, startedAt));
+        return Promise.resolve(take > 1 ? { type: "messages", messages: delivered } : { type: "message", message: delivered[0] });
       }
     }
     const budget = Math.max(1, Math.min(Math.floor(timeoutMs), this.options.waitTimeoutMs));
@@ -1204,29 +2002,42 @@ var AgentHub = class {
         onAbort,
         ...from !== void 0 ? { from } : {},
         ...ref !== void 0 ? { ref } : {},
-        ...threadId !== void 0 ? { threadId } : {}
+        ...threadId !== void 0 ? { threadId } : {},
+        ...manual === true ? { manual } : {},
+        // A batch request keeps the batch SHAPE even when the wait ends with a
+        // single message, so the caller's field access does not depend on timing.
+        ...maxMessages > 1 ? { batch: true } : {}
       });
       this.waiters.set(peerId, list);
     });
   }
   /** Create a message from `from` addressed to `to` and deliver it. `to` may
    *  be a peer id, {@link BROADCAST}, or a group id. */
-  route(from, to, kind, content, ref, threadId) {
-    if (!this.lastSeen.has(from)) throw new Error(`sender not registered: ${from}`);
+  route(from, to, kind, content, ref, threadId, expiresAt, system = false, priority) {
+    const message = this.compose(from, to, kind, content, ref, threadId, expiresAt, system, priority);
+    this.dispatch(message);
+    return message;
+  }
+  /** Validate, build, and record a message from `from` to `to` (`to` may be a
+   *  peer id, {@link BROADCAST}, or a group id). Composing and dispatching are
+   *  separate steps because a caller may need ledger state to exist before
+   *  anything reaches a recipient — {@link sendTask} books delivery times. */
+  compose(from, to, kind, content, ref, threadId, expiresAt, system = false, priority) {
+    if (!system && !this.lastSeen.has(from)) throw new Error(`sender not registered: ${from}`);
     const group = this.groups.get(to);
-    if (to !== BROADCAST && group === void 0 && !this.lastSeen.has(to)) {
+    const known = this.lastSeen.has(to) || this.parkedAt.has(to);
+    if (to !== BROADCAST && group === void 0 && !known) {
       throw new Error(`unknown recipient: ${to} (registered peers: ${this.peers().join(", ") || "none"})`);
     }
     let hop = 0;
     if (ref !== void 0) {
       const parent = this.historyRing.findLast((m) => m.id === ref);
-      hop = (parent?.hop ?? 0) + 1;
-      if (hop > MAX_HOP) {
-        throw new Error(`hop limit exceeded (max ${MAX_HOP}): start a new task/thread instead of extending this chain`);
-      }
+      const ceiling = kind === "task" && parent?.kind === "task" ? MAX_HOP : MAX_REPLY_CHAIN;
+      hop = Math.min((parent?.hop ?? 0) + 1, ceiling);
     }
     const message = {
       id: randomUUID(),
+      seq: ++this.seqCounter,
       from,
       to,
       kind,
@@ -1235,27 +2046,45 @@ var AgentHub = class {
       ...threadId !== void 0 ? { threadId } : {},
       ...group !== void 0 ? { channel: group.id } : {},
       ...hop > 0 ? { hop } : {},
+      ...expiresAt !== void 0 ? { expiresAt } : {},
+      // Only a real priority is stored: an unset one must not appear on the wire,
+      // or every reader has to distinguish 0 from "absent" for no reason.
+      ...priority !== void 0 ? { priority } : {},
       ts: Date.now()
     };
-    this.lastSeen.set(from, message.ts);
+    if (!system) this.lastSeen.set(from, message.ts);
+    this.bumpTraffic(from, "sent");
+    if (kind === "ack") this.bumpTraffic(from, "acked");
     this.remember(message);
-    if (to === BROADCAST) {
-      for (const peer of this.peers()) {
-        if (peer !== from) this.deliver(peer, message);
+    return message;
+  }
+  /** Fan a composed message out to its recipients: broadcast, group members,
+   *  or the single addressed peer. */
+  dispatch(message) {
+    if (message.to === BROADCAST) {
+      for (const peer of this.audience()) {
+        if (peer !== message.from) this.deliver(peer, message);
       }
-    } else if (group !== void 0) {
+      return;
+    }
+    const group = this.groups.get(message.to);
+    if (group !== void 0) {
       for (const member of group.members) {
-        if (member !== from) this.deliver(member, message);
+        if (member !== message.from) this.deliver(member, message);
       }
-    } else {
-      this.deliver(to, message);
+      return;
     }
-    return message;
+    this.deliver(message.to, message);
   }
   /** Queue or hand off a message; wake the first matching waiter for its target.
    *  History / onMessage are recorded by the caller (route / sendToGroup) —
    *  exactly once per message, never per fan-out target. */
   deliver(target, message) {
+    this.bumpTraffic(target, "received");
+    if (message.expiresAt !== void 0 && message.expiresAt <= Date.now()) {
+      this.countDrop(target, "expired", Date.now());
+      return;
+    }
     const list = this.waiters.get(target) ?? [];
     const index = list.findIndex((waiter) => {
       if (waiter.from !== void 0 && waiter.from !== message.from) return false;
@@ -1268,14 +2097,26 @@ var AgentHub = class {
       const [waiter] = list.splice(index, 1);
       this.waiters.set(target, list);
       clearTimeout(waiter.timer);
-      waiter.resolve({ type: "message", message });
+      const delivered = this.handOut(target, message, waiter.manual === true, message.ts);
+      waiter.resolve(waiter.batch === true ? { type: "messages", messages: [delivered] } : { type: "message", message: delivered });
+      return;
+    }
+    if (!this.takeToken(target, Date.now())) {
+      this.countDrop(target, "rate", Date.now());
       return;
     }
     const queue = this.queues.get(target) ?? [];
-    if (queue.length >= this.options.maxQueue) queue.shift();
-    queue.push(message);
+    if (queue.length >= this.options.maxQueue) {
+      const lowest = priorityOf(queue[queue.length - 1]);
+      let victim = queue.length - 1;
+      while (victim > 0 && priorityOf(queue[victim - 1]) === lowest) victim--;
+      queue.splice(victim, 1);
+      this.countDrop(target, "overflow", Date.now());
+    }
+    insertByPriority(queue, [message]);
     this.queues.set(target, queue);
     this.options.onQueued?.(message, target);
+    if (message.kind === "task") this.options.onTaskQueued?.(message, target);
   }
   /** Append a sent message to the history ring (and fire the persistence /
    * relay hooks). Exactly one call per message — see route() / sendToGroup(). */
@@ -1285,6 +2126,20 @@ var AgentHub = class {
     this.options.onMessage?.(message);
   }
 };
+function importHop(value) {
+  return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : void 0;
+}
+function insertByPriority(queue, messages) {
+  for (const message of messages) {
+    let at = queue.length;
+    while (at > 0 && priorityOf(queue[at - 1]) < priorityOf(message)) at--;
+    queue.splice(at, 0, message);
+  }
+}
+function priorityOf(message) {
+  const value = message.priority;
+  return value === 1 || value === 2 ? value : 0;
+}
 function drainFrom(queue, from) {
   const kept = [];
   const drained = [];
@@ -1306,6 +2161,7 @@ import { existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSyn
 import { dirname } from "node:path";
 var ANON_JOIN_PEER = "__join__";
 var TOKEN_PATTERN = /^[A-Za-z0-9._:-]{16,128}$/;
+var PLACEHOLDER_TOKEN = /CHANGE[-_]?ME/i;
 function loadTokenFile(file) {
   let parsed;
   try {
@@ -1324,6 +2180,9 @@ function loadTokenFile(file) {
     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 (PLACEHOLDER_TOKEN.test(token)) {
+      throw new Error(msg("uses the example placeholder token \u2014 generate one with `agent-comm-hub auth gen`"));
+    }
     if (typeof peer !== "string" || !PEER_ID_PATTERN.test(peer) || peer === "all") {
       throw new Error(msg(`has an invalid peer id '${String(peer)}'`));
     }
@@ -1339,8 +2198,19 @@ function loadTokenFile(file) {
     peers.add(peer);
   });
   if (table.size === 0) throw new Error(`auth token file ${file}: no tokens defined`);
+  warnIfTokenFileIsReadableByOthers(file);
   return table;
 }
+function warnIfTokenFileIsReadableByOthers(file) {
+  if (process.platform === "win32") return;
+  try {
+    const mode = statSync(file).mode & 511;
+    if ((mode & 63) !== 0) {
+      console.warn(`warning: ${file} is readable by group/other (mode ${mode.toString(8)}) \u2014 chmod 600 it`);
+    }
+  } catch {
+  }
+}
 function tokenTable(map) {
   return {
     authenticate: (token) => token === void 0 ? void 0 : map.get(token)
@@ -1436,6 +2306,9 @@ function loadTokenFileVoid(rows) {
   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 (PLACEHOLDER_TOKEN.test(token)) {
+      throw new Error(`example placeholder token for peer '${peer}' \u2014 generate one with \`agent-comm-hub auth gen\``);
+    }
     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");
@@ -1455,6 +2328,9 @@ function present(message) {
     ...channel !== void 0 ? { channel } : {},
     ...threadId !== void 0 ? { threadId } : {},
     ...hop !== void 0 ? { hop } : {},
+    // A2A speaks `taskId` / `contextId`; our names stay, these ride along.
+    ...message.kind === "ack" && ref !== void 0 ? { taskId: ref } : {},
+    ...threadId !== void 0 ? { contextId: threadId } : {},
     content: decodeContent(message.kind, message.content)
   };
 }
@@ -1519,13 +2395,28 @@ function rosterFor(hub, registry) {
       ...alias !== void 0 ? { alias } : {},
       ...clientName !== void 0 ? { clientName } : {},
       ...clientVersion !== void 0 ? { clientVersion } : {},
+      // The announced card rides with the roster: `bridge_peers` is how an agent
+      // sees who else is here, and a card nobody can read is not announced.
+      ...profile?.card !== void 0 ? { card: profile.card } : {},
       ...peerAnon.get(peer.id) === true ? { anonymous: true } : {},
       ...ips !== void 0 && ips.length > 0 ? { clientIps: ips } : {},
       connected: peer.connected,
+      // W7: keep the reachability verdict and the queue depth in the tool output —
+      // `connected: false` alone cannot say "idle, will read it later" apart from
+      // "gone, and your message is nowhere".
+      reachable: peer.reachable,
+      queued: peer.queued,
       lastSeenMs: peer.lastSeenMs
     };
   });
 }
+function isManagerCaller(registry, sessionId, peer, options) {
+  if (registry.tokenFor(sessionId)?.role === "manager") return true;
+  if (options.managerTokenRequired === true) return registry.isManagerSession(sessionId);
+  const managers = options.managerPeers ?? "all";
+  if (managers === "all") return true;
+  return peer !== void 0 && managers.has(peer);
+}
 function hubTools(hub, registry, options) {
   const schema = (properties, required = []) => ({
     type: "object",
@@ -1536,6 +2427,86 @@ function hubTools(hub, registry, options) {
   const str = (description) => ({ type: "string", description });
   const int = (description) => ({ type: "integer", description });
   const optStr = str;
+  const priorityField = () => ({
+    type: "integer",
+    enum: [0, 1, 2],
+    description: "Delivery importance inside the recipient's mailbox: 2 beats 1 beats 0. Default 0 (plain FIFO). Also decides what overflow drops \u2014 the LEAST important queued message goes, not the oldest."
+  });
+  const optPriority = (value) => value === 0 || value === 1 || value === 2 ? { priority: value } : {};
+  const idList = (value, tool) => {
+    if (!Array.isArray(value)) throw new Error(`${tool} expects ids: an array of message ids`);
+    const ids = value.filter((id) => typeof id === "string" && id !== "");
+    if (ids.length === 0) throw new Error(`${tool} expects at least one message id`);
+    return ids;
+  };
+  const deadline = (value) => {
+    const at = Number(value);
+    if (!Number.isFinite(at) || at <= 0) throw new Error(`invalid expiresAt: ${String(value)} (expected epoch milliseconds)`);
+    if (at <= Date.now()) throw new Error(`expiresAt is already in the past: ${new Date(at).toISOString()}`);
+    return at;
+  };
+  const parseArtifacts = (value) => {
+    if (value === void 0) return void 0;
+    if (!Array.isArray(value)) throw new Error("artifacts must be an array of {name, text?/url?} objects");
+    const out = [];
+    for (const [index, entry] of value.entries()) {
+      if (typeof entry !== "object" || entry === null) throw new Error(`artifacts[${index}] must be an object`);
+      const raw = entry;
+      if (typeof raw.name !== "string" || raw.name === "") throw new Error(`artifacts[${index}].name is required`);
+      const artifact = { name: raw.name };
+      if (typeof raw.mimeType === "string" && raw.mimeType !== "") artifact.mimeType = raw.mimeType;
+      if (typeof raw.text === "string") artifact.text = raw.text;
+      if (typeof raw.url === "string" && raw.url !== "") artifact.url = raw.url;
+      if (artifact.text === void 0 && artifact.url === void 0) {
+        throw new Error(`artifacts[${index}] needs text or url \u2014 an artifact with neither says nothing`);
+      }
+      out.push(artifact);
+    }
+    return out.length > 0 ? out : void 0;
+  };
+  const parseCard = (value) => {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) throw new Error("card must be an object");
+    const raw = value;
+    const card = {};
+    if (raw.skills !== void 0) {
+      if (!Array.isArray(raw.skills)) throw new Error("card.skills must be an array");
+      card.skills = raw.skills.map((entry, index) => {
+        if (typeof entry !== "object" || entry === null) throw new Error(`card.skills[${index}] must be an object`);
+        const skill = entry;
+        if (typeof skill.id !== "string" || skill.id === "") throw new Error(`card.skills[${index}].id is required`);
+        if (typeof skill.name !== "string" || skill.name === "") throw new Error(`card.skills[${index}].name is required`);
+        return {
+          id: skill.id,
+          name: skill.name,
+          ...typeof skill.description === "string" ? { description: skill.description } : {},
+          ...Array.isArray(skill.tags) ? { tags: skill.tags.filter((tag) => typeof tag === "string") } : {}
+        };
+      });
+    }
+    if (raw.acceptsTasks !== void 0) {
+      if (typeof raw.acceptsTasks !== "boolean") throw new Error("card.acceptsTasks must be a boolean");
+      card.acceptsTasks = raw.acceptsTasks;
+    }
+    if (raw.concurrency !== void 0) {
+      if (!Number.isInteger(raw.concurrency) || raw.concurrency < 0) throw new Error("card.concurrency must be a non-negative integer");
+      card.concurrency = raw.concurrency;
+    }
+    for (const key of ["inputModes", "outputModes"]) {
+      const list = raw[key];
+      if (list === void 0) continue;
+      if (!Array.isArray(list)) throw new Error(`card.${key} must be an array of strings`);
+      card[key] = list.filter((entry) => typeof entry === "string");
+    }
+    if (raw.runner !== void 0) {
+      if (!["herdr", "cli", "http", "none"].includes(String(raw.runner))) throw new Error("card.runner must be one of herdr | cli | http | none");
+      card.runner = raw.runner;
+    }
+    if (raw.endpoint !== void 0) {
+      if (typeof raw.endpoint !== "string" || raw.endpoint === "") throw new Error("card.endpoint must be a non-empty string");
+      card.endpoint = raw.endpoint;
+    }
+    return card;
+  };
   const requirePeer = (sessionId) => {
     const bound = registry.peerFor(sessionId);
     if (bound !== void 0) {
@@ -1552,16 +2523,26 @@ function hubTools(hub, registry, options) {
   const receipt = (message) => ({
     ok: true,
     id: message.id,
+    // The sender needs this back: it is the cursor to record.
+    ...message.seq !== void 0 ? { seq: message.seq } : {},
     from: message.from,
     to: message.to,
     kind: message.kind,
     ...message.ref !== void 0 ? { ref: message.ref } : {},
     ...message.channel !== void 0 ? { channel: message.channel } : {},
+    // A2A aliases (additive): a task receipt answers with `taskId`, and a
+    // threaded message carries its `contextId`.
+    ...message.kind === "task" ? { taskId: message.id } : {},
+    ...message.threadId !== void 0 ? { contextId: message.threadId } : {},
     ...message.threadId !== void 0 ? { threadId: message.threadId } : {},
     ...message.hop !== void 0 ? { hop: message.hop } : {},
     ts: message.ts
   });
-  const presentWait = (result) => result.type === "timeout" ? result : { type: "message", message: present(result.message) };
+  const presentWait = (result) => {
+    if (result.type === "timeout") return result;
+    if (result.type === "messages") return { type: "messages", messages: result.messages.map(present) };
+    return { type: "message", message: present(result.message) };
+  };
   const checkControl = (peer) => {
     const herdr = options.herdr;
     if (herdr === void 0) {
@@ -1574,17 +2555,27 @@ 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`);
-    }
+    if (isManagerCaller(registry, sessionId, peer, options)) return;
+    throw new Error(
+      options.managerTokenRequired === true ? `peer '${peer}' is not a hub manager \u2014 ${action} requires the manager token (Authorization: Bearer <token>)` : `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));
     return statuses.length > 0 ? statuses : void 0;
   };
+  const requireArgs = (tool, handler) => {
+    const required = tool.inputSchema.required ?? [];
+    if (required.length === 0) return handler;
+    return async (args, sessionId) => {
+      const missing = required.filter((name) => args?.[name] === void 0);
+      if (missing.length > 0) {
+        throw new Error(`missing required argument(s) for ${tool.name}: ${missing.join(", ")}`);
+      }
+      return handler(args, sessionId);
+    };
+  };
   const wrap = (peerAware, handler) => async (args, sessionId) => {
     const peer = peerAware ? requirePeer(sessionId) : "";
     return handler(args, peer, sessionId);
@@ -1598,13 +2589,20 @@ function hubTools(hub, registry, options) {
         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);
+        const boundId = registry.peerFor(sessionId);
+        const peerId = args.peerId === void 0 ? boundId : String(args.peerId);
+        if (peerId === void 0) {
+          throw new Error('no peer to register \u2014 pass peerId (e.g. {"peerId":"mavis"}); this session is not bound to a peer yet');
+        }
         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)`);
         }
+        if (peerId === HUB_PEER) {
+          throw new Error(`reserved peer id: ${peerId} (the hub uses it for its own notices)`);
+        }
         const alias = args.alias === void 0 ? void 0 : sanitizeAlias(String(args.alias));
         const tokenPeer = registry.tokenFor(sessionId)?.peer;
         if (tokenPeer !== void 0 && peerId !== tokenPeer) {
@@ -1623,8 +2621,8 @@ function hubTools(hub, registry, options) {
             if (registry.attachedCount(current) === 0) hub.unregister(current);
           }
         }
-        if (!hub.has(peerId)) hub.register(peerId);
         registry.bindPeer(sessionId, peerId);
+        if (!hub.has(peerId)) hub.register(peerId);
         registry.clearSuppress(sessionId);
         hub.touch(peerId);
         if (alias !== void 0) hub.setAlias(peerId, alias);
@@ -1652,7 +2650,7 @@ function hubTools(hub, registry, options) {
         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)) {
+        if (!hub.has(target) && !hub.isParked(target)) {
           return { ok: true, peerId: null, kicked: false };
         }
         hub.unregister(target);
@@ -1700,32 +2698,67 @@ function hubTools(hub, registry, options) {
     },
     {
       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, a group id, or "all" to broadcast. Optional `threadId` groups multi-turn dialogs; optional `ref` marks a reply-to.',
+      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, a group id, or "all" to broadcast. Optional `threadId` groups multi-turn dialogs; optional `ref` marks a reply-to and carries the chain depth in `hop`. Reply chains are counted, not enforced (50 hops for chat/ack, 5 for a task replying to a task): past the ceiling the message and its `ref` are delivered unchanged and only `hop` stops counting, so nothing is ever refused and no correlation is lost.',
       inputSchema: schema(
         {
           to: str('Target peerId, group id, or "all" to broadcast.'),
           message: str("The message text."),
           threadId: optStr("Optional conversation / workflow thread id."),
-          ref: optStr("Optional reply-to message id.")
+          priority: priorityField(),
+          ref: optStr("Optional reply-to message id."),
+          expiresAt: int("Optional absolute epoch-ms deadline. A message still queued (or about to be handed over) after it is dropped and counted as droppedExpired instead of delivered \u2014 a stale instruction is worse than none.")
         },
         ["to", "message"]
       ),
       handler: wrap(true, async (args, peer) => receipt(hub.send(peer, String(args.to), "chat", String(args.message), {
         ...args.threadId !== void 0 ? { threadId: String(args.threadId) } : {},
-        ...args.ref !== void 0 ? { ref: String(args.ref) } : {}
+        ...optPriority(args.priority),
+        ...args.ref !== void 0 ? { ref: String(args.ref) } : {},
+        ...args.expiresAt !== void 0 ? { expiresAt: deadline(args.expiresAt) } : {}
       })))
     },
+    {
+      name: "bridge_notice",
+      description: 'Send a system-flavoured notice to another agent (peer, group id, or "all"). Use it for things the recipient should see differently from chat: "your mailbox dropped 3 messages", "hub restarting", "that task was cancelled". `level` is info | warn | error (default info). The payload is structured ({message, level}) rather than plain text, and the message is a normal routed message \u2014 it queues for a parked peer like any other. It does NOT create a task ledger row.',
+      inputSchema: schema(
+        {
+          to: str('Target peerId, group id, or "all" to broadcast.'),
+          message: str("The notice text."),
+          level: { type: "string", enum: ["info", "warn", "error"], description: "Severity (default info)." },
+          threadId: optStr("Optional conversation / workflow thread id."),
+          priority: priorityField()
+        },
+        ["to", "message"]
+      ),
+      handler: wrap(true, async (args, peer) => {
+        const level = args.level === void 0 ? void 0 : String(args.level);
+        if (level !== void 0 && level !== "info" && level !== "warn" && level !== "error") {
+          throw new Error(`invalid level: ${level} (expected info | warn | error)`);
+        }
+        const payload = {
+          message: String(args.message),
+          ...level !== void 0 ? { level } : {}
+        };
+        return receipt(hub.send(peer, String(args.to), "notice", encodeContent(payload), {
+          ...args.threadId !== void 0 ? { threadId: String(args.threadId) } : {},
+          ...optPriority(args.priority)
+        }));
+      })
+    },
     {
       name: "bridge_task",
-      description: 'Delegate a structured task to another agent (peer, group, or "all"). The assignee acks with accepted | working | rejected | done | failed (bridge_ack). Track with bridge_task_status(ref) / bridge_tasks; wait for the ack with bridge_wait({ ref }). Optional timeoutMs marks the task `timeout` when the SLA expires without a terminal ack.',
+      description: 'Delegate a structured task to another agent (peer, group, or "all"). The assignee acks with accepted | working | rejected | done | failed (bridge_ack). Track with bridge_task_status(ref) / bridge_tasks; wait for the ack with bridge_wait({ ref }). Optional timeoutMs marks the task `timeout` when the SLA expires without a terminal ack; any positive duration is honored, including multi-day deadlines (the hub re-arms its timer instead of overflowing it). Optional `ref` names the task this one answers \u2014 when the parent is itself a task the new one is a re-delegation, and `hop` counts that chain depth (saturating at 5; the task is always delivered).',
       inputSchema: schema(
         {
           to: str('Target peerId, group id, or "all" to broadcast.'),
           prompt: str("What the receiving agent should do."),
           context: optStr("Optional background information for the task."),
           deliverable: optStr("Optional expected deliverable description."),
-          timeoutMs: int("Optional soft SLA in ms; hub marks the task timeout when it expires."),
-          threadId: optStr("Optional conversation / workflow thread id.")
+          timeoutMs: int("Optional soft SLA in ms from now (e.g. 30000). No upper bound \u2014 a deadline past ~24.8 days is honored as well."),
+          threadId: optStr("Optional conversation / workflow thread id."),
+          priority: priorityField(),
+          ref: optStr("Optional: the task message id this one answers (makes it a re-delegation when the parent is a task; that chain is capped at 5 hops)."),
+          expiresAt: int("Optional absolute epoch-ms deadline for DELIVERY (distinct from timeoutMs, which is the assignee's SLA after it arrives). A task still undelivered at that moment is dropped and counted as droppedExpired.")
         },
         ["to", "prompt"]
       ),
@@ -1734,8 +2767,9 @@ function hubTools(hub, registry, options) {
         ...args.context !== void 0 ? { context: String(args.context) } : {},
         ...args.deliverable !== void 0 ? { deliverable: String(args.deliverable) } : {},
         ...args.timeoutMs !== void 0 ? { timeoutMs: Number(args.timeoutMs) } : {},
-        ...args.threadId !== void 0 ? { threadId: String(args.threadId) } : {}
-      })))
+        ...args.threadId !== void 0 ? { threadId: String(args.threadId) } : {},
+        ...optPriority(args.priority)
+      }, args.ref === void 0 ? void 0 : String(args.ref), args.expiresAt === void 0 ? void 0 : deadline(args.expiresAt))))
     },
     {
       name: "bridge_ack",
@@ -1743,21 +2777,24 @@ function hubTools(hub, registry, options) {
       inputSchema: schema(
         {
           ref: str("The id of the message being acknowledged."),
-          status: { type: "string", enum: ["accepted", "working", "rejected", "done", "failed"], description: "acknowledgement status." },
+          status: { type: "string", enum: [...CLIENT_ACK_STATUSES], description: "acknowledgement status. `input-required` is an INTERRUPT: it asks the sender for information without ending the task \u2014 the sender answers with bridge_task_input and work resumes. To stop a task use bridge_task_cancel, not an ack." },
           note: optStr("Optional explanation for the acknowledgement."),
+          artifacts: { type: "array", description: "Optional output attached to this ack: [{name, mimeType?, text? | url?}]. A `done` ack with artifacts is how you hand back what you produced; they show up in bridge_task_status.", items: { type: "object" } },
           progress: int("Optional 0-100 progress (meaningful with status=working).")
         },
         ["ref", "status"]
       ),
       handler: wrap(true, async (args, peer) => {
         const status = String(args.status);
-        const valid = ["accepted", "working", "rejected", "done", "failed"];
+        const valid = CLIENT_ACK_STATUSES;
         if (!valid.includes(status)) {
           throw new Error(`invalid ack status: ${status} (expected ${valid.join(" | ")})`);
         }
+        const artifacts = parseArtifacts(args.artifacts);
         return receipt(hub.sendAck(peer, String(args.ref), {
           status,
           ...args.note !== void 0 ? { note: String(args.note) } : {},
+          ...artifacts !== void 0 ? { artifacts } : {},
           ...args.progress !== void 0 ? { progress: Number(args.progress) } : {}
         }));
       })
@@ -1796,26 +2833,99 @@ function hubTools(hub, registry, options) {
     },
     {
       name: "bridge_task_status",
-      description: "Status of one delegated task: current ledger state (pending \u2192 accepted/working \u2192 done/failed/timeout, or rejected), the original prompt/context/deliverable, per-assignee state, and every ack event (who, status, note, progress, when). Use the task message id (the same id you pass as bridge_ack ref).",
+      description: "Status of one delegated task: current ledger state (pending \u2192 accepted/working \u2192 done/failed/timeout, or rejected), the original prompt/context/deliverable, per-assignee state, and every ack event (who, status, note, progress, when). Use the task message id (the same id you pass as bridge_ack ref). Readable by the sender, by an assignee (a group task carries the GROUP id in `to`, so its assignees read it through their assignee row) and by a group member; everyone else needs manager rights.",
       inputSchema: schema({ ref: str("Task message id (the id returned by bridge_task, also used as ack ref).") }, ["ref"]),
       handler: wrap(true, async (args, peer, sessionId) => {
         const ref = String(args.ref);
         const task = hub.taskOf(ref);
         if (task === void 0) throw new Error(`unknown task: ${ref}`);
-        if (task.from !== peer && task.to !== peer && task.to !== BROADCAST) {
+        const isAssignee = task.assignees.some((assignee) => assignee.peerId === peer);
+        const isGroupMember = hub.groupOf(task.to)?.members.includes(peer) ?? false;
+        if (task.from !== peer && task.to !== peer && task.to !== BROADCAST && !isAssignee && !isGroupMember) {
           requireManager(peer, `reading task '${ref}'`, sessionId);
         }
-        return { task };
+        return {
+          task,
+          // A2A naming aliases: the same task under the names an A2A client
+          // already uses. `task.id` stays authoritative.
+          taskId: task.id,
+          ...task.threadId !== void 0 ? { contextId: task.threadId } : {},
+          a2aState: a2aState(task.status)
+        };
       })
     },
+    {
+      name: "bridge_task_cancel",
+      description: "Cancel a delegated task. Either side may do it: the sender stops work it no longer wants, an assignee reports it will not finish. The cancel is recorded on the ledger (`canceled`, terminal) and routed to the OTHER side so whoever did not press the button finds out. Cancelling an already-terminal task is an error, not a silent no-op.",
+      inputSchema: schema(
+        {
+          ref: str("Task message id (the id returned by bridge_task)."),
+          reason: optStr("Optional reason, delivered with the cancel and kept on the timeline.")
+        },
+        ["ref"]
+      ),
+      handler: wrap(true, async (args, peer) => receipt(hub.cancelTask(peer, String(args.ref), args.reason === void 0 ? void 0 : String(args.reason))))
+    },
+    {
+      name: "bridge_task_input",
+      description: "Answer a task whose assignee acked `input-required`: only the task's SENDER can answer it. The answer is delivered to the waiting assignee as an ack carrying the task id (so its `bridge_wait { ref }` picks it up) and the task resumes (`working`). An assignee does not call this \u2014 it resumes by acking `working` itself.",
+      inputSchema: schema(
+        {
+          ref: str("Task message id."),
+          input: str("The information the assignee asked for.")
+        },
+        ["ref", "input"]
+      ),
+      handler: wrap(true, async (args, peer) => receipt(hub.taskInput(peer, String(args.ref), String(args.input))))
+    },
+    {
+      name: "bridge_announce",
+      description: "Say what you can do, so other agents can find you: skills (id + name, optional tags), whether you accept tasks, how many at once, your input/output modes, and how you are executed when not polling. Replaces your previous card. `bridge_discover` only offers peers that set acceptsTasks \u2014 announcing a skill alone does not mean you want work.",
+      inputSchema: schema(
+        {
+          card: {
+            type: "object",
+            description: 'Your card: {skills?: [{id, name, description?, tags?}], acceptsTasks?: boolean, concurrency?: number, inputModes?: string[], outputModes?: string[], runner?: "herdr"|"cli"|"http"|"none", endpoint?: string}.'
+          }
+        },
+        ["card"]
+      ),
+      handler: wrap(true, async (args, peer) => {
+        const profile = hub.announceCard(peer, parseCard(args.card));
+        return { ok: true, peer, card: profile.card };
+      })
+    },
+    {
+      name: "bridge_discover",
+      description: "Find a peer to hand work to. Returns the peers whose announced card matches, each with its current load (queued mailbox depth, live waiters, non-terminal tasks assigned to it). By default only peers that announced `acceptsTasks: true` are returned \u2014 pass acceptsTasks:false to list peers regardless. Peers that never announced a card are never returned.",
+      inputSchema: schema(
+        {
+          skill: optStr("Only peers declaring this skill id."),
+          tag: optStr("Only peers whose skills carry this tag."),
+          acceptsTasks: { type: "boolean", description: "Require the peer to accept tasks (default true). Pass false to drop that requirement." },
+          idleOnly: { type: "boolean", description: "Only peers with nothing queued, no waiter and no running task." }
+        },
+        []
+      ),
+      handler: wrap(true, async (args) => ({
+        peers: hub.discover({
+          ...args.skill !== void 0 ? { skill: String(args.skill) } : {},
+          ...args.tag !== void 0 ? { tag: String(args.tag) } : {},
+          ...args.acceptsTasks !== void 0 ? { acceptsTasks: args.acceptsTasks === true } : {},
+          ...args.idleOnly !== void 0 ? { idleOnly: args.idleOnly === true } : {}
+        })
+      }))
+    },
     {
       name: "bridge_wait",
-      description: "Wait (long-poll) for the next message addressed to you. Resolves immediately when one is queued; otherwise blocks until one arrives or the timeout fires. `from` narrows to one sender. `ref` waits specifically for the ack of that task id. `threadId` narrows to one conversation thread. Loop this tool to hold a real-time conversation.",
+      description: 'Wait (long-poll) for the next message addressed to you. Resolves immediately when one is queued; otherwise blocks until one arrives or the timeout fires. `from` narrows to one sender. `ref` waits specifically for the ack of that task id. `threadId` narrows to one conversation thread. Loop this tool to hold a real-time conversation. With `ack: "manual"` the message is LEASED rather than consumed: it comes back (with `attempts` incremented) if you do not call bridge_commit in time, and is dead-lettered after too many hand-outs. Use it when losing a message would be worse than handling one twice.',
       inputSchema: schema({
         from: optStr("Only wait for messages from this peerId."),
         ref: optStr("Only wait for the ack of this task message id (bridge_task id)."),
         threadId: optStr("Only wait for messages carrying this threadId."),
-        timeoutMs: int(`Max wait in milliseconds (default ${DEFAULT_WAIT_MS}, ceiling is server waitTimeoutMs).`)
+        timeoutMs: int(`Max wait in milliseconds (default ${DEFAULT_WAIT_MS}, ceiling is server waitTimeoutMs).`),
+        maxMessages: int('Take up to this many already-queued messages in one call (default 1). With > 1 the result is {type:"messages", messages:[\u2026]} instead of {type:"message", message:{\u2026}} \u2014 the shape follows the request, not how many happened to be queued.'),
+        ack: { type: "string", enum: ["auto", "manual"], description: '"auto" (default) consumes the message; "manual" leases it until bridge_commit (or bridge_nack).' }
       }),
       handler: wrap(true, async (args, peer) => presentWait(await hub.wait(
         peer,
@@ -1823,14 +2933,39 @@ function hubTools(hub, registry, options) {
         args.from === void 0 ? void 0 : String(args.from),
         void 0,
         args.ref === void 0 ? void 0 : String(args.ref),
-        args.threadId === void 0 ? void 0 : String(args.threadId)
+        args.threadId === void 0 ? void 0 : String(args.threadId),
+        args.ack === "manual",
+        args.maxMessages === void 0 ? 1 : Math.max(1, Number(args.maxMessages))
       )))
     },
     {
       name: "bridge_poll",
-      description: "Non-blocking: drain every message currently queued for you. Empty list when nothing is waiting. `from` narrows to one sender.",
-      inputSchema: schema({ from: optStr("Only drain messages from this peerId.") }),
-      handler: wrap(true, async (args, peer) => ({ messages: hub.poll(peer, args.from === void 0 ? void 0 : String(args.from)).map(present) }))
+      description: 'Non-blocking: drain every message currently queued for you. Empty list when nothing is waiting. `from` narrows to one sender. `ack: "manual"` leases what it drains (see bridge_wait) instead of consuming it.',
+      inputSchema: schema({
+        from: optStr("Only drain messages from this peerId."),
+        ack: { type: "string", enum: ["auto", "manual"], description: '"auto" (default) consumes; "manual" leases until bridge_commit.' }
+      }),
+      handler: wrap(true, async (args, peer) => ({
+        messages: hub.poll(peer, args.from === void 0 ? void 0 : String(args.from), { manual: args.ack === "manual" }).map(present)
+      }))
+    },
+    {
+      name: "bridge_commit",
+      description: 'Acknowledge messages you received under a manual lease (bridge_wait / bridge_poll with ack: "manual"). Until you commit, the hub keeps them in flight and hands them out again once the lease expires \u2014 committing is what makes handling them final. Returns how many leases were released.',
+      inputSchema: schema(
+        { ids: { type: "array", items: { type: "string" }, description: "Message ids you received and have finished handling." } },
+        ["ids"]
+      ),
+      handler: wrap(true, async (args, peer) => ({ committed: hub.commit(peer, idList(args.ids, "bridge_commit")) }))
+    },
+    {
+      name: "bridge_nack",
+      description: "Give leased messages back NOW instead of waiting for the lease to expire \u2014 use it when handling failed. They return to the head of your queue (another session of the same peer can retry), their attempt count is kept, and a message that keeps failing ends up dead-lettered instead of looping. It also revives a dead-lettered message (resetting its attempts). Returns how many were requeued.",
+      inputSchema: schema(
+        { ids: { type: "array", items: { type: "string" }, description: "Message ids to give back." } },
+        ["ids"]
+      ),
+      handler: wrap(true, async (args, peer) => ({ requeued: hub.nack(peer, idList(args.ids, "bridge_nack")) }))
     },
     {
       name: "bridge_status",
@@ -1838,6 +2973,21 @@ function hubTools(hub, registry, options) {
       inputSchema: schema({}),
       handler: wrap(true, async () => hub.status(livePeersFor(registry)))
     },
+    {
+      name: "bridge_metrics",
+      description: "Operational counters, per peer and global. Per peer: sent / received / acked (traffic counters that survive a drained queue), queued, inFlight, deadLettered, droppedOverflow, droppedExpired, connected. Global: messagesTotal (the history seq \u2014 a true count, not a rolling window), peers / connectedPeers / parkedPeers, waitersNow, queuedTotal, tasksByStatus, and the drop / lease totals. Every number is derived from live state or from a counter the hub already keeps; nothing is estimated. Counters are per run and reset on restart.",
+      inputSchema: schema({}),
+      handler: wrap(true, async () => hub.metrics())
+    },
+    {
+      name: "bridge_events",
+      description: "Read the hub's own operational event stream, oldest first. These are what the HUB did, not what peers said: `peer_joined` / `peer_left` / `peer_parked` / `mailbox_dropped` / `task_transition` / `runner_started` / `runner_finished`. Each event has a monotonic `seq` (never resets in a run), a `ts`, and a kind-specific `detail`. Pass `since` (exclusive) with the `lastSeq` of your previous call to poll for new events only. `truncated: true` means the window you asked for is older than the ring still holds, so you missed entries \u2014 re-read from the start rather than assuming you saw everything. Events are per-run and in-memory; a restart starts a new sequence.",
+      inputSchema: schema({
+        since: { type: "number", description: "Return only events with a seq greater than this (exclusive)." },
+        limit: { type: "number", description: "Maximum events to return, newest kept (default 100, max 500)." }
+      }),
+      handler: wrap(true, async (args) => hub.events(args))
+    },
     {
       name: "bridge_peers",
       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.",
@@ -1850,10 +3000,16 @@ function hubTools(hub, registry, options) {
       inputSchema: schema({
         peer: optStr('PeerId whose conversation to inspect; "all" = every peer; default: yourself. Other peers / "all" require manager rights.'),
         channel: optStr("Read a group channel history instead of a peer conversation (you must be a member, or a manager)."),
-        limit: int("How many messages to return (default 20).")
+        limit: int("How many messages to return (default 20)."),
+        since: int('Resume cursor: return only messages with seq greater than this. Read bridge_status.lastSeq to start from "now"; omit to include history recorded before cursors existed.')
       }),
       handler: wrap(true, async (args, peer, sessionId) => {
         const limit = Math.min(args.limit === void 0 ? 20 : Number(args.limit), 1e3);
+        const sinceRaw = args.since === void 0 ? void 0 : Number(args.since);
+        if (sinceRaw !== void 0 && (!Number.isFinite(sinceRaw) || sinceRaw < 0)) {
+          throw new Error(`invalid since: ${String(args.since)} (expected a non-negative sequence number)`);
+        }
+        const since = sinceRaw;
         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);
@@ -1863,9 +3019,9 @@ function hubTools(hub, registry, options) {
           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) };
+          return { messages: hub.historyChannel(groupId, limit, since).map(present) };
         }
-        const messages = target === BROADCAST ? hub.historyAll(limit) : hub.history(target, limit);
+        const messages = target === BROADCAST ? hub.historyAll(limit, since) : hub.history(target, limit, since);
         return { messages: messages.map(present) };
       })
     },
@@ -2141,11 +3297,11 @@ function hubTools(hub, registry, options) {
         return read === null ? { matched: null } : { matched: read };
       })
     }
-  ];
+  ].map((tool) => ({ ...tool, handler: requireArgs(tool, tool.handler) }));
 }
 
 // src/mcp-server.ts
-import { randomUUID as randomUUID2 } from "node:crypto";
+import { randomUUID as randomUUID2, timingSafeEqual } from "node:crypto";
 import { readFileSync as readFileSync2 } from "node:fs";
 var ADMIN_PATH = "/admin";
 var ADMIN_API_PATH = "/admin/api";
@@ -2160,6 +3316,7 @@ var SUPPORTED_VERSIONS = ["2025-06-18", "2025-03-26", "2024-11-05"];
 var LATEST_VERSION = SUPPORTED_VERSIONS[0];
 var MAX_BODY_BYTES = 1048576;
 var HEARTBEAT_MS = 2e4;
+var DEFAULT_SESSION_TTL_MS = 30 * 6e4;
 var SessionRegistry = class {
   sessions = /* @__PURE__ */ new Set();
   /** sessionId → peerId claimed via `bridge_register`. */
@@ -2172,8 +3329,17 @@ var SessionRegistry = class {
   ensureSession(sessionId) {
     const id = sessionId ?? randomUUID2();
     this.sessions.add(id);
+    this.lastUsedAt.set(id, Date.now());
     return id;
   }
+  /** Has this session id ever been minted here and not terminated since?
+   *  A request presenting an id the registry does not know must be answered 404
+   *  (spec MUST) so the client starts a new session, instead of being adopted
+   *  silently — which is how a client kept talking to a hub that had restarted
+   *  and already forgotten it. */
+  hasSession(sessionId) {
+    return this.sessions.has(sessionId);
+  }
   /** Peer bound to a session, if any. */
   peerFor(sessionId) {
     if (sessionId === void 0) return void 0;
@@ -2229,6 +3395,47 @@ var SessionRegistry = class {
   isSuppressed(sessionId) {
     return sessionId !== void 0 && this.suppressedAuto.has(sessionId);
   }
+  /** Session → the last time a request presented it.
+   *
+   *  The registry is the only thing that knows a session exists, so it is also the
+   *  only thing that can decide one is finished. Without this the maps below only
+   *  ever grew, `hasSession` was true forever, and "this session is over" was not
+   *  expressible — so the 404 path could never fire for a session the hub had
+   *  genuinely finished with. */
+  lastUsedAt = /* @__PURE__ */ new Map();
+  /** Record that `sessionId` was just used (a request carried its id). */
+  touch(sessionId) {
+    if (sessionId !== void 0 && this.sessions.has(sessionId)) this.lastUsedAt.set(sessionId, Date.now());
+  }
+  /**
+   * Forget sessions that are finished: no live SSE stream, and unused for `ttlMs`.
+   * Returns the ids removed. `ttlMs <= 0` disables reaping.
+   *
+   * Safe because a client that gets 404 is REQUIRED by the spec to send a fresh
+   * `initialize`, and the hub auto-registers it under the same peer id — it comes
+   * back with its mailbox intact. A live SSE stream pins a session regardless of
+   * age: that is the one signal that means "still connected", and it wins.
+   */
+  sweep(now, ttlMs) {
+    if (ttlMs <= 0) return [];
+    const removed = [];
+    for (const sessionId of [...this.sessions]) {
+      if (this.liveStreams.has(sessionId)) continue;
+      const last = this.lastUsedAt.get(sessionId) ?? now;
+      if (now - last <= ttlMs) continue;
+      this.sessions.delete(sessionId);
+      this.lastUsedAt.delete(sessionId);
+      this.peerBindings.delete(sessionId);
+      this.clientNames.delete(sessionId);
+      this.clientVersions.delete(sessionId);
+      this.sessionIps.delete(sessionId);
+      this.tokenBindings.delete(sessionId);
+      this.managerSessions.delete(sessionId);
+      this.suppressedAuto.delete(sessionId);
+      removed.push(sessionId);
+    }
+    return removed;
+  }
   /** 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();
@@ -2247,6 +3454,19 @@ var SessionRegistry = class {
     if (sessionId === void 0) return void 0;
     return this.tokenBindings.get(sessionId);
   }
+  /** Sessions that presented the loopback manager token (`--manager-token`).
+   * Distinct from a token-table identity: loopback mode has no token table, so
+   * the manager secret is the only thing separating "the operator's GUI" from
+   * "any other local MCP client". */
+  managerSessions = /* @__PURE__ */ new Set();
+  /** Remember that this session proved it holds the manager token. */
+  markManagerSession(sessionId) {
+    this.managerSessions.add(sessionId);
+  }
+  /** Did this session present the manager token? */
+  isManagerSession(sessionId) {
+    return sessionId !== void 0 && this.managerSessions.has(sessionId);
+  }
   /** Mark a session's SSE stream open (server→client channel alive). */
   markSseOpen(sessionId) {
     this.liveStreams.add(sessionId);
@@ -2305,7 +3525,7 @@ var SessionRegistry = class {
 var McpStreamableHttpServer = class {
   constructor(tools, info, registry, log = () => {
   }, onInitialize = () => {
-  }, authenticate, adminApi, heartbeatMs) {
+  }, authenticate, adminApi, heartbeatMs, originPolicy, managerToken, sessionTtlMs = DEFAULT_SESSION_TTL_MS) {
     this.tools = tools;
     this.info = info;
     this.registry = registry;
@@ -2314,29 +3534,54 @@ var McpStreamableHttpServer = class {
     this.authenticate = authenticate;
     this.adminApi = adminApi;
     this.heartbeatMs = heartbeatMs;
+    this.originPolicy = originPolicy;
+    this.managerToken = managerToken;
+    this.sessionTtlMs = sessionTtlMs;
   }
   sseStreams = /* @__PURE__ */ new Map();
   heartbeatTimer;
+  sessionSweepTimer;
+  /** Does this request carry the loopback manager token? */
+  presentedManagerToken(req) {
+    if (this.managerToken === void 0) return false;
+    const header = headerValue(req.headers.authorization);
+    if (header === void 0) return false;
+    const match = /^Bearer\s+(.+)$/i.exec(header);
+    return match !== null && secretEquals(match[1].trim(), this.managerToken);
+  }
   /** Attach request handling for `path` (e.g. `/mcp`) to an http server. */
   attach(server, path2) {
     this.heartbeatTimer = setInterval(() => {
       if (this.sseStreams.size === 0) return;
-      this.notifyAll("notifications/message", {
+      this.notifyAll(SSE_METHOD, {
         level: "debug",
         logger: "bridge",
         data: { event: "heartbeat", ts: Date.now() }
       });
     }, this.heartbeatMs ?? HEARTBEAT_MS);
     this.heartbeatTimer.unref?.();
+    if (this.sessionTtlMs > 0) {
+      const interval = Math.min(6e4, Math.max(1e3, this.sessionTtlMs / 4));
+      this.sessionSweepTimer = setInterval(() => {
+        const removed = this.registry.sweep(Date.now(), this.sessionTtlMs);
+        if (removed.length > 0) this.log(`sessions reaped: ${removed.length}`);
+      }, interval);
+      this.sessionSweepTimer.unref?.();
+    }
     server.on("request", (req, res) => {
       const url = new URL(req.url ?? "/", "http://localhost");
+      if (!this.originAllowed(req)) {
+        res.writeHead(403, { ...this.corsFor(req), "Content-Type": "application/json; charset=utf-8", "Mcp-Protocol-Version": messageProtocolVersion(req) });
+        res.end(JSON.stringify({ error: `origin not allowed: ${headerValue(req.headers.origin) ?? ""}` }));
+        return;
+      }
       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 === "/healthz") {
-        res.writeHead(200, { "Content-Type": "application/json; charset=utf-8", ...corsHeaders() });
+        res.writeHead(200, { "Content-Type": "application/json; charset=utf-8", ...this.corsFor(req) });
         res.end(JSON.stringify({ ok: true, ts: Date.now() }));
         return;
       }
@@ -2357,15 +3602,16 @@ var McpStreamableHttpServer = class {
         return;
       }
       if (req.method === "OPTIONS") {
-        res.writeHead(204, corsHeaders()).end();
+        res.writeHead(204, this.corsFor(req)).end();
         return;
       }
-      res.writeHead(405, corsHeaders()).end();
+      res.writeHead(405, { ...this.corsFor(req), "Mcp-Protocol-Version": messageProtocolVersion(req) }).end();
     });
   }
   /** Close all open SSE streams (called on server shutdown). */
   close() {
     if (this.heartbeatTimer !== void 0) clearInterval(this.heartbeatTimer);
+    if (this.sessionSweepTimer !== void 0) clearInterval(this.sessionSweepTimer);
     for (const stream of this.sseStreams.values()) stream.end();
     this.sseStreams.clear();
   }
@@ -2393,33 +3639,107 @@ data: ${JSON.stringify({ jsonrpc: "2.0", method, params })}
       }
     }
   }
+  /**
+   * Cross-origin gate. A request is allowed when:
+   *  - it carries no `Origin` (curl, MCP clients, the desktop app — never browsers), or
+   *  - the origin is explicitly listed (`--allow-origins`, or 'all'), or
+   *  - the origin is a loopback hostname (the bundled admin page, local tooling), or
+   *  - it presents a valid bearer token AND its origin host matches the `Host`
+   *    header (the admin page behind a TLS reverse proxy, where the hub cannot
+   *    know its own public origin).
+   *
+   * The last clause is deliberately credential-gated, not identity-gated: with
+   * `--allow-join` the transport mints an anonymous identity for a request that
+   * carries nothing at all, so testing only `authenticate(req) !== undefined`
+   * would re-open this branch to exactly the rebinding page it exists to stop.
+   * A real `Authorization` header is required as well.
+   */
+  originAllowed(req) {
+    const origin = headerValue(req.headers.origin);
+    if (origin === void 0) return true;
+    const policy = this.originPolicy;
+    if (policy?.allow === "all") return true;
+    if (policy?.allow?.has(origin) === true) return true;
+    if (origin.includes(",") || /\s/.test(origin)) return false;
+    const originHost = originHostname(origin);
+    if (originHost === void 0) return false;
+    if (isLoopbackHost(originHost)) return true;
+    const identity = this.authenticate?.(req);
+    if (identity === void 0 || identity.anonymous === true) return false;
+    const host = headerValue(req.headers.host);
+    return host !== void 0 && hostHeaderName(host) === originHost;
+  }
+  /** CORS headers for one request: echoes the origin only when it is allowed. */
+  corsFor(req) {
+    if (req === void 0) return corsHeaders();
+    const origin = headerValue(req.headers.origin);
+    return corsHeaders(origin !== void 0 && this.originAllowed(req) ? origin : void 0);
+  }
   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" }));
+    let streamIdentity;
+    if (this.authenticate !== void 0) {
+      streamIdentity = this.authenticate(req);
+      if (streamIdentity === void 0) {
+        res.writeHead(401, { ...this.corsFor(req), "Content-Type": "application/json; charset=utf-8", "Mcp-Protocol-Version": messageProtocolVersion(req) });
+        res.end(JSON.stringify({ error: "unauthorized: missing or invalid bearer token" }));
+        return;
+      }
+      const existing = this.registry.sessionIdFor(req);
+      const bound = existing === void 0 ? void 0 : this.registry.tokenFor(existing);
+      const bothAnonymous = bound?.anonymous === true && streamIdentity.anonymous === true;
+      if (bound !== void 0 && !bothAnonymous && (bound.peer !== streamIdentity.peer || bound.role !== streamIdentity.role)) {
+        this.unauthorized(req, res, null, "token does not match this session");
+        return;
+      }
+    }
+    if (this.protocolVersionRejected(req, res)) return;
+    const streamSession = this.registry.sessionIdFor(req);
+    if (streamSession !== void 0 && !this.registry.hasSession(streamSession)) {
+      this.jsonRpcError(req, res, null, -32001, "session not found \u2014 send a new initialize request", void 0, 404);
       return;
     }
-    const sessionId = this.registry.ensureSession(this.registry.sessionIdFor(req));
-    const identity = this.authenticate?.(req);
-    if (identity !== void 0) this.registry.bindToken(sessionId, identity);
+    this.registry.touch(streamSession);
+    const sessionId = this.registry.ensureSession(streamSession);
+    if (this.presentedManagerToken(req)) this.registry.markManagerSession(sessionId);
+    if (streamIdentity !== void 0) this.registry.bindToken(sessionId, streamIdentity);
     res.writeHead(200, {
-      ...corsHeaders(),
+      ...this.corsFor(req),
       "Content-Type": "text/event-stream; charset=utf-8",
       "Cache-Control": "no-cache",
       Connection: "keep-alive",
+      // nginx (and anything else speaking X-Accel) buffers proxied responses by
+      // default, which breaks SSE completely: events sit in the proxy until its
+      // buffer fills or the stream ends, so a client never sees a push. This header
+      // is the in-band way to turn that off — it needs no proxy configuration, and
+      // a proxy that ignores it is unaffected.
+      "X-Accel-Buffering": "no",
+      // Same header the POST path sets: the client should see the version the
+      // server is speaking on every 200, not only on JSON responses.
+      "Mcp-Protocol-Version": messageProtocolVersion(req),
       ...req.headers["mcp-session-id"] ? {} : { "Mcp-Session-Id": sessionId }
     });
     res.write(": connected\n\n");
     this.sseStreams.set(sessionId, res);
     this.registry.markSseOpen(sessionId);
     req.on("close", () => {
-      this.sseStreams.delete(sessionId);
-      this.registry.markSseClosed(sessionId);
+      if (this.sseStreams.get(sessionId) === res) this.sseStreams.delete(sessionId);
+      if (!this.sseStreams.has(sessionId)) 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" });
+  unauthorized(req, res, id, why) {
+    res.writeHead(401, {
+      ...this.corsFor(req),
+      "Content-Type": "application/json; charset=utf-8",
+      // MCP authorization spec: a 401 MUST carry WWW-Authenticate. The hub does not
+      // implement OAuth (authorization is OPTIONAL in MCP), so there is no
+      // resource_metadata to advertise — the bare scheme is still required.
+      "WWW-Authenticate": "Bearer",
+      // Every response names the protocol version the server is speaking, errors
+      // included: a client that only sees 401s still needs to know what it is
+      // talking to before it can decide whether to retry.
+      "Mcp-Protocol-Version": messageProtocolVersion(req)
+    });
     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
@@ -2427,7 +3747,7 @@ data: ${JSON.stringify({ jsonrpc: "2.0", method, params })}
    * 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.writeHead(status, { ...this.corsFor(req), "Content-Type": "application/json; charset=utf-8" });
       res.end(JSON.stringify(body));
     };
     const identity = this.authenticate?.(req);
@@ -2476,49 +3796,57 @@ data: ${JSON.stringify({ jsonrpc: "2.0", method, params })}
     if (this.authenticate !== void 0) {
       authIdentity = this.authenticate(req);
       if (authIdentity === void 0) {
-        this.unauthorized(res, null, "missing or invalid bearer token");
+        this.unauthorized(req, 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");
+        this.unauthorized(req, res, null, "token does not match this session");
         return;
       }
       if (existingSession !== void 0 && bound === void 0 && !authIdentity.anonymous) {
         this.registry.bindToken(existingSession, authIdentity);
       }
     }
+    if (this.protocolVersionRejected(req, res)) return;
+    const presentedSession = this.registry.sessionIdFor(req);
+    if (presentedSession !== void 0 && !this.registry.hasSession(presentedSession)) {
+      this.jsonRpcError(req, res, null, -32001, "session not found \u2014 send a new initialize request", void 0, 404);
+      return;
+    }
+    this.registry.touch(presentedSession);
     let body;
     try {
       body = await readBody(req);
     } catch (error) {
-      this.jsonRpcError(res, null, -32700, `parse error: ${error.message}`);
+      this.jsonRpcError(req, res, null, -32700, `parse error: ${error.message}`);
       return;
     }
     let message;
     try {
       message = JSON.parse(body.toString("utf8"));
     } catch {
-      this.jsonRpcError(res, null, -32700, "parse error: invalid JSON");
+      this.jsonRpcError(req, res, null, -32700, "parse error: invalid JSON");
       return;
     }
     if (typeof message !== "object" || message === null || message.method === void 0) {
-      this.jsonRpcError(res, message?.id ?? null, -32600, "invalid request");
+      this.jsonRpcError(req, res, message?.id ?? null, -32600, "invalid request");
       return;
     }
     const id = message.id ?? null;
     const sessionId = this.registry.sessionIdFor(req);
     if (sessionId !== void 0) this.registry.sessionIps.set(sessionId, clientIp(req));
+    if (sessionId !== void 0 && this.presentedManagerToken(req)) this.registry.markManagerSession(sessionId);
     if (id === null) {
-      res.writeHead(202, { ...corsHeaders(), "Content-Length": "0" }).end();
+      res.writeHead(202, { ...this.corsFor(req), "Content-Length": "0" }).end();
       return;
     }
     try {
       const { result, extraHeaders } = await this.dispatch(message, sessionId, authIdentity);
       res.writeHead(200, {
-        ...corsHeaders(),
+        ...this.corsFor(req),
         "Content-Type": "application/json; charset=utf-8",
         "Mcp-Protocol-Version": messageProtocolVersion(req),
         ...extraHeaders
@@ -2526,7 +3854,7 @@ data: ${JSON.stringify({ jsonrpc: "2.0", method, params })}
       res.end(JSON.stringify({ jsonrpc: "2.0", id, result }));
     } catch (error) {
       const code = error.code ?? -32603;
-      this.jsonRpcError(res, id, code, error.message, void 0, messageProtocolVersion(req));
+      this.jsonRpcError(req, res, id, code, error.message);
     }
   }
   async dispatch(message, sessionId, authIdentity) {
@@ -2589,11 +3917,27 @@ data: ${JSON.stringify({ jsonrpc: "2.0", method, params })}
         throw rpcError(-32601, `method not found: ${method}`);
     }
   }
-  jsonRpcError(res, id, code, message, data, protocolVersion) {
-    res.writeHead(code === -32700 || code === -32600 ? 400 : 200, {
-      ...corsHeaders(),
+  /** Spec MUST: a request carrying an `MCP-Protocol-Version` this server does
+   *  not implement gets 400. Absent is fine — an absent header means the client is
+   *  on the newest revision this server knows, which is what responses advertise
+   *  (`messageProtocolVersion` returns LATEST_VERSION) —
+   *  but *present and unknown* is a client speaking a revision whose rules this
+   *  server would otherwise be guessing at. Writes the response itself and
+   *  reports whether it did. */
+  protocolVersionRejected(req, res) {
+    const presented = req.headers["mcp-protocol-version"];
+    if (presented === void 0) return false;
+    if (typeof presented === "string" && SUPPORTED_VERSIONS.includes(presented)) return false;
+    this.jsonRpcError(req, res, null, -32600, `unsupported MCP-Protocol-Version: ${String(presented).slice(0, 64)} (supported: ${SUPPORTED_VERSIONS.join(", ")})`, void 0, 400);
+    return true;
+  }
+  jsonRpcError(req, res, id, code, message, data, status) {
+    const code400 = code === -32700 || code === -32600;
+    const httpStatus = status ?? (code400 ? 400 : 200);
+    res.writeHead(httpStatus, {
+      ...this.corsFor(req),
       "Content-Type": "application/json; charset=utf-8",
-      ...protocolVersion ? { "Mcp-Protocol-Version": protocolVersion } : {}
+      "Mcp-Protocol-Version": messageProtocolVersion(req)
     });
     res.end(JSON.stringify({ jsonrpc: "2.0", id, error: { code, message, ...data !== void 0 ? { data } : {} } }));
   }
@@ -2604,7 +3948,8 @@ function rpcError(code, message) {
   return error;
 }
 function messageProtocolVersion(req) {
-  return req.headers["mcp-protocol-version"] ?? LATEST_VERSION;
+  const presented = req.headers["mcp-protocol-version"];
+  return typeof presented === "string" && SUPPORTED_VERSIONS.includes(presented) ? presented : LATEST_VERSION;
 }
 function clientIp(req) {
   const forwarded = req.headers["x-forwarded-for"];
@@ -2614,10 +3959,44 @@ function clientIp(req) {
   }
   return (req.socket.remoteAddress ?? "?").replace(/^::ffff:/, "");
 }
-function corsHeaders() {
+function headerValue(value) {
+  const raw = Array.isArray(value) ? value[0] : value;
+  return typeof raw === "string" && raw.trim() !== "" ? raw.trim() : void 0;
+}
+function secretEquals(a, b) {
+  const left = Buffer.from(a, "utf8");
+  const right = Buffer.from(b, "utf8");
+  return left.length === right.length && timingSafeEqual(left, right);
+}
+function originHostname(origin) {
+  try {
+    return new URL(origin).hostname.toLowerCase();
+  } catch {
+    return void 0;
+  }
+}
+function hostHeaderName(host) {
+  try {
+    return new URL(`http://${host}`).hostname.toLowerCase();
+  } catch {
+    return void 0;
+  }
+}
+function isLoopbackHost(host) {
+  const name = host.trim().toLowerCase().replace(/\.$/, "");
+  if (name === "localhost" || name === "::1" || name === "[::1]") return true;
+  const quad = /^127\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(name);
+  return quad !== null && quad.slice(1).every((octet) => Number(octet) <= 255);
+}
+var ALLOWED_REQUEST_HEADERS = "content-type, mcp-session-id, mcp-protocol-version, authorization";
+function corsHeaders(allowOrigin) {
   return {
-    "Access-Control-Allow-Origin": "*",
-    "Access-Control-Allow-Headers": "*",
+    Vary: "Origin",
+    ...allowOrigin !== void 0 ? { "Access-Control-Allow-Origin": allowOrigin } : {},
+    "Access-Control-Allow-Headers": ALLOWED_REQUEST_HEADERS,
+    // Exposed so a cross-origin browser client can actually READ the version the
+    // server is speaking: without this the header is set but invisible to script.
+    "Access-Control-Expose-Headers": "Mcp-Session-Id, Mcp-Protocol-Version",
     "Access-Control-Allow-Methods": "GET, POST, OPTIONS"
   };
 }
@@ -2643,7 +4022,7 @@ function readBody(req) {
 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.threadId ?? null, message.ts];
+  return [message.id, message.from, message.to, message.kind, message.content, message.ref ?? null, message.channel ?? null, message.threadId ?? null, message.ts, message.hop ?? null, message.seq ?? null, message.expiresAt ?? null];
 }
 function rowToMessage(row) {
   const id = row.id;
@@ -2663,6 +4042,15 @@ function rowToMessage(row) {
     ...typeof row.ref === "string" && row.ref !== "" ? { ref: row.ref } : {},
     ...typeof row.channel === "string" && row.channel !== "" ? { channel: row.channel } : {},
     ...typeof row.thread_id === "string" && row.thread_id !== "" ? { threadId: row.thread_id } : {},
+    // Chain depth: rows written before the hop column restore without it
+    // (treated as a chain origin by importHistory — never as a bogus depth).
+    ...typeof row.hop === "number" && Number.isFinite(row.hop) && row.hop > 0 ? { hop: row.hop } : {},
+    // Cursors: rows written before the mseq column restore without it, and are
+    // then reachable only without a `since` cursor (never mistaken for seq 0).
+    ...typeof row.mseq === "number" && Number.isFinite(row.mseq) && row.mseq > 0 ? { seq: row.mseq } : {},
+    // Deadline: restored so a message that expired while the hub was down is
+    // dropped rather than delivered late.
+    ...typeof row.expires_at === "number" && Number.isFinite(row.expires_at) && row.expires_at > 0 ? { expiresAt: row.expires_at } : {},
     ts
   };
 }
@@ -2673,15 +4061,15 @@ var SQLiteStateStore = class {
     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
+        id TEXT PRIMARY KEY, alias TEXT, client_name TEXT, client_version TEXT, registered_at INTEGER, card TEXT
       );
       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, thread_id TEXT, ts INTEGER NOT NULL
+        to_peer TEXT NOT NULL, kind TEXT NOT NULL, content TEXT NOT NULL, ref TEXT, channel TEXT, thread_id TEXT, ts INTEGER NOT NULL, hop INTEGER, mseq INTEGER, expires_at INTEGER
       );
       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, thread_id TEXT, ts INTEGER NOT NULL
+        to_peer TEXT NOT NULL, kind TEXT NOT NULL, content TEXT NOT NULL, ref TEXT, channel TEXT, thread_id TEXT, ts INTEGER NOT NULL, hop INTEGER, mseq INTEGER, expires_at INTEGER
       );
       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
@@ -2691,11 +4079,17 @@ var SQLiteStateStore = class {
       );
     `);
     for (const table of ["messages", "mailboxes"]) {
-      try {
-        this.db.exec(`ALTER TABLE ${table} ADD COLUMN thread_id TEXT`);
-      } catch {
+      for (const column of ["thread_id TEXT", "hop INTEGER", "mseq INTEGER", "expires_at INTEGER"]) {
+        try {
+          this.db.exec(`ALTER TABLE ${table} ADD COLUMN ${column}`);
+        } catch {
+        }
       }
     }
+    try {
+      this.db.exec("ALTER TABLE profiles ADD COLUMN card TEXT");
+    } catch {
+    }
     log.info(`sqlite state open: ${file}`);
   }
   db;
@@ -2707,24 +4101,24 @@ var SQLiteStateStore = class {
   /** Insert buffered messages and re-snapshot mailboxes/profiles/groups/tasks. */
   flush(snapshot) {
     const insert = this.db.prepare(
-      "INSERT INTO messages (id, from_peer, to_peer, kind, content, ref, channel, thread_id, ts) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)"
+      "INSERT INTO messages (id, from_peer, to_peer, kind, content, ref, channel, thread_id, ts, hop, mseq, expires_at) 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, thread_id, ts) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)"
+      "INSERT INTO mailboxes (peer, id, from_peer, to_peer, kind, content, ref, channel, thread_id, ts, hop, mseq, expires_at) 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 (?, ?, ?, ?, ?)"
+      "INSERT INTO profiles (id, alias, client_name, client_version, registered_at, card) VALUES (?, ?, ?, ?, ?, ?)"
     );
     for (const profile of snapshot.profiles) {
-      insertProfile.run(profile.id, profile.alias ?? null, profile.clientName ?? null, profile.clientVersion ?? null, profile.registeredAt);
+      insertProfile.run(profile.id, profile.alias ?? null, profile.clientName ?? null, profile.clientVersion ?? null, profile.registeredAt, profile.card === void 0 ? null : JSON.stringify(profile.card));
     }
     this.db.exec("DELETE FROM groups");
     const insertGroup = this.db.prepare(
@@ -2756,7 +4150,9 @@ var SQLiteStateStore = class {
         ...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()
+        registeredAt: typeof row.registered_at === "number" ? row.registered_at : Date.now(),
+        // A corrupt card row must not take the whole roster down.
+        ...cardField(row.card)
       });
     }
     const messages = [];
@@ -2804,10 +4200,19 @@ var SQLiteStateStore = class {
     this.db.close();
   }
 };
+function cardField(raw) {
+  if (typeof raw !== "string" || raw === "") return {};
+  try {
+    const parsed = JSON.parse(raw);
+    return typeof parsed === "object" && parsed !== null ? { card: parsed } : {};
+  } catch {
+    return {};
+  }
+}
 
 // src/index.ts
 var SERVER_NAME = "agent-comm-hub";
-var SERVER_VERSION = "0.9.0";
+var SERVER_VERSION = "0.10.0";
 var DEFAULT_HOST = "127.0.0.1";
 var DEFAULT_PORT = 18764;
 var DEFAULT_PATH = "/mcp";
@@ -2858,23 +4263,60 @@ function writeRosterFile(file, profiles) {
   writeFileSync2(tmp, JSON.stringify({ version: 1, savedAt: Date.now(), profiles }), "utf8");
   renameSync2(tmp, file);
 }
+function readManagerTokenFile(stateFile) {
+  if (stateFile === void 0) return void 0;
+  const file = join(dirname2(stateFile), "manager.token");
+  try {
+    const raw = readFileSync3(file, "utf8").trim();
+    return raw === "" ? void 0 : raw;
+  } catch (error) {
+    if (error.code === "ENOENT") return void 0;
+    throw new Error(`cannot read the manager token ${file}: ${error.message}`);
+  }
+}
 function startHub(config = {}, log = console) {
   const overrides = Object.fromEntries(Object.entries(config).filter(([, value]) => value !== void 0));
   const resolved = { ...DEFAULT_CONFIG, ...overrides };
+  const managerToken = resolved.managerToken ?? readManagerTokenFile(resolved.stateFile);
+  if (!isLoopbackHost(resolved.host) && resolved.authTokens === void 0 && resolved.insecure !== true) {
+    throw new Error(
+      `refusing to bind ${resolved.host} without --auth-tokens: the hub has no authentication, so every client that can reach the port would be trusted. Pass --auth-tokens <file> (recommended), or --insecure to accept the risk on an already-isolated network.`
+    );
+  }
+  if (managerToken === void 0 && resolved.managerPeers !== "all" && !isLoopbackHost(resolved.host)) {
+    log.warn(
+      `manager peer ids are claimable by any client that can reach ${resolved.host}:${resolved.port} \u2014 set --manager-token (or run with --auth-tokens) to require a credential`
+    );
+  }
+  if (managerToken !== void 0 && resolved.authTokens !== void 0) {
+    log.warn(
+      "both --manager-token and --auth-tokens are set: the token table owns the Authorization header, so the manager token is ignored. Grant manager rights with `auth add <peer> --role manager` instead."
+    );
+  }
   let mcp;
   let dbStore;
   const pushRoster = () => {
-    mcp.notifyAll("notifications/message", {
+    mcp.notifyAll(SSE_METHOD, {
       level: "info",
       logger: "bridge",
-      data: { event: "peers_changed", peers: rosterFor(hub, registry) }
+      data: { event: SSE_EVENT_PEERS_CHANGED, peers: rosterFor(hub, registry) }
     });
   };
+  const streamCursor = /* @__PURE__ */ new Map();
+  const oneStreamPer = (key, candidates) => {
+    if (candidates.length === 0) return [];
+    const streamed = registry.liveSessions();
+    const open = candidates.filter((id) => streamed.has(id));
+    const pool = open.length > 0 ? open : candidates;
+    const at = (streamCursor.get(key) ?? 0) % pool.length;
+    streamCursor.set(key, (at + 1) % pool.length);
+    return [pool[at]];
+  };
   const pushQueued = (message, target) => {
-    mcp.notify(registry.sessionsForPeer(target), "notifications/message", {
+    mcp.notify(oneStreamPer(`peer:${target}`, registry.sessionsForPeer(target)), SSE_METHOD, {
       level: "info",
       logger: "bridge",
-      data: { event: "message", message: present(message) }
+      data: { event: SSE_EVENT_MESSAGE, message: present(message) }
     });
   };
   const managerSet = resolved.managerPeers === "all" ? void 0 : new Set(resolved.managerPeers);
@@ -2883,15 +4325,15 @@ function startHub(config = {}, log = console) {
     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)) {
+      if (isManagerCaller(registry, sessionId, peer, { managerPeers: managerSet, managerTokenRequired: managerToken !== void 0 })) {
         managers.push(sessionId);
       }
     }
     if (managers.length > 0) {
-      mcp.notify(managers, "notifications/message", {
+      mcp.notify(oneStreamPer("relay", managers), SSE_METHOD, {
         level: "info",
         logger: "bridge",
-        data: { event: "message", message: present(message) }
+        data: { event: SSE_EVENT_MESSAGE, message: present(message) }
       });
     }
   };
@@ -2925,12 +4367,64 @@ function startHub(config = {}, log = console) {
     }, 500);
     saveTimer.unref?.();
   };
+  let runnerRegistry;
+  const runnerQueue = /* @__PURE__ */ new Map();
+  const taskPayload = (content) => {
+    try {
+      const parsed = JSON.parse(content);
+      return {
+        prompt: typeof parsed.prompt === "string" ? parsed.prompt : content,
+        ...typeof parsed.context === "string" ? { context: parsed.context } : {},
+        ...typeof parsed.deliverable === "string" ? { deliverable: parsed.deliverable } : {},
+        ...typeof parsed.threadId === "string" ? { threadId: parsed.threadId } : {}
+      };
+    } catch {
+      return { prompt: content };
+    }
+  };
+  function runTask(message, target) {
+    const runner = runnerRegistry?.get(target);
+    if (runner === void 0) return;
+    const previous = runnerQueue.get(target) ?? Promise.resolve();
+    const next = previous.then(async () => {
+      const payload = taskPayload(message.content);
+      hub.noteEvent("runner_started", { peer: target, detail: { taskId: message.id, runner: runner.name } });
+      try {
+        const result = await runner.run({ taskId: message.id, peer: target, ...payload });
+        hub.noteEvent("runner_finished", { peer: target, detail: { taskId: message.id, runner: runner.name, status: result.status } });
+        hub.ackForRunner(target, message.id, { status: result.status, note: result.note });
+        log.info(`runner ${runner.name}: task ${message.id} for '${target}' -> ${result.status}`);
+      } catch (error) {
+        hub.noteEvent("runner_finished", { peer: target, detail: { taskId: message.id, runner: runner.name, status: "failed", error: error.message } });
+        try {
+          hub.ackForRunner(target, message.id, { status: "failed", note: `runner error: ${error.message}` });
+        } catch {
+        }
+        log.warn(`runner ${runner.name} errored on task ${message.id}: ${error.message}`);
+      }
+    });
+    runnerQueue.set(target, next.catch(() => {
+    }));
+  }
   const hub = new AgentHub({
     maxQueue: resolved.maxQueue,
     historyLimit: resolved.historyLimit,
     waitTimeoutMs: resolved.waitTimeoutMs,
     connectedWindowMs: resolved.connectedWindowMs,
     peerIdleTimeoutMs: resolved.peerIdleTimeoutMs,
+    parkedTtlMs: resolved.parkedTtlMs,
+    leaseTtlMs: resolved.leaseTtlMs,
+    maxAttempts: resolved.maxAttempts,
+    ratePerMin: resolved.ratePerMin,
+    // A parked mailbox that expires is data loss: say so, and make the store
+    // re-snapshot so the dropped rows cannot resurrect on the next restart.
+    onMailboxExpired: (peerId, dropped) => {
+      log.warn(`parked mailbox for '${peerId}' expired after ${resolved.parkedTtlMs ?? DEFAULT_PARKED_TTL_MS}ms: ${dropped} message(s) dropped`);
+      if (dbStore !== void 0) {
+        dbDirty = true;
+        scheduleSave();
+      }
+    },
     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.
@@ -2986,6 +4480,17 @@ function startHub(config = {}, log = console) {
       } catch (error) {
         log.warn(`message notification failed: ${error.message}`);
       }
+    },
+    // A task that reached a mailbox has nobody polling for it. If this peer has
+    // a runner configured, wake it — that is the whole point of a runner.
+    // `runnerRegistry` is filled in below, once the herdr adapter exists; this
+    // hook only ever fires after the hub is serving.
+    onTaskQueued: (message, target) => {
+      try {
+        runTask(message, target);
+      } catch (error) {
+        log.warn(`runner dispatch failed for '${target}': ${error.message}`);
+      }
     }
   });
   const registry = new SessionRegistry();
@@ -3038,6 +4543,8 @@ function startHub(config = {}, log = console) {
     socketPath: resolved.herdrSocketPath,
     sendRequest: resolved.herdrSendRequest
   });
+  runnerRegistry = new RunnerRegistry(resolved.runners ?? [], { herdr });
+  if (runnerRegistry.size > 0) log.info(`runners configured for: ${runnerRegistry.peers().join(", ")}`);
   let auth;
   let authReload;
   if (resolved.authTokens !== void 0) {
@@ -3063,7 +4570,8 @@ function startHub(config = {}, log = console) {
       waitTimeoutMs: resolved.waitTimeoutMs,
       herdr,
       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)
+      managerPeers: resolved.managerPeers === "all" ? "all" : new Set(resolved.managerPeers ?? DEFAULT_CONFIG.managerPeers),
+      managerTokenRequired: managerToken !== void 0
     }),
     { name: SERVER_NAME, version: SERVER_VERSION },
     registry,
@@ -3090,12 +4598,15 @@ function startHub(config = {}, log = console) {
     },
     auth,
     authTokensAdmin(resolved.authTokens, authReload),
-    resolved.heartbeatMs
+    resolved.heartbeatMs,
+    resolved.allowOrigins === void 0 || resolved.allowOrigins.length === 0 ? void 0 : { allow: new Set(resolved.allowOrigins) },
+    managerToken,
+    resolved.sessionTtlMs
   );
   const server = createServer();
   mcp.attach(server, resolved.path);
   server.on("error", (error) => log.warn(`hub http server error: ${error.message}`));
-  server.listen(resolved.port, resolved.host, () => {
+  server.listen(resolved.port, resolved.host.trim(), () => {
     log.info(`agent-comm-hub listening on http://${resolved.host}:${resolved.port}${resolved.path}`);
   });
   return {
@@ -3128,24 +4639,36 @@ export {
   AGENT_STATUSES,
   AgentHub,
   BROADCAST,
+  CLIENT_ACK_STATUSES,
   DEFAULT_CONFIG,
   DEFAULT_HOST,
   DEFAULT_PATH,
   DEFAULT_PORT,
+  DEFAULT_RUN_TIMEOUT_MS,
+  HUB_PEER,
   HerdrCtl,
   KINDS,
+  MAX_EVENTS,
   MAX_HOP,
+  MAX_REPLY_CHAIN,
+  MAX_RUN_NOTE_CHARS,
   McpStreamableHttpServer,
   PEER_ID_PATTERN,
+  RunnerRegistry,
   SERVER_NAME,
   SERVER_VERSION,
   SQLiteStateStore,
+  SSE_EVENT_MESSAGE,
+  SSE_EVENT_PEERS_CHANGED,
+  SSE_METHOD,
   SessionRegistry,
   TERMINAL_TASK_STATUSES,
+  a2aState,
   ackToTaskStatus,
   addToken,
   aggregateTaskStatus,
   autoRegisterPeer,
+  createRunner,
   decodeContent,
   encodeContent,
   generateToken,
@@ -3159,5 +4682,6 @@ export {
   sanitizePeerId,
   startHub,
   tokenTable,
+  validateRunnerConfig,
   watchTokenFile
 };