@cotal-ai/connector-claude-code 0.21.0 → 0.23.0

package/dist/mcp.cjs

@@ -406,11 +406,11 @@ var require_codegen = __commonJS({
         const rhs = this.rhs === void 0 ? "" : ` = ${this.rhs}`;
         return `${varKind} ${this.name}${rhs};` + _n;
       }
-      optimizeNames(names, constants) {
+      optimizeNames(names, constants4) {
         if (!names[this.name.str])
           return;
         if (this.rhs)
-          this.rhs = optimizeExpr(this.rhs, names, constants);
+          this.rhs = optimizeExpr(this.rhs, names, constants4);
         return this;
       }
       get names() {
@@ -427,10 +427,10 @@ var require_codegen = __commonJS({
       render({ _n }) {
         return `${this.lhs} = ${this.rhs};` + _n;
       }
-      optimizeNames(names, constants) {
+      optimizeNames(names, constants4) {
         if (this.lhs instanceof code_1.Name && !names[this.lhs.str] && !this.sideEffects)
           return;
-        this.rhs = optimizeExpr(this.rhs, names, constants);
+        this.rhs = optimizeExpr(this.rhs, names, constants4);
         return this;
       }
       get names() {
@@ -491,8 +491,8 @@ var require_codegen = __commonJS({
       optimizeNodes() {
         return `${this.code}` ? this : void 0;
       }
-      optimizeNames(names, constants) {
-        this.code = optimizeExpr(this.code, names, constants);
+      optimizeNames(names, constants4) {
+        this.code = optimizeExpr(this.code, names, constants4);
         return this;
       }
       get names() {
@@ -521,12 +521,12 @@ var require_codegen = __commonJS({
         }
         return nodes.length > 0 ? this : void 0;
       }
-      optimizeNames(names, constants) {
+      optimizeNames(names, constants4) {
         const { nodes } = this;
         let i = nodes.length;
         while (i--) {
           const n = nodes[i];
-          if (n.optimizeNames(names, constants))
+          if (n.optimizeNames(names, constants4))
             continue;
           subtractNames(names, n.names);
           nodes.splice(i, 1);
@@ -579,12 +579,12 @@ var require_codegen = __commonJS({
           return void 0;
         return this;
       }
-      optimizeNames(names, constants) {
+      optimizeNames(names, constants4) {
         var _a3;
-        this.else = (_a3 = this.else) === null || _a3 === void 0 ? void 0 : _a3.optimizeNames(names, constants);
-        if (!(super.optimizeNames(names, constants) || this.else))
+        this.else = (_a3 = this.else) === null || _a3 === void 0 ? void 0 : _a3.optimizeNames(names, constants4);
+        if (!(super.optimizeNames(names, constants4) || this.else))
           return;
-        this.condition = optimizeExpr(this.condition, names, constants);
+        this.condition = optimizeExpr(this.condition, names, constants4);
         return this;
       }
       get names() {
@@ -607,10 +607,10 @@ var require_codegen = __commonJS({
       render(opts) {
         return `for(${this.iteration})` + super.render(opts);
       }
-      optimizeNames(names, constants) {
-        if (!super.optimizeNames(names, constants))
+      optimizeNames(names, constants4) {
+        if (!super.optimizeNames(names, constants4))
           return;
-        this.iteration = optimizeExpr(this.iteration, names, constants);
+        this.iteration = optimizeExpr(this.iteration, names, constants4);
         return this;
       }
       get names() {
@@ -646,10 +646,10 @@ var require_codegen = __commonJS({
       render(opts) {
         return `for(${this.varKind} ${this.name} ${this.loop} ${this.iterable})` + super.render(opts);
       }
-      optimizeNames(names, constants) {
-        if (!super.optimizeNames(names, constants))
+      optimizeNames(names, constants4) {
+        if (!super.optimizeNames(names, constants4))
           return;
-        this.iterable = optimizeExpr(this.iterable, names, constants);
+        this.iterable = optimizeExpr(this.iterable, names, constants4);
         return this;
       }
       get names() {
@@ -691,11 +691,11 @@ var require_codegen = __commonJS({
         (_b = this.finally) === null || _b === void 0 ? void 0 : _b.optimizeNodes();
         return this;
       }
-      optimizeNames(names, constants) {
+      optimizeNames(names, constants4) {
         var _a3, _b;
-        super.optimizeNames(names, constants);
-        (_a3 = this.catch) === null || _a3 === void 0 ? void 0 : _a3.optimizeNames(names, constants);
-        (_b = this.finally) === null || _b === void 0 ? void 0 : _b.optimizeNames(names, constants);
+        super.optimizeNames(names, constants4);
+        (_a3 = this.catch) === null || _a3 === void 0 ? void 0 : _a3.optimizeNames(names, constants4);
+        (_b = this.finally) === null || _b === void 0 ? void 0 : _b.optimizeNames(names, constants4);
         return this;
       }
       get names() {
@@ -996,7 +996,7 @@ var require_codegen = __commonJS({
     function addExprNames(names, from) {
       return from instanceof code_1._CodeOrName ? addNames(names, from.names) : names;
     }
-    function optimizeExpr(expr, names, constants) {
+    function optimizeExpr(expr, names, constants4) {
       if (expr instanceof code_1.Name)
         return replaceName(expr);
       if (!canOptimize(expr))
@@ -1011,14 +1011,14 @@ var require_codegen = __commonJS({
         return items;
       }, []));
       function replaceName(n) {
-        const c = constants[n.str];
+        const c = constants4[n.str];
         if (c === void 0 || names[n.str] !== 1)
           return n;
         delete names[n.str];
         return c;
       }
       function canOptimize(e) {
-        return e instanceof code_1._Code && e._items.some((c) => c instanceof code_1.Name && names[c.str] === 1 && constants[c.str] !== void 0);
+        return e instanceof code_1._Code && e._items.some((c) => c instanceof code_1.Name && names[c.str] === 1 && constants4[c.str] !== void 0);
       }
     }
     function subtractNames(names, from) {
@@ -7887,16 +7887,16 @@ var require_ipparser = __commonJS({
       ip[15] = d;
       return ip;
     }
-    function isIP(h) {
-      return parseIP(h) !== void 0;
+    function isIP(h2) {
+      return parseIP(h2) !== void 0;
     }
-    function parseIP(h) {
-      for (let i = 0; i < h.length; i++) {
-        switch (h[i]) {
+    function parseIP(h2) {
+      for (let i = 0; i < h2.length; i++) {
+        switch (h2[i]) {
           case ".":
-            return parseIPv4(h);
+            return parseIPv4(h2);
           case ":":
-            return parseIPv6(h);
+            return parseIPv6(h2);
         }
       }
       return;
@@ -8092,12 +8092,12 @@ var require_servers = __commonJS({
       const protocol = port === 80 ? "https" : "http";
       const url2 = new URL(`${protocol}://${u}`);
       url2.port = `${port}`;
-      let hostname4 = url2.hostname;
-      if (hostname4.charAt(0) === "[") {
-        hostname4 = hostname4.substring(1, hostname4.length - 1);
+      let hostname5 = url2.hostname;
+      if (hostname5.charAt(0) === "[") {
+        hostname5 = hostname5.substring(1, hostname5.length - 1);
       }
       const listen = url2.host;
-      return { listen, hostname: hostname4, port };
+      return { listen, hostname: hostname5, port };
     }
     var ServerImpl = class _ServerImpl {
       src;
@@ -9605,9 +9605,9 @@ var require_headers = __commonJS({
         const mh = new _MsgHdrsImpl();
         const s = encoders_1.TD.decode(a);
         const lines = s.split("\r\n");
-        const h = lines[0];
-        if (h !== HEADER) {
-          let str2 = h.replace(HEADER, "").trim();
+        const h2 = lines[0];
+        if (h2 !== HEADER) {
+          let str2 = h2.replace(HEADER, "").trim();
           if (str2.length > 0) {
             mh._code = parseInt(str2, 10);
             if (isNaN(mh._code)) {
@@ -9766,12 +9766,12 @@ ${k}: ${v[i]}`;
         return this._description;
       }
       static fromRecord(r) {
-        const h = new _MsgHdrsImpl();
+        const h2 = new _MsgHdrsImpl();
         for (const k in r) {
           const v = r[k];
-          h.headers.set(k, Array.isArray(v) ? v : [`${v}`]);
+          h2.headers.set(k, Array.isArray(v) ? v : [`${v}`]);
         }
-        return h;
+        return h2;
       }
     };
     exports2.MsgHdrsImpl = MsgHdrsImpl;
@@ -10475,11 +10475,11 @@ var require_nacl_fast = __commonJS({
       var _9 = new Uint8Array(32);
       _9[0] = 9;
       var gf0 = gf(), gf1 = gf([1]), _121665 = gf([56129, 1]), D = gf([30883, 4953, 19914, 30187, 55467, 16705, 2637, 112, 59544, 30585, 16505, 36039, 65139, 11119, 27886, 20995]), D2 = gf([61785, 9906, 39828, 60374, 45398, 33411, 5274, 224, 53552, 61171, 33010, 6542, 64743, 22239, 55772, 9222]), X = gf([54554, 36645, 11616, 51542, 42930, 38181, 51040, 26924, 56412, 64982, 57905, 49316, 21502, 52590, 14035, 8553]), Y = gf([26200, 26214, 26214, 26214, 26214, 26214, 26214, 26214, 26214, 26214, 26214, 26214, 26214, 26214, 26214, 26214]), I = gf([41136, 18958, 6951, 50414, 58488, 44335, 6150, 12099, 55207, 15867, 153, 11085, 57099, 20417, 9344, 11139]);
-      function ts64(x, i, h, l) {
-        x[i] = h >> 24 & 255;
-        x[i + 1] = h >> 16 & 255;
-        x[i + 2] = h >> 8 & 255;
-        x[i + 3] = h & 255;
+      function ts64(x, i, h2, l) {
+        x[i] = h2 >> 24 & 255;
+        x[i + 1] = h2 >> 16 & 255;
+        x[i + 2] = h2 >> 8 & 255;
+        x[i + 3] = h2 & 255;
         x[i + 4] = l >> 24 & 255;
         x[i + 5] = l >> 16 & 255;
         x[i + 6] = l >> 8 & 255;
@@ -11158,10 +11158,10 @@ var require_nacl_fast = __commonJS({
         s.finish(out, outpos);
         return 0;
       }
-      function crypto_onetimeauth_verify(h, hpos, m, mpos, n, k) {
+      function crypto_onetimeauth_verify(h2, hpos, m, mpos, n, k) {
         var x = new Uint8Array(16);
         crypto_onetimeauth(x, 0, m, mpos, n, k);
-        return crypto_verify_16(h, hpos, x, 0);
+        return crypto_verify_16(h2, hpos, x, 0);
       }
       function crypto_secretbox(c, m, d, n, k) {
         var i;
@@ -11914,7 +11914,7 @@ var require_nacl_fast = __commonJS({
         1246189591
       ];
       function crypto_hashblocks_hl(hh, hl, m, n) {
-        var wh = new Int32Array(16), wl = new Int32Array(16), bh0, bh1, bh2, bh3, bh4, bh5, bh6, bh7, bl0, bl1, bl2, bl3, bl4, bl5, bl6, bl7, th, tl, i, j, h, l, a, b, c, d;
+        var wh = new Int32Array(16), wl = new Int32Array(16), bh0, bh1, bh2, bh3, bh4, bh5, bh6, bh7, bl0, bl1, bl2, bl3, bl4, bl5, bl6, bl7, th, tl, i, j, h2, l, a, b, c, d;
         var ah0 = hh[0], ah1 = hh[1], ah2 = hh[2], ah3 = hh[3], ah4 = hh[4], ah5 = hh[5], ah6 = hh[6], ah7 = hh[7], al0 = hl[0], al1 = hl[1], al2 = hl[2], al3 = hl[3], al4 = hl[4], al5 = hl[5], al6 = hl[6], al7 = hl[7];
         var pos = 0;
         while (n >= 128) {
@@ -11940,76 +11940,76 @@ var require_nacl_fast = __commonJS({
             bl5 = al5;
             bl6 = al6;
             bl7 = al7;
-            h = ah7;
+            h2 = ah7;
             l = al7;
             a = l & 65535;
             b = l >>> 16;
-            c = h & 65535;
-            d = h >>> 16;
-            h = (ah4 >>> 14 | al4 << 32 - 14) ^ (ah4 >>> 18 | al4 << 32 - 18) ^ (al4 >>> 41 - 32 | ah4 << 32 - (41 - 32));
+            c = h2 & 65535;
+            d = h2 >>> 16;
+            h2 = (ah4 >>> 14 | al4 << 32 - 14) ^ (ah4 >>> 18 | al4 << 32 - 18) ^ (al4 >>> 41 - 32 | ah4 << 32 - (41 - 32));
             l = (al4 >>> 14 | ah4 << 32 - 14) ^ (al4 >>> 18 | ah4 << 32 - 18) ^ (ah4 >>> 41 - 32 | al4 << 32 - (41 - 32));
             a += l & 65535;
             b += l >>> 16;
-            c += h & 65535;
-            d += h >>> 16;
-            h = ah4 & ah5 ^ ~ah4 & ah6;
+            c += h2 & 65535;
+            d += h2 >>> 16;
+            h2 = ah4 & ah5 ^ ~ah4 & ah6;
             l = al4 & al5 ^ ~al4 & al6;
             a += l & 65535;
             b += l >>> 16;
-            c += h & 65535;
-            d += h >>> 16;
-            h = K[i * 2];
+            c += h2 & 65535;
+            d += h2 >>> 16;
+            h2 = K[i * 2];
             l = K[i * 2 + 1];
             a += l & 65535;
             b += l >>> 16;
-            c += h & 65535;
-            d += h >>> 16;
-            h = wh[i % 16];
+            c += h2 & 65535;
+            d += h2 >>> 16;
+            h2 = wh[i % 16];
             l = wl[i % 16];
             a += l & 65535;
             b += l >>> 16;
-            c += h & 65535;
-            d += h >>> 16;
+            c += h2 & 65535;
+            d += h2 >>> 16;
             b += a >>> 16;
             c += b >>> 16;
             d += c >>> 16;
             th = c & 65535 | d << 16;
             tl = a & 65535 | b << 16;
-            h = th;
+            h2 = th;
             l = tl;
             a = l & 65535;
             b = l >>> 16;
-            c = h & 65535;
-            d = h >>> 16;
-            h = (ah0 >>> 28 | al0 << 32 - 28) ^ (al0 >>> 34 - 32 | ah0 << 32 - (34 - 32)) ^ (al0 >>> 39 - 32 | ah0 << 32 - (39 - 32));
+            c = h2 & 65535;
+            d = h2 >>> 16;
+            h2 = (ah0 >>> 28 | al0 << 32 - 28) ^ (al0 >>> 34 - 32 | ah0 << 32 - (34 - 32)) ^ (al0 >>> 39 - 32 | ah0 << 32 - (39 - 32));
             l = (al0 >>> 28 | ah0 << 32 - 28) ^ (ah0 >>> 34 - 32 | al0 << 32 - (34 - 32)) ^ (ah0 >>> 39 - 32 | al0 << 32 - (39 - 32));
             a += l & 65535;
             b += l >>> 16;
-            c += h & 65535;
-            d += h >>> 16;
-            h = ah0 & ah1 ^ ah0 & ah2 ^ ah1 & ah2;
+            c += h2 & 65535;
+            d += h2 >>> 16;
+            h2 = ah0 & ah1 ^ ah0 & ah2 ^ ah1 & ah2;
             l = al0 & al1 ^ al0 & al2 ^ al1 & al2;
             a += l & 65535;
             b += l >>> 16;
-            c += h & 65535;
-            d += h >>> 16;
+            c += h2 & 65535;
+            d += h2 >>> 16;
             b += a >>> 16;
             c += b >>> 16;
             d += c >>> 16;
             bh7 = c & 65535 | d << 16;
             bl7 = a & 65535 | b << 16;
-            h = bh3;
+            h2 = bh3;
             l = bl3;
             a = l & 65535;
             b = l >>> 16;
-            c = h & 65535;
-            d = h >>> 16;
-            h = th;
+            c = h2 & 65535;
+            d = h2 >>> 16;
+            h2 = th;
             l = tl;
             a += l & 65535;
             b += l >>> 16;
-            c += h & 65535;
-            d += h >>> 16;
+            c += h2 & 65535;
+            d += h2 >>> 16;
             b += a >>> 16;
             c += b >>> 16;
             d += c >>> 16;
@@ -12033,34 +12033,34 @@ var require_nacl_fast = __commonJS({
             al0 = bl7;
             if (i % 16 === 15) {
               for (j = 0; j < 16; j++) {
-                h = wh[j];
+                h2 = wh[j];
                 l = wl[j];
                 a = l & 65535;
                 b = l >>> 16;
-                c = h & 65535;
-                d = h >>> 16;
-                h = wh[(j + 9) % 16];
+                c = h2 & 65535;
+                d = h2 >>> 16;
+                h2 = wh[(j + 9) % 16];
                 l = wl[(j + 9) % 16];
                 a += l & 65535;
                 b += l >>> 16;
-                c += h & 65535;
-                d += h >>> 16;
+                c += h2 & 65535;
+                d += h2 >>> 16;
                 th = wh[(j + 1) % 16];
                 tl = wl[(j + 1) % 16];
-                h = (th >>> 1 | tl << 32 - 1) ^ (th >>> 8 | tl << 32 - 8) ^ th >>> 7;
+                h2 = (th >>> 1 | tl << 32 - 1) ^ (th >>> 8 | tl << 32 - 8) ^ th >>> 7;
                 l = (tl >>> 1 | th << 32 - 1) ^ (tl >>> 8 | th << 32 - 8) ^ (tl >>> 7 | th << 32 - 7);
                 a += l & 65535;
                 b += l >>> 16;
-                c += h & 65535;
-                d += h >>> 16;
+                c += h2 & 65535;
+                d += h2 >>> 16;
                 th = wh[(j + 14) % 16];
                 tl = wl[(j + 14) % 16];
-                h = (th >>> 19 | tl << 32 - 19) ^ (tl >>> 61 - 32 | th << 32 - (61 - 32)) ^ th >>> 6;
+                h2 = (th >>> 19 | tl << 32 - 19) ^ (tl >>> 61 - 32 | th << 32 - (61 - 32)) ^ th >>> 6;
                 l = (tl >>> 19 | th << 32 - 19) ^ (th >>> 61 - 32 | tl << 32 - (61 - 32)) ^ (tl >>> 6 | th << 32 - 6);
                 a += l & 65535;
                 b += l >>> 16;
-                c += h & 65535;
-                d += h >>> 16;
+                c += h2 & 65535;
+                d += h2 >>> 16;
                 b += a >>> 16;
                 c += b >>> 16;
                 d += c >>> 16;
@@ -12069,137 +12069,137 @@ var require_nacl_fast = __commonJS({
               }
             }
           }
-          h = ah0;
+          h2 = ah0;
           l = al0;
           a = l & 65535;
           b = l >>> 16;
-          c = h & 65535;
-          d = h >>> 16;
-          h = hh[0];
+          c = h2 & 65535;
+          d = h2 >>> 16;
+          h2 = hh[0];
           l = hl[0];
           a += l & 65535;
           b += l >>> 16;
-          c += h & 65535;
-          d += h >>> 16;
+          c += h2 & 65535;
+          d += h2 >>> 16;
           b += a >>> 16;
           c += b >>> 16;
           d += c >>> 16;
           hh[0] = ah0 = c & 65535 | d << 16;
           hl[0] = al0 = a & 65535 | b << 16;
-          h = ah1;
+          h2 = ah1;
           l = al1;
           a = l & 65535;
           b = l >>> 16;
-          c = h & 65535;
-          d = h >>> 16;
-          h = hh[1];
+          c = h2 & 65535;
+          d = h2 >>> 16;
+          h2 = hh[1];
           l = hl[1];
           a += l & 65535;
           b += l >>> 16;
-          c += h & 65535;
-          d += h >>> 16;
+          c += h2 & 65535;
+          d += h2 >>> 16;
           b += a >>> 16;
           c += b >>> 16;
           d += c >>> 16;
           hh[1] = ah1 = c & 65535 | d << 16;
           hl[1] = al1 = a & 65535 | b << 16;
-          h = ah2;
+          h2 = ah2;
           l = al2;
           a = l & 65535;
           b = l >>> 16;
-          c = h & 65535;
-          d = h >>> 16;
-          h = hh[2];
+          c = h2 & 65535;
+          d = h2 >>> 16;
+          h2 = hh[2];
           l = hl[2];
           a += l & 65535;
           b += l >>> 16;
-          c += h & 65535;
-          d += h >>> 16;
+          c += h2 & 65535;
+          d += h2 >>> 16;
           b += a >>> 16;
           c += b >>> 16;
           d += c >>> 16;
           hh[2] = ah2 = c & 65535 | d << 16;
           hl[2] = al2 = a & 65535 | b << 16;
-          h = ah3;
+          h2 = ah3;
           l = al3;
           a = l & 65535;
           b = l >>> 16;
-          c = h & 65535;
-          d = h >>> 16;
-          h = hh[3];
+          c = h2 & 65535;
+          d = h2 >>> 16;
+          h2 = hh[3];
           l = hl[3];
           a += l & 65535;
           b += l >>> 16;
-          c += h & 65535;
-          d += h >>> 16;
+          c += h2 & 65535;
+          d += h2 >>> 16;
           b += a >>> 16;
           c += b >>> 16;
           d += c >>> 16;
           hh[3] = ah3 = c & 65535 | d << 16;
           hl[3] = al3 = a & 65535 | b << 16;
-          h = ah4;
+          h2 = ah4;
           l = al4;
           a = l & 65535;
           b = l >>> 16;
-          c = h & 65535;
-          d = h >>> 16;
-          h = hh[4];
+          c = h2 & 65535;
+          d = h2 >>> 16;
+          h2 = hh[4];
           l = hl[4];
           a += l & 65535;
           b += l >>> 16;
-          c += h & 65535;
-          d += h >>> 16;
+          c += h2 & 65535;
+          d += h2 >>> 16;
           b += a >>> 16;
           c += b >>> 16;
           d += c >>> 16;
           hh[4] = ah4 = c & 65535 | d << 16;
           hl[4] = al4 = a & 65535 | b << 16;
-          h = ah5;
+          h2 = ah5;
           l = al5;
           a = l & 65535;
           b = l >>> 16;
-          c = h & 65535;
-          d = h >>> 16;
-          h = hh[5];
+          c = h2 & 65535;
+          d = h2 >>> 16;
+          h2 = hh[5];
           l = hl[5];
           a += l & 65535;
           b += l >>> 16;
-          c += h & 65535;
-          d += h >>> 16;
+          c += h2 & 65535;
+          d += h2 >>> 16;
           b += a >>> 16;
           c += b >>> 16;
           d += c >>> 16;
           hh[5] = ah5 = c & 65535 | d << 16;
           hl[5] = al5 = a & 65535 | b << 16;
-          h = ah6;
+          h2 = ah6;
           l = al6;
           a = l & 65535;
           b = l >>> 16;
-          c = h & 65535;
-          d = h >>> 16;
-          h = hh[6];
+          c = h2 & 65535;
+          d = h2 >>> 16;
+          h2 = hh[6];
           l = hl[6];
           a += l & 65535;
           b += l >>> 16;
-          c += h & 65535;
-          d += h >>> 16;
+          c += h2 & 65535;
+          d += h2 >>> 16;
           b += a >>> 16;
           c += b >>> 16;
           d += c >>> 16;
           hh[6] = ah6 = c & 65535 | d << 16;
           hl[6] = al6 = a & 65535 | b << 16;
-          h = ah7;
+          h2 = ah7;
           l = al7;
           a = l & 65535;
           b = l >>> 16;
-          c = h & 65535;
-          d = h >>> 16;
-          h = hh[7];
+          c = h2 & 65535;
+          d = h2 >>> 16;
+          h2 = hh[7];
           l = hl[7];
           a += l & 65535;
           b += l >>> 16;
-          c += h & 65535;
-          d += h >>> 16;
+          c += h2 & 65535;
+          d += h2 >>> 16;
           b += a >>> 16;
           c += b >>> 16;
           d += c >>> 16;
@@ -12240,7 +12240,7 @@ var require_nacl_fast = __commonJS({
         return 0;
       }
       function add(p, q) {
-        var a = gf(), b = gf(), c = gf(), d = gf(), e = gf(), f = gf(), g = gf(), h = gf(), t = gf();
+        var a = gf(), b = gf(), c = gf(), d = gf(), e = gf(), f = gf(), g = gf(), h2 = gf(), t = gf();
         Z(a, p[1], p[0]);
         Z(t, q[1], q[0]);
         M(a, a, t);
@@ -12254,11 +12254,11 @@ var require_nacl_fast = __commonJS({
         Z(e, b, a);
         Z(f, d, c);
         A(g, d, c);
-        A(h, b, a);
+        A(h2, b, a);
         M(p[0], e, f);
-        M(p[1], h, g);
+        M(p[1], h2, g);
         M(p[2], g, f);
-        M(p[3], e, h);
+        M(p[3], e, h2);
       }
       function cswap(p, q, b) {
         var i;
@@ -12342,7 +12342,7 @@ var require_nacl_fast = __commonJS({
         modL(r, x);
       }
       function crypto_sign(sm, m, n, sk) {
-        var d = new Uint8Array(64), h = new Uint8Array(64), r = new Uint8Array(64);
+        var d = new Uint8Array(64), h2 = new Uint8Array(64), r = new Uint8Array(64);
         var i, j, x = new Float64Array(64);
         var p = [gf(), gf(), gf(), gf()];
         crypto_hash(d, sk, 32);
@@ -12357,13 +12357,13 @@ var require_nacl_fast = __commonJS({
         scalarbase(p, r);
         pack(sm, p);
         for (i = 32; i < 64; i++) sm[i] = sk[i];
-        crypto_hash(h, sm, n + 64);
-        reduce(h);
+        crypto_hash(h2, sm, n + 64);
+        reduce(h2);
         for (i = 0; i < 64; i++) x[i] = 0;
         for (i = 0; i < 32; i++) x[i] = r[i];
         for (i = 0; i < 32; i++) {
           for (j = 0; j < 32; j++) {
-            x[i + j] += h[i] * d[j];
+            x[i + j] += h2[i] * d[j];
           }
         }
         modL(sm.subarray(32), x);
@@ -12399,15 +12399,15 @@ var require_nacl_fast = __commonJS({
       }
       function crypto_sign_open(m, sm, n, pk) {
         var i;
-        var t = new Uint8Array(32), h = new Uint8Array(64);
+        var t = new Uint8Array(32), h2 = new Uint8Array(64);
         var p = [gf(), gf(), gf(), gf()], q = [gf(), gf(), gf(), gf()];
         if (n < 64) return -1;
         if (unpackneg(q, pk)) return -1;
         for (i = 0; i < n; i++) m[i] = sm[i];
         for (i = 0; i < 32; i++) m[i + 32] = pk[i];
-        crypto_hash(h, m, n);
-        reduce(h);
-        scalarmult(p, q, h);
+        crypto_hash(h2, m, n);
+        reduce(h2);
+        scalarmult(p, q, h2);
         scalarbase(q, sm.subarray(32));
         add(p, q);
         pack(t, p);
@@ -12641,9 +12641,9 @@ var require_nacl_fast = __commonJS({
       nacl2.sign.signatureLength = crypto_sign_BYTES;
       nacl2.hash = function(msg) {
         checkArrayTypes(msg);
-        var h = new Uint8Array(crypto_hash_BYTES);
-        crypto_hash(h, msg, msg.length);
-        return h;
+        var h2 = new Uint8Array(crypto_hash_BYTES);
+        crypto_hash(h2, msg, msg.length);
+        return h2;
       };
       nacl2.hash.hashLength = crypto_hash_BYTES;
       nacl2.verify = function(x, y) {
@@ -14065,9 +14065,9 @@ var require_protocol = __commonJS({
         }
       }
       static async connect(options, publisher) {
-        const h = new _ProtocolHandler(options, publisher);
-        await h.dialLoop();
-        return h;
+        const h2 = new _ProtocolHandler(options, publisher);
+        await h2.dialLoop();
+        return h2;
       }
       static toError(s) {
         let err2 = errors_1.errors.PermissionViolationError.parse(s);
@@ -16399,9 +16399,9 @@ var require_jsbaseclient_api = __commonJS({
           a = new TextEncoder().encode(JSON.stringify(data));
         }
         if (typeof minApiVersion === "number") {
-          const h = reqOpts.headers ?? (0, internal_1.headers)();
-          h.set(types_1.JsHeaders.RequiredApiLevel, minApiVersion.toString());
-          reqOpts.headers = h;
+          const h2 = reqOpts.headers ?? (0, internal_1.headers)();
+          h2.set(types_1.JsHeaders.RequiredApiLevel, minApiVersion.toString());
+          reqOpts.headers = h2;
         }
         let retries = r || 1;
         retries = retries === -1 ? Number.MAX_SAFE_INTEGER : retries;
@@ -20796,11 +20796,11 @@ var require_kv = __commonJS({
           sc.subject_delete_marker_ttl = (0, internal_1.nanos)(bo.markerTTL);
         }
         if (opts.mirror) {
-          const mirror2 = Object.assign({}, opts.mirror);
-          if (!mirror2.name.startsWith(types_1.kvPrefix)) {
-            mirror2.name = `${types_1.kvPrefix}${mirror2.name}`;
+          const mirror = Object.assign({}, opts.mirror);
+          if (!mirror.name.startsWith(types_1.kvPrefix)) {
+            mirror.name = `${types_1.kvPrefix}${mirror.name}`;
           }
-          sc.mirror = mirror2;
+          sc.mirror = mirror;
           sc.mirror_direct = true;
         } else if (opts.sources) {
           const sources = opts.sources.map((s) => {
@@ -20863,17 +20863,17 @@ var require_kv = __commonJS({
         this._prefixLen = 0;
         this.prefix = `$KV.${this.bucket}`;
         this.useJsPrefix = this.js.apiPrefix !== "$JS.API";
-        const { mirror: mirror2 } = info.config;
-        if (mirror2) {
-          let n = mirror2.name;
+        const { mirror } = info.config;
+        if (mirror) {
+          let n = mirror.name;
           if (n.startsWith(types_1.kvPrefix)) {
             n = n.substring(types_1.kvPrefix.length);
           }
-          if (mirror2.external && mirror2.external.api !== "") {
-            const mb = mirror2.name.substring(types_1.kvPrefix.length);
+          if (mirror.external && mirror.external.api !== "") {
+            const mb = mirror.name.substring(types_1.kvPrefix.length);
             this.useJsPrefix = false;
             this.prefix = `$KV.${mb}`;
-            this.editPrefix = `${mirror2.external.api}.$KV.${n}`;
+            this.editPrefix = `${mirror.external.api}.$KV.${n}`;
           } else {
             this.editPrefix = this.prefix;
           }
@@ -20952,8 +20952,8 @@ var require_kv = __commonJS({
       close() {
         return Promise.resolve();
       }
-      dataLen(data, h) {
-        const slen = h ? h.get(internal_2.JsHeaders.MessageSizeHdr) || "" : "";
+      dataLen(data, h2) {
+        const slen = h2 ? h2.get(internal_2.JsHeaders.MessageSizeHdr) || "" : "";
         if (slen !== "") {
           return parseInt(slen, 10);
         }
@@ -21005,13 +21005,13 @@ var require_kv = __commonJS({
         data = this.codec.value.encode(data);
         const o = { timeout: opts?.timeout };
         if (opts.previousSeq !== void 0) {
-          const h = (0, internal_1.headers)();
-          o.headers = h;
-          h.set(internal_2.PubHeaders.ExpectedLastSubjectSequenceHdr, `${opts.previousSeq}`);
+          const h2 = (0, internal_1.headers)();
+          o.headers = h2;
+          h2.set(internal_2.PubHeaders.ExpectedLastSubjectSequenceHdr, `${opts.previousSeq}`);
         }
         if (markerTTL) {
-          const h = o.headers || (0, internal_1.headers)();
-          h.set(internal_2.PubHeaders.MessageTTL, markerTTL);
+          const h2 = o.headers || (0, internal_1.headers)();
+          h2.set(internal_2.PubHeaders.MessageTTL, markerTTL);
         }
         try {
           const pa = await this.js.publish(this.subjectForKey(ek, true), data, o);
@@ -21105,19 +21105,19 @@ var require_kv = __commonJS({
       async _doDeleteOrPurge(k, op, opts) {
         const ek = this.encodeKey(k);
         this.validateKey(ek);
-        const h = (0, internal_1.headers)();
-        h.set(exports2.kvOperationHdr, op);
+        const h2 = (0, internal_1.headers)();
+        h2.set(exports2.kvOperationHdr, op);
         if (op === "PURGE") {
           const popts = opts;
-          h.set(internal_2.JsHeaders.RollupHdr, internal_2.JsHeaders.RollupValueSubject);
+          h2.set(internal_2.JsHeaders.RollupHdr, internal_2.JsHeaders.RollupValueSubject);
           if (typeof popts?.ttl === "string" && popts.ttl !== "") {
-            h.set(internal_2.PubHeaders.MessageTTL, `${popts.ttl}`);
+            h2.set(internal_2.PubHeaders.MessageTTL, `${popts.ttl}`);
           }
         }
         if (opts?.previousSeq) {
-          h.set(internal_2.PubHeaders.ExpectedLastSubjectSequenceHdr, `${opts.previousSeq}`);
+          h2.set(internal_2.PubHeaders.ExpectedLastSubjectSequenceHdr, `${opts.previousSeq}`);
         }
-        await this.js.publish(this.subjectForKey(ek, true), internal_1.Empty, { headers: h });
+        await this.js.publish(this.subjectForKey(ek, true), internal_1.Empty, { headers: h2 });
       }
       _buildCC(k, content, opts = {}) {
         const a = !Array.isArray(k) ? [k] : k;
@@ -22869,7 +22869,7 @@ var require_sha256 = __commonJS({
         this.hash();
       };
       Sha256.prototype.hash = function() {
-        var a = this.h0, b = this.h1, c = this.h2, d = this.h3, e = this.h4, f = this.h5, g = this.h6, h = this.h7, blocks2 = this.blocks, j, s0, s1, maj, t1, t2, ch, ab, da, cd, bc;
+        var a = this.h0, b = this.h1, c = this.h2, d = this.h3, e = this.h4, f = this.h5, g = this.h6, h2 = this.h7, blocks2 = this.blocks, j, s0, s1, maj, t1, t2, ch, ab, da, cd, bc;
         for (j = 16; j < 64; ++j) {
           t1 = blocks2[j - 15];
           s0 = (t1 >>> 7 | t1 << 25) ^ (t1 >>> 18 | t1 << 14) ^ t1 >>> 3;
@@ -22883,12 +22883,12 @@ var require_sha256 = __commonJS({
             if (this.is224) {
               ab = 300032;
               t1 = blocks2[0] - 1413257819;
-              h = t1 - 150054599 << 0;
+              h2 = t1 - 150054599 << 0;
               d = t1 + 24177077 << 0;
             } else {
               ab = 704751109;
               t1 = blocks2[0] - 210244248;
-              h = t1 - 1521486534 << 0;
+              h2 = t1 - 1521486534 << 0;
               d = t1 + 143694565 << 0;
             }
             this.first = false;
@@ -22898,16 +22898,16 @@ var require_sha256 = __commonJS({
             ab = a & b;
             maj = ab ^ a & c ^ bc;
             ch = e & f ^ ~e & g;
-            t1 = h + s1 + ch + K[j] + blocks2[j];
+            t1 = h2 + s1 + ch + K[j] + blocks2[j];
             t2 = s0 + maj;
-            h = d + t1 << 0;
+            h2 = d + t1 << 0;
             d = t1 + t2 << 0;
           }
           s0 = (d >>> 2 | d << 30) ^ (d >>> 13 | d << 19) ^ (d >>> 22 | d << 10);
-          s1 = (h >>> 6 | h << 26) ^ (h >>> 11 | h << 21) ^ (h >>> 25 | h << 7);
+          s1 = (h2 >>> 6 | h2 << 26) ^ (h2 >>> 11 | h2 << 21) ^ (h2 >>> 25 | h2 << 7);
           da = d & a;
           maj = da ^ d & b ^ ab;
-          ch = h & e ^ ~h & f;
+          ch = h2 & e ^ ~h2 & f;
           t1 = g + s1 + ch + K[j + 1] + blocks2[j + 1];
           t2 = s0 + maj;
           g = c + t1 << 0;
@@ -22916,7 +22916,7 @@ var require_sha256 = __commonJS({
           s1 = (g >>> 6 | g << 26) ^ (g >>> 11 | g << 21) ^ (g >>> 25 | g << 7);
           cd = c & d;
           maj = cd ^ c & a ^ da;
-          ch = g & h ^ ~g & e;
+          ch = g & h2 ^ ~g & e;
           t1 = f + s1 + ch + K[j + 2] + blocks2[j + 2];
           t2 = s0 + maj;
           f = b + t1 << 0;
@@ -22925,7 +22925,7 @@ var require_sha256 = __commonJS({
           s1 = (f >>> 6 | f << 26) ^ (f >>> 11 | f << 21) ^ (f >>> 25 | f << 7);
           bc = b & c;
           maj = bc ^ b & d ^ cd;
-          ch = f & g ^ ~f & h;
+          ch = f & g ^ ~f & h2;
           t1 = e + s1 + ch + K[j + 3] + blocks2[j + 3];
           t2 = s0 + maj;
           e = a + t1 << 0;
@@ -22939,7 +22939,7 @@ var require_sha256 = __commonJS({
         this.h4 = this.h4 + e << 0;
         this.h5 = this.h5 + f << 0;
         this.h6 = this.h6 + g << 0;
-        this.h7 = this.h7 + h << 0;
+        this.h7 = this.h7 + h2 << 0;
       };
       Sha256.prototype.hex = function() {
         this.finalize();
@@ -23138,13 +23138,13 @@ var require_sha2562 = __commonJS({
         }
         const create = m.createHash;
         factory = () => {
-          const h = create("sha256");
+          const h2 = create("sha256");
           return {
             update(data) {
-              h.update(data);
+              h2.update(data);
             },
             digest() {
-              return new Uint8Array(h.digest());
+              return new Uint8Array(h2.digest());
             }
           };
         };
@@ -23623,16 +23623,16 @@ var require_objectstore = __commonJS({
               const digest = base64_1.Base64UrlPaddedCodec.encode(sha.digest());
               info.digest = `${exports2.digestType}${digest}`;
               info.deleted = false;
-              const h = (0, internal_1.headers)();
+              const h2 = (0, internal_1.headers)();
               if (typeof previousRevision === "number") {
-                h.set(internal_2.PubHeaders.ExpectedLastSubjectSequenceHdr, `${previousRevision}`);
+                h2.set(internal_2.PubHeaders.ExpectedLastSubjectSequenceHdr, `${previousRevision}`);
               }
-              h.set(internal_2.JsHeaders.RollupHdr, internal_2.JsHeaders.RollupValueSubject);
+              h2.set(internal_2.JsHeaders.RollupHdr, internal_2.JsHeaders.RollupValueSubject);
               const ack = fi ? await fi.last(metaSubj, JSON.stringify(info), {
-                headers: h,
+                headers: h2,
                 timeout
               }) : await this.js.publish(metaSubj, JSON.stringify(info), {
-                headers: h,
+                headers: h2,
                 timeout
               });
               info.revision = ack.seq;
@@ -23840,10 +23840,10 @@ var require_objectstore = __commonJS({
         info.size = 0;
         info.chunks = 0;
         info.digest = "";
-        const h = (0, internal_1.headers)();
-        h.set(internal_2.JsHeaders.RollupHdr, internal_2.JsHeaders.RollupValueSubject);
+        const h2 = (0, internal_1.headers)();
+        h2.set(internal_2.JsHeaders.RollupHdr, internal_2.JsHeaders.RollupValueSubject);
         await this.js.publish(this._metaSubject(info.name), JSON.stringify(info), {
-          headers: h
+          headers: h2
         });
         return this.jsm.streams.purge(this.stream, {
           filter: this._chunkSubject(info.nuid)
@@ -55478,7 +55478,7 @@ var StdioServerTransport = class {
 
 // ../connector-core/dist/config.js
 var import_node_os = require("node:os");
-var import_node_fs2 = require("node:fs");
+var import_node_fs3 = require("node:fs");
 
 // ../../packages/core/dist/subjects.js
 var import_node_crypto = require("node:crypto");
@@ -57220,6 +57220,10 @@ for (const def of [...Object.values(RECORD_KINDS), ...AUTHORITY_KIND_DEFS]) {
 Object.freeze(AUTHORITY_KIND_DEFS);
 Object.freeze(RECORD_KINDS);
 var AUTHORITY_DEF_SET = new Set(AUTHORITY_KIND_DEFS);
+function isCasLoss(e) {
+  const code = e?.code;
+  return code === 10071 || code === 10164;
+}
 
 // ../../packages/core/dist/endpoint-journal.js
 var import_transport_node = __toESM(require_transport_node(), 1);
@@ -57545,8 +57549,8 @@ function assertDeadline(deadlineMs, what = "deadlineMs") {
   return deadlineMs;
 }
 function isNoRespondersMsg(msg) {
-  const h = msg.headers;
-  return h != null && (h.code === 503 || h.status === "503");
+  const h2 = msg.headers;
+  return h2 != null && (h2.code === 503 || h2.status === "503");
 }
 async function raceBounded(read, ms, what, details) {
   let t;
@@ -57566,10 +57570,10 @@ var unansweredDetail = (op) => ({ kind: EP_UNANSWERED, endpoint: op.endpoint, co
 function replySubjectFor(space, caller, n) {
   return `${spacePrefix(space)}.ep.reply.*.*.*.${callerTokens(caller).join(".")}.${n}`;
 }
-function staleEpochRefusal(op, responder, held, reference, rail) {
+function staleEpochRefusal(op, responder, held2, reference, rail) {
   const who2 = `the ${op.endpoint} instance ${responder.instanceId}`;
-  const ahead = responder.epoch > held;
-  const situation = reference === "bind" ? ahead ? `${who2} answered at epoch ${responder.epoch}, but this handle resolved against it at epoch ${held}: a SUCCESSOR of the bound incarnation answered (a restart or supersession), so the handle is the stale side; re-resolve to adopt it` : `${who2} answered at epoch ${responder.epoch}, but this handle resolved against it at epoch ${held}: a SUPERSEDED incarnation still connected answered, and its reply is rejected` : ahead ? `${who2} answered at epoch ${responder.epoch}, but a currency read of its registered epoch returned ${held}: the responder is ahead of the registry read (the read lags a restart), so its reply is rejected until the read catches up; nothing of this caller's is stale` : `${who2} answered at epoch ${responder.epoch}, but a currency read of its registered epoch returned ${held}: a SUPERSEDED incarnation still connected answered, and its reply is rejected`;
+  const ahead = responder.epoch > held2;
+  const situation = reference === "bind" ? ahead ? `${who2} answered at epoch ${responder.epoch}, but this handle resolved against it at epoch ${held2}: a SUCCESSOR of the bound incarnation answered (a restart or supersession), so the handle is the stale side; re-resolve to adopt it` : `${who2} answered at epoch ${responder.epoch}, but this handle resolved against it at epoch ${held2}: a SUPERSEDED incarnation still connected answered, and its reply is rejected` : ahead ? `${who2} answered at epoch ${responder.epoch}, but a currency read of its registered epoch returned ${held2}: the responder is ahead of the registry read (the read lags a restart), so its reply is rejected until the read catches up; nothing of this caller's is stale` : `${who2} answered at epoch ${responder.epoch}, but a currency read of its registered epoch returned ${held2}: a SUPERSEDED incarnation still connected answered, and its reply is rejected`;
   const detail = {
     kind: EP_UNBOUND_RESPONDER,
     endpoint: op.endpoint,
@@ -57577,7 +57581,7 @@ function staleEpochRefusal(op, responder, held, reference, rail) {
     answeredBy: responder.instanceId,
     ...reference === "bind" ? { boundTo: responder.instanceId } : {},
     answeredEpoch: responder.epoch,
-    heldEpoch: held,
+    heldEpoch: held2,
     reference,
     pinned: rail === "inst"
   };
@@ -58684,8 +58688,8 @@ var Types;
 })(Types || (Types = {}));
 (function(nacl2) {
   "use strict";
-  var u64 = function(h, l) {
-    this.hi = h | 0 >>> 0;
+  var u64 = function(h2, l) {
+    this.hi = h2 | 0 >>> 0;
     this.lo = l | 0 >>> 0;
   };
   var gf = function(init) {
@@ -58800,9 +58804,9 @@ var Types;
     return u << 8 | x[i + 0] & 255;
   }
   function dl64(x, i) {
-    var h = x[i] << 24 | x[i + 1] << 16 | x[i + 2] << 8 | x[i + 3];
+    var h2 = x[i] << 24 | x[i + 1] << 16 | x[i + 2] << 8 | x[i + 3];
     var l = x[i + 4] << 24 | x[i + 5] << 16 | x[i + 6] << 8 | x[i + 7];
-    return new u64(h, l);
+    return new u64(h2, l);
   }
   function st32(x, j, u) {
     var i;
@@ -58832,7 +58836,7 @@ var Types;
   function crypto_verify_32(x, xi, y, yi) {
     return vn(x, xi, y, yi, 32);
   }
-  function core(out, inp, k, c, h) {
+  function core(out, inp, k, c, h2) {
     var w = new Uint32Array(16), x = new Uint32Array(16), y = new Uint32Array(16), t = new Uint32Array(4);
     var i, j, m;
     for (i = 0; i < 4; i++) {
@@ -58853,7 +58857,7 @@ var Types;
       }
       for (m = 0; m < 16; m++) x[m] = w[m];
     }
-    if (h) {
+    if (h2) {
       for (i = 0; i < 16; i++) x[i] = x[i] + y[i] | 0;
       for (i = 0; i < 4; i++) {
         x[5 * i] = x[5 * i] - ld32(c, 4 * i) | 0;
@@ -58931,11 +58935,11 @@ var Types;
     crypto_core_hsalsa20(s, n, k, sigma);
     return crypto_stream_salsa20_xor(c, cpos, m, mpos, d, n.subarray(16), s);
   }
-  function add1305(h, c) {
+  function add1305(h2, c) {
     var j, u = 0;
     for (j = 0; j < 17; j++) {
-      u = u + (h[j] + c[j] | 0) | 0;
-      h[j] = u & 255;
+      u = u + (h2[j] + c[j] | 0) | 0;
+      h2[j] = u & 255;
       u >>>= 8;
     }
   }
@@ -58960,8 +58964,8 @@ var Types;
   ]);
   function crypto_onetimeauth(out, outpos, m, mpos, n, k) {
     var s, i, j, u;
-    var x = new Uint32Array(17), r = new Uint32Array(17), h = new Uint32Array(17), c = new Uint32Array(17), g = new Uint32Array(17);
-    for (j = 0; j < 17; j++) r[j] = h[j] = 0;
+    var x = new Uint32Array(17), r = new Uint32Array(17), h2 = new Uint32Array(17), c = new Uint32Array(17), g = new Uint32Array(17);
+    for (j = 0; j < 17; j++) r[j] = h2[j] = 0;
     for (j = 0; j < 16; j++) r[j] = k[j];
     r[3] &= 15;
     r[4] &= 252;
@@ -58976,43 +58980,43 @@ var Types;
       c[j] = 1;
       mpos += j;
       n -= j;
-      add1305(h, c);
+      add1305(h2, c);
       for (i = 0; i < 17; i++) {
         x[i] = 0;
-        for (j = 0; j < 17; j++) x[i] = x[i] + h[j] * (j <= i ? r[i - j] : 320 * r[i + 17 - j] | 0) | 0 | 0;
+        for (j = 0; j < 17; j++) x[i] = x[i] + h2[j] * (j <= i ? r[i - j] : 320 * r[i + 17 - j] | 0) | 0 | 0;
       }
-      for (i = 0; i < 17; i++) h[i] = x[i];
+      for (i = 0; i < 17; i++) h2[i] = x[i];
       u = 0;
       for (j = 0; j < 16; j++) {
-        u = u + h[j] | 0;
-        h[j] = u & 255;
+        u = u + h2[j] | 0;
+        h2[j] = u & 255;
         u >>>= 8;
       }
-      u = u + h[16] | 0;
-      h[16] = u & 3;
+      u = u + h2[16] | 0;
+      h2[16] = u & 3;
       u = 5 * (u >>> 2) | 0;
       for (j = 0; j < 16; j++) {
-        u = u + h[j] | 0;
-        h[j] = u & 255;
+        u = u + h2[j] | 0;
+        h2[j] = u & 255;
         u >>>= 8;
       }
-      u = u + h[16] | 0;
-      h[16] = u;
+      u = u + h2[16] | 0;
+      h2[16] = u;
     }
-    for (j = 0; j < 17; j++) g[j] = h[j];
-    add1305(h, minusp);
-    s = -(h[16] >>> 7) | 0;
-    for (j = 0; j < 17; j++) h[j] ^= s & (g[j] ^ h[j]);
+    for (j = 0; j < 17; j++) g[j] = h2[j];
+    add1305(h2, minusp);
+    s = -(h2[16] >>> 7) | 0;
+    for (j = 0; j < 17; j++) h2[j] ^= s & (g[j] ^ h2[j]);
     for (j = 0; j < 16; j++) c[j] = k[j + 16];
     c[16] = 0;
-    add1305(h, c);
-    for (j = 0; j < 16; j++) out[outpos + j] = h[j];
+    add1305(h2, c);
+    for (j = 0; j < 16; j++) out[outpos + j] = h2[j];
     return 0;
   }
-  function crypto_onetimeauth_verify(h, hpos, m, mpos, n, k) {
+  function crypto_onetimeauth_verify(h2, hpos, m, mpos, n, k) {
     var x = new Uint8Array(16);
     crypto_onetimeauth(x, 0, m, mpos, n, k);
-    return crypto_verify_16(h, hpos, x, 0);
+    return crypto_verify_16(h2, hpos, x, 0);
   }
   function crypto_secretbox(c, m, d, n, k) {
     var i;
@@ -59215,14 +59219,14 @@ var Types;
     return crypto_box_open_afternm(m, c, d, n, k);
   }
   function add64() {
-    var a = 0, b = 0, c = 0, d = 0, m16 = 65535, l, h, i;
+    var a = 0, b = 0, c = 0, d = 0, m16 = 65535, l, h2, i;
     for (i = 0; i < arguments.length; i++) {
       l = arguments[i].lo;
-      h = arguments[i].hi;
+      h2 = arguments[i].hi;
       a += l & m16;
       b += l >>> 16;
-      c += h & m16;
-      d += h >>> 16;
+      c += h2 & m16;
+      d += h2 >>> 16;
     }
     b += a >>> 16;
     c += b >>> 16;
@@ -59233,31 +59237,31 @@ var Types;
     return new u64(x.hi >>> c, x.lo >>> c | x.hi << 32 - c);
   }
   function xor64() {
-    var l = 0, h = 0, i;
+    var l = 0, h2 = 0, i;
     for (i = 0; i < arguments.length; i++) {
       l ^= arguments[i].lo;
-      h ^= arguments[i].hi;
+      h2 ^= arguments[i].hi;
     }
-    return new u64(h, l);
+    return new u64(h2, l);
   }
   function R(x, c) {
-    var h, l, c1 = 32 - c;
+    var h2, l, c1 = 32 - c;
     if (c < 32) {
-      h = x.hi >>> c | x.lo << c1;
+      h2 = x.hi >>> c | x.lo << c1;
       l = x.lo >>> c | x.hi << c1;
     } else if (c < 64) {
-      h = x.lo >>> c | x.hi << c1;
+      h2 = x.lo >>> c | x.hi << c1;
       l = x.hi >>> c | x.lo << c1;
     }
-    return new u64(h, l);
+    return new u64(h2, l);
   }
   function Ch(x, y, z2) {
-    var h = x.hi & y.hi ^ ~x.hi & z2.hi, l = x.lo & y.lo ^ ~x.lo & z2.lo;
-    return new u64(h, l);
+    var h2 = x.hi & y.hi ^ ~x.hi & z2.hi, l = x.lo & y.lo ^ ~x.lo & z2.lo;
+    return new u64(h2, l);
   }
   function Maj(x, y, z2) {
-    var h = x.hi & y.hi ^ x.hi & z2.hi ^ y.hi & z2.hi, l = x.lo & y.lo ^ x.lo & z2.lo ^ y.lo & z2.lo;
-    return new u64(h, l);
+    var h2 = x.hi & y.hi ^ x.hi & z2.hi ^ y.hi & z2.hi, l = x.lo & y.lo ^ x.lo & z2.lo ^ y.lo & z2.lo;
+    return new u64(h2, l);
   }
   function Sigma0(x) {
     return xor64(R(x, 28), R(x, 34), R(x, 39));
@@ -59448,10 +59452,10 @@ var Types;
     121
   ]);
   function crypto_hash(out, m, n) {
-    var h = new Uint8Array(64), x = new Uint8Array(256);
+    var h2 = new Uint8Array(64), x = new Uint8Array(256);
     var i, b = n;
-    for (i = 0; i < 64; i++) h[i] = iv[i];
-    crypto_hashblocks(h, m, n);
+    for (i = 0; i < 64; i++) h2[i] = iv[i];
+    crypto_hashblocks(h2, m, n);
     n %= 128;
     for (i = 0; i < 256; i++) x[i] = 0;
     for (i = 0; i < n; i++) x[i] = m[b - n + i];
@@ -59459,12 +59463,12 @@ var Types;
     n = 256 - 128 * (n < 112 ? 1 : 0);
     x[n - 9] = 0;
     ts64(x, n - 8, new u64(b / 536870912 | 0, b << 3));
-    crypto_hashblocks(h, x, n);
-    for (i = 0; i < 64; i++) out[i] = h[i];
+    crypto_hashblocks(h2, x, n);
+    for (i = 0; i < 64; i++) out[i] = h2[i];
     return 0;
   }
   function add(p, q) {
-    var a = gf(), b = gf(), c = gf(), d = gf(), e = gf(), f = gf(), g = gf(), h = gf(), t = gf();
+    var a = gf(), b = gf(), c = gf(), d = gf(), e = gf(), f = gf(), g = gf(), h2 = gf(), t = gf();
     Z(a, p[1], p[0]);
     Z(t, q[1], q[0]);
     M(a, a, t);
@@ -59478,11 +59482,11 @@ var Types;
     Z(e, b, a);
     Z(f, d, c);
     A(g, d, c);
-    A(h, b, a);
+    A(h2, b, a);
     M(p[0], e, f);
-    M(p[1], h, g);
+    M(p[1], h2, g);
     M(p[2], g, f);
-    M(p[3], e, h);
+    M(p[3], e, h2);
   }
   function cswap(p, q, b) {
     var i;
@@ -59609,7 +59613,7 @@ var Types;
     modL(r, x);
   }
   function crypto_sign(sm, m, n, sk) {
-    var d = new Uint8Array(64), h = new Uint8Array(64), r = new Uint8Array(64);
+    var d = new Uint8Array(64), h2 = new Uint8Array(64), r = new Uint8Array(64);
     var i, j, x = new Float64Array(64);
     var p = [
       gf(),
@@ -59629,13 +59633,13 @@ var Types;
     scalarbase(p, r);
     pack(sm, p);
     for (i = 32; i < 64; i++) sm[i] = sk[i];
-    crypto_hash(h, sm, n + 64);
-    reduce(h);
+    crypto_hash(h2, sm, n + 64);
+    reduce(h2);
     for (i = 0; i < 64; i++) x[i] = 0;
     for (i = 0; i < 32; i++) x[i] = r[i];
     for (i = 0; i < 32; i++) {
       for (j = 0; j < 32; j++) {
-        x[i + j] += h[i] * d[j];
+        x[i + j] += h2[i] * d[j];
       }
     }
     modL(sm.subarray(32), x);
@@ -59671,7 +59675,7 @@ var Types;
   }
   function crypto_sign_open(m, sm, n, pk) {
     var i;
-    var t = new Uint8Array(32), h = new Uint8Array(64);
+    var t = new Uint8Array(32), h2 = new Uint8Array(64);
     var p = [
       gf(),
       gf(),
@@ -59687,9 +59691,9 @@ var Types;
     if (unpackneg(q, pk)) return -1;
     for (i = 0; i < n; i++) m[i] = sm[i];
     for (i = 0; i < 32; i++) m[i + 32] = pk[i];
-    crypto_hash(h, m, n);
-    reduce(h);
-    scalarmult(p, q, h);
+    crypto_hash(h2, m, n);
+    reduce(h2);
+    scalarmult(p, q, h2);
     scalarbase(q, sm.subarray(32));
     add(p, q);
     pack(t, p);
@@ -59930,9 +59934,9 @@ var Types;
   nacl2.sign.signatureLength = crypto_sign_BYTES;
   nacl2.hash = function(msg) {
     checkArrayTypes(msg);
-    var h = new Uint8Array(crypto_hash_BYTES);
-    crypto_hash(h, msg, msg.length);
-    return h;
+    var h2 = new Uint8Array(crypto_hash_BYTES);
+    crypto_hash(h2, msg, msg.length);
+    return h2;
   };
   nacl2.hash.hashLength = crypto_hash_BYTES;
   nacl2.verify = function(x, y) {
@@ -60643,6 +60647,31 @@ function loadAgentFile(path) {
   };
 }
 
+// ../../packages/core/dist/fs-safe.js
+var import_node_fs2 = require("node:fs");
+var import_node_path = require("node:path");
+function ensureDirNoSymlink(parent, ...segments) {
+  let dir = parent;
+  for (const seg of segments) {
+    dir = (0, import_node_path.join)(dir, seg);
+    let st;
+    try {
+      st = (0, import_node_fs2.lstatSync)(dir);
+    } catch (e) {
+      if (e.code === "ENOENT") {
+        (0, import_node_fs2.mkdirSync)(dir, { mode: 448 });
+        continue;
+      }
+      throw e;
+    }
+    if (st.isSymbolicLink())
+      throw new Error(`refusing to write under "${dir}": it is a symlink`);
+    if (!st.isDirectory())
+      throw new Error(`refusing to write under "${dir}": not a directory`);
+  }
+  return dir;
+}
+
 // ../../packages/core/dist/secret-fs.js
 var isWin = process.platform === "win32";
 
@@ -62644,11 +62673,11 @@ var CotalEndpoint = class _CotalEndpoint extends import_node_events.EventEmitter
     await this.manager();
     const kv = await this.membersRegistry();
     const existing = await readMember(kv, channel, owner, lifecycleUid);
-    const open = existing?.record.state === "durable-active" && existing.record.leaveCursor === void 0;
-    if (open && existing.record.activated)
+    const open5 = existing?.record.state === "durable-active" && existing.record.leaveCursor === void 0;
+    if (open5 && existing.record.activated)
       return { durable: true, generation: existing.record.generation };
-    const joinCursor = open ? existing.record.joinCursor : await this.chatFrontier();
-    const generation = open ? existing.record.generation : (existing?.record.generation ?? 0) + 1;
+    const joinCursor = open5 ? existing.record.joinCursor : await this.chatFrontier();
+    const generation = open5 ? existing.record.generation : (existing?.record.generation ?? 0) + 1;
     const base = {
       channel,
       owner,
@@ -62660,7 +62689,7 @@ var CotalEndpoint = class _CotalEndpoint extends import_node_events.EventEmitter
       writerIdentity: this.card.id,
       updatedAt: Date.now()
     };
-    if (!open)
+    if (!open5)
       await commitMember(kv, base);
     const fence = Math.max(await this.chatFrontier(), await this.fanoutDeliveredSeq());
     const cu = await this.catchupCopy(owner, lifecycleUid, channel, joinCursor, fence, generation);
@@ -64255,6 +64284,12 @@ function isAguiFramePart(part) {
   }
 }
 
+// ../../packages/core/dist/event-channel.js
+var EVENT_CHANNEL_PREFIX = "events.";
+function eventChannel(principal) {
+  return `${EVENT_CHANNEL_PREFIX}${principalKey(principal.owner, principal.actor).key}`;
+}
+
 // ../../packages/core/dist/broker-floor.js
 var BROKER_FLOOR = Object.freeze({ major: 2, minor: 12 });
 
@@ -64328,7 +64363,7 @@ function configFromEnv(env = process.env) {
     userAuth = {
       owner: userVars.owner,
       actor: userVars.actor,
-      sentinelCreds: (0, import_node_fs2.readFileSync)(userVars.sentinel, "utf8"),
+      sentinelCreds: (0, import_node_fs3.readFileSync)(userVars.sentinel, "utf8"),
       bearerCmd
     };
   }
@@ -64336,7 +64371,7 @@ function configFromEnv(env = process.env) {
     space: env.COTAL_SPACE?.trim() || link?.space || "demo",
     id: env.COTAL_ID?.trim() || void 0,
     lifecycleUid,
-    creds: credsPath ? (0, import_node_fs2.readFileSync)(credsPath, "utf8") : void 0,
+    creds: credsPath ? (0, import_node_fs3.readFileSync)(credsPath, "utf8") : void 0,
     userAuth,
     name,
     role: env.COTAL_ROLE?.trim() || def?.role || void 0,
@@ -64726,13 +64761,13 @@ var MeshAgent = class extends import_node_events2.EventEmitter {
    *  holding it has reported — a release from one must not speak for another still in flight. */
   releaseInFlight(ids) {
     for (const id of ids) {
-      const held = this.inFlightIds.get(id);
-      if (held === void 0)
+      const held2 = this.inFlightIds.get(id);
+      if (held2 === void 0)
         continue;
-      if (held <= 1)
+      if (held2 <= 1)
         this.inFlightIds.delete(id);
       else
-        this.inFlightIds.set(id, held - 1);
+        this.inFlightIds.set(id, held2 - 1);
     }
   }
   /** Return scoped pending messages and ack them — call only when they're actually surfaced. */
@@ -65221,18 +65256,1821 @@ ${lines.join("\n")}`;
 };
 
 // ../connector-core/dist/launch.js
-function transcriptChannel(name) {
-  return `tr-${name.toLowerCase().replace(/[^a-z0-9_-]+/g, "-")}`;
+function eventChannelForSession(ep) {
+  if (ep.actorIsEphemeral)
+    throw new Error("events are not available for a session with a self-minted identity: this endpoint has no declared id and no credentials, so its actor is a fresh random token per process and its event channel could never match a grant. Launch it with an identity (an authed mesh, or an explicit id) to publish events.");
+  return eventChannel(ep.principal);
 }
 
 // ../connector-core/dist/agui.js
+var import_node_crypto8 = require("node:crypto");
+var import_node_path2 = require("node:path");
+var COTAL_CUSTOM_EVENTS = [];
+var AGUI_PROTOCOL = "ag-ui/0.0.57";
+var AguiVocabularyError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "AguiVocabularyError";
+  }
+};
+var AguiBrackets = class _AguiBrackets {
+  run;
+  text = /* @__PURE__ */ new Set();
+  reasoning = /* @__PURE__ */ new Set();
+  tools = /* @__PURE__ */ new Set();
+  /**
+   * The machine's whole state, as plain JSON — what the WAL persists so a restart does not lose it.
+   *
+   * Sorted, because this value is written to disk and compared BY A HUMAN reading two documents.
+   * A `Set`'s iteration order is insertion order, so two machines that are semantically identical
+   * would serialize differently depending on the order events happened to arrive, and a diff of two
+   * WALs would show a change where there is none.
+   */
+  snapshot() {
+    return {
+      run: this.run,
+      text: [...this.text].sort(),
+      reasoning: [...this.reasoning].sort(),
+      tools: [...this.tools].sort()
+    };
+  }
+  /** Rebuild a machine from a snapshot. The inverse of {@link snapshot}, and the reason a mid-run
+   *  restart can continue instead of refusing its first event. */
+  static restore(s) {
+    const b = new _AguiBrackets();
+    b.run = s.run;
+    for (const id of s.text)
+      b.text.add(id);
+    for (const id of s.reasoning)
+      b.reasoning.add(id);
+    for (const id of s.tools)
+      b.tools.add(id);
+    return b;
+  }
+  /** An independent machine at the same state — used to VALIDATE a batch without advancing the
+   *  machine that is in step with the disk. */
+  clone() {
+    return _AguiBrackets.restore(this.snapshot());
+  }
+  /** True while a run is open — i.e. the stream is mid-turn and not at a legal stopping point. */
+  get open() {
+    return this.run !== void 0;
+  }
+  /** The run currently open, for diagnostics and for checking a frame's envelope against it. */
+  get runId() {
+    return this.run;
+  }
+  /** Feed one event. Throws {@link AguiVocabularyError} on the first violation. */
+  accept(event) {
+    const e = event;
+    const t = e.type;
+    if (t === AGUI_EVENT_TYPE.RUN_STARTED) {
+      if (this.run !== void 0)
+        throw new AguiVocabularyError(`RUN_STARTED for "${String(e.runId)}" while run "${this.run}" is still open`);
+      this.run = String(e.runId);
+      return;
+    }
+    if (this.run === void 0)
+      throw new AguiVocabularyError(`${t} emitted outside an open run`);
+    if (t === AGUI_EVENT_TYPE.RUN_FINISHED || t === AGUI_EVENT_TYPE.RUN_ERROR) {
+      if (t === AGUI_EVENT_TYPE.RUN_FINISHED && String(e.runId) !== this.run)
+        throw new AguiVocabularyError(`RUN_FINISHED for "${String(e.runId)}" but the open run is "${this.run}"`);
+      const dangling = [...this.text, ...this.reasoning, ...this.tools];
+      if (dangling.length > 0)
+        throw new AguiVocabularyError(`${t} while still open: ${dangling.join(", ")}`);
+      this.run = void 0;
+      return;
+    }
+    switch (t) {
+      case AGUI_EVENT_TYPE.TEXT_MESSAGE_START:
+        return this.openId(this.text, String(e.messageId), t);
+      case AGUI_EVENT_TYPE.TEXT_MESSAGE_CONTENT:
+        return this.requireOpen(this.text, String(e.messageId), t);
+      case AGUI_EVENT_TYPE.TEXT_MESSAGE_END:
+        return this.closeId(this.text, String(e.messageId), t);
+      case AGUI_EVENT_TYPE.REASONING_MESSAGE_START:
+        return this.openId(this.reasoning, String(e.messageId), t);
+      case AGUI_EVENT_TYPE.REASONING_MESSAGE_CONTENT:
+        return this.requireOpen(this.reasoning, String(e.messageId), t);
+      case AGUI_EVENT_TYPE.REASONING_MESSAGE_END:
+        return this.closeId(this.reasoning, String(e.messageId), t);
+      case AGUI_EVENT_TYPE.TOOL_CALL_START:
+        return this.openId(this.tools, String(e.toolCallId), t);
+      case AGUI_EVENT_TYPE.TOOL_CALL_ARGS:
+        return this.requireOpen(this.tools, String(e.toolCallId), t);
+      case AGUI_EVENT_TYPE.TOOL_CALL_END:
+        return this.closeId(this.tools, String(e.toolCallId), t);
+      case AGUI_EVENT_TYPE.TOOL_CALL_RESULT:
+        if (this.tools.has(String(e.toolCallId)))
+          throw new AguiVocabularyError(`TOOL_CALL_RESULT for "${String(e.toolCallId)}" while its call is still open`);
+        return;
+      case AGUI_EVENT_TYPE.CUSTOM:
+        if (!COTAL_CUSTOM_EVENTS.includes(String(e.name)))
+          throw new AguiVocabularyError(`CUSTOM "${String(e.name)}" is not declared in COTAL_CUSTOM_EVENTS (the v1 table is empty by specification)`);
+        return;
+      default:
+        throw new AguiVocabularyError(`${t} is not in the mapped subset this plane emits`);
+    }
+  }
+  /**
+   * Assert the stream is at a legal stopping point.
+   *
+   * Called at the end of a synthesized sequence and by any consumer checking a writer closed
+   * cleanly. NOT called per frame: mid-turn frames are legally unbalanced.
+   */
+  assertClosed() {
+    if (this.run !== void 0)
+      throw new AguiVocabularyError(`run "${this.run}" was never closed`);
+  }
+  openId(set3, id, t) {
+    if (set3.has(id))
+      throw new AguiVocabularyError(`${t} re-opened "${id}" while already open`);
+    set3.add(id);
+  }
+  requireOpen(set3, id, t) {
+    if (!set3.has(id))
+      throw new AguiVocabularyError(`${t} for "${id}" which is not open`);
+  }
+  closeId(set3, id, t) {
+    if (!set3.delete(id))
+      throw new AguiVocabularyError(`${t} for "${id}" which is not open`);
+  }
+};
+function aguiFrame(opts) {
+  for (const [field, value] of [
+    ["threadId", opts.threadId],
+    ["runId", opts.runId],
+    ["epoch", opts.epoch]
+  ])
+    if (typeof value !== "string" || value.length === 0)
+      throw new AguiVocabularyError(`frame ${field} must be a non-empty string`);
+  if (!Number.isSafeInteger(opts.seq) || opts.seq < 0)
+    throw new AguiVocabularyError(`frame seq must be a non-negative safe integer, got ${JSON.stringify(opts.seq)}`);
+  if (!Array.isArray(opts.events) || opts.events.length === 0)
+    throw new AguiVocabularyError("a frame must carry at least one event");
+  return {
+    kind: AGUI_FRAME_KIND,
+    protocol: AGUI_PROTOCOL,
+    threadId: opts.threadId,
+    runId: opts.runId,
+    epoch: opts.epoch,
+    seq: opts.seq,
+    events: opts.events
+  };
+}
+function runStarted(o) {
+  return {
+    type: AGUI_EVENT_TYPE.RUN_STARTED,
+    threadId: o.threadId,
+    runId: o.runId,
+    timestamp: o.timestamp,
+    ...o.cotal ? { cotal: o.cotal } : {}
+  };
+}
+function assertInterrupts(list) {
+  if (!Array.isArray(list) || list.length === 0)
+    throw new AguiVocabularyError("outcome.interrupts must be a non-empty array when the outcome is an interrupt");
+  for (const [i, entry] of list.entries()) {
+    const e = entry;
+    if (typeof e !== "object" || e === null)
+      throw new AguiVocabularyError(`outcome.interrupts[${i}] is not an object`);
+    if (typeof e.id !== "string")
+      throw new AguiVocabularyError(`outcome.interrupts[${i}].id must be a string`);
+    if (typeof e.reason !== "string")
+      throw new AguiVocabularyError(`outcome.interrupts[${i}].reason must be a string`);
+  }
+}
+function runFinished(o) {
+  if (o.outcome?.type === "interrupt")
+    assertInterrupts(o.outcome.interrupts);
+  return {
+    type: AGUI_EVENT_TYPE.RUN_FINISHED,
+    threadId: o.threadId,
+    runId: o.runId,
+    timestamp: o.timestamp,
+    ...o.outcome ? { outcome: o.outcome } : {},
+    ...o.cotal ? { cotal: o.cotal } : {}
+  };
+}
+function textMessageStart(o) {
+  return {
+    type: AGUI_EVENT_TYPE.TEXT_MESSAGE_START,
+    messageId: o.messageId,
+    timestamp: o.timestamp,
+    ...o.role ? { role: o.role } : {},
+    ...o.cotal ? { cotal: o.cotal } : {}
+  };
+}
+function textMessageContent(o) {
+  return {
+    type: AGUI_EVENT_TYPE.TEXT_MESSAGE_CONTENT,
+    messageId: o.messageId,
+    delta: o.delta,
+    timestamp: o.timestamp,
+    ...o.cotal ? { cotal: o.cotal } : {}
+  };
+}
+function textMessageEnd(o) {
+  return {
+    type: AGUI_EVENT_TYPE.TEXT_MESSAGE_END,
+    messageId: o.messageId,
+    timestamp: o.timestamp,
+    ...o.cotal ? { cotal: o.cotal } : {}
+  };
+}
+function toolCallStart(o) {
+  return {
+    type: AGUI_EVENT_TYPE.TOOL_CALL_START,
+    toolCallId: o.toolCallId,
+    toolCallName: o.toolCallName,
+    timestamp: o.timestamp,
+    ...o.parentMessageId ? { parentMessageId: o.parentMessageId } : {},
+    ...o.cotal ? { cotal: o.cotal } : {}
+  };
+}
+function toolCallArgs(o) {
+  return {
+    type: AGUI_EVENT_TYPE.TOOL_CALL_ARGS,
+    toolCallId: o.toolCallId,
+    delta: o.delta,
+    timestamp: o.timestamp,
+    ...o.cotal ? { cotal: o.cotal } : {}
+  };
+}
+function toolCallEnd(o) {
+  return {
+    type: AGUI_EVENT_TYPE.TOOL_CALL_END,
+    toolCallId: o.toolCallId,
+    timestamp: o.timestamp,
+    ...o.cotal ? { cotal: o.cotal } : {}
+  };
+}
+function toolCallResult(o) {
+  return {
+    type: AGUI_EVENT_TYPE.TOOL_CALL_RESULT,
+    messageId: o.messageId,
+    toolCallId: o.toolCallId,
+    content: o.content,
+    timestamp: o.timestamp,
+    ...o.cotal ? { cotal: o.cotal } : {}
+  };
+}
+function reasoningMessageStart(o) {
+  return {
+    type: AGUI_EVENT_TYPE.REASONING_MESSAGE_START,
+    messageId: o.messageId,
+    role: "reasoning",
+    timestamp: o.timestamp,
+    ...o.cotal ? { cotal: o.cotal } : {}
+  };
+}
+function reasoningMessageContent(o) {
+  return {
+    type: AGUI_EVENT_TYPE.REASONING_MESSAGE_CONTENT,
+    messageId: o.messageId,
+    delta: o.delta,
+    timestamp: o.timestamp,
+    ...o.cotal ? { cotal: o.cotal } : {}
+  };
+}
+function reasoningMessageEnd(o) {
+  return {
+    type: AGUI_EVENT_TYPE.REASONING_MESSAGE_END,
+    messageId: o.messageId,
+    timestamp: o.timestamp,
+    ...o.cotal ? { cotal: o.cotal } : {}
+  };
+}
 var TRUNCATABLE_FIELDS = [
   { type: AGUI_EVENT_TYPE.TOOL_CALL_ARGS, field: "delta" },
   { type: AGUI_EVENT_TYPE.TOOL_CALL_RESULT, field: "content" },
   { type: AGUI_EVENT_TYPE.TEXT_MESSAGE_CONTENT, field: "delta" }
 ];
+var AguiBracketStateLost = class extends AguiVocabularyError {
+  cause;
+  constructor(message, cause) {
+    super(message);
+    this.cause = cause;
+    this.name = "AguiBracketStateLost";
+  }
+};
+var AguiEmitterHalted = class extends Error {
+  reason;
+  constructor(reason, message) {
+    super(message);
+    this.reason = reason;
+    this.name = "AguiEmitterHalted";
+  }
+};
 var SIZING_ID = "S".repeat(64);
 var SIZING_EXPECTATION = Number.MAX_SAFE_INTEGER;
+function packUnits(opts) {
+  const { threadId, epoch, measure, limit } = opts;
+  if (!Number.isSafeInteger(limit) || limit <= 0)
+    throw new AguiVocabularyError(`pack limit must be a positive safe integer, got ${JSON.stringify(limit)}`);
+  const out = [];
+  let seq = opts.firstSeq;
+  let batch = [];
+  let batchRun;
+  let batchCursor;
+  const flush = () => {
+    if (batch.length === 0)
+      return;
+    out.push({ frame: aguiFrame({ threadId, runId: batchRun, epoch, seq, events: batch }), cursor: batchCursor });
+    seq += 1;
+    batch = [];
+    batchRun = void 0;
+    batchCursor = void 0;
+  };
+  for (const unit of opts.units) {
+    if (unit.events.length === 0)
+      throw new AguiVocabularyError("packUnits was handed an empty unit; a record that maps to nothing advances the cursor and never becomes a frame");
+    if (batchRun !== void 0 && unit.runId !== batchRun)
+      flush();
+    const candidate2 = [...batch, ...unit.events];
+    const fits = measure(aguiFrame({ threadId, runId: batchRun ?? unit.runId, epoch, seq, events: candidate2 })) <= limit;
+    if (fits) {
+      batch = candidate2;
+      batchRun = batchRun ?? unit.runId;
+      batchCursor = unit.cursor;
+      continue;
+    }
+    flush();
+    const alone = aguiFrame({ threadId, runId: unit.runId, epoch, seq, events: unit.events });
+    const aloneBytes = measure(alone);
+    if (aloneBytes > limit)
+      throw new AguiVocabularyError(`a single source observation does not fit in one frame (${aloneBytes} > ${limit} bytes, ${unit.events.length} event(s), run ${unit.runId}). One source observation is one frame, and that rule requires this to fail loud rather than be truncated at a frame boundary: a frame that ends mid-record has no cursor it can honestly store, and a dropped boundary with no gap marker is worse than a halt.`);
+    batch = [...unit.events];
+    batchRun = unit.runId;
+    batchCursor = unit.cursor;
+  }
+  flush();
+  return out;
+}
+var AguiEmitter = class _AguiEmitter {
+  ep;
+  wal;
+  source;
+  map;
+  channel;
+  threadId;
+  /**
+   * The bracket machine AT THE FOLDED POSITION — deliberately not "wherever validation got to".
+   *
+   * It advances one frame at a time, immediately before that frame's `beginSend`, so the state
+   * frozen with a pending frame is the state that belongs to it. A machine advanced by the whole
+   * batch up front would freeze a state describing events that had not been sent.
+   */
+  brackets;
+  halted;
+  /** True once THIS process has fed an event through the bracket machine. It is the half of the
+   *  restart diagnosis that keeps a genuine mid-stream violation from being blamed on a restart. */
+  fedAnyEvent = false;
+  constructor(ep, wal, source, map2, channel, threadId) {
+    this.ep = ep;
+    this.wal = wal;
+    this.source = source;
+    this.map = map2;
+    this.channel = channel;
+    this.threadId = threadId;
+    this.brackets = wal.brackets ? AguiBrackets.restore(wal.brackets) : new AguiBrackets();
+  }
+  /**
+   * Start an emitter: resolve the channel, run the single-replica preflight, and settle any pending
+   * frame.
+   *
+   * **THIS IS THAT PREFLIGHT'S PRODUCTION CALL SITE, AND UNTIL THIS FUNCTION EXISTED THERE WAS
+   * NONE.** `CotalEndpoint.assertExpectationSemantics()` had zero production callers: it was a
+   * check that shipped, was covered by its own suite, and never ran outside one. That is why it is
+   * called HERE, before recovery and therefore before any publish — a serialized append on an
+   * unverified stream is the exact case it exists to prevent, and doing it after recovery would
+   * leave the one publish that matters most, the re-publish of a frozen frame, outside the guard.
+   */
+  static async start(opts) {
+    const { endpoint, wal } = opts;
+    const channel = eventChannelForSession(endpoint);
+    const live = principalKey(endpoint.principal.owner, endpoint.principal.actor).key;
+    if (wal.principal !== live)
+      throw new Error(`event WAL belongs to principal ${wal.principal}, but this endpoint is ${live} \u2014 refusing to publish under one identity from another's write-ahead log`);
+    await endpoint.assertExpectationSemantics();
+    if (!opts.subjectFrontier || typeof opts.subjectFrontier.advance !== "function")
+      throw new Error(`event emitter for ${channel}: a subject frontier is required \u2014 the subject is shared by every thread of this principal, so the publish expectation cannot come from one thread's log`);
+    await wal.bindSubjectFrontier(opts.subjectFrontier);
+    const em = new _AguiEmitter(endpoint, wal, opts.source, opts.map, channel, wal.threadId);
+    await em.recover();
+    return em;
+  }
+  /** True once the emitter has stopped for good. */
+  get stopped() {
+    return this.halted !== void 0;
+  }
+  /**
+   * Boot recovery, branching on the WAL's tag.
+   *
+   * `acked` NEVER republishes: the frame landed and we know it, so the only remaining work is to
+   * fold. `sent_unacked` is the genuinely uncertain case and republishes with the SAME frozen `id`
+   * and `E` — never the current tip, because re-deriving either is what turns an uncertain publish
+   * into a second, different message.
+   */
+  async recover() {
+    const p = this.wal.pending;
+    if (!p)
+      return;
+    if (p.state === "acked") {
+      await this.wal.fold();
+      return;
+    }
+    await this.attempt({ id: p.id, E: p.E, body: p.body, retry: true });
+  }
+  /**
+   * Read forward, map, pack, and publish. Returns what it did, so a caller can distinguish "nothing
+   * to do" from "did work" without inspecting the WAL.
+   */
+  async pump() {
+    if (this.halted)
+      throw this.halted;
+    if (this.wal.pending)
+      throw new Error(`event emitter for ${this.channel}: a frame is still pending; recovery must settle it before a new read`);
+    const read = await this.source.read(this.wal.frontier.sourceCursor);
+    const units = [];
+    for (const rec of read.records) {
+      const mapped = this.map(rec.value);
+      if (mapped === null || mapped.events.length === 0) {
+        const last = units[units.length - 1];
+        if (last)
+          last.cursor = rec.cursor;
+        continue;
+      }
+      units.push({ runId: mapped.runId, events: mapped.events, cursor: rec.cursor });
+    }
+    if (units.length === 0) {
+      if (read.cursor !== this.wal.frontier.sourceCursor)
+        await this.wal.advanceCursorOnly(read.cursor);
+      return { frames: 0, events: 0 };
+    }
+    const probe = this.brackets.clone();
+    for (const u of units)
+      for (const e of u.events) {
+        try {
+          probe.accept(e);
+        } catch (err2) {
+          throw this.diagnoseBracket(err2);
+        }
+      }
+    this.fedAnyEvent = true;
+    const frames = packUnits({
+      threadId: this.threadId,
+      epoch: this.wal.epoch,
+      firstSeq: this.wal.frontier.seq + 1,
+      units,
+      measure: (f) => this.measure(f),
+      limit: this.ep.maxPayload
+    });
+    let events2 = 0;
+    for (const { frame, cursor } of frames) {
+      await this.publish(frame, cursor);
+      events2 += frame.events.length;
+    }
+    if (read.cursor !== this.wal.frontier.sourceCursor)
+      await this.wal.advanceCursorOnly(read.cursor);
+    return { frames: frames.length, events: events2 };
+  }
+  /**
+   * Close the run this stream currently has open, at a boundary the RECORD STREAM CANNOT SEE.
+   *
+   * **This exists because the two halves of the mapping were specified against different inputs.**
+   * The plan sources `RUN_FINISHED` from a harness lifecycle hook, and the durable plane reads a
+   * FILE: a hook fires in another process and writes no record, so a hook-sourced terminal has no
+   * vehicle into a record-sourced stream. Deriving the terminal from records instead is possible but
+   * lies about time in two ways that matter to a live view: the finish lands only when the NEXT turn
+   * starts, so a finished agent renders as still running, and the last run of a session never closes
+   * at all, because there is no later record to close it on. This is that vehicle.
+   *
+   * It is a FRAME LIKE ANY OTHER: same epoch, same `seq` line, same write-ahead discipline, same
+   * halt rules. The single thing that differs is the cursor, which is republished UNCHANGED, because
+   * this frame consumes no source record. A frame that advanced the cursor here would mark records
+   * consumed that were never mapped.
+   *
+   * Idempotent by construction rather than by a flag: the bracket machine is the only state it
+   * reads, so once the run is closed there is nothing open to close and it answers `null`. That also
+   * makes it safe on a stream whose run was opened by a PREVIOUS process, since the machine is
+   * restored from the WAL.
+   *
+   * @returns the run that was closed, or `null` when the stream was already at a stopping point.
+   */
+  async closeRun(o) {
+    if (this.halted)
+      throw this.halted;
+    if (this.wal.pending)
+      throw new Error(`event emitter for ${this.channel}: a frame is still pending; recovery must settle it before a run can be closed`);
+    const runId = this.brackets.runId;
+    if (runId === void 0)
+      return null;
+    const cursor = this.wal.frontier.sourceCursor;
+    if (cursor === void 0)
+      throw new Error(`event emitter for ${this.channel}: run "${runId}" is open on a frontier that carries no source cursor. A run can only be open because a frame published it, and a frame that published cannot leave the cursor unset, so this WAL disagrees with itself. Refusing to invent a cursor for the closing frame.`);
+    const event = runFinished({
+      threadId: this.threadId,
+      runId,
+      timestamp: o.timestamp,
+      ...o.cotal ? { cotal: o.cotal } : {}
+    });
+    const probe = this.brackets.clone();
+    try {
+      probe.accept(event);
+    } catch (err2) {
+      throw this.diagnoseBracket(err2);
+    }
+    this.fedAnyEvent = true;
+    const frames = packUnits({
+      threadId: this.threadId,
+      epoch: this.wal.epoch,
+      firstSeq: this.wal.frontier.seq + 1,
+      units: [{ runId, events: [event], cursor }],
+      measure: (f) => this.measure(f),
+      limit: this.ep.maxPayload
+    });
+    for (const { frame, cursor: c } of frames)
+      await this.publish(frame, c);
+    return runId;
+  }
+  /** Measure a candidate frame EXACTLY as the wire will, at an upper bound over id and expectation. */
+  measure(frame) {
+    return this.ep.encodedSize({
+      channel: this.channel,
+      parts: [frame],
+      id: SIZING_ID,
+      expectedLastSubjectSeq: SIZING_EXPECTATION
+    });
+  }
+  /** Transition 1 then the first network attempt. */
+  async publish(frame, cursor) {
+    for (const e of frame.events)
+      this.brackets.accept(e);
+    const brackets = this.brackets.snapshot();
+    const id = (0, import_node_crypto8.randomUUID)();
+    const E = this.wal.expectedTip;
+    const body = [frame];
+    await this.wal.beginSend({ id, E, seq: frame.seq, sourceCursor: cursor, body, brackets });
+    await this.attempt({ id, E, body, retry: false });
+  }
+  /**
+   * One publish attempt — first or retry — with the FROZEN id and the FROZEN `E`. Never the tip.
+   *
+   * The three outcomes are not symmetric and the asymmetry is the design:
+   * - `!duplicate` → transition 2 then 3. Success becomes durable before the frontier moves.
+   * - `duplicate` → HALT. On a first attempt it means a body WE DID NOT WRITE holds our id, and
+   *   folding its `ackSeq` would advance the frontier and the source cursor past events that were
+   *   never published. On a retry it cannot happen on a single-replica stream at all, because such a
+   *   stream evaluates the expectation before the dedup cache, so observing it proves the stream is
+   *   not single-replica. Both are
+   *   fail-loud, and neither is a case where guessing is better than stopping.
+   * - CAS loss → HALT. Someone else moved the tip on a subject only this principal may write, or
+   *   the subject was purged. Uncertainty plus a moved tip is exactly what must not be guessed at.
+   *
+   * A NETWORK error is deliberately none of these: it leaves `pending` as `sent_unacked`, which is
+   * the state that means "we do not know", and the next boot retries the same frozen frame.
+   */
+  async attempt(o) {
+    let ack;
+    try {
+      ({ ack } = await this.ep.multicastExpecting({
+        channel: this.channel,
+        parts: o.body,
+        id: o.id,
+        expectedLastSubjectSeq: o.E
+      }));
+    } catch (e) {
+      if (isCasLoss(e))
+        throw this.halt("cas-loss", `event emitter for ${this.channel}: the subject tip is no longer ${o.E} (${e.message}). The broker ACL confines this subject to one principal, so the tip moved for one of: a CONCURRENT emitter under this same principal. The per-principal lock refuses a second one, but the lock FILE lives under a workspace root, so an emitter started against a DIFFERENT root, or by a path that never takes the lock, meets no lock at all. Another host and a stale pid do not get past it; they refuse the start instead, loudly; a subject frontier record that disagrees with the stream, which is what an interrupted upgrade or a restored backup leaves behind; a RESTORED stream; or a FILTERED PURGE, which returns the tip to 0 for every thread on the channel. One more cause is not a second writer at all: this log's OWN last ack. The shared record advances before the log records the ack, so a crash between those two writes leaves the record ahead of the frozen expectation this frame carries, and the retry publishes a sequence the subject has already passed. On disk it reads as a pending frame in state sent_unacked whose E is BEHIND the record's tip, which a restored record can also look like, so it narrows the search rather than ending it. None of these is resolvable by re-reading the tip, which agent credentials cannot read in any case. Clearing it is an explicit abandonment of epoch, seq, E, cursor and the shared subject record together, and it is VALID ONLY ONCE THE SUBJECT IS ACTUALLY EMPTY, which of the causes above is true of the FILTERED PURGE alone. On any other cause the tip is still where it is, so removing this state does not clear the halt: the next session opens virgin, expects 0, halts on the same tip, and the sibling logs a tip could have been rebuilt from are gone. Purge the channel first, or find the second writer, or match the signature above and stop looking for one. Once the subject really is back to 0, no command performs the abandonment, so by hand it means removing ${(0, import_node_path2.dirname)((0, import_node_path2.dirname)(this.wal.path))} whole, and removing less than that leaves a mixed state the next start refuses.`);
+      throw e;
+    }
+    if (ack.duplicate)
+      throw this.halt("duplicate-ack", `event emitter for ${this.channel}: the broker answered ${o.retry ? "a RETRY" : "a FIRST attempt"} for id ${o.id} with duplicate:true. ` + (o.retry ? `Under the SINGLE-REPLICA RETRY RULE this cannot happen on an R1 stream, which evaluates the subject expectation before the dedup cache \u2014 so either the stream is not R1 or a foreign body holds our stream-wide id. ` : `We have never published this id, so a body we did not write holds it. `) + `Folding this ack would advance the frontier and the source cursor past events that were never published: silent loss of real events. The frontier and cursor are unchanged.`);
+    await this.wal.recordAck(ack.seq);
+    await this.wal.fold();
+  }
+  /**
+   * Decide whether a bracket refusal is the WRITER's fault or OURS, and say which.
+   *
+   * Ours iff ALL THREE hold, and each is load-bearing:
+   * - this process has fed NO event through the machine yet, so the machine cannot have been put
+   *   into a bad state by anything we did in this run; and
+   * - the frontier is non-virgin, so frames — and therefore possibly an open `RUN_STARTED` — were
+   *   published by a PREVIOUS process; and
+   * - the WAL cannot say what was open. Since v2 the machine is PERSISTED, so an ordinary restart
+   *   restores it and never reaches here at all; `null` means the document was migrated from v1 and
+   *   genuinely never recorded the state. Without this condition the diagnosis would survive as a
+   *   permanent excuse for a case the migration fixed.
+   *
+   * Drop the first condition and a genuine mid-stream violation by the writer gets blamed on a
+   * restart that happened an hour ago. Drop the second and a violation on a virgin thread, where
+   * nothing was ever published and nothing could have been lost, gets blamed on a restart that never
+   * happened. Each condition alone produces a confident, wrong diagnosis — which is worse than the
+   * undiagnosed error it replaced, because a named cause stops the search.
+   */
+  diagnoseBracket(err2) {
+    if (this.fedAnyEvent || this.wal.frontier.seq === 0 || this.wal.brackets !== null)
+      return err2;
+    return new AguiBracketStateLost(`event emitter for ${this.channel}: bracket state was LOST ACROSS A RESTART \u2014 this is not a protocol violation by the writer. This process has emitted nothing yet, but the WAL says frame ${this.wal.frontier.seq} already went out, and the document records NO bracket state (it was migrated from v1, which never stored one), so any run or message the previous process left open is invisible to this one. Resuming from the source cursor therefore lands mid-run and the first event is refused. A WAL written by this build persists the machine and does not reach this path. The underlying refusal was: ${err2.message}`, err2);
+  }
+  halt(reason, message) {
+    this.halted = new AguiEmitterHalted(reason, message);
+    return this.halted;
+  }
+};
+
+// ../connector-core/dist/durable-source.js
+var import_node_crypto9 = require("node:crypto");
+var import_node_fs4 = require("node:fs");
+var import_promises = require("node:fs/promises");
+var JsonlFileSource = class _JsonlFileSource {
+  path;
+  kind = "jsonl-file";
+  constructor(path) {
+    this.path = path;
+  }
+  /**
+   * A cursor is `<dev>:<ino>:<offset>` — canonical, and BOUND TO THE FILE'S IDENTITY.
+   *
+   * The offset alone is not enough: a source replaced by an unrelated file of the same size or
+   * larger reads as an ordinary append, and the reader resumes at a byte offset inside a document
+   * it has never seen. Carrying `dev`/`ino` makes replacement DETECTABLE, which is the only thing
+   * that lets it fail loud instead of returning fabricated records.
+   *
+   * Parsed strictly: `Number()` coerces `" "` to 0 — replaying all history — and accepts `"1e0"`,
+   * `"01"`, `"+1"`. A cursor is persisted state handed back to us later, so a non-canonical one
+   * means something upstream is wrong, not something to guess at.
+   */
+  static parseCursor(cursor) {
+    const m = /^(\d+):(\d+):(0|[1-9]\d*):([0-9a-f]{16})$/.exec(cursor);
+    if (!m)
+      throw new Error(`JsonlFileSource: malformed cursor ${JSON.stringify(cursor)} (want <dev>:<ino>:<offset>:<seal>)`);
+    const offset = Number(m[3]);
+    if (!Number.isSafeInteger(offset))
+      throw new Error(`JsonlFileSource: cursor offset out of range in ${JSON.stringify(cursor)}`);
+    return { dev: m[1], ino: m[2], offset, seal: m[4] };
+  }
+  /**
+   * A seal over **the last 512 bytes before the cursor** — a BOUNDED form of the invariant a
+   * resumable offset wants: *the bytes immediately before my cursor are still the bytes that were
+   * there when I stopped.*
+   *
+   * **THE BOUND IS PART OF THE GUARANTEE AND IS STATED HERE BECAUSE IT IS NOT THE WHOLE PREFIX.**
+   * A rewrite confined to bytes EARLIER than `offset - 512` that preserves the sealed window, the
+   * inode and the size is **not detected** — reproduced independently by three reviewers, including
+   * with an ordinary same-length in-place PII scrub of earlier transcript lines. That is a real
+   * limitation with known edges: a scrub via temp-file+rename changes the inode and IS caught; one
+   * that changes length trips the offset/identity path and IS caught; one touching the sealed window
+   * IS caught. Only same-inode, same-size, in-place, wholly-outside-the-window escapes.
+   *
+   * What that costs is bounded and worth naming precisely: the emit path stays correct, because the
+   * cursor never moves backwards and forward records are read from bytes the rewrite did not touch.
+   * What is lost is the ability to detect that already-consumed on-disk history drifted after we
+   * read it. If whole-prefix integrity is ever required, this span must cover it — or the cursor has
+   * to carry a rolling hash instead of a window.
+   *
+   * `dev`/`ino` catch unlink-and-recreate, but **not an in-place rewrite** (`writeFileSync` with no
+   * unlink keeps the inode), and that case resumes at a byte offset inside a different document and
+   * emits fragments of it as records (`fmae-rev-eng`, CONFIRMED). Size cannot catch it either when
+   * the replacement is larger.
+   *
+   * Note what this deliberately does NOT flag: a rewrite that reproduces the same preceding bytes.
+   * There the consumed prefix is genuinely unchanged, so resuming is correct — the seal states an
+   * invariant rather than guessing at intent.
+   */
+  static async sealAt(fh, offset) {
+    const span = Math.min(offset, 512);
+    const buf = Buffer.allocUnsafe(span);
+    if (span > 0)
+      await fh.read(buf, 0, span, offset - span);
+    return (0, import_node_crypto9.createHash)("sha256").update(buf.subarray(0, span)).digest("hex").slice(0, 16);
+  }
+  /** Offset just past the last COMPLETE line at or before `limit` — a safe boundary to resume at. */
+  static async lastCompleteBoundary(fh, limit) {
+    if (limit === 0)
+      return 0;
+    const window2 = 64 * 1024;
+    let searched = 0;
+    while (searched < limit) {
+      const len = Math.min(window2, limit - searched);
+      const at = limit - searched - len;
+      const buf = Buffer.allocUnsafe(len);
+      const { bytesRead } = await fh.read(buf, 0, len, at);
+      const idx = buf.subarray(0, bytesRead).lastIndexOf(10);
+      if (idx !== -1)
+        return at + idx + 1;
+      searched += len;
+    }
+    return 0;
+  }
+  async read(cursor) {
+    const fh = await (0, import_promises.open)(this.path, import_node_fs4.constants.O_RDONLY | (import_node_fs4.constants.O_NOFOLLOW ?? 0));
+    try {
+      const st = await fh.stat();
+      const size = st.size;
+      const dev = String(st.dev), ino = String(st.ino);
+      const here = async (offset) => `${dev}:${ino}:${offset}:${await _JsonlFileSource.sealAt(fh, offset)}`;
+      if (cursor === void 0)
+        return { records: [], cursor: await here(await _JsonlFileSource.lastCompleteBoundary(fh, size)) };
+      const from = _JsonlFileSource.parseCursor(cursor);
+      if (from.dev !== dev || from.ino !== ino)
+        throw new Error(`JsonlFileSource: ${this.path} is not the file this cursor came from (cursor ${from.dev}:${from.ino}, now ${dev}:${ino}) \u2014 it was replaced or rotated`);
+      if (from.offset > size)
+        throw new Error(`JsonlFileSource: cursor offset ${from.offset} is past end ${size} for ${this.path} \u2014 the file was truncated`);
+      const seal = await _JsonlFileSource.sealAt(fh, from.offset);
+      if (seal !== from.seal)
+        throw new Error(`JsonlFileSource: the bytes before offset ${from.offset} in ${this.path} have changed (seal ${from.seal} -> ${seal}) \u2014 the file was rewritten in place, not appended to`);
+      if (from.offset === size)
+        return { records: [], cursor: await here(from.offset) };
+      const len = size - from.offset;
+      const buf = Buffer.allocUnsafe(len);
+      const { bytesRead } = await fh.read(buf, 0, len, from.offset);
+      const chunk = buf.subarray(0, bytesRead);
+      const lastNl = chunk.lastIndexOf(10);
+      if (lastNl === -1)
+        return { records: [], cursor: await here(from.offset) };
+      let complete;
+      try {
+        complete = new TextDecoder("utf-8", { fatal: true }).decode(chunk.subarray(0, lastNl));
+      } catch (e) {
+        throw new Error(`JsonlFileSource: invalid UTF-8 at offset ~${from.offset} in ${this.path}: ${e.message}`);
+      }
+      const records = [];
+      let at = from.offset;
+      for (const line of complete.split("\n")) {
+        at += Buffer.byteLength(line, "utf8") + 1;
+        if (line.trim() === "")
+          continue;
+        let value;
+        try {
+          value = JSON.parse(line);
+        } catch (e) {
+          throw new Error(`JsonlFileSource: unparseable complete line at offset ~${from.offset} in ${this.path}: ${e.message}`);
+        }
+        records.push({ value, cursor: await here(at) });
+      }
+      const end = from.offset + lastNl + 1;
+      if (at !== end)
+        throw new Error(`JsonlFileSource: internal cursor walk ended at ${at} but the batch ends at ${end} in ${this.path}`);
+      return { records, cursor: await here(end) };
+    } finally {
+      await fh.close();
+    }
+  }
+};
+
+// ../connector-core/dist/event-wal.js
+var import_node_crypto10 = require("node:crypto");
+var import_node_fs5 = require("node:fs");
+var import_promises2 = require("node:fs/promises");
+var import_node_path3 = require("node:path");
+var EVENT_WAL_VERSION = 3;
+var WalCorruptError = class extends Error {
+  path;
+  invariant;
+  constructor(path, invariant, detail) {
+    super(`event WAL at ${path} is unusable (${invariant}): ${detail}`);
+    this.path = path;
+    this.invariant = invariant;
+    this.name = "WalCorruptError";
+  }
+};
+var WalStaleWriterError = class extends Error {
+  path;
+  expectedGen;
+  foundGen;
+  constructor(path, expectedGen, foundGen) {
+    super(`event WAL at ${path} was written by another handle since this one read it (this handle expects generation ${expectedGen}, the file is at ${foundGen === void 0 ? "no file at all" : `generation ${foundGen}`}) \u2014 refusing to overwrite it. A second emitter or a stale handle is writing this principal's log.`);
+    this.path = path;
+    this.expectedGen = expectedGen;
+    this.foundGen = foundGen;
+    this.name = "WalStaleWriterError";
+  }
+};
+var isSafeNonNegInt = (n) => Number.isSafeInteger(n) && n >= 0;
+function docGeneration(path, doc) {
+  if (typeof doc.v === "number" && doc.v < 3)
+    return 0;
+  if (!isSafeNonNegInt(doc.gen))
+    throw new WalCorruptError(path, "gen is a safe non-negative integer", `found gen=${String(doc.gen)} on a v${String(doc.v)} document`);
+  return doc.gen;
+}
+async function openExclusiveNoFollow(path) {
+  return (0, import_promises2.open)(path, import_node_fs5.constants.O_WRONLY | import_node_fs5.constants.O_CREAT | import_node_fs5.constants.O_EXCL | (import_node_fs5.constants.O_NOFOLLOW ?? 0), 384);
+}
+function assertPendingVintage(path, p, f) {
+  if (p.E !== f.lastSubjectSeq)
+    throw new WalCorruptError(path, "pending.E === frontier.lastSubjectSeq", `pending.E=${p.E} frontier.lastSubjectSeq=${f.lastSubjectSeq} \u2014 the frozen expectation is not the tip this WAL believes, so retrying it can only CAS-halt or append at the wrong position`);
+  if (p.seq !== f.seq + 1)
+    throw new WalCorruptError(path, "pending.seq === frontier.seq + 1", `pending.seq=${p.seq} frontier.seq=${f.seq} \u2014 a pending frame must be exactly the frontier's successor`);
+  if (p.state === "sent_unacked") {
+    if (p.ackSeq !== void 0)
+      throw new WalCorruptError(path, "sent_unacked has no ackSeq", `state is "sent_unacked" but ackSeq=${String(p.ackSeq)} \u2014 the document contradicts its own tag`);
+    return;
+  }
+  if (!isSafeNonNegInt(p.ackSeq))
+    throw new WalCorruptError(path, "acked.ackSeq present", `state is "acked" but ackSeq is ${String(p.ackSeq)}`);
+  if (!(p.ackSeq > f.lastSubjectSeq))
+    throw new WalCorruptError(path, "acked.ackSeq > frontier.lastSubjectSeq", `ackSeq=${p.ackSeq} frontier.lastSubjectSeq=${f.lastSubjectSeq} \u2014 the frontier is of a later vintage than the acked frame, so its sourceCursor may already have passed events that were never published; resuming would drop them with no gap for a consumer to see`);
+}
+function parseBrackets(path, field, v, nullable2) {
+  if (v === null && nullable2)
+    return null;
+  if (typeof v !== "object" || v === null)
+    throw new WalCorruptError(path, `${field} is an object${nullable2 ? " or null" : ""}`, JSON.stringify(v));
+  const b = v;
+  if (b.run !== void 0 && typeof b.run !== "string")
+    throw new WalCorruptError(path, `${field}.run is a string or absent`, JSON.stringify(b.run));
+  const lists = { text: b.text, reasoning: b.reasoning, tools: b.tools };
+  for (const [k, list] of Object.entries(lists)) {
+    if (!Array.isArray(list) || list.some((x) => typeof x !== "string"))
+      throw new WalCorruptError(path, `${field}.${k} is an array of strings`, JSON.stringify(list));
+  }
+  if (b.run === void 0 && b.text.concat(b.reasoning, b.tools).length > 0)
+    throw new WalCorruptError(path, `${field} has no open run while messages or tool calls are open`, JSON.stringify(b));
+  return { run: b.run, text: b.text, reasoning: b.reasoning, tools: b.tools };
+}
+function parseDoc(path, raw, space, threadId, principal) {
+  let d;
+  try {
+    d = JSON.parse(raw);
+  } catch (e) {
+    throw new WalCorruptError(path, "parseable JSON", e.message);
+  }
+  if (typeof d !== "object" || d === null)
+    throw new WalCorruptError(path, "document is an object", typeof d);
+  const doc = d;
+  if (typeof doc.v !== "number" || !Number.isSafeInteger(doc.v) || doc.v < 1)
+    throw new WalCorruptError(path, "v is a positive integer", `found v=${String(doc.v)}`);
+  if (doc.v > EVENT_WAL_VERSION)
+    throw new WalCorruptError(path, `v <= ${EVENT_WAL_VERSION}`, `this WAL is v${doc.v} and this build understands v${EVENT_WAL_VERSION} \u2014 THE STATE IS NEWER THAN THE CODE, which is what a code rollback across the v2 migration (persisted bracket state) or the v3 one (the write generation) leaves behind. The migration is forward-only by design: there is no downgrade, because a lossy one would silently discard state this file exists to preserve. Run the newer build, or move this WAL aside and accept that the thread restarts from a new epoch.`);
+  if (doc.space !== space)
+    throw new WalCorruptError(path, "space matches", `WAL space=${String(doc.space)} caller=${space}`);
+  if (doc.threadId !== threadId)
+    throw new WalCorruptError(path, "threadId matches", `WAL threadId=${String(doc.threadId)} caller=${threadId}`);
+  if (doc.principal !== principal)
+    throw new WalCorruptError(path, "principal matches", `WAL principal=${String(doc.principal)} caller=${principal}`);
+  if (typeof doc.epoch !== "string" || doc.epoch.length === 0)
+    throw new WalCorruptError(path, "epoch is a non-empty string", String(doc.epoch));
+  const f = doc.frontier;
+  if (!f || !isSafeNonNegInt(f.seq) || !isSafeNonNegInt(f.lastSubjectSeq))
+    throw new WalCorruptError(path, "frontier is well-formed", JSON.stringify(doc.frontier));
+  if (f.sourceCursor !== void 0 && typeof f.sourceCursor !== "string")
+    throw new WalCorruptError(path, "frontier.sourceCursor is a string or absent", typeof f.sourceCursor);
+  if (f.seq === 0 !== (f.lastSubjectSeq === 0))
+    throw new WalCorruptError(path, "frontier.seq and lastSubjectSeq are both zero or both nonzero", JSON.stringify(f));
+  if ((f.seq > 0 || f.lastSubjectSeq > 0) && typeof f.sourceCursor !== "string")
+    throw new WalCorruptError(path, "a nonzero frontier carries its sourceCursor", JSON.stringify(f));
+  if (doc.pending !== null && typeof doc.pending !== "object")
+    throw new WalCorruptError(path, "pending is present (null or an object)", doc.pending === void 0 ? "the key is absent, which is not the same as null" : typeof doc.pending);
+  let pending = null;
+  if (doc.pending !== null) {
+    const p = doc.pending;
+    if (p.state !== "sent_unacked" && p.state !== "acked")
+      throw new WalCorruptError(path, "pending.state is a known tag", String(p.state));
+    if (typeof p.id !== "string" || p.id.length === 0)
+      throw new WalCorruptError(path, "pending.id is a non-empty string", String(p.id));
+    try {
+      assertIdToken(p.id, "event WAL pending.id");
+    } catch (e) {
+      throw new WalCorruptError(path, "pending.id satisfies the wire id grammar", e.message);
+    }
+    if (!isSafeNonNegInt(p.E) || !isSafeNonNegInt(p.seq))
+      throw new WalCorruptError(path, "pending E/seq are safe non-negative integers", JSON.stringify(p));
+    if (typeof p.sourceCursor !== "string")
+      throw new WalCorruptError(path, "pending.sourceCursor is a string", typeof p.sourceCursor);
+    if (!Array.isArray(p.body) || p.body.length === 0)
+      throw new WalCorruptError(path, "pending.body is a non-empty array of parts", JSON.stringify(p.body));
+    if (doc.v === 1)
+      throw new WalCorruptError(path, "a v1 WAL has no frame in flight", `this v1 document holds a ${String(p.state)} frame, and v2 requires the bracket state that belongs to it \u2014 which v1 never recorded and nothing here can reconstruct. Let the older build settle this frame first, then start the newer one.`);
+    p.brackets = parseBrackets(path, "pending.brackets", p.brackets, false);
+    pending = p;
+    assertPendingVintage(path, pending, f);
+  }
+  const brackets = doc.v === 1 ? null : parseBrackets(path, "brackets", doc.brackets, true);
+  return {
+    v: EVENT_WAL_VERSION,
+    // MIGRATED IN MEMORY; it reaches disk on the next durable write.
+    // The generation as the FILE states it, so the first write from this handle compares against
+    // what it actually read rather than against its own migrated shape.
+    gen: docGeneration(path, doc),
+    space,
+    epoch: doc.epoch,
+    threadId,
+    principal,
+    frontier: f,
+    pending,
+    brackets
+  };
+}
+var EventWal = class _EventWal {
+  path;
+  doc;
+  /**
+   * Every mutation runs one-at-a-time on this chain.
+   *
+   * Without it, two concurrent `beginSend` calls both read `this.doc.pending === null` before either
+   * durable replace finishes — the guard is an in-memory read that is NOT atomic with the write
+   * across its `await` points. Reviewers reproduced the split: one call fulfils, one rejects, and
+   * the process is left holding `pending.id === "A"` in memory while the disk says `"B"`. Recovery
+   * would then resume the frame on disk while the live emitter retries the other, which breaks the
+   * one thing this file exists to guarantee — that `id` and `E` are frozen and agreed.
+   *
+   * A per-instance chain is sufficient and honest about its scope, and the scope is narrower than it
+   * once claimed: it serializes THIS INSTANCE's callers. It does nothing about a SECOND `EventWal`
+   * on the same file, in this process or another — the chain is per object, so two objects are two
+   * chains and both of them "succeed". That gap was described here as "solved upstream by the
+   * principal-level lock" while no lock was ever acquired. Two things close it now, and neither is
+   * this chain: `acquirePrincipalLock` refuses a second emitter for the principal at start, and
+   * {@link EventWal.assertNotClobbering} refuses a stale handle's write even when it got past that.
+   */
+  chain = Promise.resolve();
+  /** Run `op` after every previously-queued mutation, whether they resolved or threw. */
+  serialize(op) {
+    const next = this.chain.then(op, op);
+    this.chain = next.catch(() => void 0);
+    return next;
+  }
+  constructor(path, doc) {
+    this.path = path;
+    this.doc = doc;
+  }
+  get epoch() {
+    return this.doc.epoch;
+  }
+  /** The principal this WAL was loaded FOR — exposed so a consumer can prove it is holding its own.
+   *  `open()` already refuses a document whose stored principal disagrees, but that check protects
+   *  the FILE, not the caller: an emitter handed the wrong WAL object entirely would sail past it. */
+  get principal() {
+    return this.doc.principal;
+  }
+  get threadId() {
+    return this.doc.threadId;
+  }
+  /** The bracket machine at the folded position, or `null` when the document cannot say (migrated
+   *  from v1). The two are different facts; see {@link WalDoc.brackets}. */
+  get brackets() {
+    return this.doc.brackets;
+  }
+  get frontier() {
+    return { ...this.doc.frontier };
+  }
+  get pending() {
+    return this.doc.pending ? { ...this.doc.pending } : null;
+  }
+  /**
+   * Load an existing WAL, or start a virgin one.
+   *
+   * `subjectMayExist` is the caller's honest statement about whether this principal+thread could
+   * already have published. It is NOT a convenience flag: with it true, a missing or empty WAL is a
+   * refusal, because the tip cannot be inferred — agent creds hold no read shape over the subject,
+   * and guessing `E := 0` either CAS-halts forever or appends under a stale expectation. Recovery
+   * from that state is an explicit operator act, never a startup heuristic.
+   */
+  /** Bound by {@link bindSubjectFrontier}; absent for a WAL nothing publishes from. */
+  subject;
+  static async open(path, opts) {
+    let raw;
+    let bytes;
+    try {
+      bytes = await (0, import_promises2.readFile)(path);
+    } catch (e) {
+      if (e.code !== "ENOENT")
+        throw e;
+    }
+    if (bytes !== void 0) {
+      try {
+        raw = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+      } catch {
+        throw new WalCorruptError(path, "the file is valid UTF-8", "invalid UTF-8 bytes; refusing rather than substituting U+FFFD");
+      }
+    }
+    if (raw === void 0) {
+      if (opts.subjectMayExist)
+        throw new WalCorruptError(path, "WAL exists when the subject may", "no WAL file, but this thread may already have published");
+      return new _EventWal(path, _EventWal.virgin(opts.space, opts.threadId, opts.principal));
+    }
+    if (raw.length === 0)
+      throw new WalCorruptError(path, "WAL is non-empty", "the file is zero bytes \u2014 distinct from missing and never treated as a virgin thread");
+    return new _EventWal(path, parseDoc(path, raw, opts.space, opts.threadId, opts.principal));
+  }
+  static virgin(space, threadId, principal) {
+    return {
+      v: EVENT_WAL_VERSION,
+      // Nothing has been written yet, so the first durable replace stamps generation 1 and must find
+      // NO FILE. A file present at generation 0 means somebody else created it while this handle
+      // believed the thread was virgin, and that is refused rather than overwritten.
+      gen: 0,
+      space,
+      epoch: (0, import_node_crypto10.randomUUID)(),
+      threadId,
+      principal,
+      frontier: { seq: 0, lastSubjectSeq: 0, sourceCursor: void 0 },
+      pending: null,
+      // KNOWN empty, not unknown: a virgin thread has published nothing, so "nothing is open" is an
+      // observation this writer can actually make.
+      brackets: { run: void 0, text: [], reasoning: [], tools: [] }
+    };
+  }
+  /**
+   * Bind the PRINCIPAL-scoped subject frontier this thread publishes onto.
+   *
+   * **THE TIP IS NOT THIS THREAD'S TO REMEMBER, AND THAT IS THE WHOLE CORRECTION.**
+   * `frontier.lastSubjectSeq` records the last sequence THIS thread was assigned, which is a true
+   * fact about this log and was mistaken for the subject's tip. The subject is per principal, so a
+   * second session of the same agent opened virgin, expected an empty subject its own predecessor
+   * had filled, and halted forever. Once bound, the bound record is authoritative for the
+   * expectation and this document's own number is history.
+   *
+   * Called once, by {@link AguiEmitter.start}, which is the only thing that drives a WAL toward a
+   * publish. An UNBOUND log still opens, replays and reports its own frontier, so a caller that
+   * only READS one needs no record; but every step toward a publish reads the subject's tip, so
+   * `expectedTip`, `beginSend`, `recordAck` and `abandon` all throw until this has been called.
+   * An earlier version of this sentence said an unbound WAL behaved exactly as it did before,
+   * which was true when it was written and stopped being true in the same change that made the
+   * unbound expectation throw.
+   */
+  async bindSubjectFrontier(frontier) {
+    if (this.subject === frontier)
+      return;
+    if (this.subject)
+      throw new Error(`event WAL ${this.path}: a DIFFERENT subject frontier is already bound`);
+    this.subject = frontier;
+  }
+  /**
+   * The sequence a publish must expect, which is the SUBJECT's tip and not this thread's.
+   *
+   * **UNBOUND IT THROWS, AND AN EARLIER VERSION OF THIS RETURNED THIS DOCUMENT'S OWN LAST ACK.**
+   * That number is the defect's own shape: per session, while the subject is per principal. The
+   * argument for returning it was that no shipped path can reach it, because
+   * {@link AguiEmitter.start} is the only route from a log to a publish and it binds before the
+   * emitter exists. The argument was true, and it is the same argument the released seam shipped
+   * on: two correct components with an assumption standing where a guard belongs, recorded in
+   * prose. So the assumption is a guard now. A caller that drives a log toward a publish without a
+   * frontier fails here rather than republishing an expectation that was never the subject's.
+   */
+  get expectedTip() {
+    if (!this.subject)
+      throw new Error(`event WAL ${this.path}: no subject frontier is bound, so there is no expectation to publish. The subject is shared by every thread of this principal, so this document's own last ack is not it; bind the principal's record with bindSubjectFrontier first.`);
+    return this.subject.tip;
+  }
+  /** Transition 1 — record the frame, with `id` and `E` frozen, BEFORE any publish. */
+  async beginSend(frame) {
+    return this.serialize(async () => {
+      if (this.doc.pending)
+        throw new Error(`event WAL ${this.path}: a frame is already pending; one emit unit is one pending frame`);
+      assertIdToken(frame.id, "event WAL pending id");
+      if (frame.E !== this.expectedTip)
+        throw new Error(`event WAL ${this.path}: E=${frame.E} is not the subject's tip ${this.expectedTip}`);
+      if (frame.seq !== this.doc.frontier.seq + 1)
+        throw new Error(`event WAL ${this.path}: seq=${frame.seq} is not the frontier's successor ${this.doc.frontier.seq + 1}`);
+      if (!Array.isArray(frame.body) || frame.body.length === 0)
+        throw new Error(`event WAL ${this.path}: a frame body must be a non-empty array of parts`);
+      await this.write({ ...this.doc, pending: { state: "sent_unacked", ...frame } });
+    });
+  }
+  /**
+   * Transition 2 — a NON-duplicate ack becomes durable before the frontier moves.
+   * A duplicate ack must never reach here; the caller fails loud on one.
+   */
+  async recordAck(ackSeq) {
+    return this.serialize(async () => {
+      const p = this.doc.pending;
+      if (!p || p.state !== "sent_unacked")
+        throw new Error(`event WAL ${this.path}: no sent_unacked frame to ack`);
+      if (!isSafeNonNegInt(ackSeq))
+        throw new Error(`event WAL ${this.path}: ackSeq must be a safe non-negative integer, got ${String(ackSeq)}`);
+      if (ackSeq <= this.expectedTip)
+        throw new Error(`event WAL ${this.path}: ackSeq=${ackSeq} is not ahead of the subject's tip ${this.expectedTip}`);
+      const subject = this.subject;
+      if (!subject)
+        throw new Error(`event WAL ${this.path}: no subject frontier is bound, so this ack has no shared record to advance`);
+      await this.assertNotClobbering();
+      await subject.advance(ackSeq);
+      await this.write({ ...this.doc, pending: { ...p, state: "acked", ackSeq } });
+    });
+  }
+  /** Transition 3 — fold the acked frame into the frontier and clear pending. */
+  async fold() {
+    return this.serialize(async () => {
+      const p = this.doc.pending;
+      if (!p || p.state !== "acked" || p.ackSeq === void 0)
+        throw new Error(`event WAL ${this.path}: no acked frame to fold`);
+      await this.write({
+        ...this.doc,
+        frontier: { seq: p.seq, lastSubjectSeq: p.ackSeq, sourceCursor: p.sourceCursor },
+        pending: null,
+        // The frame's frozen state becomes the document's, so `brackets` always describes exactly the
+        // events that are PUBLISHED AND FOLDED — never a batch that was validated and not yet sent.
+        brackets: p.brackets
+      });
+    });
+  }
+  /**
+   * Transition 4 — a bounded source range that mapped to NOTHING.
+   *
+   * A mapper SUCCESS returning zero events advances the cursor atomically and alone: no
+   * `seq` consumed, no pending written, no publish. A mapper ERROR never advances it. Empty and
+   * failed must not share a path: conflating them turns a parser bug into silently skipped history.
+   */
+  async advanceCursorOnly(rangeEnd) {
+    return this.serialize(async () => {
+      if (this.doc.pending)
+        throw new Error(`event WAL ${this.path}: cannot advance the cursor while a frame is pending`);
+      await this.write({ ...this.doc, frontier: { ...this.doc.frontier, sourceCursor: rangeEnd } });
+    });
+  }
+  /**
+   * Abandonment — explicit, destructive and TOTAL. Mints a new epoch AND resets `seq`,
+   * `lastSubjectSeq` and `sourceCursor` together, reusing the same subject; the new epoch is what
+   * tells a consumer the chain broke. Partial abandonment is not a state: either all four move or
+   * the emitter stays halted. Required after a filtered channel purge, which returns the subject
+   * tip to 0 while the WAL still holds a non-zero `E`, permanently CAS-failing every later publish.
+   */
+  async abandon() {
+    return this.serialize(async () => {
+      await this.assertNotClobbering();
+      if (!this.subject)
+        throw new Error(`event WAL ${this.path}: no subject frontier is bound, so an abandonment here would clear this log and leave the principal's shared tip standing, which is the partial abandonment this method refuses to produce; bind the principal's record with bindSubjectFrontier first.`);
+      await this.subject.reset();
+      await this.write({
+        ...this.doc,
+        epoch: (0, import_node_crypto10.randomUUID)(),
+        frontier: { seq: 0, lastSubjectSeq: 0, sourceCursor: void 0 },
+        pending: null,
+        // Abandonment is TOTAL, and the bracket machine is part of the total. A new epoch tells a
+        // consumer the chain broke, so carrying the old chain's open runs into it would be a partial
+        // abandonment — and partial abandonment is not a state.
+        brackets: { run: void 0, text: [], reasoning: [], tools: [] }
+      });
+    });
+  }
+  /**
+   * Durable replace: write a sibling temp file, fsync it, then rename over the target. The rename
+   * is what makes a reader see either the whole old document or the whole new one and never a torn
+   * prefix — which is precisely why a zero-byte WAL is treated as corruption rather than as virgin.
+   *
+   * **MODE 0600, AND THE REASON IS NOT TIDINESS: `pending.id` IS A PRE-PUBLICATION SECRET.**
+   * The dedup cache the frozen id is checked against is STREAM-WIDE, so anyone who learns an id
+   * BEFORE its frame is published can pre-seed it and make the real publish come back
+   * `duplicate: true`. The design attributes the safety of that entirely to `randomUUID()` entropy —
+   * which holds only while the id is unguessable AND unread. An id already on the wire is harmless
+   * (that message has landed); the only window where it is dangerous is exactly the window this
+   * file holds it in, between transition 1 and the ack.
+   *
+   * So the residual a reviewer raised as "gated on a local disk read rather than mesh access" is
+   * gated on a read OF THIS FILE. A world-readable WAL would convert a property the design credits
+   * to entropy into one credited to filesystem luck. Under our own rules the attack yields a LOUD
+   * halt rather than silent loss — a duplicate ack on a retry fails loud with the frontier and
+   * cursor unmoved — so this is denial of service, not corruption. Closing it by construction is
+   * cheap enough that naming it as an accepted residual would be the worse trade.
+   */
+  async write(next) {
+    await this.assertNotClobbering();
+    const stamped = { ...next, gen: this.doc.gen + 1 };
+    const tmp = (0, import_node_path3.join)((0, import_node_path3.dirname)(this.path), `.${(0, import_node_crypto10.createHash)("sha256").update(this.path).digest("hex").slice(0, 12)}.${process.pid}.${(0, import_node_crypto10.randomUUID)().slice(0, 8)}.wal.tmp`);
+    const body = JSON.stringify(stamped);
+    const fh = await openExclusiveNoFollow(tmp);
+    try {
+      await fh.writeFile(body, "utf8");
+      await fh.sync();
+    } finally {
+      await fh.close();
+    }
+    try {
+      await (0, import_promises2.rename)(tmp, this.path);
+    } catch (e) {
+      await (0, import_promises2.unlink)(tmp).catch(() => {
+      });
+      throw e;
+    }
+    this.doc = stamped;
+  }
+  /**
+   * Refuse to replace a document this handle did not read.
+   *
+   * **THE FAILURE THIS EXISTS FOR WAS EXECUTED, NOT IMAGINED.** Two `EventWal` objects were opened
+   * on one file. A ran the full cycle and folded a frontier of `{seq:1, lastSubjectSeq:5}`. B, whose
+   * in-memory document was frozen back at the pending write, then called `recordAck(99)` and
+   * `fold()` — both SUCCEEDED, each replacing the whole file, and the WAL came back up claiming a
+   * durable tip of 99: a subject sequence the broker never assigned. The next publish freezes
+   * `E := 99` against a stream whose real tip is 5, so the emitter either CAS-halts forever or
+   * recovers a frontier that never existed. Nothing about that is loud; it reads as a healthy WAL.
+   *
+   * The per-instance `serialize` chain cannot see it (two instances, two chains) and neither can the
+   * principal lock (B's handle predates any lock B would take, and a lock is not held against a
+   * process's own second object). The guard has to be HERE, on the write, where the two views
+   * finally meet.
+   *
+   * **This is a check, not a transaction, and the difference is stated rather than glossed.** The
+   * read and the `rename` are separate syscalls, so a writer that lands in between is not caught by
+   * this; what is caught is every stale handle — the case that actually occurs, because a stale
+   * handle stays stale for as long as it exists rather than for a syscall's width. The lock is what
+   * keeps a second live writer from starting; this is what keeps one that already exists from
+   * winning.
+   */
+  async assertNotClobbering() {
+    let bytes;
+    try {
+      bytes = await (0, import_promises2.readFile)(this.path);
+    } catch (e) {
+      if (e.code !== "ENOENT")
+        throw e;
+    }
+    if (bytes === void 0) {
+      if (this.doc.gen !== 0)
+        throw new WalStaleWriterError(this.path, this.doc.gen, void 0);
+      return;
+    }
+    let raw;
+    try {
+      raw = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    } catch {
+      throw new WalCorruptError(this.path, "the file is valid UTF-8", "invalid UTF-8 bytes on the file about to be replaced; refusing rather than substituting U+FFFD");
+    }
+    let d;
+    try {
+      d = JSON.parse(raw);
+    } catch (e) {
+      throw new WalCorruptError(this.path, "parseable JSON", e.message);
+    }
+    if (typeof d !== "object" || d === null)
+      throw new WalCorruptError(this.path, "document is an object", typeof d);
+    const onDisk = docGeneration(this.path, d);
+    if (onDisk !== this.doc.gen)
+      throw new WalStaleWriterError(this.path, this.doc.gen, onDisk);
+  }
+};
+
+// ../connector-core/dist/subject-frontier.js
+var import_node_crypto12 = require("node:crypto");
+var import_node_fs6 = require("node:fs");
+var import_promises4 = require("node:fs/promises");
+var import_node_path5 = require("node:path");
+
+// ../connector-core/dist/agui-wal-path.js
+var import_node_crypto11 = require("node:crypto");
+var import_promises3 = require("node:fs/promises");
+var import_node_os3 = require("node:os");
+var import_node_path4 = require("node:path");
+var EventsStateRootMissing = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "EventsStateRootMissing";
+  }
+};
+function resolveEventsStateRoot(env) {
+  const root = env.COTAL_WORKSPACE_ROOT;
+  if (typeof root !== "string" || root.trim() === "")
+    throw new EventsStateRootMissing("events are enabled for this session but COTAL_WORKSPACE_ROOT is not set, so there is nowhere to put the event write-ahead log. The launcher forwards it from LaunchOpts.workspaceRoot; a session started outside a manager has no workspace root and must not publish events. Refusing rather than defaulting to the working directory, which would put the WAL somewhere no later start looks.");
+  return root;
+}
+function h(value) {
+  return (0, import_node_crypto11.createHash)("sha256").update(value).digest("hex").slice(0, 16);
+}
+function eventWalLocation(opts) {
+  const principalDir = (0, import_node_path4.join)(opts.workspaceRoot, ".cotal", "events", h(opts.space), h(opts.principal));
+  const threadDir = (0, import_node_path4.join)(principalDir, h(opts.threadId));
+  return {
+    principalDir,
+    lockPath: (0, import_node_path4.join)(principalDir, ".lock"),
+    subjectPath: (0, import_node_path4.join)(principalDir, "subject.json"),
+    threadDir,
+    walPath: (0, import_node_path4.join)(threadDir, "wal.json")
+  };
+}
+var PrincipalLockError = class extends Error {
+  path;
+  invariant;
+  constructor(path, invariant, detail) {
+    super(`event WAL principal lock at ${path} (${invariant}): ${detail}`);
+    this.path = path;
+    this.invariant = invariant;
+    this.name = "PrincipalLockError";
+  }
+};
+var held = /* @__PURE__ */ new Map();
+function ownerIsAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    return e.code !== "ESRCH";
+  }
+}
+async function createLockFile(path) {
+  try {
+    return await openExclusiveNoFollow(path);
+  } catch (e) {
+    if (e.code === "EEXIST")
+      return void 0;
+    throw e;
+  }
+}
+async function reclaimIfOwnerIsGone(path) {
+  let raw;
+  try {
+    raw = await (0, import_promises3.readFile)(path, "utf8");
+  } catch (e) {
+    if (e.code === "ENOENT")
+      return;
+    throw e;
+  }
+  let record2;
+  try {
+    record2 = JSON.parse(raw);
+  } catch {
+    throw new PrincipalLockError(path, "the lock names its owner", "the file is not readable JSON, so its owner cannot be checked; refusing rather than reclaiming a lock that may be held");
+  }
+  const r = record2;
+  if (!Number.isSafeInteger(r.pid) || r.pid <= 0 || typeof r.host !== "string" || r.host.length === 0)
+    throw new PrincipalLockError(path, "the lock names its owner", `the record carries pid=${String(r.pid)} host=${String(r.host)}, which names nobody checkable`);
+  const here = (0, import_node_os3.hostname)();
+  if (r.host !== here)
+    throw new PrincipalLockError(path, "the recorded owner is on THIS host", `held by pid ${r.pid} on ${r.host} while this process runs on ${here}; liveness on another machine is not observable from here`);
+  if (ownerIsAlive(r.pid))
+    throw new PrincipalLockError(path, "the recorded owner is gone", `pid ${r.pid} on ${here} is still running and holds this principal's emitter`);
+  await (0, import_promises3.unlink)(path).catch((e) => {
+    if (e.code !== "ENOENT")
+      throw e;
+  });
+}
+async function acquirePrincipalLock(lockPath) {
+  const already = held.get(lockPath);
+  if (already)
+    return already;
+  let fh = await createLockFile(lockPath);
+  if (fh === void 0) {
+    await reclaimIfOwnerIsGone(lockPath);
+    fh = await createLockFile(lockPath);
+    if (fh === void 0)
+      throw new PrincipalLockError(lockPath, "the reclaimed lock is free when this process takes it", "another process created the lock between the reclaim and this open, and now holds this principal");
+  }
+  const record2 = JSON.stringify({ pid: process.pid, host: (0, import_node_os3.hostname)(), token: (0, import_node_crypto11.randomUUID)(), acquiredAt: (/* @__PURE__ */ new Date()).toISOString() });
+  try {
+    await fh.writeFile(record2, "utf8");
+    await fh.sync();
+  } catch (e) {
+    await fh.close().catch(() => {
+    });
+    await (0, import_promises3.unlink)(lockPath).catch(() => {
+    });
+    throw e;
+  }
+  const lock = {
+    path: lockPath,
+    async release() {
+      if (held.get(lockPath) !== lock)
+        return;
+      held.delete(lockPath);
+      await fh.close().catch(() => {
+      });
+      await (0, import_promises3.unlink)(lockPath).catch((e) => {
+        if (e.code !== "ENOENT")
+          throw e;
+      });
+    }
+  };
+  held.set(lockPath, lock);
+  return lock;
+}
+async function fsyncDir(dir) {
+  let fh;
+  try {
+    fh = await (0, import_promises3.open)(dir, "r");
+  } catch (e) {
+    const code = e.code;
+    if (code === "EPERM" || code === "EACCES")
+      return;
+    throw e;
+  }
+  try {
+    await fh.sync();
+  } catch (e) {
+    const code = e.code;
+    if (code !== "EBADF" && code !== "EINVAL" && code !== "EPERM" && code !== "EISDIR")
+      throw e;
+  } finally {
+    await fh.close();
+  }
+}
+async function ensureEventWalDir(opts) {
+  const loc = eventWalLocation(opts);
+  ensureDirNoSymlink(opts.workspaceRoot, ".cotal", "events", h(opts.space), h(opts.principal), h(opts.threadId));
+  for (let dir = loc.threadDir; ; dir = (0, import_node_path4.dirname)(dir)) {
+    await fsyncDir(dir);
+    if (dir === opts.workspaceRoot || (0, import_node_path4.dirname)(dir) === dir)
+      break;
+  }
+  const lock = await acquirePrincipalLock(loc.lockPath);
+  return { ...loc, lock };
+}
+
+// ../connector-core/dist/subject-frontier.js
+var SUBJECT_FRONTIER_VERSION = 1;
+var SubjectFrontierCorruptError = class extends Error {
+  path;
+  invariant;
+  constructor(path, invariant, detail) {
+    super(`subject frontier ${path}: expected ${invariant} \u2014 ${detail}`);
+    this.path = path;
+    this.invariant = invariant;
+    this.name = "SubjectFrontierCorruptError";
+  }
+};
+var SubjectFrontierMovedError = class extends Error {
+  path;
+  viewTip;
+  diskTip;
+  constructor(path, viewTip, diskTip) {
+    super(`subject frontier ${path}: the record moved under this writer (this view holds ${viewTip}, the file holds ${diskTip === void 0 ? "no record at all" : diskTip}). The tip is shared by every thread of the principal, so writing this view's number would take the record backwards to a sequence the broker has already passed, and every later publish would expect a tip the subject no longer has.`);
+    this.path = path;
+    this.viewTip = viewTip;
+    this.diskTip = diskTip;
+    this.name = "SubjectFrontierMovedError";
+  }
+};
+var isSafeNonNegInt2 = (n) => typeof n === "number" && Number.isSafeInteger(n) && n >= 0;
+var FileSubjectFrontier = class _FileSubjectFrontier {
+  path;
+  doc;
+  constructor(path, doc) {
+    this.path = path;
+    this.doc = doc;
+  }
+  get tip() {
+    return this.doc.tip;
+  }
+  /**
+   * Open, or create a virgin record.
+   *
+   * A MISSING file is virgin and legal: this principal has never published, which is the ordinary
+   * state on a first run and after a fresh install. A ZERO-BYTE file is NOT, for the same reason
+   * the write-ahead log refuses one: an atomic temp-and-rename never produces it, so it is a
+   * filesystem that lost the tail, and reading it as "never published" is the guess this whole
+   * mechanism exists to remove.
+   */
+  static async open(path, opts) {
+    let bytes;
+    try {
+      bytes = await (0, import_promises4.readFile)(path);
+    } catch (e) {
+      if (e.code !== "ENOENT")
+        throw e;
+    }
+    if (bytes === void 0) {
+      const recovered = await _FileSubjectFrontier.recoverTipFromThreadLogs((0, import_node_path5.dirname)(path), opts.principal);
+      const fresh = new _FileSubjectFrontier(path, { v: SUBJECT_FRONTIER_VERSION, space: opts.space, principal: opts.principal, tip: 0 });
+      if (recovered > 0)
+        await fresh.write({ ...fresh.doc, tip: recovered });
+      return fresh;
+    }
+    return new _FileSubjectFrontier(path, _FileSubjectFrontier.parse(path, bytes, opts));
+  }
+  /**
+   * Bytes to a validated document, or a refusal.
+   *
+   * SHARED BY `open` AND BY THE RE-READ IN {@link advance} on purpose. A record that went corrupt
+   * underneath a live writer has to meet the same wall as one that was corrupt at boot; validating
+   * only on the way in would let a writer that opened a good file overwrite a bad one, which
+   * destroys the evidence of whatever produced it.
+   */
+  static parse(path, bytes, opts) {
+    let raw;
+    try {
+      raw = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    } catch {
+      throw new SubjectFrontierCorruptError(path, "valid UTF-8", "invalid UTF-8 bytes; refusing rather than substituting U+FFFD");
+    }
+    if (raw.length === 0)
+      throw new SubjectFrontierCorruptError(path, "a non-empty file", "the file is zero bytes \u2014 distinct from missing, and never treated as virgin");
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch (e) {
+      throw new SubjectFrontierCorruptError(path, "parseable JSON", e.message);
+    }
+    const d = parsed;
+    if (d?.v !== SUBJECT_FRONTIER_VERSION)
+      throw new SubjectFrontierCorruptError(path, `v === ${SUBJECT_FRONTIER_VERSION}`, String(d?.v));
+    if (d.space !== opts.space)
+      throw new SubjectFrontierCorruptError(path, "space matches", `file=${String(d.space)} caller=${opts.space}`);
+    if (d.principal !== opts.principal)
+      throw new SubjectFrontierCorruptError(path, "principal matches", `file=${String(d.principal)} caller=${opts.principal}`);
+    if (!isSafeNonNegInt2(d.tip))
+      throw new SubjectFrontierCorruptError(path, "tip is a safe non-negative integer", String(d.tip));
+    return { v: d.v, space: d.space, principal: d.principal, tip: d.tip };
+  }
+  async advance(seq) {
+    return this.serialize(async () => {
+      if (!isSafeNonNegInt2(seq))
+        throw new Error(`subject frontier ${this.path}: seq must be a safe non-negative integer, got ${String(seq)}`);
+      if (seq <= this.doc.tip)
+        throw new Error(`subject frontier ${this.path}: seq=${seq} does not advance the tip ${this.doc.tip}`);
+      const disk = await this.readDiskTip();
+      if (disk === void 0 ? this.doc.tip !== 0 : disk !== this.doc.tip)
+        throw new SubjectFrontierMovedError(this.path, this.doc.tip, disk);
+      await this.write({ ...this.doc, tip: seq });
+    });
+  }
+  /**
+   * The tip the FILE holds, or `undefined` when no record exists yet.
+   *
+   * Fully validated, not a bare `JSON.parse().tip`: the disagreement this feeds is decided on a
+   * number, and a number taken from a document that failed its own shape checks is not evidence.
+   */
+  async readDiskTip() {
+    let bytes;
+    try {
+      bytes = await (0, import_promises4.readFile)(this.path);
+    } catch (e) {
+      if (e.code === "ENOENT")
+        return void 0;
+      throw e;
+    }
+    return _FileSubjectFrontier.parse(this.path, bytes, { space: this.doc.space, principal: this.doc.principal }).tip;
+  }
+  /**
+   * One mutation at a time on THIS instance.
+   *
+   * The re-read above is a read-modify-write, so two callers that interleave between the read and
+   * the rename would both pass a check neither still satisfies. One frontier is legitimately bound
+   * to SEVERAL logs (the pinning runs the other way: a log may not change which record it
+   * publishes onto), so concurrent callers on one instance are an ordinary state, not a misuse.
+   *
+   * It serializes this instance and nothing else. Two instances have two chains, which is the case
+   * the re-read exists for.
+   */
+  chain = Promise.resolve();
+  serialize(op) {
+    const next = this.chain.then(op, op);
+    this.chain = next.catch(() => void 0);
+    return next;
+  }
+  /**
+   * Recover the tip from the THREAD LOGS beside this record, for an installation upgrading from a
+   * release where this record did not exist.
+   *
+   * **THIS IS THE WHOLE UPGRADE PATH AND LEAVING IT OUT MAKES THE FIX APPLY TO NOBODY WHO ALREADY
+   * RAN THE BROKEN VERSION.** My first attempt seeded from the log of the thread being opened, which
+   * is empty in the case that matters: upgrading restarts the seat, so the first session after the
+   * upgrade is a NEW thread with a virgin log, while the sequence it needs sits in the PREVIOUS
+   * thread's log. A cell in `smoke:agui-multi-session` failed on exactly that and is the reason this
+   * function exists rather than the reasoning that produced the first version.
+   *
+   * **ONLY WHEN THE RECORD IS ABSENT, NEVER WHEN IT READS ZERO.** A record holding zero is what
+   * abandonment writes after a filtered purge, and re-seeding it from a thread log would silently
+   * undo the abandonment and restore an expectation the subject no longer has. Missing and zero are
+   * different states and this is the second place in this plane where conflating them is the bug.
+   *
+   * A sibling that cannot be read or does not parse is FATAL rather than skipped. Skipping it
+   * under-counts the tip, which produces a permanent halt later with a message about a moved tip,
+   * pointing at everything except the file that was quietly ignored here.
+   */
+  static async recoverTipFromThreadLogs(principalDir, principal) {
+    let entries;
+    try {
+      entries = await (0, import_promises4.readdir)(principalDir, { withFileTypes: true });
+    } catch (e) {
+      if (e.code === "ENOENT")
+        return 0;
+      throw e;
+    }
+    let best = 0;
+    for (const ent of entries) {
+      if (ent.isSymbolicLink())
+        throw new SubjectFrontierCorruptError((0, import_node_path5.join)(principalDir, ent.name), "a real directory beside the record, never a symlink", "following it would carry this scan outside the principal directory, and the writer that creates these directories refuses a symlinked component for the same reason");
+      if (!ent.isDirectory())
+        continue;
+      const walPath = (0, import_node_path5.join)(principalDir, ent.name, "wal.json");
+      let st;
+      try {
+        st = await (0, import_promises4.lstat)(walPath);
+      } catch (e) {
+        const code = e.code;
+        if (code === "ENOENT" || code === "ENOTDIR")
+          continue;
+        throw e;
+      }
+      if (st.isSymbolicLink())
+        throw new SubjectFrontierCorruptError(walPath, "a real thread log, never a symlink", "following it would read a log this principal's writer never wrote");
+      if (st.nlink > 1)
+        throw new SubjectFrontierCorruptError(walPath, "a thread log with exactly one name", `it has ${st.nlink}, so the same file is reachable from outside this principal's directory and its tip is not this principal's to read`);
+      let raw;
+      try {
+        const fh = await (0, import_promises4.open)(walPath, import_node_fs6.constants.O_RDONLY | (import_node_fs6.constants.O_NOFOLLOW ?? 0));
+        try {
+          raw = await fh.readFile();
+        } finally {
+          await fh.close();
+        }
+      } catch (e) {
+        const code = e.code;
+        if (code === "ENOENT" || code === "ENOTDIR")
+          continue;
+        if (code === "ELOOP")
+          throw new SubjectFrontierCorruptError(walPath, "a real thread log, never a symlink", "the file became a symlink between the check and the open");
+        throw e;
+      }
+      let doc;
+      try {
+        doc = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(raw));
+      } catch (e) {
+        throw new SubjectFrontierCorruptError(walPath, "a readable thread log while recovering the subject tip", e.message);
+      }
+      if (doc.principal !== principal)
+        throw new SubjectFrontierCorruptError(walPath, `a thread log for principal ${principal}`, `found ${String(doc.principal)}`);
+      const seq = doc.frontier?.lastSubjectSeq;
+      if (!isSafeNonNegInt2(seq))
+        throw new SubjectFrontierCorruptError(walPath, "frontier.lastSubjectSeq is a safe non-negative integer", String(seq));
+      if (seq > best)
+        best = seq;
+      const pending = doc.pending;
+      if (pending && pending.state === "acked") {
+        const acked = pending.ackSeq;
+        if (!isSafeNonNegInt2(acked))
+          throw new SubjectFrontierCorruptError(walPath, "an acked pending carries a safe non-negative ackSeq", String(acked));
+        if (!(acked > seq))
+          throw new SubjectFrontierCorruptError(walPath, "an acked pending is ahead of the frontier it will fold into", `ackSeq=${acked} frontier.lastSubjectSeq=${seq}`);
+        if (acked > best)
+          best = acked;
+      }
+    }
+    return best;
+  }
+  // `seedFromThread` used to live here, and it is GONE rather than kept for a caller that might
+  // want it. Recovery moved into `open`, which is the only place that can see every sibling log,
+  // and what was left behind was a public method that writes a tip into a record whose only
+  // precondition is that the record reads 0. A record reading 0 is exactly what abandonment writes
+  // after a channel purge, so the leftover was a supported route back into the state this file
+  // exists to prevent, with no shipped caller to justify it.
+  async reset() {
+    return this.serialize(async () => {
+      await this.write({ ...this.doc, tip: 0 });
+    });
+  }
+  /** Atomic replace: sibling temp, fsync, rename, fsync the directory. */
+  async write(next) {
+    const tmp = `${this.path}.${(0, import_node_crypto12.randomUUID)()}.tmp`;
+    const fh = await (0, import_promises4.open)(tmp, import_node_fs6.constants.O_WRONLY | import_node_fs6.constants.O_CREAT | import_node_fs6.constants.O_EXCL, 384);
+    try {
+      await fh.writeFile(JSON.stringify(next));
+      await fh.sync();
+    } finally {
+      await fh.close();
+    }
+    try {
+      await (0, import_promises4.rename)(tmp, this.path);
+    } catch (e) {
+      await (0, import_promises4.unlink)(tmp).catch(() => {
+      });
+      throw e;
+    }
+    await fsyncDir((0, import_node_path5.dirname)(this.path));
+    this.doc = next;
+  }
+};
+
+// ../connector-core/dist/agui-holder.js
+var AguiEmitterHolder = class {
+  startEmitter;
+  onError;
+  onRunClosed;
+  emitter;
+  /** The path this holder is BOUND to. Set before `starting`, so a second path is refused even
+   *  while the first start is still in flight. */
+  boundPath;
+  /**
+   * Terminal. Once set, this holder never starts, pumps, or reports success again.
+   *
+   * It does not retry, and that is a decision rather than an omission. A retry on the next hook
+   * would re-run that preflight and a WAL recovery against a stream this holder has already
+   * failed to establish itself on, on a timer set by how often the user happens to type. The
+   * emitter's own answer to an uncertain publish is to halt rather than to limp, and a holder that
+   * quietly reconnected underneath it would reintroduce, one layer up, exactly the silence the
+   * emitter refuses.
+   */
+  dead;
+  /** ALL mutation runs on this chain. Hook events arrive concurrently on the control socket, so
+   *  without it two flushes could read the source at the same cursor. */
+  chain = Promise.resolve();
+  /**
+   * @param startEmitter Builds and starts the emitter for an adopted path. Injected rather than
+   *   assembled here: the WAL location, the source, and the record mapper are all connector
+   *   decisions, and a holder that made them would be a second place they are decided.
+   * @param onError Where a failure goes. Required, and not defaulted to a swallow: this class runs
+   *   behind a hook that must not throw, so the only way a failure reaches a human is if the caller
+   *   is made to say where it goes.
+   * @param onRunClosed Told which run {@link closeRun} closed, so the connector's own mapper can
+   *   forget the run it will no longer attribute records to. Optional, and it is NOT the holder
+   *   doing the forgetting: which state a record mapper keeps is the connector's business, and a
+   *   holder that reached into it would be a second place that decides what a run is. Without it a
+   *   mapper that still believes the run is open would emit under a `runId` the published stream has
+   *   already closed, and the emitter would refuse the batch.
+   */
+  constructor(startEmitter, onError, onRunClosed) {
+    this.startEmitter = startEmitter;
+    this.onError = onError;
+    this.onRunClosed = onRunClosed;
+  }
+  /** True once an emitter is running here. False while a start is still in flight — it reports what
+   *  IS, never what is about to be. */
+  get running() {
+    return this.emitter !== void 0 && !this.emitter.stopped;
+  }
+  /** The failure that killed this holder, if one did. */
+  get failure() {
+    return this.dead;
+  }
+  /** The path this holder bound to on first adopt, if it has adopted. */
+  get path() {
+    return this.boundPath;
+  }
+  /**
+   * Adopt a transcript path, starting the emitter if this is the first one.
+   *
+   * Synchronous and non-throwing by contract, because a hook calls it. The work lands on the chain.
+   */
+  adopt(path) {
+    this.enqueue(() => this.ensureStarted(path).then(() => void 0));
+  }
+  /**
+   * Adopt if necessary, then drain the source into frames.
+   *
+   * Same contract as {@link adopt}: synchronous, non-throwing, work on the chain.
+   */
+  flush(path) {
+    this.enqueue(async () => {
+      const emitter = await this.ensureStarted(path);
+      if (!emitter || emitter.stopped)
+        return;
+      await emitter.pump();
+    });
+  }
+  /**
+   * Start at most once, bind the path once.
+   *
+   * Returns `undefined` when there is nothing to run against — a dead holder or a path this holder
+   * cannot take — rather than throwing, so a caller cannot mistake "no emitter" for "pumped".
+   */
+  /**
+   * Close the open run at a turn boundary the record stream cannot see.
+   *
+   * Same contract as {@link adopt} and {@link flush}: synchronous, non-throwing, work on the chain,
+   * because a lifecycle hook calls it and a hook must not be made to wait or to fail.
+   *
+   * It deliberately does NOT start an emitter. A session that never adopted a transcript has nothing
+   * open and nothing to close, and starting one here would reach the broker on the way OUT of a
+   * turn that published nothing.
+   */
+  closeRun(timestamp) {
+    this.enqueue(async () => {
+      const emitter = this.emitter;
+      if (this.dead || !emitter || emitter.stopped)
+        return;
+      const runId = await emitter.closeRun({ timestamp });
+      if (runId !== null)
+        this.onRunClosed?.(runId);
+    });
+  }
+  async ensureStarted(path) {
+    if (this.dead)
+      return void 0;
+    if (typeof path !== "string" || path.length === 0)
+      return void 0;
+    if (this.boundPath !== void 0 && this.boundPath !== path) {
+      this.die(new Error(`AG-UI emitter is bound to transcript ${this.boundPath}; refusing to re-adopt ${path} \u2014 a second session needs its own emitter and its own write-ahead log`));
+      return void 0;
+    }
+    if (this.emitter)
+      return this.emitter;
+    if (this.boundPath === void 0) {
+      this.boundPath = path;
+      try {
+        this.emitter = await this.startEmitter(path);
+        return this.emitter;
+      } catch (e) {
+        this.die(e);
+        return void 0;
+      }
+    }
+    return this.emitter;
+  }
+  die(e) {
+    if (this.dead)
+      return;
+    this.dead = e;
+    this.onError(e);
+  }
+  enqueue(step) {
+    this.chain = this.chain.then(step).catch((e) => this.die(e));
+  }
+  /** Await the queued work. For callers that need a settled point — a shutdown, or a cell. */
+  async settled() {
+    await this.chain;
+  }
+};
 
 // ../connector-core/dist/agui-render.js
 var str = (v) => typeof v === "string" ? v : void 0;
@@ -65242,7 +67080,7 @@ var THINK_PREFIX = "(thinking) ";
 var TOOL_PREFIX = "\u2699 ";
 var RESULT_PREFIX = "  \u21B3 ";
 var BLOCK_START_CHARS = /* @__PURE__ */ new Set([..."#>|`~=_*+-[<0123456789", "	"]);
-function renderEvents(events) {
+function renderEvents(events2) {
   const lines = [];
   const text = /* @__PURE__ */ new Map();
   const reasoning = /* @__PURE__ */ new Map();
@@ -65260,7 +67098,7 @@ function renderEvents(events) {
       emit(first, cont, acc + suffix);
     map2.delete(id);
   };
-  for (const e of events) {
+  for (const e of events2) {
     const type = typeof e === "object" && e !== null ? str(e.type) : void 0;
     switch (type) {
       case AGUI_EVENT_TYPE.RUN_STARTED:
@@ -65343,11 +67181,11 @@ var aguiFramePartRenderer = Object.freeze({
   render(part) {
     if (!isAguiFramePart(part))
       return `[not an AG-UI frame]`;
-    const events = part.events;
-    if (!Array.isArray(events) || events.length === 0)
+    const events2 = part.events;
+    if (!Array.isArray(events2) || events2.length === 0)
       return `[AG-UI frame carrying no events]`;
-    const lines = renderEvents(events);
-    return lines.length > 0 ? lines.join("\n") : `[AG-UI frame with ${events.length} event(s) and nothing to show]`;
+    const lines = renderEvents(events2);
+    return lines.length > 0 ? lines.join("\n") : `[AG-UI frame with ${events2.length} event(s) and nothing to show]`;
   }
 });
 function registerAguiFramePartRenderer() {
@@ -65362,7 +67200,7 @@ var import_node_child_process2 = require("node:child_process");
 
 // ../connector-core/dist/docs-bundle.generated.js
 var DOCS_BUNDLE = {
-  "version": "0.21.0",
+  "version": "0.23.0",
   "generatedFrom": "docs/*.md + SPEC.md + spec/cotal.schema.json",
   "pages": [
     {
@@ -65419,42 +67257,42 @@ var DOCS_BUNDLE = {
       "title": "Authoring a connector",
       "kind": "Reference: describes the TypeScript reference implementation, not the wire contract.",
       "summary": "A connector teaches Cotal how to launch one agent harness (Claude Code, OpenCode, your own) as a mesh node.",
-      "body": '# Authoring a connector\n\n> **Reference**: describes the TypeScript reference implementation, not the wire contract. \xB7 **For:** integrators adding a new agent harness \xB7 **Wire contract:** [SPEC](../SPEC.md)\n\nA **connector** teaches Cotal how to launch one agent harness (Claude Code, OpenCode, your own) as a\nmesh node. Connectors are ordinary [extensions](cli.md#ext): you publish an npm package, the operator\nruns `cotal ext add <your-package>`, and it plugs in exactly like the first-party connectors,\nwhich are themselves just connectors seeded on first run. There is no special-casing for built-ins,\nso anything the built-ins can do, yours can too.\n\n## The contract\n\nImplement `Connector` from `@cotal-ai/core` and self-register it on import:\n\n```ts\nimport { registry, type Connector } from "@cotal-ai/core";\n\nconst myConnector: Connector = {\n  kind: "connector",\n  name: "myagent",                       // the --agent value; must be unique, never "cotal"\n  requires: ["myagent"],                 // external CLIs the launch needs on PATH (preflighted)\n  buildLaunch(opts) {                    // opts \u2192 the process + env that joins the mesh\n    return {\n      command: "myagent",\n      args: ["--serve"],\n      env: { /* COTAL_* wiring from opts */ },\n    };\n  },\n  // optional: listModels, supportsModelVariant, supportsResume, transcriptChannel,\n  //           eventChannel, pluginRoot\n};\n\nregistry.register(myConnector);          // runs on import \u2014 that\'s what makes it "plug in"\n```\n\n`buildLaunch(opts)` is the whole job: given a `LaunchOpts` (space, name, role, creds, channels,\nmodel, prompt\u2026), return a `LaunchSpec` (the command, args, and environment) whose process connects to\nthe broker as that mesh node. Everything else on the interface is optional and default-deny: declare\n`supportsModelVariant`/`supportsResume` only if you honor them (a request for one you don\'t declare\nfails loud before any provisioning), list `requires` so a missing CLI fails with a clear message, and\nimplement `listModels` only if you want a selector catalog. Implement `eventChannel` only if your\nsession publishes a structured event plane: it names the channel the manager grants that session\npublish rights on, so the grant and the subject the session publishes to come from one function\nrather than two that can drift, and `--events` refuses a connector that does not implement it. See\nthe `Connector` interface in\n[`packages/core/src/connector.ts`](../packages/core/src/connector.ts) and the OpenCode connector in\n[`extensions/connector-opencode/`](../extensions/connector-opencode/) for a complete worked example.\n\n## Packaging rules (enforced at `ext add`)\n\n`cotal ext add` verifies these and fails loud otherwise, because they are what keep every extension\nsharing the binary\'s single `@cotal-ai/core` registry instance:\n\n- **`@cotal-ai/core` is a `peerDependency`, never a regular dependency.** A regular dep vendors a\n  second copy of core, whose separate registry would swallow your `registry.register` call \u2014 the add\n  would import your package cleanly but see zero contributions and refuse it. Any other `@cotal-ai/*`\n  you use is a peer too. `ext add` junction-links each `@cotal-ai/*` peer to the binary\'s own copy;\n  lazy materialization verifies and rebinds those links for the registry-facing entry\'s initial import,\n  so global installs and source worktrees can share the machine extension prefix. Import every host peer\n  in that initial graph; launcher/child artifacts that run later must bundle their dependencies rather\n  than resolving a mutable host-peer link after another Cotal process may have rebound it.\n- **Bundle core as external.** If you bundle (esbuild/rollup), mark `@cotal-ai/core` (and any other\n  `@cotal-ai/*`) `--external` so the runtime `import` resolves the host\'s copy, not an inlined one.\n- **Importing the package must self-register.** Your entry (`main`/`exports`) must run\n  `registry.register(...)` as a side effect of import (e.g. `export * from "./extension.js"`), so the\n  lazy materialize path can bring you online without a bespoke hook.\n- **Name yourself.** The connector `name` is the `--agent` value; it must be unique across installed\n  extensions and must not be the reserved name `cotal`.\n\nA minimal `package.json`:\n\n```jsonc\n{\n  "name": "@you/cotal-connector-myagent",\n  "type": "module",\n  "main": "./dist/index.js",\n  "files": ["dist"],                     // whatever `ext add` needs to install + import\n  "peerDependencies": { "@cotal-ai/core": ">=0.1.0" }\n}\n```\n\n## Install, use, remove\n\n```bash\ncotal ext add @you/cotal-connector-myagent   # installs + verifies + caches its contribution\ncotal spawn --agent myagent                   # or `agent: myagent` in a manifest\ncotal ext remove @you/cotal-connector-myagent # gone; nothing static-imported it\n```\n\nSet `COTAL_DEFAULT_AGENT=myagent` to make it the default for a bare `cotal spawn`. Your connector\nresolves through the same lazy-materialize path as the built-ins (in the CLI\'s launch preflight and in\nthe manager), so a live `cotal up` will seed nothing extra: it imports your package, reads `requires`,\nand launches. For runtimes (how a node is hosted: pty/tmux/\u2026) rather than harnesses, the same\nextension model applies via the `Runtime` contract; see [define a team](define-a-team.md) and\n[the CLI reference](cli.md).\n'
+      "body": '# Authoring a connector\n\n> **Reference**: describes the TypeScript reference implementation, not the wire contract. \xB7 **For:** integrators adding a new agent harness \xB7 **Wire contract:** [SPEC](../SPEC.md)\n\nA **connector** teaches Cotal how to launch one agent harness (Claude Code, OpenCode, your own) as a\nmesh node. Connectors are ordinary [extensions](cli.md#ext): you publish an npm package, the operator\nruns `cotal ext add <your-package>`, and it plugs in exactly like the first-party connectors,\nwhich are themselves just connectors seeded on first run. There is no special-casing for built-ins,\nso anything the built-ins can do, yours can too.\n\n## The contract\n\nImplement `Connector` from `@cotal-ai/core` and self-register it on import:\n\n```ts\nimport { registry, type Connector } from "@cotal-ai/core";\n\nconst myConnector: Connector = {\n  kind: "connector",\n  name: "myagent",                       // the --agent value; must be unique, never "cotal"\n  requires: ["myagent"],                 // external CLIs the launch needs on PATH (preflighted)\n  buildLaunch(opts) {                    // opts \u2192 the process + env that joins the mesh\n    return {\n      command: "myagent",\n      args: ["--serve"],\n      env: { /* COTAL_* wiring from opts */ },\n    };\n  },\n  // optional: listModels, supportsModelVariant, supportsResume, eventChannel, pluginRoot\n};\n\nregistry.register(myConnector);          // runs on import \u2014 that\'s what makes it "plug in"\n```\n\n`buildLaunch(opts)` is the whole job: given a `LaunchOpts` (space, name, role, creds, channels,\nmodel, prompt\u2026), return a `LaunchSpec` (the command, args, and environment) whose process connects to\nthe broker as that mesh node. Everything else on the interface is optional and default-deny: declare\n`supportsModelVariant`/`supportsResume` only if you honor them (a request for one you don\'t declare\nfails loud before any provisioning), list `requires` so a missing CLI fails with a clear message, and\nimplement `listModels` only if you want a selector catalog. Implement `eventChannel` only if your\nsession publishes a structured event plane: it names the channel the manager grants that session\npublish rights on, so the grant and the subject the session publishes to come from one function\nrather than two that can drift, and `--events` refuses a connector that does not implement it. See\nthe `Connector` interface in\n[`packages/core/src/connector.ts`](../packages/core/src/connector.ts) and the OpenCode connector in\n[`extensions/connector-opencode/`](../extensions/connector-opencode/) for a complete worked example.\n\n## Packaging rules (enforced at `ext add`)\n\n`cotal ext add` verifies these and fails loud otherwise, because they are what keep every extension\nsharing the binary\'s single `@cotal-ai/core` registry instance:\n\n- **`@cotal-ai/core` is a `peerDependency`, never a regular dependency.** A regular dep vendors a\n  second copy of core, whose separate registry would swallow your `registry.register` call \u2014 the add\n  would import your package cleanly but see zero contributions and refuse it. Any other `@cotal-ai/*`\n  you use is a peer too. `ext add` junction-links each `@cotal-ai/*` peer to the binary\'s own copy;\n  lazy materialization verifies and rebinds those links for the registry-facing entry\'s initial import,\n  so global installs and source worktrees can share the machine extension prefix. Import every host peer\n  in that initial graph; launcher/child artifacts that run later must bundle their dependencies rather\n  than resolving a mutable host-peer link after another Cotal process may have rebound it.\n- **Bundle core as external.** If you bundle (esbuild/rollup), mark `@cotal-ai/core` (and any other\n  `@cotal-ai/*`) `--external` so the runtime `import` resolves the host\'s copy, not an inlined one.\n- **Importing the package must self-register.** Your entry (`main`/`exports`) must run\n  `registry.register(...)` as a side effect of import (e.g. `export * from "./extension.js"`), so the\n  lazy materialize path can bring you online without a bespoke hook.\n- **Name yourself.** The connector `name` is the `--agent` value; it must be unique across installed\n  extensions and must not be the reserved name `cotal`.\n\nA minimal `package.json`:\n\n```jsonc\n{\n  "name": "@you/cotal-connector-myagent",\n  "type": "module",\n  "main": "./dist/index.js",\n  "files": ["dist"],                     // whatever `ext add` needs to install + import\n  "peerDependencies": { "@cotal-ai/core": ">=0.1.0" }\n}\n```\n\n## Install, use, remove\n\n```bash\ncotal ext add @you/cotal-connector-myagent   # installs + verifies + caches its contribution\ncotal spawn --agent myagent                   # or `agent: myagent` in a manifest\ncotal ext remove @you/cotal-connector-myagent # gone; nothing static-imported it\n```\n\nSet `COTAL_DEFAULT_AGENT=myagent` to make it the default for a bare `cotal spawn`. Your connector\nresolves through the same lazy-materialize path as the built-ins (in the CLI\'s launch preflight and in\nthe manager), so a live `cotal up` will seed nothing extra: it imports your package, reads `requires`,\nand launches. For runtimes (how a node is hosted: pty/tmux/\u2026) rather than harnesses, the same\nextension model applies via the `Runtime` contract; see [define a team](define-a-team.md) and\n[the CLI reference](cli.md).\n'
     },
     {
       "slug": "build-a-client",
       "title": "Build a Cotal client",
       "kind": "Guide (informative)",
       "summary": "This page is the reading order for implementing a Cotal client in another language (Go, Python, Rust, or anything with a NATS client library) against the spec, without reimplementing the protocol.",
-      "body": "# Build a Cotal client\n\n> **Guide** (informative) \xB7 **For:** spec implementers \xB7 **Normative:** [SPEC](../SPEC.md). Where this guide and the spec disagree, the spec wins.\n\nThis page is the reading order for implementing a Cotal client in another language (Go,\nPython, Rust, or anything with a NATS client library) against the spec, without\nreimplementing the protocol.\n\n## What you are implementing\n\nCotal is two layers, and a client sits astride both:\n\n- **The transport-agnostic contract** ([SPEC \xA73](../SPEC.md#3-subject-layout) through\n  [\xA77](../SPEC.md#7-channels)): the subject layout, delivery modes, envelopes, presence, and\n  channels. This is the standard; it does not mention NATS.\n- **The NATS + JetStream binding** ([SPEC \xA78](../SPEC.md#8-nats--jetstream-binding) through\n  [\xA710](../SPEC.md#10-connection-and-onboarding)): how those abstractions map onto streams,\n  durables, KV, subject-scoped auth, and the join link. It is the only binding defined today.\n\nA client is a **thin layer over a NATS client library**: the library owns the connection,\nJetStream, and KV; your code owns subject construction and parsing, envelope validation, the\nreceive-side authenticity checks, and the presence/channel loops. See\n[transport.md](transport.md) for the split and the capabilities a binding must provide.\n\n## Prerequisites\n\n- A **NATS client library with JetStream + KV support** in your language (the official\n  `nats.go`, `nats.py`, `async-nats` for Rust, etc.).\n- A **local mesh to test against**. From this repo:\n\n  ```bash\n  cotal up                                   # broker + auth + control plane on 127.0.0.1:4222\n  cotal mint <name> --profile agent          # write an agent creds file to join with\n  ```\n\n  `cotal mint <name> --profile <agent|observer|admin>` also takes `--allow-subscribe a,b`\n  and `--allow-publish a,b` to scope the read/post ACLs, and `--out <path>`. The creds file\n  binds your principal (`owner.actor`, [SPEC \xA72](../SPEC.md#2-identity)) and your channel\n  grants; see\n  [identity-and-auth.md](identity-and-auth.md) and [run-a-mesh.md](run-a-mesh.md).\n  If your client will **receive** DMs or role anycasts (step 6), mint with `--provision`\n  (`--role <role>` for the anycast queue): the DM/task consumers are pre-created and\n  bind-only, and the command prints the lifecycle uid your client binds them under.\n\n## Build order\n\nEach step names what to build, the section that governs it, and how to watch it work against a\nlocal mesh. The [SPEC \xA712](../SPEC.md#12-conformance) conformance list is the checklist these\nmap to.\n\n1. **Identity + connection**: [SPEC \xA72](../SPEC.md#2-identity),\n   [\xA710](../SPEC.md#10-connection-and-onboarding),\n   [\xA713.12](../SPEC.md#1312-nats--jetstream-binding). Read the server version from the\n   **pre-auth INFO** and **fail loud below nats-server 2.12** (the v0.4 control surface relies\n   on 2.12 schedule/CAS semantics); treat a repeated pre-auth drop as a possible\n   oversized-CONNECT diagnostic, not an infinite retry loop. Then connect with the minted creds\n   and adopt the principal bound to the credential; set the inbox prefix to your connection's\n   reply inbox (`_INBOX_<connId>`) before any request, pull, or KV watch. *See it:* a wrong or missing cred is refused at connect, so a clean connect\n   confirms identity and creds are wired correctly.\n\n2. **Subject construction + parsing**: [SPEC \xA73](../SPEC.md#3-subject-layout). Build the three\n   messaging subject shapes plus the v0.4 endpoint control rails\n   ([\xA713.2](../SPEC.md#132-grammar)), and a parser that locates the sender principal (its two\n   adjacent owner + actor tokens) by kind (the sender-position asymmetry). *See it:* run the five subject-parsing vectors in\n   [SPEC \xA712](../SPEC.md#12-conformance) and match every result, including the malformed row.\n\n3. **Envelopes + schema validation**: [SPEC \xA75](../SPEC.md#5-envelopes). Emit and parse\n   `CotalMessage` with exactly one routing field set. *See it:* validate your encoder's output\n   against [`spec/cotal.schema.json`](../spec/cotal.schema.json) and the two sample messages in\n   [SPEC \xA712](../SPEC.md#12-conformance).\n\n4. **Presence heartbeat**: [SPEC \xA76](../SPEC.md#6-presence-and-discovery). Write your own\n   presence key on the heartbeat interval and derive peers' `offline` from stale timestamps and\n   KV deletes. From v0.4 your AgentCard MUST advertise `protocolVersion: \"0.4\"`, and in auth mode\n   your presence record MUST carry your `lifecycleUid` (\xA76; advisory for display, since authority\n   checks use the trusted lifecycle mapping, not presence); a peer that omits `protocolVersion`\n   reads as pre-0.4 and is not addressed on the control-surface rails\n   ([SPEC \xA76](../SPEC.md#6-presence-and-discovery),\n   [\xA713.11](../SPEC.md#1311-the-hard-cut)). *See it:* run [`cotal console`](watch-a-mesh.md) and watch your endpoint appear\n   in the roster and go stale when you stop heartbeating.\n\n5. **Multicast + channel join/replay**: [SPEC \xA77](../SPEC.md#7-channels). Publish to a concrete\n   channel; join by subscribing under your read ACL; on join, record the watermark, backfill\n   history if replay is on, and mark backfilled messages `historical`. *See it:* post from your\n   client and receive it on a reference peer (or `cotal console`); a late join replays with\n   `historical=true` and no live/backfill duplicates.\n\n6. **DM + anycast**: [SPEC \xA78](../SPEC.md#8-nats--jetstream-binding). Bind (do not create) your\n   `dm_<owner>-<actor>-<lifecycleUid>` and, if you hold a role, `svc_<role>` durable, and ack consumed copies. *See it:*\n   a reference peer unicasts to you and anycasts to your role; exactly one anycast consumer wins.\n\n7. **Receive-side checks**: [SPEC \xA74](../SPEC.md#4-delivery-modes),\n   [\xA75](../SPEC.md#5-envelopes), [\xA78](../SPEC.md#8-nats--jetstream-binding). Reject any message\n   whose `from.id` does not match the subject sender; derive the delivery kind\n   (channel/dm/anycast) from the subject, not payload fields; ack only after surfacing, and\n   terminate the permanent anomalies (`malformed-subject`, `sender-mismatch`, `malformed-json`)\n   instead of redelivering them.\n\n8. **Delivery classes + backstop tolerance**: [SPEC \xA74](../SPEC.md#4-delivery-modes),\n   [\xA77](../SPEC.md#7-channels). Resolve a channel's effective `live`/`durable` class from channel\n   config and use one resolution everywhere. On a `durable` channel, tolerate the at-most-once\n   `live` gap, catch up from the durable backstop, and deduplicate by `id` across the live,\n   backfill, and durable copies. If durable membership can't be established, report *joined live\n   with the backstop unestablished*, never *joined durable*. See\n   [delivery-daemon.md](delivery-daemon.md) and [presence-and-delivery.md](presence-and-delivery.md).\n\n## Testing conformance\n\n[SPEC \xA712](../SPEC.md#12-conformance) is the gate: its numbered list is the set of behaviors a\nconformant authenticated NATS client implements. Two artifacts there are language-agnostic and\nreusable directly:\n\n- The **subject-parsing table** and the **sample multicast/unicast messages**: fixed vectors\n  you can assert against.\n- [`spec/cotal.schema.json`](../spec/cotal.schema.json) (draft-07): validate every delivery\n  message you emit against it.\n\nThe end-to-end test is the **\xA712 interop scenario** run against a **local reference mesh**:\nprovision a space, connect two clients, exchange multicast/unicast/anycast, and check a late\njoiner's replay. The repository's own smoke suite (`packages/core/smoke/`, `bin/smoke/`) is\nTypeScript, driven through `tsx` and the reference endpoint; it is the reference\nimplementation's regression harness, **not** a cross-language conformance runner. So for a\nclient in another language, the interop scenario against a local `cotal up` mesh (with a\nreference agent as the other party; spawn one via [run-a-mesh.md](run-a-mesh.md) or\n[define-a-team.md](define-a-team.md)) is the current conformance test.\n\n## What not to build\n\n- **No transport abstraction layer.** There is one binding. Bind straight to your NATS client;\n  do not invent a pluggable transport interface. If you ever bind to a non-NATS substrate, the\n  capability contract in [transport.md](transport.md) is what you implement against, and you\n  supply durability and presence yourself, since a live-only pipe has neither.\n- **No orchestrator.** Cotal peers are lateral. A client connects, presents itself, and\n  exchanges messages; it does not schedule or supervise other agents. Spawning and supervision\n  live in separate tooling (the [manager](run-a-mesh.md), [mcp-tools.md](mcp-tools.md)), not in\n  the wire client.\n\nKeep it thin: a NATS client, subject build/parse, envelope validation, the receive-side checks,\nand the presence/channel loops. Everything else is the reference implementation's business, not\nthe protocol's.\n"
+      "body": "# Build a Cotal client\n\n> **Guide** (informative) \xB7 **For:** spec implementers \xB7 **Normative:** [SPEC](../SPEC.md). Where this guide and the spec disagree, the spec wins.\n\nThis page is the reading order for implementing a Cotal client in another language (Go,\nPython, Rust, or anything with a NATS client library) against the spec, without\nreimplementing the protocol.\n\n## What you are implementing\n\nCotal is two layers, and a client sits astride both:\n\n- **The transport-agnostic contract** ([SPEC \xA73](../SPEC.md#3-subject-layout) through\n  [\xA77](../SPEC.md#7-channels)): the subject layout, delivery modes, envelopes, presence, and\n  channels. This is the standard; it does not mention NATS.\n- **The NATS + JetStream binding** ([SPEC \xA78](../SPEC.md#8-nats--jetstream-binding) through\n  [\xA710](../SPEC.md#10-connection-and-onboarding)): how those abstractions map onto streams,\n  durables, KV, subject-scoped auth, and the join link. It is the only binding defined today.\n\nA client is a **thin layer over a NATS client library**: the library owns the connection,\nJetStream, and KV; your code owns subject construction and parsing, envelope validation, the\nreceive-side authenticity checks, and the presence/channel loops. See\n[transport.md](transport.md) for the split and the capabilities a binding must provide.\n\n## Prerequisites\n\n- A **NATS client library with JetStream + KV support** in your language (the official\n  `nats.go`, `nats.py`, `async-nats` for Rust, etc.).\n- A **local mesh to test against**. From this repo:\n\n  ```bash\n  cotal up                                   # broker + auth + control plane on 127.0.0.1:4222\n  cotal mint <name> --profile agent          # write an agent creds file to join with\n  ```\n\n  `cotal mint <name> --profile agent` also takes `--allow-subscribe a,b` and\n  `--allow-publish a,b` to scope the read/post ACLs, and `--out <path>`. Those two flags apply to\n  the **agent** profile only: `observer` and `admin` carry a fixed read set (`observer` reads the\n  whole chat plane) and `mint` refuses both flags there, so scope a reader with the agent profile. The creds file\n  binds your principal (`owner.actor`, [SPEC \xA72](../SPEC.md#2-identity)) and your channel\n  grants; see\n  [identity-and-auth.md](identity-and-auth.md) and [run-a-mesh.md](run-a-mesh.md).\n  If your client will **receive** DMs or role anycasts (step 6), mint with `--provision`\n  (`--role <role>` for the anycast queue): the DM/task consumers are pre-created and\n  bind-only, and the command prints the lifecycle uid your client binds them under.\n\n## Build order\n\nEach step names what to build, the section that governs it, and how to watch it work against a\nlocal mesh. The [SPEC \xA712](../SPEC.md#12-conformance) conformance list is the checklist these\nmap to.\n\n1. **Identity + connection**: [SPEC \xA72](../SPEC.md#2-identity),\n   [\xA710](../SPEC.md#10-connection-and-onboarding),\n   [\xA713.12](../SPEC.md#1312-nats--jetstream-binding). Read the server version from the\n   **pre-auth INFO** and **fail loud below nats-server 2.12** (the v0.4 control surface relies\n   on 2.12 schedule/CAS semantics); treat a repeated pre-auth drop as a possible\n   oversized-CONNECT diagnostic, not an infinite retry loop. Then connect with the minted creds\n   and adopt the principal bound to the credential; set the inbox prefix to your connection's\n   reply inbox (`_INBOX_<connId>`) before any request, pull, or KV watch. *See it:* a wrong or missing cred is refused at connect, so a clean connect\n   confirms identity and creds are wired correctly.\n\n2. **Subject construction + parsing**: [SPEC \xA73](../SPEC.md#3-subject-layout). Build the three\n   messaging subject shapes plus the v0.4 endpoint control rails\n   ([\xA713.2](../SPEC.md#132-grammar)), and a parser that locates the sender principal (its two\n   adjacent owner + actor tokens) by kind (the sender-position asymmetry). *See it:* run the five subject-parsing vectors in\n   [SPEC \xA712](../SPEC.md#12-conformance) and match every result, including the malformed row.\n\n3. **Envelopes + schema validation**: [SPEC \xA75](../SPEC.md#5-envelopes). Emit and parse\n   `CotalMessage` with exactly one routing field set. *See it:* validate your encoder's output\n   against [`spec/cotal.schema.json`](../spec/cotal.schema.json) and the two sample messages in\n   [SPEC \xA712](../SPEC.md#12-conformance).\n\n4. **Presence heartbeat**: [SPEC \xA76](../SPEC.md#6-presence-and-discovery). Write your own\n   presence key on the heartbeat interval and derive peers' `offline` from stale timestamps and\n   KV deletes. From v0.4 your AgentCard MUST advertise `protocolVersion: \"0.4\"`, and in auth mode\n   your presence record MUST carry your `lifecycleUid` (\xA76; advisory for display, since authority\n   checks use the trusted lifecycle mapping, not presence); a peer that omits `protocolVersion`\n   reads as pre-0.4 and is not addressed on the control-surface rails\n   ([SPEC \xA76](../SPEC.md#6-presence-and-discovery),\n   [\xA713.11](../SPEC.md#1311-the-hard-cut)). *See it:* run [`cotal console`](watch-a-mesh.md) and watch your endpoint appear\n   in the roster and go stale when you stop heartbeating.\n\n5. **Multicast + channel join/replay**: [SPEC \xA77](../SPEC.md#7-channels). Publish to a concrete\n   channel; join by subscribing under your read ACL; on join, record the watermark, backfill\n   history if replay is on, and mark backfilled messages `historical`. *See it:* post from your\n   client and receive it on a reference peer (or `cotal console`); a late join replays with\n   `historical=true` and no live/backfill duplicates.\n\n6. **DM + anycast**: [SPEC \xA78](../SPEC.md#8-nats--jetstream-binding). Bind (do not create) your\n   `dm_<owner>-<actor>-<lifecycleUid>` and, if you hold a role, `svc_<role>` durable, and ack consumed copies. *See it:*\n   a reference peer unicasts to you and anycasts to your role; exactly one anycast consumer wins.\n\n7. **Receive-side checks**: [SPEC \xA74](../SPEC.md#4-delivery-modes),\n   [\xA75](../SPEC.md#5-envelopes), [\xA78](../SPEC.md#8-nats--jetstream-binding). Reject any message\n   whose `from.id` does not match the subject sender; derive the delivery kind\n   (channel/dm/anycast) from the subject, not payload fields; ack only after surfacing, and\n   terminate the permanent anomalies (`malformed-subject`, `sender-mismatch`, `malformed-json`)\n   instead of redelivering them.\n\n8. **Delivery classes + backstop tolerance**: [SPEC \xA74](../SPEC.md#4-delivery-modes),\n   [\xA77](../SPEC.md#7-channels). Resolve a channel's effective `live`/`durable` class from channel\n   config and use one resolution everywhere. On a `durable` channel, tolerate the at-most-once\n   `live` gap, catch up from the durable backstop, and deduplicate by `id` across the live,\n   backfill, and durable copies. If durable membership can't be established, report *joined live\n   with the backstop unestablished*, never *joined durable*. See\n   [delivery-daemon.md](delivery-daemon.md) and [presence-and-delivery.md](presence-and-delivery.md).\n\n## Testing conformance\n\n[SPEC \xA712](../SPEC.md#12-conformance) is the gate: its numbered list is the set of behaviors a\nconformant authenticated NATS client implements. Two artifacts there are language-agnostic and\nreusable directly:\n\n- The **subject-parsing table** and the **sample multicast/unicast messages**: fixed vectors\n  you can assert against.\n- [`spec/cotal.schema.json`](../spec/cotal.schema.json) (draft-07): validate every delivery\n  message you emit against it.\n\nThe end-to-end test is the **\xA712 interop scenario** run against a **local reference mesh**:\nprovision a space, connect two clients, exchange multicast/unicast/anycast, and check a late\njoiner's replay. The repository's own smoke suite (`packages/core/smoke/`, `bin/smoke/`) is\nTypeScript, driven through `tsx` and the reference endpoint; it is the reference\nimplementation's regression harness, **not** a cross-language conformance runner. So for a\nclient in another language, the interop scenario against a local `cotal up` mesh (with a\nreference agent as the other party; spawn one via [run-a-mesh.md](run-a-mesh.md) or\n[define-a-team.md](define-a-team.md)) is the current conformance test.\n\n## What not to build\n\n- **No transport abstraction layer.** There is one binding. Bind straight to your NATS client;\n  do not invent a pluggable transport interface. If you ever bind to a non-NATS substrate, the\n  capability contract in [transport.md](transport.md) is what you implement against, and you\n  supply durability and presence yourself, since a live-only pipe has neither.\n- **No orchestrator.** Cotal peers are lateral. A client connects, presents itself, and\n  exchanges messages; it does not schedule or supervise other agents. Spawning and supervision\n  live in separate tooling (the [manager](run-a-mesh.md), [mcp-tools.md](mcp-tools.md)), not in\n  the wire client.\n\nKeep it thin: a NATS client, subject build/parse, envelope validation, the receive-side checks,\nand the presence/channel loops. Everything else is the reference implementation's business, not\nthe protocol's.\n"
     },
     {
       "slug": "cli",
       "title": "`cotal` CLI reference",
       "kind": "Reference: describes the TypeScript reference implementation (the `cotal` CLI), not the wire contract.",
       "summary": "cotal is the operator command line for the reference implementation: bring a mesh up, mint identities, launch agents, watch what they do, and tear it all down.",
-      "body": "# `cotal` CLI reference\n\n> **Reference**: describes the TypeScript reference implementation (the `cotal` CLI), not the wire contract. \xB7 **For:** operators \xB7 **Wire contract:** [SPEC](../SPEC.md)\n\n`cotal` is the operator command line for the reference implementation: bring a mesh up, mint\nidentities, launch agents, watch what they do, and tear it all down. It is a thin client over the\nwire contract: the normative subjects and schemas live in the [SPEC](../SPEC.md); this page is\nlookup material for the commands, not a walkthrough; if you are new, start with\n[Getting started](getting-started.md).\n\n## Running it\n\n```bash\nnpm install -g cotal-ai   # puts `cotal` on your PATH (needs Node 22+)\ncotal --help              # every command, grouped\ncotal --version           # cotal-ai version + each installed extension's (also `cotal -v`)\ncotal <command> --help    # one command's flags and usage\n```\n\n`npx cotal-ai <command>` runs it without a global install; in a dev clone, `pnpm cotal <command>`\nruns it through `tsx` with no build step. Bare `cotal` prints help. Every command generates its own\n`--help`, usage, and shell completion from its declared flags.\n\nCommands come from the surfaces the binary composes: the base mesh CLI, the manager\n(`supervise`), and the delivery daemon (`deliver`), plus any operator-installed extensions.\n`cotal ext add <npm-package>` installs any registry providers a package contributes: commands,\nruntimes, and local process lifecycle descriptors. The `web` dashboard and optional manager\nruntimes ship this way.\n\n## Commands\n\n| Area | Command | Purpose |\n|---|---|---|\n| Set up & lifecycle | [`setup`](#setup) | Guided, configure-only setup (installs, seeds personas; launches nothing) |\n| Set up & lifecycle | [`update`](#update) | Reconcile first-party extensions and check or opt into a coherent CLI upgrade |\n| Set up & lifecycle | [`up`](#up) | Start a local mesh (nats-server + JetStream), or boot a whole manifest with `-f` |\n| Set up & lifecycle | [`down`](#down) | Stop the whole stack, selected registered components, or a manifest deploy |\n| Set up & lifecycle | [`backup`](#backup-and-restore) | Create an offline full-space or registry-only artifact from a preserved cut |\n| Set up & lifecycle | [`clean`](#clean) | Configurable cleanup: purge history (live), or wipe the local store / identity (stopped) |\n| Set up & lifecycle | [`meshes`](#meshes-use-status) | List the running meshes on this machine |\n| Set up & lifecycle | [`use`](#meshes-use-status) | Set the default mesh a bare `cotal spawn` joins |\n| Set up & lifecycle | [`status`](#meshes-use-status) | Read-only diagnostics for setup, processes, and the selected mesh |\n| Agents & personas | [`spawn`](#spawn) | Launch an agent from a persona (foreground, or `--detach` via the manager) |\n| Agents & personas | [`models`](#models) | List connector model catalogs and variants from the manager |\n| Agents & personas | [`ps`](#ps-stop-attach) | List managed agents and their mesh status |\n| Agents & personas | [`stop`](#ps-stop-attach) | Ask the manager to stop a managed agent |\n| Agents & personas | [`attach`](#ps-stop-attach) | Stream and drive a managed agent's terminal (pty runtime) |\n| Agents & personas | [`input`](#input) | Type one line into a managed agent's terminal without attaching |\n| Agents & personas | [`personas`](#personas) | List, show, edit, create, or remove local personas |\n| Agents & personas | [`supervise`](#supervise) | Run a manager daemon (the agent supervisor / control plane) |\n| Agents & personas | [`runtimes`](#runtimes) | List the agent runtimes the manager can spawn through and whether each is reachable |\n| Agents & personas | [`reconcile-gate`](#reconcile-gate) | Unfreeze an issuance gate left frozen by a crashed manager restart, after verifying the holder is gone |\n| Messaging & watching | [`endpoints`](#endpoints) | List every endpoint in the live presence roster, including infrastructure |\n| Messaging & watching | [`describe` / `invoke`](#describe-invoke) | Resolve a v0.4 service's command surface off the wire; invoke one command by name |\n| Messaging & watching | [`send`](#send) | Send one message, then exit: DM a peer, post a channel, or ask a role |\n| Messaging & watching | [`channels`](#channels) | Inspect or set the channel registry |\n| Messaging & watching | [`history`](#history) | Clear retained message history |\n| Messaging & watching | [`console`](#console) | Live protocol view for a space (TUI, or `--plain` line stream) |\n| Messaging & watching | [`web`](#web) | Browser dashboard (installed as the `@cotal-ai/web` extension) |\n| Auth & meshes | [`mint`](#mint) | Mint a creds file for a space (static auth mode) |\n| Auth & meshes | [`login`](#login-logout) | Sign in to a per-user-auth mesh's IdP (once per machine) |\n| Auth & meshes | [`logout`](#login-logout) | Revoke the IdP session and clear the cached login |\n| Auth & meshes | [`actor`](#actor) | Manage a user-auth space's actor ledger (grant / revoke / list) |\n| Auth & meshes | [`doctor`](#doctor) | Credential-health diagnosis and repair (`doctor auth`) |\n| Auth & meshes | [`join`](#join) | Join a space as your own presence (interactive) |\n| Manifest | [`topology`](#manifest-deploys) | Validate and view a mesh manifest's access graph (read-only) |\n| Extensions & misc | [`ext`](#ext) | Install / remove operator CLI extensions |\n| Extensions & misc | [`completion`](#completion) | Print or install shell completion |\n| Extensions & misc | [`feedback`](#feedback) | Send feedback to the Cotal developers |\n| Extensions & misc | [`deliver`](#server-daemons) | Run the server-side Plane-3 delivery daemon |\n| Extensions & misc | [`feedback-intake`](#server-daemons) | Run a self-hosted feedback intake server |\n\nThe manifest modes of `up`, `spawn`, and `down` (`-f <cotal.yaml>`) plus `topology` are covered\ntogether under [Manifest deploys](#manifest-deploys).\n\n## setup\n\n```bash\ncotal setup [--full] [--demo] [--yes]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--full` | off | Redo the full guided flow (implies `--demo`) |\n| `--demo` | off | Also seed the guided expert team (`david`, `sven`, `me`) |\n| `--yes`, `-y` | off | Non-interactive accept-all (for agents / CI) |\n\nGuided setup is **configure-only**: it checks prerequisites, installs the Claude Code plugin, and\nseeds persona files, and it launches nothing (no mesh, no web, no manager). First run gets the\nnarrated flow; later runs print a status card. By default it seeds one `default` persona; the\n`david`/`sven`/`me` team is opt-in via `--demo`. See [Getting started](getting-started.md) and, for\nmaintainers, [setup internals](setup-internals.md).\n\n## update\n\n```bash\ncotal update [--self]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--self` | off | If a newer release exists, install that exact validated `cotal-ai` version globally and reconcile through the newly installed binary |\n\nWithout `--self`, `update` keeps the installed first-party surfaces coherent with the running\nbinary: it force-reconciles the four built-in connectors, then reinstalls other `@cotal-ai/*`\noperator extensions at the binary's exact version. Each extension runs in an isolated child, so one\nfailure cannot poison later replays. It then checks npm; a newer binary is an informational notice\nwith `cotal update --self` as the next command, not an automatic install.\n\nWith `--self`, the npm check happens first. When a newer release exists, Cotal installs the exact\nversion it validated, resolves and verifies that package in npm's global root, then launches that\nbinary to reconcile connectors and first-party extensions to the new generation. An npx or dev-clone\ninvocation therefore installs and continues through a separate global copy; it never claims the\nalready-running process changed. If the binary is current, `--self` performs the normal local\nreconcile without reinstalling it.\n\nThird-party extensions are listed with their installed version and recorded spec but are not\nauto-updated in v1. Floating third-party updates require `@cotal-ai/*` peer-range validation and are\na future follow-up. A failed connector/extension install, npm metadata check, or requested global\ninstall is reported and makes the command exit nonzero. Independent extension attempts continue so\nthe output includes every failure; an unavailable npm registry does not undo a completed local\nreconcile, but the command still exits nonzero because it could not establish that the install is\ncurrent.\n\n## up\n\n```bash\ncotal up [--detach] [--open] [--space <s>] [--server <url>] [--channels <path>] [--runtime <name>]\ncotal up --tls-cert <cert.pem> --tls-key <key.pem>   # serve TLS (both, or neither)\ncotal up --restore <dir> [--restore-only registry] [--accept-missing-source]\ncotal up -f <cotal.yaml> [--dry-run] [--runtime <name>]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--server <url>` | auto (free local port) | Listen URL override |\n| `--host <host>` | \u2014 | Bind host override. With no `--server`, the broker URL is derived from it, so `--host <addr>` alone is enough to make a mesh reachable at that address; a `--host`/`--server` pair naming different addresses is refused. A wildcard bind (`0.0.0.0`, `::`) keeps a dialable loopback URL. Recorded on the mesh and reused by every later manager launch, so a repair or resume keeps remote [`attach`](#ps-stop-attach) working |\n| `--space <s>` | the folder's name | Space name |\n| `--store-dir <dir>` | \u2014 | JetStream store directory |\n| `--channels <path>` | `.cotal/channels.json` if present | Channel-registry seed file (JSON). An explicit path that is missing is an error |\n| `--restore <dir>` | \u2014 | Restore a completed offline backup before exposing the normal listener |\n| `--restore-only registry` | artifact selection | Restore only the registry component |\n| `--accept-missing-source` | off | Explicit disaster consent when the inode-bound preserved source is absent |\n| `--open` | off (auth) | Unauthenticated dev mesh: no JWT, no ACLs |\n| `--user-auth` | off | Per-user auth: people `cotal login`; connects are authorized against the actor ledger |\n| `--idp <url>` | \u2014 | With `--user-auth`: the IdP auth base URL to pin on first enable |\n| `--detach` | off | Run in the background (stop with `cotal down`) |\n| `--tls-cert <path>` | \u2014 | PEM certificate to serve TLS with. Must be given together with `--tls-key`. The pair is validated **before** the broker starts \u2014 readability, private-key mode, that the two match, the validity window, and that the certificate covers the host clients will dial \u2014 because `nats-server` starts happily on an expired certificate and only the client then fails. The decision is recorded, so a later bare `cotal up` after a `cotal down` keeps serving TLS rather than silently reverting to cleartext |\n| `--tls-key <path>` | \u2014 | PEM private key for `--tls-cert`. Refused if group- or other-readable (tighten to `600`) |\n| `--file <cotal.yaml>`, `-f` | \u2014 | Launch a whole mesh from a manifest |\n| `--dry-run` | off | With `-f`: print the plan, mutate nothing |\n| `--runtime <name>` | `pty` (or the manifest's, with `-f`) | Agent runtime for the mesh manager (`pty` built in; others are installed extensions, explicit-only). Resolved + probed before the broker starts; an uninstalled/unreachable runtime fails loud. With `-f`, overrides the manifest's runtime |\n| `--rotate-sys` | off | Rotate the space's system account and re-mint its two `$SYS` creds. Needs a stopped mesh; refused with `--open` |\n\n`cotal up` boots a local nats-server with JetStream and, in auth mode (the default), JWT auth and\nper-agent ACLs; `--detach` records the mesh so `cotal spawn` from any directory can find it. With no\n`--server`, it auto-selects a free port if the default address is taken; an explicit `--server`\nstays fail-loud on collision. `--detach` also brings up the control plane (delivery daemon in auth\nmode, then the manager). The `-f` form is a [manifest deploy](#manifest-deploys); see\n[Run a mesh](run-a-mesh.md).\n\n`--user-auth --idp <url>` starts the space's auth service alongside the broker (the NATS\nauth callout plus the loopback token exchange); it is torn down with `cotal down`, and a\nre-run of `cotal up` heals a dead service on a running broker. `--user-auth` and `--open`\ncontradict each other and are refused loudly; a running broker cannot change auth mode\nwithout a `cotal down` first. See [identity & auth](identity-and-auth.md).\n\n`--rotate-sys` renews the two `$SYS` credentials (`membership-observer`, `connection-evictor`).\nThey carry a 30-day expiry and nothing re-signs them in place, because the system-account seed is\nnever persisted, so they are renewed by issuing a **new system account** under the same broker\noperator and minting fresh creds against it. A plain re-`up` does **not** do this: it reuses the\nexisting trust record, and its `$SYS` creds along with it.\n\nThe rotation is safe to run on a real space, with one operational cost. The data account, the account\nsigning key, every agent credential minted from it, and the JetStream store are all untouched; what\ndies is the retired system account, and with it any out-of-band copy of the old `$SYS` creds, on every\nbroker that loads the rotated config. The cost is that **earlier full backups stop being restorable**\n(see below), so this is not a no-consequence operation. It needs the broker to restart on the rewritten\nconfig, so it runs as part of a boot:\n\n```bash\ncotal down\ncotal up --rotate-sys --detach     # agents reconnect; nothing is re-provisioned\ncotal doctor auth                  # both $SYS creds healthy again, 30 days out\n```\n\nA rotation is a stopped, fresh boot, and anything that is not one refuses it, all for the same reason\n(the on-disk material and the broker it runs on must never end up on different generations):\n\n- a live mesh, because the running broker would keep serving the retired account;\n- an open mesh, whether that comes from `--open` or from `broker.auth: false` in a manifest, which\n  has no system account at all;\n- `--restore`, because reinstating a trust root and superseding it in one command leaves no way to\n  say which authority the mesh came up on;\n- an unfinished restore or resume attempt on this root, including one `cotal up` would recover on\n  its own, because those paths can adopt a live listener and return without booting a broker;\n- a root that hosts more than one space, because the system account lives in the shared broker\n  record and a rotation would retire every tenant's, while the root holds one `$SYS` cred pair\n  pinned to one data account.\n\nTwo things to know before you run it:\n\n- **The retirement is config-load-bound.** Old `$SYS` creds are refused by any broker that loads the\n  rotated config. A stale `nats-server` still running the *previous* config in memory would keep\n  honouring them, so stop every broker for this root first. `--rotate-sys` refuses if this root's\n  mesh is recorded as running, if anything unidentified is answering at the address it was given, or\n  if the root's pid file names a live (or unreadable) process. Those are Cotal's own ownership\n  records, not a scan of the process table: a `nats-server` you started by hand against this root's\n  `server.conf` on some other port writes none of them and will not be seen. Do not run one.\n- **It invalidates earlier full backups.** A full artifact binds to the trust chain it was taken\n  against, and that commitment covers the operator JWT and the system account. Every full backup\n  taken before a rotation refuses to restore afterwards, so take a fresh `cotal backup` once the\n  rotated mesh is up. `cotal up --restore` names this case when the data account still matches.\n\nThe commit is not atomic (a trust-record write plus two credential writes), so an interrupted\nrotation leaves the record ahead of the creds. That split is detected rather than silent: every\n`cotal up` on an auth mesh, and every `cotal doctor auth`, compares each `$SYS` cred's issuer against\nthe persisted record and names the retired account. `up` warns rather than refusing, because these\ncreds power the membership graph and live eviction, both of which degrade fail-soft; the mesh is not\nworth taking down over them. Re-running the rotation heals it, at the cost of one generation.\n\nWhile those creds are expired the mesh keeps delivering messages, but the\n[membership feed](delivery-daemon.md) and live connection eviction stay down; `cotal doctor auth`\nand the manager's log both name the credential and this repair.\n\n## down\n\n```bash\ncotal down\ncotal down --preserve-state [--store-dir <dir>]\ncotal down manager [delivery auth web nats ...]\ncotal down web [--space <name>]\ncotal down -f <cotal.yaml> | --run <id> [--dry-run]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--file <cotal.yaml>`, `-f` | \u2014 | Tear down this manifest's deploy |\n| `--run <id>` | \u2014 | Tear down one `spawn -f` run by id |\n| `--space <name>` | current mesh | With components: the mesh whose target-addressed components (e.g. `web`) to stop |\n| `--dry-run` | off | Print the manifest teardown or selected components, mutate nothing |\n| `--preserve-state` | off | Bare whole stack only: fence the manager, retain principals and durable state, stop and prove the stack down, then publish `ready` |\n| `--store-dir <dir>` | `.cotal/nats` | With `--preserve-state`: the actual store path (required for a custom store) |\n\nBare `cotal down` stops the whole local stack in dependency order. Positional component names stop\nonly those self-registered local processes; for example, `cotal down manager` leaves delivery and\nthe broker running, and `cotal down web` is available when the web extension is installed. A\ncomponent that starts target-resolved (the web dashboard) is stopped the same way: `cotal down web`\nresolves the mesh exactly like `cotal web` (registry current mesh first, `--space` to name one), so\nit works from any directory; the other components always stop under the folder you run it in. The\n`-f` / `--run` forms tear down a [manifest deploy](#manifest-deploys) without stopping the whole mesh\nand cannot be combined with component names. Stopping `nats` alone is refused while an unselected\nregistered daemon is still live; include those components or use bare `cotal down`.\n\nNormal `down` remains destructive at the logical identity/durable layer. `--preserve-state` is a\ndifferent maintenance transition: it suppresses leave/deprovision cleanup, persists the manager's\nsame-principal resume inventory, stops the entire stack without removing run/auth artifacts, and\npublishes a stable inode-bound cut only after every recorded process is proven stopped and the exact\nrecorded NATS endpoint is unreachable. A missing or stale broker pidfile never counts as stopped. The\nattempt is bound durably before the manager is fenced, the resume document and attempt-bound\n`cut-intent` are fsynced before manager commit, and the manager's commitment itself is journaled\n(`cut-committed`) before any process stops. A retry after a crash at any of those boundaries reuses\nthe exact recorded attempt and finishes the remaining stop and endpoint proofs idempotently, without\nneeding the (by then intentionally dead) manager. A partial cut never publishes `ready`. It cannot\nbe combined with component names, manifest teardown, or `--dry-run`.\n\n## clean\n\n```bash\ncotal clean <history|store|all> --force\ncotal clean restore-attempt --attempt <id> --force\ncotal clean restore-fallback --attempt <id> --force\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` / `--server <url>` / `--creds <path>` | resolved mesh | `history`: target mesh |\n| `--dms` | off | `history`: also clear DM history |\n| `--store-dir <dir>` | `.cotal/nats` | `store`/`all`: JetStream store directory |\n| `--force` | \u2014 | Required: destructive, no prompting |\n| `--attempt <id>` | \u2014 | `restore-attempt`: exact stale pre-commit attempt; `restore-fallback`: matching healthy committed restore |\n\nOne configurable cleanup verb; every target requires `--force`.\n\n- `history` purges the retained message backlog on the **running** broker (channels, plus DMs\n  with `--dms`). The same operation as [`history clear`](#history), which stays as an alias.\n- `store` deletes the **stopped** mesh's JetStream store (`.cotal/nats`): streams, durable\n  consumers, and messages. This is the reset for stale on-disk broker state, e.g. durables\n  minted by an older, incompatible Cotal generation surviving a `down`/`up` cycle.\n- `all` is `store` plus the space identity (`.cotal/auth`), the local creds and markers tied to\n  it, any crash residue a normal `down` would have swept (stale pidfiles, `run/`), and the mesh's\n  registry entry; the next `cotal up` mints a fresh identity.\n\n`history` needs the mesh up; `store` and `all` refuse while any recorded mesh process is still\nalive or any same-root recorded broker endpoint remains reachable (run `cotal down` first). They\nalso refuse outright on a root that holds accounts for several spaces: the store and the broker\ntrust record are shared by every space on the broker, so both targets would take out all of them\nand no `--space` can narrow that. `down`, `backup` and `up --restore` refuse there for the same\nreason. `cotal status` lists the tenants on such a root. Personas\n(`.cotal/agents`) and logs are never touched. A custom\nstore location is not recorded anywhere, so `--store-dir` must repeat whatever the mesh was\nlaunched with. Custom cleanup targets must contain either the Cotal store-generation marker or a\nreal `jetstream/` store directory; filesystem roots, project roots, and Cotal auth/maintenance trees\nare always refused.\n\n`store` and `all` also refuse every maintenance journal state. After a healthy committed restore,\n`restore-fallback` is the only supported way to remove the recorded unchanged old-store inode; it\nnever deletes the active target, requires both the exact attempt id and `--force`, and retires the\ncompleted restore journal so a later `down --preserve-state` can start a new backup cycle.\n\n## backup and restore\n\n```bash\ncotal down --preserve-state [--store-dir <dir>]\ncotal backup create <dir> [--only full|registry] [--store-dir <dir>]\ncotal up --restore <dir> [--restore-only registry] [--accept-missing-source]\n```\n\nBackup is offline-only. It requires the stable `ready` record from `down --preserve-state`, an exact\nstore match, no live recorded process, and an unreachable exact endpoint from the recorded cut.\nThat endpoint is probed immediately before cloning, so a live broker with a missing or stale pidfile\nis still refused. It claims the cut, reflink/copies the stopped source to a\nprivate attempt clone, and opens only that clone on a random loopback bootstrap broker with an\nindependent parent/deadline watchdog. It validates the canonical stream and pull-consumer inventory,\nwrites native snapshots with consumers excluded, and stores conservative contiguous ACK-floor\ncheckpoints separately. The original store is never opened by the backup broker, and the stack is\nnot restarted implicitly. Artifact destinations must not overlap the preserved source or maintenance\nattempt tree. Restore artifacts and targets likewise cannot nest inside or contain each other, the\npreserved source, or the maintenance attempt tree.\n\n`full` is the default and indivisible: channel registry, CHAT/DM/TASK/INBOX/DLV, ACL, MEMBERS, and\nvalidated durable checkpoints. `registry` is the sole partial artifact. Presence, derived membership\nfeed, leases, native ephemeral/history consumers, credentials, keys, tokens, owner secrets, and actor\nledger files are excluded. Artifacts are exclusively created `0700`; snapshot/checkpoint files and\nthe manifest are `0600`; `manifest.json` is written last with exact sizes and SHA-256 values. The\ndirectory is trusted operator input: hashes detect corruption, not malicious rewriting.\n\nRestore validates and stages the exact allowlisted artifact bytes before moving or creating a store.\nIt requires the same space and existing trust state. The whole pre-commit window holds a journaled\nliveness claim (coordinator, watchdogs, brokers, absolute deadline): ordinary `up` and a repeated\n`up --restore` refuse while the claim is live, and a stale attempt is recovered only after the\ndeadline has elapsed and every recorded owner is proven dead \u2014 automatically by a retried\n`up --restore`, or explicitly with `cotal clean restore-attempt --attempt <id> --force`. Nothing\never rolls back a live attempt. A registry-only artifact restores as registry-only whether or not\n`--restore-only registry` is passed; omitted infrastructure is always created and the exact\npost-restore stream inventory is asserted before commit intent. Ordinary `up` from a preserved cut\nresumes only the exact recorded source store and runtime; a contradicting `--store-dir` or\n`--runtime` fails in preflight. Authenticated restores validate the complete\nspace trust bundle before staging, including nkeys, seed matches, JWTs, signers, and space binding;\nfull restores commit to the validated operator, system-account, data-account, and active-signer root\nchain in addition to the static/user authority fingerprint. Because the system account is part of that\ncommitment, a [`cotal up --rotate-sys`](#up) makes every full artifact taken before it unrestorable\nagainst this root: take a fresh full backup after each rotation. The composed commitment is revalidated\nimmediately before store mutation and never includes secret seeds. Restore never creates fresh auth.\nSame-path restores atomically retain the old\nsource at the journaled fallback path; alternate targets retain it in place; a missing canonical\nsource needs explicit `--accept-missing-source`. Quarantine and target restores use current canonical\nconfigs on isolated random-loopback brokers, never expose native snapshot consumers, and publish a\ncommit-intent immediately before the normal listener starts. Archive bytes never instantiate the real\ntarget: after quarantine validation, every stream is re-snapshotted from the validated quarantine\nstate into attempt-owned sanitized files, and the target is restored solely from those. Before that boundary, failure rolls back\nthe attempt-owned target; after it, ambiguity preserves both stores and records forward-repair\nrecourse. The cooperative maintenance lock excludes Cotal commands, not arbitrary raw NATS processes.\n\nBootstrap brokers in every auth mode \u2014 including open \u2014 mount the store under a local account with\nrandom operation-specific logins only, each carrying the exact per-phase subject permission matrix;\nnormal static credentials and user-auth sentinel/bearer connections are rejected, and no auth\nservice or callout starts. Open mode differs only in its account label, never in authority. Inventory, each stream snapshot,\nrestore initiation, exact upload id, validation, and each checkpoint recreation use separate exact\nauthorities. Every checkpoint carries the source stream's message/first/last sequence state and must\nmatch its snapshot record before mutation; core then derives and validates the only allowed start\npolicy. TASK is not a CLI exception: the same core checkpoint API recreates its canonical `DeliverAll`\nWorkQueue durable because acknowledged tasks are absent from retention and NATS forbids a\nstart-sequence policy there. Registry-only restore creates every omitted canonical stream and transient\nbucket on the isolated target before the normal listener is exposed. It deliberately does not resume\nretained agents or recreate their DM/DLV/TASK/ACL state; their identity material stays retained and\nstopped rather than being reprovisioned into a partial restore.\n\nAfter listener readiness, the manager starts attempt-bound, validates retained credentials/tokens\nwithout granting or reprovisioning, and resumes the exact persisted principals under cleanup\nsuppression. Registry-only restore uses the same flow with an empty agent set. `commitResume` is an\nidempotent validation barrier only: success must be `awaitingFinalize` with an attempt-bound 64-hex\ncommit token and does not release suppression. Under the workspace lock, the CLI first fsyncs that\nexact evidence as `manager-committed` (restore) or `resume-committed` (ordinary resume), then calls\ntoken-bound `finalizeResume`; only an `active` response for the exact token releases suppression. The\nCLI records the same token in finalization evidence before a restore becomes `active`, or before an\nordinary resume retires and consumes the marker. Re-entry from either committed state skips the prior\nidempotent activation/commit phases, retries finalization with the durable token, and finishes the\nworkspace transition. Failure before finalization preserves the committed state and cleanup\nsuppression; it is not rewritten through a degraded transition. Re-entry between any two earlier\nboundaries reuses the same attempt and may retry the idempotent phases without deleting retained state. A missing or\nchanged per-agent dependency is a named fail-closed result; the journal becomes degraded and remains\navailable for forward repair. A retry from `resume-intent`,\n`resume-active`, or `resume-degraded` reuses the same attempt and inventory after the prior listener is\nproven stopped. Every normal restore listener has an unguessable attempt-bound NATS server name. The\nCLI fsyncs its exact name/nonce, canonical endpoint, process owner, and generation-bound target identity\nimmediately after spawn. Re-entry accepts a surviving listener only when its INFO server name, live PID\nrecord, endpoint, and target identity all match that proof; degraded restore repair then moves through\nthe guarded workspace transition only after manager commit. If an uncommitted bound owner is provably\ndead, recovery retires that exact proof under the maintenance lock and binds a fresh listener for the\nsame attempt, endpoint, and target with a new nonce and server name. A live foreign/mismatched listener\nor ambiguous owner is preserved and refused, never adopted by reachability alone. A reconstructed\ncommit/degraded attempt without either the exact bound proof or a durable dead-listener replacement\nrecord fails closed even when the recorded port is free. A later ordinary startup may pass an `active`\nrestore only when its details prove manager commit and its exact recorded listener is dead.\n\n## meshes, use, status\n\n```bash\ncotal meshes\ncotal meshes add                      # guided, on a terminal\ncotal meshes add <space> --server <url> [--root <dir>] [--mode auth|open] [--force]\ncotal meshes rm <space> [<space> \u2026] [--force]\ncotal use <space>\ncotal status [--space <s>] [--server <url>]\n```\n\n`meshes` lists the meshes this machine knows; a `*` marks the `current` default a bare\n`cotal spawn` joins.\n\nRun on a terminal with the space or `--server` missing, **`meshes add` is guided**: it asks for the\none thing that cannot be derived (the broker URL), probes it, and tells you what answered - open or\nrequiring credentials. It then offers the spaces your `--root` already holds credentials for, states\nthe mode as a fact about that broker rather than asking, and shows the exact record before writing\nanything. A broker that does not answer, or a space name already registered, becomes a choice rather\nthan an error. Anything you pass on the command line is taken as given and not asked again. Without\na terminal - a script, an agent, CI - nothing prompts and the flag form's errors stand\n(`COTAL_NO_PROMPT=1` forces that too).\n\n`cotal up` and `cotal down` maintain their own records. `meshes add` registers a mesh they cannot\nspeak for: one running on another machine, a shared broker, a hosted space. `--root` is the folder\nwhose `.cotal/auth` holds that mesh's credentials and whose `.cotal/agents` holds its personas\n(default: the project you run it in) \u2014 the registry stores that path, never a secret. `--mode`\ndefaults to `auth` when the root holds the space's account record and to `open` otherwise; a\nuser-auth space cannot be registered by hand, because its IdP pins are trust that only\n`cotal up --user-auth` establishes. The broker is probed before anything is recorded, so a wrong\naddress, or credentials that mesh will not accept, fails here instead of at the first `spawn`;\n`--force` records without verifying (and replaces an existing record).\n\n`meshes rm` drops records \u2014 it never stops a mesh. For a mesh running on this machine `cotal down`\nis the right verb, and `rm` says so unless you pass `--force`. A record you added by hand is only\nremoved by something that names it \u2014 `meshes rm`, or an `add --force` replacement \u2014 or by a\n`cotal up` that actually starts the broker for that same space, server and root, which becomes that\nmesh and so takes the record over (a `cotal up` for that space anywhere else refuses instead).\nNothing that merely *infers* a record is stale touches it: an\nunreachable broker is listed `offline` and stays, and `cotal down` / `cotal clean all` leave it\nalone even when it shares a root with the project they are tearing down, because nothing on this\nmachine could write it back.\n\n`use <space>` sets that default; the selection applies from every directory,\nincluding inside another mesh's project. `status` is a read-only report: machine prerequisites\n(starting with the installed `cotal-ai` version), the installed extensions and their versions, this\nfolder's `.cotal/`, the recorded meshes, and a live snapshot of the selected mesh (roster, channels,\nmembership feed). `status` takes only `--space` / `--server` to pick the mesh to inspect; it starts\nnothing.\n\n## spawn\n\n```bash\ncotal spawn [<persona>] [--detach] [--name <n>] [--agent <a>] [--model <m>] [--variant <v>] [--prompt <text>] [--cwd <dir>]\ncotal spawn -f <cotal.yaml> [--dry-run]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` | resolved mesh | Target space |\n| `--server <url>` | registry entry | Broker URL override |\n| `--creds <path>` | \u2014 | Control-caller creds for an off-registry manager (`--detach` only) |\n| `--name <n>` | persona's `name:` | Presence-name override (does not choose the persona) |\n| `--config <persona-or-path>` | \u2014 | Persona catalog name or file path; wins over the positional |\n| `--agent <a>` | `COTAL_DEFAULT_AGENT`, else `claude` | Connector type (`claude`, `opencode`, `hermes`, \u2026) |\n| `--role <r>` | persona's `role:` | Role override |\n| `--model <m>` | persona's `model:` | Model override |\n| `--variant <v>` | persona's `variant:` | Model variant override (connector-defined; e.g. OpenCode reasoning tiers) |\n| `--cwd <dir>` | this cwd | Working directory to root the agent at |\n| `--prompt <text>` | \u2014 | Initial prompt auto-submitted at start |\n| `--resume <id>` | \u2014 | Fork an existing session id into the mesh (claude only) |\n| `--transcript` / `--no-transcript` | off | Mirror the session transcript to `tr-<name>` |\n| `--events` / `--no-events` | off | Publish the session's structured event plane to its own event channel |\n| `--share-tools <sel>` | none | Share named operator MCP servers with the agent |\n| `--subscribe <a,b>` | persona's | Channel read-set override |\n| `--allow-subscribe <a,b>` | = subscribe | Read-ACL override |\n| `--allow-publish <a,b>` | deny | Post-ACL override |\n| `--detach`, `-d` | off | Launch via the manager into a detached PTY (reattach with `cotal attach`) |\n| `--on <instance>` | class anycast | With `--detach` only: pin the launch to one manager instance id (the whole id, as `ps` prints it). Refused on a foreground spawn (no manager to pin), with `-f` (a manifest deploy launches through the manager class queue), and when empty |\n| `--file <cotal.yaml>`, `-f` | \u2014 | Deploy a manifest onto the running mesh |\n| `--dry-run` | off | With `-f`: print the plan, mutate nothing |\n| `--allow-stale <a,b>` | \u2014 | With `-f`: waive named stale agents (apply-only) |\n| `--runtime <name>` | manifest's | With `-f`: override the manifest's runtime |\n\n`--events` turns on the session's **event plane**: a stream of structured events describing what\nthe agent did, rather than the prose it wrote, on a channel of its own. The channel is named after\nthe agent's principal, `events.<owner>.<actor>`, never after its display name, because two live\nagents are allowed to share a display name and would then share a stream. The launch grants publish\nrights on exactly that one channel, foreground and detached alike, and a connector that does not\npublish an event plane refuses the flag rather than starting a session whose events have nowhere to\ngo.\n\nThe flag and the grant are separate on purpose. Holding publish rights on a channel is not a request\nto publish to it, so writing an event channel into an agent file's `allowPublish` does not turn the\nplane on: only the launch does.\n\nThe persona (`--config` > positional > `COTAL_DEFAULT_PERSONA` > `default`) is loaded from the\ntarget mesh's `.cotal/agents/`; the launch flags override the file. Foreground runs the agent\nattached to your terminal; `--detach` hands the launch to the running manager. Both modes get the\ndurable backstop on a mesh that runs the delivery daemon; `--live-only` skips it for a foreground\nspawn (messages posted while it is disconnected are then not replayed). A foreground exit retires\nthe agent's creds and broker footprint, like a manager despawn. A `--detach` spawn is an\n**action**: the manager accepts it and returns the allocated identity at once, then the launch\nfollows to a terminal outcome rather than blocking (see [the control surface](control-surface.md)).\nSee [Connect Claude Code](connect-claude.md) and [Agent files](agent-files.md); `-f` is a\n[manifest deploy](#manifest-deploys). (`cotal start` was merged into `cotal spawn --detach`.)\n\n## models\n\n```bash\ncotal models [--agent <connector>] [--refresh]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` / `--server <url>` / `--creds <path>` | resolved mesh | Which manager to reach |\n| `--agent <connector>` | all registered connectors | Connector whose catalog to list |\n| `--refresh` | off | Ask the connector to refresh its provider cache |\n\nAsks the running manager for each connector's model catalog (model ids plus their variants)\nfor connectors that expose one (OpenCode today; a connector without a catalog says so). Pick a\nresult with `cotal spawn --model <provider/model> --variant <v>`.\n\n## endpoints\n\n```bash\ncotal endpoints [--space <s>] [--server <url>] [--creds <path>]\n```\n\nLists the mesh presence roster: agents, the manager, and any other protocol endpoint, with each\nendpoint's role, kind, status, and current activity. Unlike `ps`, this is a read-only presence view;\nit is not limited to child processes owned by the manager.\n\n## describe, invoke\n\n```bash\ncotal describe <endpoint>                                        [--space <s>]\ncotal invoke <endpoint> <command> [--args '<json>']              [--space <s>]\ncotal invoke <endpoint> <command> --name <agent> [--admin]       [--space <s>]\n```\n\nThe generic v0.4 service surface. `describe` resolves a registered endpoint's command set off the\nwire - the reserved `describe` command answers the registered contract digests, the schemas are\nfetched from the space's content-addressed contract store, recompiled, and verified against those\ndigests - and prints each command with its capability class and targeting shape. `invoke` calls one\ncommand by name: `--args` is a JSON object validated against the fetched input schema *before*\npublish; a targeted command takes `--name <agent>` (resolved to the agent's current principal via\n`ps`) or `--self`. `--admin` uses the admin instrument credential, whose cross-agent reach rides\nthe operator-only `any` authorization mode. Neither command has compile-time knowledge of any\nendpoint's schemas - this is the same trust chain every built-in control command now uses. Needs an\nauth mesh: the manager registers its service on both static and per-user meshes (a signed-in user\nrides their bearer; cross-agent reach needs the `admin` scope). An open mesh has no service\nregistry.\n\n## ps, stop, attach\n\n```bash\ncotal ps [--on <instance>] [--space <s>]\ncotal stop --name <n> [--on <instance>] [--space <s>]\ncotal attach --name <n> [--on <instance>] [--space <s>]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` / `--server <url>` / `--creds <path>` | resolved mesh | Which manager to reach |\n| `--name <n>` | \u2014 | Managed agent to stop / attach (required) |\n| `--on <instance>` | class anycast (`ps`: class scatter) | Pin to one manager instance id (multi-manager space); takes the whole id as `ps` prints it, not a prefix. An empty value (`--on \"\"`, an unset shell variable) is refused, never treated as absent |\n\nThese are operator clients over the running manager's control plane. `ps` prints two facts per\nmanaged agent, because they answer different questions: the process fact from the manager's own\nruntime handle (`running` with its uptime, or `exited` with how long it ran), and the mesh fact from\nthe roster (`idle` / `working` / `waiting` / `mesh offline`, or `not in roster` when the seat has no\npresence row at all: a seat that has not joined yet, or one that never did). A seat can be `running` and `mesh offline` at once: the process is alive and\nits presence has lapsed. On a user-auth mesh `ps` also renders each managed agent's last\ncredential-refresh outcome, fail-closed.\n\n**Mode split (chosen up front, never try-scatter-then-degrade):**\n\n- **Static / open mesh.** Bare `ps` is a **class scatter**: it freezes the live manager class from\n  the records registry, merges every registered instance's agents grouped and attributed per\n  instance, and a non-answering instance is shown as `registered, no answer within the deadline`\n  (never silently omitted). That label is the whole claim: the instance is registered and did not\n  answer. It does not say the host is down, because a dead host never deregisters itself and a\n  live one can be slow; if it is gone, deregister it.\n  `--on <instance>` pins the read to one exact instance id instead. A wrong pin fails loud\n  rather than falling through: a well-formed id that no live manager carries is reported as\n  `manager instance <id> did not answer` (nothing else is asked), and a credential without that\n  instance's rail is reported as refused by the broker, not as an unresponsive manager. A manager\n  that answers with a refusal is shown with its own cause; \"no manager reachable\" is said only when\n  nothing answered at all. If the scatter's own registry read fails (the freeze or the reconcile),\n  `ps` says the manager registry could not be read rather than pronouncing on the managers, which\n  may all be up.\n\n**`stop` and `attach` route by seat locality.** A seat can only be stopped or attached by the\nmanager actually running it, and the class queue does not know which one that is. So on a\nstatic/open mesh both verbs first ask every registered instance which one hosts the named seat, then\naddress that instance directly. You do not need `--on` for this \u2014 it happens by default.\n\n`--on <instance>` remains the override, for when you already know where the seat lives or the\nlookup itself is degraded. It is also the **only** route on a **user-auth mesh**: a ledger-scoped\nbearer does not hold the registry-read rows the lookup needs, so there the verbs stay on the class\nqueue unless you pin them yourself.\n\nIf the seat is found on no reachable instance, the error says so \u2014 how many managers answered, and\nwhich ones did not \u2014 rather than reporting a bare `no agent <name>`. That distinction matters\nbecause a single manager cannot tell \"hosted elsewhere\" from \"does not exist\": it answers\n`not-found` for both.\n- **User-auth mesh.** `cotal ps` reports what **one** manager knows about your agents (an `ep.one`\n  read against the manager's in-memory roster, owner-filtered). It does **not** report other\n  manager instances, and it cannot tell you that one is down \u2014 an unreachable manager is absent\n  from the list, not flagged. Completeness across a multi-manager user-auth space is not claimed.\n  A manager that does not answer fails the command outright (exit non-zero), rather than printing\n  an empty list that could be read as \"no agents\". Your ledger row needs the `admin` scope to\n  reach `ps` at all; `spawn` alone is refused by the broker (the ep tier boundary).\n\n`attach` streams and drives an agent's terminal on the `pty` runtime; detach with the escape key\n(Ctrl-] by default; see [`COTAL_DETACH_KEY`](config.md)). It does so over a one-use, holder-bound\nmesh session ([SPEC](../SPEC.md) \xA713.6): the manager replies with a signed session grant (never a\n`127.0.0.1` URL), the CLI redeems it once over the broker, and the browser console (`cotal console`)\ndrives the same session. `stop` and `attach` need a running manager to talk to. On a static mesh\nthey are cross-agent admin operations. On a user-auth mesh, your own agents (any agent under your\nowner) need only the `spawn` scope; another owner's agent needs `admin` on your ledger row\n([identity & auth](identity-and-auth.md)). Launch detached agents with [`spawn --detach`](#spawn).\n\n`attach` streams over the manager's own HTTP/WS face rather than the mesh. That endpoint binds\n**loopback by default**, so nothing is exposed by accident; `cotal up --host <addr>` passes its bind\naddress down, which is what lets you attach to an agent whose manager runs on another machine. A\nbare `cotal supervise` and an embedded manager stay machine-local. Set it directly with\n`supervise --console-host <host>`.\n\nThat address is **recorded on the mesh** and carried forward, because it is a decision rather than\nsomething later commands can work out for themselves (a broker dial address is not a manager bind\naddress). Every later manager launch for the same mesh reuses it \u2014 a same-root `cotal up` repair,\nadopting a preserved or restored listener, a `spawn -f` manifest deploy \u2014 so a manager replacement\ndoes not quietly move a reachable attach face back to loopback. Passing `--host` again overrides it,\nso you can widen or narrow exposure whenever you like; a mesh that never asked stays loopback-only\nand records nothing.\n\nBecause that face carries terminal read and write for every managed agent, it is credentialed in two\ntiers. A mesh caller receives a **ticket** bound to the single agent the manager just authorized,\nsingle-use and short-lived, so one authorized attach can never be re-pointed at someone else's\nagent. The **console token** is the operator's own, reaches every agent, and is printed only to the\nmanager's output. The roster, the live feed, and the PTY stream all answer `401` without one; the\nstatic console shell is served openly, since it describes no agent.\n\n## input\n\n```bash\ncotal input --name <n> --text <text> [--no-enter] [--on <instance>] [--space <s>]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` / `--server <url>` / `--creds <path>` | resolved mesh | Which manager to reach |\n| `--name <n>` | | Managed agent to type into (required) |\n| `--text <text>` | | The text to type, taken verbatim (required) |\n| `--no-enter` | off | Type the text and stop there, without pressing Enter |\n| `--on <instance>` | class anycast | Pin to one manager instance id, exactly as [`attach`](#ps-stop-attach) |\n\nTypes one line into a running agent's terminal, as if you had typed it there, and returns. This is\nthe half of [`attach`](#ps-stop-attach) that a program wants: `attach` is a live stream that holds a\nsession open and expects a terminal on your side, so a script, a cron job or a web UI cannot use it\nto send a single line. `input` is one authorized call.\n\nWhat it is for is **harness commands**. A line beginning with `/` is not chat and not a message: it\nis something the agent's own harness handles, and the only way in is the keyboard.\n\n```bash\ncotal input --name reviewer --text \"/compact\"          # ask the harness to compact its context\ncotal input --name reviewer --text \"/model opus\"       # switch its model\ncotal input --name reviewer --text \"hold on that PR\"   # ordinary typing works too\n```\n\n**Quoting.** `--text` takes a value, so a payload starting with `/` survives as written. A payload\nstarting with a dash needs the `=` form, because the shell-style `--text --foo` is ambiguous and is\nrefused rather than guessed:\n\n```bash\ncotal input --name reviewer --text=--verbose          # dash-leading text: use --text=<value>\n```\n\nEnter is pressed by default, since a command typed but never submitted has not been delivered.\n`--no-enter` types the text and leaves it sitting at the prompt, which is how you stage a line and\nsend it later.\n\nNothing comes back but a delivery receipt (`\u2713 sent 9 bytes to reviewer`, counting the trailing\ncarriage return). Whatever the agent does next shows up where its output already goes: the mesh, its\ntranscript, or an `attach`.\n\n**This one is operator-only, and more narrowly than `stop` or `attach`.** Those two are granted to\nanything holding `spawn`, so an agent can stop and attach to seats under its own owner. `input` is\nnot: it is granted only to operator credentials, which on a user-auth mesh means your ledger row\nneeds the `admin` scope, the same scope [`ps`](#ps-stop-attach) already needs there. The reason is\nthat a write into a terminal is control of whatever is running in it, and on a user-auth mesh the\nown-owner rule covers every seat under you, not only the ones you launched: a `spawn`-scoped agent\ncould otherwise type into a sibling it never started. Seat locality is still resolved for you.\n\nOnly the `pty` runtime can be typed into. The external terminal runtimes (`tmux`, `cmux`, `orca`,\n`herdr`) attach to a process they do not own, so they have no input stream for it and the command\nrefuses by name rather than dropping the keystroke.\n\n## personas\n\n```bash\ncotal personas list [-v] [--running]\ncotal personas show <name>\ncotal personas edit <name>\ncotal personas new <name> (--prompt <t> | --from <f>) [--role <r>] [--model <m>]\ncotal personas rm <name> --force\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` / `--server <url>` / `--creds <path>` | resolved mesh | Which mesh's persona catalog |\n| `--role <r>` | \u2014 | `new`: the persona's role |\n| `--model <m>` | \u2014 | `new`: the persona's model |\n| `--prompt <t>` | \u2014 | `new`: the persona's prompt text |\n| `--from <f>` | \u2014 | `new`: seed the prompt from a file |\n| `--verbose`, `-v` | off | `list`: include role / model / description |\n| `--running` | off | `list`: mark personas live on the mesh |\n| `--force` | \u2014 | `rm`: required, delete without prompting |\n\nPersonas are the local agent files under `.cotal/agents/` that `cotal spawn` launches. See\n[Agent files](agent-files.md) for the file format.\n\n## supervise\n\n```bash\ncotal supervise [--runtime <name>] [--space <s>] [--server <url>] [--spawn <names>]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` | this folder's auth space | Space to supervise |\n| `--server <url>` | the local mesh | Broker URL |\n| `--runtime <name>` | `pty` | Agent runtime (`pty` built in; extension runtimes are explicit-only) |\n| `--console-port <n>` | \u2014 | Protocol-console port |\n| `--console-host <host>` | loopback | Bind host for the console + attach endpoint. Loopback keeps it machine-local; `cotal up` passes the address it bound the broker to, which is what lets `cotal attach` reach this manager from another machine |\n| `--roster <file>` | \u2014 | Declarative roster to boot at startup |\n| `--launch <spec>` | \u2014 | Resolved manifest launch spec (from `up -f` / `spawn -f`) |\n| `--spawn <names>` | \u2014 | Comma-separated personas to pre-spawn at startup |\n\nThe manager is the agent supervisor and control plane: it answers `spawn --detach`, `stop`, `ps`,\n`attach`, and the `cotal_*` manager tools. `cotal up --detach` starts one for you; run `supervise`\ndirectly to recover a dead manager or drive a custom runtime. Default runtime is `pty`; install an\noptional provider first (`cotal ext add @cotal-ai/orca`, `@cotal-ai/tmux`, `@cotal-ai/cmux`, or `@cotal-ai/herdr`) and\nselect it explicitly. A missing provider or app fails loudly; there is no fallback. See [Deploy](deploy.md).\n\n## reconcile-gate\n\n```bash\ncotal reconcile-gate [--space <s>] [--server <url>] [--endpoint <e>] [--instance <id>]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` | this folder's auth space | Space the frozen gate lives in |\n| `--server <url>` | the local mesh | Broker URL |\n| `--endpoint <e>` | `manager` | Endpoint whose gate is frozen |\n| `--instance <id>` | this folder's persisted manager instance | Instance id |\n\n**When you need this.** A manager restart killed partway through \u2014 after it began deregistering,\nbefore the new incarnation finished \u2014 leaves the endpoint's issuance gate *frozen*, held by a\nprocess that no longer exists. The next manager start refuses to proceed, which is correct: the\nfreeze is what stops two incarnations serving at once. But nothing can lift it, so every restart\nfails the same way. `cotal doctor` shows the gate as frozen; the manager's own start logs name the\ngate it could not advance.\n\nThis command is the way out. It checks that the holder really is gone, prints what it found, and\nthen finishes the dead operation exactly as the interrupted restart would have: revoke the old\ncredentials, evict their holders with verification, and reopen the gate. Start the manager\nafterwards and its normal takeover runs end to end.\n\n**It refuses far more often than it acts, on purpose**, and always says which check stopped it:\n\n| Refusal | What it means | What to do |\n|---|---|---|\n| `holder-alive` | The freeze-holder still has a live connection \u2014 a manager *is* running | Stop that process first. Reconciling would evict a live manager's credentials |\n| `holder-unknown` | The connection sweep could not prove the holder absent | Not safe to proceed: an unprovable holder is treated as a live one. Re-run once the broker answers completely |\n| `liveness-unestablishable` | The delivery daemon could not be asked at all | Start it (`cotal up` runs it) and re-run. Silence is never read as death |\n| `not-frozen` / `no-gate` | The gate is open, or there is no gate at that coordinate | Nothing to repair \u2014 check `--endpoint` / `--instance` |\n| `wrong-op-kind` | Frozen under a takeover or retirement, not a registration | Out of scope for this command; it will not reinterpret another operation's intent |\n| `eviction-unverified` | The holder looked gone but eviction could not be verified | The gate is left frozen, unchanged. Investigate the broker before retrying |\n| `raced` | A newer manager moved the gate mid-repair | Re-run `cotal doctor` and look again |\n\nThere is no `--force`, and no path that discards gate state: the only way this reopens a gate is by\nproving the holder is gone and then completing the operation properly.\n\n## deregister-instance\n\n```bash\ncotal deregister-instance [--space <s>] [--server <url>] [--endpoint <e>] [--instance <id>]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` | this folder's auth space | Space the instance is registered in |\n| `--server <url>` | the local mesh | Broker URL |\n| `--endpoint <e>` | `manager` | Endpoint the instance serves |\n| `--instance <id>` | this folder's persisted manager instance | Instance id, the whole id as `cotal ps` prints it |\n\n**When you need this.** The service registry records *registration*, not liveness, and nothing in\nthe model expires a row. A manager that stops cleanly removes its own registration. One whose host\ndied without writing anything cannot, so its record goes on claiming a live instance forever: every\nclass scatter in that space freezes the dead slot in, and `cotal ps`, `stop` and `attach` each pay\ntheir whole deadline waiting for a machine that is never coming back. A laptop that was reimaged, a\ncontainer that was deleted, a box that will not be back on the network: those registrations have no\nother exit.\n\nThis command is that exit. It asks the instance first, and it removes a record only when the broker\naffirms the instance's own rail is empty: nothing subscribed there. Then it deletes the\nregistration's two records keys, each pinned to the revision it read, and prints what it removed.\n\n**Silence alone never passes.** An unanswered describe is what a dead host, a wedged process and a\nslow one all look like, and a hung process still holds its subscriptions, so the broker sees\ninterest on its rail. That instance is refused and the observation is printed. A dead process holds\nno connection and therefore no subscription, so a real corpse is still removed.\n\n**It refuses rather than guesses**, and says which check stopped it:\n\n| Refusal | What it means | What to do |\n|---|---|---|\n| `instance-answered` | The instance answered a pinned describe. It is alive | Nothing to repair. If it is wedged rather than gone, stop the process first; its own clean stop removes the record |\n| `instance-not-affirmed-gone` | It did not answer, and the broker did not report its rail empty, which is what a held subscription looks like: slow or hung, not affirmed gone | Nothing was removed. Stop the process; its record goes on its own clean stop, or re-run this once it is down |\n| `liveness-unestablishable` | The probe itself failed, so nothing was learned | Fix the probe's path (credential, broker) and re-run. A probe that could not run is never read as death |\n| `not-registered` | No registration at that coordinate | Check `--instance` and `--endpoint`. This takes the whole id, never a prefix |\n| `superseded` | The record moved between the read and the delete | Something is writing to it. Nothing was removed; re-observe before retrying |\n\nThere is no `--force` and no sweep: silence is not death, and a rule that removed rows on silence\nwould eventually remove a live instance that was merely slow. An operator names one instance, the\nbroker's verdict on its rail is what authorizes the removal, and the guard's job is to show them\nthey named a dead one. Removal is not a one way door either. The same instance re-registers over\nthe tombstone on its next start, under the same identity.\n\n## runtimes\n\n```bash\ncotal runtimes\n```\n\nLists every agent runtime the manager can spawn through: the built-in `pty`, the official providers\n(`orca`, `tmux`, `cmux`, `herdr`), and any custom provider installed via `cotal ext add`. Each installed\nprovider is probed so you can see what is actually reachable on this machine before selecting it:\n\n```\npty    built in\norca   installed \xB7 reachable   @cotal-ai/orca\ntmux   available \xB7 cotal ext add @cotal-ai/tmux\ncmux   available \xB7 cotal ext add @cotal-ai/cmux\nherdr  available \xB7 cotal ext add @cotal-ai/herdr\n```\n\n`installed \xB7 reachable` / `unreachable` is the provider's own `available()` probe; `available` means\nit is a known runtime you can add with the shown command. Selecting an unknown or uninstalled runtime\nvia `up`/`spawn --runtime <name>` fails loud and, for a known one, points at the exact `cotal ext add`\npackage \u2014 there is no silent fallback to `pty`.\n\n## send\n\n```bash\ncotal send dm <agent> \"<text>\"   [--space <s>] [--server <url>] [--creds <path>]\ncotal send msg <channel> \"<text>\"\ncotal send ask <role> \"<text>\"\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` / `--server <url>` / `--creds <path>` | resolved mesh | Which mesh, and (off-registry) which credential |\n\nOne-shot messaging: connect, send a single direct message (`dm`), channel post (`msg`), or role\nask/anycast (`ask`), then exit. For a running conversation, agents use the mesh tools instead\n([MCP tools](mcp-tools.md)).\n\n## channels\n\n```bash\ncotal channels list\ncotal channels set <name> [--replay | --no-replay] [--window <n>] [--desc <s>] [--instructions <s>]\ncotal channels default --replay | --no-replay\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` / `--server <url>` / `--creds <path>` | resolved mesh | Target mesh |\n| `--replay` / `--no-replay` | \u2014 | `set`/`default`: replay history to new joiners, or not |\n| `--window <n>` | \u2014 | `set`: replay window size |\n| `--desc <s>` | \u2014 | `set`: one-line channel description |\n| `--instructions <s>` | \u2014 | `set`: instructions shown to joiners |\n\nInspects and edits the channel registry: replay policy, description, and joiner instructions. ACL\nsemantics (who may read or post) are set at mint / provision time, not here; see\n[Channels and permissions](channels-and-permissions.md). On a user-auth mesh, `list` rides your\nown login as is; `set` and `default` edit the registry over a short-lived\nchannel-writer view, which needs ledger scope `admin` ([Identity & auth](identity-and-auth.md)).\n\n\n## history\n\n```bash\ncotal history clear --force [--dms] [--space <s>]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` / `--server <url>` / `--creds <path>` | resolved mesh | Target mesh |\n| `--dms` | off | Also clear DM history |\n| `--force` | \u2014 | Required: clear without prompting |\n\nPurges retained channel history; `--dms` extends it to direct-message history. An alias of\n[`clean history`](#clean). On a user-auth mesh the purge rides a short-lived purger view over\nyour login, which needs ledger scope `admin` ([Identity & auth](identity-and-auth.md)).\n\n## console\n\n```bash\ncotal console [--plain] [--space <s>]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` / `--server <url>` / `--creds <path>` | resolved mesh | Space to watch |\n| `--plain` | off | Line stream instead of the TUI |\n\nA live protocol view for a space: a lazygit-style TUI, or a plain line stream on `--plain`. On a\nuser-auth mesh it rides the read-only admin view over your login, which needs ledger scope\n`admin`. See [Watch a mesh](watch-a-mesh.md).\n\n## web\n\n```bash\ncotal web [--detach] [--port <n>] [--no-open] [--space <s>]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` / `--server <url>` / `--creds <path>` | resolved mesh | Space to serve |\n| `--port <n>` | `7799` | HTTP port |\n| `--detach` | off | Run in the background; stop with `cotal down web` or bare `cotal down` |\n| `--no-open` | off | Don't open the browser |\n\nThe browser observability dashboard: presence, channels, and a live feed. It is **not** part of\n`cotal up`: it ships inside `cotal-ai` as the `@cotal-ai/web` extension, seeded automatically on first\nrun (like the built-in connectors) so it always matches your CLI version. It self-registers `cotal web`\ninto this surface and serves\n`http://cotal.localhost:7799` (loopback; `*.localhost` resolves in Chrome/Firefox/Edge; Safari may\nneed `http://127.0.0.1:7799`). On a user-auth mesh the dashboard rides the read-only admin view\nover your login, and a channel purge asks for its own channel-purger view per click; both need\nledger scope `admin`. Detached mode re-execs the current Cotal installation, writes diagnostics to\nthe mesh root's `.cotal/web.log`, and reports success only after the HTTP server answers. It requires\na recorded mesh root, but can be launched from any directory once `cotal up` has recorded the mesh.\nSee [Watch a mesh](watch-a-mesh.md).\n\n## mint\n\n```bash\ncotal mint <name> [--profile <agent|observer|admin>] [--out <path>] [--signer]\ncotal mint <name> --provision [--role <role>] [--space <s>] [--server <url>]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--profile <agent\\|observer\\|admin>` | `agent` | Credential profile |\n| `--out <path>` | `.cotal/auth/creds/<name>.creds` | Output path |\n| `--signer` | off | Emit a stripped account-signing file instead |\n| `--force` | off | With `--signer`: overwrite an existing file |\n| `--allow-subscribe <a,b>` | profile default | Read-ACL override |\n| `--allow-publish <a,b>` | profile default | Post-ACL override |\n| `--role <role>` | the agent file's | Agent profile: the anycast task queue the identity pulls (`svc_<role>`) |\n| `--provision` | off | Agent profile: also pre-create the identity's bind-only DM/deliver durables (and its role's task queue) on the live mesh, so the credential can consume |\n| `--space <s>`, `--server <url>` | the resolved mesh | With `--provision`: which mesh to provision on |\n\nMints a NATS creds file for a space in **static** auth mode, scoped to a profile and (optionally)\nexplicit read/post ACLs. `--signer` emits an account-signing file for delegating minting to another\nhost. A per-user-auth space refuses `mint`: agents there join under a logged-in user\n([`login`](#login-logout) + [`actor grant`](#actor)), never via a handed-out creds file. See\n[Identity and auth](identity-and-auth.md).\n\nA plain mint is creds only: the identity can publish within its post ACL at once, but on an authed\nmesh its DM inbox and task queue are provisioner-pre-created and bind-only, so a **consuming**\nconnect fails until they exist. `--provision` performs that pre-create in the same command (a\nprovisioner cred is minted from the space's trust material, used, and dropped), so a long-running\nclient you start yourself can receive DMs and role anycasts like a spawned seat. The command prints\nthe identity's principal (its wire id) and lifecycle uid; a consuming client passes that uid as its\n`lifecycleUid`. Agent profile only; an open mesh needs none of this (peers self-create there). The\nmesh it provisions on must be the one this folder's auth is for - same space and same account key -\nso `--provision` can never quietly mint under another root's trust material.\n\n## login, logout\n\n```bash\ncotal login --idp <auth base URL> [--client-id <id>]\ncotal logout --idp <auth base URL>\n```\n\nSigns you in to a per-user-auth mesh's IdP (device code flow) and caches the session; run it\nonce per machine. It prints your IdP subject, the id the operator grants against. After a\nlogin, every command on that mesh works under your identity: each connect takes a fresh IdP\nproof, exchanges it locally for a short-lived bearer, and is authorized against the actor\nledger at connect time. `logout` revokes the IdP session and clears the cache. See\n[identity & auth](identity-and-auth.md).\n\n## actor\n\n```bash\ncotal actor grant <actor> --sub <IdP subject> [--scope a,b] [--allow-subscribe a,b] [--allow-publish a,b] [--role <r>] [--label <l>]\ncotal actor revoke <actor> (--sub <IdP subject> | --owner <u_\u2026>)\ncotal actor list\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` | the folder's | Space whose ledger to manage |\n| `--sub <subject>` | \u2014 | The IdP subject (shown by `cotal login`) the actor belongs to |\n| `--owner <u_\u2026>` | \u2014 | The derived owner token (alternative to `--sub`) |\n| `--scope <a,b>` | `spawn,role:default` | Capability scope (`''` = none; `spawn` = may run agents, `role:<r>` = may delegate role r, `admin` = cross-agent control) |\n| `--allow-subscribe <a,b>` | `>` (all channels) | Channel read ACL; the user's envelope, their agents can never read beyond it |\n| `--allow-publish <a,b>` | `>` (all channels) | Channel post ACL; also the envelope for their agents' posting |\n| `--role <r>` | \u2014 | Role (scopes the task-queue consumer) |\n| `--label <l>` | \u2014 | Display label for `actor list` (never the IdP subject) |\n\nThe actor ledger is the single authorization source of a user-auth space: no row, no access.\nA bare `grant` is the **full** envelope (all channels, may spawn); the flags narrow it. A\nre-grant **replaces** the row, so to add a capability, re-grant with it added to the current\nscope (`cotal actor list` shows what a row holds). `revoke` denies the next exchange and the\nnext connect with no restart, and evicts the principal's live connections. Managed-agent rows\n(written by the spawn path) live in a disjoint row space this command never touches. See\n[identity & auth](identity-and-auth.md).\n\n## doctor\n\n```bash\ncotal doctor auth [--fix]\n```\n\nCredential-health diagnosis and repair for this folder's mesh: renders every managed\ncredential as healthy / near-expiry / expired and ends in `healthy` or the exact next\ncommand; `--fix` applies the repairs it can. The one surface every stale-credential error\npoints at.\n\n## join\n\n```bash\ncotal join --space <s> --name <n> [--role <r>] [--channel <c>]\ncotal join --link <url> | --token <t>\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` / `--server <url>` / `--creds <path>` | resolved mesh | Which mesh, and which credential |\n| `--name <n>` | \u2014 | Your presence name |\n| `--role <r>` | \u2014 | Your role |\n| `--channel <c>` | \u2014 | Channel to join |\n| `--kind <k>` | `agent` | Endpoint kind |\n| `--link <url>` | \u2014 | Join link (`cotal://\u2026`) |\n| `--token <t>` | \u2014 | Join token |\n| `--lifecycle-uid <uid>` | \u2014 | Required with `--creds`: the lifecycle UID minted alongside the credential (`COTAL_LIFECYCLE_UID` works too). A credential's durable grants name exact lifecycle-keyed resources, so `join` refuses to invent one |\n| `--tls` | off | Connect over TLS |\n\nAn interactive presence: join a space under your own name and role, without launching an agent\nharness. A `--link` or `--token` supplies the where and the auth in one value. See\n[Spaces](spaces.md) and [Identity and auth](identity-and-auth.md).\n\n## Manifest deploys\n\nA `cotal.yaml` manifest declares a whole mesh (channels, personas, roles, and ACLs) in one file.\nThree commands consume it, plus a read-only validator:\n\n```bash\ncotal up -f cotal.yaml         # boot a fresh mesh from the manifest\ncotal spawn -f cotal.yaml      # deploy the manifest additively onto a running mesh\ncotal down -f cotal.yaml       # tear that deploy down (or --run <id> for one run)\ncotal topology view -f cotal.yaml   # validate + view the access graph, change nothing\n```\n\n`up -f` and `spawn -f` differ in target: `up -f` brings up a new broker and applies the manifest;\n`spawn -f` requires an already-reachable mesh and applies additively (ownership-scoped). On a\nuser-auth mesh, `spawn -f` deploys over your own login (the deployer view, gated on ledger scope\n`spawn`): the manifest's agents land under your owner, a manifest claiming another owner is\nrefused, and seeding new channels additionally needs scope `admin`. Both take\n`--dry-run` to print the plan without mutating anything. `topology` validates the manifest and\nrenders its channel / role / ACL graph. See [Define a team](define-a-team.md) and the\n[manifest reference](manifest.md).\n\n## ext\n\n```bash\ncotal ext                 # same as `list`\ncotal ext add <npm-package>\ncotal ext remove <name>\ncotal ext list\ncotal ext root            # print just the install prefix (scriptable)\ncotal ext seed [--repair|--reset|--force]\n```\n\nOperator-installed extensions: `add` installs an npm package into a cotal-owned prefix and records\nevery registry provider it contributes. Commands appear in help, completion, and dispatch; runtime\nproviders are lazy-loaded by commands such as `supervise`; local process providers participate in\n`status` and selective `down`. `remove` and `list` manage them. The `@cotal-ai/web` dashboard is the\ncanonical command/process example. Installed packages and their location are described in\n[config](config.md).\n\nBare `cotal ext` lists the inventory, headed by the install prefix. That prefix is a cotal-owned npm\nroot kept **separate** from npm's own global tree, so these packages never show up in `npm list -g` \u2014\n`cotal ext` (or the Extensions section of `cotal status`) is the canonical inventory. `cotal ext root`\nprints only the path, for scripts. The versions shown are the manifest pin recorded at add time.\n\nRemoving an extension that owns a running local process is refused with the mesh root and its\n`cotal down <component>` command; stop it first so uninstalling the package never strands a process\nwhose lifecycle provider is gone.\n\n### Built-in connectors are seeded extensions\n\nThe first-party agent connectors (`claude`, `opencode`, `codex`, `hermes`, `pi`) are not compiled into\nthe binary. They are seeded on first run through the **same** `ext add` path a third party uses, and\nappear in `cotal ext list` like any other extension. So you can remove one you do not want\n(`cotal ext remove @cotal-ai/connector-hermes`), and a deliberately-removed connector STAYS removed\nacross upgrades. `cotal ext add <your-package>` adds a third-party connector the same way. The web\ndashboard (`@cotal-ai/web`, providing `command:web`) is a fifth built-in seeded on the same path.\n\n`cotal ext seed` is the maintenance entry for that seeding (it runs automatically on the first real\ncommand of each boot, so you rarely call it):\n\n| Flag | Meaning |\n|---|---|\n| (none) | Reconcile: seed any never-seeded built-in, refresh a seeded one whose version the binary bumped, leave a removed one removed. A no-op once current. |\n| `--repair` | Recover after an interrupted seed or a lost authority (rebuilds the interrupted connector; restores the removed-vs-never-seeded record from its durable backup). |\n| `--reset` | Discard the record and re-seed all six built-ins (the five connectors plus the web dashboard). **Resurrects any you removed.** Rebuilds cleanly over corrupt seed state. |\n| `--force` | Re-seed the built-ins even when the version stamp is current or a downgrade. |\n\nThe default connector for a bare `cotal spawn` (no `--agent`) is `claude`; set `COTAL_DEFAULT_AGENT`\n(e.g. `opencode`) to change it. An `--agent` naming a removed connector fails loud with the exact\n`cotal ext add` to restore it. Set `COTAL_SKIP_CONNECTOR_SEED=1` to turn off the automatic first-run\nseed/refresh entirely (for a controlled or offline setup that manages connectors by hand); `cotal ext\nseed` still runs on request.\n\n## completion\n\n```bash\ncotal completion <bash|zsh|fish|powershell>   # print a stub to eval / source\ncotal completion install [shell]              # install it persistently\n```\n\nPrints or installs shell completion. Completion candidates come from each command's declared flags\nand, where useful, live mesh state (spaces, personas, managed agents) resolved offline.\n\n## feedback\n\n```bash\ncotal feedback \"<summary>\" [--type <t>] [--email <e>] [--details <text>]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--type <t>` | \u2014 | `bug` \\| `idea` \\| `friction` \\| `praise` \\| `other` |\n| `--details <text>` | \u2014 | Longer free-form details |\n| `--severity <s>` | \u2014 | `low` \\| `medium` \\| `high` |\n| `--area <a>` | \u2014 | The part of Cotal this concerns |\n| `--email <e>` | git email | Contact email (required on the keyless public path) |\n| `--name <n>` | \u2014 | Your name (optional) |\n| `--url <url>` | keyed / public intake | Intake URL override |\n| `--key <k>` | `COTAL_FEEDBACK_KEY` | Feedback key |\n\nSends feedback to the Cotal developers. With a key (`--key` / `COTAL_FEEDBACK_KEY`) it routes to the\nkeyed beta intake; without one it goes to the public `cotal.ai` intake and requires a contact email\n(`--email` / `COTAL_FEEDBACK_EMAIL`, else your git email). Run a self-hosted intake with\n[`feedback-intake`](#server-daemons).\n\n## Server daemons\n\nTwo long-lived infra roles ship with the CLI. They are not part of everyday operation; the delivery\ndaemon comes up automatically with `cotal up --detach` in auth mode.\n\n```bash\ncotal deliver --space <s> [--server <url>] [--creds <file>]\ncotal auth-service --space <s> --server <url> [--port <n>]\ncotal feedback-intake --keys <keys.json> [--port <n>] [--creds <file>]\n```\n\n`auth-service` runs a user-auth space's identity plane (the NATS auth callout plus the\nloopback token exchange and JWKS); `cotal up --user-auth` starts and supervises it for you,\nso you run it directly only to recover one by hand.\n\n`deliver` runs the server-side Plane-3 delivery daemon: the durable backstop and membership/ACL\nauthority. It is auth-mode-only and single-instance (`--shard`/`--shards` accept only `N=1`);\n`--dev-mint` mints a scoped cred from the local signer for standalone dev. See the\n[delivery daemon](delivery-daemon.md). `feedback-intake` runs a self-hosted feedback server\n(requires `--keys` and a scoped `--creds`), announcing submissions into a space channel; flags\ninclude `--host`/`--port`, `--store`, `--space`/`--channel`, `--max-bytes`, and `--rate-limit`.\n\n## Plumbing\n\n`cotal __complete <words\u2026>` is the internal entry the shell-completion stubs call to emit candidates\nfor the current command line; you never run it directly. `cotal agent-bearer` is machine-facing\nplumbing on user-auth meshes: spawned agents exec it to print a fresh short-lived bearer from their\nspawn-time secret; you never run it directly either. (`cotal start` is a removed tombstone: it\nerrors and points you to `cotal spawn --detach`.)\n"
+      "body": "# `cotal` CLI reference\n\n> **Reference**: describes the TypeScript reference implementation (the `cotal` CLI), not the wire contract. \xB7 **For:** operators \xB7 **Wire contract:** [SPEC](../SPEC.md)\n\n`cotal` is the operator command line for the reference implementation: bring a mesh up, mint\nidentities, launch agents, watch what they do, and tear it all down. It is a thin client over the\nwire contract: the normative subjects and schemas live in the [SPEC](../SPEC.md); this page is\nlookup material for the commands, not a walkthrough; if you are new, start with\n[Getting started](getting-started.md).\n\n## Running it\n\n```bash\nnpm install -g cotal-ai   # puts `cotal` on your PATH (needs Node 22+)\ncotal --help              # every command, grouped\ncotal --version           # cotal-ai version + each installed extension's (also `cotal -v`)\ncotal <command> --help    # one command's flags and usage\n```\n\n`npx cotal-ai <command>` runs it without a global install; in a dev clone, `pnpm cotal <command>`\nruns it through `tsx` with no build step. Bare `cotal` prints help. Every command generates its own\n`--help`, usage, and shell completion from its declared flags.\n\nCommands come from the surfaces the binary composes: the base mesh CLI, the manager\n(`supervise`), and the delivery daemon (`deliver`), plus any operator-installed extensions.\n`cotal ext add <npm-package>` installs any registry providers a package contributes: commands,\nruntimes, and local process lifecycle descriptors. The `web` dashboard and optional manager\nruntimes ship this way.\n\n## Commands\n\n| Area | Command | Purpose |\n|---|---|---|\n| Set up & lifecycle | [`setup`](#setup) | Guided, configure-only setup (installs, seeds personas; launches nothing) |\n| Set up & lifecycle | [`update`](#update) | Reconcile first-party extensions and check or opt into a coherent CLI upgrade |\n| Set up & lifecycle | [`up`](#up) | Start a local mesh (nats-server + JetStream), or boot a whole manifest with `-f` |\n| Set up & lifecycle | [`down`](#down) | Stop the whole stack, selected registered components, or a manifest deploy |\n| Set up & lifecycle | [`backup`](#backup-and-restore) | Create an offline full-space or registry-only artifact from a preserved cut |\n| Set up & lifecycle | [`clean`](#clean) | Configurable cleanup: purge history (live), or wipe the local store / identity (stopped) |\n| Set up & lifecycle | [`meshes`](#meshes-use-status) | List the running meshes on this machine |\n| Set up & lifecycle | [`use`](#meshes-use-status) | Set the default mesh a bare `cotal spawn` joins |\n| Set up & lifecycle | [`status`](#meshes-use-status) | Read-only diagnostics for setup, processes, and the selected mesh |\n| Agents & personas | [`spawn`](#spawn) | Launch an agent from a persona (foreground, or `--detach` via the manager) |\n| Agents & personas | [`models`](#models) | List connector model catalogs and variants from the manager |\n| Agents & personas | [`ps`](#ps-stop-attach) | List managed agents and their mesh status |\n| Agents & personas | [`stop`](#ps-stop-attach) | Ask the manager to stop a managed agent |\n| Agents & personas | [`attach`](#ps-stop-attach) | Stream and drive a managed agent's terminal (pty runtime) |\n| Agents & personas | [`input`](#input) | Type one line into a managed agent's terminal without attaching |\n| Agents & personas | [`personas`](#personas) | List, show, edit, create, or remove local personas |\n| Agents & personas | [`supervise`](#supervise) | Run a manager daemon (the agent supervisor / control plane) |\n| Agents & personas | [`runtimes`](#runtimes) | List the agent runtimes the manager can spawn through and whether each is reachable |\n| Agents & personas | [`reconcile-gate`](#reconcile-gate) | Unfreeze an issuance gate left frozen by a crashed manager restart, after verifying the holder is gone |\n| Messaging & watching | [`endpoints`](#endpoints) | List every endpoint in the live presence roster, including infrastructure |\n| Messaging & watching | [`describe` / `invoke`](#describe-invoke) | Resolve a v0.4 service's command surface off the wire; invoke one command by name |\n| Messaging & watching | [`send`](#send) | Send one message, then exit: DM a peer, post a channel, or ask a role |\n| Messaging & watching | [`channels`](#channels) | Inspect or set the channel registry |\n| Messaging & watching | [`history`](#history) | Clear retained message history |\n| Messaging & watching | [`console`](#console) | Live protocol view for a space (TUI, or `--plain` line stream) |\n| Messaging & watching | [`web`](#web) | Browser dashboard (installed as the `@cotal-ai/web` extension) |\n| Auth & meshes | [`mint`](#mint) | Mint a creds file for a space (static auth mode) |\n| Auth & meshes | [`login`](#login-logout) | Sign in to a per-user-auth mesh's IdP (once per machine) |\n| Auth & meshes | [`logout`](#login-logout) | Revoke the IdP session and clear the cached login |\n| Auth & meshes | [`actor`](#actor) | Manage a user-auth space's actor ledger (grant / revoke / list) |\n| Auth & meshes | [`doctor`](#doctor) | Credential-health diagnosis and repair (`doctor auth`) |\n| Auth & meshes | [`join`](#join) | Join a space as your own presence (interactive) |\n| Manifest | [`topology`](#manifest-deploys) | Validate and view a mesh manifest's access graph (read-only) |\n| Extensions & misc | [`ext`](#ext) | Install / remove operator CLI extensions |\n| Extensions & misc | [`completion`](#completion) | Print or install shell completion |\n| Extensions & misc | [`feedback`](#feedback) | Send feedback to the Cotal developers |\n| Extensions & misc | [`deliver`](#server-daemons) | Run the server-side Plane-3 delivery daemon |\n| Extensions & misc | [`feedback-intake`](#server-daemons) | Run a self-hosted feedback intake server |\n\nThe manifest modes of `up`, `spawn`, and `down` (`-f <cotal.yaml>`) plus `topology` are covered\ntogether under [Manifest deploys](#manifest-deploys).\n\n## setup\n\n```bash\ncotal setup [--full] [--demo] [--yes]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--full` | off | Redo the full guided flow (implies `--demo`) |\n| `--demo` | off | Also seed the guided expert team (`david`, `sven`, `me`) |\n| `--yes`, `-y` | off | Non-interactive accept-all (for agents / CI) |\n\nGuided setup is **configure-only**: it checks prerequisites, installs the Claude Code plugin, and\nseeds persona files, and it launches nothing (no mesh, no web, no manager). First run gets the\nnarrated flow; later runs print a status card. By default it seeds one `default` persona; the\n`david`/`sven`/`me` team is opt-in via `--demo`. See [Getting started](getting-started.md) and, for\nmaintainers, [setup internals](setup-internals.md).\n\n## update\n\n```bash\ncotal update [--self]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--self` | off | If a newer release exists, install that exact validated `cotal-ai` version globally and reconcile through the newly installed binary |\n\nWithout `--self`, `update` keeps the installed first-party surfaces coherent with the running\nbinary: it force-reconciles the four built-in connectors, then reinstalls other `@cotal-ai/*`\noperator extensions at the binary's exact version. Each extension runs in an isolated child, so one\nfailure cannot poison later replays. It then checks npm; a newer binary is an informational notice\nwith `cotal update --self` as the next command, not an automatic install.\n\nWith `--self`, the npm check happens first. When a newer release exists, Cotal installs the exact\nversion it validated, resolves and verifies that package in npm's global root, then launches that\nbinary to reconcile connectors and first-party extensions to the new generation. An npx or dev-clone\ninvocation therefore installs and continues through a separate global copy; it never claims the\nalready-running process changed. If the binary is current, `--self` performs the normal local\nreconcile without reinstalling it.\n\nThird-party extensions are listed with their installed version and recorded spec but are not\nauto-updated in v1. Floating third-party updates require `@cotal-ai/*` peer-range validation and are\na future follow-up. A failed connector/extension install, npm metadata check, or requested global\ninstall is reported and makes the command exit nonzero. Independent extension attempts continue so\nthe output includes every failure; an unavailable npm registry does not undo a completed local\nreconcile, but the command still exits nonzero because it could not establish that the install is\ncurrent.\n\n## up\n\n```bash\ncotal up [--detach] [--open] [--space <s>] [--server <url>] [--channels <path>] [--runtime <name>]\ncotal up --tls-cert <cert.pem> --tls-key <key.pem>   # serve TLS (both, or neither)\ncotal up --restore <dir> [--restore-only registry] [--accept-missing-source]\ncotal up -f <cotal.yaml> [--dry-run] [--runtime <name>]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--server <url>` | auto (free local port) | Listen URL override |\n| `--host <host>` | \u2014 | Bind host override. With no `--server`, the broker URL is derived from it, so `--host <addr>` alone is enough to make a mesh reachable at that address; a `--host`/`--server` pair naming different addresses is refused. A wildcard bind (`0.0.0.0`, `::`) keeps a dialable loopback URL. Recorded on the mesh and reused by every later manager launch, so a repair or resume keeps remote [`attach`](#ps-stop-attach) working |\n| `--space <s>` | the folder's name | Space name |\n| `--store-dir <dir>` | \u2014 | JetStream store directory |\n| `--channels <path>` | `.cotal/channels.json` if present | Channel-registry seed file (JSON). An explicit path that is missing is an error |\n| `--restore <dir>` | \u2014 | Restore a completed offline backup before exposing the normal listener |\n| `--restore-only registry` | artifact selection | Restore only the registry component |\n| `--accept-missing-source` | off | Explicit disaster consent when the inode-bound preserved source is absent |\n| `--open` | off (auth) | Unauthenticated dev mesh: no JWT, no ACLs |\n| `--user-auth` | off | Per-user auth: people `cotal login`; connects are authorized against the actor ledger |\n| `--idp <url>` | \u2014 | With `--user-auth`: the IdP auth base URL to pin on first enable |\n| `--detach` | off | Run in the background (stop with `cotal down`) |\n| `--tls-cert <path>` | \u2014 | PEM certificate to serve TLS with. Must be given together with `--tls-key`. The pair is validated **before** the broker starts \u2014 readability, private-key mode, that the two match, the validity window, and that the certificate covers the host clients will dial \u2014 because `nats-server` starts happily on an expired certificate and only the client then fails. The decision is recorded, so a later bare `cotal up` after a `cotal down` keeps serving TLS rather than silently reverting to cleartext |\n| `--tls-key <path>` | \u2014 | PEM private key for `--tls-cert`. Refused if group- or other-readable (tighten to `600`) |\n| `--file <cotal.yaml>`, `-f` | \u2014 | Launch a whole mesh from a manifest |\n| `--dry-run` | off | With `-f`: print the plan, mutate nothing |\n| `--runtime <name>` | `pty` (or the manifest's, with `-f`) | Agent runtime for the mesh manager (`pty` built in; others are installed extensions, explicit-only). Resolved + probed before the broker starts; an uninstalled/unreachable runtime fails loud. With `-f`, overrides the manifest's runtime |\n| `--rotate-sys` | off | Rotate the space's system account and re-mint its two `$SYS` creds. Needs a stopped mesh; refused with `--open` |\n\n`cotal up` boots a local nats-server with JetStream and, in auth mode (the default), JWT auth and\nper-agent ACLs; `--detach` records the mesh so `cotal spawn` from any directory can find it. With no\n`--server`, it auto-selects a free port if the default address is taken; an explicit `--server`\nstays fail-loud on collision. `--detach` also brings up the control plane (delivery daemon in auth\nmode, then the manager). The `-f` form is a [manifest deploy](#manifest-deploys); see\n[Run a mesh](run-a-mesh.md).\n\n`--user-auth --idp <url>` starts the space's auth service alongside the broker (the NATS\nauth callout plus the loopback token exchange); it is torn down with `cotal down`, and a\nre-run of `cotal up` heals a dead service on a running broker. `--user-auth` and `--open`\ncontradict each other and are refused loudly; a running broker cannot change auth mode\nwithout a `cotal down` first. See [identity & auth](identity-and-auth.md).\n\n`--rotate-sys` renews the two `$SYS` credentials (`membership-observer`, `connection-evictor`).\nThey carry a 30-day expiry and nothing re-signs them in place, because the system-account seed is\nnever persisted, so they are renewed by issuing a **new system account** under the same broker\noperator and minting fresh creds against it. A plain re-`up` does **not** do this: it reuses the\nexisting trust record, and its `$SYS` creds along with it.\n\nThe rotation is safe to run on a real space, with one operational cost. The data account, the account\nsigning key, every agent credential minted from it, and the JetStream store are all untouched; what\ndies is the retired system account, and with it any out-of-band copy of the old `$SYS` creds, on every\nbroker that loads the rotated config. The cost is that **earlier full backups stop being restorable**\n(see below), so this is not a no-consequence operation. It needs the broker to restart on the rewritten\nconfig, so it runs as part of a boot:\n\n```bash\ncotal down\ncotal up --rotate-sys --detach     # agents reconnect; nothing is re-provisioned\ncotal doctor auth                  # both $SYS creds healthy again, 30 days out\n```\n\nA rotation is a stopped, fresh boot, and anything that is not one refuses it, all for the same reason\n(the on-disk material and the broker it runs on must never end up on different generations):\n\n- a live mesh, because the running broker would keep serving the retired account;\n- an open mesh, whether that comes from `--open` or from `broker.auth: false` in a manifest, which\n  has no system account at all;\n- `--restore`, because reinstating a trust root and superseding it in one command leaves no way to\n  say which authority the mesh came up on;\n- an unfinished restore or resume attempt on this root, including one `cotal up` would recover on\n  its own, because those paths can adopt a live listener and return without booting a broker;\n- a root that hosts more than one space, because the system account lives in the shared broker\n  record and a rotation would retire every tenant's, while the root holds one `$SYS` cred pair\n  pinned to one data account.\n\nTwo things to know before you run it:\n\n- **The retirement is config-load-bound.** Old `$SYS` creds are refused by any broker that loads the\n  rotated config. A stale `nats-server` still running the *previous* config in memory would keep\n  honouring them, so stop every broker for this root first. `--rotate-sys` refuses if this root's\n  mesh is recorded as running, if anything unidentified is answering at the address it was given, or\n  if the root's pid file names a live (or unreadable) process. Those are Cotal's own ownership\n  records, not a scan of the process table: a `nats-server` you started by hand against this root's\n  `server.conf` on some other port writes none of them and will not be seen. Do not run one.\n- **It invalidates earlier full backups.** A full artifact binds to the trust chain it was taken\n  against, and that commitment covers the operator JWT and the system account. Every full backup\n  taken before a rotation refuses to restore afterwards, so take a fresh `cotal backup` once the\n  rotated mesh is up. `cotal up --restore` names this case when the data account still matches.\n\nThe commit is not atomic (a trust-record write plus two credential writes), so an interrupted\nrotation leaves the record ahead of the creds. That split is detected rather than silent: every\n`cotal up` on an auth mesh, and every `cotal doctor auth`, compares each `$SYS` cred's issuer against\nthe persisted record and names the retired account. `up` warns rather than refusing, because these\ncreds power the membership graph and live eviction, both of which degrade fail-soft; the mesh is not\nworth taking down over them. Re-running the rotation heals it, at the cost of one generation.\n\nWhile those creds are expired the mesh keeps delivering messages, but the\n[membership feed](delivery-daemon.md) and live connection eviction stay down; `cotal doctor auth`\nand the manager's log both name the credential and this repair.\n\n## down\n\n```bash\ncotal down\ncotal down --preserve-state [--store-dir <dir>]\ncotal down manager [delivery auth web nats ...]\ncotal down web [--space <name>]\ncotal down -f <cotal.yaml> | --run <id> [--dry-run]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--file <cotal.yaml>`, `-f` | \u2014 | Tear down this manifest's deploy |\n| `--run <id>` | \u2014 | Tear down one `spawn -f` run by id |\n| `--space <name>` | current mesh | With components: the mesh whose target-addressed components (e.g. `web`) to stop |\n| `--dry-run` | off | Print the manifest teardown or selected components, mutate nothing |\n| `--preserve-state` | off | Bare whole stack only: fence the manager, retain principals and durable state, stop and prove the stack down, then publish `ready` |\n| `--store-dir <dir>` | `.cotal/nats` | With `--preserve-state`: the actual store path (required for a custom store) |\n\nBare `cotal down` stops the whole local stack in dependency order. Positional component names stop\nonly those self-registered local processes; for example, `cotal down manager` leaves delivery and\nthe broker running, and `cotal down web` is available when the web extension is installed. A\ncomponent that starts target-resolved (the web dashboard) is stopped the same way: `cotal down web`\nresolves the mesh exactly like `cotal web` (registry current mesh first, `--space` to name one), so\nit works from any directory; the other components always stop under the folder you run it in. The\n`-f` / `--run` forms tear down a [manifest deploy](#manifest-deploys) without stopping the whole mesh\nand cannot be combined with component names. Stopping `nats` alone is refused while an unselected\nregistered daemon is still live; include those components or use bare `cotal down`.\n\nNormal `down` remains destructive at the logical identity/durable layer. `--preserve-state` is a\ndifferent maintenance transition: it suppresses leave/deprovision cleanup, persists the manager's\nsame-principal resume inventory, stops the entire stack without removing run/auth artifacts, and\npublishes a stable inode-bound cut only after every recorded process is proven stopped and the exact\nrecorded NATS endpoint is unreachable. A missing or stale broker pidfile never counts as stopped. The\nattempt is bound durably before the manager is fenced, the resume document and attempt-bound\n`cut-intent` are fsynced before manager commit, and the manager's commitment itself is journaled\n(`cut-committed`) before any process stops. A retry after a crash at any of those boundaries reuses\nthe exact recorded attempt and finishes the remaining stop and endpoint proofs idempotently, without\nneeding the (by then intentionally dead) manager. A partial cut never publishes `ready`. It cannot\nbe combined with component names, manifest teardown, or `--dry-run`.\n\n## clean\n\n```bash\ncotal clean <history|store|all> --force\ncotal clean restore-attempt --attempt <id> --force\ncotal clean restore-fallback --attempt <id> --force\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` / `--server <url>` / `--creds <path>` | resolved mesh | `history`: target mesh |\n| `--dms` | off | `history`: also clear DM history |\n| `--store-dir <dir>` | `.cotal/nats` | `store`/`all`: JetStream store directory |\n| `--force` | \u2014 | Required: destructive, no prompting |\n| `--attempt <id>` | \u2014 | `restore-attempt`: exact stale pre-commit attempt; `restore-fallback`: matching healthy committed restore |\n\nOne configurable cleanup verb; every target requires `--force`.\n\n- `history` purges the retained message backlog on the **running** broker (channels, plus DMs\n  with `--dms`). The same operation as [`history clear`](#history), which stays as an alias.\n- `store` deletes the **stopped** mesh's JetStream store (`.cotal/nats`): streams, durable\n  consumers, and messages. This is the reset for stale on-disk broker state, e.g. durables\n  minted by an older, incompatible Cotal generation surviving a `down`/`up` cycle.\n- `all` is `store` plus the space identity (`.cotal/auth`), the local creds and markers tied to\n  it, any crash residue a normal `down` would have swept (stale pidfiles, `run/`), and the mesh's\n  registry entry; the next `cotal up` mints a fresh identity.\n\n`history` needs the mesh up; `store` and `all` refuse while any recorded mesh process is still\nalive or any same-root recorded broker endpoint remains reachable (run `cotal down` first). They\nalso refuse outright on a root that holds accounts for several spaces: the store and the broker\ntrust record are shared by every space on the broker, so both targets would take out all of them\nand no `--space` can narrow that. `down`, `backup` and `up --restore` refuse there for the same\nreason. `cotal status` lists the tenants on such a root. Personas\n(`.cotal/agents`) and logs are never touched. A custom\nstore location is not recorded anywhere, so `--store-dir` must repeat whatever the mesh was\nlaunched with. Custom cleanup targets must contain either the Cotal store-generation marker or a\nreal `jetstream/` store directory; filesystem roots, project roots, and Cotal auth/maintenance trees\nare always refused.\n\n`store` and `all` also refuse every maintenance journal state. After a healthy committed restore,\n`restore-fallback` is the only supported way to remove the recorded unchanged old-store inode; it\nnever deletes the active target, requires both the exact attempt id and `--force`, and retires the\ncompleted restore journal so a later `down --preserve-state` can start a new backup cycle.\n\n## backup and restore\n\n```bash\ncotal down --preserve-state [--store-dir <dir>]\ncotal backup create <dir> [--only full|registry] [--store-dir <dir>]\ncotal up --restore <dir> [--restore-only registry] [--accept-missing-source]\n```\n\nBackup is offline-only. It requires the stable `ready` record from `down --preserve-state`, an exact\nstore match, no live recorded process, and an unreachable exact endpoint from the recorded cut.\nThat endpoint is probed immediately before cloning, so a live broker with a missing or stale pidfile\nis still refused. It claims the cut, reflink/copies the stopped source to a\nprivate attempt clone, and opens only that clone on a random loopback bootstrap broker with an\nindependent parent/deadline watchdog. It validates the canonical stream and pull-consumer inventory,\nwrites native snapshots with consumers excluded, and stores conservative contiguous ACK-floor\ncheckpoints separately. The original store is never opened by the backup broker, and the stack is\nnot restarted implicitly. Artifact destinations must not overlap the preserved source or maintenance\nattempt tree. Restore artifacts and targets likewise cannot nest inside or contain each other, the\npreserved source, or the maintenance attempt tree.\n\n`full` is the default and indivisible: channel registry, CHAT/DM/TASK/INBOX/DLV, ACL, MEMBERS, and\nvalidated durable checkpoints. `registry` is the sole partial artifact. Presence, derived membership\nfeed, leases, native ephemeral/history consumers, credentials, keys, tokens, owner secrets, and actor\nledger files are excluded. Artifacts are exclusively created `0700`; snapshot/checkpoint files and\nthe manifest are `0600`; `manifest.json` is written last with exact sizes and SHA-256 values. The\ndirectory is trusted operator input: hashes detect corruption, not malicious rewriting.\n\nRestore validates and stages the exact allowlisted artifact bytes before moving or creating a store.\nIt requires the same space and existing trust state. The whole pre-commit window holds a journaled\nliveness claim (coordinator, watchdogs, brokers, absolute deadline): ordinary `up` and a repeated\n`up --restore` refuse while the claim is live, and a stale attempt is recovered only after the\ndeadline has elapsed and every recorded owner is proven dead \u2014 automatically by a retried\n`up --restore`, or explicitly with `cotal clean restore-attempt --attempt <id> --force`. Nothing\never rolls back a live attempt. A registry-only artifact restores as registry-only whether or not\n`--restore-only registry` is passed; omitted infrastructure is always created and the exact\npost-restore stream inventory is asserted before commit intent. Ordinary `up` from a preserved cut\nresumes only the exact recorded source store and runtime; a contradicting `--store-dir` or\n`--runtime` fails in preflight. Authenticated restores validate the complete\nspace trust bundle before staging, including nkeys, seed matches, JWTs, signers, and space binding;\nfull restores commit to the validated operator, system-account, data-account, and active-signer root\nchain in addition to the static/user authority fingerprint. Because the system account is part of that\ncommitment, a [`cotal up --rotate-sys`](#up) makes every full artifact taken before it unrestorable\nagainst this root: take a fresh full backup after each rotation. The composed commitment is revalidated\nimmediately before store mutation and never includes secret seeds. Restore never creates fresh auth.\nSame-path restores atomically retain the old\nsource at the journaled fallback path; alternate targets retain it in place; a missing canonical\nsource needs explicit `--accept-missing-source`. Quarantine and target restores use current canonical\nconfigs on isolated random-loopback brokers, never expose native snapshot consumers, and publish a\ncommit-intent immediately before the normal listener starts. Archive bytes never instantiate the real\ntarget: after quarantine validation, every stream is re-snapshotted from the validated quarantine\nstate into attempt-owned sanitized files, and the target is restored solely from those. Before that boundary, failure rolls back\nthe attempt-owned target; after it, ambiguity preserves both stores and records forward-repair\nrecourse. The cooperative maintenance lock excludes Cotal commands, not arbitrary raw NATS processes.\n\nBootstrap brokers in every auth mode \u2014 including open \u2014 mount the store under a local account with\nrandom operation-specific logins only, each carrying the exact per-phase subject permission matrix;\nnormal static credentials and user-auth sentinel/bearer connections are rejected, and no auth\nservice or callout starts. Open mode differs only in its account label, never in authority. Inventory, each stream snapshot,\nrestore initiation, exact upload id, validation, and each checkpoint recreation use separate exact\nauthorities. Every checkpoint carries the source stream's message/first/last sequence state and must\nmatch its snapshot record before mutation; core then derives and validates the only allowed start\npolicy. TASK is not a CLI exception: the same core checkpoint API recreates its canonical `DeliverAll`\nWorkQueue durable because acknowledged tasks are absent from retention and NATS forbids a\nstart-sequence policy there. Registry-only restore creates every omitted canonical stream and transient\nbucket on the isolated target before the normal listener is exposed. It deliberately does not resume\nretained agents or recreate their DM/DLV/TASK/ACL state; their identity material stays retained and\nstopped rather than being reprovisioned into a partial restore.\n\nAfter listener readiness, the manager starts attempt-bound, validates retained credentials/tokens\nwithout granting or reprovisioning, and resumes the exact persisted principals under cleanup\nsuppression. Registry-only restore uses the same flow with an empty agent set. `commitResume` is an\nidempotent validation barrier only: success must be `awaitingFinalize` with an attempt-bound 64-hex\ncommit token and does not release suppression. Under the workspace lock, the CLI first fsyncs that\nexact evidence as `manager-committed` (restore) or `resume-committed` (ordinary resume), then calls\ntoken-bound `finalizeResume`; only an `active` response for the exact token releases suppression. The\nCLI records the same token in finalization evidence before a restore becomes `active`, or before an\nordinary resume retires and consumes the marker. Re-entry from either committed state skips the prior\nidempotent activation/commit phases, retries finalization with the durable token, and finishes the\nworkspace transition. Failure before finalization preserves the committed state and cleanup\nsuppression; it is not rewritten through a degraded transition. Re-entry between any two earlier\nboundaries reuses the same attempt and may retry the idempotent phases without deleting retained state. A missing or\nchanged per-agent dependency is a named fail-closed result; the journal becomes degraded and remains\navailable for forward repair. A retry from `resume-intent`,\n`resume-active`, or `resume-degraded` reuses the same attempt and inventory after the prior listener is\nproven stopped. Every normal restore listener has an unguessable attempt-bound NATS server name. The\nCLI fsyncs its exact name/nonce, canonical endpoint, process owner, and generation-bound target identity\nimmediately after spawn. Re-entry accepts a surviving listener only when its INFO server name, live PID\nrecord, endpoint, and target identity all match that proof; degraded restore repair then moves through\nthe guarded workspace transition only after manager commit. If an uncommitted bound owner is provably\ndead, recovery retires that exact proof under the maintenance lock and binds a fresh listener for the\nsame attempt, endpoint, and target with a new nonce and server name. A live foreign/mismatched listener\nor ambiguous owner is preserved and refused, never adopted by reachability alone. A reconstructed\ncommit/degraded attempt without either the exact bound proof or a durable dead-listener replacement\nrecord fails closed even when the recorded port is free. A later ordinary startup may pass an `active`\nrestore only when its details prove manager commit and its exact recorded listener is dead.\n\n## meshes, use, status\n\n```bash\ncotal meshes\ncotal meshes add                      # guided, on a terminal\ncotal meshes add <space> --server <url> [--root <dir>] [--mode auth|open] [--force]\ncotal meshes rm <space> [<space> \u2026] [--force]\ncotal use <space>\ncotal status [--space <s>] [--server <url>]\n```\n\n`meshes` lists the meshes this machine knows; a `*` marks the `current` default a bare\n`cotal spawn` joins.\n\nRun on a terminal with the space or `--server` missing, **`meshes add` is guided**: it asks for the\none thing that cannot be derived (the broker URL), probes it, and tells you what answered - open or\nrequiring credentials. It then offers the spaces your `--root` already holds credentials for, states\nthe mode as a fact about that broker rather than asking, and shows the exact record before writing\nanything. A broker that does not answer, or a space name already registered, becomes a choice rather\nthan an error. Anything you pass on the command line is taken as given and not asked again. Without\na terminal - a script, an agent, CI - nothing prompts and the flag form's errors stand\n(`COTAL_NO_PROMPT=1` forces that too).\n\n`cotal up` and `cotal down` maintain their own records. `meshes add` registers a mesh they cannot\nspeak for: one running on another machine, a shared broker, a hosted space. `--root` is the folder\nwhose `.cotal/auth` holds that mesh's credentials and whose `.cotal/agents` holds its personas\n(default: the project you run it in) \u2014 the registry stores that path, never a secret. `--mode`\ndefaults to `auth` when the root holds the space's account record and to `open` otherwise; a\nuser-auth space cannot be registered by hand, because its IdP pins are trust that only\n`cotal up --user-auth` establishes. The broker is probed before anything is recorded, so a wrong\naddress, or credentials that mesh will not accept, fails here instead of at the first `spawn`;\n`--force` records without verifying (and replaces an existing record).\n\n`meshes rm` drops records \u2014 it never stops a mesh. For a mesh running on this machine `cotal down`\nis the right verb, and `rm` says so unless you pass `--force`. A record you added by hand is only\nremoved by something that names it \u2014 `meshes rm`, or an `add --force` replacement \u2014 or by a\n`cotal up` that actually starts the broker for that same space, server and root, which becomes that\nmesh and so takes the record over (a `cotal up` for that space anywhere else refuses instead).\nNothing that merely *infers* a record is stale touches it: an\nunreachable broker is listed `offline` and stays, and `cotal down` / `cotal clean all` leave it\nalone even when it shares a root with the project they are tearing down, because nothing on this\nmachine could write it back.\n\n`use <space>` sets that default; the selection applies from every directory,\nincluding inside another mesh's project. `status` is a read-only report: machine prerequisites\n(starting with the installed `cotal-ai` version), the installed extensions and their versions, this\nfolder's `.cotal/`, the recorded meshes, and a live snapshot of the selected mesh (roster, channels,\nmembership feed). `status` takes only `--space` / `--server` to pick the mesh to inspect; it starts\nnothing.\n\n## spawn\n\n```bash\ncotal spawn [<persona>] [--detach] [--name <n>] [--agent <a>] [--model <m>] [--variant <v>] [--prompt <text>] [--cwd <dir>]\ncotal spawn -f <cotal.yaml> [--dry-run]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` | resolved mesh | Target space |\n| `--server <url>` | registry entry | Broker URL override |\n| `--creds <path>` | \u2014 | Control-caller creds for an off-registry manager (`--detach` only) |\n| `--name <n>` | persona's `name:` | Presence-name override (does not choose the persona) |\n| `--config <persona-or-path>` | \u2014 | Persona catalog name or file path; wins over the positional |\n| `--agent <a>` | `COTAL_DEFAULT_AGENT`, else `claude` | Connector type (`claude`, `opencode`, `hermes`, \u2026) |\n| `--role <r>` | persona's `role:` | Role override |\n| `--model <m>` | persona's `model:` | Model override |\n| `--variant <v>` | persona's `variant:` | Model variant override (connector-defined; e.g. OpenCode reasoning tiers) |\n| `--cwd <dir>` | this cwd | Working directory to root the agent at |\n| `--prompt <text>` | \u2014 | Initial prompt auto-submitted at start |\n| `--resume <id>` | \u2014 | Fork an existing session id into the mesh (claude only) |\n| `--events` / `--no-events` | off | Publish the session's structured event plane to its own event channel |\n| `--share-tools <sel>` | none | Share named operator MCP servers with the agent |\n| `--subscribe <a,b>` | persona's | Channel read-set override |\n| `--allow-subscribe <a,b>` | = subscribe | Read-ACL override |\n| `--allow-publish <a,b>` | deny | Post-ACL override |\n| `--detach`, `-d` | off | Launch via the manager into a detached PTY (reattach with `cotal attach`) |\n| `--on <instance>` | class anycast | With `--detach` only: pin the launch to one manager instance id (the whole id, as `ps` prints it). Refused on a foreground spawn (no manager to pin), with `-f` (a manifest deploy launches through the manager class queue), and when empty |\n| `--file <cotal.yaml>`, `-f` | \u2014 | Deploy a manifest onto the running mesh |\n| `--dry-run` | off | With `-f`: print the plan, mutate nothing |\n| `--allow-stale <a,b>` | \u2014 | With `-f`: waive named stale agents (apply-only) |\n| `--runtime <name>` | manifest's | With `-f`: override the manifest's runtime |\n\n`--events` turns on the session's **event plane**: a stream of structured events describing what\nthe agent did, rather than the prose it wrote, on a channel of its own. The channel is named after\nthe agent's principal, `events.<owner>.<actor>`, never after its display name, because two live\nagents are allowed to share a display name and would then share a stream. The launch grants publish\nrights on exactly that one channel, foreground and detached alike, and a connector that does not\npublish an event plane refuses the flag rather than starting a session whose events have nowhere to\ngo.\n\nThe flag and the grant are separate on purpose. Holding publish rights on a channel is not a request\nto publish to it, so writing an event channel into an agent file's `allowPublish` does not turn the\nplane on: only the launch does.\n\nThe persona (`--config` > positional > `COTAL_DEFAULT_PERSONA` > `default`) is loaded from the\ntarget mesh's `.cotal/agents/`; the launch flags override the file. Foreground runs the agent\nattached to your terminal; `--detach` hands the launch to the running manager. Both modes get the\ndurable backstop on a mesh that runs the delivery daemon; `--live-only` skips it for a foreground\nspawn (messages posted while it is disconnected are then not replayed). A foreground exit retires\nthe agent's creds and broker footprint, like a manager despawn. A `--detach` spawn is an\n**action**: the manager accepts it and returns the allocated identity at once, then the launch\nfollows to a terminal outcome rather than blocking (see [the control surface](control-surface.md)).\nSee [Connect Claude Code](connect-claude.md) and [Agent files](agent-files.md); `-f` is a\n[manifest deploy](#manifest-deploys). (`cotal start` was merged into `cotal spawn --detach`.)\n\n## models\n\n```bash\ncotal models [--agent <connector>] [--refresh]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` / `--server <url>` / `--creds <path>` | resolved mesh | Which manager to reach |\n| `--agent <connector>` | all registered connectors | Connector whose catalog to list |\n| `--refresh` | off | Ask the connector to refresh its provider cache |\n\nAsks the running manager for each connector's model catalog (model ids plus their variants)\nfor connectors that expose one (OpenCode today; a connector without a catalog says so). Pick a\nresult with `cotal spawn --model <provider/model> --variant <v>`.\n\n## endpoints\n\n```bash\ncotal endpoints [--space <s>] [--server <url>] [--creds <path>]\n```\n\nLists the mesh presence roster: agents, the manager, and any other protocol endpoint, with each\nendpoint's role, kind, status, and current activity. Unlike `ps`, this is a read-only presence view;\nit is not limited to child processes owned by the manager.\n\n## describe, invoke\n\n```bash\ncotal describe <endpoint>                                        [--space <s>]\ncotal invoke <endpoint> <command> [--args '<json>']              [--space <s>]\ncotal invoke <endpoint> <command> --name <agent> [--admin]       [--space <s>]\n```\n\nThe generic v0.4 service surface. `describe` resolves a registered endpoint's command set off the\nwire - the reserved `describe` command answers the registered contract digests, the schemas are\nfetched from the space's content-addressed contract store, recompiled, and verified against those\ndigests - and prints each command with its capability class and targeting shape. `invoke` calls one\ncommand by name: `--args` is a JSON object validated against the fetched input schema *before*\npublish; a targeted command takes `--name <agent>` (resolved to the agent's current principal via\n`ps`) or `--self`. `--admin` uses the admin instrument credential, whose cross-agent reach rides\nthe operator-only `any` authorization mode. Neither command has compile-time knowledge of any\nendpoint's schemas - this is the same trust chain every built-in control command now uses. Needs an\nauth mesh: the manager registers its service on both static and per-user meshes (a signed-in user\nrides their bearer; cross-agent reach needs the `admin` scope). An open mesh has no service\nregistry.\n\n## ps, stop, attach\n\n```bash\ncotal ps [--on <instance>] [--space <s>]\ncotal stop --name <n> [--on <instance>] [--space <s>]\ncotal attach --name <n> [--on <instance>] [--no-reconnect] [--space <s>]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` / `--server <url>` / `--creds <path>` | resolved mesh | Which manager to reach |\n| `--name <n>` | \u2014 | Managed agent to stop / attach (required) |\n| `--on <instance>` | class anycast (`ps`: class scatter) | Pin to one manager instance id (multi-manager space); takes the whole id as `ps` prints it, not a prefix. An empty value (`--on \"\"`, an unset shell variable) is refused, never treated as absent |\n| `--no-reconnect` (`attach`) | off | End the attach when its session ends, instead of re-establishing it. For scripts that want one run and one exit code |\n\nThese are operator clients over the running manager's control plane. `ps` prints two facts per\nmanaged agent, because they answer different questions: the process fact from the manager's own\nruntime handle (`running` with its uptime, or `exited` with how long it ran), and the mesh fact from\nthe roster (`idle` / `working` / `waiting` / `mesh offline`, or `not in roster` when the seat has no\npresence row at all: a seat that has not joined yet, or one that never did). A seat can be `running` and `mesh offline` at once: the process is alive and\nits presence has lapsed. On a user-auth mesh `ps` also renders each managed agent's last\ncredential-refresh outcome, fail-closed.\n\n**Mode split (chosen up front, never try-scatter-then-degrade):**\n\n- **Static / open mesh.** Bare `ps` is a **class scatter**: it freezes the live manager class from\n  the records registry, merges every registered instance's agents grouped and attributed per\n  instance, and a non-answering instance is shown as `registered, no answer within the deadline`\n  (never silently omitted). That label is the whole claim: the instance is registered and did not\n  answer. It does not say the host is down, because a dead host never deregisters itself and a\n  live one can be slow; if it is gone, deregister it.\n  `--on <instance>` pins the read to one exact instance id instead. A wrong pin fails loud\n  rather than falling through: a well-formed id that no live manager carries is reported as\n  `manager instance <id> did not answer` (nothing else is asked), and a credential without that\n  instance's rail is reported as refused by the broker, not as an unresponsive manager. A manager\n  that answers with a refusal is shown with its own cause; \"no manager reachable\" is said only when\n  nothing answered at all. If the scatter's own registry read fails (the freeze or the reconcile),\n  `ps` says the manager registry could not be read rather than pronouncing on the managers, which\n  may all be up.\n\n**`stop` and `attach` route by seat locality.** A seat can only be stopped or attached by the\nmanager actually running it, and the class queue does not know which one that is. So on a\nstatic/open mesh both verbs first ask every registered instance which one hosts the named seat, then\naddress that instance directly. You do not need `--on` for this \u2014 it happens by default.\n\n`--on <instance>` remains the override, for when you already know where the seat lives or the\nlookup itself is degraded. It is also the **only** route on a **user-auth mesh**: a ledger-scoped\nbearer does not hold the registry-read rows the lookup needs, so there the verbs stay on the class\nqueue unless you pin them yourself.\n\nIf the seat is found on no reachable instance, the error says so \u2014 how many managers answered, and\nwhich ones did not \u2014 rather than reporting a bare `no agent <name>`. That distinction matters\nbecause a single manager cannot tell \"hosted elsewhere\" from \"does not exist\": it answers\n`not-found` for both.\n- **User-auth mesh.** `cotal ps` reports what **one** manager knows about your agents (an `ep.one`\n  read against the manager's in-memory roster, owner-filtered). It does **not** report other\n  manager instances, and it cannot tell you that one is down \u2014 an unreachable manager is absent\n  from the list, not flagged. Completeness across a multi-manager user-auth space is not claimed.\n  A manager that does not answer fails the command outright (exit non-zero), rather than printing\n  an empty list that could be read as \"no agents\". Your ledger row needs the `admin` scope to\n  reach `ps` at all; `spawn` alone is refused by the broker (the ep tier boundary).\n\n`attach` streams and drives an agent's terminal on the `pty` runtime; detach with the escape key\n(Ctrl-] by default; see [`COTAL_DETACH_KEY`](config.md)). It does so over a one-use, holder-bound\nmesh session ([SPEC](../SPEC.md) \xA713.6): the manager replies with a signed session grant (never a\n`127.0.0.1` URL), the CLI redeems it once over the broker, and the browser console (`cotal console`)\ndrives the same session. `stop` and `attach` need a running manager to talk to. On a static mesh\nthey are cross-agent admin operations. On a user-auth mesh, your own agents (any agent under your\nowner) need only the `spawn` scope; another owner's agent needs `admin` on your ledger row\n([identity & auth](identity-and-auth.md)). Launch detached agents with [`spawn --detach`](#spawn).\n\n**`attach` reconnects when the link dies.** A session lives on a network link, and a laptop that\nsleeps, a VPN that drops or a wifi handover kills it. When that happens `attach` prints\n`[cotal: connection lost, reconnecting]` on stderr and starts asking the manager for a new session:\na fresh grant, a fresh per-session credential, a fresh connection, so every attempt re-runs the same\nauthorization the first attach did. On success it prints `[cotal: reconnected]`, the manager repaints\nthe seat's current screen the way it does for any attach, and you carry on in the same terminal.\nRetries wait 1s, 2s, 5s, 10s, then 30s, for as long as the seat exists. The detach key is read\nduring those waits, so a reconnect never traps you; it is not read across the round trip that\nhands the old session back and opens the new one, so a press inside that window takes effect when\nthe round trip returns, within seconds.\n\nIt stops on its own when reconnecting cannot help, and says why: a manager that refuses the attach\nexits non-zero with the manager's own message, and a reconnect that finds the seat no longer there\n(despawned, or its agent exited while the link was down) exits cleanly with `seat <name> is gone`.\nA refusal that could still pass, such as a manager at its session ceiling, is relayed in the\nmanager's own words while the loop keeps trying, once per refusal rather than once per attempt.\nPressing the detach key, or the agent's process exiting while you are attached, ends the attach as\nit always did. `--no-reconnect` turns all of this off and restores the single-session behaviour,\nwhich is what a script wants.\n\nEach reconnect also hands the abandoned session back to the manager, over the first link that can\ncarry the message, so an attach that flaps does not eat the manager's session slots one outage at a\ntime. If that message never gets a link, the attach says so when it ends.\n\n`attach` streams over the manager's own HTTP/WS face rather than the mesh. That endpoint binds\n**loopback by default**, so nothing is exposed by accident; `cotal up --host <addr>` passes its bind\naddress down, which is what lets you attach to an agent whose manager runs on another machine. A\nbare `cotal supervise` and an embedded manager stay machine-local. Set it directly with\n`supervise --console-host <host>`.\n\nThat address is **recorded on the mesh** and carried forward, because it is a decision rather than\nsomething later commands can work out for themselves (a broker dial address is not a manager bind\naddress). Every later manager launch for the same mesh reuses it \u2014 a same-root `cotal up` repair,\nadopting a preserved or restored listener, a `spawn -f` manifest deploy \u2014 so a manager replacement\ndoes not quietly move a reachable attach face back to loopback. Passing `--host` again overrides it,\nso you can widen or narrow exposure whenever you like; a mesh that never asked stays loopback-only\nand records nothing.\n\nBecause that face carries terminal read and write for every managed agent, it is credentialed in two\ntiers. A mesh caller receives a **ticket** bound to the single agent the manager just authorized,\nsingle-use and short-lived, so one authorized attach can never be re-pointed at someone else's\nagent. The **console token** is the operator's own, reaches every agent, and is printed only to the\nmanager's output. The roster, the live feed, and the PTY stream all answer `401` without one; the\nstatic console shell is served openly, since it describes no agent.\n\n## input\n\n```bash\ncotal input --name <n> --text <text> [--no-enter] [--on <instance>] [--space <s>]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` / `--server <url>` / `--creds <path>` | resolved mesh | Which manager to reach |\n| `--name <n>` | | Managed agent to type into (required) |\n| `--text <text>` | | The text to type, taken verbatim (required) |\n| `--no-enter` | off | Type the text and stop there, without pressing Enter |\n| `--on <instance>` | class anycast | Pin to one manager instance id, exactly as [`attach`](#ps-stop-attach) |\n\nTypes one line into a running agent's terminal, as if you had typed it there, and returns. This is\nthe half of [`attach`](#ps-stop-attach) that a program wants: `attach` is a live stream that holds a\nsession open and expects a terminal on your side, so a script, a cron job or a web UI cannot use it\nto send a single line. `input` is one authorized call.\n\nWhat it is for is **harness commands**. A line beginning with `/` is not chat and not a message: it\nis something the agent's own harness handles, and the only way in is the keyboard.\n\n```bash\ncotal input --name reviewer --text \"/compact\"          # ask the harness to compact its context\ncotal input --name reviewer --text \"/model opus\"       # switch its model\ncotal input --name reviewer --text \"hold on that PR\"   # ordinary typing works too\n```\n\n**Quoting.** `--text` takes a value, so a payload starting with `/` survives as written. A payload\nstarting with a dash needs the `=` form, because the shell-style `--text --foo` is ambiguous and is\nrefused rather than guessed:\n\n```bash\ncotal input --name reviewer --text=--verbose          # dash-leading text: use --text=<value>\n```\n\nEnter is pressed by default, since a command typed but never submitted has not been delivered.\n`--no-enter` types the text and leaves it sitting at the prompt, which is how you stage a line and\nsend it later.\n\nNothing comes back but a delivery receipt (`\u2713 sent 9 bytes to reviewer`, counting the trailing\ncarriage return). Whatever the agent does next shows up where its output already goes: the mesh, its\ntranscript, or an `attach`.\n\n**This one is operator-only, and more narrowly than `stop` or `attach`.** Those two are granted to\nanything holding `spawn`, so an agent can stop and attach to seats under its own owner. `input` is\nnot: it is granted only to operator credentials, which on a user-auth mesh means your ledger row\nneeds the `admin` scope, the same scope [`ps`](#ps-stop-attach) already needs there. The reason is\nthat a write into a terminal is control of whatever is running in it, and on a user-auth mesh the\nown-owner rule covers every seat under you, not only the ones you launched: a `spawn`-scoped agent\ncould otherwise type into a sibling it never started. Seat locality is still resolved for you.\n\nOnly the `pty` runtime can be typed into. The external terminal runtimes (`tmux`, `cmux`, `orca`,\n`herdr`) attach to a process they do not own, so they have no input stream for it and the command\nrefuses by name rather than dropping the keystroke.\n\n## personas\n\n```bash\ncotal personas list [-v] [--running]\ncotal personas show <name>\ncotal personas edit <name>\ncotal personas new <name> (--prompt <t> | --from <f>) [--role <r>] [--model <m>]\ncotal personas rm <name> --force\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` / `--server <url>` / `--creds <path>` | resolved mesh | Which mesh's persona catalog |\n| `--role <r>` | \u2014 | `new`: the persona's role |\n| `--model <m>` | \u2014 | `new`: the persona's model |\n| `--prompt <t>` | \u2014 | `new`: the persona's prompt text |\n| `--from <f>` | \u2014 | `new`: seed the prompt from a file |\n| `--verbose`, `-v` | off | `list`: include role / model / description |\n| `--running` | off | `list`: mark personas live on the mesh |\n| `--force` | \u2014 | `rm`: required, delete without prompting |\n\nPersonas are the local agent files under `.cotal/agents/` that `cotal spawn` launches. See\n[Agent files](agent-files.md) for the file format.\n\n## supervise\n\n```bash\ncotal supervise [--runtime <name>] [--space <s>] [--server <url>] [--spawn <names>]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` | this folder's auth space | Space to supervise |\n| `--server <url>` | the local mesh | Broker URL |\n| `--runtime <name>` | `pty` | Agent runtime (`pty` built in; extension runtimes are explicit-only) |\n| `--console-port <n>` | \u2014 | Protocol-console port |\n| `--console-host <host>` | loopback | Bind host for the console + attach endpoint. Loopback keeps it machine-local; `cotal up` passes the address it bound the broker to, which is what lets `cotal attach` reach this manager from another machine |\n| `--roster <file>` | \u2014 | Declarative roster to boot at startup |\n| `--launch <spec>` | \u2014 | Resolved manifest launch spec (from `up -f` / `spawn -f`) |\n| `--spawn <names>` | \u2014 | Comma-separated personas to pre-spawn at startup |\n\nThe manager is the agent supervisor and control plane: it answers `spawn --detach`, `stop`, `ps`,\n`attach`, and the `cotal_*` manager tools. `cotal up --detach` starts one for you; run `supervise`\ndirectly to recover a dead manager or drive a custom runtime. Default runtime is `pty`; install an\noptional provider first (`cotal ext add @cotal-ai/orca`, `@cotal-ai/tmux`, `@cotal-ai/cmux`, or `@cotal-ai/herdr`) and\nselect it explicitly. A missing provider or app fails loudly; there is no fallback. See [Deploy](deploy.md).\n\n## reconcile-gate\n\n```bash\ncotal reconcile-gate [--space <s>] [--server <url>] [--endpoint <e>] [--instance <id>]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` | this folder's auth space | Space the frozen gate lives in |\n| `--server <url>` | the local mesh | Broker URL |\n| `--endpoint <e>` | `manager` | Endpoint whose gate is frozen |\n| `--instance <id>` | this folder's persisted manager instance | Instance id |\n\n**When you need this.** A manager restart killed partway through \u2014 after it began deregistering,\nbefore the new incarnation finished \u2014 leaves the endpoint's issuance gate *frozen*, held by a\nprocess that no longer exists. The next manager start refuses to proceed, which is correct: the\nfreeze is what stops two incarnations serving at once. But nothing can lift it, so every restart\nfails the same way. `cotal doctor` shows the gate as frozen; the manager's own start logs name the\ngate it could not advance.\n\nThis command is the way out. It checks that the holder really is gone, prints what it found, and\nthen finishes the dead operation exactly as the interrupted restart would have: revoke the old\ncredentials, evict their holders with verification, and reopen the gate. Start the manager\nafterwards and its normal takeover runs end to end.\n\n**It refuses far more often than it acts, on purpose**, and always says which check stopped it:\n\n| Refusal | What it means | What to do |\n|---|---|---|\n| `holder-alive` | The freeze-holder still has a live connection \u2014 a manager *is* running | Stop that process first. Reconciling would evict a live manager's credentials |\n| `holder-unknown` | The connection sweep could not prove the holder absent | Not safe to proceed: an unprovable holder is treated as a live one. Re-run once the broker answers completely |\n| `liveness-unestablishable` | The delivery daemon could not be asked at all | Start it (`cotal up` runs it) and re-run. Silence is never read as death |\n| `not-frozen` / `no-gate` | The gate is open, or there is no gate at that coordinate | Nothing to repair \u2014 check `--endpoint` / `--instance` |\n| `wrong-op-kind` | Frozen under a takeover or retirement, not a registration | Out of scope for this command; it will not reinterpret another operation's intent |\n| `eviction-unverified` | The holder looked gone but eviction could not be verified | The gate is left frozen, unchanged. Investigate the broker before retrying |\n| `raced` | A newer manager moved the gate mid-repair | Re-run `cotal doctor` and look again |\n\nThere is no `--force`, and no path that discards gate state: the only way this reopens a gate is by\nproving the holder is gone and then completing the operation properly.\n\n## deregister-instance\n\n```bash\ncotal deregister-instance [--space <s>] [--server <url>] [--endpoint <e>] [--instance <id>]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` | this folder's auth space | Space the instance is registered in |\n| `--server <url>` | the local mesh | Broker URL |\n| `--endpoint <e>` | `manager` | Endpoint the instance serves |\n| `--instance <id>` | this folder's persisted manager instance | Instance id, the whole id as `cotal ps` prints it |\n\n**When you need this.** The service registry records *registration*, not liveness, and nothing in\nthe model expires a row. A manager that stops cleanly removes its own registration. One whose host\ndied without writing anything cannot, so its record goes on claiming a live instance forever: every\nclass scatter in that space freezes the dead slot in, and `cotal ps`, `stop` and `attach` each pay\ntheir whole deadline waiting for a machine that is never coming back. A laptop that was reimaged, a\ncontainer that was deleted, a box that will not be back on the network: those registrations have no\nother exit.\n\nThis command is that exit. It asks the instance first, and it removes a record only when the broker\naffirms the instance's own rail is empty: nothing subscribed there. Then it deletes the\nregistration's two records keys, each pinned to the revision it read, and prints what it removed.\n\n**Silence alone never passes.** An unanswered describe is what a dead host, a wedged process and a\nslow one all look like, and a hung process still holds its subscriptions, so the broker sees\ninterest on its rail. That instance is refused and the observation is printed. A dead process holds\nno connection and therefore no subscription, so a real corpse is still removed.\n\n**It refuses rather than guesses**, and says which check stopped it:\n\n| Refusal | What it means | What to do |\n|---|---|---|\n| `instance-answered` | The instance answered a pinned describe. It is alive | Nothing to repair. If it is wedged rather than gone, stop the process first; its own clean stop removes the record |\n| `instance-not-affirmed-gone` | It did not answer, and the broker did not report its rail empty, which is what a held subscription looks like: slow or hung, not affirmed gone | Nothing was removed. Stop the process; its record goes on its own clean stop, or re-run this once it is down |\n| `liveness-unestablishable` | The probe itself failed, so nothing was learned | Fix the probe's path (credential, broker) and re-run. A probe that could not run is never read as death |\n| `not-registered` | No registration at that coordinate | Check `--instance` and `--endpoint`. This takes the whole id, never a prefix |\n| `superseded` | The record moved between the read and the delete | Something is writing to it. Nothing was removed; re-observe before retrying |\n\nThere is no `--force` and no sweep: silence is not death, and a rule that removed rows on silence\nwould eventually remove a live instance that was merely slow. An operator names one instance, the\nbroker's verdict on its rail is what authorizes the removal, and the guard's job is to show them\nthey named a dead one. Removal is not a one way door either. The same instance re-registers over\nthe tombstone on its next start, under the same identity.\n\n## runtimes\n\n```bash\ncotal runtimes\n```\n\nLists every agent runtime the manager can spawn through: the built-in `pty`, the official providers\n(`orca`, `tmux`, `cmux`, `herdr`), and any custom provider installed via `cotal ext add`. Each installed\nprovider is probed so you can see what is actually reachable on this machine before selecting it:\n\n```\npty    built in\norca   installed \xB7 reachable   @cotal-ai/orca\ntmux   available \xB7 cotal ext add @cotal-ai/tmux\ncmux   available \xB7 cotal ext add @cotal-ai/cmux\nherdr  available \xB7 cotal ext add @cotal-ai/herdr\n```\n\n`installed \xB7 reachable` / `unreachable` is the provider's own `available()` probe; `available` means\nit is a known runtime you can add with the shown command. Selecting an unknown or uninstalled runtime\nvia `up`/`spawn --runtime <name>` fails loud and, for a known one, points at the exact `cotal ext add`\npackage \u2014 there is no silent fallback to `pty`.\n\n## send\n\n```bash\ncotal send dm <agent> \"<text>\"   [--space <s>] [--server <url>] [--creds <path>]\ncotal send msg <channel> \"<text>\"\ncotal send ask <role> \"<text>\"\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` / `--server <url>` / `--creds <path>` | resolved mesh | Which mesh, and (off-registry) which credential |\n\nOne-shot messaging: connect, send a single direct message (`dm`), channel post (`msg`), or role\nask/anycast (`ask`), then exit. For a running conversation, agents use the mesh tools instead\n([MCP tools](mcp-tools.md)).\n\n## channels\n\n```bash\ncotal channels list\ncotal channels set <name> [--replay | --no-replay] [--window <n>] [--desc <s>] [--instructions <s>]\ncotal channels default --replay | --no-replay\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` / `--server <url>` / `--creds <path>` | resolved mesh | Target mesh |\n| `--replay` / `--no-replay` | \u2014 | `set`/`default`: replay history to new joiners, or not |\n| `--window <n>` | \u2014 | `set`: replay window size |\n| `--desc <s>` | \u2014 | `set`: one-line channel description |\n| `--instructions <s>` | \u2014 | `set`: instructions shown to joiners |\n\nInspects and edits the channel registry: replay policy, description, and joiner instructions. ACL\nsemantics (who may read or post) are set at mint / provision time, not here; see\n[Channels and permissions](channels-and-permissions.md). On a user-auth mesh, `list` rides your\nown login as is; `set` and `default` edit the registry over a short-lived\nchannel-writer view, which needs ledger scope `admin` ([Identity & auth](identity-and-auth.md)).\n\n\n## history\n\n```bash\ncotal history clear --force [--dms] [--space <s>]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` / `--server <url>` / `--creds <path>` | resolved mesh | Target mesh |\n| `--dms` | off | Also clear DM history |\n| `--force` | \u2014 | Required: clear without prompting |\n\nPurges retained channel history; `--dms` extends it to direct-message history. An alias of\n[`clean history`](#clean). On a user-auth mesh the purge rides a short-lived purger view over\nyour login, which needs ledger scope `admin` ([Identity & auth](identity-and-auth.md)).\n\n## console\n\n```bash\ncotal console [--plain] [--space <s>]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` / `--server <url>` / `--creds <path>` | resolved mesh | Space to watch |\n| `--plain` | off | Line stream instead of the TUI |\n\nA live protocol view for a space: a lazygit-style TUI, or a plain line stream on `--plain`. On a\nuser-auth mesh it rides the read-only admin view over your login, which needs ledger scope\n`admin`. See [Watch a mesh](watch-a-mesh.md).\n\n## web\n\n```bash\ncotal web [--detach] [--port <n>] [--no-open] [--space <s>]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` / `--server <url>` / `--creds <path>` | resolved mesh | Space to serve |\n| `--port <n>` | `7799` | HTTP port |\n| `--detach` | off | Run in the background; stop with `cotal down web` or bare `cotal down` |\n| `--no-open` | off | Don't open the browser |\n\nThe browser observability dashboard: presence, channels, and a live feed. It is **not** part of\n`cotal up`: it ships inside `cotal-ai` as the `@cotal-ai/web` extension, seeded automatically on first\nrun (like the built-in connectors) so it always matches your CLI version. It self-registers `cotal web`\ninto this surface and serves\n`http://cotal.localhost:7799` (loopback; `*.localhost` resolves in Chrome/Firefox/Edge; Safari may\nneed `http://127.0.0.1:7799`). On a user-auth mesh the dashboard rides the read-only admin view\nover your login, and a channel purge asks for its own channel-purger view per click; both need\nledger scope `admin`. Detached mode re-execs the current Cotal installation, writes diagnostics to\nthe mesh root's `.cotal/web.log`, and reports success only after the HTTP server answers. It requires\na recorded mesh root, but can be launched from any directory once `cotal up` has recorded the mesh.\nSee [Watch a mesh](watch-a-mesh.md).\n\n## mint\n\n```bash\ncotal mint <name> [--profile <agent|observer|admin>] [--out <path>] [--signer]\ncotal mint <name> --provision [--role <role>] [--space <s>] [--server <url>]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--profile <agent\\|observer\\|admin>` | `agent` | Credential profile |\n| `--out <path>` | `.cotal/auth/creds/<name>.creds` | Output path |\n| `--signer` | off | Emit a stripped account-signing file instead |\n| `--force` | off | With `--signer`: overwrite an existing file |\n| `--allow-subscribe <a,b>` | the agent file's, else subscribe | Read-ACL override, **agent profile only**: `observer` and `admin` carry a fixed read set, and `mint` refuses this flag there rather than narrowing nothing |\n| `--allow-publish <a,b>` | the agent file's, else deny | Post-ACL override, **agent profile only** |\n| `--role <role>` | the agent file's | Agent profile: the anycast task queue the identity pulls (`svc_<role>`) |\n| `--provision` | off | Agent profile: also pre-create the identity's bind-only DM/deliver durables (and its role's task queue) on the live mesh, so the credential can consume |\n| `--space <s>`, `--server <url>` | the resolved mesh | With `--provision`: which mesh to provision on |\n\nMints a NATS creds file for a space in **static** auth mode, scoped to a profile and (optionally)\nexplicit read/post ACLs. `--signer` emits an account-signing file for delegating minting to another\nhost. A per-user-auth space refuses `mint`: agents there join under a logged-in user\n([`login`](#login-logout) + [`actor grant`](#actor)), never via a handed-out creds file. See\n[Identity and auth](identity-and-auth.md).\n\nA plain mint is creds only: the identity can publish within its post ACL at once, but on an authed\nmesh its DM inbox and task queue are provisioner-pre-created and bind-only, so a **consuming**\nconnect fails until they exist. `--provision` performs that pre-create in the same command (a\nprovisioner cred is minted from the space's trust material, used, and dropped), so a long-running\nclient you start yourself can receive DMs and role anycasts like a spawned seat. The command prints\nthe identity's principal (its wire id) and lifecycle uid; a consuming client passes that uid as its\n`lifecycleUid`. Agent profile only; an open mesh needs none of this (peers self-create there). The\nmesh it provisions on must be the one this folder's auth is for - same space and same account key -\nso `--provision` can never quietly mint under another root's trust material.\n\n## login, logout\n\n```bash\ncotal login --idp <auth base URL> [--client-id <id>]\ncotal logout --idp <auth base URL>\n```\n\nSigns you in to a per-user-auth mesh's IdP (device code flow) and caches the session; run it\nonce per machine. It prints your IdP subject, the id the operator grants against. After a\nlogin, every command on that mesh works under your identity: each connect takes a fresh IdP\nproof, exchanges it locally for a short-lived bearer, and is authorized against the actor\nledger at connect time. `logout` revokes the IdP session and clears the cache. See\n[identity & auth](identity-and-auth.md).\n\n## actor\n\n```bash\n# an upsert of the WHOLE row: a flag left off is the WIDE default below, not \"unchanged\"\ncotal actor grant <actor> --sub <IdP subject> [--scope a,b] [--allow-subscribe a,b] [--allow-publish a,b] [--role <r>] [--label <l>]\ncotal actor revoke <actor> (--sub <IdP subject> | --owner <u_\u2026>)\ncotal actor list\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` | the folder's | Space whose ledger to manage |\n| `--sub <subject>` | \u2014 | The IdP subject (shown by `cotal login`) the actor belongs to |\n| `--owner <u_\u2026>` | \u2014 | The derived owner token (alternative to `--sub`) |\n| `--scope <a,b>` | `spawn,role:default` | Capability scope (`''` = none; `spawn` = may run agents, `role:<r>` = may delegate role r, `admin` = cross-agent control) |\n| `--allow-subscribe <a,b>` | `>` (all channels) | Channel read ACL; the user's envelope, their agents can never read beyond it |\n| `--allow-publish <a,b>` | `>` (all channels) | Channel post ACL; also the envelope for their agents' posting |\n| `--role <r>` | \u2014 | Role (scopes the task-queue consumer) |\n| `--label <l>` | \u2014 | Display label for `actor list` (never the IdP subject) |\n\nThe actor ledger is the single authorization source of a user-auth space: no row, no access.\nA bare `grant` is the **full** envelope (all channels, may spawn); the flags narrow it. A\nre-grant **replaces the whole row**, not the one field you name, so to add a capability spell\nevery field out: the new scope plus the row's current read set, post set, role and label\n(`cotal actor list` shows what a row holds). A field left off does not stay as it was, it\nreverts to the wide default in the table above, which is how a narrow reader becomes a reader\nof every channel. `revoke` denies the next exchange and the next connect with no restart, and\nevicts the principal's live connections. Managed-agent rows\n(written by the spawn path) live in a disjoint row space this command never touches. See\n[identity & auth](identity-and-auth.md).\n\n## doctor\n\n```bash\ncotal doctor auth [--fix]\n```\n\nCredential-health diagnosis and repair for this folder's mesh: renders every managed\ncredential as healthy / near-expiry / expired and ends in `healthy` or the exact next\ncommand; `--fix` applies the repairs it can. The one surface every stale-credential error\npoints at.\n\n## join\n\n```bash\ncotal join --space <s> --name <n> [--role <r>] [--channel <c>]\ncotal join --link <url> | --token <t>\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--space <s>` / `--server <url>` / `--creds <path>` | resolved mesh | Which mesh, and which credential |\n| `--name <n>` | \u2014 | Your presence name |\n| `--role <r>` | \u2014 | Your role |\n| `--channel <c>` | \u2014 | Channel to join |\n| `--kind <k>` | `agent` | Endpoint kind |\n| `--link <url>` | \u2014 | Join link (`cotal://\u2026`) |\n| `--token <t>` | \u2014 | Join token |\n| `--lifecycle-uid <uid>` | \u2014 | Required with `--creds`: the lifecycle UID minted alongside the credential (`COTAL_LIFECYCLE_UID` works too). A credential's durable grants name exact lifecycle-keyed resources, so `join` refuses to invent one |\n| `--tls` | off | Connect over TLS |\n\nAn interactive presence: join a space under your own name and role, without launching an agent\nharness. A `--link` or `--token` supplies the where and the auth in one value. See\n[Spaces](spaces.md) and [Identity and auth](identity-and-auth.md).\n\n## Manifest deploys\n\nA `cotal.yaml` manifest declares a whole mesh (channels, personas, roles, and ACLs) in one file.\nThree commands consume it, plus a read-only validator:\n\n```bash\ncotal up -f cotal.yaml         # boot a fresh mesh from the manifest\ncotal spawn -f cotal.yaml      # deploy the manifest additively onto a running mesh\ncotal down -f cotal.yaml       # tear that deploy down (or --run <id> for one run)\ncotal topology view -f cotal.yaml   # validate + view the access graph, change nothing\n```\n\n`up -f` and `spawn -f` differ in target: `up -f` brings up a new broker and applies the manifest;\n`spawn -f` requires an already-reachable mesh and applies additively (ownership-scoped). On a\nuser-auth mesh, `spawn -f` deploys over your own login (the deployer view, gated on ledger scope\n`spawn`): the manifest's agents land under your owner, a manifest claiming another owner is\nrefused, and seeding new channels additionally needs scope `admin`. Both take\n`--dry-run` to print the plan without mutating anything. `topology` validates the manifest and\nrenders its channel / role / ACL graph. See [Define a team](define-a-team.md) and the\n[manifest reference](manifest.md).\n\n## ext\n\n```bash\ncotal ext                 # same as `list`\ncotal ext add <npm-package>\ncotal ext remove <name>\ncotal ext list\ncotal ext root            # print just the install prefix (scriptable)\ncotal ext seed [--repair|--reset|--force]\n```\n\nOperator-installed extensions: `add` installs an npm package into a cotal-owned prefix and records\nevery registry provider it contributes. Commands appear in help, completion, and dispatch; runtime\nproviders are lazy-loaded by commands such as `supervise`; local process providers participate in\n`status` and selective `down`. `remove` and `list` manage them. The `@cotal-ai/web` dashboard is the\ncanonical command/process example. Installed packages and their location are described in\n[config](config.md).\n\nBare `cotal ext` lists the inventory, headed by the install prefix. That prefix is a cotal-owned npm\nroot kept **separate** from npm's own global tree, so these packages never show up in `npm list -g` \u2014\n`cotal ext` (or the Extensions section of `cotal status`) is the canonical inventory. `cotal ext root`\nprints only the path, for scripts. The versions shown are the manifest pin recorded at add time.\n\nRemoving an extension that owns a running local process is refused with the mesh root and its\n`cotal down <component>` command; stop it first so uninstalling the package never strands a process\nwhose lifecycle provider is gone.\n\n### Built-in connectors are seeded extensions\n\nThe first-party agent connectors (`claude`, `opencode`, `codex`, `hermes`, `pi`) are not compiled into\nthe binary. They are seeded on first run through the **same** `ext add` path a third party uses, and\nappear in `cotal ext list` like any other extension. So you can remove one you do not want\n(`cotal ext remove @cotal-ai/connector-hermes`), and a deliberately-removed connector STAYS removed\nacross upgrades. `cotal ext add <your-package>` adds a third-party connector the same way. The web\ndashboard (`@cotal-ai/web`, providing `command:web`) is a fifth built-in seeded on the same path.\n\n`cotal ext seed` is the maintenance entry for that seeding (it runs automatically on the first real\ncommand of each boot, so you rarely call it):\n\n| Flag | Meaning |\n|---|---|\n| (none) | Reconcile: seed any never-seeded built-in, refresh a seeded one whose version the binary bumped, leave a removed one removed. A no-op once current. |\n| `--repair` | Recover after an interrupted seed or a lost authority (rebuilds the interrupted connector; restores the removed-vs-never-seeded record from its durable backup). |\n| `--reset` | Discard the record and re-seed all six built-ins (the five connectors plus the web dashboard). **Resurrects any you removed.** Rebuilds cleanly over corrupt seed state. |\n| `--force` | Re-seed the built-ins even when the version stamp is current or a downgrade. |\n\nThe default connector for a bare `cotal spawn` (no `--agent`) is `claude`; set `COTAL_DEFAULT_AGENT`\n(e.g. `opencode`) to change it. An `--agent` naming a removed connector fails loud with the exact\n`cotal ext add` to restore it. Set `COTAL_SKIP_CONNECTOR_SEED=1` to turn off the automatic first-run\nseed/refresh entirely (for a controlled or offline setup that manages connectors by hand); `cotal ext\nseed` still runs on request.\n\n## completion\n\n```bash\ncotal completion <bash|zsh|fish|powershell>   # print a stub to eval / source\ncotal completion install [shell]              # install it persistently\n```\n\nPrints or installs shell completion. Completion candidates come from each command's declared flags\nand, where useful, live mesh state (spaces, personas, managed agents) resolved offline.\n\n## feedback\n\n```bash\ncotal feedback \"<summary>\" [--type <t>] [--email <e>] [--details <text>]\n```\n\n| Flag | Default | Meaning |\n|---|---|---|\n| `--type <t>` | \u2014 | `bug` \\| `idea` \\| `friction` \\| `praise` \\| `other` |\n| `--details <text>` | \u2014 | Longer free-form details |\n| `--severity <s>` | \u2014 | `low` \\| `medium` \\| `high` |\n| `--area <a>` | \u2014 | The part of Cotal this concerns |\n| `--email <e>` | git email | Contact email (required on the keyless public path) |\n| `--name <n>` | \u2014 | Your name (optional) |\n| `--url <url>` | keyed / public intake | Intake URL override |\n| `--key <k>` | `COTAL_FEEDBACK_KEY` | Feedback key |\n\nSends feedback to the Cotal developers. With a key (`--key` / `COTAL_FEEDBACK_KEY`) it routes to the\nkeyed beta intake; without one it goes to the public `cotal.ai` intake and requires a contact email\n(`--email` / `COTAL_FEEDBACK_EMAIL`, else your git email). Run a self-hosted intake with\n[`feedback-intake`](#server-daemons).\n\n## Server daemons\n\nTwo long-lived infra roles ship with the CLI. They are not part of everyday operation; the delivery\ndaemon comes up automatically with `cotal up --detach` in auth mode.\n\n```bash\ncotal deliver --space <s> [--server <url>] [--creds <file>]\ncotal auth-service --space <s> --server <url> [--port <n>]\ncotal feedback-intake --keys <keys.json> [--port <n>] [--creds <file>]\n```\n\n`auth-service` runs a user-auth space's identity plane (the NATS auth callout plus the\nloopback token exchange and JWKS); `cotal up --user-auth` starts and supervises it for you,\nso you run it directly only to recover one by hand.\n\n`deliver` runs the server-side Plane-3 delivery daemon: the durable backstop and membership/ACL\nauthority. It is auth-mode-only and single-instance (`--shard`/`--shards` accept only `N=1`);\n`--dev-mint` mints a scoped cred from the local signer for standalone dev. See the\n[delivery daemon](delivery-daemon.md). `feedback-intake` runs a self-hosted feedback server\n(requires `--keys` and a scoped `--creds`), announcing submissions into a space channel; flags\ninclude `--host`/`--port`, `--store`, `--space`/`--channel`, `--max-bytes`, and `--rate-limit`.\n\n## Plumbing\n\n`cotal __complete <words\u2026>` is the internal entry the shell-completion stubs call to emit candidates\nfor the current command line; you never run it directly. `cotal agent-bearer` is machine-facing\nplumbing on user-auth meshes: spawned agents exec it to print a fresh short-lived bearer from their\nspawn-time secret; you never run it directly either. (`cotal start` is a removed tombstone: it\nerrors and points you to `cotal spawn --detach`.)\n"
     },
     {
       "slug": "config",
       "title": "Configuration & environment",
       "kind": "Reference: describes the TypeScript reference implementation (the `cotal` CLI and connectors), not the wire contract.",
       "summary": "Three things configure a Cotal workstation: the config file (per-connector settings, notably which of your MCP servers get shared with spawned agents), a set of COTAL environment variables, and the\u2026",
-      "body": '# Configuration & environment\n\n> **Reference**: describes the TypeScript reference implementation (the `cotal` CLI and connectors), not the wire contract. \xB7 **For:** operators \xB7 **Wire contract:** [SPEC](../SPEC.md)\n\nThree things configure a Cotal workstation: the **config file** (per-connector settings, notably\nwhich of your MCP servers get shared with spawned agents), a set of **`COTAL_*` environment\nvariables**, and the **on-disk layout** under a project\'s `.cotal/` and your machine\'s `~/.cotal`.\nNone of these are part of the wire contract; they configure the reference implementation only.\n\n## The config file\n\nThe cotal config file carries per-connector launch settings. It is layered from two locations,\nmost-specific-wins:\n\n| Layer | Path | Scope |\n|---|---|---|\n| Base | `$XDG_CONFIG_HOME/cotal/config.json` (else `~/.config/cotal/config.json`; `%APPDATA%\\Cotal\\config.json` on Windows) | Operator-level, every space |\n| Override | `<project-root>/.cotal/config.json` | Space-local |\n\nThey merge per connector and per server name: a server in the space-local file replaces the\nsame-named server in the operator-level file; connectors or servers present in only one side are\nkept. A missing file is empty (valid); malformed JSON or a non-object top level is a loud error.\n\nToday it carries one thing: which of your personal MCP servers a connector should **share** with the\nagents it spawns. By default a spawned agent gets none: the Claude connector launches with\n`--strict-mcp-config`, dropping every ambient MCP server (they are heavy and useless to a meshed\nteammate). This file is the explicit opt-in.\n\n```json\n{\n  "connectors": {\n    "claude": {\n      "mcpServers": {\n        "github": {\n          "command": "npx",\n          "args": ["-y", "@modelcontextprotocol/server-github"],\n          "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }\n        }\n      }\n    }\n  }\n}\n```\n\nEach server is written in the de-facto `.mcp.json` shape, so you can copy an entry straight out of\nyour own Claude / VS Code / Cursor config. Secrets ride as **`${VAR}` references** (also\n`${VAR:-default}`), resolved from your environment at launch and forwarded to the child **by name**\n(never as literals) so the file stays safe to keep in `~/.config` or a gitignored `.cotal/`. Only\n`command`, `args`, `env`, `url`, and `headers` are expanded; any other key passes through verbatim.\n\n**`--share-tools` interplay**. The per-spawn selection narrows what this config declares:\n\n| `--share-tools` | Result |\n|---|---|\n| (flag absent) | Every server declared for the connector |\n| `none` or empty | Nothing |\n| `a,b` | Only those named: each **must** be declared, or the spawn fails (no silent drop) |\n\nToday only the `claude` connector consumes shared MCP servers; OpenCode inherits config through its\nown merge layer and Hermes has no MCP. See [Connect Claude Code](connect-claude.md) for the full\nsharing model.\n\n## Environment variables\n\nThese are the operator-facing variables. Most of the connector-session ones (space, name, role, \u2026)\nare set **for you** by `cotal spawn` / the manager when they launch an agent; you set them by hand\nonly when you drive a connector session yourself (e.g. your own `claude` with the plugin) or a custom\nlauncher. Comma-separated lists are trimmed.\n\n| Variable | Consumed by | Meaning | Default |\n|---|---|---|---|\n| `COTAL_SPACE` | connector session | Space to join | `demo` (or the join link\'s) |\n| `COTAL_NAME` | connector session | Presence name / identity | required (or via `COTAL_AGENT_FILE` / `COTAL_LINK`) |\n| `COTAL_ROLE` | connector session | Role | agent file\'s `role:`, else none |\n| `COTAL_SERVERS` | connector session | Broker URL(s) | the default local broker (or the link\'s) |\n| `COTAL_CREDS` | connector session | Path to a NATS creds file (auth mode) | none (open mode) |\n| `COTAL_LINK` | connector session | `cotal://token@host/space` join link: supplies server, auth, space | none |\n| `COTAL_AGENT_FILE` | connector session | Path to a persona file: supplies name, role, kind, channels | none |\n| `COTAL_SUBSCRIBE` | connector session | Active channel read set | agent file / link, else `general` |\n| `COTAL_ALLOW_SUBSCRIBE` | connector session | Read ACL (channels the agent *may* read) | = `COTAL_SUBSCRIBE` |\n| `COTAL_ALLOW_PUBLISH` | connector session | Post ACL (channels the agent *may* post to) | deny (empty) |\n| `COTAL_MODEL` | connector session | Model label (display metadata) | agent file\'s `model:`, else none |\n| `COTAL_KIND` | connector session | Endpoint kind | `agent` |\n| `COTAL_TLS` | connector session | Connect over TLS (`1`) | off |\n| `COTAL_TOKEN` | connector session | Auth token (token / open modes) | none |\n| `COTAL_CAPABILITIES` | connector session | Control-plane capabilities (e.g. `spawn`) that gate manager tools | agent file\'s `capabilities:` |\n| `COTAL_QUIET` / `COTAL_MUTED` | connector session | Per-channel attention defaults (never-wake / drop-on-receive) | agent file\'s, else none |\n| `COTAL_CHANNEL` | Claude connector | Force channel wake-nudges on (`1`) / off; set to `1` by the Claude launcher | auto-detect |\n| `COTAL_TRANSCRIPT` | connector session | Mirror this session\'s transcript to `tr-<name>` (`1`) | off |\n| `COTAL_TRANSCRIPT_DEFAULT` | manager | Default transcript-mirror for managed spawns (`1`) | off |\n| `COTAL_EVENTS_DEFAULT` | manager | Default AG-UI event plane for managed spawns (`1`) | off |\n| `COTAL_DEFAULT_AGENT` | `cotal spawn` | Default connector type for a bare spawn | `claude` |\n| `COTAL_DEFAULT_PERSONA` | `cotal spawn` | Default persona for a bare spawn | `default` |\n| `COTAL_SKIP_CONNECTOR_SEED` | boot gate | Skip the automatic built-in-connector seed/refresh on a command (`1`); `cotal ext seed` still works | off |\n| `COTAL_DETACH_KEY` | `cotal attach` | Detach escape key (`ctrl-<char>` / `^<char>`) | `ctrl-]` |\n| `COTAL_FEEDBACK_KEY` | `feedback`, connector | Beta feedback key \u2192 keyed intake | none (public intake) |\n| `COTAL_FEEDBACK_EMAIL` | `feedback`, connector | Contact email for the keyless public intake | your git email |\n| `COTAL_FEEDBACK_URL` | `feedback`, connector | Intake URL override (self-hosted) | keyed / public intake |\n| `COTAL_SKIP_ASSIST` | `setup` | Disable the interactive Claude handoff on a failed step (`1`; for CI) | off |\n| `COTAL_COMPLETE_DEBUG` | `completion` | Print completion-resolution errors to stderr | off |\n| `COTAL_SERVE_HEADLESS` | OpenCode runtime | Run the OpenCode server without a foreground TUI (`1`) | off |\n| `COTAL_HOME` | workspace | Override the machine-home dir for the **mesh registry only** (`meshes/`, `current-mesh`, onboard marker). Does **not** redirect project-root paths (`findCotalRoot` / `.cotal/broker-policy.json`, NATS store, manager/delivery state, auth). Tests that run `cotal up` must also use a temp project root with its own `.cotal/` as `cwd` | `~/.cotal` |\n\n> `--console-port` is a `cotal supervise` flag, not an environment variable; there is no\n> `COTAL_CONSOLE_PORT`.\n\n### Set by the launcher, not by you\n\nThese are wired into a spawned child\'s environment by the connector / launcher and read back inside\nthe session. They are not operator knobs; listed so you recognize them in a process listing.\n\n| Variable | Purpose |\n|---|---|\n| `COTAL_ID` | Stable agent id chosen by the launcher (static meshes) |\n| `COTAL_LIFECYCLE_UID` | The incarnation\'s lifecycle UID, minted once per spawn; the session binds its lifecycle-keyed DM/delivery/history consumers by it (its credential pins the same names). Required for an authed launch (`COTAL_CREDS` or user-mode); config parsing fails loud without it. Open mode omits it (the endpoint self-mints per session) |\n| `COTAL_OWNER` / `COTAL_ACTOR` / `COTAL_SENTINEL_CREDS` / `COTAL_BEARER_CMD` | User-auth launch identity: the agent\'s principal, its sentinel creds path, and the exec-able bearer command; all four together, mutually exclusive with `COTAL_CREDS` |\n| `COTAL_CONTROL_SOCKET` / `COTAL_CONTROL_TOKEN` | The session\'s local control endpoint (path + token) the MCP server listens on and the lifecycle hooks connect to; token is env-only, never argv or logs |\n| `COTAL_BRIDGE_SOCKET` / `COTAL_TOOLS_FILE` / `COTAL_PARENT_PID` | Hermes sidecar plumbing (bridge socket, generated tool descriptors, launcher pid to watch) |\n| `OPENCODE_CONFIG_CONTENT` | Inline OpenCode config (the injected cotal plugin, highest merge layer) |\n| `OPENCODE_DB` / `OPENCODE_HOME` / `OPENCODE_PORT` / `OPENCODE_SERVER_URL` / `COTAL_OPENCODE_*` | OpenCode server plumbing (home, port, DB, server URL) |\n\nThe launcher forwards only a fixed OS allow-list (PATH, HOME, TERM, locale, XDG/Windows config dirs,\n\u2026) plus the named model-provider key and any `${VAR}` secrets a shared MCP server references, never\nyour whole environment, so unrelated secrets don\'t bleed into spawned agents. There are also a few\ninternal timing knobs (e.g. `COTAL_MEMBERSHIP_INTERVAL_MS`, `COTAL_DELIVERY_BROKER_GONE_MS`) that you\nshould not set in normal operation.\n\n## On-disk layout\n\n### Project: `.cotal/`\n\nA project\'s state lives in `.cotal/` at the mesh root (found by walking up from the cwd, like `.git`).\n**It is gitignored**; it holds secrets and machine-local process state.\n\n| Path | What it is |\n|---|---|\n| `auth/broker.json` | Broker trust material: the operator seed and the system account (secret; the system-account signing seed is stripped before writing). One per broker, shared by every space on it |\n| `auth/account.<key>.json` | One space\'s own NATS data account and signing seed (secret). One file per space, all signed by the broker above; `<key>` is a stable, case-safe hex encoding of the space name (never the raw name, so two case-differing spaces can\'t collide) |\n| `auth/space.<key>/` | One space\'s user-auth state (IdP pin, issuer keys, owner secret, callout account), present only when that space enables per-user auth. Keyed by the same case-safe hex encoding; pre-hex layouts (`auth/<space>/`) are renamed here on first touch |\n| `auth/creds/<name>.creds` | Per-agent minted NATS credentials |\n| `auth/server.conf` | Generated nats-server config for the broker. The core renderer accepts every space on the broker; `cotal up` currently orchestrates one space per root, so it renders that one space\'s account |\n| `broker-policy.json` | Durable broker **launch** policy (TLS-required cert/key path references, or plaintext). Survives `cotal down` so a bare re-`up` cannot silently drop TLS. Under the project root \u2014 **not** under `COTAL_HOME` |\n| `agents/<name>.md` | Persona / agent files ([Agent files](agent-files.md)) |\n| `manifests/<hash>.json` | Manifest-deploy ledger (records of `up -f` / `spawn -f` runs) |\n| `config.json` | Space-local connector config (the override layer above) |\n| `nats.pid` \xB7 `nats.log` | Background nats-server pid + log |\n| `manager.pid` \xB7 `manager.log` | Manager (supervisor) pid + log; `manager.delivery-aware` marks a delivery-aware build. The manager writes the pid itself, whatever started it, and removes it on a clean stop only while it still names that process. A reader treats the record as a running manager only if the pid is alive **and** the process is a supervisor: a recycled pid belonging to something else is reported as a stale record, never signalled |\n| `delivery.pid` \xB7 `delivery.log` \xB7 `delivery.creds` | Delivery daemon pid, log, and scoped cred (auth mode) |\n| `web.pid` \xB7 `web.log` | Web dashboard pid + log |\n| `membership.json` \xB7 `membership-*.creds` | Membership feed state + its scoped creds |\n| `setup.log` | Last `cotal setup` run |\n\n### Machine: `~/.cotal`\n\nCross-project machine state, so a `cotal spawn` from any directory can find a running mesh. Location:\n`~/.cotal` on POSIX, `%LOCALAPPDATA%\\Cotal` on Windows; overridable with `COTAL_HOME`.\n\n`COTAL_HOME` overrides **this tree only** (registry + current pointer + onboard marker). It is not a\nfull workstation sandbox. Broker launch policy, the JetStream store, pidfiles, and auth live under\nthe **project** `.cotal/` found by walking up from the cwd ([Project: `.cotal/`](#project-cotal)\nabove, including `broker-policy.json` on TLS meshes). A probe that sets `COTAL_HOME` alone and runs\n`cotal up --tls-cert \u2026` from a directory whose walked root is the operator home still writes those\nproject paths on the live machine.\n\n| Path | What it is |\n|---|---|\n| `meshes/space.<key>.json` | Registry of running meshes: one file per broker `cotal up` started (server URL, root path, mode, TLS-required client intent when recorded); `<key>` is the same case-safe hex encoding of the space name, and the record\'s own `space` field is authoritative |\n| `current-mesh` | Default space a bare `cotal spawn` joins (set by `cotal use`) |\n| `onboarded.json` | First-run marker (with `ONBOARD_VERSION`) that flips setup between first-run and status-card |\n| the Claude plugin marketplace | The installed `cotal-mesh` plugin assets |\n\n### Config dir: `$XDG_CONFIG_HOME/cotal`\n\nDistinct from `~/.cotal`. Location: `$XDG_CONFIG_HOME/cotal`, else `~/.config/cotal` on POSIX, or\n`%APPDATA%\\Cotal` on Windows.\n\n| Path | What it is |\n|---|---|\n| `config.json` | Operator-level connector config (the base layer above) |\n| `extensions/` | `cotal ext` install prefix: its own npm root (`node_modules`) plus an `extensions.json` provider/command-display cache. Built-in connectors install here too, seeded on first run |\n| `seed/` | Built-in-connector seeding state: the `ever-seeded` authority (+ durable backup), the init witness, the version stamp, the crash cursor, and `store/<version>/<name>` (the stable payloads `ext add --install-links` reifies each seeded connector from) |\n\nFor how `cotal setup` populates the machine state and the plugin, and how the built-in connectors are\nseeded as removable extensions, see [setup internals](setup-internals.md).\n'
+      "body": '# Configuration & environment\n\n> **Reference**: describes the TypeScript reference implementation (the `cotal` CLI and connectors), not the wire contract. \xB7 **For:** operators \xB7 **Wire contract:** [SPEC](../SPEC.md)\n\nThree things configure a Cotal workstation: the **config file** (per-connector settings, notably\nwhich of your MCP servers get shared with spawned agents), a set of **`COTAL_*` environment\nvariables**, and the **on-disk layout** under a project\'s `.cotal/` and your machine\'s `~/.cotal`.\nNone of these are part of the wire contract; they configure the reference implementation only.\n\n## The config file\n\nThe cotal config file carries per-connector launch settings. It is layered from two locations,\nmost-specific-wins:\n\n| Layer | Path | Scope |\n|---|---|---|\n| Base | `$XDG_CONFIG_HOME/cotal/config.json` (else `~/.config/cotal/config.json`; `%APPDATA%\\Cotal\\config.json` on Windows) | Operator-level, every space |\n| Override | `<project-root>/.cotal/config.json` | Space-local |\n\nThey merge per connector and per server name: a server in the space-local file replaces the\nsame-named server in the operator-level file; connectors or servers present in only one side are\nkept. A missing file is empty (valid); malformed JSON or a non-object top level is a loud error.\n\nToday it carries one thing: which of your personal MCP servers a connector should **share** with the\nagents it spawns. By default a spawned agent gets none: the Claude connector launches with\n`--strict-mcp-config`, dropping every ambient MCP server (they are heavy and useless to a meshed\nteammate). This file is the explicit opt-in.\n\n```json\n{\n  "connectors": {\n    "claude": {\n      "mcpServers": {\n        "github": {\n          "command": "npx",\n          "args": ["-y", "@modelcontextprotocol/server-github"],\n          "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }\n        }\n      }\n    }\n  }\n}\n```\n\nEach server is written in the de-facto `.mcp.json` shape, so you can copy an entry straight out of\nyour own Claude / VS Code / Cursor config. Secrets ride as **`${VAR}` references** (also\n`${VAR:-default}`), resolved from your environment at launch and forwarded to the child **by name**\n(never as literals) so the file stays safe to keep in `~/.config` or a gitignored `.cotal/`. Only\n`command`, `args`, `env`, `url`, and `headers` are expanded; any other key passes through verbatim.\n\n**`--share-tools` interplay**. The per-spawn selection narrows what this config declares:\n\n| `--share-tools` | Result |\n|---|---|\n| (flag absent) | Every server declared for the connector |\n| `none` or empty | Nothing |\n| `a,b` | Only those named: each **must** be declared, or the spawn fails (no silent drop) |\n\nToday only the `claude` connector consumes shared MCP servers; OpenCode inherits config through its\nown merge layer and Hermes has no MCP. See [Connect Claude Code](connect-claude.md) for the full\nsharing model.\n\n## Environment variables\n\nThese are the operator-facing variables. Most of the connector-session ones (space, name, role, \u2026)\nare set **for you** by `cotal spawn` / the manager when they launch an agent; you set them by hand\nonly when you drive a connector session yourself (e.g. your own `claude` with the plugin) or a custom\nlauncher. Comma-separated lists are trimmed.\n\n| Variable | Consumed by | Meaning | Default |\n|---|---|---|---|\n| `COTAL_SPACE` | connector session | Space to join | `demo` (or the join link\'s) |\n| `COTAL_NAME` | connector session | Presence name / identity | required (or via `COTAL_AGENT_FILE` / `COTAL_LINK`) |\n| `COTAL_ROLE` | connector session | Role | agent file\'s `role:`, else none |\n| `COTAL_SERVERS` | connector session | Broker URL(s) | the default local broker (or the link\'s) |\n| `COTAL_CREDS` | connector session | Path to a NATS creds file (auth mode) | none (open mode) |\n| `COTAL_LINK` | connector session | `cotal://token@host/space` join link: supplies server, auth, space | none |\n| `COTAL_AGENT_FILE` | connector session | Path to a persona file: supplies name, role, kind, channels | none |\n| `COTAL_SUBSCRIBE` | connector session | Active channel read set | agent file / link, else `general` |\n| `COTAL_ALLOW_SUBSCRIBE` | connector session | Read ACL (channels the agent *may* read) | = `COTAL_SUBSCRIBE` |\n| `COTAL_ALLOW_PUBLISH` | connector session | Post ACL (channels the agent *may* post to) | deny (empty) |\n| `COTAL_MODEL` | connector session | Model label (display metadata) | agent file\'s `model:`, else none |\n| `COTAL_KIND` | connector session | Endpoint kind | `agent` |\n| `COTAL_TLS` | connector session | Connect over TLS (`1`) | off |\n| `COTAL_TOKEN` | connector session | Auth token (token / open modes) | none |\n| `COTAL_CAPABILITIES` | connector session | Control-plane capabilities (e.g. `spawn`) that gate manager tools | agent file\'s `capabilities:` |\n| `COTAL_QUIET` / `COTAL_MUTED` | connector session | Per-channel attention defaults (never-wake / drop-on-receive) | agent file\'s, else none |\n| `COTAL_CHANNEL` | Claude connector | Force channel wake-nudges on (`1`) / off; set to `1` by the Claude launcher | auto-detect |\n| `COTAL_EVENTS` | connector session | Arm this session\'s event plane (`1`); set by the launcher for `--events` spawns | off |\n| `COTAL_EVENTS_DEFAULT` | manager | Default event plane for managed spawns (`1`) | off |\n| `COTAL_DEFAULT_AGENT` | `cotal spawn` | Default connector type for a bare spawn | `claude` |\n| `COTAL_DEFAULT_PERSONA` | `cotal spawn` | Default persona for a bare spawn | `default` |\n| `COTAL_SKIP_CONNECTOR_SEED` | boot gate | Skip the automatic built-in-connector seed/refresh on a command (`1`); `cotal ext seed` still works | off |\n| `COTAL_DETACH_KEY` | `cotal attach` | Detach escape key (`ctrl-<char>` / `^<char>`) | `ctrl-]` |\n| `COTAL_FEEDBACK_KEY` | `feedback`, connector | Beta feedback key \u2192 keyed intake | none (public intake) |\n| `COTAL_FEEDBACK_EMAIL` | `feedback`, connector | Contact email for the keyless public intake | your git email |\n| `COTAL_FEEDBACK_URL` | `feedback`, connector | Intake URL override (self-hosted) | keyed / public intake |\n| `COTAL_SKIP_ASSIST` | `setup` | Disable the interactive Claude handoff on a failed step (`1`; for CI) | off |\n| `COTAL_COMPLETE_DEBUG` | `completion` | Print completion-resolution errors to stderr | off |\n| `COTAL_SERVE_HEADLESS` | OpenCode runtime | Run the OpenCode server without a foreground TUI (`1`) | off |\n| `COTAL_HOME` | workspace | Override the machine-home dir for the **mesh registry only** (`meshes/`, `current-mesh`, onboard marker). Does **not** redirect project-root paths (`findCotalRoot` / `.cotal/broker-policy.json`, NATS store, manager/delivery state, auth). Tests that run `cotal up` must also use a temp project root with its own `.cotal/` as `cwd` | `~/.cotal` |\n\n> `--console-port` is a `cotal supervise` flag, not an environment variable; there is no\n> `COTAL_CONSOLE_PORT`.\n\n### Set by the launcher, not by you\n\nThese are wired into a spawned child\'s environment by the connector / launcher and read back inside\nthe session. They are not operator knobs; listed so you recognize them in a process listing.\n\n| Variable | Purpose |\n|---|---|\n| `COTAL_ID` | Stable agent id chosen by the launcher (static meshes) |\n| `COTAL_LIFECYCLE_UID` | The incarnation\'s lifecycle UID, minted once per spawn; the session binds its lifecycle-keyed DM/delivery/history consumers by it (its credential pins the same names). Required for an authed launch (`COTAL_CREDS` or user-mode); config parsing fails loud without it. Open mode omits it (the endpoint self-mints per session) |\n| `COTAL_OWNER` / `COTAL_ACTOR` / `COTAL_SENTINEL_CREDS` / `COTAL_BEARER_CMD` | User-auth launch identity: the agent\'s principal, its sentinel creds path, and the exec-able bearer command; all four together, mutually exclusive with `COTAL_CREDS` |\n| `COTAL_CONTROL_SOCKET` / `COTAL_CONTROL_TOKEN` | The session\'s local control endpoint (path + token) the MCP server listens on and the lifecycle hooks connect to; token is env-only, never argv or logs |\n| `COTAL_BRIDGE_SOCKET` / `COTAL_TOOLS_FILE` / `COTAL_PARENT_PID` | Hermes sidecar plumbing (bridge socket, generated tool descriptors, launcher pid to watch) |\n| `OPENCODE_CONFIG_CONTENT` | Inline OpenCode config (the injected cotal plugin, highest merge layer) |\n| `OPENCODE_DB` / `OPENCODE_HOME` / `OPENCODE_PORT` / `OPENCODE_SERVER_URL` / `COTAL_OPENCODE_*` | OpenCode server plumbing (home, port, DB, server URL) |\n\nThe launcher forwards only a fixed OS allow-list (PATH, HOME, TERM, locale, XDG/Windows config dirs,\n\u2026) plus the named model-provider key and any `${VAR}` secrets a shared MCP server references, never\nyour whole environment, so unrelated secrets don\'t bleed into spawned agents. There are also a few\ninternal timing knobs (e.g. `COTAL_MEMBERSHIP_INTERVAL_MS`, `COTAL_DELIVERY_BROKER_GONE_MS`) that you\nshould not set in normal operation.\n\n## On-disk layout\n\n### Project: `.cotal/`\n\nA project\'s state lives in `.cotal/` at the mesh root (found by walking up from the cwd, like `.git`).\n**It is gitignored**; it holds secrets and machine-local process state.\n\n| Path | What it is |\n|---|---|\n| `auth/broker.json` | Broker trust material: the operator seed and the system account (secret; the system-account signing seed is stripped before writing). One per broker, shared by every space on it |\n| `auth/account.<key>.json` | One space\'s own NATS data account and signing seed (secret). One file per space, all signed by the broker above; `<key>` is a stable, case-safe hex encoding of the space name (never the raw name, so two case-differing spaces can\'t collide) |\n| `auth/space.<key>/` | One space\'s user-auth state (IdP pin, issuer keys, owner secret, callout account), present only when that space enables per-user auth. Keyed by the same case-safe hex encoding; pre-hex layouts (`auth/<space>/`) are renamed here on first touch |\n| `auth/creds/<name>.creds` | Per-agent minted NATS credentials |\n| `auth/server.conf` | Generated nats-server config for the broker. The core renderer accepts every space on the broker; `cotal up` currently orchestrates one space per root, so it renders that one space\'s account |\n| `broker-policy.json` | Durable broker **launch** policy (TLS-required cert/key path references, or plaintext). Survives `cotal down` so a bare re-`up` cannot silently drop TLS. Under the project root \u2014 **not** under `COTAL_HOME` |\n| `agents/<name>.md` | Persona / agent files ([Agent files](agent-files.md)) |\n| `manifests/<hash>.json` | Manifest-deploy ledger (records of `up -f` / `spawn -f` runs) |\n| `config.json` | Space-local connector config (the override layer above) |\n| `nats.pid` \xB7 `nats.log` | Background nats-server pid + log |\n| `manager.pid` \xB7 `manager.log` | Manager (supervisor) pid + log; `manager.delivery-aware` marks a delivery-aware build. The manager writes the pid itself, whatever started it, and removes it on a clean stop only while it still names that process. A reader treats the record as a running manager only if the pid is alive **and** the process is a supervisor: a recycled pid belonging to something else is reported as a stale record, never signalled |\n| `delivery.pid` \xB7 `delivery.log` \xB7 `delivery.creds` | Delivery daemon pid, log, and scoped cred (auth mode) |\n| `web.pid` \xB7 `web.log` | Web dashboard pid + log |\n| `membership.json` \xB7 `membership-*.creds` | Membership feed state + its scoped creds |\n| `setup.log` | Last `cotal setup` run |\n\n### Machine: `~/.cotal`\n\nCross-project machine state, so a `cotal spawn` from any directory can find a running mesh. Location:\n`~/.cotal` on POSIX, `%LOCALAPPDATA%\\Cotal` on Windows; overridable with `COTAL_HOME`.\n\n`COTAL_HOME` overrides **this tree only** (registry + current pointer + onboard marker). It is not a\nfull workstation sandbox. Broker launch policy, the JetStream store, pidfiles, and auth live under\nthe **project** `.cotal/` found by walking up from the cwd ([Project: `.cotal/`](#project-cotal)\nabove, including `broker-policy.json` on TLS meshes). A probe that sets `COTAL_HOME` alone and runs\n`cotal up --tls-cert \u2026` from a directory whose walked root is the operator home still writes those\nproject paths on the live machine.\n\n| Path | What it is |\n|---|---|\n| `meshes/space.<key>.json` | Registry of running meshes: one file per broker `cotal up` started (server URL, root path, mode, TLS-required client intent when recorded); `<key>` is the same case-safe hex encoding of the space name, and the record\'s own `space` field is authoritative |\n| `current-mesh` | Default space a bare `cotal spawn` joins (set by `cotal use`) |\n| `onboarded.json` | First-run marker (with `ONBOARD_VERSION`) that flips setup between first-run and status-card |\n| the Claude plugin marketplace | The installed `cotal-mesh` plugin assets |\n\n### Config dir: `$XDG_CONFIG_HOME/cotal`\n\nDistinct from `~/.cotal`. Location: `$XDG_CONFIG_HOME/cotal`, else `~/.config/cotal` on POSIX, or\n`%APPDATA%\\Cotal` on Windows.\n\n| Path | What it is |\n|---|---|\n| `config.json` | Operator-level connector config (the base layer above) |\n| `extensions/` | `cotal ext` install prefix: its own npm root (`node_modules`) plus an `extensions.json` provider/command-display cache. Built-in connectors install here too, seeded on first run |\n| `seed/` | Built-in-connector seeding state: the `ever-seeded` authority (+ durable backup), the init witness, the version stamp, the crash cursor, and `store/<version>/<name>` (the stable payloads `ext add --install-links` reifies each seeded connector from) |\n\nFor how `cotal setup` populates the machine state and the plugin, and how the built-in connectors are\nseeded as removable extensions, see [setup internals](setup-internals.md).\n'
     },
     {
       "slug": "connect-claude",
       "title": "Connect Claude",
       "kind": "Guide (informative)",
       "summary": "The Claude Code connector turns a real claude session into a Cotal mesh peer.",
-      "body": "# Connect Claude\n\n> **Guide** (informative) \xB7 **For:** operators \xB7 **Prereqs:** [Quickstart](getting-started.md)\n\nThe Claude Code connector turns a real `claude` session into a Cotal mesh peer. A bundled\nplugin inside the session joins NATS, maps lifecycle hooks to presence, and exposes the\nmesh tools. Nothing wraps Claude; it is an ordinary session that happens to be on the\nmesh.\n\nThe shared mesh runtime (agent, `cotal_*` tools, hook relay) lives in\n[`@cotal-ai/connector-core`](../extensions/connector-core); this connector is the thin\nClaude-specific adapter over it. Siblings: [OpenCode](connect-opencode.md) (beta),\n[Hermes](connect-hermes.md) (alpha), [pi](connect-pi.md) (alpha); the\n[Connectors](connectors.md) matrix compares them feature-by-feature.\n\n## Set up\n\n```bash\ncotal setup      # one-time: installs the plugin, seeds one agent; launches nothing\ncotal up         # brings up the mesh + delivery daemon + a detached manager\n```\n\n`cotal setup` installs the cotal plugin (so the repo's Claude sessions get the `cotal_*`\ntools) and seeds one `default` persona; `cotal up` brings up the local stack so\n`cotal spawn --detach` / `cotal_spawn` work right away. Re-running either is idempotent.\nThe install mechanics and the invariants behind them are in\n[setup internals](setup-internals.md).\n\n`cotal setup` also installs Cotal's authored Agent Skills (`SKILL.md`, the agentskills.io format) for\ncoordinating agent teams (today `team-topology`), from one canonical source, on two channels:\n\n- **Claude Code** gets a second, skills-only plugin, `cotal-skills`, from the same `cotal-mesh`\n  marketplace, at **user scope** (machine-wide), and **independent of the mesh connector**: it carries no\n  code and no core dependency, installs whenever Claude is on `PATH` (even with the connector removed),\n  and uninstalls on its own with `claude plugin uninstall cotal-skills --scope user`. Its plugin version\n  is stamped from the running CLI release, so an upgrade + `cotal setup` runs `claude plugin update` and\n  the deployed install actually gets the new skill. `cotal setup` installs it on first run and on repeat\n  runs, so upgraders are not left behind.\n- **Every other harness** (Codex, Cursor, OpenCode, Gemini CLI, Windsurf/Devin) reads the cross-vendor\n  `~/.agents/skills/` directory convention, which has no remote index, so `cotal setup` **reconciles** it:\n  it installs/updates each Cotal skill, backs up a copy you have edited to `SKILL.md.bak` before\n  replacing it, and removes a Cotal skill that is no longer shipped. Only skills Cotal owns are touched;\n  your own or third-party skills there are left alone. `cotal status` reports whether the drop is current,\n  stale, missing, or has a retired skill to reconcile. This is the working cross-vendor path.\n\nCotal also generates an [Agent Skills discovery index](https://cotal.ai/.well-known/agent-skills/index.json)\non cotal.ai, but that RFC is still a draft with no harness consuming it yet, so it is a forward bet,\nnot a channel to rely on today.\n\n## Spawn a session\n\n```bash\ncotal spawn                 # foreground: your default agent, in this terminal\ncotal spawn dave --detach   # supervised: the manager runs it in a PTY\n```\n\nA spawn resolves a persona from `.cotal/agents/<name>.md` ([agent files](agent-files.md));\n`--model`, `--variant`, `--cwd`, `--prompt`, ACL overrides, and `--share-tools` apply to\nboth forms ([run a mesh](run-a-mesh.md) has the full resolution rules). The session joins\nwith identity from its environment and auto-registers presence by the time it is\ninteractive.\n\nInside the session, the agent orients with one read-only tool, `cotal_orientation`: its\nidentity, the channels it reads and may post to, its capabilities, the tools available,\nwho's present, and unread counts. The full tool surface is the\n[MCP tool catalog](mcp-tools.md). In auth mode the team-supervision tools\n(`cotal_spawn` / `cotal_persona`) are injected **only** for personas declaring\n`capabilities: [spawn]` (the same grant that opens the privileged control subject), so an\nagent's toolset matches what it can actually invoke. Clearing retained history is\noperator-only ([run a mesh](run-a-mesh.md)), never an agent tool.\n\n## How it binds\n\nClaude Code exposes four integration surfaces, and three of them collapse into a single\ndual-purpose MCP server:\n\n| Surface | Mechanism |\n|---|---|\n| Outbound, ambient | `http` lifecycle hooks \u2192 POST to the connector (presence, activity) |\n| Outbound, deliberate | MCP tools `cotal_send` / `cotal_dm` / `cotal_anycast` (+ `cotal_feedback`) |\n| Inbound, pull | MCP tool `cotal_inbox` (same server) |\n| Inbound, push | Channel nudge + hook drain (below) |\n\nThe manager launches the *real* `claude` (no wrapper):\n\n```\nclaude --strict-mcp-config --mcp-config '{\"mcpServers\":{\"cotal\":{\u2026}}}' \\\n       --dangerously-load-development-channels server:cotal\n# env: COTAL_SPACE, COTAL_NAME, COTAL_ROLE, COTAL_SERVERS, COTAL_CHANNEL=1\n```\n\n- **MCP isolation.** A spawned agent runs with **only** the cotal MCP server:\n  `--strict-mcp-config` ignores every other MCP source, crucially the operator's personal\n  `~/.claude.json` servers (several spawns each booting a heavy helper would starve\n  memory). Share your own servers deliberately (see below).\n- **Installed, not `--plugin-dir`.** The plugin is installed once (`claude plugin install\n  cotal@cotal-mesh --scope local`) because its hooks bind only to an *installed* plugin.\n  In a clone the marketplace is the repo's `.claude-plugin/marketplace.json`; `cotal setup`\n  (npx, no clone) materializes the same marketplace under `~/.cotal/claude-plugin/` (each plugin dir is\n  rebuilt from scratch and atomically replaced, never merged, so no stale file rides in). The\n  `cotal-skills` plugin installs from that same marketplace at user scope (`claude plugin install\n  cotal-skills@cotal-mesh --scope user`); its assets ship inside the CLI package, not the connector, and\n  its version tracks the CLI release so updates land.\n- **Identity-gated.** Connector code requires `COTAL_NAME` *or* `COTAL_LINK`. A plain\n  `claude` with no `COTAL_*` env stays inert and never joins, so your own sessions in a\n  repo do not appear as stray peers.\n- **Hands-free.** The dev-channels flag prints a one-time confirm prompt; the PTY runtime\n  auto-clears it, so a supervised launch needs no keypress.\n\nInbound mesh messages arrive in context as\n`<channel source=\"cotal\" from=\"bob\" kind=\"dm\" \u2026>\u2026</channel>`: each meta key a tag\nattribute the agent can read for routing.\n\n## How messages reach the session\n\nDurable deliveries land in the connector's inbox from JetStream consumers\n([SPEC \xA78](../SPEC.md#8-nats--jetstream-binding)); live channel traffic can instead arrive\nthrough an at-most-once core subscription. A durable message sent while the agent is busy\nor offline waits on the stream. Two things move a message from inbox to model; one\ndelivers, the other only wakes:\n\n- **Hook drain (delivery).** `SessionStart` / `UserPromptSubmit` hooks read automatic inbox items and\n  inject them as `additionalContext`. This is the single authoritative path: deterministic and works\n  on any Claude Code build. Quiet ambient is excluded and stays buffered for `cotal_inbox`.\n  A message is **acked only once the hook reply carrying it has cleared both legs of its journey**:\n  the connector's control socket to the hook process (which gives up after 2s), and the hook\n  process's own stdout to Claude Code (which it force-exits 1s after starting to write). The relay\n  sends a receipt back down the control socket from that stdout write's callback, and only on a\n  clean write \u2014 a runtime whose pipe has gone away fails it \u2014 and the connector treats that receipt,\n  not its own socket write, as delivery. So a large injection killed mid-flush, or one written to a\n  broken pipe, leaves the message un-acked and JetStream redelivers it. What this does *not* prove is\n  that Claude Code read or applied the reply: a payload small enough to fit the pipe buffer is\n  reported written the moment the kernel takes it. That residual is why the path errs toward\n  at-least-once rather than treating a confirmed write as a confirmed read. Acking when\n  the reply was merely *formatted* meant a lost reply was a lost message: it was already marked\n  handled, so its own redelivery was silently acked on arrival.\n  This errs toward **at-least-once**: if a reply lands but its confirmation does not, the batch is\n  surfaced again and flagged as a possible repeat. A duplicate injection is noise; a buried DM stops\n  the peer answering at all.\n- **Channel nudge (wake).** An arriving message fires a `notifications/claude/channel`\n  event that wakes an *idle* session into a turn, so the drain runs *now* instead of at\n  the next prompt. The nudge never acks anything. A nudge that the host rejects is retried with a\n  bounded backoff while anything is still pending \u2014 for an idle session it is the only wake source,\n  so dropping it means silence until someone types. If a nudge is lost anyway (a race in the host's\n  channel startup), JetStream redelivery re-announces the unacked durable item through the same\n  attention policy, so a durable message always wakes the session eventually. If the channel cannot\n  run at all, delivery still waits for the next hook. Live-only traffic has no durable retry.\n\n**Two priority tiers.** A *directed* message (DM, anycast, or a channel message that\n`@mentions` us) always nudges. *Ambient* channel chatter does not nudge mid-turn; it\naccumulates, and the `Stop` \u2192 idle transition fires one batch nudge so the backlog drains\ntogether.\n\n**Constraints (accepted).** Channels are a Claude Code research preview (\u2265 v2.1.80;\npermission relay \u2265 v2.1.81): Anthropic auth only, admin-enabled on Team/Enterprise, and a\ncustom channel needs the `--dangerously-load-development-channels` launch flag. The hook\ndrain does not depend on any of that; the channel only adds \"wake me when idle.\"\n\nThe same channel also relays **tool-permission requests** onto the mesh, so a peer (a\nhuman at the CLI, a policy node) can approve or deny an agent's pending tool call through\nCotal rather than a per-terminal prompt.\n\n### Attention: how much traffic wakes you\n\nAn agent picks how aggressively peer traffic reaches it with\n`cotal_status({ attention })` (three modes, orthogonal to presence):\n\n| arrival | open (default) | dnd | focus |\n|---|---|---|---|\n| directed (dm / anycast) | wake + inject | wake + inject | wake + inject |\n| channel `@mention` | wake + inject | wake + inject | ack-drop; wake to *pull*; not injected |\n| ambient channel chatter | wake when idle; hold while working | never wakes; injects next turn | ack-drop; recall via `cotal_inbox` |\n\nPer-channel overrides refine this: **quiet** (delivered, never wakes; `@mention` still\nwakes) and **muted** (dropped on receive, mentions included; DMs/anycast unaffected), set\nwith `cotal_channel_mode` or as agent-file defaults (`quiet:` / `muted:`,\n[agent files](agent-files.md)). A per-channel override is the final word for that channel.\nQuiet ambient is pull-only: it never hitchhikes on a human prompt, DM, mention, or other\nconnector-driven turn. `cotal_inbox` explicitly surfaces and clears it. A quiet-channel\n`@mention` remains automatic and injects normally.\n\nThe local inbox is bounded. On pathological overflow it evicts pull-only items before automatic\ntraffic. If the bounded live/durable classification guard also fills, the connector fails closed:\notherwise-normal ambient becomes pull-only until restart. Muted hard-drop and normal focus recall\nstill take precedence. Focus also keeps a bounded exclusion list so mode toggles cannot recall\nquiet/muted traffic; if that safety bound fills, recall skips the affected channel and reports it\nas incomplete rather than risk resurfacing excluded content.\nIf the separate hard-drop disposition guard fills, channel traffic is dropped for the rest of the\nsession rather than risk a late copy bypassing an earlier muted/focus decision; DMs and anycast are\nunaffected.\n\nAttention is **advisory UX, not a boundary**: any peer can wake a dnd/focus agent by\nnaming it, and `muted` means \"I opted out of receiving\", not \"the channel is blocked\";\nthe broker still authorizes and delivers. Focus's real effect is shrinking the\nuntrusted-ambient injection surface (only subject-authenticated dm/anycast auto-inject).\nIt resets to **open** on `SessionStart`, so a restarted agent never stays silently deaf.\nYour attention is mirrored into presence so peers can see it.\n\n## Presence mapping\n\nThe connector wires a small subset of Claude Code hooks to presence states; presence is\ncoarse, and \"what it is doing\" rides on activity updates. Presence is **advisory**: a presence\npublish that fails (the endpoint mid-reconnect, say) is swallowed and never prevents the same hook\nfrom delivering messages or flushing held ones.\n\n| Hook | \u2192 state |\n|---|---|\n| `SessionStart` | `idle` (join; surfaces the inbox; captures the live model into `meta.model` when no pin) |\n| `UserPromptSubmit` | `working` (turn starts; surfaces the inbox) |\n| `PreToolUse` | no change; records *what* is about to run, so a permission wait can name it |\n| `Notification` (permission / elicitation) | `waiting` (blocked on a human: activity leads with the pending tool, e.g. `Bash: git push \u2026`) |\n| `Stop` / `StopFailure` | `idle` (turn done / died on an API error; flushes anything held while busy) |\n| `SessionEnd` | `offline` (graceful leave) |\n\nHooks are relayed over the connector's **authenticated** local control endpoint (per-user\nsocket + per-launch token, constant-time checked), so a local process that finds the path\nstill can't drive presence or stop the agent. The full Claude Code hook-event list lives\nwith the adapter:\n[`extensions/connector-claude-code`](../extensions/connector-claude-code/README.md).\n\n## Transcript mirror\n\nA managed session mirrors its own transcript onto a per-agent channel, **`tr-<name>`**, so\npeers and cheap observer agents can read what the agent *actually* did: assistant text in\nfull, tool calls as one-liners, results truncated, thinking omitted. Gated by\n`COTAL_TRANSCRIPT` (set for managed sessions; a personal session with the plugin never\nmirrors). A `tr-` channel is a regular channel (durable, listed by `cotal_channels`,\nreadable on demand) with a rolling window, so long sessions age out early entries. In\nauth mode the launcher provisions publish rights for it alongside the agent's channels.\n\n## Resume an existing session (fork, never hijack)\n\n`--resume <session-id>` pulls an existing Claude session, its context and transcript,\ninto the mesh. It **forks**: Claude mints a *new* session id from that transcript\n(`--resume <id> --fork-session`), so the meshed agent gets its own session and the\noriginal is untouched.\n\n- `cotal spawn --resume <id>` (foreground) is the primary surface: the transcript is on\n  *your* machine, and errors are Claude's own stderr, inline.\n- `--detach --resume <id>` works, with two differences: the id resolves against the\n  **manager host's** `~/.claude` (you practically need `--cwd`), and the manager waits for\n  a real outcome; `\u2713 started` means the agent *joined the mesh*, `\u2717 exited on launch`\n  carries Claude's last output, and an uncertain launch (~30 s) is reported without\n  tearing the agent down.\n- Resume is an **operator surface only**, deliberately not exposed on MCP `cotal_spawn`\n  (a mesh peer naming host-local transcripts would widen `spawn` into transcript\n  disclosure). Only the Claude connector supports it today; OpenCode and Hermes fail loud.\n- Needs a `claude` new enough for `--resume \u2026 --fork-session` (verified on 2.1.197).\n\n## Sharing your MCP servers\n\nIsolation is the default, but a meshed teammate sometimes genuinely needs one of your own\ntools (say, web search). The opt-in is the cotal config file\n(`~/.config/cotal/config.json`, or a space-local `.cotal/config.json` layered on top):\neach entry the familiar `.mcp.json` shape, secrets written as `${VAR}` references, never\nliterals ([full format](config.md)).\n\nAt launch the connector forwards *only* the named vars the chosen servers declare and\npasses the merged config as an owner-only temp file; `--strict-mcp-config` stays on, so\nonly cotal + the explicitly shared servers load. Scope per spawn with\n`--share-tools tavily,figma` (or `--share-tools none`).\n\nTwo caveats: sharing a server grants its credential to the agent (the var lives in the\nClaude process's environment, so share only when you're fine with that teammate holding\nthe key), and memory adds up, because a heavy server boots once per spawn, multiplied\nacross a team.\n\n## Feedback\n\n`cotal_feedback` works out of the box: without a key it posts to the public intake at\n`https://cotal.ai/v1/feedback` (needs a contact email: `COTAL_FEEDBACK_EMAIL`, then\n`git config user.email`, else the agent asks). Set `COTAL_FEEDBACK_KEY=fbk_<key>` in a\nbeta tester's environment to route to the keyed intake (`Authorization: Bearer`, identity\nderived from the key); `COTAL_FEEDBACK_URL` overrides either endpoint. The CLI can send\ntoo: `cotal feedback \"<summary>\" [--type bug]`. Each submission carries\n`origin: human | agent`, whether the tester asked, or the agent auto-reported a major\nissue.\n"
+      "body": "# Connect Claude\n\n> **Guide** (informative) \xB7 **For:** operators \xB7 **Prereqs:** [Quickstart](getting-started.md)\n\nThe Claude Code connector turns a real `claude` session into a Cotal mesh peer. A bundled\nplugin inside the session joins NATS, maps lifecycle hooks to presence, and exposes the\nmesh tools. Nothing wraps Claude; it is an ordinary session that happens to be on the\nmesh.\n\nThe shared mesh runtime (agent, `cotal_*` tools, hook relay) lives in\n[`@cotal-ai/connector-core`](../extensions/connector-core); this connector is the thin\nClaude-specific adapter over it. Siblings: [OpenCode](connect-opencode.md) (beta),\n[Hermes](connect-hermes.md) (alpha), [pi](connect-pi.md) (alpha); the\n[Connectors](connectors.md) matrix compares them feature-by-feature.\n\n## Set up\n\n```bash\ncotal setup      # one-time: installs the plugin, seeds one agent; launches nothing\ncotal up         # brings up the mesh + delivery daemon + a detached manager\n```\n\n`cotal setup` installs the cotal plugin (so the repo's Claude sessions get the `cotal_*`\ntools) and seeds one `default` persona; `cotal up` brings up the local stack so\n`cotal spawn --detach` / `cotal_spawn` work right away. Re-running either is idempotent.\nThe install mechanics and the invariants behind them are in\n[setup internals](setup-internals.md).\n\n`cotal setup` also installs Cotal's authored Agent Skills (`SKILL.md`, the agentskills.io format) for\ncoordinating agent teams (today `team-topology`), from one canonical source, on two channels:\n\n- **Claude Code** gets a second, skills-only plugin, `cotal-skills`, from the same `cotal-mesh`\n  marketplace, at **user scope** (machine-wide), and **independent of the mesh connector**: it carries no\n  code and no core dependency, installs whenever Claude is on `PATH` (even with the connector removed),\n  and uninstalls on its own with `claude plugin uninstall cotal-skills --scope user`. Its plugin version\n  is stamped from the running CLI release, so an upgrade + `cotal setup` runs `claude plugin update` and\n  the deployed install actually gets the new skill. `cotal setup` installs it on first run and on repeat\n  runs, so upgraders are not left behind.\n- **Every other harness** (Codex, Cursor, OpenCode, Gemini CLI, Windsurf/Devin) reads the cross-vendor\n  `~/.agents/skills/` directory convention, which has no remote index, so `cotal setup` **reconciles** it:\n  it installs/updates each Cotal skill, backs up a copy you have edited to `SKILL.md.bak` before\n  replacing it, and removes a Cotal skill that is no longer shipped. Only skills Cotal owns are touched;\n  your own or third-party skills there are left alone. `cotal status` reports whether the drop is current,\n  stale, missing, or has a retired skill to reconcile. This is the working cross-vendor path.\n\nCotal also generates an [Agent Skills discovery index](https://cotal.ai/.well-known/agent-skills/index.json)\non cotal.ai, but that RFC is still a draft with no harness consuming it yet, so it is a forward bet,\nnot a channel to rely on today.\n\n## Spawn a session\n\n```bash\ncotal spawn                 # foreground: your default agent, in this terminal\ncotal spawn dave --detach   # supervised: the manager runs it in a PTY\n```\n\nA spawn resolves a persona from `.cotal/agents/<name>.md` ([agent files](agent-files.md));\n`--model`, `--variant`, `--cwd`, `--prompt`, ACL overrides, and `--share-tools` apply to\nboth forms ([run a mesh](run-a-mesh.md) has the full resolution rules). The session joins\nwith identity from its environment and auto-registers presence by the time it is\ninteractive.\n\nInside the session, the agent orients with one read-only tool, `cotal_orientation`: its\nidentity, the channels it reads and may post to, its capabilities, the tools available,\nwho's present, and unread counts. The full tool surface is the\n[MCP tool catalog](mcp-tools.md). In auth mode the team-supervision tools\n(`cotal_spawn` / `cotal_persona`) are injected **only** for personas declaring\n`capabilities: [spawn]` (the same grant that opens the privileged control subject), so an\nagent's toolset matches what it can actually invoke. Clearing retained history is\noperator-only ([run a mesh](run-a-mesh.md)), never an agent tool.\n\n## How it binds\n\nClaude Code exposes four integration surfaces, and three of them collapse into a single\ndual-purpose MCP server:\n\n| Surface | Mechanism |\n|---|---|\n| Outbound, ambient | `http` lifecycle hooks \u2192 POST to the connector (presence, activity) |\n| Outbound, deliberate | MCP tools `cotal_send` / `cotal_dm` / `cotal_anycast` (+ `cotal_feedback`) |\n| Inbound, pull | MCP tool `cotal_inbox` (same server) |\n| Inbound, push | Channel nudge + hook drain (below) |\n\nThe manager launches the *real* `claude` (no wrapper):\n\n```\nclaude --strict-mcp-config --mcp-config '{\"mcpServers\":{\"cotal\":{\u2026}}}' \\\n       --dangerously-load-development-channels server:cotal\n# env: COTAL_SPACE, COTAL_NAME, COTAL_ROLE, COTAL_SERVERS, COTAL_CHANNEL=1\n```\n\n- **MCP isolation.** A spawned agent runs with **only** the cotal MCP server:\n  `--strict-mcp-config` ignores every other MCP source, crucially the operator's personal\n  `~/.claude.json` servers (several spawns each booting a heavy helper would starve\n  memory). Share your own servers deliberately (see below).\n- **Installed, not `--plugin-dir`.** The plugin is installed once (`claude plugin install\n  cotal@cotal-mesh --scope local`) because its hooks bind only to an *installed* plugin.\n  In a clone the marketplace is the repo's `.claude-plugin/marketplace.json`; `cotal setup`\n  (npx, no clone) materializes the same marketplace under `~/.cotal/claude-plugin/` (each plugin dir is\n  rebuilt from scratch and atomically replaced, never merged, so no stale file rides in). The\n  `cotal-skills` plugin installs from that same marketplace at user scope (`claude plugin install\n  cotal-skills@cotal-mesh --scope user`); its assets ship inside the CLI package, not the connector, and\n  its version tracks the CLI release so updates land.\n- **Identity-gated.** Connector code requires `COTAL_NAME` *or* `COTAL_LINK`. A plain\n  `claude` with no `COTAL_*` env stays inert and never joins, so your own sessions in a\n  repo do not appear as stray peers.\n- **Hands-free.** The dev-channels flag prints a one-time confirm prompt; the PTY runtime\n  auto-clears it, so a supervised launch needs no keypress.\n\nInbound mesh messages arrive in context as\n`<channel source=\"cotal\" from=\"bob\" kind=\"dm\" \u2026>\u2026</channel>`: each meta key a tag\nattribute the agent can read for routing.\n\n## How messages reach the session\n\nDurable deliveries land in the connector's inbox from JetStream consumers\n([SPEC \xA78](../SPEC.md#8-nats--jetstream-binding)); live channel traffic can instead arrive\nthrough an at-most-once core subscription. A durable message sent while the agent is busy\nor offline waits on the stream. Two things move a message from inbox to model; one\ndelivers, the other only wakes:\n\n- **Hook drain (delivery).** `SessionStart` / `UserPromptSubmit` hooks read automatic inbox items and\n  inject them as `additionalContext`. This is the single authoritative path: deterministic and works\n  on any Claude Code build. Quiet ambient is excluded and stays buffered for `cotal_inbox`.\n  A message is **acked only once the hook reply carrying it has cleared both legs of its journey**:\n  the connector's control socket to the hook process (which gives up after 2s), and the hook\n  process's own stdout to Claude Code (which it force-exits 1s after starting to write). The relay\n  sends a receipt back down the control socket from that stdout write's callback, and only on a\n  clean write (a runtime whose pipe has gone away fails it), and the connector treats that receipt,\n  not its own socket write, as delivery. So a large injection killed mid-flush, or one written to a\n  broken pipe, leaves the message un-acked and JetStream redelivers it. What this does *not* prove is\n  that Claude Code read or applied the reply: a payload small enough to fit the pipe buffer is\n  reported written the moment the kernel takes it. That residual is why the path errs toward\n  at-least-once rather than treating a confirmed write as a confirmed read. Acking when\n  the reply was merely *formatted* meant a lost reply was a lost message: it was already marked\n  handled, so its own redelivery was silently acked on arrival.\n  This errs toward **at-least-once**: if a reply lands but its confirmation does not, the batch is\n  surfaced again and flagged as a possible repeat. A duplicate injection is noise; a buried DM stops\n  the peer answering at all.\n- **Channel nudge (wake).** An arriving message fires a `notifications/claude/channel`\n  event that wakes an *idle* session into a turn, so the drain runs *now* instead of at\n  the next prompt. The nudge never acks anything. A nudge that the host rejects is retried with a\n  bounded backoff while anything is still pending. For an idle session it is the only wake source,\n  so dropping it means silence until someone types. If a nudge is lost anyway (a race in the host's\n  channel startup), JetStream redelivery re-announces the unacked durable item through the same\n  attention policy, so a durable message always wakes the session eventually. If the channel cannot\n  run at all, delivery still waits for the next hook. Live-only traffic has no durable retry.\n\n**Two priority tiers.** A *directed* message (DM, anycast, or a channel message that\n`@mentions` us) always nudges. *Ambient* channel chatter does not nudge mid-turn; it\naccumulates, and the `Stop` \u2192 idle transition fires one batch nudge so the backlog drains\ntogether.\n\n**Constraints (accepted).** Channels are a Claude Code research preview (\u2265 v2.1.80;\npermission relay \u2265 v2.1.81): Anthropic auth only, admin-enabled on Team/Enterprise, and a\ncustom channel needs the `--dangerously-load-development-channels` launch flag. The hook\ndrain does not depend on any of that; the channel only adds \"wake me when idle.\"\n\nThe same channel also relays **tool-permission requests** onto the mesh, so a peer (a\nhuman at the CLI, a policy node) can approve or deny an agent's pending tool call through\nCotal rather than a per-terminal prompt.\n\n### Attention: how much traffic wakes you\n\nAn agent picks how aggressively peer traffic reaches it with\n`cotal_status({ attention })` (three modes, orthogonal to presence):\n\n| arrival | open (default) | dnd | focus |\n|---|---|---|---|\n| directed (dm / anycast) | wake + inject | wake + inject | wake + inject |\n| channel `@mention` | wake + inject | wake + inject | ack-drop; wake to *pull*; not injected |\n| ambient channel chatter | wake when idle; hold while working | never wakes; injects next turn | ack-drop; recall via `cotal_inbox` |\n\nPer-channel overrides refine this: **quiet** (delivered, never wakes; `@mention` still\nwakes) and **muted** (dropped on receive, mentions included; DMs/anycast unaffected), set\nwith `cotal_channel_mode` or as agent-file defaults (`quiet:` / `muted:`,\n[agent files](agent-files.md)). A per-channel override is the final word for that channel.\nQuiet ambient is pull-only: it never hitchhikes on a human prompt, DM, mention, or other\nconnector-driven turn. `cotal_inbox` explicitly surfaces and clears it. A quiet-channel\n`@mention` remains automatic and injects normally.\n\nThe local inbox is bounded. On pathological overflow it evicts pull-only items before automatic\ntraffic. If the bounded live/durable classification guard also fills, the connector fails closed:\notherwise-normal ambient becomes pull-only until restart. Muted hard-drop and normal focus recall\nstill take precedence. Focus also keeps a bounded exclusion list so mode toggles cannot recall\nquiet/muted traffic; if that safety bound fills, recall skips the affected channel and reports it\nas incomplete rather than risk resurfacing excluded content.\nIf the separate hard-drop disposition guard fills, channel traffic is dropped for the rest of the\nsession rather than risk a late copy bypassing an earlier muted/focus decision; DMs and anycast are\nunaffected.\n\nAttention is **advisory UX, not a boundary**: any peer can wake a dnd/focus agent by\nnaming it, and `muted` means \"I opted out of receiving\", not \"the channel is blocked\";\nthe broker still authorizes and delivers. Focus's real effect is shrinking the\nuntrusted-ambient injection surface (only subject-authenticated dm/anycast auto-inject).\nIt resets to **open** on `SessionStart`, so a restarted agent never stays silently deaf.\nYour attention is mirrored into presence so peers can see it.\n\n## Presence mapping\n\nThe connector wires a small subset of Claude Code hooks to presence states; presence is\ncoarse, and \"what it is doing\" rides on activity updates. Presence is **advisory**: a presence\npublish that fails (the endpoint mid-reconnect, say) is swallowed and never prevents the same hook\nfrom delivering messages or flushing held ones.\n\n| Hook | \u2192 state |\n|---|---|\n| `SessionStart` | `idle` (join; surfaces the inbox; captures the live model into `meta.model` when no pin) |\n| `UserPromptSubmit` | `working` (turn starts; surfaces the inbox) |\n| `PreToolUse` | no change; records *what* is about to run, so a permission wait can name it |\n| `Notification` (permission / elicitation) | `waiting` (blocked on a human: activity leads with the pending tool, e.g. `Bash: git push \u2026`) |\n| `Stop` / `StopFailure` | `idle` (turn done / died on an API error; flushes anything held while busy) |\n| `SessionEnd` | `offline` (graceful leave) |\n\nHooks are relayed over the connector's **authenticated** local control endpoint (per-user\nsocket + per-launch token, constant-time checked), so a local process that finds the path\nstill can't drive presence or stop the agent. The full Claude Code hook-event list lives\nwith the adapter:\n[`extensions/connector-claude-code`](../extensions/connector-claude-code/README.md).\n\n## Event plane\n\nA session launched with `cotal spawn --events` publishes a **structured** account of what it\ndid: run boundaries per turn, assistant text, reasoning, and each tool call with its arguments,\nits end, and its result. Not prose about the work, the work itself, in a vocabulary a program can\nread. Arming is `COTAL_EVENTS`, which the launcher sets for `--events` spawns; a personal session\nwith the plugin installed publishes nothing.\n\nThe channel is **`events.<owner>.<actor>`**, named after the session's principal. What the actor\nhalf is depends on the mesh, and the difference matters when you go looking for it: on a static mesh\nit is a key the manager allocated, never the display name, so two live agents sharing a display name\ndo not share a stream; on a user-auth mesh it is the agent's own name, because that is what the\nledger row is keyed on. Spelled out again with both halves below. The launch grants publish rights\non exactly that one channel. A spawn\nthat asks for a *different* agent's event channel is refused at the door rather than granted, since\nthat channel carries the session's tool inputs and outputs. The same rule runs on restart: a manager\nresume document that names another agent's event channel is refused rather than adopted, because the\nmanaged row is re-armed from that document and the credential is re-minted from the row.\n\nThe rule reads a **concrete** channel, two principal tokens and nothing else. A pattern such as\n`events.<owner>.>` is not an event channel to it and passes untouched, governed by ordinary ACL\nauthority: on a user mesh the delegation envelope, on a static mesh the spawning credential itself.\nThat is deliberate, because the pattern is the form an operator writes on purpose for an observer,\nand it is worth knowing rather than assuming the fence is total.\n\nTo let something else read a plane, grant it out of band. The refusal prints the command for the\nmesh it is running on, spelled out in full, and only that one.\n\nOn a **user-auth** mesh:\n\n```bash\ncotal actor grant <reader> --owner <owner> --scope '' --allow-subscribe 'events.<owner>.<actor>' --allow-publish ''\n```\n\nEvery field, deliberately. `actor grant` is an upsert of the whole row, and an omitted flag is not\n\"leave it alone\": it is the wide default, `>` read, `>` post, and `spawn,role:default` scope. A bare\n`cotal actor grant <reader>` therefore grants a reader of every channel in the space, which is the\nopposite of what a scoped watcher is for.\n\nOn a **static** mesh there is no actor ledger for `actor grant` to write to, and the refusal says\nso; mint the reader instead:\n\n```bash\ncotal mint watcher --profile agent --allow-subscribe 'events.<owner>.<actor>' --provision\n```\n\nThe **agent** profile, not the observer one. `mint` reads `--allow-subscribe` only for that\nprofile, and refuses it anywhere else: `--profile observer --allow-subscribe <channel>` exits\nnon-zero and writes no creds file, because the observer profile carries a fixed read set over the\nwhole chat plane, which is the opposite of what a scoped watcher is for. The agent profile also prints the lifecycle uid the\nreader needs, since an authed consuming endpoint refuses to start without one.\n\nTwo things a reader has to do that are not obvious, both on `CotalEndpoint`. It must pass the event\nchannel in `channels`, or the endpoint joins `general` by default and a scoped credential is refused\nthere. And it reads history with `readHistory(channel)`, the delivery daemon's mediated read, not\n`channelHistory(channel)`: a scoped credential is denied the ad-hoc consumer the direct read\ncreates, by design. `cotal console` and the web console already do both.\n\nThe `<owner>.<actor>` pair is the session's principal, not its display name. On a user-auth mesh\nthe actor half **is** the agent's name, so the channel is `events.<your-owner>.<agent-name>`. On a\nstatic mesh the owner half is the literal `local` and the actor is a key the manager allocated, so\nthe channel is `events.local.<key>`; the spawn reply carries that key as `id`. Note\nthat `cotal console` and the web console keep event channels out of their channel lists on purpose,\nsince a plane is a machine feed rather than a conversation; they draw the frames when you open the\nchannel by name.\n\nThe rule governs the manager's doors, which are the ones a caller other than you can reach. A\nforeground `cotal spawn` on your own machine mints from your own signing material, so it can still\ngrant any channel you name: that is the out-of-band grant, not a way around the rule.\n\nEvents are written to a per-session write-ahead log before they are published, so a hook that fires\nafter a restart resumes at the cursor it left rather than replaying or skipping, and a run that was\nopen when the session stopped is closed rather than left dangling.\n\nOne channel carries **every session of one agent**, because it is named after the principal and not\nafter the session. Alongside the per-session logs the connector keeps one small record per principal,\nholding the last sequence the broker assigned on that channel, so a new session continues the stream\nits predecessor left instead of starting again from nothing. Both live under the events state root\n(`COTAL_WORKSPACE_ROOT`), and neither is something you edit by hand.\n\nA **missing** record is not a fault: the connector rebuilds it from the session logs beside it,\nwhich is how an agent that was already running before this record existed keeps its stream. That\nrebuild stops if any one of those session logs is damaged. Unreadable, not valid JSON, and written\nfor a different principal all count, and so does a session directory or a log that is a link rather\nthan the real file the connector wrote, or a log that has more than one name. A tip taken from the\nrest would be too low, and it would stop publication later with nothing left to point at the cause.\nThe connector names the file instead, and the only way past it is the directory removal described\nbelow, under the same condition. A record that **disagrees with the broker** is a fault, and the\nconnector stops publishing and says why rather than guessing. A record that **moved while a session\nwas writing to it** is refused the same way: it means something else wrote the principal's record,\nand the connector reports which value it held and which the file holds rather than writing over the\nlater one. There is no command to clear it. The state is the principal's directory under the events\nroot, and clearing it by hand means removing that directory whole: the sequence, the cursor and the\nper-session logs only mean anything together, so removing part of it leaves a state the next start\nrefuses. Removing it is only half a remedy, and the half that comes first is the channel. The\ndirectory is where the agent's memory of the tip lives, not the tip itself, so on a channel that\nstill holds frames the next session opens expecting an empty one and stops on the same\ndisagreement, with the logs a tip could have been rebuilt from now gone. Purge the channel first,\nthen remove the directory.\n\nReading it: `cotal console` and the web console draw event frames directly. A frame carries no text\npart by design, so a surface that renders a message as flat text shows a marker instead of prose.\n\n**On a per-user-auth mesh, arming needs the spawner's grant to cover the channel.** The event\nchannel is added to the child's publish set, and delegation only narrows: an agent may hand down\na subset of what it holds and no more. So a peer-initiated `--events` spawn is refused unless the\nspawning identity's own grant already covers the child's event channel. The refusal prints the\nexact `cotal actor grant` command that widens it. An operator launch, whose chain reaches an\nadmin-scoped or roster row, is unaffected.\n\n## Resume an existing session (fork, never hijack)\n\n`--resume <session-id>` pulls an existing Claude session, its context and transcript,\ninto the mesh. It **forks**: Claude mints a *new* session id from that transcript\n(`--resume <id> --fork-session`), so the meshed agent gets its own session and the\noriginal is untouched.\n\n- `cotal spawn --resume <id>` (foreground) is the primary surface: the transcript is on\n  *your* machine, and errors are Claude's own stderr, inline.\n- `--detach --resume <id>` works, with two differences: the id resolves against the\n  **manager host's** `~/.claude` (you practically need `--cwd`), and the manager waits for\n  a real outcome; `\u2713 started` means the agent *joined the mesh*, `\u2717 exited on launch`\n  carries Claude's last output, and an uncertain launch (~30 s) is reported without\n  tearing the agent down.\n- Resume is an **operator surface only**, deliberately not exposed on MCP `cotal_spawn`\n  (a mesh peer naming host-local transcripts would widen `spawn` into transcript\n  disclosure). Only the Claude connector supports it today; OpenCode and Hermes fail loud.\n- Needs a `claude` new enough for `--resume \u2026 --fork-session` (verified on 2.1.197).\n\n## Sharing your MCP servers\n\nIsolation is the default, but a meshed teammate sometimes genuinely needs one of your own\ntools (say, web search). The opt-in is the cotal config file\n(`~/.config/cotal/config.json`, or a space-local `.cotal/config.json` layered on top):\neach entry the familiar `.mcp.json` shape, secrets written as `${VAR}` references, never\nliterals ([full format](config.md)).\n\nAt launch the connector forwards *only* the named vars the chosen servers declare and\npasses the merged config as an owner-only temp file; `--strict-mcp-config` stays on, so\nonly cotal + the explicitly shared servers load. Scope per spawn with\n`--share-tools tavily,figma` (or `--share-tools none`).\n\nTwo caveats: sharing a server grants its credential to the agent (the var lives in the\nClaude process's environment, so share only when you're fine with that teammate holding\nthe key), and memory adds up, because a heavy server boots once per spawn, multiplied\nacross a team.\n\n## Feedback\n\n`cotal_feedback` works out of the box: without a key it posts to the public intake at\n`https://cotal.ai/v1/feedback` (needs a contact email: `COTAL_FEEDBACK_EMAIL`, then\n`git config user.email`, else the agent asks). Set `COTAL_FEEDBACK_KEY=fbk_<key>` in a\nbeta tester's environment to route to the keyed intake (`Authorization: Bearer`, identity\nderived from the key); `COTAL_FEEDBACK_URL` overrides either endpoint. The CLI can send\ntoo: `cotal feedback \"<summary>\" [--type bug]`. Each submission carries\n`origin: human | agent`, whether the tester asked, or the agent auto-reported a major\nissue.\n"
     },
     {
       "slug": "connect-codex",
       "title": "Connect Codex (beta)",
       "kind": "Guide (informative)",
       "summary": "OpenAI Codex joins a Cotal mesh as a lateral peer: the same cotal tool surface, the same message delivery and attention model as the other connectors, plus mid-turn steering (previously pi-only): a\u2026",
-      "body": "# Connect Codex (beta)\n\n> **Guide** (informative) \xB7 **For:** operators \xB7 **Prereqs:** [Quickstart](getting-started.md)\n\n[OpenAI Codex](https://developers.openai.com/codex/) joins a Cotal mesh as a lateral peer: the\nsame `cotal_*` tool surface, the same message delivery and attention model as the other\nconnectors, plus mid-turn steering (previously pi-only): a directed peer message arriving\nmid-turn is **steered into the running turn** instead of waiting for it to end.\n\n**Beta** means the everyday path (spawn into the real Codex TUI, coordinate, watch) works; the\nspawn options that are not wired **fail loud** rather than degrade: resuming a session\n(`--resume`) and tool-sharing (`connectors.codex.mcpServers`). See [Limits](#limits).\n\n## Install\n\nThe connector ships with the CLI as a seeded extension (`@cotal-ai/connector-codex`): no\nseparate install step and no Codex-side plugin. You only need an authenticated `codex` binary\non your PATH (a ChatGPT-plan login or an `OPENAI_API_KEY`). If an older install is missing it,\n`cotal ext seed --repair` (or `cotal ext add @cotal-ai/connector-codex`) brings it in.\n\n**Don't install the `cotal` plugin Codex offers you.** Searching Codex's plugin list for \"cotal\"\nturns up a plugin named `cotal`, from the `cotal-mesh` marketplace. That is the **Claude Code**\nadapter, which appears there only because Codex reads the same plugin-marketplace format; it is\nnot this connector and installing it does not connect Codex to a mesh. Codex needs nothing\ninstalled on its side: the connector drives it from the outside, over `codex app-server`.\n\n**Codex version.** The connector drives `codex app-server` over its experimental v2 surface.\nMinimum **codex-cli 0.145.0**; tested against 0.145.0 and 0.146.0. An older binary authenticates fine but has\nno `--listen`/`--ws-auth` listener, so the launch fails at startup rather than misbehaving quietly:\ncheck with `codex --version` and upgrade (`npm i -g @openai/codex`) if a launch reports that the\napp-server exited before it started listening. The surface is explicitly experimental upstream, so\na later Codex release may change it and need a connector update. That is a break to report, not a\nsupport range we can promise ahead of it.\n\n## Spawn it\n\nSame launch grammar as any agent (see [run-a-mesh.md](run-a-mesh.md)):\n\n```bash\ncotal spawn --agent codex                # foreground in this terminal\ncotal spawn reviewer --agent codex -d    # detached via the manager; watch with `cotal attach`\nCOTAL_DEFAULT_AGENT=codex cotal spawn    # make codex the default harness\n```\n\nOr set `agent: codex` in a team [manifest](manifest.md). Persona, role, and model come from the\nagent file as for any connector ([agent-files.md](agent-files.md)).\n\n## Choose a model\n\n```bash\ncotal models --agent codex               # ids + reasoning-effort variants, via app-server model/list\ncotal spawn --agent codex --model gpt-5.6-sol --variant high\n```\n\nThe **variant** is Codex's reasoning effort (`minimal` | `low` | `medium` | `high` | `xhigh`).\nLike the `codex` CLI itself, the connector does not validate model ids or efforts locally. An\nunknown value fails at request time, server-side.\n\nModel and variant are published on presence, which is where `cotal roster` and the web dashboard's\n`model \xB7 variant` badge read them from. The variant appears only when you asked for one (via\n`--variant` or `variant:` in the agent file): there is no way to read the effort back off a running\nthread, so an unset variant is shown as absent rather than guessed at.\n\n## How it binds\n\nCodex has no in-process plugin runtime and its MCP client cannot wake an idle session, so the\nconnector runs Codex's own client/server split: a small **host process** embeds the mesh\nendpoint and drives a `codex app-server` thread over JSON-RPC (the same protocol the Codex TUI\nruns on). The app-server runs as an authenticated loopback **listener** rather than a private\npipe, which is what lets Codex's own TUI attach to the very thread the mesh is driving.\n\n- **Wake and steer.** An inbound batch starts a real turn (`turn/start`). A DIRECTED message\n  (DM, anycast, @mention) arriving mid-turn is injected into the live turn (`turn/steer`);\n  ambient channel chatter waits for the turn boundary so it can't derail work in flight.\n- **Native tools, one endpoint.** The host serves the shared `cotal_*` tools itself, on a\n  bearer-authenticated loopback MCP endpoint (the token is passed by env name, so it never appears\n  in the process table; see [Limits](#limits) for what that token does and does not protect). The model calls them like any tool and they\n  execute against the host's single mesh endpoint: no sidecar process, no second identity. The\n  app-server is the MCP client, so the tools work the same on a turn a peer message started and\n  on one **you** typed into the TUI.\n- **At-least-once delivery.** A turn's surfaced messages are acked (by exact id) only when the\n  turn completes. A failed turn retries with backoff, and an interrupted turn leaves the batch to\n  redeliver. If the Codex app-server itself dies, the host restarts it in place (same mesh\n  identity, credential, and durable) and re-drives the un-acked batch into the new thread; a\n  crash *loop* (more than 3 in 2 minutes) is fatal rather than an endless respawn. (The shared\n  bounded-inbox overflow rule applies: under extreme bursts an evicted in-flight id cannot\n  redeliver.)\n- **Isolated, never written.** Each agent gets a private `CODEX_HOME` (one hashed directory\n  per space+name under `.cotal/codex/`, rooted at the manager's workspace): your `~/.codex`\n  config.toml, hooks, and MCP servers never load into a managed agent, and Codex's per-project\n  trust records never touch your real config. Your `auth.json` is symlinked in (re-linked each\n  launch), so ChatGPT-plan token refreshes never fork. Without an `auth.json` (or an\n  `OPENAI_API_KEY`) the launch fails loud at thread start. Keyring-stored credentials are not\n  wired through the isolated home; use the file store or the env key for managed agents. That\n  symlink is why managed Codex agents are **POSIX-only** today: on Windows without Developer\n  Mode the link fails, and the launch fails loud rather than copying `auth.json` (a copy would\n  fork the token and break plan refreshes).\n- **Autonomy defaults.** Spawned agents run `approval_policy=never`,\n  `sandbox_mode=workspace-write`, and `sandbox_workspace_write={network_access=true}`.\n  See [Autonomy and the sandbox](#autonomy-and-the-sandbox) for what each one means and how to\n  change it.\n- **It really is Codex.** `cotal spawn --agent codex` drops you into the actual Codex TUI,\n  attached to the thread the mesh drives (`codex resume --remote`). Mesh turns render as they\n  happen, and anything you type is a real user turn on that same thread with the `cotal_*` tools\n  still available. In the foreground that is your terminal; detached it is the manager's pty,\n  which is exactly what `cotal attach` streams and drives. With no terminal at all (piped output,\n  CI, a smoke) the host stays headless and prints an activity feed instead: the same peer either\n  way, only the UI differs. `--transcript` mirrors the feed to `tr-<name>`.\n  **Which mode you get** is decided by whether *stdout* is a terminal, and `COTAL_CODEX_TUI=1|0`\n  overrides that check when it would guess wrong (a wrapper that redirects output, a CI run that\n  wants deterministic text). It is read from the environment of **whichever process builds the\n  launch**, so set it in the right place:\n  - foreground `cotal spawn`: your own shell, per spawn;\n  - detached (`-d`): the **manager's** environment, because the manager builds the launch. Set it\n    where you start the manager (`COTAL_CODEX_TUI=0 cotal up`) and it applies to every codex agent\n    that manager supervises. Exporting it in the shell that runs `cotal spawn -d` does nothing.\n\n  A detached agent gets the manager's pty, which *is* a terminal, so the default there is the TUI,\n  which is what `cotal attach` streams.\n  Once the TUI paints, the terminal belongs to Codex, so the host's own diagnostics move to\n  `host.log` inside the agent's private home\n  (`<workspace>/.cotal/codex/<space>-<name>-<hash>/host.log`; the handoff line prints the exact\n  path, and `ls -t .cotal/codex/*/host.log` finds it after the fact). Attached, a failure is also\n  reported on the terminal; detached, that report goes to the pty, so the file is the durable copy.\n- **Presence from events.** working/idle/waiting are derived from the app-server event stream;\n  the model id is reported from the started thread.\n\n`--opt k=v` launch options render as codex `-c k=v` config overrides on the app-server child\n(top-level keys, scalar values; write TOML inline-table text yourself for nested values). The\nconnector's own defaults and selectors ride the same rail and yield to yours, except\n`mcp_servers`, which is how the agent reaches the mesh: the whole namespace is refused loud (at\nspawn, not at launch) rather than silently overridden.\n\n## Autonomy and the sandbox\n\nA spawned Codex agent is woken by peer messages, which arrive when nobody is watching the\nterminal. The defaults follow from that, and all three are overridable per spawn with `--opt`.\n\n| Default | What it means |\n| --- | --- |\n| `approval_policy=\"never\"` | Never **ask** before running a command. Not \"refuse\": the agent runs its commands, it just does not stop to prompt. An interactive policy is refused loud rather than honored dishonestly, because a mesh-driven turn would block forever on a prompt nobody sees, and the alternative (auto-answering for you) nullifies the policy you asked for. |\n| `sandbox_mode=\"workspace-write\"` | Commands may read anywhere but write only inside the agent's workspace. This, not the prompt, is the part that is actually enforced; see below for the (real) exposure it leaves. |\n| `sandbox_workspace_write={network_access=true}` | Network **on** inside that sandbox. Codex's own default is off, which breaks installing a dependency, pushing a branch, or calling an API, with an error that reads like the task is impossible rather than the sandbox saying no. Applied only when the sandbox is actually `workspace-write`: tighten the mode and no network grant is emitted at all. |\n\nWhat the sandbox guarantees, stated literally: it **blocks out-of-workspace local filesystem\nwrites**. It does **not** block reads, exfiltration, or networked side effects.\n\nAll three of those are live with the defaults above, because a peer's message is a **remote input**\nthat can cause this agent to run commands. A confused or hostile peer can in principle get it to\nread a file elsewhere on your machine and send it; reach loopback or link-local services; or act\nthrough any credential it can read, which includes irreversible actions: a force-push, an API\ndelete, a deploy. Containing filesystem writes is therefore not the same as containing damage, and\nit should not be read that way. It is still worth keeping, because it is the one class this sandbox\ncan actually enforce.\n\nIf that exposure is wrong for a given agent, turn the network back off (below), tighten the mode,\nor run it under a separate OS user; the same point is repeated under [Limits](#limits) so it\nsurvives a skim. The spawn capability is the trust boundary for *who* may create an agent; the\nsandbox bounds one class of what it can then be talked into doing, not all of it.\n\nTune it per spawn:\n\n```bash\ncotal spawn --agent codex --opt sandbox_mode=read-only                        # tightest: no writes\ncotal spawn --agent codex --opt 'sandbox_workspace_write={network_access=false}'  # contained, offline\ncotal spawn --agent codex --opt sandbox_mode=danger-full-access               # no sandbox at all\n```\n\n`danger-full-access` is Codex's own name for it and means what it says: the agent may write\nanywhere your user account can. Codex documents that mode as intended only for environments that\nare already externally sandboxed (a container, a VM), not a workstation. On a laptop, prefer\ntightening the workspace over removing the sandbox.\n\n## Limits\n\n- **The sandbox blocks out-of-workspace filesystem writes, and only that.** It does not block\n  reads, exfiltration, or networked side effects. With the default `workspace-write` + network on,\n  a peer-driven turn can read anything your user account can (`~/.ssh`, `~/.aws`, `.env` files, the\n  agent's own `auth.json`) and send it; reach loopback and link-local services; and act through any\n  credential it can read, including irreversibly (a force-push, an API delete, a deploy). Only\n  local writes outside the workspace are stopped, so this is not \"everything risky is reversible\"\n  and not \"the only exposure is disclosure\". If that is wrong for a given agent, spawn it with\n  `--opt 'sandbox_workspace_write={network_access=false}'` or `--opt sandbox_mode=read-only`, or\n  run it as a separate OS user. See [Autonomy and the sandbox](#autonomy-and-the-sandbox).\n- **Not a boundary between agents on one machine.** The app-server listener and the tool\n  endpoint are both loopback-bound and token-authenticated, which keeps out other OS users and\n  anything off-box. It is not isolation between *managed agents*, which run as the same user and\n  can therefore reach each other's tokens; a hostile agent on your workstation could drive\n  another's Codex or speak as it on the mesh. Run mutually distrusted agents under separate OS\n  users or separate machines.\n- **The TUI is local-only.** The app-server listener binds loopback and nothing else, so\n  attaching Codex's UI to an agent on another machine needs your own SSH port-forward; there is\n  no built-in remote attach. `cotal attach` (which streams the manager's pty) is the supported\n  way to reach a detached agent.\n- **No session resume.** `cotal spawn --resume <id>` throws: a resumed codex thread comes up\n  without its configured MCP servers, so the agent would be mute on the mesh.\n- **No tool-sharing.** `connectors.codex.mcpServers` is not implemented and throws if set.\n- **Experimental upstream surface.** `codex app-server` is labeled experimental by OpenAI (it\n  is also what the Codex TUI itself runs on). The connector pins every protocol shape in one\n  driver file and re-proves the contract with a gated live smoke (`COTAL_E2E_CODEX=1`).\n\n## See also\n\n- [Connectors](connectors.md): the feature matrix across all connectors\n- [Run a mesh](run-a-mesh.md) \xB7 [Define a team](define-a-team.md) \xB7 [Watch a mesh](watch-a-mesh.md)\n- [MCP tools](mcp-tools.md) \xB7 [Connect Claude Code](connect-claude.md) \xB7 [Connect OpenCode](connect-opencode.md)\n"
+      "body": "# Connect Codex (beta)\n\n> **Guide** (informative) \xB7 **For:** operators \xB7 **Prereqs:** [Quickstart](getting-started.md)\n\n[OpenAI Codex](https://developers.openai.com/codex/) joins a Cotal mesh as a lateral peer: the\nsame `cotal_*` tool surface, the same message delivery and attention model as the other\nconnectors, plus mid-turn steering (previously pi-only): a directed peer message arriving\nmid-turn is **steered into the running turn** instead of waiting for it to end.\n\n**Beta** means the everyday path (spawn into the real Codex TUI, coordinate, watch) works; the\nspawn options that are not wired **fail loud** rather than degrade: resuming a session\n(`--resume`) and tool-sharing (`connectors.codex.mcpServers`). See [Limits](#limits).\n\n## Install\n\nThe connector ships with the CLI as a seeded extension (`@cotal-ai/connector-codex`): no\nseparate install step and no Codex-side plugin. You only need an authenticated `codex` binary\non your PATH (a ChatGPT-plan login or an `OPENAI_API_KEY`). If an older install is missing it,\n`cotal ext seed --repair` (or `cotal ext add @cotal-ai/connector-codex`) brings it in.\n\n**Don't install the `cotal` plugin Codex offers you.** Searching Codex's plugin list for \"cotal\"\nturns up a plugin named `cotal`, from the `cotal-mesh` marketplace. That is the **Claude Code**\nadapter, which appears there only because Codex reads the same plugin-marketplace format; it is\nnot this connector and installing it does not connect Codex to a mesh. Codex needs nothing\ninstalled on its side: the connector drives it from the outside, over `codex app-server`.\n\n**Codex version.** The connector drives `codex app-server` over its experimental v2 surface.\nMinimum **codex-cli 0.145.0**; tested against 0.145.0 and 0.146.0. An older binary authenticates fine but has\nno `--listen`/`--ws-auth` listener, so the launch fails at startup rather than misbehaving quietly:\ncheck with `codex --version` and upgrade (`npm i -g @openai/codex`) if a launch reports that the\napp-server exited before it started listening. The surface is explicitly experimental upstream, so\na later Codex release may change it and need a connector update. That is a break to report, not a\nsupport range we can promise ahead of it.\n\n## Spawn it\n\nSame launch grammar as any agent (see [run-a-mesh.md](run-a-mesh.md)):\n\n```bash\ncotal spawn --agent codex                # foreground in this terminal\ncotal spawn reviewer --agent codex -d    # detached via the manager; watch with `cotal attach`\nCOTAL_DEFAULT_AGENT=codex cotal spawn    # make codex the default harness\n```\n\nOr set `agent: codex` in a team [manifest](manifest.md). Persona, role, and model come from the\nagent file as for any connector ([agent-files.md](agent-files.md)).\n\n## Choose a model\n\n```bash\ncotal models --agent codex               # ids + reasoning-effort variants, via app-server model/list\ncotal spawn --agent codex --model gpt-5.6-sol --variant high\n```\n\nThe **variant** is Codex's reasoning effort (`minimal` | `low` | `medium` | `high` | `xhigh`).\nLike the `codex` CLI itself, the connector does not validate model ids or efforts locally. An\nunknown value fails at request time, server-side.\n\nModel and variant are published on presence, which is where `cotal roster` and the web dashboard's\n`model \xB7 variant` badge read them from. The variant appears only when you asked for one (via\n`--variant` or `variant:` in the agent file): there is no way to read the effort back off a running\nthread, so an unset variant is shown as absent rather than guessed at.\n\n## How it binds\n\nCodex has no in-process plugin runtime and its MCP client cannot wake an idle session, so the\nconnector runs Codex's own client/server split: a small **host process** embeds the mesh\nendpoint and drives a `codex app-server` thread over JSON-RPC (the same protocol the Codex TUI\nruns on). The app-server runs as an authenticated loopback **listener** rather than a private\npipe, which is what lets Codex's own TUI attach to the very thread the mesh is driving.\n\n- **Wake and steer.** An inbound batch starts a real turn (`turn/start`). A DIRECTED message\n  (DM, anycast, @mention) arriving mid-turn is injected into the live turn (`turn/steer`);\n  ambient channel chatter waits for the turn boundary so it can't derail work in flight.\n- **Native tools, one endpoint.** The host serves the shared `cotal_*` tools itself, on a\n  bearer-authenticated loopback MCP endpoint (the token is passed by env name, so it never appears\n  in the process table; see [Limits](#limits) for what that token does and does not protect). The model calls them like any tool and they\n  execute against the host's single mesh endpoint: no sidecar process, no second identity. The\n  app-server is the MCP client, so the tools work the same on a turn a peer message started and\n  on one **you** typed into the TUI.\n- **At-least-once delivery.** A turn's surfaced messages are acked (by exact id) only when the\n  turn completes. A failed turn retries with backoff, and an interrupted turn leaves the batch to\n  redeliver. If the Codex app-server itself dies, the host restarts it in place (same mesh\n  identity, credential, and durable) and re-drives the un-acked batch into the new thread; a\n  crash *loop* (more than 3 in 2 minutes) is fatal rather than an endless respawn. (The shared\n  bounded-inbox overflow rule applies: under extreme bursts an evicted in-flight id cannot\n  redeliver.)\n- **Isolated, never written.** Each agent gets a private `CODEX_HOME` (one hashed directory\n  per space+name under `.cotal/codex/`, rooted at the manager's workspace): your `~/.codex`\n  config.toml, hooks, and MCP servers never load into a managed agent, and Codex's per-project\n  trust records never touch your real config. Your `auth.json` is symlinked in (re-linked each\n  launch), so ChatGPT-plan token refreshes never fork. Without an `auth.json` (or an\n  `OPENAI_API_KEY`) the launch fails loud at thread start. Keyring-stored credentials are not\n  wired through the isolated home; use the file store or the env key for managed agents. That\n  symlink is why managed Codex agents are **POSIX-only** today: on Windows without Developer\n  Mode the link fails, and the launch fails loud rather than copying `auth.json` (a copy would\n  fork the token and break plan refreshes).\n- **Autonomy defaults.** Spawned agents run `approval_policy=never`,\n  `sandbox_mode=workspace-write`, and `sandbox_workspace_write={network_access=true}`.\n  See [Autonomy and the sandbox](#autonomy-and-the-sandbox) for what each one means and how to\n  change it.\n- **It really is Codex.** `cotal spawn --agent codex` drops you into the actual Codex TUI,\n  attached to the thread the mesh drives (`codex resume --remote`). Mesh turns render as they\n  happen, and anything you type is a real user turn on that same thread with the `cotal_*` tools\n  still available. In the foreground that is your terminal; detached it is the manager's pty,\n  which is exactly what `cotal attach` streams and drives. With no terminal at all (piped output,\n  CI, a smoke) the host stays headless and prints an activity feed instead: the same peer either\n  way, only the UI differs.\n  **Which mode you get** is decided by whether *stdout* is a terminal, and `COTAL_CODEX_TUI=1|0`\n  overrides that check when it would guess wrong (a wrapper that redirects output, a CI run that\n  wants deterministic text). It is read from the environment of **whichever process builds the\n  launch**, so set it in the right place:\n  - foreground `cotal spawn`: your own shell, per spawn;\n  - detached (`-d`): the **manager's** environment, because the manager builds the launch. Set it\n    where you start the manager (`COTAL_CODEX_TUI=0 cotal up`) and it applies to every codex agent\n    that manager supervises. Exporting it in the shell that runs `cotal spawn -d` does nothing.\n\n  A detached agent gets the manager's pty, which *is* a terminal, so the default there is the TUI,\n  which is what `cotal attach` streams.\n  Once the TUI paints, the terminal belongs to Codex, so the host's own diagnostics move to\n  `host.log` inside the agent's private home\n  (`<workspace>/.cotal/codex/<space>-<name>-<hash>/host.log`; the handoff line prints the exact\n  path, and `ls -t .cotal/codex/*/host.log` finds it after the fact). Attached, a failure is also\n  reported on the terminal; detached, that report goes to the pty, so the file is the durable copy.\n- **Presence from events.** working/idle/waiting are derived from the app-server event stream;\n  the model id is reported from the started thread.\n\n`--opt k=v` launch options render as codex `-c k=v` config overrides on the app-server child\n(top-level keys, scalar values; write TOML inline-table text yourself for nested values). The\nconnector's own defaults and selectors ride the same rail and yield to yours, except\n`mcp_servers`, which is how the agent reaches the mesh: the whole namespace is refused loud (at\nspawn, not at launch) rather than silently overridden.\n\n## Autonomy and the sandbox\n\nA spawned Codex agent is woken by peer messages, which arrive when nobody is watching the\nterminal. The defaults follow from that, and all three are overridable per spawn with `--opt`.\n\n| Default | What it means |\n| --- | --- |\n| `approval_policy=\"never\"` | Never **ask** before running a command. Not \"refuse\": the agent runs its commands, it just does not stop to prompt. An interactive policy is refused loud rather than honored dishonestly, because a mesh-driven turn would block forever on a prompt nobody sees, and the alternative (auto-answering for you) nullifies the policy you asked for. |\n| `sandbox_mode=\"workspace-write\"` | Commands may read anywhere but write only inside the agent's workspace. This, not the prompt, is the part that is actually enforced; see below for the (real) exposure it leaves. |\n| `sandbox_workspace_write={network_access=true}` | Network **on** inside that sandbox. Codex's own default is off, which breaks installing a dependency, pushing a branch, or calling an API, with an error that reads like the task is impossible rather than the sandbox saying no. Applied only when the sandbox is actually `workspace-write`: tighten the mode and no network grant is emitted at all. |\n\nWhat the sandbox guarantees, stated literally: it **blocks out-of-workspace local filesystem\nwrites**. It does **not** block reads, exfiltration, or networked side effects.\n\nAll three of those are live with the defaults above, because a peer's message is a **remote input**\nthat can cause this agent to run commands. A confused or hostile peer can in principle get it to\nread a file elsewhere on your machine and send it; reach loopback or link-local services; or act\nthrough any credential it can read, which includes irreversible actions: a force-push, an API\ndelete, a deploy. Containing filesystem writes is therefore not the same as containing damage, and\nit should not be read that way. It is still worth keeping, because it is the one class this sandbox\ncan actually enforce.\n\nIf that exposure is wrong for a given agent, turn the network back off (below), tighten the mode,\nor run it under a separate OS user; the same point is repeated under [Limits](#limits) so it\nsurvives a skim. The spawn capability is the trust boundary for *who* may create an agent; the\nsandbox bounds one class of what it can then be talked into doing, not all of it.\n\nTune it per spawn:\n\n```bash\ncotal spawn --agent codex --opt sandbox_mode=read-only                        # tightest: no writes\ncotal spawn --agent codex --opt 'sandbox_workspace_write={network_access=false}'  # contained, offline\ncotal spawn --agent codex --opt sandbox_mode=danger-full-access               # no sandbox at all\n```\n\n`danger-full-access` is Codex's own name for it and means what it says: the agent may write\nanywhere your user account can. Codex documents that mode as intended only for environments that\nare already externally sandboxed (a container, a VM), not a workstation. On a laptop, prefer\ntightening the workspace over removing the sandbox.\n\n## Limits\n\n- **The sandbox blocks out-of-workspace filesystem writes, and only that.** It does not block\n  reads, exfiltration, or networked side effects. With the default `workspace-write` + network on,\n  a peer-driven turn can read anything your user account can (`~/.ssh`, `~/.aws`, `.env` files, the\n  agent's own `auth.json`) and send it; reach loopback and link-local services; and act through any\n  credential it can read, including irreversibly (a force-push, an API delete, a deploy). Only\n  local writes outside the workspace are stopped, so this is not \"everything risky is reversible\"\n  and not \"the only exposure is disclosure\". If that is wrong for a given agent, spawn it with\n  `--opt 'sandbox_workspace_write={network_access=false}'` or `--opt sandbox_mode=read-only`, or\n  run it as a separate OS user. See [Autonomy and the sandbox](#autonomy-and-the-sandbox).\n- **Not a boundary between agents on one machine.** The app-server listener and the tool\n  endpoint are both loopback-bound and token-authenticated, which keeps out other OS users and\n  anything off-box. It is not isolation between *managed agents*, which run as the same user and\n  can therefore reach each other's tokens; a hostile agent on your workstation could drive\n  another's Codex or speak as it on the mesh. Run mutually distrusted agents under separate OS\n  users or separate machines.\n- **The TUI is local-only.** The app-server listener binds loopback and nothing else, so\n  attaching Codex's UI to an agent on another machine needs your own SSH port-forward; there is\n  no built-in remote attach. `cotal attach` (which streams the manager's pty) is the supported\n  way to reach a detached agent.\n- **No session resume.** `cotal spawn --resume <id>` throws: a resumed codex thread comes up\n  without its configured MCP servers, so the agent would be mute on the mesh.\n- **No tool-sharing.** `connectors.codex.mcpServers` is not implemented and throws if set.\n- **Experimental upstream surface.** `codex app-server` is labeled experimental by OpenAI (it\n  is also what the Codex TUI itself runs on). The connector pins every protocol shape in one\n  driver file and re-proves the contract with a gated live smoke (`COTAL_E2E_CODEX=1`).\n\n## See also\n\n- [Connectors](connectors.md): the feature matrix across all connectors\n- [Run a mesh](run-a-mesh.md) \xB7 [Define a team](define-a-team.md) \xB7 [Watch a mesh](watch-a-mesh.md)\n- [MCP tools](mcp-tools.md) \xB7 [Connect Claude Code](connect-claude.md) \xB7 [Connect OpenCode](connect-opencode.md)\n"
     },
     {
       "slug": "connect-hermes",
@@ -65587,7 +67425,7 @@ var DOCS_BUNDLE = {
       "title": "Security model",
       "kind": "Concept (informative threat model)",
       "summary": "Cotal v0 provides containment and sender authenticity for peers sharing one trusted NATS broker.",
-      "body": "# Security model\n\n> **Concept** (informative threat model) \xB7 **For:** operators and security reviewers \xB7 **Normative:** [SPEC \xA79](../SPEC.md#9-nats--jetstream-security-and-authorization). This page is the threat model SPEC \xA79 references; where the two disagree, the spec wins.\n\nCotal v0 provides containment and sender authenticity for peers sharing one trusted NATS\nbroker. It is not an end-to-end encrypted or untrusted-relay protocol. The enforcement\nmechanics (profiles, ACLs, consumer confinement) are defined in\n[SPEC \xA79](../SPEC.md#9-nats--jetstream-security-and-authorization) and\n[Appendix B](../SPEC.md#appendix-b-profile-acls), explained informally in\n[identity & auth](identity-and-auth.md); this page covers **who the adversaries are and\nwhat is (not) defended**.\n\n## Trust boundary\n\n- One Cotal space maps to one NATS account.\n- The broker, operator, account signing key holder, and any `admin` credential are trusted.\n- On a per-user-auth mesh, ledger scope `admin` is the same trust grade as an `admin`\n  credential: it unlocks the elevated views (the whole-space read tap, history and channel\n  purges, channel-registry writes, cross-owner control), so grant it as operator authority,\n  not as a convenience ([identity & auth](identity-and-auth.md)).\n- Agents are not trusted to self-report sender identity, channel permissions, or DM access.\n\n## Adversaries\n\nEach adversary, what it can attempt, and what stops it (or why it is out of scope).\n\n- **Compromised or malicious peer agent** (authenticated, in-space): the primary adversary.\n  It cannot forge another agent's `from.id` (the subject sender, an `owner.actor` principal,\n  is pinned to its connection by NATS permissions; not another owner, and not a sibling actor\n  under its own owner), cannot publish to channels outside its declared allow-list, and cannot read\n  another agent's DMs or another role's work queue ([SPEC \xA79](../SPEC.md#9-nats--jetstream-security-and-authorization)).\n  It still can send well-formed hostile content to channels it is allowed on\n  (see *Prompt-facing data*) and flood within its limits (see *availability* under *What v0\n  does not protect*). These are **broker-enforced** guarantees and assume the peer has no host\n  filesystem or process access to the account signer: the default single-host manager and container\n  compositions do not isolate the signer from a same-uid agent, which could then mint `admin` and\n  read any DM. Isolating it is a hosted-composition concern (see [Embedding Cotal](embedding.md) and\n  [Deploy](deploy.md)).\n- **Buggy or lazy receiver:** sender authenticity depends on the receiver enforcing the\n  `from.id`-equals-subject-sender check; a client that skips it accepts spoofed senders. The\n  check is therefore normative: receivers MUST reject on mismatch\n  ([SPEC \xA75](../SPEC.md#5-envelopes), [\xA712](../SPEC.md#12-conformance)).\n- **On-path network attacker** (between an agent and the broker): defeated only when the join\n  link uses `cotals://` (TLS **required** \u2014 client refuses if the broker is not TLS). Plain\n  `cotal://` does **not** require TLS: a NATS client may still auto-upgrade against an honest\n  TLS broker, but a forged plaintext `INFO` can strip the upgrade and harvest credentials. Use\n  plain `cotal://` only on trusted networks and in dev.\n- **Content author targeting a reading model:** any writer of channel `description` /\n  `instructions`, presence `activity`, message bodies, or free-form metadata can attempt\n  prompt injection against an agent that reads it. See *Prompt-facing data*.\n- **Untrusted broker, relay, operator, or admin:** out of scope by definition. The broker and\n  any `admin` credential can read, drop, replay, or alter all plaintext traffic. v0 makes no\n  claim against a hostile broker; signed envelopes and untrusted-relay bindings are reserved\n  for a later version ([roadmap](roadmap.md)).\n\n## What v0 protects\n\nThe guarantees, at a glance, each enforced by the broker per\n[SPEC \xA79](../SPEC.md#9-nats--jetstream-security-and-authorization):\n\n- **Sender authenticity**: the sender id is encoded in the subject and enforced by NATS\n  permissions; receivers reject payloads whose `from.id` mismatches.\n- **Space containment**: account boundaries isolate one space's subjects, streams, and KV\n  buckets from another.\n- **Channel publish scope**: posting only as self, only to declared `allowPublish`\n  channels (default-deny).\n- **Channel read scope**, reads bounded to the `allowSubscribe` ACL: live joins are\n  broker-refused outside it, and history reads ride server-pinned single-channel consumers.\n  - **Known metadata leak (not content):** agents hold `STREAM.INFO` on the chat stream, so\n    a `subjects_filter` query can enumerate retained chat *subjects* (channel names, sender\n    ids, per-subject counts) including channels outside `allowSubscribe`. This is metadata,\n    never message content, and channel *names* are already public via the registry. Hiding\n    even the existence/volume of other channels requires the per-channel-stream model and is\n    deferred strict-containment work ([roadmap](roadmap.md)).\n- **DM / task peer confidentiality**: per-identity inbox prefixes plus\n  provisioner-created bind-only consumers, so an agent cannot read someone else's inbox or\n  steal another role's work; durable-channel backstop reads are re-authorized by a trusted\n  reader ([delivery daemon](delivery-daemon.md)).\n- **Transport secrecy (optional)**: `cotals://` enforces TLS for the hop to the broker.\n  It protects that hop, not the broker itself.\n\n## What v0 does not protect\n\n- **Untrusted broker or relay:** the broker can read, drop, replay, or alter plaintext\n  traffic. Signed envelopes are reserved for a later version.\n- **End-to-end secrecy:** DMs are plaintext to the broker and to `admin`. Cotal v0\n  deliberately does not add end-to-end encryption, trading secrecy for a single trusted broker.\n- **Non-repudiation:** sender authenticity is broker-enforced, not portable proof. (A2A signs\n  every message for this; here it is reserved as signed envelopes.)\n- **Availability:** an authenticated peer can flood any channel or inbox it may write to. v0\n  relies on coarse NATS account limits (connections, subscriptions, payload and storage caps)\n  and adds no per-agent application-level rate limiting.\n- **Replay by a peer:** a peer may re-send its own prior messages; v0 defines no protocol-level\n  nonce or idempotency key. It cannot replay as another agent (subject binding still holds).\n- **Static agent credential revocation:** on a static-auth mesh, a *manager-spawned* agent cred\n  is now bounded (24h TTL, renewed by the manager for live agents only) and lifecycle-registered:\n  despawn drives the full \xA713.1 retirement \u2014 its ledger rows are revoked and the manager's\n  control surface refuses the retired incarnation's credential outright. What remains: within\n  the TTL window a *copied* cred keeps its inline data-plane grants (static has no auth callout,\n  so nothing re-checks at reconnect), and an out-of-band `cotal mint` cred is still long-lived\n  until key rotation. A per-user-auth mesh closes both: short-lived bearers, ledger revocation\n  that bites at the next connect, and live-connection eviction\n  ([identity & auth](identity-and-auth.md)). A copied signing *seed* still stays valid until\n  rotation on either kind of mesh.\n- **Manager compromise:** the operator side is split into narrow, single-purpose profiles (there\n  is **no allow-all cred**); the long-lived **supervisor** serves control and touches\n  presence/its lease but cannot read a DM, create a consumer, or delete a stream; the destructive\n  verbs (`STREAM.DELETE`/`PURGE`, cross-agent stop, per-agent provisioning) ride ephemeral\n  per-command creds (teardown / control-caller-admin / deployer / provisioner). What stays hot on\n  a static-auth mesh is the account **signing key** on the mint/manager box (a compromise there\n  can still mint fresh creds); on a per-user-auth mesh it is held by the auth service (the callout\n  stage) and by any running manager, which self-mints its supervisor cred and renewals from it\n  ([identity & auth](identity-and-auth.md)).\n- **`spawn` is host-launch authority:** launch options are a raw passthrough (no allow/deny\n  list), so a persona holding `capabilities: [spawn]` can drive the connector's full launch\n  surface on the manager host (Claude `--mcp-config`, `--add-dir`, permission flags; OpenCode\n  agent-config keys). The boundary is *who* may spawn (the authenticated caller, gated by the\n  capability), not *which* flags they pass. Grant `spawn` as host-launch authority, not a narrow\n  \"add a teammate\" permission ([run a mesh](run-a-mesh.md#spawning-agents)).\n\n## Prompt-facing data\n\nChannel `description` and `instructions`, presence `activity`, message bodies, and free-form\nmetadata may reach models. Writers that can set channel registry text are privileged, and\nregistry text is length-bounded, but clients MUST still render all of it as attributed,\nadvisory data, never as trusted system instruction. This is the indirect-prompt-injection\nsurface common to agent protocols (MCP tool descriptions, A2A agent cards): Cotal's position is\nthat the reading client, not the wire, is the trust boundary for model-facing text.\n\n## Reporting\n\nReport a suspected vulnerability privately to the maintainers rather than in a public issue.\n"
+      "body": "# Security model\n\n> **Concept** (informative threat model) \xB7 **For:** operators and security reviewers \xB7 **Normative:** [SPEC \xA79](../SPEC.md#9-nats--jetstream-security-and-authorization). This page is the threat model SPEC \xA79 references; where the two disagree, the spec wins.\n\nCotal v0 provides containment and sender authenticity for peers sharing one trusted NATS\nbroker. It is not an end-to-end encrypted or untrusted-relay protocol. The enforcement\nmechanics (profiles, ACLs, consumer confinement) are defined in\n[SPEC \xA79](../SPEC.md#9-nats--jetstream-security-and-authorization) and\n[Appendix B](../SPEC.md#appendix-b-profile-acls), explained informally in\n[identity & auth](identity-and-auth.md); this page covers **who the adversaries are and\nwhat is (not) defended**.\n\n## Trust boundary\n\n- One Cotal space maps to one NATS account.\n- The broker, operator, account signing key holder, and any `admin` credential are trusted.\n- On a per-user-auth mesh, ledger scope `admin` is the same trust grade as an `admin`\n  credential: it unlocks the elevated views (the whole-space read tap, history and channel\n  purges, channel-registry writes, cross-owner control), so grant it as operator authority,\n  not as a convenience ([identity & auth](identity-and-auth.md)).\n- Agents are not trusted to self-report sender identity, channel permissions, or DM access.\n\n## Adversaries\n\nEach adversary, what it can attempt, and what stops it (or why it is out of scope).\n\n- **Compromised or malicious peer agent** (authenticated, in-space): the primary adversary.\n  It cannot forge another agent's `from.id` (the subject sender, an `owner.actor` principal,\n  is pinned to its connection by NATS permissions; not another owner, and not a sibling actor\n  under its own owner), cannot publish to channels outside its declared allow-list, and cannot read\n  another agent's DMs or another role's work queue ([SPEC \xA79](../SPEC.md#9-nats--jetstream-security-and-authorization)).\n  It still can send well-formed hostile content to channels it is allowed on\n  (see *Prompt-facing data*) and flood within its limits (see *availability* under *What v0\n  does not protect*). These are **broker-enforced** guarantees and assume the peer has no host\n  filesystem or process access to the account signer: the default single-host manager and container\n  compositions do not isolate the signer from a same-uid agent, which could then mint `admin` and\n  read any DM. Isolating it is a hosted-composition concern (see [Embedding Cotal](embedding.md) and\n  [Deploy](deploy.md)).\n- **Buggy or lazy receiver:** sender authenticity depends on the receiver enforcing the\n  `from.id`-equals-subject-sender check; a client that skips it accepts spoofed senders. The\n  check is therefore normative: receivers MUST reject on mismatch\n  ([SPEC \xA75](../SPEC.md#5-envelopes), [\xA712](../SPEC.md#12-conformance)).\n- **On-path network attacker** (between an agent and the broker): defeated only when the join\n  link uses `cotals://` (TLS **required** \u2014 client refuses if the broker is not TLS). Plain\n  `cotal://` does **not** require TLS: a NATS client may still auto-upgrade against an honest\n  TLS broker, but a forged plaintext `INFO` can strip the upgrade and harvest credentials. Use\n  plain `cotal://` only on trusted networks and in dev.\n- **Content author targeting a reading model:** any writer of channel `description` /\n  `instructions`, presence `activity`, message bodies, or free-form metadata can attempt\n  prompt injection against an agent that reads it. See *Prompt-facing data*.\n- **Untrusted broker, relay, operator, or admin:** out of scope by definition. The broker and\n  any `admin` credential can read, drop, replay, or alter all plaintext traffic. v0 makes no\n  claim against a hostile broker; signed envelopes and untrusted-relay bindings are reserved\n  for a later version ([roadmap](roadmap.md)).\n\n## What v0 protects\n\nThe guarantees, at a glance, each enforced by the broker per\n[SPEC \xA79](../SPEC.md#9-nats--jetstream-security-and-authorization):\n\n- **Sender authenticity**: the sender id is encoded in the subject and enforced by NATS\n  permissions; receivers reject payloads whose `from.id` mismatches.\n- **Space containment**: account boundaries isolate one space's subjects, streams, and KV\n  buckets from another.\n- **Channel publish scope**: posting only as self, only to declared `allowPublish`\n  channels (default-deny).\n- **Channel read scope**, reads bounded to the `allowSubscribe` ACL: live joins are\n  broker-refused outside it, and history reads ride server-pinned single-channel consumers.\n  - **Known metadata leak (not content):** agents hold `STREAM.INFO` on the chat stream, so\n    a `subjects_filter` query can enumerate retained chat *subjects* (channel names, sender\n    ids, per-subject counts) including channels outside `allowSubscribe`. This is metadata,\n    never message content, and channel *names* are already public via the registry. Hiding\n    even the existence/volume of other channels requires the per-channel-stream model and is\n    deferred strict-containment work ([roadmap](roadmap.md)).\n- **DM / task peer confidentiality**: per-identity inbox prefixes plus\n  provisioner-created bind-only consumers, so an agent cannot read someone else's inbox or\n  steal another role's work; durable-channel backstop reads are re-authorized by a trusted\n  reader ([delivery daemon](delivery-daemon.md)).\n- **Transport secrecy (optional)**: `cotals://` enforces TLS for the hop to the broker.\n  It protects that hop, not the broker itself.\n\n## What v0 does not protect\n\n- **Untrusted broker or relay:** the broker can read, drop, replay, or alter plaintext\n  traffic. Signed envelopes are reserved for a later version.\n- **End-to-end secrecy:** DMs are plaintext to the broker and to `admin`. Cotal v0\n  deliberately does not add end-to-end encryption, trading secrecy for a single trusted broker.\n- **Non-repudiation:** sender authenticity is broker-enforced, not portable proof. (A2A signs\n  every message for this; here it is reserved as signed envelopes.)\n- **Availability:** an authenticated peer can flood any channel or inbox it may write to. v0\n  relies on coarse NATS account limits (connections, subscriptions, payload and storage caps)\n  and adds no per-agent application-level rate limiting.\n- **Replay by a peer:** a peer may re-send its own prior messages; v0 defines no protocol-level\n  nonce or idempotency key. It cannot replay as another agent (subject binding still holds).\n- **Static agent credential revocation:** on a static-auth mesh, a *manager-spawned* agent cred\n  is now bounded (24h TTL, renewed by the manager for live agents only) and lifecycle-registered:\n  despawn drives the full \xA713.1 retirement \u2014 its ledger rows are revoked and the manager's\n  control surface refuses the retired incarnation's credential outright. What remains: within\n  the TTL window a *copied* cred keeps its inline data-plane grants (static has no auth callout,\n  so nothing re-checks at reconnect), and an out-of-band `cotal mint` cred is still long-lived\n  until key rotation. A per-user-auth mesh closes both: short-lived bearers, ledger revocation\n  that bites at the next connect, and live-connection eviction\n  ([identity & auth](identity-and-auth.md)). A copied signing *seed* still stays valid until\n  rotation on either kind of mesh.\n- **Manager compromise:** the operator side is split into narrow, single-purpose profiles (there\n  is **no allow-all cred**); the long-lived **supervisor** serves control and touches\n  presence/its lease but cannot read a DM, create a consumer, or delete a stream; the destructive\n  verbs (`STREAM.DELETE`/`PURGE`, cross-agent stop, per-agent provisioning) ride ephemeral\n  per-command creds (teardown / control-caller-admin / deployer / provisioner). What stays hot on\n  a static-auth mesh is the account **signing key** on the mint/manager box (a compromise there\n  can still mint fresh creds); on a per-user-auth mesh it is held by the auth service (the callout\n  stage) and by any running manager, which self-mints its supervisor cred and renewals from it\n  ([identity & auth](identity-and-auth.md)).\n- **A static mesh's spawn credential is the ACL tier:** a caller that may spawn may also name the\n  child's channel ACL, and on a static-auth mesh nothing attenuates that against the caller's own\n  grant, because there is no ledger to attenuate against. This is the same class as the entry above\n  and is not specific to any channel: the read set a spawn-capable static caller may hand its child\n  covers ordinary channels, and `events.*` alongside them. A per-user-auth mesh does attenuate it:\n  every delegation must sit inside the spawner's own grant, checked by NATS-pattern containment\n  along the whole chain, at the grant write and again at every bearer exchange\n  ([identity & auth](identity-and-auth.md)). Grant `spawn` on a static mesh as ACL authority, not\n  as a narrow \"add a teammate\" permission.\n- **`spawn` is host-launch authority:** launch options are a raw passthrough (no allow/deny\n  list), so a persona holding `capabilities: [spawn]` can drive the connector's full launch\n  surface on the manager host (Claude `--mcp-config`, `--add-dir`, permission flags; OpenCode\n  agent-config keys). The boundary is *who* may spawn (the authenticated caller, gated by the\n  capability), not *which* flags they pass. Grant `spawn` as host-launch authority, not a narrow\n  \"add a teammate\" permission ([run a mesh](run-a-mesh.md#spawning-agents)).\n\n## Prompt-facing data\n\nChannel `description` and `instructions`, presence `activity`, message bodies, and free-form\nmetadata may reach models. Writers that can set channel registry text are privileged, and\nregistry text is length-bounded, but clients MUST still render all of it as attributed,\nadvisory data, never as trusted system instruction. This is the indirect-prompt-injection\nsurface common to agent protocols (MCP tool descriptions, A2A agent cards): Cotal's position is\nthat the reading client, not the wire, is the trust boundary for model-facing text.\n\n## Reporting\n\nReport a suspected vulnerability privately to the maintainers rather than in a public issue.\n"
     },
     {
       "slug": "setup-internals",
@@ -65729,10 +67567,10 @@ function sectionsOf(slug, pageTitle, body) {
   for (const line of body.split("\n")) {
     if (line.trimStart().startsWith("```"))
       inFence = !inFence;
-    const h = inFence ? null : line.match(/^#{2,6}\s+(.+?)\s*$/);
-    if (h) {
+    const h2 = inFence ? null : line.match(/^#{2,6}\s+(.+?)\s*$/);
+    if (h2) {
       flush();
-      heading = `${pageTitle} \u203A ${h[1].trim()}`;
+      heading = `${pageTitle} \u203A ${h2[1].trim()}`;
     }
     buf.push(line);
   }
@@ -65808,10 +67646,10 @@ function renderSearch(query, hits) {
   if (!hits.length) {
     return `No matches for "${query}" in the Cotal v${DOCS_BUNDLE.version} docs. Call cotal_docs() for the page index, or search an exact identifier (a subject, a cotal_* tool, a field name).`;
   }
-  const blocks = hits.map((h) => `## ${h.heading}
-${capSection(h.text)}
+  const blocks = hits.map((h2) => `## ${h2.heading}
+${capSection(h2.text)}
 
-\u2192 read the full page: cotal_docs(page: "${h.slug}")`);
+\u2192 read the full page: cotal_docs(page: "${h2.slug}")`);
   return [
     `# Cotal v${DOCS_BUNDLE.version} docs \u2014 top matches for "${query}"`,
     "The most relevant sections are below. Read the full page before writing code or wire frames.",
@@ -65953,12 +67791,12 @@ function fmtFrom(i) {
   return i.fromRole ? `${i.fromName}/${i.fromRole}` : i.fromName;
 }
 function fmtItem(i) {
-  const h = i.historical ? "(history) " : "";
+  const h2 = i.historical ? "(history) " : "";
   if (i.kind === "dm")
-    return `[DM from ${fmtFrom(i)}] ${h}${i.text}`;
+    return `[DM from ${fmtFrom(i)}] ${h2}${i.text}`;
   if (i.kind === "anycast")
-    return `[@${i.service} from ${fmtFrom(i)}] ${h}${i.text}`;
-  return `[#${i.channel}${i.mentionsMe ? " @you" : ""} ${fmtFrom(i)}] ${h}${i.text}`;
+    return `[@${i.service} from ${fmtFrom(i)}] ${h2}${i.text}`;
+  return `[#${i.channel}${i.mentionsMe ? " @you" : ""} ${fmtFrom(i)}] ${h2}${i.text}`;
 }
 function renderChannelInfo(channel, info) {
   const lines = [
@@ -66433,8 +68271,8 @@ function registerCotalTools(server, agent, config2, source) {
 
 // ../connector-core/dist/control.js
 var import_node_net2 = require("node:net");
-var import_node_fs3 = require("node:fs");
-var import_node_crypto8 = require("node:crypto");
+var import_node_fs7 = require("node:fs");
+var import_node_crypto13 = require("node:crypto");
 var HANDOFF_DEADLINE_MS = 5e3;
 var LEGACY_WRITE_DEADLINE_MS = 5e3;
 var MAX_FRAME_BYTES = 1 << 20;
@@ -66442,18 +68280,18 @@ var AUTH_DEADLINE_MS = 5e3;
 function tokenMatches(presented, digest) {
   if (typeof presented !== "string")
     return false;
-  return (0, import_node_crypto8.timingSafeEqual)((0, import_node_crypto8.createHash)("sha256").update(presented).digest(), digest);
+  return (0, import_node_crypto13.timingSafeEqual)((0, import_node_crypto13.createHash)("sha256").update(presented).digest(), digest);
 }
 function who(i) {
   return i.fromRole ? `${i.fromName}/${i.fromRole}` : i.fromName;
 }
 function fmtItem2(i) {
-  const h = i.historical ? " (history)" : "";
+  const h2 = i.historical ? " (history)" : "";
   if (i.kind === "dm")
-    return `\u2022 DM from ${who(i)}${h}: ${i.text}`;
+    return `\u2022 DM from ${who(i)}${h2}: ${i.text}`;
   if (i.kind === "anycast")
-    return `\u2022 @${i.service} (from ${who(i)})${h}: ${i.text}`;
-  return `\u2022 #${i.channel} ${who(i)}${h}: ${i.text}`;
+    return `\u2022 @${i.service} (from ${who(i)})${h2}: ${i.text}`;
+  return `\u2022 #${i.channel} ${who(i)}${h2}: ${i.text}`;
 }
 function formatInjection(items) {
   if (!items.length)
@@ -66521,10 +68359,10 @@ function writeReply(sock, reply, awaitHandoff) {
 }
 function startControlServer(agent, endpoint, handle, opts = {}) {
   const { path } = endpoint;
-  const digest = (0, import_node_crypto8.createHash)("sha256").update(endpoint.token).digest();
-  if (process.platform !== "win32" && (0, import_node_fs3.existsSync)(path)) {
+  const digest = (0, import_node_crypto13.createHash)("sha256").update(endpoint.token).digest();
+  if (process.platform !== "win32" && (0, import_node_fs7.existsSync)(path)) {
     try {
-      (0, import_node_fs3.unlinkSync)(path);
+      (0, import_node_fs7.unlinkSync)(path);
     } catch {
     }
   }
@@ -66589,19 +68427,23 @@ function startControlServer(agent, endpoint, handle, opts = {}) {
   return server;
 }
 
+// src/mcp.ts
+var import_node_crypto14 = require("node:crypto");
+var import_node_path6 = require("node:path");
+
 // src/hooks.ts
 function toolDetail(name, input) {
   if (typeof name !== "string" || !name) return void 0;
   const i = input ?? {};
-  const salient2 = i.command ?? i.file_path ?? i.path ?? i.url ?? i.pattern ?? i.description;
-  let detail = typeof salient2 === "string" ? salient2 : Object.keys(i).length ? JSON.stringify(i) : "";
+  const salient = i.command ?? i.file_path ?? i.path ?? i.url ?? i.pattern ?? i.description;
+  let detail = typeof salient === "string" ? salient : Object.keys(i).length ? JSON.stringify(i) : "";
   if (detail.length > 300) detail = `${detail.slice(0, 299)}\u2026`;
   return { name, detail };
 }
 var REPEAT_NOTE = "(A previous delivery of one or more of these was not confirmed, so they may be a repeat.)";
 var REPEAT_LABEL_CAP = 512;
 function createClaudeHandle(deps = {}) {
-  const mirror2 = () => deps.mirror?.();
+  const events2 = () => deps.events?.();
   let pendingTool;
   const inFlight = /* @__PURE__ */ new WeakMap();
   const unconfirmed = /* @__PURE__ */ new Set();
@@ -66632,7 +68474,7 @@ ${body}` : body;
     try {
       switch (event) {
         case "SessionStart": {
-          mirror2()?.adopt(ev.transcript_path);
+          events2()?.adopt(ev.transcript_path);
           if (typeof ev.model === "string") await agent.setModel(ev.model).catch(() => {
           });
           await safeStatus(agent, "idle");
@@ -66645,12 +68487,12 @@ ${body}` : body;
         }
         case "UserPromptSubmit":
           pendingTool = void 0;
-          mirror2()?.flush(ev.transcript_path);
+          events2()?.flush(ev.transcript_path);
           await safeStatus(agent, "working");
           return withContext(surfaceAutomatic(agent, ev));
         case "PreToolUse":
           pendingTool = toolDetail(ev.tool_name, ev.tool_input);
-          mirror2()?.flush(ev.transcript_path);
+          events2()?.flush(ev.transcript_path);
           return {};
         case "Notification": {
           const msg = typeof ev.message === "string" ? ev.message : void 0;
@@ -66661,12 +68503,13 @@ ${body}` : body;
         case "Stop":
         case "StopFailure":
           pendingTool = void 0;
-          mirror2()?.flush(ev.transcript_path);
+          events2()?.flush(ev.transcript_path);
+          events2()?.closeRun(Date.now());
           await safeStatus(agent, "idle");
           if (agent.pendingWake() > 0) agent.requestWake();
           return {};
         case "SessionEnd":
-          mirror2()?.flush(ev.transcript_path);
+          events2()?.flush(ev.transcript_path);
           await safeStatus(agent, "offline");
           return {};
         default:
@@ -66759,168 +68602,211 @@ function createWakePolicy(agent, notify, log = () => {
   };
 }
 
-// src/transcript.ts
-var import_node_fs4 = require("node:fs");
-var MAX_PREVIEW = 700;
-var MAX_CHUNK = 6e3;
-function truncate(s, max) {
-  return s.length > max ? `${s.slice(0, max - 1)}\u2026` : s;
-}
-function salient(input) {
-  const i = input ?? {};
-  const v = i.command ?? i.file_path ?? i.path ?? i.url ?? i.pattern ?? i.description;
-  const s = typeof v === "string" ? v : Object.keys(i).length ? JSON.stringify(i) : "";
-  return s ? `: ${truncate(s, 300)}` : "";
-}
-function resultText(content) {
-  if (typeof content === "string") return content;
-  if (Array.isArray(content))
-    return content.map((b) => typeof b?.text === "string" ? b.text : "").filter(Boolean).join("\n");
-  return "";
-}
-function condense(line) {
-  let e;
-  try {
-    e = JSON.parse(line);
-  } catch {
-    return [];
-  }
-  if (!e || e.isMeta) return [];
-  const content = e.message?.content;
-  if (e.type === "assistant" && Array.isArray(content)) {
-    const out = [];
-    for (const b of content) {
-      if (b.type === "text" && b.text?.trim()) out.push(b.text.trim());
-      else if (b.type === "tool_use" && b.name) out.push(`\u2692 ${b.name}${salient(b.input)}`);
-    }
-    return out;
+// src/agui-map.ts
+var ORIGIN_RULE = {
+  human: "human",
+  channel: "channel",
+  // a peer/mesh delivery IS a turn, the one change from the original table
+  "task-notification": null,
+  // known, and deliberately not a turn
+  // MEASURED ON THIS MACHINE'S CORPUS, 237 session files and 531,882 records: 4 occurrences, every
+  // one a standing goal the harness re-injects to continue work, all carrying
+  // `promptSource: "system"`. It opens a run because a run is work that began, and this input is
+  // what began it; an observer asking what the agent did and what triggered it is owed the answer
+  // "the harness continued itself", which is neither a person nor a peer. So it is attributed as
+  // itself rather than folded into either.
+  //
+  // WITHOUT THIS KEY THE MAPPER THROWS IN PRODUCTION on a value that is already in the corpus, and
+  // the throw is the correct behaviour for an unmeasured provenance. Adding it is what a
+  // measurement buys; guessing at it is what the throw exists to prevent.
+  "auto-continuation": "auto-continuation"
+};
+var ABSENT_ORIGIN_RULE = {
+  sdk: "sdk",
+  // MEASURED, 6 occurrences across the same 237-file corpus, and READ rather than counted: every
+  // one is a person typing, each a file path followed by a question about it. They carry no
+  // `origin` because the harness does not stamp one on this shape, not because nobody authored
+  // them.
+  //
+  // This is the case the previous table would have THROWN on, which is why it had to be read and
+  // not assumed. A throw here is a session that stops mapping mid-stream; attributing these to
+  // anything other than the person who typed them would be the confident wrong attribution the
+  // enumeration exists to prevent. Both failures were available, so the record was opened.
+  typed: "human",
+  // **NOT FROM MY CORPUS — FROM §3.1's, WHICH I CANNOT RE-READ.** My 88-session sweep finds this
+  // value on an absent-origin `user` record ZERO times in 129,910 records. §3.1's table records it
+  // 81 times, as "local-command caveats, heartbeats, resumed-session summaries", on a capture with
+  // 4728 `user` entries and 3068 `channel` deliveries — and **no session on this machine matches
+  // that shape**; the closest has 18 human and 0 channel. So the two measurements are over different
+  // corpora and one of them is gone.
+  //
+  // It is entered as `null` — known, and NOT a turn — because §3.1 already classified it and a
+  // measurement I cannot repeat is still a measurement. Leaving it out would make the throw below
+  // fire in production on a class the plan documents, which is the one thing a fail-loud branch must
+  // not do: **a fail-loud branch is only safe if you know what is on the other side of it.**
+  system: null
+};
+var runOpeningAttribution = (entry) => {
+  const kind = entry.origin?.kind;
+  if (kind === void 0) {
+    const ps = entry.promptSource;
+    if (ps === void 0) return null;
+    if (!(ps in ABSENT_ORIGIN_RULE))
+      throw new Error(
+        `agui-map: origin-less entry ${entry.uuid ?? "<no uuid>"} carries promptSource ${JSON.stringify(ps)}, which this mapper has never measured. Refusing to decide whether it begins a run. Add it to ABSENT_ORIGIN_RULE deliberately, with a measurement.`
+      );
+    return ABSENT_ORIGIN_RULE[ps];
   }
-  if (e.type === "user") {
-    if (typeof content === "string")
-      return content.trim() ? [`\xBB ${truncate(content.trim(), MAX_PREVIEW)}`] : [];
-    if (Array.isArray(content)) {
-      const out = [];
-      for (const b of content) {
-        if (b.type === "tool_result") {
-          const t = resultText(b.content).trim();
-          out.push(`\u2192 ${b.is_error ? "ERROR: " : ""}${t ? truncate(t, MAX_PREVIEW) : "(no output)"}`);
-        } else if (b.type === "text" && b.text?.trim()) {
-          out.push(`\xBB ${truncate(b.text.trim(), MAX_PREVIEW)}`);
-        }
+  if (!(kind in ORIGIN_RULE))
+    throw new Error(
+      `agui-map: unrecognised origin.kind ${JSON.stringify(kind)} on entry ${entry.uuid ?? "<no uuid>"} \u2014 refusing to decide whether it begins a run, or to attribute one to a provenance this mapper has never seen. Add it to ORIGIN_RULE deliberately, with a measurement.`
+    );
+  return ORIGIN_RULE[kind];
+};
+function stampOf(entry, now) {
+  const parsed = entry.timestamp ? Date.parse(entry.timestamp) : Number.NaN;
+  return Number.isFinite(parsed) ? { ts: parsed, arrival: false } : { ts: now(), arrival: true };
+}
+function resultContent(raw) {
+  return typeof raw === "string" ? raw : JSON.stringify(raw ?? null);
+}
+function createClaudeMapper(opts) {
+  const now = opts.now ?? (() => Date.now());
+  let open5 = null;
+  let runsOpened = 0;
+  let promptShaped = 0;
+  let refusedUnattributable = 0;
+  const closeOpenRun = (timestamp, stopReason) => {
+    if (open5 === null) return null;
+    const runId = open5;
+    open5 = null;
+    return {
+      runId,
+      events: [
+        runFinished({
+          threadId: opts.threadId,
+          runId,
+          timestamp,
+          ...stopReason ? { cotal: { stopReason } } : {}
+        })
+      ]
+    };
+  };
+  const map2 = (entry) => {
+    const { ts, arrival } = stampOf(entry, now);
+    const arrivalMeta = arrival ? { tsSource: "arrival" } : void 0;
+    const uuid3 = entry.uuid ?? "";
+    const events2 = [];
+    if (entry.type === "user") {
+      const content = entry.message?.content;
+      const toolResults = Array.isArray(content) ? content.filter((b) => b.type === "tool_result" && b.tool_use_id) : [];
+      if (toolResults.length > 0) {
+        content.forEach((b, i) => {
+          if (b.type !== "tool_result" || !b.tool_use_id) return;
+          events2.push(
+            toolCallResult({
+              messageId: `${uuid3}#${i}`,
+              toolCallId: b.tool_use_id,
+              content: resultContent(b.content),
+              timestamp: ts,
+              ...b.is_error || arrivalMeta ? { cotal: { ...b.is_error ? { isError: true } : {}, ...arrivalMeta } } : {}
+            })
+          );
+        });
+        return events2.length > 0 && open5 !== null ? { runId: open5, events: events2 } : null;
+      }
+      const promptText = typeof content === "string" ? content : Array.isArray(content) ? content.filter((b) => b.type === "text" && typeof b.text === "string").map((b) => b.text).join("\n") : null;
+      if (promptText === null) return null;
+      if (entry.isCompactSummary === true || entry.isVisibleInTranscriptOnly === true) return null;
+      promptShaped += 1;
+      const turnSource = runOpeningAttribution(entry);
+      if (turnSource === null) {
+        refusedUnattributable += 1;
+        return null;
       }
-      return out;
-    }
-  }
-  return [];
-}
-var TranscriptMirror = class {
-  constructor(agent, channel) {
-    this.agent = agent;
-    this.channel = channel;
-  }
-  agent;
-  channel;
-  path;
-  offset = 0;
-  /** A batch that failed mid-publish: chunks + how many already landed. Retried (from the
-   *  first unsent chunk — never re-sending a delivered one) before any new read. */
-  pending;
-  /** ALL path/offset mutation and publishing runs on this serialized chain — hook events
-   *  land concurrently on the control socket. */
-  chain = Promise.resolve();
-  /** Adopt the transcript at its CURRENT end — mirror only what happens from now on, so a
-   *  resumed session (or a mirror that first sees the path mid-session) never rebroadcasts. */
-  adopt(path) {
-    this.enqueue(() => {
-      this.adoptNow(path);
-      return Promise.resolve();
-    });
-  }
-  /** Queue a flush of new transcript entries to the channel. Never throws, never blocks the
-   *  hook reply — the read+publish runs on the serialized chain. */
-  flush(path) {
-    this.enqueue(() => {
-      if (!this.path) this.adoptNow(path);
-      return this.doFlush();
-    });
-  }
-  enqueue(step) {
-    this.chain = this.chain.then(step).catch((e) => {
-      process.stderr.write(`[cotal-connector] transcript mirror: ${e.message}
-`);
-    });
-  }
-  adoptNow(path) {
-    if (typeof path !== "string" || !path || this.path === path) return;
-    this.path = path;
-    this.pending = void 0;
-    try {
-      this.offset = (0, import_node_fs4.statSync)(path).size;
-    } catch {
-      this.offset = 0;
-    }
-  }
-  async doFlush() {
-    if (!this.path || !this.agent.connected) return;
-    if (!this.pending) {
-      const { lines, nextOffset } = this.readComplete();
-      if (nextOffset === this.offset) return;
-      this.pending = { chunks: chunkLines(lines.flatMap(condense), MAX_CHUNK), sent: 0, nextOffset };
-    }
-    const p = this.pending;
-    while (p.sent < p.chunks.length) {
-      await this.agent.send(p.chunks[p.sent], this.channel);
-      p.sent++;
-    }
-    this.offset = p.nextOffset;
-    this.pending = void 0;
-  }
-  /** New complete lines since the offset (a trailing partial line stays for the next flush). */
-  readComplete() {
-    const none = () => ({ lines: [], nextOffset: this.offset });
-    let fd;
-    try {
-      fd = (0, import_node_fs4.openSync)(this.path, "r");
-    } catch {
-      return none();
-    }
-    try {
-      const size = (0, import_node_fs4.fstatSync)(fd).size;
-      if (size < this.offset) this.offset = 0;
-      if (size === this.offset) return none();
-      const buf = Buffer.alloc(size - this.offset);
-      (0, import_node_fs4.readSync)(fd, buf, 0, buf.length, this.offset);
-      const text = buf.toString("utf8");
-      const lastNl = text.lastIndexOf("\n");
-      if (lastNl < 0) return none();
+      const prior = closeOpenRun(ts);
+      const runId2 = opts.mintRunId();
+      open5 = runId2;
+      runsOpened += 1;
+      const messageId = `${uuid3}#0`;
+      const selfAuthored = turnSource !== "channel";
+      const carriesBody = selfAuthored && promptText.length > 0;
       return {
-        lines: text.slice(0, lastNl).split("\n").filter(Boolean),
-        nextOffset: this.offset + Buffer.byteLength(text.slice(0, lastNl + 1), "utf8")
+        runId: runId2,
+        events: [
+          ...prior?.events ?? [],
+          runStarted({
+            threadId: opts.threadId,
+            runId: runId2,
+            timestamp: ts,
+            cotal: { runIdSource: "connector", turnSource, ...arrivalMeta }
+          }),
+          ...carriesBody ? [
+            textMessageStart({ messageId, timestamp: ts, role: "user", ...arrivalMeta ? { cotal: arrivalMeta } : {} }),
+            textMessageContent({ messageId, delta: promptText, timestamp: ts }),
+            textMessageEnd({ messageId, timestamp: ts })
+          ] : []
+        ]
       };
-    } finally {
-      (0, import_node_fs4.closeSync)(fd);
     }
-  }
-};
-function chunkLines(lines, max) {
-  const chunks = [];
-  let cur = "";
-  for (const line of lines) {
-    if (cur && cur.length + 1 + line.length > max) {
-      chunks.push(cur);
-      cur = line;
-    } else {
-      cur = cur ? `${cur}
-${line}` : line;
-    }
-  }
-  if (cur) chunks.push(cur);
-  return chunks;
+    if (entry.type !== "assistant" || !Array.isArray(entry.message?.content)) return null;
+    const runId = open5;
+    entry.message.content.forEach((b, i) => {
+      const messageId = `${uuid3}#${i}`;
+      const meta3 = {
+        ...entry.message?.id ? { providerMessageId: entry.message.id } : {},
+        ...entry.message?.stop_reason ? { stopReason: entry.message.stop_reason } : {},
+        ...arrivalMeta
+      };
+      const cotal = Object.keys(meta3).length > 0 ? { cotal: meta3 } : {};
+      if (b.type === "text" && typeof b.text === "string") {
+        events2.push(
+          textMessageStart({ messageId, timestamp: ts, role: "assistant", ...cotal }),
+          textMessageContent({ messageId, delta: b.text, timestamp: ts }),
+          textMessageEnd({ messageId, timestamp: ts })
+        );
+        return;
+      }
+      if (b.type === "thinking" && opts.reasoning && typeof b.thinking === "string") {
+        events2.push(
+          reasoningMessageStart({ messageId, timestamp: ts, ...cotal }),
+          reasoningMessageContent({ messageId, delta: b.thinking, timestamp: ts }),
+          reasoningMessageEnd({ messageId, timestamp: ts })
+        );
+        return;
+      }
+      if (b.type === "tool_use" && b.id) {
+        events2.push(
+          toolCallStart({
+            toolCallId: b.id,
+            toolCallName: b.name ?? "",
+            timestamp: ts,
+            parentMessageId: messageId,
+            ...cotal
+          }),
+          toolCallArgs({ toolCallId: b.id, delta: JSON.stringify(b.input ?? null), timestamp: ts }),
+          toolCallEnd({ toolCallId: b.id, timestamp: ts })
+        );
+      }
+    });
+    if (events2.length === 0) return null;
+    return runId === null ? null : { runId, events: events2 };
+  };
+  const diagnose = () => {
+    if (runsOpened > 0) return null;
+    if (promptShaped === 0)
+      return `agui-map: no run opened \u2014 this session contains no prompt-shaped record at all (no string-content, non-compaction \`user\` entry). Nothing was refused; there was nothing to refuse.`;
+    return `agui-map: NO RUN OPENED, and it was a refusal, not an empty session \u2014 ${refusedUnattributable} of ${promptShaped} prompt-shaped record(s) carry neither an \`origin.kind\` this mapper enumerates nor \`promptSource: "sdk"\`, so none of them could be attributed and none opened a run. Every event downstream of a run is therefore absent BY DECISION. If these are real prompts, the harness has a provenance shape that has not been measured: measure it and add it to ORIGIN_RULE or ABSENT_ORIGIN_RULE deliberately.`;
+  };
+  const forgetOpenRun = (runId) => {
+    if (open5 === runId) open5 = null;
+  };
+  return { map: map2, closeOpenRun, openRun: () => open5, forgetOpenRun, diagnose };
 }
 
 // src/mcp.ts
-var mirror;
-var claude = createClaudeHandle({ mirror: () => mirror });
+var events;
+var claude = createClaudeHandle({ events: () => events });
 async function main() {
   if (!hasIdentity()) {
     process.stderr.write("[cotal-connector] no COTAL_NAME \u2014 not a managed session; staying off the mesh\n");
@@ -66930,8 +68816,37 @@ async function main() {
   config2.connector = "claude";
   const agent = new MeshAgent(config2);
   agent.start();
-  if (/^(1|true|yes|on)$/i.test(process.env.COTAL_TRANSCRIPT ?? ""))
-    mirror = new TranscriptMirror(agent, transcriptChannel(config2.name));
+  if (/^(1|true|yes|on)$/i.test(process.env.COTAL_EVENTS ?? "")) {
+    let mapper;
+    events = new AguiEmitterHolder(
+      async (transcriptPath) => {
+        const workspaceRoot = resolveEventsStateRoot(process.env);
+        const threadId = (0, import_node_path6.basename)(transcriptPath, ".jsonl");
+        const principal = principalKey(agent.ep.principal.owner, agent.ep.principal.actor).key;
+        const { walPath, subjectPath } = await ensureEventWalDir({ workspaceRoot, space: config2.space, principal, threadId });
+        const subjectFrontier = await FileSubjectFrontier.open(subjectPath, { space: config2.space, principal });
+        const wal = await EventWal.open(walPath, { space: config2.space, threadId, principal, subjectMayExist: false });
+        mapper = createClaudeMapper({ threadId, mintRunId: () => (0, import_node_crypto14.randomUUID)() });
+        return AguiEmitter.start({
+          endpoint: agent.ep,
+          wal,
+          subjectFrontier,
+          source: new JsonlFileSource(transcriptPath),
+          map: mapper.map
+        });
+      },
+      // Required, and not defaulted to a swallow: this runs behind a hook that must not throw, so
+      // a failure reaches a human only if it is written somewhere. The holder is terminal on
+      // error, it does not retry, so this line is the whole record of why events stopped.
+      (e) => process.stderr.write(`[cotal-connector] AG-UI emitter stopped: ${e.message}
+`),
+      // The turn terminal closes a run the record stream never described, so the mapper still
+      // believes that run is open. Without this it would attribute the next records to a run the
+      // published stream has already finished and the emitter would refuse the batch. Keyed on the
+      // id, so a newer run opened in between is left alone.
+      (runId) => mapper?.forgetOpenRun(runId)
+    );
+  }
   const controlPath = process.env.COTAL_CONTROL_SOCKET;
   const controlToken = process.env.COTAL_CONTROL_TOKEN;
   if (!controlPath || !controlToken) {