@cotal-ai/connector-hermes 0.3.2 → 0.4.0

package/README.md

@@ -0,0 +1,11 @@
+# @cotal-ai/connector-hermes
+
+The Hermes (Nous Research) adapter: connects the Hermes agent to the mesh as a lateral peer.
+Ships a Python sidecar (`pyproject.toml` / `uv.lock`) alongside the TypeScript connector. A
+sibling of the Claude Code and OpenCode adapters, over
+[`@cotal-ai/connector-core`](../connector-core).
+
+**Tier:** `extensions/`. Peer-depends [`@cotal-ai/core`](../../packages/core); self-registers on
+import.
+
+See the [root AGENTS.md](../../AGENTS.md) for the tier rules.

package/dist/extension.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"extension.d.ts","sourceRoot":"","sources":["../src/extension.ts"],"names":[],"mappings":"AACA,OAAO,EAAY,KAAK,SAAS,EAAoC,MAAM,gBAAgB,CAAC;AAc5F;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,EAAE,SAgB7B,CAAC"}
+{"version":3,"file":"extension.d.ts","sourceRoot":"","sources":["../src/extension.ts"],"names":[],"mappings":"AACA,OAAO,EAAY,KAAK,SAAS,EAAoC,MAAM,gBAAgB,CAAC;AAW5F;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,EAAE,SAsB7B,CAAC"}

package/dist/extension.js

@@ -1,5 +1,6 @@
 import { fileURLToPath } from "node:url";
 import { registry } from "@cotal-ai/core";
+import { launchEnv, MODEL_PROVIDER_KEYS } from "@cotal-ai/connector-core";
 /** The launcher (run via tsx, which loads both) owns the mesh endpoint and supervises the Hermes
  *  gateway as a child — see launch.ts. Resolve `.ts` when this module loads from source (dev) and
  *  `.js` when it loads from the build: the package's `import` resolves to dist/, so a hardcoded
@@ -7,9 +8,6 @@ import { registry } from "@cotal-ai/core";
 const ENTRY_EXT = import.meta.url.includes("/dist/") ? "js" : "ts";
 const TSX = fileURLToPath(new URL("../node_modules/.bin/tsx", import.meta.url));
 const LAUNCH_ENTRY = fileURLToPath(new URL(`./launch.${ENTRY_EXT}`, import.meta.url));
-/** Provider keys forwarded to the Hermes gateway if present. Hermes is model-agnostic; any one
- *  of these unlocks a provider. We forward, never require — the operator's own keys, untouched. */
-const PROVIDER_KEYS = ["OPENROUTER_API_KEY", "ANTHROPIC_API_KEY", "OPENAI_API_KEY", "NOUS_API_KEY"];
 /**
  * The Hermes (Nous Research) connector. Unlike Claude Code / Codex — where the harness *is* the
  * process and an MCP server rides inside it — Hermes runs as a long-lived **gateway daemon** that
@@ -24,7 +22,14 @@ export const hermesConnector = {
     kind: "connector",
     name: "hermes",
     buildLaunch(opts) {
-        const env = { COTAL_SPACE: opts.space, COTAL_NAME: opts.name };
+        // OS allow-list + the named model-provider key (Hermes is model-agnostic; any one unlocks a
+        // provider), forwarded BY NAME — never `...process.env` — so the operator's unrelated secrets
+        // don't reach the gateway child (P3).
+        const env = {
+            ...launchEnv({ providerKeys: MODEL_PROVIDER_KEYS }),
+            COTAL_SPACE: opts.space,
+            COTAL_NAME: opts.name,
+        };
         if (opts.role)
             env.COTAL_ROLE = opts.role;
         if (opts.id)
@@ -39,9 +44,6 @@ export const hermesConnector = {
             env.COTAL_AGENT_FILE = opts.configPath;
         if (process.env.HERMES_MODEL)
             env.HERMES_MODEL = process.env.HERMES_MODEL;
-        for (const k of PROVIDER_KEYS)
-            if (process.env[k])
-                env[k] = process.env[k];
         return { command: TSX, args: [LAUNCH_ENTRY], env };
     },
 };

package/dist/extension.js.map

@@ -1 +1 @@
-{"version":3,"file":"extension.js","sourceRoot":"","sources":["../src/extension.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,QAAQ,EAAoD,MAAM,gBAAgB,CAAC;AAE5F;;;2DAG2D;AAC3D,MAAM,SAAS,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;AACnE,MAAM,GAAG,GAAG,aAAa,CAAC,IAAI,GAAG,CAAC,0BAA0B,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAChF,MAAM,YAAY,GAAG,aAAa,CAAC,IAAI,GAAG,CAAC,YAAY,SAAS,EAAE,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAEtF;mGACmG;AACnG,MAAM,aAAa,GAAG,CAAC,oBAAoB,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,cAAc,CAAC,CAAC;AAEpG;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,eAAe,GAAc;IACxC,IAAI,EAAE,WAAW;IACjB,IAAI,EAAE,QAAQ;IACd,WAAW,CAAC,IAAgB;QAC1B,MAAM,GAAG,GAA2B,EAAE,WAAW,EAAE,IAAI,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC;QACvF,IAAI,IAAI,CAAC,IAAI;YAAE,GAAG,CAAC,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC;QAC1C,IAAI,IAAI,CAAC,EAAE;YAAE,GAAG,CAAC,QAAQ,GAAG,IAAI,CAAC,EAAE,CAAC;QACpC,IAAI,IAAI,CAAC,KAAK;YAAE,GAAG,CAAC,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC;QAC7C,IAAI,IAAI,CAAC,OAAO;YAAE,GAAG,CAAC,aAAa,GAAG,IAAI,CAAC,OAAO,CAAC;QACnD,wFAAwF;QACxF,mFAAmF;QACnF,IAAI,IAAI,CAAC,UAAU;YAAE,GAAG,CAAC,gBAAgB,GAAG,IAAI,CAAC,UAAU,CAAC;QAC5D,IAAI,OAAO,CAAC,GAAG,CAAC,YAAY;YAAE,GAAG,CAAC,YAAY,GAAG,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC;QAC1E,KAAK,MAAM,CAAC,IAAI,aAAa;YAAE,IAAI,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC;gBAAE,GAAG,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAE,CAAC;QAC5E,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,YAAY,CAAC,EAAE,GAAG,EAAE,CAAC;IACrD,CAAC;CACF,CAAC;AAEF,QAAQ,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAC"}
+{"version":3,"file":"extension.js","sourceRoot":"","sources":["../src/extension.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,QAAQ,EAAoD,MAAM,gBAAgB,CAAC;AAC5F,OAAO,EAAE,SAAS,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAE1E;;;2DAG2D;AAC3D,MAAM,SAAS,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;AACnE,MAAM,GAAG,GAAG,aAAa,CAAC,IAAI,GAAG,CAAC,0BAA0B,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAChF,MAAM,YAAY,GAAG,aAAa,CAAC,IAAI,GAAG,CAAC,YAAY,SAAS,EAAE,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAEtF;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,eAAe,GAAc;IACxC,IAAI,EAAE,WAAW;IACjB,IAAI,EAAE,QAAQ;IACd,WAAW,CAAC,IAAgB;QAC1B,4FAA4F;QAC5F,8FAA8F;QAC9F,sCAAsC;QACtC,MAAM,GAAG,GAA2B;YAClC,GAAG,SAAS,CAAC,EAAE,YAAY,EAAE,mBAAmB,EAAE,CAAC;YACnD,WAAW,EAAE,IAAI,CAAC,KAAK;YACvB,UAAU,EAAE,IAAI,CAAC,IAAI;SACtB,CAAC;QACF,IAAI,IAAI,CAAC,IAAI;YAAE,GAAG,CAAC,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC;QAC1C,IAAI,IAAI,CAAC,EAAE;YAAE,GAAG,CAAC,QAAQ,GAAG,IAAI,CAAC,EAAE,CAAC;QACpC,IAAI,IAAI,CAAC,KAAK;YAAE,GAAG,CAAC,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC;QAC7C,IAAI,IAAI,CAAC,OAAO;YAAE,GAAG,CAAC,aAAa,GAAG,IAAI,CAAC,OAAO,CAAC;QACnD,wFAAwF;QACxF,mFAAmF;QACnF,IAAI,IAAI,CAAC,UAAU;YAAE,GAAG,CAAC,gBAAgB,GAAG,IAAI,CAAC,UAAU,CAAC;QAC5D,IAAI,OAAO,CAAC,GAAG,CAAC,YAAY;YAAE,GAAG,CAAC,YAAY,GAAG,OAAO,CAAC,GAAG,CAAC,YAAa,CAAC;QAC3E,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,YAAY,CAAC,EAAE,GAAG,EAAE,CAAC;IACrD,CAAC;CACF,CAAC;AAEF,QAAQ,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@cotal-ai/connector-hermes",
-  "version": "0.3.2",
+  "description": "Cotal connector for the Hermes (Nous Research) agent.",
+  "version": "0.4.0",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -22,14 +23,14 @@
   "dependencies": {
     "tsx": "^4.22.4",
     "zod": "^4.4.3",
-    "@cotal-ai/connector-core": "0.3.2"
+    "@cotal-ai/connector-core": "0.4.0"
   },
   "peerDependencies": {
     "@cotal-ai/core": ">=0.1.0"
   },
   "devDependencies": {
     "esbuild": "^0.28.0",
-    "@cotal-ai/core": "0.3.2"
+    "@cotal-ai/core": "0.4.0"
   },
   "files": [
     "bin",

package/plugin/cotal/_sidecar/standalone.cjs

@@ -14758,7 +14758,7 @@ function subjectMatches(pattern, subject) {
   const s = subject.split(".");
   for (let i = 0; i < p.length; i++) {
     if (p[i] === ">")
-      return true;
+      return i < s.length;
     if (i >= s.length)
       return false;
     if (p[i] === "*")
@@ -14768,6 +14768,26 @@ function subjectMatches(pattern, subject) {
   }
   return p.length === s.length;
 }
+function assertValidChannel(channel) {
+  const segs = channel.split(".");
+  if (!channel.length || segs.some((s) => s.length === 0))
+    throw new Error(`invalid channel "${channel}": empty segment (no leading/trailing/double dots)`);
+  segs.forEach((s, i) => {
+    if (s === ">") {
+      if (i !== segs.length - 1)
+        throw new Error(`invalid channel "${channel}": '>' is only valid as the last segment`);
+      return;
+    }
+    if (s === "*")
+      return;
+    if (!/^[A-Za-z0-9_-]+$/.test(s))
+      throw new Error(`invalid channel "${channel}": segment "${s}" must be a NATS-safe token ([A-Za-z0-9_-]), '*', or '>' \u2014 policy channel names can't contain characters the wire layer would rewrite`);
+  });
+  return channel;
+}
+function channelInAllow(allow, channel) {
+  return allow.some((a) => subjectMatches(a, channel));
+}
 function collapseFilterSubjects(subjects) {
   const uniq = [...new Set(subjects)];
   return uniq.filter((x) => !uniq.some((y) => y !== x && subjectMatches(y, x)));
@@ -14781,6 +14801,8 @@ function anycastSubject(space, service, sender) {
 function controlServiceSubject(space, service, sender) {
   return `${spacePrefix(space)}.ctl.${routeToken(service)}.${routeToken(sender)}`;
 }
+var CONTROL_PRIVILEGED = "manager";
+var CONTROL_SELF_SERVICE = "self";
 function spaceWildcard(space) {
   return `${spacePrefix(space)}.>`;
 }
@@ -14820,6 +14842,9 @@ function taskStream(space) {
 function chatDurable(instance) {
   return `chat_${token(instance)}`;
 }
+function chatHistDurable(instance) {
+  return `chathist_${token(instance)}`;
+}
 function dmDurable(instance) {
   return `dm_${token(instance)}`;
 }
@@ -14827,6 +14852,46 @@ function taskDurable(service) {
   return `svc_${token(service)}`;
 }
 
+// ../../packages/core/dist/resolve.js
+var AmbiguousPeerError = class extends Error {
+  target;
+  candidates;
+  constructor(target, candidates) {
+    super(`"${target}" is ambiguous \u2014 ${candidates.length} peers share that name: ` + candidates.map((c) => `${c.name} (${c.id}, ${c.status})`).join("; ") + `. Re-send to the exact instance id.`);
+    this.target = target;
+    this.candidates = candidates;
+    this.name = "AmbiguousPeerError";
+  }
+};
+function candidate(p) {
+  return { id: p.card.id, name: p.card.name, role: p.card.role, status: p.status, ts: p.ts };
+}
+function resolvePeer(roster, target, opts = {}) {
+  const peers = opts.selfId ? roster.filter((p) => p.card.id !== opts.selfId) : roster;
+  const byId = peers.find((p) => p.card.id === target);
+  if (byId)
+    return byId;
+  const want = target.trim().toLowerCase();
+  if (!want)
+    return void 0;
+  const matches = peers.filter((p) => p.card.name.toLowerCase() === want);
+  if (matches.length === 0)
+    return void 0;
+  const live = matches.filter((p) => p.status !== "offline");
+  const pool = live.length > 0 ? live : matches;
+  if (pool.length === 1)
+    return pool[0];
+  throw new AmbiguousPeerError(target, pool.map(candidate));
+}
+function assertValidName(name) {
+  if (name.length === 0 || name !== name.trim())
+    throw new Error(`invalid name ${JSON.stringify(name)}: must be non-empty with no surrounding whitespace`);
+  if (/[\r\n]/.test(name))
+    throw new Error(`invalid name ${JSON.stringify(name)}: must be a single line`);
+  if (name.includes("/"))
+    throw new Error(`invalid name ${JSON.stringify(name)}: "/" is reserved (the owner/name separator)`);
+}
+
 // ../../packages/core/dist/link.js
 function parseJoinLink(link) {
   const tls = link.startsWith("cotals://");
@@ -16506,9 +16571,10 @@ async function createSpaceStreams(jsm, space) {
     max_msgs_per_subject: MAX_MSGS_PER_SUBJECT,
     // capped per-channel backlog (buffer + history)
     discard: import_jetstream.DiscardPolicy.Old,
-    // Enable the read-only Direct Get API for per-channel history backfill on join (a pure
-    // read verb, no consumer create). CHAT ONLY — never DM/TASK: direct-get bypasses the
-    // consumer-create deny that is DM's confidentiality boundary.
+    // Direct Get API stays enabled on CHAT (harmless: agents hold no DIRECT.GET grant). Per-channel
+    // history reads no longer use it — they go through contained single-filter ephemeral consumers
+    // (endpoint `collectHistory`) so the read ACL bounds them. NEVER set on DM/TASK: direct-get
+    // would bypass the consumer-create deny that is DM's confidentiality boundary.
     allow_direct: true
   });
   await jsm.streams.add({
@@ -16536,6 +16602,18 @@ function dmDurableConfig(space, id, opts = {}) {
     cfg.inactive_threshold = (0, import_transport_node.nanos)(opts.inactiveThresholdMs);
   return cfg;
 }
+function chatDurableConfig(space, id, channels, opts = {}) {
+  const cfg = {
+    durable_name: chatDurable(id),
+    filter_subjects: collapseFilterSubjects(channels.map((ch) => chatSubject(space, "*", ch))),
+    ack_policy: import_jetstream.AckPolicy.Explicit,
+    ack_wait: (0, import_transport_node.nanos)(opts.ackWaitMs ?? 6e4),
+    deliver_policy: import_jetstream.DeliverPolicy.New
+  };
+  if (opts.inactiveThresholdMs)
+    cfg.inactive_threshold = (0, import_transport_node.nanos)(opts.inactiveThresholdMs);
+  return cfg;
+}
 function taskDurableConfig(space, role, opts = {}) {
   return {
     durable_name: taskDurable(role),
@@ -16634,10 +16712,28 @@ function loadAgentFile(path) {
   const name = str("name");
   if (!name)
     throw new Error(`agent file ${path}: "name" is required`);
+  assertValidName(name);
   const kind = str("kind");
   if (kind && kind !== "agent" && kind !== "endpoint")
     throw new Error(`agent file ${path}: "kind" must be "agent" or "endpoint"`);
-  const known = /* @__PURE__ */ new Set(["name", "role", "kind", "description", "tags", "channels", "publish", "model"]);
+  for (const old of ["channels", "publish"])
+    if (old in fm)
+      throw new Error(`agent file ${path}: "${old}" was renamed \u2014 use "subscribe"/"allowSubscribe" (read) and "allowPublish" (post)`);
+  const subscribe = list("subscribe");
+  const allowSubscribe = list("allowSubscribe");
+  const allowPublish = list("allowPublish");
+  for (const ch of [...subscribe ?? [], ...allowSubscribe ?? [], ...allowPublish ?? []])
+    try {
+      assertValidChannel(ch);
+    } catch (e) {
+      throw new Error(`agent file ${path}: ${e.message}`);
+    }
+  const effSubscribe = subscribe?.length ? subscribe : ["general"];
+  const effAllow = allowSubscribe?.length ? allowSubscribe : effSubscribe;
+  for (const ch of effSubscribe)
+    if (!channelInAllow(effAllow, ch))
+      throw new Error(`agent file ${path}: subscribe channel "${ch}" is not within allowSubscribe [${effAllow.join(", ")}]`);
+  const known = /* @__PURE__ */ new Set(["name", "role", "kind", "description", "tags", "subscribe", "allowSubscribe", "allowPublish", "model", "capabilities", "owner"]);
   const meta3 = {};
   for (const [k, v] of Object.entries(fm))
     if (!known.has(k) && typeof v === "string")
@@ -16648,9 +16744,12 @@ function loadAgentFile(path) {
     kind,
     description: str("description"),
     tags: list("tags"),
-    channels: list("channels"),
-    publish: list("publish"),
+    subscribe,
+    allowSubscribe,
+    allowPublish,
     model: str("model"),
+    capabilities: list("capabilities"),
+    owner: str("owner"),
     meta: Object.keys(meta3).length ? meta3 : void 0,
     persona: persona || void 0
   };
@@ -16693,6 +16792,9 @@ var CotalEndpoint = class extends import_node_events.EventEmitter {
    *  a lagging joiner + dedups the backfill overlap). Keyed by the subscription pattern (may be
    *  wildcard), so the drop matches every concrete channel the pattern subsumes. */
   joinSeq = /* @__PURE__ */ new Map();
+  /** Serializes history reads ({@link collectHistory}): they share the fixed per-instance
+   *  `chathist_<id>` consumer, so overlapping reads would delete/recreate it under one another. */
+  histLock = Promise.resolve();
   subs = [];
   streamMsgs = [];
   heartbeatTimer;
@@ -16701,9 +16803,24 @@ var CotalEndpoint = class extends import_node_events.EventEmitter {
   status = "idle";
   activity;
   stopped = false;
+  /** In-flight rebuild (drain+rebind) — serializes manual reconnect, the supervisor's
+   *  closed(), and reestablishLoop so only ONE rebuild runs at a time (a second trigger
+   *  coalesces onto the shared promise, never starts a parallel connectAndBind). */
+  rebuildPromise;
+  /** True only during the null window of a rebuild (this.nc unset) — user-facing ops then
+   *  throw a "reconnecting" message instead of the misleading "endpoint not started". */
+  reconnecting = false;
+  /** One reestablishLoop at a time; concurrent triggers coalesce via rebuild(). */
+  reestablishing = false;
+  /** Interruptible backoff for reestablishLoop — reconnect()/stop() resolves this to retry
+   *  now instead of awaiting the full retryMs. */
+  backoffResolve;
+  backoffTimer;
+  retryMs = 3e3;
   constructor(opts) {
     super();
     this.space = opts.space;
+    assertValidName(opts.card.name);
     const credId = opts.creds ? idFromCreds(opts.creds) : void 0;
     if (opts.card.id && credId && opts.card.id !== credId)
       throw new Error(`card.id ${opts.card.id} != creds identity ${credId} \u2014 they must be the same nkey`);
@@ -16728,6 +16845,15 @@ var CotalEndpoint = class extends import_node_events.EventEmitter {
     return { id: this.card.id, name: this.card.name, role: this.card.role };
   }
   async start() {
+    await this.connectAndBind();
+    this.superviseConnection();
+  }
+  /** Open the connection and bind everything that hangs off it: status watch, presence
+   *  watch + heartbeat, channel registry, and the durable consumers. Re-runnable — a
+   *  reconnect calls it again after {@link clearConnectionScoped}; every binding is
+   *  idempotent (durables bind by name, JetStream dedups by msgID, KV opens are idempotent). */
+  async connectAndBind() {
+    this.clearConnectionScoped();
     this.nc = await (0, import_transport_node3.connect)({
       servers: this.servers,
       name: `cotal:${this.card.name}`,
@@ -16766,11 +16892,167 @@ var CotalEndpoint = class extends import_node_events.EventEmitter {
         await this.ensureStreams();
       await this.startConsumers();
     }
+    this.emit("connection", { connected: true });
+  }
+  /** Tear down everything {@link connectAndBind} (re)creates, so a rebind can't leak a
+   *  second heartbeat, double-pump a consumer, or keep stale roster ghosts. Caller-owned
+   *  subs (tap/serve) are left alone — they aren't rebuilt here. */
+  clearConnectionScoped() {
+    if (this.heartbeatTimer) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = void 0;
+    }
+    if (this.sweepTimer) {
+      clearInterval(this.sweepTimer);
+      this.sweepTimer = void 0;
+    }
+    for (const msgs of this.streamMsgs) {
+      try {
+        msgs.stop();
+      } catch {
+      }
+    }
+    this.streamMsgs.length = 0;
+    this.roster.clear();
+    this.joinSeq.clear();
+    this.channelConfigs.clear();
+    this.channelDefaults = {};
+  }
+  /** If stop() ran during a rebuild's `await connectAndBind`, the just-bound connection +
+   *  heartbeat + supervisor would be left live on a stopped endpoint. Tear that fresh
+   *  connection back down and report it. Reads `this.nc` in its own scope (a bare `this.nc`
+   *  in doRebuild narrows to `never` via TS inlining connectAndBind's assignment). Returns
+   *  true iff it tore something down (caller bails out of the rebuild). */
+  async tearDownIfStopped() {
+    if (!this.stopped)
+      return false;
+    const nc = this.nc;
+    this.clearConnectionScoped();
+    try {
+      await nc?.drain();
+    } catch {
+    }
+    this.nc = void 0;
+    return true;
+  }
+  /** Watch for a terminal close (nats.js has exhausted its own reconnect) and rebuild.
+   *  Our own stop()/drain also resolves closed(), so the `stopped` guard keeps a clean
+   *  shutdown from re-establishing. The identity guard (`this.nc !== nc`) no-ops a STALE
+   *  supervisor — one whose connection reconnect()/rebuild already replaced — so only a
+   *  close of the CURRENT connection triggers a rebuild. The rebuild itself is serialized
+   *  with the manual path via {@link rebuild}. */
+  superviseConnection() {
+    const nc = this.nc;
+    if (!nc)
+      return;
+    void nc.closed().then((err2) => {
+      if (this.stopped)
+        return;
+      if (this.nc !== nc)
+        return;
+      this.emit("connection", { connected: false });
+      this.emit("error", new Error(`mesh connection closed${err2 ? `: ${err2.message}` : ""} \u2014 re-establishing`));
+      void this.reestablishLoop();
+    });
+  }
+  /** Single serialized rebuild: drain the old connection and rebind via {@link connectAndBind},
+   *  guarded so concurrent triggers (manual {@link reconnect}, the supervisor's closed(), the
+   *  retry loop) coalesce onto ONE in-flight rebuild instead of racing two connectAndBinds and
+   *  leaking a connection. Returns the shared promise; a second caller gets the in-flight one. */
+  rebuild() {
+    if (this.rebuildPromise)
+      return this.rebuildPromise;
+    const p = this.doRebuild().finally(() => {
+      if (this.rebuildPromise === p)
+        this.rebuildPromise = void 0;
+    });
+    this.rebuildPromise = p;
+    return p;
+  }
+  /** The transition: stop the connection-scoped timers FIRST (so nothing live touches
+   *  this.nc during the null window), drop the connection refs, drain the old nc, then
+   *  rebind + re-arm the supervisor on the fresh connection. clearConnectionScoped is
+   *  idempotent, so connectAndBind's own call here is a noop. */
+  async doRebuild() {
+    const oldNc = this.nc;
+    this.reconnecting = true;
+    try {
+      this.clearConnectionScoped();
+      this.nc = void 0;
+      this.js = void 0;
+      this.jsm = void 0;
+      this.kv = void 0;
+      this.channelKv = void 0;
+      this.emit("connection", { connected: false });
+      try {
+        await oldNc?.drain();
+      } catch {
+      }
+      await this.connectAndBind();
+      if (await this.tearDownIfStopped())
+        return;
+      this.superviseConnection();
+    } finally {
+      this.reconnecting = false;
+    }
+  }
+  /** Rebuild with backoff until it sticks or we're stopped. Interruptible: a manual
+   *  {@link reconnect} kicks the backoff so the next attempt runs immediately instead of
+   *  awaiting the full retryMs. One loop at a time ({@link reestablishing}); concurrent
+   *  triggers coalesce via {@link rebuild}. */
+  async reestablishLoop() {
+    if (this.reestablishing)
+      return;
+    this.reestablishing = true;
+    try {
+      while (!this.stopped) {
+        try {
+          await this.rebuild();
+          return;
+        } catch (e) {
+          if (!this.stopped)
+            this.emit("error", e);
+          await new Promise((resolve) => {
+            this.backoffResolve = resolve;
+            this.backoffTimer = setTimeout(resolve, this.retryMs);
+          });
+        }
+      }
+    } finally {
+      this.reestablishing = false;
+    }
+  }
+  /** Cut an in-flight reestablish backoff short so the next attempt runs immediately, and
+   *  clear its timer so it can't fire later on a stopped/restarted loop. */
+  kickBackoff() {
+    this.backoffResolve?.();
+    if (this.backoffTimer) {
+      clearTimeout(this.backoffTimer);
+      this.backoffTimer = void 0;
+    }
+  }
+  /** Manual reconnect: tear down the current connection and rebuild, WITHOUT the permanent
+   *  stop (stopped/stopping stay false). Serialized with the self-heal supervisor via
+   *  {@link rebuild}, and interruptible — if a backoff is in flight, kick it so the attempt
+   *  is now, not in retryMs. Throws if stopped. On failure, leaves {@link reestablishLoop}
+   *  running in the background so the endpoint never stays dead, and rethrows so the caller
+   *  can report it. */
+  async reconnect() {
+    if (this.stopped)
+      throw new Error("endpoint stopped \u2014 cannot reconnect");
+    this.kickBackoff();
+    try {
+      await this.rebuild();
+    } catch (e) {
+      void this.reestablishLoop();
+      throw e;
+    }
   }
   async stop() {
     if (this.stopped)
       return;
     this.stopped = true;
+    this.kickBackoff();
     if (this.heartbeatTimer)
       clearInterval(this.heartbeatTimer);
     if (this.sweepTimer)
@@ -16899,7 +17181,7 @@ var CotalEndpoint = class extends import_node_events.EventEmitter {
   /** Send a control request to a service and await its reply (client side). */
   async requestControl(service, req, timeoutMs = 5e3) {
     if (!this.nc)
-      throw new Error("endpoint not started");
+      throw new Error(this.notLiveMsg());
     const body = { ...req, from: req.from ?? this.ref() };
     const m = await this.nc.request(controlServiceSubject(this.space, service, this.card.id), JSON.stringify(body), { timeout: timeoutMs });
     return m.json();
@@ -16940,14 +17222,16 @@ var CotalEndpoint = class extends import_node_events.EventEmitter {
    */
   async joinChannel(channel) {
     if (!this.jsm)
-      throw new Error("endpoint not started");
+      throw new Error(this.notLiveMsg());
     if (this.channels.includes(channel))
       return { joined: false, backfilled: 0 };
-    const next = collapseFilterSubjects([...this.channels, channel].map((ch) => chatSubject(this.space, "*", ch)));
     const armed = await this.armJoin([channel]);
-    await this.jsm.consumers.update(chatStream(this.space), chatDurable(this.card.id), {
-      filter_subjects: next
-    });
+    try {
+      await this.setChatFilter([...this.channels, channel]);
+    } catch (e) {
+      this.joinSeq.delete(channel);
+      throw e;
+    }
     this.channels.push(channel);
     const backfilled = await this.backfillArmed(armed);
     return { joined: true, backfilled };
@@ -16957,26 +17241,51 @@ var CotalEndpoint = class extends import_node_events.EventEmitter {
    *  leaving). Returns whether anything changed. */
   async leaveChannel(channel) {
     if (!this.jsm)
-      throw new Error("endpoint not started");
+      throw new Error(this.notLiveMsg());
     const i = this.channels.indexOf(channel);
     if (i < 0)
       return { left: false };
     if (this.channels.length === 1)
       throw new Error(`cannot leave "${channel}" \u2014 it is your only channel (an empty filter would subscribe to all)`);
     const remaining = this.channels.filter((c) => c !== channel);
-    await this.jsm.consumers.update(chatStream(this.space), chatDurable(this.card.id), {
-      filter_subjects: collapseFilterSubjects(remaining.map((ch) => chatSubject(this.space, "*", ch)))
-    });
+    await this.setChatFilter(remaining);
     this.channels.splice(i, 1);
     this.joinSeq.delete(channel);
     return { left: true };
   }
+  /** Move the chat live-tail durable to a new channel set. OPEN mode self-serves the
+   *  `consumers.update` (the agent owns its durable). AUTH mode is bind-only — the agent has no
+   *  UPDATE grant — so it sends a mediated control request to the manager, which validates the set
+   *  ⊆ its `allowSubscribe` before moving the filter. Throws clearly when no privileged responder is
+   *  present: a manager-less standalone auth session is fixed to its boot subscribe set — a
+   *  documented limitation, not a silent degrade. */
+  async setChatFilter(channels) {
+    if (!this.jsm)
+      throw new Error(this.notLiveMsg());
+    if (!this.creds) {
+      await this.jsm.consumers.update(chatStream(this.space), chatDurable(this.card.id), {
+        filter_subjects: collapseFilterSubjects(channels.map((ch) => chatSubject(this.space, "*", ch)))
+      });
+      return;
+    }
+    let reply;
+    try {
+      reply = await this.requestControl(CONTROL_SELF_SERVICE, { op: "setChannels", args: { channels } });
+    } catch (e) {
+      const msg = e.message;
+      if (/no responders/i.test(msg))
+        throw new Error("cannot change channels at runtime: no privileged provisioner (manager) is serving the mesh \u2014 this session is fixed to its boot subscribe set");
+      throw e;
+    }
+    if (!reply.ok)
+      throw new Error(reply.error ?? "channel change rejected");
+  }
   /** One coherent channel model for dashboards: every channel that has messages OR a registry
    *  entry (configured-but-empty), each tagged with its {@link ChannelConfig}. Works even on
    *  observer endpoints (no consumers needed). */
   async listChannels() {
     if (!this.nc)
-      throw new Error("endpoint not started");
+      throw new Error(this.notLiveMsg());
     const mgr = await (0, import_jetstream2.jetstreamManager)(this.nc);
     const counts = /* @__PURE__ */ new Map();
     try {
@@ -17099,9 +17408,16 @@ var CotalEndpoint = class extends import_node_events.EventEmitter {
         this.emit("error", e);
     });
   }
+  /** The error message for a guard that finds the endpoint unbound: "reconnecting" during a
+   *  rebuild's null window OR an inter-retry backoff (so a concurrent op reports the real
+   *  reason, not "not started" — `reestablishing` spans the whole retry loop incl. backoff),
+   *  else "endpoint not started" (genuine pre-start). */
+  notLiveMsg() {
+    return this.reconnecting || this.reestablishing ? "reconnecting \u2014 try again shortly" : "endpoint not started";
+  }
   async publishMsg(subject, msg) {
     if (!this.js)
-      throw new Error("endpoint not started");
+      throw new Error(this.notLiveMsg());
     await this.js.publish(subject, JSON.stringify(msg), { msgID: msg.id });
   }
   /** Create the three backing streams for this space (idempotent). Open-mode lazy create;
@@ -17111,6 +17427,29 @@ var CotalEndpoint = class extends import_node_events.EventEmitter {
       throw new Error("endpoint not started");
     await createSpaceStreams(this.jsm, this.space);
   }
+  /**
+   * Privileged: pre-create an agent's bind-only chat live-tail durable (auth mode), filtered to its
+   * `subscribe` set, so the agent can BIND it without holding CONSUMER.CREATE/UPDATE on CHAT — its
+   * live read can't be self-widened past `allowSubscribe`. The creator sets the filter; the agent
+   * never does (mirrors {@link provisionDmInbox}). Idempotent. The caller must be permissive on CHAT.
+   */
+  async provisionChatDurable(targetId, subscribe) {
+    const jsm = await this.manager();
+    await jsm.consumers.add(chatStream(this.space), chatDurableConfig(this.space, targetId, subscribe));
+  }
+  /**
+   * Privileged: move an agent's bind-only chat durable to a new channel set — the write half of the
+   * mediated join/leave. The manager calls this AFTER validating the set ⊆ the agent's
+   * `allowSubscribe`; the agent itself has no UPDATE grant, so this trusted path is the only way its
+   * live filter moves. The filter is rebuilt from channel names here (not from agent-supplied
+   * subjects) so a caller can't smuggle a hand-built filter.
+   */
+  async setChatFilterFor(targetId, channels) {
+    const jsm = await this.manager();
+    await jsm.consumers.update(chatStream(this.space), chatDurable(targetId), {
+      filter_subjects: collapseFilterSubjects(channels.map((ch) => chatSubject(this.space, "*", ch)))
+    });
+  }
   /**
    * Privileged: pre-create an agent's DM inbox durable (auth mode), so the agent can BIND
    * it without holding CONSUMER.CREATE on DM_<space>. The creator sets the filter to
@@ -17145,8 +17484,6 @@ var CotalEndpoint = class extends import_node_events.EventEmitter {
     if (!this.jsm)
       throw new Error("endpoint not started");
     const id = this.card.id;
-    const ack_wait = (0, import_transport_node3.nanos)(this.ackWaitMs);
-    const inactive_threshold = (0, import_transport_node3.nanos)(this.inactiveThresholdMs);
     if (!this.creds) {
       await this.jsm.consumers.add(dmStream(this.space), dmDurableConfig(this.space, id, {
         ackWaitMs: this.ackWaitMs,
@@ -17159,14 +17496,15 @@ var CotalEndpoint = class extends import_node_events.EventEmitter {
       const want = collapseFilterSubjects(this.channels.map((ch) => chatSubject(this.space, "*", ch)));
       const info = await this.consumerInfo(chatStream(this.space), durable);
       if (!info) {
-        await this.jsm.consumers.add(chatStream(this.space), {
-          durable_name: durable,
-          filter_subjects: want,
-          ack_policy: import_jetstream2.AckPolicy.Explicit,
-          ack_wait,
-          deliver_policy: import_jetstream2.DeliverPolicy.New,
-          inactive_threshold
-        });
+        if (this.creds)
+          throw new Error(`chat durable ${durable} not pre-created \u2014 a launcher must call provisionChatDurable (auth mode binds the durable, it never self-creates)`);
+        await this.jsm.consumers.add(chatStream(this.space), chatDurableConfig(this.space, id, this.channels, {
+          ackWaitMs: this.ackWaitMs,
+          inactiveThresholdMs: this.inactiveThresholdMs
+        }));
+      }
+      const consumed = (info?.delivered?.consumer_seq ?? 0) > 0;
+      if (!consumed) {
         const armed = await this.armJoin(this.channels);
         await this.pump(chatStream(this.space), durable);
         await this.backfillArmed(armed);
@@ -17175,7 +17513,7 @@ var CotalEndpoint = class extends import_node_events.EventEmitter {
         const haveFilters = info.config.filter_subjects ?? (info.config.filter_subject ? [info.config.filter_subject] : []);
         const gained = this.channels.filter((c) => !haveFilters.some((f) => subjectMatches(f, chatSubject(this.space, "*", c))));
         const armed = gained.length ? await this.armJoin(gained) : void 0;
-        if (!sameSet(haveFilters, want))
+        if (!this.creds && !sameSet(haveFilters, want))
           await this.jsm.consumers.update(chatStream(this.space), durable, { filter_subjects: want });
         if (armed)
           await this.backfillArmed(armed);
@@ -17292,63 +17630,107 @@ var CotalEndpoint = class extends import_node_events.EventEmitter {
     if (!this.channelKv)
       return { replay: effectiveReplay(void 0, void 0) };
     const [cfg, defaults] = await Promise.all([
-      readChannelConfig(this.channelKv, channel),
+      isConcreteChannel(channel) ? readChannelConfig(this.channelKv, channel) : Promise.resolve(void 0),
       readChannelDefaults(this.channelKv)
     ]);
     return { replay: effectiveReplay(cfg, defaults), windowMs: effectiveReplayWindowMs(cfg, defaults) };
   }
-  /** Read a channel's retained history up to `upToSeq` via JetStream **Direct Get** (a read
-   *  verb — no consumer create, so it rides a read-only grant) and emit each message as a
-   *  `historical` "message" event. `sinceMs` bounds how far back via a native Direct-Get
-   *  `start_time` (now − window); unset ⇒ the full retained window. New messages (`seq > upToSeq`)
-   *  are skipped — the live tail owns them. Pages the batch API; the ack handle is a no-op. */
-  async backfillChannel(channel, upToSeq, sinceMs) {
-    if (!this.jsm)
+  /**
+   * Read retained chat history on ONE channel subject through a name-scoped, single-filter
+   * EPHEMERAL pull consumer — the broker-contained replacement for the removed Direct Get. The
+   * create rides `$JS.API.CONSUMER.CREATE.<CHAT>.<chathist_id>.<subject>`, whose trailing filter
+   * token nats-server pins to the request body (JSConsumerCreateFilterSubjectMismatchErr, code
+   * 10131) — so an agent can only ever replay a channel its `allowSubscribe` grants. Single filter
+   * only (plural isn't ACL-constrainable); `AckPolicy.None` + `mem_storage` so it leaves no durable
+   * state, and it is deleted right after. Returns raw messages in stream order from `start`,
+   * stopping once past `untilSeq` (exclusive of it) or after `limit`. The per-instance name means
+   * calls must be serial — every reader here awaits to completion, so they are.
+   */
+  async collectHistory(subject, start, opts = {}) {
+    const run = this.histLock.then(() => this.collectHistoryInner(subject, start, opts));
+    this.histLock = run.catch(() => {
+    });
+    return run;
+  }
+  async collectHistoryInner(subject, start, opts = {}) {
+    if (!this.jsm || !this.js)
       throw new Error("endpoint not started");
-    const subject = chatSubject(this.space, "*", channel);
-    const collected = [];
-    const startTime = sinceMs === void 0 ? void 0 : new Date(Date.now() - sinceMs);
-    let startSeq = 1;
-    let first = true;
-    pages: for (; ; ) {
-      let last = 0;
-      let got = 0;
-      try {
-        const query = first && startTime !== void 0 ? { start_time: startTime, next_by_subj: subject, batch: 256 } : { seq: startSeq, next_by_subj: subject, batch: 256 };
-        first = false;
-        const iter = await this.jsm.direct.getBatch(chatStream(this.space), query);
-        for await (const sm of iter) {
+    const stream = chatStream(this.space);
+    const name = chatHistDurable(this.card.id);
+    const out = [];
+    try {
+      await this.jsm.consumers.delete(stream, name);
+    } catch {
+    }
+    await this.jsm.consumers.add(stream, {
+      name,
+      filter_subject: subject,
+      ack_policy: import_jetstream2.AckPolicy.None,
+      mem_storage: true,
+      inactive_threshold: (0, import_transport_node3.nanos)(3e4),
+      ..."time" in start ? { deliver_policy: import_jetstream2.DeliverPolicy.StartTime, opt_start_time: start.time.toISOString() } : { deliver_policy: import_jetstream2.DeliverPolicy.StartSequence, opt_start_seq: start.seq }
+    });
+    try {
+      const consumer = await this.js.consumers.get(stream, name);
+      let pending = (await consumer.info()).num_pending;
+      while (pending > 0) {
+        const want = Math.min(pending, 256);
+        const iter = await consumer.fetch({ max_messages: want, expires: 5e3 });
+        let got = 0;
+        for await (const m of iter) {
           got++;
-          if (sm.seq > upToSeq)
-            break pages;
-          last = sm.seq;
-          let msg;
-          try {
-            msg = sm.json();
-          } catch {
+          if (opts.untilSeq !== void 0 && m.seq > opts.untilSeq)
+            return out;
+          if (!subjectMatches(subject, m.subject))
             continue;
-          }
-          const parsed = parseSubject(sm.subject);
-          if (!parsed || msg.from?.id !== parsed.sender || msg.from.id === this.card.id)
-            continue;
-          collected.push({ msg, seq: sm.seq });
+          out.push(m);
+          if (opts.limit !== void 0 && out.length >= opts.limit)
+            return out;
         }
-      } catch (e) {
-        if (e.code === 404)
+        if (got < want)
           break;
-        this.emit("error", e);
-        break;
+        pending -= got;
+      }
+    } finally {
+      try {
+        await this.jsm.consumers.delete(stream, name);
+      } catch {
       }
-      if (got === 0 || last === 0)
-        break;
-      startSeq = last + 1;
+    }
+    return out;
+  }
+  /** Read a channel's retained history up to `upToSeq` (the join frontier) and emit each message
+   *  as a `historical` "message" event. `sinceMs` bounds how far back via a native consumer
+   *  `start_time` (now − window); unset ⇒ the full retained window. New messages (`seq > upToSeq`)
+   *  are skipped — the live tail owns them. Reads through the contained {@link collectHistory}. */
+  async backfillChannel(channel, upToSeq, sinceMs) {
+    const subject = chatSubject(this.space, "*", channel);
+    const start = sinceMs === void 0 ? { seq: 1 } : { time: new Date(Date.now() - sinceMs) };
+    let msgs;
+    try {
+      msgs = await this.collectHistory(subject, start, { untilSeq: upToSeq });
+    } catch (e) {
+      this.emit("error", e);
+      return 0;
     }
     const noop = { ack: () => {
     }, nak: () => {
     } };
-    for (const { msg } of collected)
+    let n = 0;
+    for (const sm of msgs) {
+      let msg;
+      try {
+        msg = sm.json();
+      } catch {
+        continue;
+      }
+      const parsed = parseSubject(sm.subject);
+      if (!parsed || msg.from?.id !== parsed.sender || msg.from.id === this.card.id)
+        continue;
       this.emit("message", msg, noop, { historical: true, kind: "channel" });
-    return collected.length;
+      n++;
+    }
+    return n;
   }
   /**
    * Replay-gated pull of a channel's retained ambient from `sinceSeq` (exclusive) forward — the
@@ -17359,52 +17741,37 @@ var CotalEndpoint = class extends import_node_events.EventEmitter {
    *
    * Honors the **same** per-channel replay gate as join-backfill ({@link joinPolicyFresh}): a
    * `replay=off` channel returns nothing, so `focus` can't become a history bypass for a channel
-   * that denies replay to everyone else (chat is `allow_direct` with no broker-level ACL, so this
-   * app gate is the entire boundary).
+   * that denies replay to everyone else (the read ACL bounds *which* channels recall can touch; this
+   * app gate bounds *whether* a permitted channel replays).
    */
   async recallChannel(channel, sinceSeq) {
     if (!this.jsm)
-      throw new Error("endpoint not started");
+      throw new Error(this.notLiveMsg());
     if (!isConcreteChannel(channel))
       return { messages: [], dropped: false };
     const policy = await this.joinPolicyFresh(channel);
     if (!policy.replay)
       return { messages: [], dropped: false };
     const subject = chatSubject(this.space, "*", channel);
+    let raw;
+    try {
+      raw = await this.collectHistory(subject, { seq: sinceSeq + 1 });
+    } catch (e) {
+      this.emit("error", e);
+      raw = [];
+    }
     const collected = [];
-    let startSeq = sinceSeq + 1;
-    pages: for (; ; ) {
-      let last = 0;
-      let got = 0;
+    for (const sm of raw) {
+      let msg;
       try {
-        const iter = await this.jsm.direct.getBatch(chatStream(this.space), {
-          seq: startSeq,
-          next_by_subj: subject,
-          batch: 256
-        });
-        for await (const sm of iter) {
-          got++;
-          last = sm.seq;
-          let msg;
-          try {
-            msg = sm.json();
-          } catch {
-            continue;
-          }
-          const parsed = parseSubject(sm.subject);
-          if (!parsed || msg.from?.id !== parsed.sender || msg.from.id === this.card.id)
-            continue;
-          collected.push(msg);
-        }
-      } catch (e) {
-        if (e.code === 404)
-          break;
-        this.emit("error", e);
-        break;
+        msg = sm.json();
+      } catch {
+        continue;
       }
-      if (got === 0 || last === 0)
-        break;
-      startSeq = last + 1;
+      const parsed = parseSubject(sm.subject);
+      if (!parsed || msg.from?.id !== parsed.sender || msg.from.id === this.card.id)
+        continue;
+      collected.push(msg);
     }
     const dropped = await this.channelDropped(subject, sinceSeq);
     return { messages: collected, dropped };
@@ -17435,22 +17802,16 @@ var CotalEndpoint = class extends import_node_events.EventEmitter {
     return oldest !== void 0 && oldest > sinceSeq + 1;
   }
   /** Sequence of the earliest message still retained on a channel subject (any sender), or
-   *  undefined if nothing is retained. One 1-message Direct Get — used for the recall drop marker. */
+   *  undefined if nothing is retained. One message through the contained {@link collectHistory} —
+   *  used for the recall drop marker. */
   async channelOldestSeq(subject) {
     if (!this.jsm)
       return void 0;
     try {
-      const iter = await this.jsm.direct.getBatch(chatStream(this.space), {
-        seq: 1,
-        next_by_subj: subject,
-        batch: 1
-      });
-      for await (const sm of iter)
-        return sm.seq;
-      return void 0;
+      const [first] = await this.collectHistory(subject, { seq: 1 }, { limit: 1 });
+      return first?.seq;
     } catch (e) {
-      if (e.code !== 404)
-        this.emit("error", e);
+      this.emit("error", e);
       return void 0;
     }
   }
@@ -17599,6 +17960,13 @@ function describeStatusError(err2) {
   }
   return err2;
 }
+function isPermissionDenied(e) {
+  if (e instanceof import_transport_node3.PermissionViolationError)
+    return true;
+  if (e?.cause instanceof import_transport_node3.PermissionViolationError)
+    return true;
+  return /permissions?\s+violation/i.test(String(e?.message ?? ""));
+}
 
 // ../../packages/core/dist/spaces.js
 var import_transport_node4 = __toESM(require_transport_node(), 1);
@@ -17645,9 +18013,17 @@ function configFromEnv(env = process.env) {
   const name = env.COTAL_NAME?.trim() || def?.name || (link ? (0, import_node_os.userInfo)().username : void 0);
   if (!name)
     throw new Error("COTAL_NAME, COTAL_AGENT_FILE or COTAL_LINK is required \u2014 a Cotal session needs an explicit identity from its launcher");
-  const channels = splitList(env.COTAL_CHANNELS);
-  const resolvedChannels = channels.length ? channels : def?.channels ?? link?.channels ?? ["general"];
-  const publish = splitList(env.COTAL_PUBLISH);
+  const subscribe = splitList(env.COTAL_SUBSCRIBE);
+  const resolvedSubscribe = subscribe.length ? subscribe : def?.subscribe ?? link?.channels ?? ["general"];
+  const allowSub = splitList(env.COTAL_ALLOW_SUBSCRIBE);
+  const resolvedAllowSub = allowSub.length ? allowSub : def?.allowSubscribe ?? resolvedSubscribe;
+  for (const ch of resolvedSubscribe)
+    if (!channelInAllow(resolvedAllowSub, ch))
+      throw new Error(`COTAL config: subscribe channel "${ch}" is not within allowSubscribe [${resolvedAllowSub.join(", ")}]`);
+  const allowPub = splitList(env.COTAL_ALLOW_PUBLISH);
+  const resolvedAllowPub = allowPub.length ? allowPub : def?.allowPublish ?? [];
+  for (const ch of [...resolvedSubscribe, ...resolvedAllowSub, ...resolvedAllowPub])
+    assertValidChannel(ch);
   const credsPath = env.COTAL_CREDS?.trim();
   return {
     space: env.COTAL_SPACE?.trim() || link?.space || "demo",
@@ -17658,8 +18034,11 @@ function configFromEnv(env = process.env) {
     description: def?.description,
     tags: def?.tags,
     servers: env.COTAL_SERVERS?.trim() || link?.servers || DEFAULT_SERVER,
-    channels: resolvedChannels,
-    publish: publish.length ? publish : def?.publish ?? resolvedChannels,
+    subscribe: resolvedSubscribe,
+    allowSubscribe: resolvedAllowSub,
+    // Post ACL is default-DENY: only what's explicitly declared (env > agent-file). The broker
+    // enforces it under auth; in open mode posting is unrestricted regardless (see laneLine).
+    allowPublish: resolvedAllowPub,
     kind: env.COTAL_KIND?.trim() || def?.kind || "agent",
     token: env.COTAL_TOKEN?.trim() || link?.token,
     user: link?.user,
@@ -17684,6 +18063,7 @@ var MeshAgent = class extends import_node_events2.EventEmitter {
   _status = "idle";
   _attention = "open";
   // F3: fail-open default; reset to open on SessionStart
+  _contextId;
   /** Chat-stream frontier captured when this agent entered `focus` — recall surfaces ambient
    *  published after it ("since you entered focus"). Undefined unless in focus. */
   focusSince;
@@ -17699,7 +18079,8 @@ var MeshAgent = class extends import_node_events2.EventEmitter {
       pass: config2.pass,
       creds: config2.creds,
       tls: config2.tls,
-      channels: config2.channels,
+      channels: config2.subscribe,
+      // the endpoint's live filter = the active read set
       card: {
         id: config2.id,
         name: config2.name,
@@ -17711,6 +18092,9 @@ var MeshAgent = class extends import_node_events2.EventEmitter {
     });
     this.ep.on("message", (m, d, meta3) => this.ingest(m, d, meta3));
     this.ep.on("error", (e) => this.log(`endpoint error: ${e.message}`));
+    this.ep.on("connection", (e) => {
+      this._connected = e.connected;
+    });
   }
   get id() {
     return this.ep.card.id;
@@ -17718,6 +18102,11 @@ var MeshAgent = class extends import_node_events2.EventEmitter {
   get connected() {
     return this._connected;
   }
+  /** Correlates outgoing messages to the host agent's current context/window. */
+  setContextId(contextId) {
+    const clean = contextId?.trim();
+    this._contextId = clean ? clean : void 0;
+  }
   /** Begin connecting (with background retry). Returns immediately. */
   start(retryMs = 3e3) {
     void this.connectLoop(retryMs);
@@ -17726,8 +18115,7 @@ var MeshAgent = class extends import_node_events2.EventEmitter {
     while (!this.stopping && !this._connected) {
       try {
         await this.ep.start();
-        this._connected = true;
-        this.log(`connected to ${this.config.servers} as ${this.who()} in space "${this.config.space}" on #${this.config.channels.join(", #")}`);
+        this.log(`connected to ${this.config.servers} as ${this.who()} in space "${this.config.space}" on #${this.config.subscribe.join(", #")}`);
       } catch (e) {
         this.log(`mesh unreachable (${e.message}); retrying in ${retryMs}ms`);
         await sleep(retryMs);
@@ -17736,8 +18124,26 @@ var MeshAgent = class extends import_node_events2.EventEmitter {
   }
   async stop() {
     this.stopping = true;
-    if (this._connected)
-      await this.ep.stop();
+    await this.ep.stop();
+  }
+  /** Manual reconnect: tear down the mesh connection and rebuild it in-process, WITHOUT
+   *  stopping the agent (the recovery path, so it does NOT assert connected). Delegates to
+   *  {@link CotalEndpoint.reconnect}, which is serialized with the self-heal supervisor and
+   *  interruptible. Returns a one-line status for the caller to surface (e.g. the
+   *  cotal_reconnect tool → TUI); on failure the endpoint keeps retrying in the background. */
+  async reconnect() {
+    if (this.stopping) {
+      return {
+        ok: false,
+        message: "This session is shutting down, so its Cotal mesh connection cannot be reconnected. Start a new session instead."
+      };
+    }
+    try {
+      await this.ep.reconnect();
+      return { ok: true, message: `Reconnected \u2713 (${this.config.name}@${this.config.space})` };
+    } catch (e) {
+      return { ok: false, message: `Reconnect failed: ${e.message}. Still retrying automatically \u2014 or run /reconnect to retry now.` };
+    }
   }
   // ---- inbox ---------------------------------------------------------------
   ingest(m, delivery, meta3) {
@@ -17865,7 +18271,7 @@ var MeshAgent = class extends import_node_events2.EventEmitter {
     const clean = normalizeMentions(mentions);
     if (clean)
       this.assertKnownMentions(clean);
-    return this.ep.multicast(text, { channel, mentions: clean });
+    return this.ep.multicast(text, { channel, mentions: clean, contextId: this._contextId });
   }
   /** Throw if any name isn't a peer we've observed. Validates against the FULL roster
    *  (incl. self — your own name is a valid participant; resolvePeer's self-filter would
@@ -17881,24 +18287,20 @@ var MeshAgent = class extends import_node_events2.EventEmitter {
   }
   async anycast(role, text) {
     this.assertConnected();
-    return this.ep.anycast(role, text);
+    return this.ep.anycast(role, text, { contextId: this._contextId });
   }
-  /** Resolve a peer by instance id (exact) or display name (case-insensitive, prefer present). */
+  /** Resolve a peer by instance id (exact) or display name. Deterministic and fail-loud: returns
+   *  one peer, `undefined` if none match, or throws `AmbiguousPeerError` on a same-name collision —
+   *  it never silently picks. See `resolvePeer` in @cotal-ai/core. */
   resolvePeer(target) {
-    const roster = this.ep.getRoster().filter((p) => p.card.id !== this.id);
-    const byId = roster.find((p) => p.card.id === target);
-    if (byId)
-      return byId;
-    const t = target.toLowerCase();
-    const present = roster.filter((p) => p.status !== "offline");
-    return present.find((p) => p.card.name.toLowerCase() === t) ?? roster.find((p) => p.card.name.toLowerCase() === t);
+    return resolvePeer(this.ep.getRoster(), target, { selfId: this.id });
   }
   async dm(target, text) {
     this.assertConnected();
     const peer = this.resolvePeer(target);
     if (!peer)
       throw new Error(`no peer "${target}" in space "${this.config.space}"`);
-    const msg = await this.ep.unicast(peer.card.id, text);
+    const msg = await this.ep.unicast(peer.card.id, text, { contextId: this._contextId });
     return { msg, peer };
   }
   // ---- supervision ---------------------------------------------------------
@@ -17907,23 +18309,32 @@ var MeshAgent = class extends import_node_events2.EventEmitter {
    *  runtime; from here it just joins the mesh as a lateral peer. */
   async spawn(name, role) {
     this.assertConnected();
-    return this.ep.requestControl("manager", { op: "start", args: { name, role } });
+    return this.ep.requestControl(CONTROL_PRIVILEGED, { op: "start", args: { name, role } });
   }
   /** Ask the manager to tear a teammate down (its `stop` op). Graceful by default —
    *  the session is told to exit cleanly (so it leaves the mesh) before the
-   *  process/tab is closed; `graceful:false` is a hard, immediate kill. */
+   *  process/tab is closed; `graceful:false` is a hard, immediate kill.
+   *
+   *  No `name` ⇒ self-despawn: rides the self-service control subject and the manager
+   *  resolves the target as the managed agent whose id == this caller — so it can only
+   *  ever stop itself, never a peer. A `name` ⇒ rides the privileged control subject
+   *  (transport-gated to spawn-capable/admin); the manager refines own-child vs admin. */
   async despawn(name, opts) {
     this.assertConnected();
-    return this.ep.requestControl("manager", {
+    const graceful = opts?.graceful ?? true;
+    if (!name) {
+      return this.ep.requestControl(CONTROL_SELF_SERVICE, { op: "stop", args: { graceful } });
+    }
+    return this.ep.requestControl(CONTROL_PRIVILEGED, {
       op: "stop",
-      args: { name, graceful: opts?.graceful ?? true }
+      args: { name, graceful }
     });
   }
   /** Ask the manager to purge the space's retained chat backlog (its `purge` op). Cleanup only —
    *  it doesn't touch live agents or the anycast work queue. `includeDms` also clears DM history. */
   async purgeHistory(opts) {
     this.assertConnected();
-    return this.ep.requestControl("manager", {
+    return this.ep.requestControl(CONTROL_PRIVILEGED, {
       op: "purge",
       args: { includeDms: opts?.includeDms ?? false }
     });
@@ -17933,9 +18344,10 @@ var MeshAgent = class extends import_node_events2.EventEmitter {
    *  half — so peers see the new persona; `spawn(name)` then launches an agent wearing it. */
   async definePersona(def) {
     this.assertConnected();
-    const reply = await this.ep.requestControl("manager", {
+    const reply = await this.ep.requestControl(CONTROL_PRIVILEGED, {
       op: "definePersona",
-      args: { name: def.name, role: def.role, model: def.model, persona: def.prompt }
+      // role is policy — set at spawn, never via definePersona; the manager ignores it regardless.
+      args: { name: def.name, model: def.model, persona: def.prompt }
     });
     if (reply.ok)
       await this.send(`persona \`${def.name}\` is now available \u2014 spawn it to bring it online`);
@@ -32542,6 +32954,13 @@ config(en_default());
 // ../connector-core/dist/tool-specs.js
 var ok = (text) => ({ text });
 var err = (text) => ({ text, isError: true });
+function controlFailure(action, e) {
+  const detail = e?.message ?? String(e);
+  if (isPermissionDenied(e)) {
+    return err(`${action}: this session isn't allowed to \u2014 its persona needs \`capabilities: [spawn]\` (which grants the privileged manager control subject). Add it and respawn so its creds re-mint. [${detail}]`);
+  }
+  return err(`${action}: no manager reachable (${detail}). Is the manager running?`);
+}
 function statusGlyph(s) {
   return s === "working" ? "\u25CF" : s === "waiting" ? "\u25D0" : s === "idle" ? "\u25CB" : "\xB7";
 }
@@ -32600,10 +33019,16 @@ function cotalToolSpecs(config2, source = "connector") {
         const roster = agent.roster();
         if (!roster.length)
           return ok(`No one is present in "${config2.space}" yet.`);
+        const counts = /* @__PURE__ */ new Map();
+        for (const p of roster) {
+          const n = p.card.name.toLowerCase();
+          counts.set(n, (counts.get(n) ?? 0) + 1);
+        }
         const lines = roster.map((p) => {
           const who = p.card.role ? `${p.card.name}/${p.card.role}` : p.card.name;
           const me = p.card.id === agent.id ? ` (you${agent.attention !== "open" ? `, ${agent.attention}` : ""})` : "";
-          return `${statusGlyph(p.status)} ${who} \u2014 ${p.status}${p.activity ? `: ${p.activity}` : ""}${me}`;
+          const id = (counts.get(p.card.name.toLowerCase()) ?? 0) > 1 ? ` \u2014 id: ${p.card.id}` : "";
+          return `${statusGlyph(p.status)} ${who} \u2014 ${p.status}${p.activity ? `: ${p.activity}` : ""}${me}${id}`;
         });
         return ok(`Present in "${config2.space}" (${roster.length}):
 ${lines.join("\n")}`);
@@ -32646,7 +33071,7 @@ ${all.map(fmtItem).join("\n")}`);
       description: "Broadcast a message to everyone on a channel in your space.",
       schema: {
         text: external_exports.string().describe("The message to broadcast."),
-        channel: external_exports.string().optional().describe(`Channel to send on (default: ${config2.channels.find(isConcreteChannel) ?? "general"}). Concrete only \u2014 not a wildcard like team.>; reply on the channel you received a message on.`),
+        channel: external_exports.string().optional().describe(`Channel to send on (default: ${config2.subscribe.find(isConcreteChannel) ?? "general"}). Concrete only \u2014 not a wildcard like team.>; reply on the channel you received a message on.`),
         mentions: external_exports.array(external_exports.string()).optional().describe("Names of peers to call out (e.g. ['bob']). Everyone on the channel still receives the message, but a mentioned peer gets high-priority delivery (eg @bob) \u2014 woken now if idle, instead of waiting for its next idle moment. Use sparingly: a mention WAKES that peer, so only call someone out when you need THAT specific peer to act now \u2014 never in an acknowledgement, thanks, or sign-off, or mentions ping-pong between peers and wake the channel in a loop.")
       },
       async run(agent, _config, { text: msg, channel, mentions }) {
@@ -32671,6 +33096,11 @@ ${all.map(fmtItem).join("\n")}`);
           const { peer } = await agent.dm(to, stripFaceTags(msg));
           return ok(`DM sent to ${peer.card.name}.`);
         } catch (e) {
+          if (e instanceof AmbiguousPeerError) {
+            const who = e.candidates.map((c) => `  \u2022 ${c.name}${c.role ? `/${c.role}` : ""} (${c.status}) \u2014 id: ${c.id}`).join("\n");
+            return err(`"${e.target}" is ambiguous \u2014 ${e.candidates.length} peers share that name. Re-send cotal_dm with the exact instance id as "to":
+${who}`);
+          }
           return err(`Couldn't DM: ${e.message}`);
         }
       }
@@ -32756,11 +33186,13 @@ ${lines.join("\n")}`);
     {
       name: "cotal_join",
       title: "Cotal: join a channel",
-      description: "Subscribe to a channel mid-session. Returns its registry info; if the channel replays, recent history is delivered to your inbox marked as catch-up (it pre-dates your join \u2014 don't treat it as live). Idempotent.",
+      description: "Subscribe to a channel mid-session. Returns its registry info; if the channel replays, recent history is delivered to your inbox marked as catch-up (it pre-dates your join \u2014 don't treat it as live). Idempotent. Bounded by your read ACL: a channel outside it is refused.",
       schema: {
         channel: external_exports.string().describe("The channel to join (e.g. incident).")
       },
       async run(agent, _config, { channel }) {
+        if (!channelInAllow(config2.allowSubscribe, channel))
+          return err(`Can't join #${channel}: it's outside your read ACL (allowSubscribe: ${config2.allowSubscribe.map((c) => `#${c}`).join(", ")}).`);
         try {
           const r = await agent.joinChannel(channel);
           if (!r.joined)
@@ -32796,7 +33228,7 @@ ${info}${caught}`);
       title: "Cotal: spawn a new teammate",
       description: "Ask the manager to start a new peer endpoint in your space. It joins the mesh as a lateral peer (and, when the manager runs the cmux runtime, appears in its own tab). Use when the team needs another agent.",
       schema: {
-        name: external_exports.string().describe("Unique name for the new peer."),
+        name: external_exports.string().describe("Name for the new peer; auto-numbered (e.g. reviewer-2) if taken."),
         role: external_exports.string().optional().describe("Optional role for the new peer (e.g. worker, reviewer).")
       },
       async run(agent, _config, { name, role }) {
@@ -32804,10 +33236,14 @@ ${info}${caught}`);
           const reply = await agent.spawn(name, role);
           if (!reply.ok)
             return err(`Couldn't spawn ${name}: ${reply.error ?? "manager refused"}`);
-          const mode = reply.data?.mode;
-          return ok(`Spawning ${role ? `${name}/${role}` : name}${mode ? ` (${mode})` : ""} \u2014 it will appear in the roster shortly.`);
+          const d = reply.data;
+          const actual = d?.name ?? name;
+          const mode = d?.mode;
+          const who = role ? `${actual}/${role}` : actual;
+          const lead = actual !== name ? `"${name}" was taken \u2014 spawning ${who} instead` : `Spawning ${who}`;
+          return ok(`${lead}${mode ? ` (${mode})` : ""} \u2014 it will appear in the roster shortly.`);
         } catch (e) {
-          return err(`Couldn't spawn ${name}: no manager reachable (${e.message}). Is the manager running?`);
+          return controlFailure(`Couldn't spawn ${name}`, e);
         }
       }
     },
@@ -32863,63 +33299,52 @@ ${info}${caught}`);
     {
       name: "cotal_despawn",
       title: "Cotal: stop a teammate",
-      description: "Ask the manager to tear a teammate down \u2014 it leaves the mesh and its process/tab is closed. Graceful by default (the session exits cleanly first); pass graceful:false for a hard, immediate kill. The inverse of cotal_spawn.",
+      description: "Ask the manager to tear a teammate down \u2014 it leaves the mesh and its process/tab is closed. Graceful by default (the session exits cleanly first); pass graceful:false for a hard, immediate kill. The inverse of cotal_spawn. Omit `name` to stop yourself (self-despawn): the manager resolves the target as your own managed entry, so it can only ever stop you, never a peer.",
       schema: {
-        name: external_exports.string().describe("Name of the peer to stop."),
+        name: external_exports.string().optional().describe("Name of the peer to stop. Omit to stop yourself (self-despawn)."),
         graceful: external_exports.boolean().optional().describe("Default true: let the session exit cleanly. false = hard kill.")
       },
       async run(agent, _config, { name, graceful }) {
         try {
           const reply = await agent.despawn(name, { graceful });
-          if (!reply.ok)
-            return err(`Couldn't despawn ${name}: ${reply.error ?? "manager refused"}`);
-          return ok(`Stopping ${name}${graceful === false ? " (hard)" : ""} \u2014 it will leave the roster shortly.`);
-        } catch (e) {
-          return err(`Couldn't despawn ${name}: no manager reachable (${e.message}). Is the manager running?`);
-        }
-      }
-    },
-    {
-      name: "cotal_purge",
-      title: "Cotal: clear chat history",
-      description: "Ask the manager to purge this space's retained chat backlog (channel history). Set includeDms to also clear direct-message history. Cleanup only \u2014 it does not affect live agents or the anycast work queue. Irreversible.",
-      schema: {
-        includeDms: external_exports.boolean().optional().describe("Default false: channel history only. true = also purge DM history.")
-      },
-      async run(agent, _config, { includeDms }) {
-        try {
-          const reply = await agent.purgeHistory({ includeDms });
-          if (!reply.ok)
-            return err(`Couldn't purge history: ${reply.error ?? "manager refused"}`);
-          const d = reply.data;
-          const chat = d?.chat ?? 0;
-          const dm = d?.dm;
-          return ok(`Cleared ${chat} channel message${chat === 1 ? "" : "s"}${dm === void 0 ? "" : ` and ${dm} DM${dm === 1 ? "" : "s"}`} from "${_config.space}".`);
+          if (!reply.ok) {
+            return err(`Couldn't despawn ${name ?? "self"}: ${reply.error ?? "manager refused"}`);
+          }
+          const who = name ?? "self";
+          return ok(`Stopping ${who}${graceful === false ? " (hard)" : ""} \u2014 it will leave the roster shortly.`);
         } catch (e) {
-          return err(`Couldn't purge history: no manager reachable (${e.message}). Is the manager running?`);
+          return controlFailure(`Couldn't despawn ${name ?? "self"}`, e);
         }
       }
     },
     {
       name: "cotal_persona",
       title: "Cotal: define a persona",
-      description: "Define a new persona and save it as config (the manager writes .cotal/agents/<name>.md), then announce it on the mesh. Afterwards cotal_spawn(name) launches a real agent wearing this persona/model. Use to grow the team with a custom role you describe on the fly.",
+      description: "Define a new persona and save it as config (the manager writes .cotal/agents/<name>.md), then announce it on the mesh. Afterwards cotal_spawn(name) launches a real agent wearing this persona/model. Use to grow the team with a custom persona you describe on the fly; set its role at spawn (cotal_spawn takes a role).",
       schema: {
         name: external_exports.string().regex(/^[A-Za-z0-9_-]+$/, "letters, digits, _ or - only").describe("Unique name for the persona (also the spawn name): letters, digits, _ or -."),
         prompt: external_exports.string().max(1e4).describe("The persona \u2014 an appended system prompt describing who this agent is."),
-        role: external_exports.string().max(120).optional().describe("Optional role label (e.g. reviewer, scout)."),
         model: external_exports.string().max(120).optional().describe("Optional model override (e.g. opus, sonnet).")
       },
-      async run(agent, _config, { name, prompt, role, model }) {
+      async run(agent, _config, { name, prompt, model }) {
         try {
-          const reply = await agent.definePersona({ name, prompt, role, model });
+          const reply = await agent.definePersona({ name, prompt, model });
           if (!reply.ok)
             return err(`Couldn't define ${name}: ${reply.error ?? "manager refused"}`);
           return ok(`Persona \`${name}\` saved \u2014 spawn it with cotal_spawn(name="${name}") to bring it online.`);
         } catch (e) {
-          return err(`Couldn't define ${name}: no manager reachable (${e.message}). Is the manager running?`);
+          return controlFailure(`Couldn't define ${name}`, e);
         }
       }
+    },
+    {
+      name: "cotal_reconnect",
+      title: "Cotal: reconnect to the mesh",
+      description: "Tear down and rebuild this session's mesh connection in-process \u2014 the manual recovery path when the connection has wedged (the counterpart to Claude Code's /mcp reconnect, and a complement to the automatic self-heal). Zero-argument; local only \u2014 it does not ride the mesh link. Returns a one-line status (Reconnected \u2713 / Reconnect failed \u2014 still retrying automatically, or this session is shutting down).",
+      async run(agent) {
+        const r = await agent.reconnect();
+        return r.ok ? ok(r.message) : err(r.message);
+      }
     }
   ];
 }