@kmmao/happy-agent 0.5.4 → 0.5.5

package/dist/index.mjs

@@ -1,8 +1,8 @@
 import { Command } from 'commander';
+import { randomBytes, createCipheriv, createHash, createDecipheriv, createHmac, randomUUID as randomUUID$1 } from 'node:crypto';
 import { homedir, hostname } from 'node:os';
 import { join, dirname } from 'node:path';
 import { mkdirSync, writeFileSync, unlinkSync, readFileSync, appendFileSync } from 'node:fs';
-import { randomBytes, createCipheriv, createHash, createDecipheriv, createHmac } from 'node:crypto';
 import tweetnacl from 'tweetnacl';
 import axios, { AxiosError } from 'axios';
 import qrcode from 'qrcode-terminal';
@@ -16,8 +16,10 @@ import { join as join$1, resolve, dirname as dirname$1 } from 'path';
 import { realpathSync, readFileSync as readFileSync$1, mkdirSync as mkdirSync$1, writeFileSync as writeFileSync$1 } from 'fs';
 import { tmpdir } from 'os';
 import { createServer } from 'http';
+import * as z from 'zod';
+import { z as z$1 } from 'zod';
 
-var version = "0.5.4";
+var version = "0.5.5";
 
 function loadConfig() {
   const serverUrl = (process.env.HAPPY_SERVER_URL ?? "https://s.sangreal.code.xycloud.info:2443").replace(/\/+$/, "");
@@ -226,7 +228,7 @@ async function authLogin(config, opts) {
   }
   const startTime = Date.now();
   while (Date.now() - startTime < AUTH_TIMEOUT_MS) {
-    await sleep(POLL_INTERVAL_MS);
+    await sleep$1(POLL_INTERVAL_MS);
     let result;
     try {
       const resp = await axios.post(`${config.serverUrl}/v1/auth/account/request`, {
@@ -270,7 +272,7 @@ async function authStatus(config) {
     console.log("- Action: Run `happy-agent auth login` to authenticate.");
   }
 }
-function sleep(ms) {
+function sleep$1(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
@@ -306,6 +308,7 @@ function decryptSession(raw, creds) {
     active: raw.active,
     activeAt: raw.activeAt,
     metadata: decryptField(raw.metadata, encryption),
+    metadataVersion: raw.metadataVersion,
     agentState: decryptField(raw.agentState, encryption),
     dataEncryptionKey: raw.dataEncryptionKey,
     encryption
@@ -1428,6 +1431,12 @@ class SessionClient extends EventEmitter {
     this.sessionId = opts.sessionId;
     this.encryptionKey = opts.encryptionKey;
     this.encryptionVariant = opts.encryptionVariant;
+    if (opts.initialMetadata !== void 0) {
+      this.metadata = opts.initialMetadata;
+    }
+    if (opts.initialMetadataVersion !== void 0) {
+      this.metadataVersion = opts.initialMetadataVersion;
+    }
     if (opts.initialAgentState !== void 0) {
       this.agentState = opts.initialAgentState;
     }
@@ -1480,6 +1489,9 @@ class SessionClient extends EventEmitter {
   getMetadata() {
     return this.metadata;
   }
+  getMetadataVersion() {
+    return this.metadataVersion;
+  }
   getAgentState() {
     return this.agentState;
   }
@@ -1580,42 +1592,51 @@ class SessionClient extends EventEmitter {
   // -----------------------------------------------------------------------
   // New: OCC metadata/state updates
   // -----------------------------------------------------------------------
-  async updateMetadata(newMetadata) {
+  async updateMetadataOnce(newMetadata) {
     const encrypted = encodeBase64(
       encrypt(this.encryptionKey, this.encryptionVariant, newMetadata)
     );
-    await withBackoff(
-      () => new Promise((resolve, reject) => {
-        this.socket.emit(
-          "update-metadata",
-          {
-            sid: this.sessionId,
-            expectedVersion: this.metadataVersion,
-            metadata: encrypted
-          },
-          (answer) => {
-            if (answer.result === "success" && answer.version !== void 0) {
-              this.metadataVersion = answer.version;
-              this.metadata = newMetadata;
-              resolve();
-            } else if (answer.result === "version-mismatch" && answer.version !== void 0) {
-              this.metadataVersion = answer.version;
-              if (answer.metadata) {
-                this.metadata = decrypt(
-                  this.encryptionKey,
-                  this.encryptionVariant,
-                  decodeBase64(answer.metadata)
-                );
-              }
-              reject(new Error("version-mismatch"));
-            } else {
-              reject(new Error(`update-metadata failed: ${answer.result}`));
+    await new Promise((resolve, reject) => {
+      this.socket.emit(
+        "update-metadata",
+        {
+          sid: this.sessionId,
+          expectedVersion: this.metadataVersion,
+          metadata: encrypted
+        },
+        (answer) => {
+          if (answer.result === "success" && answer.version !== void 0) {
+            this.metadataVersion = answer.version;
+            this.metadata = newMetadata;
+            resolve();
+          } else if (answer.result === "version-mismatch" && answer.version !== void 0) {
+            this.metadataVersion = answer.version;
+            if (answer.metadata) {
+              this.metadata = decrypt(
+                this.encryptionKey,
+                this.encryptionVariant,
+                decodeBase64(answer.metadata)
+              );
             }
+            reject(new Error("version-mismatch"));
+          } else {
+            reject(new Error(`update-metadata failed: ${answer.result}`));
           }
-        );
-      }),
-      { maxRetries: 3, label: "updateMetadata" }
-    );
+        }
+      );
+    });
+  }
+  async updateMetadata(newMetadata) {
+    await withBackoff(() => this.updateMetadataOnce(newMetadata), {
+      maxRetries: 3,
+      label: "updateMetadata"
+    });
+  }
+  async updateMetadataWith(handler) {
+    await withBackoff(async () => {
+      const updated = handler(this.metadata);
+      await this.updateMetadataOnce(updated);
+    }, { maxRetries: 3, label: "updateMetadataWith" });
   }
   async updateAgentState(newState) {
     const encrypted = newState !== null ? encodeBase64(encrypt(this.encryptionKey, this.encryptionVariant, newState)) : null;
@@ -3428,9 +3449,2227 @@ function daemonStatus() {
   }
 }
 
+var commonjsGlobal = typeof globalThis !== "undefined" ? globalThis : typeof window !== "undefined" ? window : typeof global !== "undefined" ? global : typeof self !== "undefined" ? self : {};
+
+var cuid2 = {};
+
+var src = {};
+
+var sha3 = {};
+
+var _u64 = {};
+
+var hasRequired_u64;
+
+function require_u64 () {
+	if (hasRequired_u64) return _u64;
+	hasRequired_u64 = 1;
+	Object.defineProperty(_u64, "__esModule", { value: true });
+	_u64.toBig = _u64.shrSL = _u64.shrSH = _u64.rotrSL = _u64.rotrSH = _u64.rotrBL = _u64.rotrBH = _u64.rotr32L = _u64.rotr32H = _u64.rotlSL = _u64.rotlSH = _u64.rotlBL = _u64.rotlBH = _u64.add5L = _u64.add5H = _u64.add4L = _u64.add4H = _u64.add3L = _u64.add3H = void 0;
+	_u64.add = add;
+	_u64.fromBig = fromBig;
+	_u64.split = split;
+	const U32_MASK64 = /* @__PURE__ */ BigInt(2 ** 32 - 1);
+	const _32n = /* @__PURE__ */ BigInt(32);
+	function fromBig(n, le = false) {
+	  if (le)
+	    return { h: Number(n & U32_MASK64), l: Number(n >> _32n & U32_MASK64) };
+	  return { h: Number(n >> _32n & U32_MASK64) | 0, l: Number(n & U32_MASK64) | 0 };
+	}
+	function split(lst, le = false) {
+	  const len = lst.length;
+	  let Ah = new Uint32Array(len);
+	  let Al = new Uint32Array(len);
+	  for (let i = 0; i < len; i++) {
+	    const { h, l } = fromBig(lst[i], le);
+	    [Ah[i], Al[i]] = [h, l];
+	  }
+	  return [Ah, Al];
+	}
+	const toBig = (h, l) => BigInt(h >>> 0) << _32n | BigInt(l >>> 0);
+	_u64.toBig = toBig;
+	const shrSH = (h, _l, s) => h >>> s;
+	_u64.shrSH = shrSH;
+	const shrSL = (h, l, s) => h << 32 - s | l >>> s;
+	_u64.shrSL = shrSL;
+	const rotrSH = (h, l, s) => h >>> s | l << 32 - s;
+	_u64.rotrSH = rotrSH;
+	const rotrSL = (h, l, s) => h << 32 - s | l >>> s;
+	_u64.rotrSL = rotrSL;
+	const rotrBH = (h, l, s) => h << 64 - s | l >>> s - 32;
+	_u64.rotrBH = rotrBH;
+	const rotrBL = (h, l, s) => h >>> s - 32 | l << 64 - s;
+	_u64.rotrBL = rotrBL;
+	const rotr32H = (_h, l) => l;
+	_u64.rotr32H = rotr32H;
+	const rotr32L = (h, _l) => h;
+	_u64.rotr32L = rotr32L;
+	const rotlSH = (h, l, s) => h << s | l >>> 32 - s;
+	_u64.rotlSH = rotlSH;
+	const rotlSL = (h, l, s) => l << s | h >>> 32 - s;
+	_u64.rotlSL = rotlSL;
+	const rotlBH = (h, l, s) => l << s - 32 | h >>> 64 - s;
+	_u64.rotlBH = rotlBH;
+	const rotlBL = (h, l, s) => h << s - 32 | l >>> 64 - s;
+	_u64.rotlBL = rotlBL;
+	function add(Ah, Al, Bh, Bl) {
+	  const l = (Al >>> 0) + (Bl >>> 0);
+	  return { h: Ah + Bh + (l / 2 ** 32 | 0) | 0, l: l | 0 };
+	}
+	const add3L = (Al, Bl, Cl) => (Al >>> 0) + (Bl >>> 0) + (Cl >>> 0);
+	_u64.add3L = add3L;
+	const add3H = (low, Ah, Bh, Ch) => Ah + Bh + Ch + (low / 2 ** 32 | 0) | 0;
+	_u64.add3H = add3H;
+	const add4L = (Al, Bl, Cl, Dl) => (Al >>> 0) + (Bl >>> 0) + (Cl >>> 0) + (Dl >>> 0);
+	_u64.add4L = add4L;
+	const add4H = (low, Ah, Bh, Ch, Dh) => Ah + Bh + Ch + Dh + (low / 2 ** 32 | 0) | 0;
+	_u64.add4H = add4H;
+	const add5L = (Al, Bl, Cl, Dl, El) => (Al >>> 0) + (Bl >>> 0) + (Cl >>> 0) + (Dl >>> 0) + (El >>> 0);
+	_u64.add5L = add5L;
+	const add5H = (low, Ah, Bh, Ch, Dh, Eh) => Ah + Bh + Ch + Dh + Eh + (low / 2 ** 32 | 0) | 0;
+	_u64.add5H = add5H;
+	const u64 = {
+	  fromBig,
+	  split,
+	  toBig,
+	  shrSH,
+	  shrSL,
+	  rotrSH,
+	  rotrSL,
+	  rotrBH,
+	  rotrBL,
+	  rotr32H,
+	  rotr32L,
+	  rotlSH,
+	  rotlSL,
+	  rotlBH,
+	  rotlBL,
+	  add,
+	  add3L,
+	  add3H,
+	  add4L,
+	  add4H,
+	  add5H,
+	  add5L
+	};
+	_u64.default = u64;
+	return _u64;
+}
+
+var utils = {};
+
+var crypto = {};
+
+var hasRequiredCrypto;
+
+function requireCrypto () {
+	if (hasRequiredCrypto) return crypto;
+	hasRequiredCrypto = 1;
+	Object.defineProperty(crypto, "__esModule", { value: true });
+	crypto.crypto = void 0;
+	crypto.crypto = typeof globalThis === "object" && "crypto" in globalThis ? globalThis.crypto : void 0;
+	return crypto;
+}
+
+var hasRequiredUtils;
+
+function requireUtils () {
+	if (hasRequiredUtils) return utils;
+	hasRequiredUtils = 1;
+	(function (exports$1) {
+		/*! noble-hashes - MIT License (c) 2022 Paul Miller (paulmillr.com) */
+		Object.defineProperty(exports$1, "__esModule", { value: true });
+		exports$1.wrapXOFConstructorWithOpts = exports$1.wrapConstructorWithOpts = exports$1.wrapConstructor = exports$1.Hash = exports$1.nextTick = exports$1.swap32IfBE = exports$1.byteSwapIfBE = exports$1.swap8IfBE = exports$1.isLE = void 0;
+		exports$1.isBytes = isBytes;
+		exports$1.anumber = anumber;
+		exports$1.abytes = abytes;
+		exports$1.ahash = ahash;
+		exports$1.aexists = aexists;
+		exports$1.aoutput = aoutput;
+		exports$1.u8 = u8;
+		exports$1.u32 = u32;
+		exports$1.clean = clean;
+		exports$1.createView = createView;
+		exports$1.rotr = rotr;
+		exports$1.rotl = rotl;
+		exports$1.byteSwap = byteSwap;
+		exports$1.byteSwap32 = byteSwap32;
+		exports$1.bytesToHex = bytesToHex;
+		exports$1.hexToBytes = hexToBytes;
+		exports$1.asyncLoop = asyncLoop;
+		exports$1.utf8ToBytes = utf8ToBytes;
+		exports$1.bytesToUtf8 = bytesToUtf8;
+		exports$1.toBytes = toBytes;
+		exports$1.kdfInputToBytes = kdfInputToBytes;
+		exports$1.concatBytes = concatBytes;
+		exports$1.checkOpts = checkOpts;
+		exports$1.createHasher = createHasher;
+		exports$1.createOptHasher = createOptHasher;
+		exports$1.createXOFer = createXOFer;
+		exports$1.randomBytes = randomBytes;
+		const crypto_1 = requireCrypto();
+		function isBytes(a) {
+		  return a instanceof Uint8Array || ArrayBuffer.isView(a) && a.constructor.name === "Uint8Array";
+		}
+		function anumber(n) {
+		  if (!Number.isSafeInteger(n) || n < 0)
+		    throw new Error("positive integer expected, got " + n);
+		}
+		function abytes(b, ...lengths) {
+		  if (!isBytes(b))
+		    throw new Error("Uint8Array expected");
+		  if (lengths.length > 0 && !lengths.includes(b.length))
+		    throw new Error("Uint8Array expected of length " + lengths + ", got length=" + b.length);
+		}
+		function ahash(h) {
+		  if (typeof h !== "function" || typeof h.create !== "function")
+		    throw new Error("Hash should be wrapped by utils.createHasher");
+		  anumber(h.outputLen);
+		  anumber(h.blockLen);
+		}
+		function aexists(instance, checkFinished = true) {
+		  if (instance.destroyed)
+		    throw new Error("Hash instance has been destroyed");
+		  if (checkFinished && instance.finished)
+		    throw new Error("Hash#digest() has already been called");
+		}
+		function aoutput(out, instance) {
+		  abytes(out);
+		  const min = instance.outputLen;
+		  if (out.length < min) {
+		    throw new Error("digestInto() expects output buffer of length at least " + min);
+		  }
+		}
+		function u8(arr) {
+		  return new Uint8Array(arr.buffer, arr.byteOffset, arr.byteLength);
+		}
+		function u32(arr) {
+		  return new Uint32Array(arr.buffer, arr.byteOffset, Math.floor(arr.byteLength / 4));
+		}
+		function clean(...arrays) {
+		  for (let i = 0; i < arrays.length; i++) {
+		    arrays[i].fill(0);
+		  }
+		}
+		function createView(arr) {
+		  return new DataView(arr.buffer, arr.byteOffset, arr.byteLength);
+		}
+		function rotr(word, shift) {
+		  return word << 32 - shift | word >>> shift;
+		}
+		function rotl(word, shift) {
+		  return word << shift | word >>> 32 - shift >>> 0;
+		}
+		exports$1.isLE = (() => new Uint8Array(new Uint32Array([287454020]).buffer)[0] === 68)();
+		function byteSwap(word) {
+		  return word << 24 & 4278190080 | word << 8 & 16711680 | word >>> 8 & 65280 | word >>> 24 & 255;
+		}
+		exports$1.swap8IfBE = exports$1.isLE ? (n) => n : (n) => byteSwap(n);
+		exports$1.byteSwapIfBE = exports$1.swap8IfBE;
+		function byteSwap32(arr) {
+		  for (let i = 0; i < arr.length; i++) {
+		    arr[i] = byteSwap(arr[i]);
+		  }
+		  return arr;
+		}
+		exports$1.swap32IfBE = exports$1.isLE ? (u) => u : byteSwap32;
+		const hasHexBuiltin = /* @__PURE__ */ (() => (
+		  // @ts-ignore
+		  typeof Uint8Array.from([]).toHex === "function" && typeof Uint8Array.fromHex === "function"
+		))();
+		const hexes = /* @__PURE__ */ Array.from({ length: 256 }, (_, i) => i.toString(16).padStart(2, "0"));
+		function bytesToHex(bytes) {
+		  abytes(bytes);
+		  if (hasHexBuiltin)
+		    return bytes.toHex();
+		  let hex = "";
+		  for (let i = 0; i < bytes.length; i++) {
+		    hex += hexes[bytes[i]];
+		  }
+		  return hex;
+		}
+		const asciis = { _0: 48, _9: 57, A: 65, F: 70, a: 97, f: 102 };
+		function asciiToBase16(ch) {
+		  if (ch >= asciis._0 && ch <= asciis._9)
+		    return ch - asciis._0;
+		  if (ch >= asciis.A && ch <= asciis.F)
+		    return ch - (asciis.A - 10);
+		  if (ch >= asciis.a && ch <= asciis.f)
+		    return ch - (asciis.a - 10);
+		  return;
+		}
+		function hexToBytes(hex) {
+		  if (typeof hex !== "string")
+		    throw new Error("hex string expected, got " + typeof hex);
+		  if (hasHexBuiltin)
+		    return Uint8Array.fromHex(hex);
+		  const hl = hex.length;
+		  const al = hl / 2;
+		  if (hl % 2)
+		    throw new Error("hex string expected, got unpadded hex of length " + hl);
+		  const array = new Uint8Array(al);
+		  for (let ai = 0, hi = 0; ai < al; ai++, hi += 2) {
+		    const n1 = asciiToBase16(hex.charCodeAt(hi));
+		    const n2 = asciiToBase16(hex.charCodeAt(hi + 1));
+		    if (n1 === void 0 || n2 === void 0) {
+		      const char = hex[hi] + hex[hi + 1];
+		      throw new Error('hex string expected, got non-hex character "' + char + '" at index ' + hi);
+		    }
+		    array[ai] = n1 * 16 + n2;
+		  }
+		  return array;
+		}
+		const nextTick = async () => {
+		};
+		exports$1.nextTick = nextTick;
+		async function asyncLoop(iters, tick, cb) {
+		  let ts = Date.now();
+		  for (let i = 0; i < iters; i++) {
+		    cb(i);
+		    const diff = Date.now() - ts;
+		    if (diff >= 0 && diff < tick)
+		      continue;
+		    await (0, exports$1.nextTick)();
+		    ts += diff;
+		  }
+		}
+		function utf8ToBytes(str) {
+		  if (typeof str !== "string")
+		    throw new Error("string expected");
+		  return new Uint8Array(new TextEncoder().encode(str));
+		}
+		function bytesToUtf8(bytes) {
+		  return new TextDecoder().decode(bytes);
+		}
+		function toBytes(data) {
+		  if (typeof data === "string")
+		    data = utf8ToBytes(data);
+		  abytes(data);
+		  return data;
+		}
+		function kdfInputToBytes(data) {
+		  if (typeof data === "string")
+		    data = utf8ToBytes(data);
+		  abytes(data);
+		  return data;
+		}
+		function concatBytes(...arrays) {
+		  let sum = 0;
+		  for (let i = 0; i < arrays.length; i++) {
+		    const a = arrays[i];
+		    abytes(a);
+		    sum += a.length;
+		  }
+		  const res = new Uint8Array(sum);
+		  for (let i = 0, pad = 0; i < arrays.length; i++) {
+		    const a = arrays[i];
+		    res.set(a, pad);
+		    pad += a.length;
+		  }
+		  return res;
+		}
+		function checkOpts(defaults, opts) {
+		  if (opts !== void 0 && {}.toString.call(opts) !== "[object Object]")
+		    throw new Error("options should be object or undefined");
+		  const merged = Object.assign(defaults, opts);
+		  return merged;
+		}
+		class Hash {
+		}
+		exports$1.Hash = Hash;
+		function createHasher(hashCons) {
+		  const hashC = (msg) => hashCons().update(toBytes(msg)).digest();
+		  const tmp = hashCons();
+		  hashC.outputLen = tmp.outputLen;
+		  hashC.blockLen = tmp.blockLen;
+		  hashC.create = () => hashCons();
+		  return hashC;
+		}
+		function createOptHasher(hashCons) {
+		  const hashC = (msg, opts) => hashCons(opts).update(toBytes(msg)).digest();
+		  const tmp = hashCons({});
+		  hashC.outputLen = tmp.outputLen;
+		  hashC.blockLen = tmp.blockLen;
+		  hashC.create = (opts) => hashCons(opts);
+		  return hashC;
+		}
+		function createXOFer(hashCons) {
+		  const hashC = (msg, opts) => hashCons(opts).update(toBytes(msg)).digest();
+		  const tmp = hashCons({});
+		  hashC.outputLen = tmp.outputLen;
+		  hashC.blockLen = tmp.blockLen;
+		  hashC.create = (opts) => hashCons(opts);
+		  return hashC;
+		}
+		exports$1.wrapConstructor = createHasher;
+		exports$1.wrapConstructorWithOpts = createOptHasher;
+		exports$1.wrapXOFConstructorWithOpts = createXOFer;
+		function randomBytes(bytesLength = 32) {
+		  if (crypto_1.crypto && typeof crypto_1.crypto.getRandomValues === "function") {
+		    return crypto_1.crypto.getRandomValues(new Uint8Array(bytesLength));
+		  }
+		  if (crypto_1.crypto && typeof crypto_1.crypto.randomBytes === "function") {
+		    return Uint8Array.from(crypto_1.crypto.randomBytes(bytesLength));
+		  }
+		  throw new Error("crypto.getRandomValues must be defined");
+		} 
+	} (utils));
+	return utils;
+}
+
+var hasRequiredSha3;
+
+function requireSha3 () {
+	if (hasRequiredSha3) return sha3;
+	hasRequiredSha3 = 1;
+	Object.defineProperty(sha3, "__esModule", { value: true });
+	sha3.shake256 = sha3.shake128 = sha3.keccak_512 = sha3.keccak_384 = sha3.keccak_256 = sha3.keccak_224 = sha3.sha3_512 = sha3.sha3_384 = sha3.sha3_256 = sha3.sha3_224 = sha3.Keccak = void 0;
+	sha3.keccakP = keccakP;
+	const _u64_ts_1 = /*@__PURE__*/ require_u64();
+	const utils_ts_1 = /*@__PURE__*/ requireUtils();
+	const _0n = BigInt(0);
+	const _1n = BigInt(1);
+	const _2n = BigInt(2);
+	const _7n = BigInt(7);
+	const _256n = BigInt(256);
+	const _0x71n = BigInt(113);
+	const SHA3_PI = [];
+	const SHA3_ROTL = [];
+	const _SHA3_IOTA = [];
+	for (let round = 0, R = _1n, x = 1, y = 0; round < 24; round++) {
+	  [x, y] = [y, (2 * x + 3 * y) % 5];
+	  SHA3_PI.push(2 * (5 * y + x));
+	  SHA3_ROTL.push((round + 1) * (round + 2) / 2 % 64);
+	  let t = _0n;
+	  for (let j = 0; j < 7; j++) {
+	    R = (R << _1n ^ (R >> _7n) * _0x71n) % _256n;
+	    if (R & _2n)
+	      t ^= _1n << (_1n << /* @__PURE__ */ BigInt(j)) - _1n;
+	  }
+	  _SHA3_IOTA.push(t);
+	}
+	const IOTAS = (0, _u64_ts_1.split)(_SHA3_IOTA, true);
+	const SHA3_IOTA_H = IOTAS[0];
+	const SHA3_IOTA_L = IOTAS[1];
+	const rotlH = (h, l, s) => s > 32 ? (0, _u64_ts_1.rotlBH)(h, l, s) : (0, _u64_ts_1.rotlSH)(h, l, s);
+	const rotlL = (h, l, s) => s > 32 ? (0, _u64_ts_1.rotlBL)(h, l, s) : (0, _u64_ts_1.rotlSL)(h, l, s);
+	function keccakP(s, rounds = 24) {
+	  const B = new Uint32Array(5 * 2);
+	  for (let round = 24 - rounds; round < 24; round++) {
+	    for (let x = 0; x < 10; x++)
+	      B[x] = s[x] ^ s[x + 10] ^ s[x + 20] ^ s[x + 30] ^ s[x + 40];
+	    for (let x = 0; x < 10; x += 2) {
+	      const idx1 = (x + 8) % 10;
+	      const idx0 = (x + 2) % 10;
+	      const B0 = B[idx0];
+	      const B1 = B[idx0 + 1];
+	      const Th = rotlH(B0, B1, 1) ^ B[idx1];
+	      const Tl = rotlL(B0, B1, 1) ^ B[idx1 + 1];
+	      for (let y = 0; y < 50; y += 10) {
+	        s[x + y] ^= Th;
+	        s[x + y + 1] ^= Tl;
+	      }
+	    }
+	    let curH = s[2];
+	    let curL = s[3];
+	    for (let t = 0; t < 24; t++) {
+	      const shift = SHA3_ROTL[t];
+	      const Th = rotlH(curH, curL, shift);
+	      const Tl = rotlL(curH, curL, shift);
+	      const PI = SHA3_PI[t];
+	      curH = s[PI];
+	      curL = s[PI + 1];
+	      s[PI] = Th;
+	      s[PI + 1] = Tl;
+	    }
+	    for (let y = 0; y < 50; y += 10) {
+	      for (let x = 0; x < 10; x++)
+	        B[x] = s[y + x];
+	      for (let x = 0; x < 10; x++)
+	        s[y + x] ^= ~B[(x + 2) % 10] & B[(x + 4) % 10];
+	    }
+	    s[0] ^= SHA3_IOTA_H[round];
+	    s[1] ^= SHA3_IOTA_L[round];
+	  }
+	  (0, utils_ts_1.clean)(B);
+	}
+	class Keccak extends utils_ts_1.Hash {
+	  // NOTE: we accept arguments in bytes instead of bits here.
+	  constructor(blockLen, suffix, outputLen, enableXOF = false, rounds = 24) {
+	    super();
+	    this.pos = 0;
+	    this.posOut = 0;
+	    this.finished = false;
+	    this.destroyed = false;
+	    this.enableXOF = false;
+	    this.blockLen = blockLen;
+	    this.suffix = suffix;
+	    this.outputLen = outputLen;
+	    this.enableXOF = enableXOF;
+	    this.rounds = rounds;
+	    (0, utils_ts_1.anumber)(outputLen);
+	    if (!(0 < blockLen && blockLen < 200))
+	      throw new Error("only keccak-f1600 function is supported");
+	    this.state = new Uint8Array(200);
+	    this.state32 = (0, utils_ts_1.u32)(this.state);
+	  }
+	  clone() {
+	    return this._cloneInto();
+	  }
+	  keccak() {
+	    (0, utils_ts_1.swap32IfBE)(this.state32);
+	    keccakP(this.state32, this.rounds);
+	    (0, utils_ts_1.swap32IfBE)(this.state32);
+	    this.posOut = 0;
+	    this.pos = 0;
+	  }
+	  update(data) {
+	    (0, utils_ts_1.aexists)(this);
+	    data = (0, utils_ts_1.toBytes)(data);
+	    (0, utils_ts_1.abytes)(data);
+	    const { blockLen, state } = this;
+	    const len = data.length;
+	    for (let pos = 0; pos < len; ) {
+	      const take = Math.min(blockLen - this.pos, len - pos);
+	      for (let i = 0; i < take; i++)
+	        state[this.pos++] ^= data[pos++];
+	      if (this.pos === blockLen)
+	        this.keccak();
+	    }
+	    return this;
+	  }
+	  finish() {
+	    if (this.finished)
+	      return;
+	    this.finished = true;
+	    const { state, suffix, pos, blockLen } = this;
+	    state[pos] ^= suffix;
+	    if ((suffix & 128) !== 0 && pos === blockLen - 1)
+	      this.keccak();
+	    state[blockLen - 1] ^= 128;
+	    this.keccak();
+	  }
+	  writeInto(out) {
+	    (0, utils_ts_1.aexists)(this, false);
+	    (0, utils_ts_1.abytes)(out);
+	    this.finish();
+	    const bufferOut = this.state;
+	    const { blockLen } = this;
+	    for (let pos = 0, len = out.length; pos < len; ) {
+	      if (this.posOut >= blockLen)
+	        this.keccak();
+	      const take = Math.min(blockLen - this.posOut, len - pos);
+	      out.set(bufferOut.subarray(this.posOut, this.posOut + take), pos);
+	      this.posOut += take;
+	      pos += take;
+	    }
+	    return out;
+	  }
+	  xofInto(out) {
+	    if (!this.enableXOF)
+	      throw new Error("XOF is not possible for this instance");
+	    return this.writeInto(out);
+	  }
+	  xof(bytes) {
+	    (0, utils_ts_1.anumber)(bytes);
+	    return this.xofInto(new Uint8Array(bytes));
+	  }
+	  digestInto(out) {
+	    (0, utils_ts_1.aoutput)(out, this);
+	    if (this.finished)
+	      throw new Error("digest() was already called");
+	    this.writeInto(out);
+	    this.destroy();
+	    return out;
+	  }
+	  digest() {
+	    return this.digestInto(new Uint8Array(this.outputLen));
+	  }
+	  destroy() {
+	    this.destroyed = true;
+	    (0, utils_ts_1.clean)(this.state);
+	  }
+	  _cloneInto(to) {
+	    const { blockLen, suffix, outputLen, rounds, enableXOF } = this;
+	    to || (to = new Keccak(blockLen, suffix, outputLen, enableXOF, rounds));
+	    to.state32.set(this.state32);
+	    to.pos = this.pos;
+	    to.posOut = this.posOut;
+	    to.finished = this.finished;
+	    to.rounds = rounds;
+	    to.suffix = suffix;
+	    to.outputLen = outputLen;
+	    to.enableXOF = enableXOF;
+	    to.destroyed = this.destroyed;
+	    return to;
+	  }
+	}
+	sha3.Keccak = Keccak;
+	const gen = (suffix, blockLen, outputLen) => (0, utils_ts_1.createHasher)(() => new Keccak(blockLen, suffix, outputLen));
+	sha3.sha3_224 = (() => gen(6, 144, 224 / 8))();
+	sha3.sha3_256 = (() => gen(6, 136, 256 / 8))();
+	sha3.sha3_384 = (() => gen(6, 104, 384 / 8))();
+	sha3.sha3_512 = (() => gen(6, 72, 512 / 8))();
+	sha3.keccak_224 = (() => gen(1, 144, 224 / 8))();
+	sha3.keccak_256 = (() => gen(1, 136, 256 / 8))();
+	sha3.keccak_384 = (() => gen(1, 104, 384 / 8))();
+	sha3.keccak_512 = (() => gen(1, 72, 512 / 8))();
+	const genShake = (suffix, blockLen, outputLen) => (0, utils_ts_1.createXOFer)((opts = {}) => new Keccak(blockLen, suffix, opts.dkLen === void 0 ? outputLen : opts.dkLen, true));
+	sha3.shake128 = (() => genShake(31, 168, 128 / 8))();
+	sha3.shake256 = (() => genShake(31, 136, 256 / 8))();
+	return sha3;
+}
+
+var hasRequiredSrc;
+
+function requireSrc () {
+	if (hasRequiredSrc) return src;
+	hasRequiredSrc = 1;
+	const { sha3_512: sha3 } = /*@__PURE__*/ requireSha3();
+	const defaultLength = 24;
+	const bigLength = 32;
+	const createEntropy = (length = 4, random = Math.random) => {
+	  let entropy = "";
+	  while (entropy.length < length) {
+	    entropy = entropy + Math.floor(random() * 36).toString(36);
+	  }
+	  return entropy;
+	};
+	function bufToBigInt(buf) {
+	  let bits = 8n;
+	  let value = 0n;
+	  for (const i of buf.values()) {
+	    const bi = BigInt(i);
+	    value = (value << bits) + bi;
+	  }
+	  return value;
+	}
+	const hash = (input = "") => {
+	  return bufToBigInt(sha3(input)).toString(36).slice(1);
+	};
+	const alphabet = Array.from(
+	  { length: 26 },
+	  (x, i) => String.fromCharCode(i + 97)
+	);
+	const randomLetter = (random) => alphabet[Math.floor(random() * alphabet.length)];
+	const createFingerprint = ({
+	  globalObj = typeof commonjsGlobal !== "undefined" ? commonjsGlobal : typeof window !== "undefined" ? window : {},
+	  random = Math.random
+	} = {}) => {
+	  const globals = Object.keys(globalObj).toString();
+	  const sourceString = globals.length ? globals + createEntropy(bigLength, random) : createEntropy(bigLength, random);
+	  return hash(sourceString).substring(0, bigLength);
+	};
+	const createCounter = (count) => () => {
+	  return count++;
+	};
+	const initialCountMax = 476782367;
+	const init = ({
+	  // Fallback if the user does not pass in a CSPRNG. This should be OK
+	  // because we don't rely solely on the random number generator for entropy.
+	  // We also use the host fingerprint, current time, and a session counter.
+	  random = Math.random,
+	  counter = createCounter(Math.floor(random() * initialCountMax)),
+	  length = defaultLength,
+	  fingerprint = createFingerprint({ random })
+	} = {}) => {
+	  return function cuid2() {
+	    const firstLetter = randomLetter(random);
+	    const time = Date.now().toString(36);
+	    const count = counter().toString(36);
+	    const salt = createEntropy(length, random);
+	    const hashInput = `${time + salt + count + fingerprint}`;
+	    return `${firstLetter + hash(hashInput).substring(1, length)}`;
+	  };
+	};
+	const createId = init();
+	const isCuid = (id, { minLength = 2, maxLength = bigLength } = {}) => {
+	  const length = id.length;
+	  const regex = /^[0-9a-z]+$/;
+	  try {
+	    if (typeof id === "string" && length >= minLength && length <= maxLength && regex.test(id))
+	      return true;
+	  } finally {
+	  }
+	  return false;
+	};
+	src.getConstants = () => ({ defaultLength, bigLength });
+	src.init = init;
+	src.createId = createId;
+	src.bufToBigInt = bufToBigInt;
+	src.createCounter = createCounter;
+	src.createFingerprint = createFingerprint;
+	src.isCuid = isCuid;
+	return src;
+}
+
+var hasRequiredCuid2;
+
+function requireCuid2 () {
+	if (hasRequiredCuid2) return cuid2;
+	hasRequiredCuid2 = 1;
+	const { createId, init, getConstants, isCuid } = requireSrc();
+	cuid2.createId = createId;
+	cuid2.init = init;
+	cuid2.getConstants = getConstants;
+	cuid2.isCuid = isCuid;
+	return cuid2;
+}
+
+var cuid2Exports = requireCuid2();
+
+const sessionRoleSchema = z.enum(["user", "agent"]);
+const sessionTextEventSchema = z.object({
+  t: z.literal("text"),
+  text: z.string(),
+  thinking: z.boolean().optional()
+});
+const sessionTextDeltaEventSchema = z.object({
+  t: z.literal("text-delta"),
+  stream: z.string(),
+  delta: z.string(),
+  thinking: z.boolean().optional()
+});
+const sessionServiceMessageEventSchema = z.object({
+  t: z.literal("service"),
+  text: z.string()
+});
+const sessionToolCallStartEventSchema = z.object({
+  t: z.literal("tool-call-start"),
+  call: z.string(),
+  name: z.string(),
+  title: z.string(),
+  description: z.string(),
+  args: z.record(z.string(), z.unknown())
+});
+const sessionToolCallEndEventSchema = z.object({
+  t: z.literal("tool-call-end"),
+  call: z.string(),
+  /** Background task ID when Bash command runs with run_in_background */
+  backgroundTaskId: z.string().optional(),
+  /** Path to the task output file on the CLI machine */
+  outputFile: z.string().optional()
+});
+const sessionFileEventSchema = z.object({
+  t: z.literal("file"),
+  ref: z.string(),
+  name: z.string(),
+  size: z.number(),
+  image: z.object({
+    width: z.number(),
+    height: z.number(),
+    thumbhash: z.string()
+  }).optional()
+});
+const sessionTurnStartEventSchema = z.object({
+  t: z.literal("turn-start")
+});
+const sessionStartEventSchema = z.object({
+  t: z.literal("start"),
+  title: z.string().optional()
+});
+const sessionTurnEndStatusSchema = z.enum([
+  "completed",
+  "failed",
+  "cancelled"
+]);
+const sessionModelUsageSchema = z.object({
+  inputTokens: z.number(),
+  outputTokens: z.number(),
+  cacheReadInputTokens: z.number(),
+  cacheCreationInputTokens: z.number(),
+  costUSD: z.number(),
+  contextWindow: z.number(),
+  maxOutputTokens: z.number()
+});
+const sessionTurnEndEventSchema = z.object({
+  t: z.literal("turn-end"),
+  status: sessionTurnEndStatusSchema,
+  model: z.string().optional(),
+  usage: z.object({
+    input_tokens: z.number(),
+    output_tokens: z.number(),
+    cache_creation_input_tokens: z.number().optional(),
+    cache_read_input_tokens: z.number().optional()
+  }).optional(),
+  durationMs: z.number().optional(),
+  totalCostUsd: z.number().optional(),
+  numTurns: z.number().optional(),
+  modelUsage: z.record(z.string(), sessionModelUsageSchema).optional()
+});
+const sessionStopEventSchema = z.object({
+  t: z.literal("stop")
+});
+const sessionUsageUpdateEventSchema = z.object({
+  t: z.literal("usage-update"),
+  model: z.string().optional(),
+  usage: z.object({
+    input_tokens: z.number(),
+    output_tokens: z.number(),
+    cache_creation_input_tokens: z.number().optional(),
+    cache_read_input_tokens: z.number().optional()
+  }),
+  durationMs: z.number().optional()
+});
+const sessionTaskStartEventSchema = z.object({
+  t: z.literal("task-start"),
+  taskId: z.string(),
+  toolUseId: z.string().optional(),
+  description: z.string(),
+  taskType: z.string().optional(),
+  /** meta.name from the workflow script (e.g. 'spec'). Only set when taskType is 'local_workflow'. */
+  workflowName: z.string().optional()
+});
+const sessionTaskProgressEventSchema = z.object({
+  t: z.literal("task-progress"),
+  taskId: z.string(),
+  description: z.string(),
+  usage: z.object({
+    totalTokens: z.number(),
+    toolUses: z.number(),
+    durationMs: z.number()
+  }).optional(),
+  lastToolName: z.string().optional(),
+  /** AI-generated progress summary (~30s interval, from agentProgressSummaries) */
+  summary: z.string().optional()
+});
+const sessionTaskEndEventSchema = z.object({
+  t: z.literal("task-end"),
+  taskId: z.string(),
+  status: z.enum(["completed", "failed", "stopped"]),
+  summary: z.string(),
+  usage: z.object({
+    totalTokens: z.number(),
+    toolUses: z.number(),
+    durationMs: z.number()
+  }).optional()
+});
+const sessionToolProgressEventSchema = z.object({
+  t: z.literal("tool-progress"),
+  toolUseId: z.string(),
+  toolName: z.string(),
+  elapsedSeconds: z.number(),
+  taskId: z.string().optional()
+});
+const sessionPromptSuggestionEventSchema = z.object({
+  t: z.literal("prompt-suggestion"),
+  suggestion: z.string()
+});
+const sessionNeedsContinueEventSchema = z.object({
+  t: z.literal("needs-continue")
+});
+const sessionStateChangedEventSchema = z.object({
+  t: z.literal("session-state-changed"),
+  /** Authoritative session lifecycle state from the SDK */
+  state: z.enum(["idle", "running", "requires_action"])
+});
+const sessionContextUsageCategorySchema = z.object({
+  name: z.string(),
+  tokens: z.number(),
+  color: z.string().optional()
+});
+const sessionTaskLogEventSchema = z.object({
+  t: z.literal("task-log"),
+  /** Background task ID or tool call ID that owns this log stream */
+  taskId: z.string(),
+  /** Path to the output file on the CLI machine */
+  outputFile: z.string(),
+  /** Incremental log content (new lines since last push) */
+  chunk: z.string(),
+  /** Byte offset in the output file where this chunk starts */
+  offset: z.number()
+});
+const sessionContextUsageEventSchema = z.object({
+  t: z.literal("context-usage"),
+  totalTokens: z.number(),
+  maxTokens: z.number(),
+  percentage: z.number(),
+  model: z.string().optional(),
+  categories: z.array(sessionContextUsageCategorySchema).optional(),
+  isAutoCompactEnabled: z.boolean().optional(),
+  autoCompactThreshold: z.number().optional(),
+  messageBreakdown: z.object({
+    toolCallTokens: z.number(),
+    toolResultTokens: z.number(),
+    attachmentTokens: z.number(),
+    assistantMessageTokens: z.number(),
+    userMessageTokens: z.number()
+  }).optional()
+});
+const sessionEventSchema = z.discriminatedUnion("t", [
+  sessionTextEventSchema,
+  sessionTextDeltaEventSchema,
+  sessionServiceMessageEventSchema,
+  sessionToolCallStartEventSchema,
+  sessionToolCallEndEventSchema,
+  sessionFileEventSchema,
+  sessionTurnStartEventSchema,
+  sessionStartEventSchema,
+  sessionTurnEndEventSchema,
+  sessionStopEventSchema,
+  sessionUsageUpdateEventSchema,
+  sessionTaskStartEventSchema,
+  sessionTaskProgressEventSchema,
+  sessionTaskEndEventSchema,
+  sessionToolProgressEventSchema,
+  sessionPromptSuggestionEventSchema,
+  sessionNeedsContinueEventSchema,
+  sessionStateChangedEventSchema,
+  sessionContextUsageEventSchema,
+  sessionTaskLogEventSchema
+]);
+const sessionEnvelopeSchema = z.object({
+  id: z.string(),
+  time: z.number(),
+  role: sessionRoleSchema,
+  turn: z.string().optional(),
+  subagent: z.string().refine((value) => cuid2Exports.isCuid(value), {
+    message: "subagent must be a cuid2 value"
+  }).optional(),
+  ev: sessionEventSchema
+}).superRefine((envelope, ctx) => {
+  if (envelope.ev.t === "service" && envelope.role !== "agent") {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: 'service events must use role "agent"',
+      path: ["role"]
+    });
+  }
+  if ((envelope.ev.t === "start" || envelope.ev.t === "stop" || envelope.ev.t === "usage-update" || envelope.ev.t === "task-start" || envelope.ev.t === "task-progress" || envelope.ev.t === "task-end" || envelope.ev.t === "tool-progress" || envelope.ev.t === "prompt-suggestion" || envelope.ev.t === "needs-continue" || envelope.ev.t === "session-state-changed" || envelope.ev.t === "context-usage" || envelope.ev.t === "task-log") && envelope.role !== "agent") {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: `${envelope.ev.t} events must use role "agent"`,
+      path: ["role"]
+    });
+  }
+});
+
+const MessageMetaSchema = z.object({
+  sentFrom: z.string().optional(),
+  permissionMode: z.enum(["default", "acceptEdits", "bypassPermissions", "plan", "dontAsk", "auto", "read-only", "safe-yolo", "yolo"]).optional(),
+  model: z.string().nullable().optional(),
+  fallbackModel: z.string().nullable().optional(),
+  customSystemPrompt: z.string().nullable().optional(),
+  appendSystemPrompt: z.string().nullable().optional(),
+  allowedTools: z.array(z.string()).nullable().optional(),
+  disallowedTools: z.array(z.string()).nullable().optional(),
+  displayText: z.string().optional(),
+  /**
+   * When false, the message is appended to the transcript without triggering
+   * an assistant turn. Requires @anthropic-ai/claude-agent-sdk 0.2.110+ on CLI.
+   * Defaults to true when unset (normal turn-triggering message).
+   */
+  shouldQuery: z.boolean().optional()
+});
+
+const UserMessageSchema = z.object({
+  role: z.literal("user"),
+  content: z.object({
+    type: z.literal("text"),
+    text: z.string()
+  }),
+  localKey: z.string().optional(),
+  meta: MessageMetaSchema.optional()
+});
+const AgentMessageSchema = z.object({
+  role: z.literal("agent"),
+  content: z.object({
+    type: z.string()
+  }).passthrough(),
+  meta: MessageMetaSchema.optional()
+});
+z.discriminatedUnion("role", [UserMessageSchema, AgentMessageSchema]);
+
+const SessionMessageContentSchema = z.object({
+  c: z.string(),
+  t: z.literal("encrypted")
+});
+const SessionMessageSchema = z.object({
+  id: z.string(),
+  seq: z.number(),
+  localId: z.string().nullish(),
+  content: SessionMessageContentSchema,
+  createdAt: z.number(),
+  updatedAt: z.number()
+});
+const SessionProtocolMessageSchema = z.object({
+  role: z.literal("session"),
+  content: sessionEnvelopeSchema,
+  meta: MessageMetaSchema.optional()
+});
+z.discriminatedUnion("role", [
+  UserMessageSchema,
+  AgentMessageSchema,
+  SessionProtocolMessageSchema
+]);
+const VersionedEncryptedValueSchema = z.object({
+  version: z.number(),
+  value: z.string()
+});
+const VersionedNullableEncryptedValueSchema = z.object({
+  version: z.number(),
+  value: z.string().nullable()
+});
+const UpdateNewMessageBodySchema = z.object({
+  t: z.literal("new-message"),
+  sid: z.string(),
+  message: SessionMessageSchema
+});
+const UpdateSessionBodySchema = z.object({
+  t: z.literal("update-session"),
+  id: z.string(),
+  metadata: VersionedEncryptedValueSchema.nullish(),
+  agentState: VersionedNullableEncryptedValueSchema.nullish(),
+  preferences: VersionedNullableEncryptedValueSchema.nullish()
+});
+const VersionedMachineEncryptedValueSchema = z.object({
+  version: z.number(),
+  value: z.string()
+});
+const UpdateMachineBodySchema = z.object({
+  t: z.literal("update-machine"),
+  machineId: z.string(),
+  metadata: VersionedMachineEncryptedValueSchema.nullish(),
+  daemonState: VersionedMachineEncryptedValueSchema.nullish(),
+  active: z.boolean().optional(),
+  activeAt: z.number().optional()
+});
+const CoreUpdateBodySchema = z.discriminatedUnion("t", [
+  UpdateNewMessageBodySchema,
+  UpdateSessionBodySchema,
+  UpdateMachineBodySchema
+]);
+z.object({
+  id: z.string(),
+  seq: z.number(),
+  body: CoreUpdateBodySchema,
+  createdAt: z.number()
+});
+
+z.object({
+  host: z.string(),
+  platform: z.string(),
+  happyCliVersion: z.string(),
+  homeDir: z.string(),
+  happyHomeDir: z.string(),
+  happyLibDir: z.string()
+});
+const TailscaleServeEntrySchema = z.object({
+  port: z.number(),
+  path: z.string().optional(),
+  protocol: z.string(),
+  target: z.string(),
+  funnel: z.boolean(),
+  hostname: z.string()
+});
+const TailscaleInfoSchema = z.object({
+  status: z.enum(["connected", "disconnected", "not-installed"]),
+  ipv4: z.string().optional(),
+  ipv6: z.string().optional(),
+  hostname: z.string().optional(),
+  tailnetName: z.string().optional(),
+  version: z.string().optional(),
+  serves: z.array(TailscaleServeEntrySchema).optional()
+});
+const TunnelEntrySchema = z.object({
+  provider: z.string(),
+  localPort: z.number(),
+  remotePort: z.number().optional(),
+  protocol: z.string(),
+  path: z.string().optional(),
+  target: z.string(),
+  publicUrl: z.string().optional(),
+  accessScope: z.enum(["public", "private", "tailnet"]),
+  hostname: z.string().optional(),
+  metadata: z.record(z.string(), z.string()).optional()
+});
+const TunnelProviderInfoSchema = z.object({
+  provider: z.string(),
+  status: z.enum(["available", "unavailable", "not-installed"]),
+  version: z.string().optional(),
+  entries: z.array(TunnelEntrySchema),
+  metadata: z.record(z.string(), z.string()).optional()
+});
+const TunnelStateSchema = z.object({
+  providers: z.array(TunnelProviderInfoSchema)
+});
+const AutomationPrioritySchema = z.enum(["urgent", "user", "background"]);
+const AutomationJobKindSchema = z.enum(["supervisor", "webhook", "agent_loop", "task"]);
+const AutomationJobStatusSchema = z.enum([
+  "queued",
+  "dispatching",
+  "running",
+  "completed",
+  "failed",
+  "cancelled"
+]);
+const AutomationJobSummarySchema = z.object({
+  id: z.string(),
+  kind: AutomationJobKindSchema,
+  status: AutomationJobStatusSchema,
+  priority: AutomationPrioritySchema,
+  dedupeKey: z.string(),
+  attempt: z.number(),
+  maxAttempts: z.number(),
+  createdAt: z.number(),
+  updatedAt: z.number(),
+  dispatchedAt: z.number().optional(),
+  completedAt: z.number().optional(),
+  nextRunAt: z.number().optional(),
+  sessionId: z.string().optional(),
+  label: z.string().optional(),
+  projectId: z.string().optional(),
+  runId: z.string().optional(),
+  loopId: z.string().optional(),
+  loopIteration: z.number().optional(),
+  continuityKey: z.string().optional(),
+  errorMessage: z.string().optional(),
+  recovered: z.boolean().optional()
+});
+const AutomationGuardianSummarySchema = z.object({
+  key: z.string(),
+  projectId: z.string(),
+  loopId: z.string().optional(),
+  sessionId: z.string(),
+  updatedAt: z.number(),
+  lastRunId: z.string().optional(),
+  attached: z.boolean().optional(),
+  recovered: z.boolean().optional()
+});
+const AutomationGuardianUsageSummarySchema = z.object({
+  key: z.string(),
+  projectId: z.string().optional(),
+  loopId: z.string().optional(),
+  reuseCount: z.number(),
+  rememberCount: z.number(),
+  resetCount: z.number(),
+  lastUsedAt: z.number(),
+  currentSessionId: z.string().optional()
+});
+const AutomationAuditEventSummarySchema = z.object({
+  id: z.string(),
+  occurredAt: z.number(),
+  kind: z.string(),
+  jobId: z.string().optional(),
+  dedupeKey: z.string().optional(),
+  sessionId: z.string().optional(),
+  projectId: z.string().optional(),
+  runId: z.string().optional(),
+  loopId: z.string().optional(),
+  trigger: z.string().optional(),
+  status: z.string().optional(),
+  guardianKey: z.string().optional(),
+  guardianSessionId: z.string().optional(),
+  message: z.string().optional()
+});
+const AutomationAuditStatsSchema = z.object({
+  totalEvents: z.number(),
+  lastEventAt: z.number().optional(),
+  queuedCount: z.number(),
+  sessionStartedCount: z.number(),
+  terminalCompletedCount: z.number(),
+  terminalFailedCount: z.number(),
+  terminalCancelledCount: z.number(),
+  guardianReuseCount: z.number(),
+  guardianRememberCount: z.number(),
+  guardianResetCount: z.number(),
+  sessionReattachedCount: z.number(),
+  watchdogStopCount: z.number(),
+  stopRequestCount: z.number(),
+  guardianEligibleRunCount: z.number(),
+  guardianReuseRate: z.number(),
+  activeGuardianCount: z.number()
+});
+const AutomationCountsSchema = z.object({
+  queued: z.number(),
+  dispatching: z.number(),
+  running: z.number(),
+  completed: z.number(),
+  failed: z.number(),
+  cancelled: z.number()
+});
+const AgentLoopSummarySchema = z.object({
+  id: z.string(),
+  name: z.string().optional(),
+  directory: z.string(),
+  enabled: z.boolean(),
+  intervalMs: z.number(),
+  cronExpression: z.string().optional(),
+  iteration: z.number(),
+  nextRunAt: z.number(),
+  runtimeState: z.string(),
+  phase: z.string(),
+  lastTriggerSource: z.string().optional(),
+  lastBriefSummary: z.string().optional(),
+  lastError: z.string().optional(),
+  agent: z.string()
+});
+const BootstrapProfileSummarySchema = z.object({
+  id: z.string(),
+  name: z.string().optional(),
+  rootDirectory: z.string(),
+  intervalMs: z.number(),
+  enabled: z.boolean(),
+  status: z.string(),
+  statusUpdatedAt: z.number(),
+  lastRunAt: z.number().optional(),
+  lastRepoCount: z.number().optional(),
+  lastSuggestionCount: z.number().optional(),
+  lastError: z.string().optional()
+});
+const AutoDreamProfileSummarySchema = z.object({
+  id: z.string(),
+  name: z.string().optional(),
+  rootDirectory: z.string(),
+  intervalMs: z.number(),
+  enabled: z.boolean(),
+  nextRunAt: z.number(),
+  status: z.string(),
+  stage: z.string(),
+  statusUpdatedAt: z.number(),
+  lastRunAt: z.number().optional(),
+  lastMemoryFiles: z.number().optional(),
+  lastError: z.string().optional()
+});
+const AutomationStateSchema = z.object({
+  updatedAt: z.number(),
+  counts: AutomationCountsSchema,
+  recentJobs: z.array(AutomationJobSummarySchema),
+  guardians: z.array(AutomationGuardianSummarySchema).optional(),
+  guardianUsage: z.array(AutomationGuardianUsageSummarySchema).optional(),
+  auditStats: AutomationAuditStatsSchema.optional(),
+  recentAuditEvents: z.array(AutomationAuditEventSummarySchema).optional(),
+  loops: z.array(AgentLoopSummarySchema).optional(),
+  bootstrapProfiles: z.array(BootstrapProfileSummarySchema).optional(),
+  autoDreamProfiles: z.array(AutoDreamProfileSummarySchema).optional()
+});
+const BriefMessageSchema = z.object({
+  loopId: z.string(),
+  loopName: z.string().optional(),
+  status: z.enum(["completed", "failed", "cancelled"]),
+  summary: z.string(),
+  detail: z.string(),
+  generatedAt: z.number(),
+  sessionId: z.string().optional()
+});
+const CliInstallSourceSchema = z.enum([
+  "npm-global",
+  "local-source",
+  "unknown"
+]);
+const CliInstallInfoSchema = z.object({
+  source: CliInstallSourceSchema,
+  canSelfUpgrade: z.boolean()
+});
+z.object({
+  status: z.union([
+    z.enum(["running", "shutting-down"]),
+    z.string()
+  ]),
+  pid: z.number().optional(),
+  httpPort: z.number().optional(),
+  startTime: z.union([z.number(), z.string()]).optional(),
+  startedAt: z.number().optional(),
+  startedWithCliVersion: z.string().optional(),
+  shutdownRequestedAt: z.number().optional(),
+  shutdownSource: z.union([
+    z.enum(["mobile-app", "cli", "os-signal", "unknown"]),
+    z.string()
+  ]).optional(),
+  tailscale: TailscaleInfoSchema.optional(),
+  tunnels: TunnelStateSchema.optional(),
+  automation: AutomationStateSchema.optional(),
+  recentBriefs: z.array(BriefMessageSchema).optional(),
+  cliInstall: CliInstallInfoSchema.optional(),
+  killed: z.boolean().optional()
+});
+
+const KnowledgeEntryTypeSchema = z.enum([
+  "discovery",
+  // New insight or finding
+  "decision",
+  // Architecture / tech choice
+  "fix",
+  // Bug fix record
+  "convention",
+  // Code convention / process rule
+  "warning"
+  // Known pitfall or gotcha
+]);
+const KnowledgeContributorTypeSchema = z.enum([
+  "session",
+  // Auto-generated by Claude session
+  "supervisor",
+  // Generated by Supervisor analysis
+  "user"
+  // Manually added by user
+]);
+const KnowledgeActionSchema = z.enum([
+  "create",
+  // New entry
+  "amend",
+  // Correction / supplement
+  "supersede",
+  // Replace old knowledge
+  "verify"
+  // Confirm still valid
+]);
+const KnowledgeStatusSchema = z.enum([
+  "active",
+  // Currently valid
+  "superseded",
+  // Replaced by newer knowledge
+  "archived"
+  // Manually archived by user
+]);
+const KnowledgeConfidenceSchema = z.enum(["high", "medium", "low"]);
+z.object({
+  entryType: KnowledgeEntryTypeSchema,
+  contributorType: KnowledgeContributorTypeSchema,
+  action: KnowledgeActionSchema,
+  title: z.string().min(1).max(200),
+  content: z.string().min(1),
+  // Structured SOAP-like fields (optional)
+  request: z.string().optional(),
+  // S: What the user asked
+  findings: z.string().optional(),
+  // O: What was discovered
+  analysis: z.string().optional(),
+  // A: Root cause / assessment
+  outcome: z.string().optional(),
+  // P: What was done
+  nextSteps: z.string().optional(),
+  // Follow-up suggestions
+  tags: z.array(z.string().max(50)).max(20).default([]),
+  confidence: KnowledgeConfidenceSchema.default("medium"),
+  sessionId: z.string().optional(),
+  model: z.string().optional(),
+  supersedesId: z.string().optional(),
+  relatedIds: z.array(z.string()).max(10).default([]),
+  affectedFiles: z.array(z.string()).max(50).default([])
+});
+z.object({
+  status: KnowledgeStatusSchema.optional(),
+  pinned: z.boolean().optional(),
+  title: z.string().min(1).max(200).optional(),
+  content: z.string().min(1).optional(),
+  tags: z.array(z.string().max(50)).max(20).optional(),
+  confidence: KnowledgeConfidenceSchema.optional()
+});
+z.object({
+  entryType: KnowledgeEntryTypeSchema.optional(),
+  status: KnowledgeStatusSchema.optional(),
+  tags: z.array(z.string()).optional(),
+  search: z.string().max(500).optional(),
+  limit: z.number().int().min(1).max(100).default(20),
+  offset: z.number().int().min(0).default(0)
+});
+const ProjectProfileSchema = z.object({
+  techStack: z.array(z.string()),
+  architectureType: z.string().optional(),
+  knownPitfalls: z.array(z.string()),
+  coreConventions: z.array(z.string()),
+  lastUpdatedAt: z.number(),
+  lastUpdatedBy: z.string().optional()
+});
+const KnowledgeInjectionModeSchema = z.enum(["auto", "full", "minimal"]);
+z.object({
+  mode: KnowledgeInjectionModeSchema,
+  contextHints: z.array(z.string()).optional()
+  // Keywords from user message for relevance
+});
+z.object({
+  profile: ProjectProfileSchema.nullable(),
+  entries: z.array(z.object({
+    id: z.string(),
+    entryType: KnowledgeEntryTypeSchema,
+    title: z.string(),
+    content: z.string(),
+    tags: z.array(z.string()),
+    confidence: KnowledgeConfidenceSchema,
+    createdAt: z.string()
+  }))
+});
+const KnowledgeChainRelationSchema = z.object({
+  from: z.string(),
+  to: z.string(),
+  type: z.enum(["supersedes", "related"])
+});
+const KnowledgeChainEntrySchema = z.object({
+  id: z.string(),
+  entryType: KnowledgeEntryTypeSchema,
+  action: KnowledgeActionSchema,
+  status: KnowledgeStatusSchema,
+  title: z.string(),
+  content: z.string(),
+  tags: z.array(z.string()),
+  confidence: KnowledgeConfidenceSchema,
+  supersedesId: z.string().nullable(),
+  createdAt: z.string()
+});
+z.object({
+  chain: z.array(KnowledgeChainEntrySchema),
+  relations: z.array(KnowledgeChainRelationSchema)
+});
+const CrossProjectSearchResultSchema = z.object({
+  id: z.string(),
+  projectId: z.string(),
+  projectPath: z.string(),
+  entryType: KnowledgeEntryTypeSchema,
+  title: z.string(),
+  content: z.string(),
+  tags: z.array(z.string()),
+  confidence: KnowledgeConfidenceSchema,
+  similarity: z.number().optional(),
+  // Present when using semantic search
+  createdAt: z.string()
+});
+z.object({
+  results: z.array(CrossProjectSearchResultSchema),
+  total: z.number()
+});
+z.object({
+  projectId: z.string(),
+  sessionId: z.string(),
+  model: z.string(),
+  turnId: z.string(),
+  turnData: z.object({
+    userMessage: z.string().max(2e3),
+    assistantText: z.string().max(5e3),
+    fileEdits: z.array(z.object({
+      path: z.string(),
+      type: z.enum(["create", "edit"])
+    })).max(50),
+    toolCallCount: z.number().int(),
+    outputTokens: z.number().int()
+  })
+});
+
+const VoiceTokenAllowedSchema = z.object({
+  allowed: z.literal(true),
+  token: z.string(),
+  agentId: z.string(),
+  elevenUserId: z.string(),
+  usedSeconds: z.number(),
+  limitSeconds: z.number()
+});
+const VoiceTokenDeniedSchema = z.object({
+  allowed: z.literal(false),
+  reason: z.enum(["voice_limit_reached", "subscription_required"]),
+  usedSeconds: z.number(),
+  limitSeconds: z.number(),
+  agentId: z.string()
+});
+z.discriminatedUnion("allowed", [
+  VoiceTokenAllowedSchema,
+  VoiceTokenDeniedSchema
+]);
+
+const TaskPrioritySchema = z.enum([
+  "urgent",
+  // User-initiated, needs immediate execution
+  "user",
+  // Normal user-created task (default)
+  "background"
+  // Automated / scheduled tasks
+]);
+const TaskStatusSchema = z.enum([
+  "queued",
+  // Waiting in queue
+  "dispatching",
+  // Being sent to CLI daemon
+  "running",
+  // Executing on CLI
+  "completed",
+  // Finished successfully
+  "failed",
+  // Execution failed
+  "cancelled"
+  // Cancelled by user
+]);
+const TaskTriggerTypeSchema = z.enum([
+  "manual",
+  // Created from App by user
+  "cron",
+  // Created by TriggerSchedule
+  "webhook"
+  // Created by WebhookTrigger
+]);
+z.object({
+  id: z.string(),
+  projectId: z.string().nullable(),
+  machineId: z.string(),
+  priority: TaskPrioritySchema,
+  status: TaskStatusSchema,
+  triggerType: TaskTriggerTypeSchema,
+  triggerRef: z.string().optional(),
+  attempt: z.number(),
+  maxAttempts: z.number(),
+  sessionId: z.string().optional(),
+  errorMessage: z.string().optional(),
+  dispatchedAt: z.number().optional(),
+  completedAt: z.number().optional(),
+  createdAt: z.number(),
+  updatedAt: z.number(),
+  // Encrypted prompt preview (first 100 chars)
+  promptPreview: z.string().optional(),
+  // Names of bound skills for display
+  skillNames: z.array(z.string()).optional()
+});
+z.object({
+  projectId: z.string().optional(),
+  machineId: z.string(),
+  prompt: z.string().min(1),
+  // Encrypted by App
+  priority: TaskPrioritySchema.default("user"),
+  maxAttempts: z.number().int().min(1).max(10).default(3),
+  skillIds: z.array(z.string()).max(10).default([])
+});
+z.object({
+  type: z.literal("task-trigger"),
+  taskId: z.string(),
+  prompt: z.string(),
+  // Encrypted prompt
+  directory: z.string(),
+  // Project directory on machine
+  priority: TaskPrioritySchema,
+  projectId: z.string().optional(),
+  resultToken: z.string().optional(),
+  skillContents: z.array(z.object({
+    name: z.string(),
+    content: z.string()
+  })).optional(),
+  agentType: z.string().nullable().optional(),
+  // "claude" | "codex" | "gemini" — null = inherit CLI default
+  modelOverride: z.string().nullable().optional()
+  // e.g. "claude-sonnet-4-20250514" — null = agent default
+});
+const TaskOutcomeSchema = z.enum([
+  "completed",
+  "failed",
+  "blocked"
+]);
+z.object({
+  taskId: z.string(),
+  status: TaskStatusSchema,
+  outcome: TaskOutcomeSchema.optional(),
+  sessionId: z.string().optional(),
+  errorMessage: z.string().optional()
+});
+z.object({
+  type: z.literal("task-status-changed"),
+  taskId: z.string(),
+  machineId: z.string().optional(),
+  status: TaskStatusSchema,
+  sessionId: z.string().optional(),
+  errorMessage: z.string().optional(),
+  completedAt: z.number().optional()
+});
+
+z.object({
+  id: z.string(),
+  projectId: z.string().nullable(),
+  name: z.string(),
+  description: z.string().optional(),
+  content: z.string(),
+  attachments: z.array(z.string()),
+  sourceKnowledgeId: z.string().optional(),
+  archived: z.boolean(),
+  createdAt: z.number(),
+  updatedAt: z.number()
+});
+z.object({
+  projectId: z.string().optional(),
+  name: z.string().min(1).max(100),
+  description: z.string().max(500).optional(),
+  content: z.string().min(1).max(5e4),
+  attachments: z.array(z.string()).max(10).default([]),
+  sourceKnowledgeId: z.string().optional()
+});
+z.object({
+  name: z.string().min(1).max(100).optional(),
+  description: z.string().max(500).optional(),
+  content: z.string().min(1).max(5e4).optional(),
+  attachments: z.array(z.string()).max(10).optional(),
+  archived: z.boolean().optional()
+});
+z.object({
+  name: z.string(),
+  content: z.string()
+});
+
+const InboxCategorySchema = z.enum([
+  "task",
+  // Task queue events (completed, failed, cancelled)
+  "trigger",
+  // Cron/webhook trigger fired
+  "supervisor",
+  // Supervisor run results
+  "session",
+  // Session lifecycle events
+  "knowledge",
+  // Knowledge base changes
+  "system"
+  // System notifications
+]);
+const InboxSeveritySchema = z.enum([
+  "info",
+  "warning",
+  "error"
+]);
+const InboxItemSummarySchema = z.object({
+  id: z.string(),
+  category: InboxCategorySchema,
+  eventType: z.string(),
+  // e.g. "task.completed", "trigger.cron.fired"
+  severity: InboxSeveritySchema,
+  title: z.string(),
+  body: z.string().optional(),
+  read: z.boolean(),
+  referenceUrl: z.string().optional(),
+  // Deep link, e.g. "/machine/xxx/tasks"
+  refType: z.string().optional(),
+  // Polymorphic ref: "task" | "trigger" | "session" | ...
+  refId: z.string().optional(),
+  // ID of referenced entity
+  groupKey: z.string().optional(),
+  // Dedup key (same source within 1h → skip)
+  createdAt: z.number()
+});
+z.object({
+  type: z.literal("inbox-new-item"),
+  item: InboxItemSummarySchema
+});
+z.object({
+  type: z.literal("inbox-unread-count"),
+  count: z.number()
+});
+
+const SessionEventTypeSchema = z.enum([
+  "file_edit",
+  // File created/modified/deleted
+  "bash_command",
+  // Shell command executed
+  "tool_call",
+  // Tool invocation (Read, Grep, etc.)
+  "git_operation",
+  // Git commit, push, branch, etc.
+  "error",
+  // Error occurred during session
+  "session_start",
+  // Session started
+  "session_end"
+  // Session ended
+]);
+const SessionEventSummarySchema = z.object({
+  id: z.string(),
+  sessionId: z.string(),
+  eventType: SessionEventTypeSchema,
+  summary: z.string(),
+  // Human-readable one-liner
+  detail: z.record(z.string(), z.unknown()).optional(),
+  // Structured metadata (JSON)
+  createdAt: z.number()
+});
+z.object({
+  sessionId: z.string(),
+  eventType: SessionEventTypeSchema,
+  summary: z.string().max(500),
+  detail: z.record(z.string(), z.unknown()).optional()
+});
+z.object({
+  type: z.literal("session-event-created"),
+  event: SessionEventSummarySchema
+});
+
+z.object({
+  /** Shell to use (defaults to user's default shell) */
+  shell: z.string().optional(),
+  /** Working directory */
+  cwd: z.string().optional(),
+  /** Initial terminal dimensions */
+  cols: z.number().int().min(1).max(500).optional(),
+  rows: z.number().int().min(1).max(200).optional()
+});
+z.object({
+  success: z.boolean(),
+  terminalId: z.string().optional(),
+  error: z.string().optional()
+});
+z.object({
+  terminalId: z.string(),
+  cols: z.number().int().min(1).max(500),
+  rows: z.number().int().min(1).max(200)
+});
+z.object({
+  terminalId: z.string()
+});
+z.object({
+  machineId: z.string(),
+  terminalId: z.string(),
+  data: z.string()
+});
+z.object({
+  machineId: z.string(),
+  terminalId: z.string(),
+  data: z.string()
+});
+z.object({
+  machineId: z.string(),
+  terminalId: z.string(),
+  exitCode: z.number()
+});
+
+const CODEX_APP_SERVER_BACKEND = "codex-app-server";
+const CODEX_MCP_LEGACY_BACKEND = "codex-mcp-legacy";
+const CodexBackendModeSchema = z.enum([
+  "auto",
+  CODEX_APP_SERVER_BACKEND,
+  CODEX_MCP_LEGACY_BACKEND
+]);
+const CodexRequestedBackendSchema = CodexBackendModeSchema;
+const CodexResolvedBackendSchema = z.enum([
+  CODEX_APP_SERVER_BACKEND,
+  CODEX_MCP_LEGACY_BACKEND
+]);
+const CodexConfigModeSchema = z.enum([
+  "inherit",
+  "managed-profile",
+  "managed-overrides"
+]);
+const CODEX_REQUESTED_BACKEND_ALIASES = {
+  auto: ["", "auto"],
+  [CODEX_APP_SERVER_BACKEND]: ["app-server", "appserver", CODEX_APP_SERVER_BACKEND],
+  [CODEX_MCP_LEGACY_BACKEND]: [
+    "legacy",
+    "mcp",
+    "mcp-legacy",
+    CODEX_MCP_LEGACY_BACKEND
+  ]
+};
+new Map(
+  Object.entries(CODEX_REQUESTED_BACKEND_ALIASES).flatMap(
+    ([backend, aliases]) => aliases.map((alias) => [alias, backend])
+  )
+);
+
+function isTemplateAwareUrl(value) {
+  if (!value) return true;
+  if (/^\$\{[A-Z_][A-Z0-9_]*(:-[^}]*)?\}$/.test(value)) return true;
+  try {
+    new URL(value);
+    return true;
+  } catch {
+    return false;
+  }
+}
+const BuiltInAIBackendProfileIdSchema = z$1.enum([
+  "anthropic",
+  "deepseek",
+  "zai",
+  "openai",
+  "azure-openai",
+  "minimax",
+  "kimi"
+]);
+new Set(
+  BuiltInAIBackendProfileIdSchema.options
+);
+const EnvironmentVariableSchema = z$1.object({
+  name: z$1.string().regex(/^[A-Z_][A-Z0-9_]*$/, "Invalid environment variable name"),
+  value: z$1.string()
+});
+const ProfileCompatibilitySchema = z$1.object({
+  claude: z$1.boolean().default(true),
+  codex: z$1.boolean().default(true),
+  gemini: z$1.boolean().default(true)
+});
+const AnthropicConfigSchema = z$1.object({
+  baseUrl: z$1.string().refine(isTemplateAwareUrl, {
+    message: "Must be a valid URL or ${VAR} or ${VAR:-default} template string"
+  }).optional(),
+  authToken: z$1.string().optional(),
+  model: z$1.string().optional()
+});
+const OpenAIConfigSchema = z$1.object({
+  apiKey: z$1.string().optional(),
+  baseUrl: z$1.string().refine(isTemplateAwareUrl, {
+    message: "Must be a valid URL or ${VAR} or ${VAR:-default} template string"
+  }).optional(),
+  model: z$1.string().optional()
+});
+const AzureOpenAIConfigSchema = z$1.object({
+  apiKey: z$1.string().optional(),
+  endpoint: z$1.string().refine(isTemplateAwareUrl, {
+    message: "Must be a valid URL or ${VAR} or ${VAR:-default} template string"
+  }).optional(),
+  apiVersion: z$1.string().optional(),
+  deploymentName: z$1.string().optional()
+});
+const TogetherAIConfigSchema = z$1.object({
+  apiKey: z$1.string().optional(),
+  model: z$1.string().optional()
+});
+const CodexConfigSchema = z$1.object({
+  backendMode: CodexBackendModeSchema.optional(),
+  configMode: CodexConfigModeSchema.optional(),
+  codexProfileName: z$1.string().optional(),
+  model: z$1.string().optional(),
+  reasoningEffort: z$1.string().optional(),
+  reasoningSummary: z$1.string().optional(),
+  verbosity: z$1.string().optional(),
+  personality: z$1.string().optional(),
+  serviceTier: z$1.string().optional(),
+  webSearchEnabled: z$1.boolean().optional(),
+  approvalPolicy: z$1.string().optional(),
+  sandboxMode: z$1.string().optional()
+});
+const TmuxConfigSchema = z$1.object({
+  sessionName: z$1.string().optional(),
+  tmpDir: z$1.string().optional(),
+  updateEnvironment: z$1.boolean().optional()
+});
+const CustomModelSchema = z$1.object({
+  id: z$1.string().min(1),
+  name: z$1.string().min(1).max(100),
+  description: z$1.string().nullish()
+});
+const DefaultPermissionModeSchema = z$1.enum([
+  "default",
+  "acceptEdits",
+  "auto",
+  "bypassPermissions",
+  "plan",
+  "read-only",
+  "safe-yolo",
+  "yolo"
+]);
+z$1.object({
+  id: z$1.string().min(1),
+  name: z$1.string().min(1).max(100),
+  description: z$1.string().max(500).optional(),
+  anthropicConfig: AnthropicConfigSchema.optional(),
+  openaiConfig: OpenAIConfigSchema.optional(),
+  azureOpenAIConfig: AzureOpenAIConfigSchema.optional(),
+  togetherAIConfig: TogetherAIConfigSchema.optional(),
+  codexConfig: CodexConfigSchema.optional(),
+  tmuxConfig: TmuxConfigSchema.optional(),
+  startupBashScript: z$1.string().optional(),
+  environmentVariables: z$1.array(EnvironmentVariableSchema).default([]),
+  customModels: z$1.array(CustomModelSchema).optional(),
+  modelMappings: z$1.record(z$1.string(), z$1.string()).optional(),
+  defaultSessionType: z$1.enum(["simple", "worktree"]).optional(),
+  defaultPermissionMode: DefaultPermissionModeSchema.optional(),
+  defaultModelMode: z$1.string().optional(),
+  compatibility: ProfileCompatibilitySchema.default({
+    claude: true,
+    codex: true,
+    gemini: true
+  }),
+  isBuiltIn: z$1.boolean().default(false),
+  createdAt: z$1.number().default(() => Date.now()),
+  updatedAt: z$1.number().default(() => Date.now()),
+  version: z$1.string().default("1.0.0")
+});
+const RuntimeProfileSourceSchema = z$1.enum([
+  "built-in-profile",
+  "account-profile",
+  "local-profile",
+  "ad-hoc"
+]);
+const RuntimeProfileTrustSchema = z$1.enum(["trusted", "untrusted"]);
+const RESOLVED_RUNTIME_PROFILE_SCHEMA_VERSION = 1;
+z$1.object({
+  schemaVersion: z$1.literal(RESOLVED_RUNTIME_PROFILE_SCHEMA_VERSION).default(RESOLVED_RUNTIME_PROFILE_SCHEMA_VERSION),
+  profileId: z$1.string().optional(),
+  profileName: z$1.string().optional(),
+  source: RuntimeProfileSourceSchema,
+  trust: RuntimeProfileTrustSchema,
+  isBuiltIn: z$1.boolean().optional(),
+  compatibility: ProfileCompatibilitySchema.optional(),
+  environmentVariables: z$1.record(z$1.string(), z$1.string()).default({}),
+  startupBashScript: z$1.string().optional(),
+  customModels: z$1.array(CustomModelSchema).optional(),
+  modelMappings: z$1.record(z$1.string(), z$1.string()).optional(),
+  defaultSessionType: z$1.enum(["simple", "worktree"]).optional(),
+  defaultPermissionMode: DefaultPermissionModeSchema.optional(),
+  defaultModelMode: z$1.string().optional()
+});
+
+const sessionProgressTodoStatusSchema = z.enum([
+  "pending",
+  "in_progress",
+  "completed"
+]);
+const sessionProgressTodoSchema = z.object({
+  content: z.string(),
+  status: sessionProgressTodoStatusSchema,
+  /** SDK-native: imperative-present form shown when status is in_progress. */
+  activeForm: z.string().optional(),
+  /** Optional phase/stage label a step belongs to, e.g. "Phase 2". */
+  stage: z.string().optional(),
+  /**
+   * Carried over from SDK's `TodoWriteOutput.verificationNudgeNeeded` — SDK
+   * flags items it suspects were marked completed without verification.
+   */
+  verificationNudgeNeeded: z.boolean().optional()
+});
+const sessionProgressListSchema = z.object({
+  /** Stable UUID for tab switching / explicit Agent addressing. */
+  id: z.string(),
+  /** Short human-readable label; auto-derived from first todo if absent. */
+  label: z.string().optional(),
+  todos: z.array(sessionProgressTodoSchema),
+  /** Optional overall stage for this list (set via MCP). */
+  currentStage: z.string().optional(),
+  /** Optional blocker list (set via MCP). */
+  blockers: z.array(z.string()).optional(),
+  startedAt: z.number(),
+  updatedAt: z.number(),
+  /** When this list stopped being active (got pushed to history). */
+  archivedAt: z.number().optional(),
+  /**
+   * Tool-call message IDs for file-editing tools (Edit/Write/MultiEdit/
+   * NotebookEdit) that ran while this list was the active one. Consumers
+   * resolve these against the session message stream to render per-list
+   * file change summaries without duplicating diff content into metadata.
+   */
+  toolCallIds: z.array(z.string()).optional(),
+  /**
+   * Timestamp at which an auto-summary was triggered for this list's
+   * completion (all todos completed → all completed transition). Dedup flag
+   * so the CLI hook only fires ONE synthetic summary-trigger message per
+   * list lifecycle, even if subsequent TodoWrite calls keep it all done.
+   */
+  summaryGeneratedAt: z.number().optional()
+});
+z.object({
+  /** Ordered by startedAt asc; last item is typically the active one. */
+  lists: z.array(sessionProgressListSchema).optional(),
+  /** Points at the active list within `lists`. */
+  currentListId: z.string().optional(),
+  /**
+   * Legacy flat fields. Still written for backward compat with older
+   * readers — kept in sync with `lists[currentListId]` on each update.
+   */
+  todos: z.array(sessionProgressTodoSchema).optional(),
+  currentStage: z.string().optional(),
+  blockers: z.array(z.string()).optional(),
+  updatedAt: z.number()
+});
+const sessionSummaryStateSchema = z.object({
+  goal: z.string(),
+  currentFocus: z.string().optional(),
+  keyDecisions: z.array(z.string()).optional(),
+  openQuestions: z.array(z.string()).optional(),
+  impactScope: z.array(z.string()).optional(),
+  updatedAt: z.number()
+});
+const sessionSummaryRefreshActiveRequestSchema = z.object({
+  requestId: z.string().min(1),
+  requestedAt: z.number(),
+  requester: z.enum(["happy-agent", "app", "system"]),
+  command: z.literal("summary-refresh"),
+  requireSummary: z.boolean()
+});
+const sessionSummaryRefreshRecentEntrySchema = z.object({
+  requestId: z.string().min(1),
+  status: z.enum(["applied", "superseded"]),
+  resolvedAt: z.number(),
+  summaryUpdatedAt: z.number().optional(),
+  supersededByRequestId: z.string().min(1).optional()
+});
+const sessionSummaryRefreshStateSchema = z.object({
+  protocolVersion: z.literal(1),
+  active: sessionSummaryRefreshActiveRequestSchema.optional(),
+  recent: z.array(sessionSummaryRefreshRecentEntrySchema).optional()
+});
+
+const HAPPY_MCP_TOOL_NAMES = [
+  "change_title",
+  "query_project_knowledge",
+  "update_progress",
+  "update_session_summary"
+];
+const HAPPY_MCP_TOOL_SPECS = {
+  change_title: {
+    title: "Change Title",
+    description: 'Set or update the chat session title. Titles should be short (under 50 chars) and action-oriented, e.g. "Fix auth token refresh".',
+    failureLabel: "Failed to change chat title",
+    inputSchema: {
+      title: z$1.string().describe("The new title for the chat session")
+    },
+    hideSuccessfulCall: true,
+    autoApproveByDefault: true,
+    permissionAction: "Waiting for approval to update chat title",
+    dynamicAction: "Updating chat title",
+    fallbackAction: "Update chat title",
+    reasonPhrases: ["title update", "title updates", "change_title"]
+  },
+  query_project_knowledge: {
+    title: "Project Knowledge",
+    description: "Search the project knowledge base for relevant context, past decisions, known pitfalls, and conventions.",
+    failureLabel: "Knowledge query failed",
+    inputSchema: {
+      query: z$1.string().describe("Search query describing what you want to know")
+    },
+    hideSuccessfulCall: false,
+    autoApproveByDefault: false,
+    permissionAction: "Waiting for approval to search project knowledge",
+    dynamicAction: "Searching project knowledge",
+    fallbackAction: "Search project knowledge",
+    reasonPhrases: []
+  },
+  update_progress: {
+    title: "Update Progress",
+    description: 'Optional override for the App\'s Progress tab. In most cases your TodoWrite calls are auto-mirrored, so you do NOT need to call this. Use it only when you want to set extra fields the CLI hook does not capture (currentStage, blockers) or to force a new list boundary with `listId: "new"`.',
+    failureLabel: "Failed to update progress",
+    inputSchema: {
+      todos: z$1.array(
+        z$1.object({
+          content: z$1.string().describe("Concise description of the task"),
+          status: z$1.enum(["pending", "in_progress", "completed"]).describe("Current status of the task"),
+          activeForm: z$1.string().optional().describe(
+            "Imperative-present form shown when status is in_progress"
+          ),
+          stage: z$1.string().optional().describe("Optional phase/stage label")
+        })
+      ).describe("The full checklist \u2014 always send every item, not a delta"),
+      currentStage: z$1.string().optional().describe("Optional overall stage name for the checklist"),
+      blockers: z$1.array(z$1.string()).optional().describe("Optional list of things blocking progress"),
+      listId: z$1.string().optional().describe("Target list id. Use 'new' to force a fresh list"),
+      label: z$1.string().optional().describe("Short human-readable name for this task list")
+    },
+    hideSuccessfulCall: false,
+    autoApproveByDefault: true,
+    permissionAction: "Waiting for approval to update progress",
+    dynamicAction: "Updating progress",
+    fallbackAction: "Update progress",
+    reasonPhrases: ["progress update", "progress updates", "update_progress"]
+  },
+  update_session_summary: {
+    title: "Update Session Summary",
+    description: "Write a narrative session summary the App shows above the progress checklist. Call at milestones, not per task: after first understanding the goal, when scope shifts significantly, when key decisions are made, or when moving to a new phase. Full rewrite each call.",
+    failureLabel: "Failed to update session summary",
+    inputSchema: {
+      goal: z$1.string().describe("What the user ultimately wants to accomplish"),
+      currentFocus: z$1.string().optional().describe("Brief description of the active task or phase"),
+      keyDecisions: z$1.array(z$1.string()).optional().describe("Important choices already made this session"),
+      openQuestions: z$1.array(z$1.string()).optional().describe("Unresolved questions or pending decisions"),
+      impactScope: z$1.array(z$1.string()).optional().describe("Modules/files/areas affected by this session's work"),
+      requestId: z$1.string().optional().describe(
+        "Optional request identifier that runtimes may record in sessionSummaryRefresh recent history for request-level confirmation"
+      )
+    },
+    hideSuccessfulCall: false,
+    autoApproveByDefault: true,
+    permissionAction: "Waiting for approval to update session summary",
+    dynamicAction: "Updating session summary",
+    fallbackAction: "Update session summary",
+    reasonPhrases: [
+      "session summary",
+      "update_session_summary",
+      "summary update"
+    ]
+  }
+};
+new Set(HAPPY_MCP_TOOL_NAMES);
+HAPPY_MCP_TOOL_NAMES.filter(
+  (toolName) => HAPPY_MCP_TOOL_SPECS[toolName].autoApproveByDefault
+);
+HAPPY_MCP_TOOL_NAMES.filter(
+  (toolName) => HAPPY_MCP_TOOL_SPECS[toolName].hideSuccessfulCall
+);
+
+const CodexRuntimeConfigSchema = z.object({
+  model: z.string().nullish(),
+  profile: z.string().nullish(),
+  approvalPolicy: z.string().nullish(),
+  sandboxMode: z.string().nullish(),
+  serviceTier: z.string().nullish(),
+  reasoningEffort: z.string().nullish(),
+  reasoningSummary: z.string().nullish(),
+  verbosity: z.string().nullish(),
+  webSearch: z.string().nullish()
+});
+const CodexAccountSchema = z.object({
+  type: z.enum(["apiKey", "chatgpt"]).nullable().optional(),
+  email: z.string().nullish(),
+  planType: z.string().nullish(),
+  requiresOpenaiAuth: z.boolean().optional()
+});
+const CodexRateLimitsSchema = z.object({
+  limitId: z.string().nullish(),
+  limitName: z.string().nullish(),
+  planType: z.string().nullish(),
+  hasCredits: z.boolean().optional()
+});
+const CodexExperimentalFeatureSchema = z.object({
+  name: z.string(),
+  stage: z.string(),
+  enabled: z.boolean(),
+  defaultEnabled: z.boolean()
+});
+const CodexSkillSummarySchema = z.object({
+  name: z.string(),
+  description: z.string(),
+  path: z.string(),
+  enabled: z.boolean()
+});
+const CodexPromptSummarySchema = z.object({
+  name: z.string(),
+  path: z.string(),
+  description: z.string().nullish()
+});
+const CodexAgentSummarySchema = z.object({
+  name: z.string(),
+  path: z.string()
+});
+const CodexMcpServerSummarySchema = z.object({
+  name: z.string(),
+  authStatus: z.string(),
+  toolCount: z.number()
+});
+z.object({
+  requestedBackend: CodexRequestedBackendSchema.optional(),
+  resolvedBackend: CodexResolvedBackendSchema.optional(),
+  configMode: CodexConfigModeSchema.optional(),
+  fallbackReason: z.string().optional(),
+  backendVersion: z.string().optional(),
+  threadId: z.string().optional(),
+  config: CodexRuntimeConfigSchema.optional(),
+  account: CodexAccountSchema.optional(),
+  rateLimits: CodexRateLimitsSchema.optional(),
+  experimentalFeatures: z.array(CodexExperimentalFeatureSchema).optional(),
+  skills: z.array(CodexSkillSummarySchema).optional(),
+  prompts: z.array(CodexPromptSummarySchema).optional(),
+  agents: z.array(CodexAgentSummarySchema).optional(),
+  mcpServers: z.array(CodexMcpServerSummarySchema).optional()
+});
+
+function buildSummaryRefreshPrompt(requestId) {
+  return [
+    "Please call mcp__happy__update_session_summary to record the current session summary with: goal, currentFocus, keyDecisions (if any), openQuestions (if any), impactScope (if any). Keep it accurate and concise.",
+    "",
+    `Request ID: ${requestId}`,
+    "Important: include this requestId exactly in the tool input as `requestId` when you call mcp__happy__update_session_summary."
+  ].join("\n");
+}
+function toMetadataRecord(metadata) {
+  if (metadata == null || typeof metadata !== "object" || Array.isArray(metadata)) {
+    return {};
+  }
+  return metadata;
+}
+function appendRecentEntry(existing, entry) {
+  return [
+    ...(existing ?? []).filter((item) => item.requestId !== entry.requestId),
+    entry
+  ].slice(-4);
+}
+function extractSessionSummaryState(metadata) {
+  const parsed = sessionSummaryStateSchema.safeParse(
+    toMetadataRecord(metadata).sessionSummary
+  );
+  return parsed.success ? parsed.data : null;
+}
+function extractSessionSummaryRefreshState(metadata) {
+  const parsed = sessionSummaryRefreshStateSchema.safeParse(
+    toMetadataRecord(metadata).sessionSummaryRefresh
+  );
+  return parsed.success ? parsed.data : null;
+}
+function buildActiveSummaryRefreshState(args) {
+  const existing = extractSessionSummaryRefreshState(args.metadata);
+  const previousActive = existing?.active;
+  const recent = previousActive && previousActive.requestId !== args.requestId ? appendRecentEntry(existing?.recent, {
+    requestId: previousActive.requestId,
+    status: "superseded",
+    resolvedAt: args.requestedAt,
+    supersededByRequestId: args.requestId
+  }) : [...existing?.recent ?? []];
+  return {
+    protocolVersion: 1,
+    active: {
+      requestId: args.requestId,
+      requestedAt: args.requestedAt,
+      requester: "happy-agent",
+      command: "summary-refresh",
+      requireSummary: args.requireSummary
+    },
+    recent
+  };
+}
+function getRecentSummaryRefreshEntry(metadata, requestId) {
+  const refresh = extractSessionSummaryRefreshState(metadata);
+  const recent = refresh?.recent;
+  if (!recent) {
+    return null;
+  }
+  for (let index = recent.length - 1; index >= 0; index -= 1) {
+    if (recent[index]?.requestId === requestId) {
+      return recent[index] ?? null;
+    }
+  }
+  return null;
+}
+function waitForSummaryRefreshRecentApplied(client, opts) {
+  const getEntry = (metadata) => getRecentSummaryRefreshEntry(metadata, opts.requestId);
+  const immediate = getEntry(client.getMetadata());
+  if (immediate?.status === "applied") {
+    return Promise.resolve(immediate);
+  }
+  if (immediate?.status === "superseded") {
+    return Promise.reject(
+      new Error(
+        `Summary refresh request ${opts.requestId} was superseded${immediate.supersededByRequestId ? ` by ${immediate.supersededByRequestId}` : ""}`
+      )
+    );
+  }
+  return new Promise((resolve, reject) => {
+    const onStateChange = (data) => {
+      const entry = getEntry(data.metadata ?? client.getMetadata());
+      if (!entry) {
+        return;
+      }
+      if (entry.status === "applied") {
+        cleanup();
+        resolve(entry);
+        return;
+      }
+      cleanup();
+      reject(
+        new Error(
+          `Summary refresh request ${opts.requestId} was superseded${entry.supersededByRequestId ? ` by ${entry.supersededByRequestId}` : ""}`
+        )
+      );
+    };
+    const onDisconnect = () => {
+      cleanup();
+      reject(
+        new Error(
+          "Socket disconnected while waiting for summary refresh acknowledgement"
+        )
+      );
+    };
+    const cleanup = () => {
+      clearTimeout(timeout);
+      client.removeListener("state-change", onStateChange);
+      client.removeListener("disconnected", onDisconnect);
+    };
+    const timeout = setTimeout(() => {
+      cleanup();
+      reject(new Error("Timeout waiting for summary refresh acknowledgement"));
+    }, opts.timeoutMs);
+    client.on("state-change", onStateChange);
+    client.on("disconnected", onDisconnect);
+  });
+}
+
 function formatTime(ts) {
   if (!ts) return "-";
   const date = new Date(ts);
+  if (Number.isNaN(date.getTime())) return "-";
   const now = /* @__PURE__ */ new Date();
   const diffMs = now.getTime() - date.getTime();
   const diffMin = Math.floor(diffMs / 6e4);
@@ -3467,7 +5706,7 @@ function normalizeListValue(value) {
 function toNonEmptyString(value) {
   return typeof value === "string" && value.trim().length > 0 ? value : void 0;
 }
-function extractSessionSummary(meta) {
+function extractSessionName(meta) {
   const direct = toNonEmptyString(meta.summary);
   if (direct) return direct;
   if (meta.summary != null && typeof meta.summary === "object") {
@@ -3475,13 +5714,21 @@ function extractSessionSummary(meta) {
   }
   return void 0;
 }
+function formatMarkdownListSection(title, items) {
+  if (items.length === 0) return [];
+  return [
+    "",
+    `### ${title}`,
+    ...items.map((item) => `- ${normalizeListValue(item)}`)
+  ];
+}
 function formatSessionTable(sessions) {
   if (sessions.length === 0) {
     return "## Sessions\n\n- Total: 0\n- Items: none";
   }
   const sections = sessions.map((s, index) => {
     const meta = s.metadata ?? {};
-    const name = normalizeListValue(extractSessionSummary(meta) ?? toNonEmptyString(meta.tag) ?? "-");
+    const name = normalizeListValue(extractSessionName(meta) ?? toNonEmptyString(meta.tag) ?? "-");
     const path = normalizeListValue(toNonEmptyString(meta.path) ?? "-");
     const status = s.active ? "active" : "inactive";
     const lastActive = normalizeListValue(formatLastActive(s.activeAt));
@@ -3504,7 +5751,7 @@ function formatSessionStatus(session) {
   const meta = session.metadata ?? {};
   const state = session.agentState ?? null;
   const tag = toNonEmptyString(meta.tag);
-  const summary = extractSessionSummary(meta);
+  const summary = extractSessionName(meta);
   const path = toNonEmptyString(meta.path);
   const host = toNonEmptyString(meta.host);
   const lifecycleState = toNonEmptyString(meta.lifecycleState);
@@ -3533,6 +5780,30 @@ function formatSessionStatus(session) {
   }
   return lines.join("\n");
 }
+function formatSessionNarrativeSummary(session) {
+  const summary = extractSessionSummaryState(session.metadata);
+  const lines = [
+    "## Session Summary",
+    "",
+    `- Session ID: ${toMarkdownInline(session.id)}`
+  ];
+  if (!summary) {
+    lines.push("- Status: missing");
+    lines.push(
+      `- Hint: Run ${toMarkdownInline(`happy-agent summary refresh ${session.id}`)} to request one.`
+    );
+    return lines.join("\n");
+  }
+  lines.push(`- Updated: ${formatLastActive(summary.updatedAt)}`);
+  lines.push(`- Goal: ${normalizeListValue(summary.goal)}`);
+  if (summary.currentFocus) {
+    lines.push(`- Focus: ${normalizeListValue(summary.currentFocus)}`);
+  }
+  lines.push(...formatMarkdownListSection("Key Decisions", summary.keyDecisions ?? []));
+  lines.push(...formatMarkdownListSection("Open Questions", summary.openQuestions ?? []));
+  lines.push(...formatMarkdownListSection("Impact Scope", summary.impactScope ?? []));
+  return lines.join("\n");
+}
 function formatMessageHistory(messages) {
   if (messages.length === 0) {
     return "## Message History\n\n- Count: 0\n- Items: none";
@@ -3599,9 +5870,48 @@ function createClient(session, creds, config) {
     encryptionVariant: session.encryption.variant,
     token: creds.token,
     serverUrl: config.serverUrl,
+    initialMetadata: session.metadata ?? null,
+    initialMetadataVersion: session.metadataVersion,
     initialAgentState: session.agentState ?? null
   });
 }
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function hydrateSessionLiveState(session, creds, config) {
+  const client = createClient(session, creds, config);
+  let liveData = false;
+  try {
+    await new Promise((resolve) => {
+      let resolved = false;
+      const done = () => {
+        if (resolved) return;
+        resolved = true;
+        clearTimeout(timeout);
+        client.removeAllListeners("state-change");
+        client.removeAllListeners("connect_error");
+        resolve();
+      };
+      const timeout = setTimeout(done, 3e3);
+      client.once(
+        "state-change",
+        (data) => {
+          session.metadata = data.metadata ?? session.metadata;
+          session.metadataVersion = client.getMetadataVersion();
+          session.agentState = data.agentState ?? session.agentState;
+          liveData = true;
+          done();
+        }
+      );
+      client.once("connect_error", () => {
+        done();
+      });
+    });
+  } finally {
+    client.close();
+  }
+  return liveData;
+}
 const program = new Command();
 program.name("happy-agent").description("CLI client for controlling Happy Coder agents remotely").version(version);
 program.command("auth").description("Manage authentication").addCommand(
@@ -3634,36 +5944,7 @@ program.command("status").description("Get live session state").argument("<sessi
   const config = loadConfig();
   const creds = requireCredentials(config);
   const session = await resolveSession(config, creds, sessionId);
-  const client = createClient(session, creds, config);
-  let liveData = false;
-  try {
-    await new Promise((resolve) => {
-      let resolved = false;
-      const done = () => {
-        if (resolved) return;
-        resolved = true;
-        clearTimeout(timeout);
-        client.removeAllListeners("state-change");
-        client.removeAllListeners("connect_error");
-        resolve();
-      };
-      const timeout = setTimeout(done, 3e3);
-      client.once(
-        "state-change",
-        (data) => {
-          session.metadata = data.metadata ?? session.metadata;
-          session.agentState = data.agentState ?? session.agentState;
-          liveData = true;
-          done();
-        }
-      );
-      client.once("connect_error", () => {
-        done();
-      });
-    });
-  } finally {
-    client.close();
-  }
+  const liveData = await hydrateSessionLiveState(session, creds, config);
   if (opts.json) {
     console.log(formatJson(session));
   } else {
@@ -3673,6 +5954,131 @@ program.command("status").description("Get live session state").argument("<sessi
     console.log(formatSessionStatus(session));
   }
 });
+program.command("summary").description("Inspect or refresh session summaries").addCommand(
+  new Command("show").description("Show the narrative session summary").argument("<session-id>", "Session ID or prefix").option("--json", "Output as JSON").action(async (sessionId, opts) => {
+    const config = loadConfig();
+    const creds = requireCredentials(config);
+    const session = await resolveSession(config, creds, sessionId);
+    const liveData = await hydrateSessionLiveState(session, creds, config);
+    const summary = extractSessionSummaryState(session.metadata);
+    if (opts.json) {
+      console.log(
+        formatJson({
+          sessionId: session.id,
+          live: liveData,
+          summary
+        })
+      );
+    } else {
+      if (!liveData) {
+        console.log("> Note: showing cached summary (could not get live state).");
+      }
+      console.log(formatSessionNarrativeSummary(session));
+    }
+  })
+).addCommand(
+  new Command("refresh").description("Ask the agent to rewrite the session summary").argument("<session-id>", "Session ID or prefix").option("--wait", "Wait for agent to become idle").option(
+    "--require-summary",
+    "Wait until this refresh request is acknowledged in sessionSummaryRefresh.recent"
+  ).option(
+    "--timeout <seconds>",
+    "Timeout in seconds when using --wait or --require-summary",
+    (v) => {
+      const n = parseInt(v, 10);
+      if (isNaN(n) || n <= 0)
+        throw new Error("--timeout must be a positive integer");
+      return n;
+    },
+    300
+  ).option("--json", "Output as JSON").action(
+    async (sessionId, opts) => {
+      const config = loadConfig();
+      const creds = requireCredentials(config);
+      const session = await resolveSession(config, creds, sessionId);
+      const timeoutMs = opts.timeout * 1e3;
+      const requestId = `summary-refresh_${randomUUID$1()}`;
+      const requestedAt = Date.now();
+      let summaryConfirmed = false;
+      const client = createClient(session, creds, config);
+      try {
+        await client.waitForConnect();
+        if (opts.requireSummary) {
+          await client.updateMetadataWith((current) => {
+            const base = current != null && typeof current === "object" && !Array.isArray(current) ? current : {};
+            return {
+              ...base,
+              sessionSummaryRefresh: buildActiveSummaryRefreshState({
+                metadata: current,
+                requestId,
+                requestedAt,
+                requireSummary: true
+              })
+            };
+          });
+        }
+        const summaryAckPromise = opts.requireSummary ? waitForSummaryRefreshRecentApplied(client, {
+          requestId,
+          timeoutMs
+        }) : null;
+        client.sendMessage(buildSummaryRefreshPrompt(requestId), {
+          sentFrom: "happy-agent-summary-refresh",
+          requestId
+        });
+        if (summaryAckPromise) {
+          await summaryAckPromise;
+          summaryConfirmed = true;
+        }
+        if (opts.wait) {
+          await sleep(500);
+          await client.waitForIdle(timeoutMs);
+        } else if (!opts.requireSummary) {
+          await sleep(500);
+        }
+        const latestMetadata = client.getMetadata();
+        if (latestMetadata !== null) {
+          session.metadata = latestMetadata;
+        }
+        session.metadataVersion = client.getMetadataVersion();
+      } finally {
+        client.close();
+      }
+      const summary = extractSessionSummaryState(session.metadata);
+      if (opts.json) {
+        console.log(
+          formatJson({
+            sessionId: session.id,
+            requestId,
+            requested: true,
+            requiredSummary: opts.requireSummary === true,
+            summaryConfirmed,
+            waited: opts.wait === true,
+            summary: opts.wait === true || opts.requireSummary === true ? summary : void 0
+          })
+        );
+      } else if (opts.wait || opts.requireSummary) {
+        if (!summary) {
+          console.log(
+            opts.requireSummary ? "> Note: summary update was required, but no valid narrative summary is available." : "> Note: summary was requested, but the session has not recorded a narrative summary yet."
+          );
+        }
+        console.log(formatSessionNarrativeSummary(session));
+      } else {
+        console.log(
+          [
+            "## Summary Refresh Requested",
+            "",
+            `- Session ID: \`${session.id}\``,
+            `- Request ID: \`${requestId}\``,
+            `- Required Summary Update: ${opts.requireSummary ? "yes" : "no"}`,
+            `- Summary Confirmed: ${summaryConfirmed ? "yes" : "no"}`,
+            `- Waited For Idle: ${opts.wait ? "yes" : "no"}`,
+            `- Hint: Run \`happy-agent summary show ${session.id}\` to inspect the updated summary.`
+          ].join("\n")
+        );
+      }
+    }
+  )
+);
 program.command("create").description("Create a new session").requiredOption("--tag <tag>", "Session tag").option("--path <path>", "Working directory path").option("--json", "Output as JSON").action(async (opts) => {
   const config = loadConfig();
   const creds = requireCredentials(config);