@agentproto/cli 0.1.0-alpha.6 → 0.1.0-alpha.8

package/dist/index.mjs

@@ -1,10 +1,11 @@
+import * as childProc from 'child_process';
 import { execFile, spawn } from 'child_process';
 import { createHash, randomUUID, randomBytes } from 'crypto';
-import { mkdtemp, writeFile, chmod, rm, mkdir, readFile, readdir, stat } from 'fs/promises';
+import { mkdtemp, writeFile, chmod, rm, mkdir, unlink, readFile, readdir, stat } from 'fs/promises';
 import { tmpdir, userInfo, hostname, homedir, platform } from 'os';
 import { resolve, join, dirname, isAbsolute, normalize, relative, basename } from 'path';
 import { promisify, parseArgs } from 'util';
-import { promises, existsSync } from 'fs';
+import { promises, existsSync, mkdirSync, writeFileSync, readFileSync } from 'fs';
 import { createInterface } from 'readline/promises';
 import { stdout, stdin } from 'process';
 import { createAgentCliRuntime } from '@agentproto/driver-agent-cli';
@@ -16,11 +17,11 @@ import matter from 'gray-matter';
 import { EventEmitter } from 'events';
 import { createServer } from 'http';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import WebSocket, { WebSocketServer } from 'ws';
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
 import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
 import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
-import WebSocket from 'ws';
 
 /**
  * @agentproto/cli v0.1.0-alpha
@@ -84,9 +85,12 @@ async function listInstalledAdapters(opts) {
         };
         out.push(info);
       } catch (err) {
-        console.warn(
-          `[agentproto/cli] listInstalledAdapters: skipping broken adapter '${slug}': ${err instanceof Error ? err.message : String(err)}`
-        );
+        const msg = err instanceof Error ? err.message : String(err);
+        if (/Cannot find package|ERR_MODULE_NOT_FOUND/i.test(msg) && msg.includes(`@agentproto/adapter-${slug}`)) ; else {
+          console.warn(
+            `[agentproto/cli] listInstalledAdapters: skipping broken adapter '${slug}': ${msg}`
+          );
+        }
       }
     }
   }
@@ -259,10 +263,10 @@ async function runExternalStep(step, ledger, head) {
 `);
   const opener = platform() === "darwin" ? "open" : platform() === "win32" ? "cmd" : "xdg-open";
   const args = platform() === "win32" ? ["/c", "start", step.url] : [step.url];
-  await new Promise((resolve3) => {
+  await new Promise((resolve4) => {
     const child = spawn(opener, args, { stdio: "ignore", detached: true });
-    child.once("error", () => resolve3());
-    child.once("spawn", () => resolve3());
+    child.once("error", () => resolve4());
+    child.once("spawn", () => resolve4());
   });
   let value = "";
   if (step.callback?.param) {
@@ -335,7 +339,7 @@ async function promptString(question, opts) {
     process.stdin.setRawMode?.(true);
     let buf = "";
     process.stdout.write(prompt);
-    return new Promise((resolve3) => {
+    return new Promise((resolve4) => {
       const onData = (chunk) => {
         for (const code of chunk) {
           if (code === 13 || code === 10) {
@@ -343,7 +347,7 @@ async function promptString(question, opts) {
             process.stdin.setRawMode?.(false);
             process.stdout.write("\n");
             rl.close();
-            resolve3(buf || opts.defaultValue || "");
+            resolve4(buf || opts.defaultValue || "");
             return;
           }
           if (code === 3) {
@@ -425,7 +429,7 @@ async function resolveSelectOptions(options) {
   });
 }
 async function runShellCapturing(cmd, opts) {
-  return new Promise((resolve3) => {
+  return new Promise((resolve4) => {
     const child = spawn("bash", ["-lc", cmd], {
       stdio: opts.interactive ? "inherit" : ["ignore", "pipe", "pipe"]
     });
@@ -443,11 +447,11 @@ async function runShellCapturing(cmd, opts) {
     }, opts.timeoutMs);
     child.once("error", () => {
       clearTimeout(timer);
-      resolve3({ exitCode: 127, stdout, stderr: stderr || "spawn error" });
+      resolve4({ exitCode: 127, stdout, stderr: stderr || "spawn error" });
     });
     child.once("exit", (code) => {
       clearTimeout(timer);
-      resolve3({ exitCode: code ?? 0, stdout, stderr });
+      resolve4({ exitCode: code ?? 0, stdout, stderr });
     });
   });
 }
@@ -806,15 +810,15 @@ function homedir2() {
   return process.env["HOME"] ?? process.env["USERPROFILE"] ?? "/";
 }
 function spawnInherit(cmd, argv) {
-  return new Promise((resolve3, reject) => {
+  return new Promise((resolve4, reject) => {
     const child = spawn(cmd, argv, { stdio: "inherit" });
     child.once("error", reject);
-    child.once("exit", (code) => resolve3(code ?? 0));
+    child.once("exit", (code) => resolve4(code ?? 0));
   });
 }
 async function runVersionCheck(check) {
   if (!check) return { ok: false, message: "no version_check declared" };
-  return new Promise((resolve3) => {
+  return new Promise((resolve4) => {
     const child = spawn("bash", ["-lc", check.cmd], {
       stdio: ["ignore", "pipe", "ignore"]
     });
@@ -822,19 +826,19 @@ async function runVersionCheck(check) {
     child.stdout.on("data", (c) => {
       buf += c.toString("utf8");
     });
-    child.once("error", () => resolve3({ ok: false, message: "check failed" }));
+    child.once("error", () => resolve4({ ok: false, message: "check failed" }));
     child.once("exit", (code) => {
       if (code !== 0) {
-        resolve3({ ok: false, message: `check exited ${code}` });
+        resolve4({ ok: false, message: `check exited ${code}` });
         return;
       }
       const re = new RegExp(check.parse);
       const m = buf.match(re);
       if (!m || !m[1]) {
-        resolve3({ ok: false, message: "could not parse version" });
+        resolve4({ ok: false, message: "could not parse version" });
         return;
       }
-      resolve3({ ok: true, message: `version ${m[1]}` });
+      resolve4({ ok: true, message: `version ${m[1]}` });
     });
   });
 }
@@ -1019,6 +1023,134 @@ function formatRelative(ms) {
   return `${Math.round(ms / 864e5)}d`;
 }
 
+// src/util/pty-factory.ts
+async function loadNodePtyFactory() {
+  try {
+    const nodePtyMod = await import('node-pty');
+    const nodePty = nodePtyMod.default ?? nodePtyMod;
+    if (typeof nodePty.spawn !== "function") return null;
+    return (opts) => {
+      const pty = nodePty.spawn(opts.command, opts.args, {
+        name: "xterm-256color",
+        cols: opts.cols,
+        rows: opts.rows,
+        cwd: opts.cwd,
+        env: {
+          ...process.env,
+          ...opts.env ?? {}
+        }
+      });
+      const proc = {
+        get pid() {
+          return pty.pid;
+        },
+        write(data) {
+          pty.write(data);
+        },
+        resize(cols, rows) {
+          pty.resize(cols, rows);
+        },
+        kill(signal) {
+          pty.kill(signal);
+        },
+        onData(handler) {
+          pty.onData(handler);
+        },
+        onExit(handler) {
+          pty.onExit(handler);
+        }
+      };
+      return proc;
+    };
+  } catch {
+    return null;
+  }
+}
+var CONFIG_FILE_PATH = () => join(homedir(), ".agentproto", "config.json");
+async function loadConfig(path) {
+  const target = CONFIG_FILE_PATH();
+  try {
+    const raw = await promises.readFile(target, "utf8");
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      return parsed;
+    }
+    console.warn(
+      `[runtime/config] ${target}: top-level value is not an object \u2014 ignoring`
+    );
+    return {};
+  } catch (err) {
+    const code = err.code;
+    if (code && code !== "ENOENT") {
+      console.warn(
+        `[runtime/config] failed to read ${target}: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+    return {};
+  }
+}
+var WORKSPACES_CONFIG_VERSION = 1;
+var DEFAULT_CONFIG_DIR = () => resolve(homedir(), ".agentproto");
+var DEFAULT_CONFIG_PATH = () => resolve(DEFAULT_CONFIG_DIR(), "workspaces.json");
+function sanitizeSlug(input2) {
+  const trimmed = input2.trim().toLowerCase();
+  const cleaned = trimmed.replace(/[^a-z0-9_-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 64);
+  return cleaned || "workspace";
+}
+async function loadWorkspacesConfig(path = DEFAULT_CONFIG_PATH()) {
+  let raw;
+  try {
+    raw = await promises.readFile(path, "utf8");
+  } catch (err) {
+    if (err.code === "ENOENT") {
+      return { version: WORKSPACES_CONFIG_VERSION, workspaces: [] };
+    }
+    throw err;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(
+      `agentproto: ${path} is not valid JSON (${err instanceof Error ? err.message : String(err)}). Delete the file or fix it manually.`
+    );
+  }
+  return normalizeConfig(parsed);
+}
+function normalizeConfig(parsed) {
+  if (!parsed || typeof parsed !== "object") {
+    return { version: WORKSPACES_CONFIG_VERSION, workspaces: [] };
+  }
+  const obj = parsed;
+  const workspaces = [];
+  if (Array.isArray(obj.workspaces)) {
+    for (const entry of obj.workspaces) {
+      if (!entry || typeof entry !== "object") continue;
+      const e = entry;
+      const slug = typeof e.slug === "string" ? sanitizeSlug(e.slug) : "";
+      const path = typeof e.path === "string" ? e.path : "";
+      if (!slug || !path) continue;
+      const addedAt = typeof e.addedAt === "string" ? e.addedAt : (/* @__PURE__ */ new Date()).toISOString();
+      const updatedAt = typeof e.updatedAt === "string" ? e.updatedAt : addedAt;
+      const we = { slug, path, addedAt, updatedAt };
+      if (typeof e.label === "string" && e.label.trim()) {
+        we.label = e.label.trim();
+      }
+      workspaces.push(we);
+    }
+  }
+  const dedup = /* @__PURE__ */ new Map();
+  for (const w of workspaces) dedup.set(w.slug, w);
+  const finalList = Array.from(dedup.values());
+  const active = typeof obj.active === "string" && finalList.some((w) => w.slug === obj.active) ? obj.active : finalList[0]?.slug;
+  const out = {
+    version: WORKSPACES_CONFIG_VERSION,
+    workspaces: finalList
+  };
+  if (active !== void 0) out.active = active;
+  return out;
+}
+
 // ../define-doctype/dist/index.mjs
 var DEFAULT_ID_PATTERN = /^[a-z0-9][a-z0-9._-]{1,79}$/;
 var MAX_DESCRIPTION_LEN = 2e3;
@@ -1153,7 +1285,7 @@ function createVerbs(spec) {
     }
     return { path, handle: newHandle, rendered };
   }
-  async function resolve22(block, ctx = {}) {
+  async function resolve4(block, ctx = {}) {
     if ("inline" in block) {
       return spec.define(block.inline);
     }
@@ -1179,7 +1311,7 @@ function createVerbs(spec) {
   async function deleteFn(path) {
     await rm(path, { force: true });
   }
-  return { create, load, list, update, resolve: resolve22, delete: deleteFn };
+  return { create, load, list, update, resolve: resolve4, delete: deleteFn };
 }
 function defaultBody(spec, frontmatter) {
   const id = typeof frontmatter.name === "string" ? frontmatter.name : typeof frontmatter.id === "string" ? frontmatter.id : typeof frontmatter.slug === "string" ? frontmatter.slug : spec.name;
@@ -1197,51 +1329,28 @@ createDoctype({
   validate(def) {
     const result = extensionFrontmatterSchema.safeParse(def);
     if (!result.success) {
-      throw new Error(
-        `defineExtension (AIP-40): ${result.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ")}`
-      );
+      throw new Error(`defineExtension (AIP-40): ${result.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ")}`);
     }
   },
   build(def) {
     return { ...def };
   }
 });
-function parseExtensionManifest(source) {
-  const parsed = matter(source);
-  if (Object.keys(parsed.data).length === 0) {
-    throw new Error("parseExtensionManifest: missing or empty frontmatter");
-  }
-  const result = extensionFrontmatterSchema.safeParse(parsed.data);
-  if (!result.success) {
-    throw new Error(
-      `parseExtensionManifest: invalid frontmatter \u2014 ${result.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ")}`
-    );
-  }
-  return { frontmatter: result.data, body: parsed.content };
-}
-
-// ../extension/dist/index.mjs
 function specFromExtension(extension, opts = {}) {
   const { parent } = opts;
   const isRoot = extension.extends === "none";
   if (!isRoot && !parent) {
-    throw new Error(
-      `specFromExtension (AIP-40): extension '${extension.slug}' extends '${extension.extends}' but no parent spec was provided in opts.parent`
-    );
+    throw new Error(`specFromExtension (AIP-40): extension '${extension.slug}' extends '${extension.extends}' but no parent spec was provided in opts.parent`);
   }
   if (isRoot && !extension.path_convention) {
-    throw new Error(
-      `specFromExtension (AIP-40): extension '${extension.slug}' is a root doctype (extends: none) and MUST declare path_convention`
-    );
+    throw new Error(`specFromExtension (AIP-40): extension '${extension.slug}' is a root doctype (extends: none) and MUST declare path_convention`);
   }
   if (parent && extension.tighten) {
     verifyTightening(extension);
   }
   const slugName = extension.slug.split(":")[1] ?? extension.slug;
   const pathTemplate = extension.path_convention ?? null;
-  const extensionKeys = new Set(
-    Object.keys(extension.add_fields?.properties ?? {})
-  );
+  const extensionKeys = new Set(Object.keys(extension.add_fields?.properties ?? {}));
   const define = (params) => {
     const withDefaults = { ...params };
     if (extension.defaults) {
@@ -1257,8 +1366,10 @@ function specFromExtension(extension, opts = {}) {
     const parentOnly = {};
     const extensionOnly = {};
     for (const [key, value] of Object.entries(withDefaults)) {
-      if (extensionKeys.has(key)) extensionOnly[key] = value;
-      else parentOnly[key] = value;
+      if (extensionKeys.has(key))
+        extensionOnly[key] = value;
+      else
+        parentOnly[key] = value;
     }
     const parentHandle = parent.define(parentOnly);
     return Object.freeze({
@@ -1269,11 +1380,7 @@ function specFromExtension(extension, opts = {}) {
   const parse = isRoot ? rootParse(extension) : parent.parse;
   const pathOf = (handle) => {
     if (pathTemplate) {
-      return resolvePathTemplate(
-        pathTemplate,
-        handle,
-        slugName
-      );
+      return resolvePathTemplate(pathTemplate, handle, slugName);
     }
     return parent.pathOf(handle);
   };
@@ -1290,33 +1397,36 @@ function verifyTightening(extension, parent) {
   const t = extension.tighten ?? {};
   for (const [field, override] of Object.entries(t)) {
     if (typeof override.minLength === "number" && typeof override.maxLength === "number" && override.minLength > override.maxLength) {
-      throw new Error(
-        `specFromExtension (AIP-40): extension '${extension.slug}' tighten.${field}: minLength (${override.minLength}) > maxLength (${override.maxLength})`
-      );
+      throw new Error(`specFromExtension (AIP-40): extension '${extension.slug}' tighten.${field}: minLength (${override.minLength}) > maxLength (${override.maxLength})`);
     }
     if (typeof override.minimum === "number" && typeof override.maximum === "number" && override.minimum > override.maximum) {
-      throw new Error(
-        `specFromExtension (AIP-40): extension '${extension.slug}' tighten.${field}: minimum (${override.minimum}) > maximum (${override.maximum})`
-      );
+      throw new Error(`specFromExtension (AIP-40): extension '${extension.slug}' tighten.${field}: minimum (${override.minimum}) > maximum (${override.maximum})`);
     }
     if (override.enum !== void 0 && !Array.isArray(override.enum)) {
-      throw new Error(
-        `specFromExtension (AIP-40): extension '${extension.slug}' tighten.${field}: enum must be an array`
-      );
+      throw new Error(`specFromExtension (AIP-40): extension '${extension.slug}' tighten.${field}: enum must be an array`);
     }
   }
 }
 function rootParse(extension) {
   return (source) => {
-    throw new Error(
-      `specFromExtension (AIP-40): extension '${extension.slug}' is a root doctype \u2014 supply your own parser or extend a public AIP for parser inheritance`
-    );
+    throw new Error(`specFromExtension (AIP-40): extension '${extension.slug}' is a root doctype \u2014 supply your own parser or extend a public AIP for parser inheritance`);
   };
 }
 function resolvePathTemplate(template, handle, doctypeSlug) {
   const identity = typeof handle.id === "string" && handle.id || typeof handle.slug === "string" && handle.slug || typeof handle.name === "string" && handle.name || "unknown";
   return template.replace(/<slug>/g, identity).replace(/<DOCTYPE>/g, doctypeSlug.toUpperCase());
 }
+function parseExtensionManifest(source) {
+  const parsed = matter(source);
+  if (Object.keys(parsed.data).length === 0) {
+    throw new Error("parseExtensionManifest: missing or empty frontmatter");
+  }
+  const result = extensionFrontmatterSchema.safeParse(parsed.data);
+  if (!result.success) {
+    throw new Error(`parseExtensionManifest: invalid frontmatter \u2014 ${result.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ")}`);
+  }
+  return { frontmatter: result.data, body: parsed.content };
+}
 
 // ../mcp-server/dist/index.mjs
 async function createMcpServer(opts) {
@@ -1503,12 +1613,55 @@ async function writeRuntimeMeta(workspace, meta) {
     await writeFile(
       join(dir, "runtime.json"),
       JSON.stringify(meta, null, 2) + "\n",
-      "utf8"
+      { encoding: "utf8", mode: 384 }
     );
   } catch (err) {
     console.error("[runtime] failed to write .agentproto/runtime.json:", err);
   }
 }
+async function unlinkRuntimeMeta(workspace) {
+  try {
+    await unlink(join(workspace, ".agentproto", "runtime.json"));
+  } catch {
+  }
+}
+async function readRuntimeMeta(workspace) {
+  const path = join(workspace, ".agentproto", "runtime.json");
+  try {
+    const [raw, st] = await Promise.all([readFile(path, "utf8"), stat(path)]);
+    const meta = JSON.parse(raw);
+    return { meta, mtime: st.mtime };
+  } catch {
+    return null;
+  }
+}
+async function sweepStaleRuntimeMetas(workspaces, currentWorkspace) {
+  const cleaned = [];
+  for (const ws of workspaces) {
+    if (ws === currentWorkspace) continue;
+    const meta = await readRuntimeMeta(ws);
+    if (!meta) continue;
+    const pid = meta.meta.pid;
+    if (typeof pid === "number" && !isPidAlive(pid)) {
+      try {
+        await unlink(join(ws, ".agentproto", "runtime.json"));
+        cleaned.push(join(ws, ".agentproto", "runtime.json"));
+      } catch {
+      }
+    }
+  }
+  return cleaned;
+}
+function isPidAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    const code = err.code;
+    if (code === "EPERM") return true;
+    return false;
+  }
+}
 var DEFAULT_TIMEOUT_MS = 6e4;
 var MAX_TIMEOUT_MS = 6e5;
 var ALLOWLIST_REL = ".agentproto/allowed-commands.json";
@@ -1937,21 +2090,21 @@ function registerFsTools(server, opts) {
     }
   );
 }
-var WORKSPACES_CONFIG_VERSION = 1;
-var DEFAULT_CONFIG_DIR = () => resolve(homedir(), ".agentproto");
-var DEFAULT_CONFIG_PATH = () => resolve(DEFAULT_CONFIG_DIR(), "workspaces.json");
-function sanitizeSlug(input2) {
+var WORKSPACES_CONFIG_VERSION2 = 1;
+var DEFAULT_CONFIG_DIR2 = () => resolve(homedir(), ".agentproto");
+var DEFAULT_CONFIG_PATH2 = () => resolve(DEFAULT_CONFIG_DIR2(), "workspaces.json");
+function sanitizeSlug2(input2) {
   const trimmed = input2.trim().toLowerCase();
   const cleaned = trimmed.replace(/[^a-z0-9_-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 64);
   return cleaned || "workspace";
 }
-async function loadWorkspacesConfig(path = DEFAULT_CONFIG_PATH()) {
+async function loadWorkspacesConfig2(path = DEFAULT_CONFIG_PATH2()) {
   let raw;
   try {
     raw = await promises.readFile(path, "utf8");
   } catch (err) {
     if (err.code === "ENOENT") {
-      return { version: WORKSPACES_CONFIG_VERSION, workspaces: [] };
+      return { version: WORKSPACES_CONFIG_VERSION2, workspaces: [] };
     }
     throw err;
   }
@@ -1963,18 +2116,18 @@ async function loadWorkspacesConfig(path = DEFAULT_CONFIG_PATH()) {
       `agentproto: ${path} is not valid JSON (${err instanceof Error ? err.message : String(err)}). Delete the file or fix it manually.`
     );
   }
-  return normaliseConfig(parsed);
+  return normalizeConfig2(parsed);
 }
 function findWorkspace(config, slug) {
-  return config.workspaces.find((w) => w.slug === sanitizeSlug(slug));
+  return config.workspaces.find((w) => w.slug === sanitizeSlug2(slug));
 }
 function getActiveWorkspace(config) {
   if (!config.active) return config.workspaces[0];
   return findWorkspace(config, config.active) ?? config.workspaces[0];
 }
-function normaliseConfig(parsed) {
+function normalizeConfig2(parsed) {
   if (!parsed || typeof parsed !== "object") {
-    return { version: WORKSPACES_CONFIG_VERSION, workspaces: [] };
+    return { version: WORKSPACES_CONFIG_VERSION2, workspaces: [] };
   }
   const obj = parsed;
   const workspaces = [];
@@ -1982,7 +2135,7 @@ function normaliseConfig(parsed) {
     for (const entry of obj.workspaces) {
       if (!entry || typeof entry !== "object") continue;
       const e = entry;
-      const slug = typeof e.slug === "string" ? sanitizeSlug(e.slug) : "";
+      const slug = typeof e.slug === "string" ? sanitizeSlug2(e.slug) : "";
       const path = typeof e.path === "string" ? e.path : "";
       if (!slug || !path) continue;
       const addedAt = typeof e.addedAt === "string" ? e.addedAt : (/* @__PURE__ */ new Date()).toISOString();
@@ -1999,7 +2152,7 @@ function normaliseConfig(parsed) {
   const finalList = Array.from(dedup.values());
   const active = typeof obj.active === "string" && finalList.some((w) => w.slug === obj.active) ? obj.active : finalList[0]?.slug;
   const out = {
-    version: WORKSPACES_CONFIG_VERSION,
+    version: WORKSPACES_CONFIG_VERSION2,
     workspaces: finalList
   };
   if (active !== void 0) out.active = active;
@@ -2125,7 +2278,7 @@ async function scanGoose(home, out, errors) {
 async function scanRegisteredWorkspaces(out, errors) {
   let workspaces = [];
   try {
-    const cfg = await loadWorkspacesConfig();
+    const cfg = await loadWorkspacesConfig2();
     workspaces = cfg.workspaces;
   } catch (err) {
     errors.push(`workspaces: load failed \u2014 ${err.message}`);
@@ -2243,7 +2396,7 @@ async function loadImportedMcps(path = IMPORTED_MCPS_PATH()) {
       `agentproto: ${path} is not valid JSON (${err instanceof Error ? err.message : String(err)}). Delete or fix manually.`
     );
   }
-  return normalise(parsed);
+  return normalize3(parsed);
 }
 async function saveImportedMcps(config, path = IMPORTED_MCPS_PATH()) {
   await promises.mkdir(dirname(path), { recursive: true });
@@ -2269,7 +2422,7 @@ function addImport(config, input2) {
 function removeImport(config, id) {
   return { ...config, imports: config.imports.filter((e) => e.id !== id) };
 }
-function normalise(parsed) {
+function normalize3(parsed) {
   if (!parsed || typeof parsed !== "object") return EMPTY;
   const obj = parsed;
   const imports = [];
@@ -2289,6 +2442,7 @@ function normalise(parsed) {
 }
 function registerSessionTools(server, opts) {
   const { registry, resolveAgentAdapter, listAgentAdapters, mcpProxy } = opts;
+  const ptyEnabled = opts.ptyEnabled === true;
   server.tool(
     "start_agent_session",
     "Spawn a long-running agent CLI (claude-code, hermes, \u2026) on the host. The session stays alive across multiple turns \u2014 call `prompt_agent_session` to continue the conversation. Returns the session id + initial descriptor. When `workspaceSlug` is set, resolves the cwd via `~/.agentproto/workspaces.json`; otherwise pass `cwd` explicitly or fall back to the active workspace.",
@@ -2325,7 +2479,7 @@ function registerSessionTools(server, opts) {
       let resolvedSlug = input2.workspaceSlug ?? "default";
       if (!cwd) {
         try {
-          const config = await loadWorkspacesConfig();
+          const config = await loadWorkspacesConfig2();
           const ws = input2.workspaceSlug ? findWorkspace(config, input2.workspaceSlug) : getActiveWorkspace(config);
           if (ws) {
             cwd = ws.path;
@@ -2420,17 +2574,44 @@ function registerSessionTools(server, opts) {
       }
     }
   );
+  server.tool(
+    "list_sessions",
+    "List sessions tracked by the daemon \u2014 agent-CLI sessions (claude-code, hermes, \u2026), terminal/PTY sessions (claude TUI, bash, \u2026), and raw commands. Each entry includes `kind`, `pty` (true for real PTYs), `name` (when set at spawn), `status`, `command`, age + exit code. Use this when you need to know what's already running before spawning anything new, or to discover a session id by name.",
+    {
+      kind: z.enum(["terminal", "agent-cli", "command", "all"]).optional().describe(
+        "Filter by session kind. `all` (default) returns every kind. Use `terminal` to list only PTY sessions, `agent-cli` for structured ACP agents."
+      ),
+      onlyAlive: z.boolean().optional().describe("When true, only running/starting sessions. Default false."),
+      status: z.enum(["starting", "running", "exited", "killed", "error"]).optional().describe("Filter by exact status (overrides onlyAlive).")
+    },
+    async (input2) => {
+      let rows = registry.list();
+      if (input2.kind && input2.kind !== "all") {
+        rows = rows.filter((s) => s.kind === input2.kind);
+      }
+      if (input2.status) {
+        rows = rows.filter((s) => s.status === input2.status);
+      } else if (input2.onlyAlive) {
+        rows = rows.filter(
+          (s) => s.status === "running" || s.status === "starting"
+        );
+      }
+      return {
+        content: [
+          { type: "text", text: JSON.stringify({ sessions: rows }, null, 2) }
+        ]
+      };
+    }
+  );
   server.tool(
     "list_agent_sessions",
-    "List all sessions tracked by the daemon \u2014 running, exited, killed. Use to find a session id when the operator's previous start call returned long ago, or to tell the user what's currently active on their machine.",
+    "DEPRECATED \u2014 prefer `list_sessions` which returns ALL kinds + filters. Despite the name this tool already returns every kind, not just agent-cli sessions; the new tool's name reflects the actual surface.",
     {
-      onlyAlive: z.boolean().optional().describe("Filter to status running/starting/mounting only. Default false.")
+      onlyAlive: z.boolean().optional().describe("Filter to status running/starting only. Default false.")
     },
     async (input2) => {
       const all = registry.list();
-      const filtered = input2.onlyAlive ? all.filter(
-        (s) => s.status === "running" || s.status === "starting" || s.status === "mounting"
-      ) : all;
+      const filtered = input2.onlyAlive ? all.filter((s) => s.status === "running" || s.status === "starting") : all;
       return {
         content: [
           {
@@ -2792,69 +2973,269 @@ function registerSessionTools(server, opts) {
       };
     }
   );
-}
-function startHeartbeat(opts) {
-  const filename = opts.filename ?? "HEARTBEAT.md";
-  const path = join(opts.workspace, filename);
-  const now = opts.now ?? (() => /* @__PURE__ */ new Date());
-  let timer = null;
-  let currentEveryMs = null;
-  let firing = false;
-  async function load() {
-    if (!existsSync(path)) return null;
-    let source;
-    try {
-      source = await readFile(path, "utf8");
-    } catch {
-      return null;
-    }
-    const parsed = matter(source);
-    const fm = parsed.data;
-    const agent = typeof fm.agent === "string" ? fm.agent : null;
-    if (!agent) return null;
-    const enabled = fm.enabled === void 0 ? true : Boolean(fm.enabled);
-    const everyRaw = typeof fm.every === "string" ? fm.every : "60s";
-    const everyMs = parseDuration(everyRaw);
-    if (!everyMs) return null;
-    const conversationTemplate = typeof fm.conversation === "string" ? fm.conversation : "heartbeat-{date}";
-    return {
-      agent,
-      everyMs,
-      enabled,
-      conversationTemplate,
-      body: parsed.content.trim()
-    };
-  }
-  async function tick() {
-    if (firing) return;
-    if (opts.shouldFire && !opts.shouldFire()) return;
-    firing = true;
-    let agentId;
-    try {
-      const hb = await load();
-      if (!hb || !hb.enabled) return;
-      agentId = hb.agent;
-      const agent = await opts.buildAgent(hb.agent);
-      if (!agent) {
-        opts.events.emit({
-          type: "heartbeat-error",
-          at: now().toISOString(),
-          agent: hb.agent,
-          error: `buildAgent('${hb.agent}') returned null`
-        });
-        return;
+  const ptyNotConfigured = (toolName) => ({
+    content: [
+      {
+        type: "text",
+        text: `${toolName}: PTY support not enabled \u2014 the daemon was started without a node-pty factory. Re-run \`agentproto serve\` from a build that ships node-pty (the optional dep ships with @agentproto/cli).`
       }
-      if (!hb.body) {
-        opts.events.emit({
-          type: "heartbeat-error",
-          at: now().toISOString(),
-          agent: hb.agent,
-          error: "HEARTBEAT.md body is empty"
-        });
-        return;
+    ],
+    isError: true
+  });
+  server.tool(
+    "start_terminal_session",
+    "Spawn a process under a real PTY (node-pty) on the host. Bytes (including ANSI escapes, alt-screen sequences) flow through the daemon's byte ring buffer; subscribers attach via the WS at /sessions/:id/pty. Use for interactive TUIs (claude, vim, htop) or to orchestrate shells from another agent. Returns the session descriptor.",
+    {
+      argv: z.array(z.string()).min(1).describe(
+        "Argv array. First element is the binary, rest are arguments. e.g. ['claude'] or ['bash', '-l']."
+      ),
+      workspaceSlug: z.string().optional().describe(
+        "Workspace slug from `agentproto workspace list`. Resolves cwd. Omit to use `cwd` explicitly or the active workspace."
+      ),
+      cwd: z.string().optional().describe("Absolute cwd. Wins over workspaceSlug when both set."),
+      cols: z.number().int().min(1).max(500).optional().describe("Initial cols. Default 80."),
+      rows: z.number().int().min(1).max(200).optional().describe("Initial rows. Default 24."),
+      name: z.string().optional().describe(
+        "User-friendly slug. Becomes an alias for the session id in subsequent tool calls (read/write/kill accept either)."
+      ),
+      label: z.string().optional().describe(
+        "Free-text label surfaced in list_agent_sessions and the UI."
+      )
+    },
+    async (input2) => {
+      if (!ptyEnabled) return ptyNotConfigured("start_terminal_session");
+      let cwd = input2.cwd;
+      let resolvedSlug = input2.workspaceSlug ?? "default";
+      if (!cwd) {
+        try {
+          const config = await loadWorkspacesConfig2();
+          const ws = input2.workspaceSlug ? findWorkspace(config, input2.workspaceSlug) : getActiveWorkspace(config);
+          if (ws) {
+            cwd = ws.path;
+            resolvedSlug = ws.slug;
+          }
+        } catch {
+        }
       }
-      const conversationId = expandTemplate(hb.conversationTemplate, now());
-      await opts.conversations.open(conversationId, { agent: hb.agent });
+      if (!cwd) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: "start_terminal_session: no cwd resolvable. Pass `cwd` explicitly or `workspaceSlug` matching `agentproto workspace list`."
+            }
+          ],
+          isError: true
+        };
+      }
+      try {
+        const desc = registry.spawnPty({
+          argv: input2.argv,
+          cwd,
+          workspaceSlug: resolvedSlug,
+          cols: input2.cols ?? 80,
+          rows: input2.rows ?? 24,
+          ...input2.name ? { name: input2.name } : {},
+          ...input2.label ? { label: input2.label } : {}
+        });
+        return {
+          content: [{ type: "text", text: JSON.stringify(desc, null, 2) }]
+        };
+      } catch (err) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `start_terminal_session: ${err instanceof Error ? err.message : String(err)}`
+            }
+          ],
+          isError: true
+        };
+      }
+    }
+  );
+  server.tool(
+    "write_terminal_input",
+    "Send keystrokes to a PTY session's stdin. The text is forwarded verbatim \u2014 include trailing newlines if the target needs them (e.g. shell commands). Use after `start_terminal_session` to drive an interactive CLI.",
+    {
+      sessionId: z.string().describe("Session id OR name from start_terminal_session."),
+      text: z.string().describe("Text to write. Sent as-is to the PTY's stdin.")
+    },
+    async (input2) => {
+      if (!ptyEnabled) return ptyNotConfigured("write_terminal_input");
+      const desc = registry.findByIdOrName(input2.sessionId);
+      if (!desc) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `write_terminal_input: no session "${input2.sessionId}"`
+            }
+          ],
+          isError: true
+        };
+      }
+      const ok = registry.writeTerminalInput(desc.id, input2.text);
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({ ok, sessionId: desc.id }, null, 2)
+          }
+        ],
+        ...ok ? {} : { isError: true }
+      };
+    }
+  );
+  server.tool(
+    "read_terminal_output",
+    "Snapshot the recent byte buffer of a PTY session. Returns base64-encoded bytes (the buffer is RAW including ANSI escapes \u2014 strip with a regex if you want plain text). `lastBytes` caps the read from the tail.",
+    {
+      sessionId: z.string().describe("Session id OR name from start_terminal_session."),
+      lastBytes: z.number().int().min(1).max(64 * 1024).optional().describe("Max bytes from the tail. Default: full ring buffer (~64 KiB).")
+    },
+    async (input2) => {
+      if (!ptyEnabled) return ptyNotConfigured("read_terminal_output");
+      const desc = registry.findByIdOrName(input2.sessionId);
+      if (!desc) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `read_terminal_output: no session "${input2.sessionId}"`
+            }
+          ],
+          isError: true
+        };
+      }
+      const buf = registry.readTerminalOutput(
+        desc.id,
+        input2.lastBytes
+      );
+      if (!buf) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `read_terminal_output: session "${desc.id}" is not a PTY`
+            }
+          ],
+          isError: true
+        };
+      }
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              {
+                sessionId: desc.id,
+                status: desc.status,
+                bytes: buf.byteLength,
+                b64: buf.toString("base64")
+              },
+              null,
+              2
+            )
+          }
+        ]
+      };
+    }
+  );
+  server.tool(
+    "kill_terminal_session",
+    "SIGTERM a PTY session and drop it from the alive set. Same effect as `kill_agent_session` for the PTY family \u2014 separate name so it's obvious what's being stopped.",
+    {
+      sessionId: z.string().describe("Session id OR name from start_terminal_session.")
+    },
+    async (input2) => {
+      if (!ptyEnabled) return ptyNotConfigured("kill_terminal_session");
+      const desc = registry.findByIdOrName(input2.sessionId);
+      if (!desc) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `kill_terminal_session: no session "${input2.sessionId}"`
+            }
+          ],
+          isError: true
+        };
+      }
+      const ok = registry.kill(desc.id);
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({ ok, sessionId: desc.id }, null, 2)
+          }
+        ]
+      };
+    }
+  );
+}
+function startHeartbeat(opts) {
+  const filename = opts.filename ?? "HEARTBEAT.md";
+  const path = join(opts.workspace, filename);
+  const now = opts.now ?? (() => /* @__PURE__ */ new Date());
+  let timer = null;
+  let currentEveryMs = null;
+  let firing = false;
+  async function load() {
+    if (!existsSync(path)) return null;
+    let source;
+    try {
+      source = await readFile(path, "utf8");
+    } catch {
+      return null;
+    }
+    const parsed = matter(source);
+    const fm = parsed.data;
+    const agent = typeof fm.agent === "string" ? fm.agent : null;
+    if (!agent) return null;
+    const enabled = fm.enabled === void 0 ? true : Boolean(fm.enabled);
+    const everyRaw = typeof fm.every === "string" ? fm.every : "60s";
+    const everyMs = parseDuration(everyRaw);
+    if (!everyMs) return null;
+    const conversationTemplate = typeof fm.conversation === "string" ? fm.conversation : "heartbeat-{date}";
+    return {
+      agent,
+      everyMs,
+      enabled,
+      conversationTemplate,
+      body: parsed.content.trim()
+    };
+  }
+  async function tick() {
+    if (firing) return;
+    if (opts.shouldFire && !opts.shouldFire()) return;
+    firing = true;
+    let agentId;
+    try {
+      const hb = await load();
+      if (!hb || !hb.enabled) return;
+      agentId = hb.agent;
+      const agent = await opts.buildAgent(hb.agent);
+      if (!agent) {
+        opts.events.emit({
+          type: "heartbeat-error",
+          at: now().toISOString(),
+          agent: hb.agent,
+          error: `buildAgent('${hb.agent}') returned null`
+        });
+        return;
+      }
+      if (!hb.body) {
+        opts.events.emit({
+          type: "heartbeat-error",
+          at: now().toISOString(),
+          agent: hb.agent,
+          error: "HEARTBEAT.md body is empty"
+        });
+        return;
+      }
+      const conversationId = expandTemplate(hb.conversationTemplate, now());
+      await opts.conversations.open(conversationId, { agent: hb.agent });
       const startedAt = now();
       await opts.conversations.appendTurn(
         conversationId,
@@ -2964,6 +3345,11 @@ function preview(text3, max = 120) {
   const flat = text3.replace(/\s+/g, " ").trim();
   return flat.length > max ? `${flat.slice(0, max - 1)}\u2026` : flat;
 }
+var DEFAULT_ALLOWED_ORIGINS = [
+  "http://localhost:*",
+  "http://127.0.0.1:*",
+  "https://localhost:*"
+];
 async function startHttpServer(opts) {
   const startedAt = Date.now();
   const authSource = opts.auth ?? { mode: "none" };
@@ -2988,15 +3374,69 @@ async function startHttpServer(opts) {
     }
     return true;
   }
+  function checkSessionsToken(req) {
+    if (!opts.token) return "ok";
+    const header = req.headers.authorization;
+    const expected = `Bearer ${opts.token}`;
+    if (header === expected) return "ok";
+    const urlStr = req.url ?? "";
+    if (urlStr.includes("?")) {
+      const qs = new URLSearchParams(urlStr.slice(urlStr.indexOf("?") + 1));
+      const qsToken = qs.get("token");
+      if (qsToken && qsToken === opts.token) return "ok";
+    }
+    const origin = req.headers.origin;
+    if (typeof origin === "string" && originAllowed(origin)) return "ok";
+    return header ? "bad" : "missing";
+  }
+  function originAllowed(origin) {
+    const list = opts.strictOrigins ? opts.allowedOrigins ?? [] : [...DEFAULT_ALLOWED_ORIGINS, ...opts.allowedOrigins ?? []];
+    for (const pattern of list) {
+      if (pattern === origin) return true;
+      if (pattern.endsWith(":*")) {
+        const prefix = pattern.slice(0, -2);
+        if (origin === prefix || origin.startsWith(prefix + ":")) return true;
+      }
+    }
+    return false;
+  }
+  function rejectUnauthorizedSession(req, res, kind) {
+    const origin = req.headers.origin ?? null;
+    const allowList = opts.strictOrigins ? opts.allowedOrigins ?? [] : [...DEFAULT_ALLOWED_ORIGINS, ...opts.allowedOrigins ?? []];
+    res.writeHead(401, { "content-type": "application/json" });
+    const message = kind === "missing" ? origin ? `Origin "${origin}" not in the daemon's allowlist, and no Bearer token sent. Either add it (\`agentproto config set daemon.allowedOrigins ${origin}\` then restart the daemon), or send Authorization: Bearer <token> read from <workspace>/.agentproto/runtime.json.` : `Authorization: Bearer <token> required on mutating /sessions/* routes. Read the token from <workspace>/.agentproto/runtime.json. (Browser callers can use an Origin in the allowlist instead.)` : `Invalid bearer token. The daemon regenerated its token on its last boot \u2014 re-read <workspace>/.agentproto/runtime.json.`;
+    res.end(
+      JSON.stringify({
+        error: "sessions_unauthorized",
+        message,
+        // Debug data so a UI / network-tab inspection points the user
+        // straight at the fix without needing the daemon's stderr.
+        rejectedOrigin: origin,
+        allowedOrigins: allowList,
+        // We never echo the token; only the absence-or-presence flag.
+        receivedAuthHeader: typeof req.headers.authorization === "string"
+      })
+    );
+  }
+  function isMutatingSessionsRoute(method, path) {
+    if (!path.startsWith("/sessions")) return false;
+    if (method === "POST" || method === "DELETE" || method === "PUT" || method === "PATCH") {
+      return true;
+    }
+    return false;
+  }
   async function handleMcp(req, res) {
     if (!authorize(req, res)) return;
     const server2 = await opts.mcpServerFactory();
     const transport = new StreamableHTTPServerTransport({
       sessionIdGenerator: void 0
     });
-    transport.onerror = (err) => {
-      console.error("[mcp transport.onerror]", err);
-    };
+    const transportInternal = transport;
+    if ("onerror" in transport) {
+      transportInternal["onerror"] = (err) => {
+        console.error("[mcp transport.onerror]", err);
+      };
+    }
     res.on("close", () => {
       void transport.close();
       void server2.close();
@@ -3073,6 +3513,77 @@ async function startHttpServer(opts) {
     res.writeHead(202, { "content-type": "application/json" });
     res.end(JSON.stringify({ status: "fired" }));
   }
+  async function handleFileUpload(req, res, url) {
+    const reply = (status, body) => {
+      res.writeHead(status, { "content-type": "application/json" });
+      res.end(JSON.stringify(body));
+    };
+    const qs = new URLSearchParams(url.includes("?") ? url.slice(url.indexOf("?") + 1) : "");
+    const cwd = qs.get("cwd");
+    const rawName = qs.get("name");
+    if (!cwd || !rawName) {
+      reply(400, { error: "missing_cwd_or_name" });
+      return;
+    }
+    if (!isAbsolute(cwd)) {
+      reply(400, { error: "cwd_not_absolute" });
+      return;
+    }
+    const safeName = rawName.replace(/[/\\]/g, "_").replace(/\.\.+/g, ".").replace(/^\.+/, "").slice(0, 200);
+    if (safeName.length === 0) {
+      reply(400, { error: "invalid_name" });
+      return;
+    }
+    try {
+      const st = await stat(cwd);
+      if (!st.isDirectory()) {
+        reply(400, { error: "cwd_not_a_directory" });
+        return;
+      }
+    } catch {
+      reply(400, { error: "cwd_not_found" });
+      return;
+    }
+    const dir = join(cwd, ".agentproto-attachments");
+    const target = resolve(dir, safeName);
+    if (!target.startsWith(resolve(dir) + (dir.endsWith("/") ? "" : "/"))) {
+      reply(400, { error: "path_traversal_blocked" });
+      return;
+    }
+    const MAX_BYTES = 32 * 1024 * 1024;
+    const chunks = [];
+    let total = 0;
+    let aborted = false;
+    await new Promise((resolveBody, rejectBody) => {
+      req.on("data", (chunk) => {
+        if (aborted) return;
+        const buf = chunk;
+        total += buf.length;
+        if (total > MAX_BYTES) {
+          aborted = true;
+          reply(413, { error: "file_too_large", maxBytes: MAX_BYTES });
+          rejectBody(new Error("too_large"));
+          return;
+        }
+        chunks.push(buf);
+      });
+      req.on("end", () => {
+        if (!aborted) resolveBody();
+      });
+      req.on("error", (err) => rejectBody(err));
+    }).catch(() => void 0);
+    if (aborted) return;
+    try {
+      await mkdir(dir, { recursive: true });
+      await writeFile(target, Buffer.concat(chunks));
+      reply(200, { path: target, bytes: total });
+    } catch (err) {
+      reply(500, {
+        error: "write_failed",
+        message: err instanceof Error ? err.message : String(err)
+      });
+    }
+  }
   function applyCors(req, res) {
     const origin = req.headers.origin ?? "*";
     res.setHeader("Access-Control-Allow-Origin", origin);
@@ -3086,6 +3597,9 @@ async function startHttpServer(opts) {
       "Access-Control-Allow-Methods",
       "GET,POST,PUT,PATCH,DELETE,OPTIONS"
     );
+    if (req.headers["access-control-request-private-network"] === "true") {
+      res.setHeader("Access-Control-Allow-Private-Network", "true");
+    }
   }
   const server = createServer((req, res) => {
     void (async () => {
@@ -3130,19 +3644,36 @@ async function startHttpServer(opts) {
           await handleHeartbeatTick(req, res);
           return;
         }
+        if (path === "/files/upload" && req.method === "POST") {
+          const gate = checkSessionsToken(req);
+          if (gate !== "ok") {
+            rejectUnauthorizedSession(req, res, gate);
+            return;
+          }
+          await handleFileUpload(req, res, url);
+          return;
+        }
         if (opts.sessions && path.startsWith("/sessions")) {
+          if (isMutatingSessionsRoute(req.method ?? "GET", path)) {
+            const gate = checkSessionsToken(req);
+            if (gate !== "ok") {
+              rejectUnauthorizedSession(req, res, gate);
+              return;
+            }
+          }
           const handled = await handleSessions(
             req,
             res,
             path,
             opts.sessions,
-            opts.resolveAgentAdapter
+            opts.resolveAgentAdapter,
+            opts.ptyEnabled === true
           );
           if (handled) return;
         }
         if (path === "/workspaces" && req.method === "GET") {
           try {
-            const config = await loadWorkspacesConfig();
+            const config = await loadWorkspacesConfig2();
             res.writeHead(200, { "content-type": "application/json" });
             res.end(JSON.stringify(config));
           } catch (err) {
@@ -3326,19 +3857,179 @@ async function startHttpServer(opts) {
       }
     })();
   });
+  const wss = new WebSocketServer({ noServer: true });
+  server.on("upgrade", (req, socket, head) => {
+    const url = req.url ?? "/";
+    const path = url.split("?")[0] ?? "/";
+    const ptyMatch = path.match(/^\/sessions\/([^/]+)\/pty$/);
+    if (!ptyMatch) {
+      socket.destroy();
+      return;
+    }
+    if (!opts.sessions || opts.ptyEnabled !== true) {
+      rejectUpgrade(socket, 501, "pty_not_configured");
+      return;
+    }
+    const gate = checkSessionsToken(req);
+    if (gate !== "ok") {
+      rejectUpgrade(socket, 401, gate === "missing" ? "missing_token" : "bad_token");
+      return;
+    }
+    const id = ptyMatch[1];
+    if (!id) {
+      rejectUpgrade(socket, 400, "missing_id");
+      return;
+    }
+    const desc = opts.sessions.findByIdOrName(id);
+    if (!desc) {
+      rejectUpgrade(socket, 404, "session_not_found");
+      return;
+    }
+    if (desc.pty !== true) {
+      rejectUpgrade(socket, 400, "session_not_pty");
+      return;
+    }
+    if (desc.status === "exited" || desc.status === "killed" || desc.status === "error") {
+      rejectUpgrade(
+        socket,
+        410,
+        `session_${desc.status}`,
+        `Session ${desc.id}${desc.name ? ` (${desc.name})` : ""} has ${desc.status}. Spawn a fresh one with: agentproto sessions restart ${desc.name ?? desc.id}`
+      );
+      return;
+    }
+    wss.handleUpgrade(req, socket, head, (ws) => {
+      handlePtyWebSocket(ws, req, desc.id, opts.sessions);
+    });
+  });
   const bind = opts.bind ?? "127.0.0.1";
-  await new Promise((resolve7, reject) => {
+  await new Promise((resolve8, reject) => {
     server.once("error", reject);
-    server.listen(opts.port, bind, () => resolve7());
+    server.listen(opts.port, bind, () => resolve8());
   });
   return {
     url: `http://${bind}:${opts.port}`,
     async stop() {
-      await new Promise((resolve7) => server.close(() => resolve7()));
+      wss.close();
+      await new Promise((resolve8) => server.close(() => resolve8()));
     }
   };
 }
-async function handleSessions(req, res, path, registry, resolveAgentAdapter) {
+function rejectUpgrade(socket, status, reason, message) {
+  const reasonText = `${status} ${reason}`;
+  const body = { error: reason };
+  if (message) body.message = message;
+  try {
+    socket.write(
+      `HTTP/1.1 ${reasonText}\r
+Content-Type: application/json\r
+Connection: close\r
+\r
+` + JSON.stringify(body) + `
+`
+    );
+  } catch {
+  }
+  socket.destroy();
+}
+function handlePtyWebSocket(ws, req, sessionId, registry) {
+  const query = new URLSearchParams(
+    (req.url ?? "").includes("?") ? (req.url ?? "").split("?")[1] : ""
+  );
+  const cols = clampPositiveInt(query.get("cols"), 80);
+  const rows = clampPositiveInt(query.get("rows"), 24);
+  const BACKPRESSURE_BYTES = 256 * 1024;
+  const handle = registry.attachPty(
+    sessionId,
+    { cols, rows },
+    (chunk) => {
+      if (ws.readyState !== ws.OPEN) return;
+      if (ws.bufferedAmount > BACKPRESSURE_BYTES) return;
+      ws.send(
+        JSON.stringify({ kind: "data", b64: chunk.toString("base64") })
+      );
+    },
+    (evt) => {
+      if (ws.readyState !== ws.OPEN) return;
+      ws.send(
+        JSON.stringify({
+          kind: "exit",
+          exitCode: evt.exitCode,
+          ...evt.signal != null ? { signal: evt.signal } : {}
+        })
+      );
+      try {
+        ws.close(1e3, "session exited");
+      } catch {
+      }
+    }
+  );
+  if (!handle) {
+    try {
+      ws.close(1011, "session not attachable");
+    } catch {
+    }
+    return;
+  }
+  ws.on("message", (raw, isBinary) => {
+    if (isBinary) {
+      return;
+    }
+    let frame;
+    try {
+      frame = JSON.parse(raw.toString("utf8"));
+    } catch {
+      return;
+    }
+    if (!frame || typeof frame !== "object") return;
+    const f = frame;
+    switch (f.kind) {
+      case "input": {
+        if (typeof f.text === "string") {
+          handle.write(f.text);
+        } else if (typeof f.b64 === "string") {
+          try {
+            handle.write(Buffer.from(f.b64, "base64").toString("utf8"));
+          } catch {
+          }
+        }
+        break;
+      }
+      case "resize": {
+        const c = typeof f.cols === "number" && f.cols > 0 ? Math.floor(f.cols) : null;
+        const r = typeof f.rows === "number" && f.rows > 0 ? Math.floor(f.rows) : null;
+        if (c && r) handle.resize(c, r);
+        break;
+      }
+      case "ping":
+        try {
+          ws.send(JSON.stringify({ kind: "pong" }));
+        } catch {
+        }
+        break;
+    }
+  });
+  ws.on("close", () => {
+    handle.detach();
+  });
+  ws.on("error", () => {
+    handle.detach();
+  });
+}
+function clampPositiveInt(raw, fallback) {
+  if (!raw) return fallback;
+  const n = Number.parseInt(raw, 10);
+  return Number.isFinite(n) && n > 0 ? n : fallback;
+}
+function clampInt(raw, fallback, min, max) {
+  if (!raw) return fallback;
+  const n = Number.parseInt(raw, 10);
+  if (!Number.isFinite(n)) return fallback;
+  if (n < min) return min;
+  if (n > max) return max;
+  return n;
+}
+async function handleSessions(req, res, path, registry, resolveAgentAdapter, ptyEnabled = false) {
   const json = (status, body) => {
     res.writeHead(status, { "content-type": "application/json" });
     res.end(JSON.stringify(body));
@@ -3370,7 +4061,7 @@ async function handleSessions(req, res, path, registry, resolveAgentAdapter) {
     let workspaceSlug = typeof b.workspaceSlug === "string" ? b.workspaceSlug : "";
     if (!cwd) {
       try {
-        const config = await loadWorkspacesConfig();
+        const config = await loadWorkspacesConfig2();
         const ws = workspaceSlug ? findWorkspace(config, workspaceSlug) : getActiveWorkspace(config);
         if (ws) {
           cwd = ws.path;
@@ -3392,7 +4083,11 @@ async function handleSessions(req, res, path, registry, resolveAgentAdapter) {
       return true;
     }
     try {
-      const agentSession = await resolved.startSession({ cwd });
+      const resumeSessionId = typeof b.resumeSessionId === "string" && b.resumeSessionId.length > 0 ? b.resumeSessionId : void 0;
+      const agentSession = await resolved.startSession({
+        cwd,
+        ...resumeSessionId ? { resumeSessionId } : {}
+      });
       const desc = registry.spawnAgent({
         workspaceSlug,
         cwd,
@@ -3411,14 +4106,78 @@ async function handleSessions(req, res, path, registry, resolveAgentAdapter) {
     }
     return true;
   }
+  if (path === "/sessions/terminal" && req.method === "POST") {
+    if (!ptyEnabled) {
+      json(501, {
+        error: "pty_not_configured",
+        message: "POST /sessions/terminal needs the host to inject `spawnPty` into createGateway (node-pty optional dep \u2014 install in @agentproto/cli)."
+      });
+      return true;
+    }
+    const body = await readJsonBody(req);
+    if (!body || typeof body !== "object") {
+      json(400, { error: "invalid_body" });
+      return true;
+    }
+    const b = body;
+    const argv = Array.isArray(b.argv) ? b.argv.filter((v) => typeof v === "string") : [];
+    if (argv.length === 0) {
+      json(400, { error: "missing_argv" });
+      return true;
+    }
+    const cols = typeof b.cols === "number" && b.cols > 0 ? Math.floor(b.cols) : 80;
+    const rows = typeof b.rows === "number" && b.rows > 0 ? Math.floor(b.rows) : 24;
+    let cwd = typeof b.cwd === "string" && b.cwd.length > 0 ? b.cwd : null;
+    let workspaceSlug = typeof b.workspaceSlug === "string" ? b.workspaceSlug : "";
+    if (!cwd) {
+      try {
+        const config = await loadWorkspacesConfig2();
+        const ws = workspaceSlug ? findWorkspace(config, workspaceSlug) : getActiveWorkspace(config);
+        if (ws) {
+          cwd = ws.path;
+          workspaceSlug = ws.slug;
+        }
+      } catch {
+      }
+    }
+    if (!cwd) {
+      cwd = process.cwd();
+      console.warn(
+        `[/sessions/terminal] no cwd resolvable for argv=${argv.join(" ")} \u2014 falling back to daemon's cwd ${cwd}`
+      );
+    }
+    if (!workspaceSlug) workspaceSlug = "default";
+    try {
+      const desc = registry.spawnPty({
+        argv,
+        cwd,
+        workspaceSlug,
+        cols,
+        rows,
+        ...b.env && typeof b.env === "object" ? { env: b.env } : {},
+        ...typeof b.name === "string" ? { name: b.name } : {},
+        ...typeof b.label === "string" ? { label: b.label } : {}
+      });
+      json(201, desc);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      const status = msg.includes("already in use") ? 409 : msg.includes("no PTY factory") ? 501 : 500;
+      json(status, { error: "pty_spawn_failed", message: msg });
+    }
+    return true;
+  }
   const promptMatch = path.match(/^\/sessions\/([^/]+)\/prompt$/);
   if (promptMatch && req.method === "POST") {
     const id2 = promptMatch[1];
     if (!id2) return false;
     const body = await readJsonBody(req);
     const prompt = body?.prompt;
-    if (typeof prompt !== "string") {
-      json(400, { error: "missing_prompt" });
+    const validPrompt = typeof prompt === "string" && prompt.length > 0 || Array.isArray(prompt) && prompt.length > 0 && prompt.every((b) => b !== null && typeof b === "object") || prompt !== null && typeof prompt === "object" && !Array.isArray(prompt);
+    if (!validPrompt) {
+      json(400, {
+        error: "missing_prompt",
+        message: "Body `prompt` must be a non-empty string, a content block object, or an array of content blocks."
+      });
       return true;
     }
     const reqUrl = req.url ?? "";
@@ -3470,14 +4229,43 @@ async function handleSessions(req, res, path, registry, resolveAgentAdapter) {
     }
     return true;
   }
-  const idMatch = path.match(/^\/sessions\/([^/]+)(\/stream|\/kill)?$/);
-  if (!idMatch) return false;
-  const [, id, suffix] = idMatch;
-  if (!id) return false;
+  const idMatch = path.match(
+    /^\/sessions\/([^/]+)(\/stream|\/kill|\/preview)?$/
+  );
+  if (!idMatch) return false;
+  const [, rawIdOrName, suffix] = idMatch;
+  if (!rawIdOrName) return false;
+  const resolvedDesc = registry.findByIdOrName(rawIdOrName);
+  const id = resolvedDesc?.id ?? rawIdOrName;
+  if (suffix === "/preview" && req.method === "GET") {
+    if (!resolvedDesc) {
+      json(404, { error: "session_not_found", id: rawIdOrName });
+      return true;
+    }
+    const reqUrl = req.url ?? "";
+    const qs = new URLSearchParams(
+      reqUrl.includes("?") ? reqUrl.slice(reqUrl.indexOf("?") + 1) : ""
+    );
+    const lineCap = clampInt(qs.get("lines"), 10, 1, 200);
+    const byteCap = clampInt(qs.get("bytes"), 16 * 1024, 256, 64 * 1024);
+    const lines = [];
+    if (resolvedDesc.pty !== true) {
+      const unsub = registry.attach(id, (line) => {
+        lines.push(line);
+      });
+      if (unsub) unsub();
+    }
+    const bufBytes = registry.readTerminalOutput(id, byteCap);
+    json(200, {
+      id: resolvedDesc.id,
+      lines: lines.slice(-lineCap),
+      bytes: bufBytes ? bufBytes.toString("base64") : null
+    });
+    return true;
+  }
   if (suffix === "/stream" && req.method === "GET") {
-    const desc = registry.get(id);
-    if (!desc) {
-      json(404, { error: "session_not_found", id });
+    if (!resolvedDesc) {
+      json(404, { error: "session_not_found", id: rawIdOrName });
       return true;
     }
     res.writeHead(200, {
@@ -3521,12 +4309,11 @@ async function handleSessions(req, res, path, registry, resolveAgentAdapter) {
     return true;
   }
   if (!suffix && req.method === "GET") {
-    const desc = registry.get(id);
-    if (!desc) {
-      json(404, { error: "session_not_found", id });
+    if (!resolvedDesc) {
+      json(404, { error: "session_not_found", id: rawIdOrName });
       return true;
     }
-    json(200, desc);
+    json(200, resolvedDesc);
     return true;
   }
   if (!suffix && req.method === "DELETE") {
@@ -3548,14 +4335,80 @@ async function readJsonBody(req) {
     return null;
   }
 }
+var RESUME_STRATEGIES = {
+  "claude-code": {
+    // Printed by claude on graceful exit when session persistence
+    // is on (default). Example: `claude --resume 0e483f81-1a44-4bec-9667-b37158450296`
+    outputHint: /claude\s+--resume\s+([0-9a-f-]{8,})/i,
+    storeAs: "claudeResumeId",
+    fsProbe: probeMtimeLatestJsonl(".claude/projects"),
+    spawnArgs: (id) => ["claude", "--resume", id]
+  }
+  // Stubs for other shipped adapters — fill in as we learn each
+  // provider's resume mechanism. Today they fall back to ACP-level
+  // resume (whatever the agent-cli runtime supports) or fresh spawn.
+  //
+  //   hermes: { storeAs: "hermesResumeId", ... }
+  //   codex: { storeAs: "codexResumeId", ... }
+  //   openclaw: { storeAs: "openClawResumeId", ... }
+  //   opencode: { storeAs: "openCodeResumeId", ... }
+};
+function probeMtimeLatestJsonl(storeRel) {
+  return async (cwd, prevStartedAt) => {
+    const encoded = cwd.replace(/\//g, "-");
+    const dir = resolve(homedir(), storeRel, encoded);
+    let entries;
+    try {
+      entries = await promises.readdir(dir);
+    } catch {
+      return null;
+    }
+    const jsonl = entries.filter((e) => e.endsWith(".jsonl"));
+    if (jsonl.length === 0) return null;
+    const startedAtMs = Date.parse(prevStartedAt);
+    const candidates = [];
+    for (const f of jsonl) {
+      try {
+        const st = await promises.stat(join(dir, f));
+        if (!Number.isFinite(startedAtMs) || st.mtimeMs >= startedAtMs - 1e3) {
+          candidates.push({ name: f, mtime: st.mtimeMs });
+        }
+      } catch {
+      }
+    }
+    if (candidates.length === 0) return null;
+    candidates.sort((a, b) => b.mtime - a.mtime);
+    return candidates[0].name.replace(/\.jsonl$/, "");
+  };
+}
 var SESSIONS_FILE_PATH = () => resolve(homedir(), ".agentproto", "sessions.json");
 var RECENT_LINES_CAP = 500;
+var RECENT_BYTES_CAP = 64 * 1024;
 var PERSIST_DEBOUNCE_MS = 1500;
+var HISTORY_CAP = 200;
+function stripAnsiCodes(s) {
+  return s.replace(/\x1b\[[0-9;?]*[A-Za-z]/g, "");
+}
 function createSessionsRegistry(opts) {
-  const persistPath = SESSIONS_FILE_PATH();
+  const persistPath = opts?.persistPath ?? SESSIONS_FILE_PATH();
+  const persist = opts?.persist ?? true;
+  const ptyFactory = opts?.spawnPty;
+  const resumeAgent = opts?.resumeAgent;
   const sessions = /* @__PURE__ */ new Map();
   let persistTimer = null;
+  let nextSubId = 1;
+  let shutdownDone = false;
+  if (persist) {
+    loadHistorySnapshot(persistPath, sessions);
+  }
+  const onProcessExit = () => {
+    shutdownImpl();
+  };
+  if (persist) {
+    process.on("exit", onProcessExit);
+  }
   const schedulePersist = () => {
+    if (!persist) return;
     if (persistTimer) clearTimeout(persistTimer);
     persistTimer = setTimeout(() => {
       void persistSnapshot();
@@ -3581,8 +4434,47 @@ function createSessionsRegistry(opts) {
       rt.recentLines.splice(0, rt.recentLines.length - RECENT_LINES_CAP);
     }
     rt.desc.lastOutputAt = (/* @__PURE__ */ new Date()).toISOString();
+    sniffResumeHints(rt, line);
     rt.emitter.emit("line", { line, stream });
   };
+  const sniffResumeHints = (rt, line) => {
+    if (rt.desc.kind !== "agent-cli") return;
+    const strategy = rt.desc.adapterSlug ? RESUME_STRATEGIES[rt.desc.adapterSlug] : void 0;
+    if (!strategy?.outputHint) return;
+    const plain = stripAnsiCodes(line);
+    const m = plain.match(strategy.outputHint);
+    if (m && m[1]) {
+      rt.desc.resumeMetadata = {
+        ...rt.desc.resumeMetadata ?? {},
+        [strategy.storeAs]: m[1]
+      };
+      schedulePersist();
+    }
+  };
+  const appendBytes = (rt, chunk) => {
+    rt.recentBytes.push(chunk);
+    rt.recentBytesSize += chunk.byteLength;
+    while (rt.recentBytesSize > RECENT_BYTES_CAP && rt.recentBytes.length > 1) {
+      const dropped = rt.recentBytes.shift();
+      if (dropped) rt.recentBytesSize -= dropped.byteLength;
+    }
+    rt.desc.lastOutputAt = (/* @__PURE__ */ new Date()).toISOString();
+    rt.emitter.emit("data", chunk);
+  };
+  const reconcilePtySize = (rt) => {
+    if (!rt.pty || !rt.ptySubscribers || rt.ptySubscribers.size === 0) return;
+    let cols = Infinity;
+    let rows = Infinity;
+    for (const dim of rt.ptySubscribers.values()) {
+      if (dim.cols < cols) cols = dim.cols;
+      if (dim.rows < rows) rows = dim.rows;
+    }
+    if (!Number.isFinite(cols) || !Number.isFinite(rows)) return;
+    try {
+      rt.pty.resize(cols, rows);
+    } catch {
+    }
+  };
   const projectEvent = (rt, evt) => {
     switch (evt.kind) {
       case "text-delta":
@@ -3671,6 +4563,59 @@ function createSessionsRegistry(opts) {
     }
     return rt;
   };
+  const maybeResumeAgent = async (rt) => {
+    if (rt.agentSession) return;
+    if (!resumeAgent) return;
+    if (rt.desc.kind !== "agent-cli") return;
+    const adapterSlug = rt.desc.adapterSlug ?? rt.adapterSlug;
+    const adapterSessionId = rt.desc.adapterSessionId;
+    const cwd = rt.desc.cwd;
+    if (!adapterSlug || !adapterSessionId || !cwd) return;
+    if (rt.resumePromise) {
+      await rt.resumePromise;
+      return;
+    }
+    rt.resumePromise = (async () => {
+      appendLine(
+        rt,
+        `\u2500\u2500 resuming ${adapterSlug} session ${adapterSessionId} \u2500\u2500`,
+        "stdout"
+      );
+      try {
+        const fresh = await resumeAgent({
+          adapterSlug,
+          cwd,
+          resumeSessionId: adapterSessionId
+        });
+        if (!fresh) {
+          appendLine(
+            rt,
+            `[error] resume failed: adapter '${adapterSlug}' returned null`,
+            "stderr"
+          );
+          return;
+        }
+        rt.agentSession = fresh;
+        rt.adapterSlug = adapterSlug;
+        rt.desc.adapterSessionId = fresh.sessionId;
+        if (rt.desc.status !== "running") {
+          rt.desc.status = "running";
+          delete rt.desc.endedAt;
+          delete rt.desc.exitCode;
+          rt.emitter.emit("status", rt.desc.status);
+        }
+        schedulePersist();
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        appendLine(rt, `[error] resume failed: ${msg}`, "stderr");
+      }
+    })();
+    try {
+      await rt.resumePromise;
+    } finally {
+      rt.resumePromise = void 0;
+    }
+  };
   const runAgentTurn = async (rt, message) => {
     if (!rt.agentSession) {
       throw new Error("runAgentTurn: session has no agentSession");
@@ -3734,12 +4679,16 @@ function createSessionsRegistry(opts) {
         pid: child.pid ?? null,
         status: "starting",
         startedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        argv: input2.argv,
+        cwd: input2.cwd,
         ...input2.label ? { label: input2.label } : {}
       };
       const rt = {
         desc,
         child,
         recentLines: [],
+        recentBytes: [],
+        recentBytesSize: 0,
         emitter: new EventEmitter(),
         busy: false,
         textBuf: "",
@@ -3792,6 +4741,8 @@ function createSessionsRegistry(opts) {
         desc,
         child: input2.child,
         recentLines: [],
+        recentBytes: [],
+        recentBytesSize: 0,
         emitter: new EventEmitter(),
         busy: false,
         textBuf: "",
@@ -3829,6 +4780,13 @@ function createSessionsRegistry(opts) {
         status: "running",
         // driver already started the session
         startedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        cwd: input2.cwd,
+        adapterSlug: input2.adapterSlug,
+        // ACP-level session id — sticks across daemon restart so
+        // `agentproto sessions restart <id>` can pass it as
+        // `resumeSessionId` and the adapter reattaches to the prior
+        // conversation rather than starting blank.
+        adapterSessionId: input2.agentSession.sessionId,
         ...input2.label ? { label: input2.label } : {}
       };
       const rt = {
@@ -3836,6 +4794,8 @@ function createSessionsRegistry(opts) {
         agentSession: input2.agentSession,
         adapterSlug: input2.adapterSlug,
         recentLines: [],
+        recentBytes: [],
+        recentBytesSize: 0,
         emitter: new EventEmitter(),
         busy: false,
         textBuf: "",
@@ -3860,14 +4820,117 @@ function createSessionsRegistry(opts) {
       }
       return desc;
     },
+    spawnPty(input2) {
+      if (!ptyFactory) {
+        throw new Error(
+          "sessions.spawnPty: no PTY factory configured (node-pty optional dep missing in the daemon)"
+        );
+      }
+      const id = `sess_${randomUUID().slice(0, 8)}`;
+      if (input2.name) {
+        for (const rt2 of sessions.values()) {
+          if (rt2.desc.name !== input2.name) continue;
+          const status = rt2.desc.status;
+          if (status === "running" || status === "starting") {
+            throw new Error(
+              `sessions.spawnPty: name "${input2.name}" already in use by ${rt2.desc.id} (status=${status})`
+            );
+          }
+          rt2.desc.name = void 0;
+        }
+      }
+      const [bin, ...args] = input2.argv;
+      if (!bin) {
+        throw new Error("sessions.spawnPty: argv must include a binary");
+      }
+      const env = { ...process.env, ...input2.env ?? {} };
+      delete env.NODE_OPTIONS;
+      const pty = ptyFactory({
+        command: bin,
+        args,
+        cwd: input2.cwd,
+        env,
+        cols: input2.cols,
+        rows: input2.rows
+      });
+      const desc = {
+        id,
+        kind: "terminal",
+        workspaceSlug: input2.workspaceSlug,
+        command: [bin, ...args].map(quoteArg).join(" "),
+        pid: pty.pid,
+        status: "running",
+        startedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        pty: true,
+        argv: input2.argv,
+        cwd: input2.cwd,
+        ...input2.name ? { name: input2.name } : {},
+        ...input2.label ? { label: input2.label } : {}
+      };
+      const rt = {
+        desc,
+        pty,
+        ptySubscribers: /* @__PURE__ */ new Map(),
+        recentLines: [],
+        recentBytes: [],
+        recentBytesSize: 0,
+        emitter: new EventEmitter(),
+        busy: false,
+        textBuf: "",
+        thoughtBuf: ""
+      };
+      rt.emitter.setMaxListeners(50);
+      sessions.set(id, rt);
+      pty.onData((chunk) => {
+        appendBytes(rt, Buffer.from(chunk, "utf8"));
+      });
+      pty.onExit((evt) => {
+        if (rt.desc.status !== "killed") {
+          rt.desc.status = "exited";
+        }
+        rt.desc.endedAt = (/* @__PURE__ */ new Date()).toISOString();
+        if (typeof evt.exitCode === "number") rt.desc.exitCode = evt.exitCode;
+        rt.emitter.emit("exit", evt);
+        rt.emitter.emit("status", rt.desc.status);
+        schedulePersist();
+      });
+      schedulePersist();
+      return desc;
+    },
     async sendPrompt(id, message) {
+      const rtPre = sessions.get(id);
+      if (rtPre) await maybeResumeAgent(rtPre);
       const rt = validateAgentTurn(id, "sendPrompt");
       await runAgentTurn(rt, message);
     },
     enqueuePrompt(id, message) {
-      const rt = validateAgentTurn(id, "enqueuePrompt");
-      void runAgentTurn(rt, message).catch(() => {
-      });
+      const rtPre = sessions.get(id);
+      if (!rtPre) {
+        throw new Error(`enqueuePrompt: no session "${id}"`);
+      }
+      if (rtPre.desc.kind !== "agent-cli") {
+        throw new Error(
+          `enqueuePrompt: session "${id}" is not an agent session (kind=${rtPre.desc.kind})`
+        );
+      }
+      if (rtPre.busy) {
+        throw new Error(
+          `enqueuePrompt: session "${id}" is mid-turn \u2014 wait for it to finish or cancel`
+        );
+      }
+      void (async () => {
+        try {
+          await maybeResumeAgent(rtPre);
+          const rt = validateAgentTurn(id, "enqueuePrompt");
+          await runAgentTurn(rt, message);
+        } catch (err) {
+          appendLine(
+            rtPre,
+            `[error] ${err instanceof Error ? err.message : String(err)}`,
+            "stderr"
+          );
+        }
+      })();
     },
     list() {
       return Array.from(sessions.values()).map((s) => s.desc).sort((a, b) => b.startedAt.localeCompare(a.startedAt));
@@ -3883,6 +4946,65 @@ function createSessionsRegistry(opts) {
       rt.emitter.on("line", handler);
       return () => rt.emitter.off("line", handler);
     },
+    attachPty(id, initial, onData, onExit) {
+      const rt = sessions.get(id);
+      if (!rt || !rt.pty || !rt.ptySubscribers) return null;
+      for (const chunk of rt.recentBytes) onData(chunk);
+      const subId = nextSubId++;
+      rt.ptySubscribers.set(subId, { cols: initial.cols, rows: initial.rows });
+      reconcilePtySize(rt);
+      const dataHandler = (chunk) => onData(chunk);
+      const exitHandler = (evt) => onExit(evt);
+      rt.emitter.on("data", dataHandler);
+      rt.emitter.once("exit", exitHandler);
+      return {
+        write(data) {
+          if (!rt.pty) return;
+          try {
+            rt.pty.write(data);
+          } catch {
+          }
+        },
+        resize(cols, rows) {
+          if (!rt.ptySubscribers) return;
+          rt.ptySubscribers.set(subId, { cols, rows });
+          reconcilePtySize(rt);
+        },
+        detach() {
+          rt.emitter.off("data", dataHandler);
+          rt.emitter.off("exit", exitHandler);
+          rt.ptySubscribers?.delete(subId);
+          reconcilePtySize(rt);
+        }
+      };
+    },
+    findByIdOrName(query) {
+      const direct = sessions.get(query);
+      if (direct) return direct.desc;
+      for (const rt of sessions.values()) {
+        if (rt.desc.name === query) return rt.desc;
+      }
+      return void 0;
+    },
+    writeTerminalInput(id, data) {
+      const rt = sessions.get(id);
+      if (!rt || !rt.pty) return false;
+      try {
+        rt.pty.write(data);
+        return true;
+      } catch {
+        return false;
+      }
+    },
+    readTerminalOutput(id, lastBytes) {
+      const rt = sessions.get(id);
+      if (!rt || !rt.pty) return null;
+      const joined = Buffer.concat(rt.recentBytes, rt.recentBytesSize);
+      if (typeof lastBytes === "number" && lastBytes > 0 && joined.byteLength > lastBytes) {
+        return joined.subarray(joined.byteLength - lastBytes);
+      }
+      return joined;
+    },
     kill(id, signal = "SIGTERM") {
       const rt = sessions.get(id);
       if (!rt) return false;
@@ -3894,6 +5016,12 @@ function createSessionsRegistry(opts) {
       if (rt.agentSession) {
         void rt.agentSession.close().catch(() => void 0);
       }
+      if (rt.pty) {
+        try {
+          rt.pty.kill(signal);
+        } catch {
+        }
+      }
       rt.child?.kill(signal);
       schedulePersist();
       return true;
@@ -3907,19 +5035,91 @@ function createSessionsRegistry(opts) {
       return true;
     },
     shutdown() {
-      if (persistTimer) clearTimeout(persistTimer);
-      for (const rt of sessions.values()) {
-        rt.emitter.removeAllListeners();
-        if (rt.desc.status === "running" || rt.desc.status === "starting") {
-          if (rt.agentSession) {
-            void rt.agentSession.close().catch(() => void 0);
+      shutdownImpl();
+    }
+  };
+  function shutdownImpl() {
+    if (shutdownDone) return;
+    shutdownDone = true;
+    if (persistTimer) clearTimeout(persistTimer);
+    if (persist) {
+      try {
+        process.off("exit", onProcessExit);
+      } catch {
+      }
+    }
+    const nowIso = (/* @__PURE__ */ new Date()).toISOString();
+    for (const rt of sessions.values()) {
+      rt.emitter.removeAllListeners();
+      if (rt.desc.status === "running" || rt.desc.status === "starting") {
+        rt.desc.status = "killed";
+        rt.desc.endedAt = nowIso;
+        if (rt.agentSession) {
+          void rt.agentSession.close().catch(() => void 0);
+        }
+        if (rt.pty) {
+          try {
+            rt.pty.kill("SIGTERM");
+          } catch {
           }
-          rt.child?.kill("SIGTERM");
         }
+        rt.child?.kill("SIGTERM");
       }
-      sessions.clear();
     }
-  };
+    if (persist) {
+      try {
+        const snapshot = {
+          savedAt: nowIso,
+          sessions: Array.from(sessions.values()).map((s) => s.desc)
+        };
+        mkdirSync(dirname(persistPath), { recursive: true });
+        writeFileSync(persistPath, JSON.stringify(snapshot, null, 2) + "\n");
+      } catch {
+      }
+    }
+    sessions.clear();
+  }
+}
+function loadHistorySnapshot(persistPath, sessions) {
+  let raw;
+  try {
+    raw = readFileSync(persistPath, "utf8");
+  } catch {
+    return;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    console.warn(
+      `[sessions] history file ${persistPath} is malformed \u2014 ignoring`
+    );
+    return;
+  }
+  if (!Array.isArray(parsed.sessions)) return;
+  const sorted = parsed.sessions.filter((s) => !!s && typeof s.id === "string").sort((a, b) => b.startedAt.localeCompare(a.startedAt)).slice(0, HISTORY_CAP);
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  for (const desc of sorted) {
+    if (sessions.has(desc.id)) continue;
+    const wasAlive = desc.status === "running" || desc.status === "starting";
+    const reclassified = wasAlive ? {
+      ...desc,
+      status: "killed",
+      endedAt: desc.endedAt ?? now
+    } : desc;
+    const rt = {
+      desc: reclassified,
+      recentLines: [],
+      recentBytes: [],
+      recentBytesSize: 0,
+      emitter: new EventEmitter(),
+      busy: false,
+      textBuf: "",
+      thoughtBuf: ""
+    };
+    rt.emitter.setMaxListeners(50);
+    sessions.set(desc.id, rt);
+  }
 }
 function quoteArg(arg) {
   if (arg === "") return '""';
@@ -4115,9 +5315,24 @@ async function openClient(entry) {
     const transport = new StdioClientTransport({
       command: snap.command,
       args: snap.args ?? [],
-      env: { ...process.env, ...expandedEnv }
+      env: { ...process.env, ...expandedEnv },
+      // Pipe stderr so we can include it in the error message instead of
+      // surfacing the opaque "Connection closed" MCP error code.
+      stderr: "pipe"
     });
-    await client.connect(transport);
+    const stderrBuf = [];
+    transport.stderr?.on("data", (chunk) => {
+      stderrBuf.push(typeof chunk === "string" ? chunk : chunk.toString("utf8"));
+      if (stderrBuf.length > 40) stderrBuf.shift();
+    });
+    try {
+      await client.connect(transport);
+    } catch (err) {
+      const stderrText = stderrBuf.join("").trim();
+      const msg = err instanceof Error ? err.message : String(err);
+      throw new Error(stderrText ? `${msg}
+stderr: ${stderrText.slice(-600)}` : msg);
+    }
     return client;
   }
   if (snap.type === "http") {
@@ -4175,7 +5390,7 @@ function quickTunnelProvider() {
         { stdio: ["ignore", "pipe", "pipe"], shell: false }
       );
       child = proc;
-      const url = await new Promise((resolve7, reject) => {
+      const url = await new Promise((resolve8, reject) => {
         let settled = false;
         const timer = setTimeout(() => {
           if (settled) return;
@@ -4200,7 +5415,7 @@ function quickTunnelProvider() {
           if (match) {
             settled = true;
             clearTimeout(timer);
-            resolve7(match[0]);
+            resolve8(match[0]);
           }
         };
         proc.stderr?.on("data", onData);
@@ -4249,15 +5464,15 @@ function quickTunnelProvider() {
         }
       }, 3e3);
       timer.unref();
-      await new Promise((resolve7) => {
+      await new Promise((resolve8) => {
         if (proc.exitCode !== null) {
           clearTimeout(timer);
-          resolve7();
+          resolve8();
           return;
         }
         proc.once("exit", () => {
           clearTimeout(timer);
-          resolve7();
+          resolve8();
         });
       });
     }
@@ -4494,7 +5709,7 @@ var WorkspacePathError = class extends Error {
 };
 function createWorkspaceFs(opts) {
   const root = resolve(opts.workspace);
-  function resolvePath32(path) {
+  function resolvePath4(path) {
     if (typeof path !== "string" || path.length === 0) {
       throw new WorkspacePathError("path must be a non-empty string");
     }
@@ -4514,18 +5729,18 @@ function createWorkspaceFs(opts) {
   }
   return {
     async readFile(path) {
-      const abs = resolvePath32(path);
+      const abs = resolvePath4(path);
       const buf = await readFile(abs);
       return buf.toString("utf8");
     },
     async writeFile(path, content) {
-      const abs = resolvePath32(path);
+      const abs = resolvePath4(path);
       await mkdir(dirname(abs), { recursive: true });
       await writeFile(abs, content);
     },
     async exists(path) {
       try {
-        const abs = resolvePath32(path);
+        const abs = resolvePath4(path);
         return existsSync(abs);
       } catch {
         return false;
@@ -4557,7 +5772,31 @@ async function createGateway(opts) {
     name: opts.name ?? "agentproto-runtime",
     version: opts.version ?? "0.1.0-alpha"
   });
-  const sessions = createSessionsRegistry();
+  const sessions = createSessionsRegistry({
+    ...opts.spawnPty ? { spawnPty: opts.spawnPty } : {},
+    // Resume hook: when a prompt arrives for a dead agent-cli row
+    // (typical after daemon restart), the registry calls back into
+    // the adapter resolver to re-create the AgentSession with
+    // `resumeSessionId = adapterSessionId`. ACP semantics: the
+    // upstream provider reattaches to the prior conversation.
+    // Unwired (no resolveAgentAdapter) → legacy "not an agent
+    // session" error, user must spawn fresh.
+    ...opts.resolveAgentAdapter ? {
+      resumeAgent: async ({ adapterSlug, cwd, resumeSessionId }) => {
+        const adapter = await opts.resolveAgentAdapter(adapterSlug);
+        if (!adapter) return null;
+        try {
+          return await adapter.startSession({ cwd, resumeSessionId });
+        } catch (err) {
+          console.warn(
+            `[agentproto] resumeAgent('${adapterSlug}', ${resumeSessionId}) failed: ${err instanceof Error ? err.message : String(err)}`
+          );
+          return null;
+        }
+      }
+    } : {}
+  });
+  const token = opts.token ?? randomUUID();
   const mcpProxy = new McpProxyRegistry();
   const mcpServerFactory = async () => {
     const { server } = await createMcpServer({
@@ -4572,6 +5811,7 @@ async function createGateway(opts) {
     registerSessionTools(server, {
       registry: sessions,
       mcpProxy,
+      ptyEnabled: opts.spawnPty != null,
       ...opts.resolveAgentAdapter ? { resolveAgentAdapter: opts.resolveAgentAdapter } : {},
       ...opts.listAgentAdapters ? { listAgentAdapters: opts.listAgentAdapters } : {}
     });
@@ -4613,6 +5853,10 @@ async function createGateway(opts) {
     heartbeat,
     sessions,
     mcpProxy,
+    token,
+    ptyEnabled: opts.spawnPty != null,
+    ...opts.allowedOrigins ? { allowedOrigins: opts.allowedOrigins } : {},
+    ...opts.strictOrigins ? { strictOrigins: true } : {},
     ...opts.resolveAgentAdapter ? { resolveAgentAdapter: opts.resolveAgentAdapter } : {},
     ...opts.listAgentAdapters ? { listAgentAdapters: opts.listAgentAdapters } : {},
     meta: { workspace, registered }
@@ -4631,7 +5875,8 @@ async function createGateway(opts) {
     pid: process.pid,
     startedAt: (/* @__PURE__ */ new Date()).toISOString(),
     name: opts.name ?? "agentproto-runtime",
-    registered
+    registered,
+    token
   });
   return {
     url: http.url,
@@ -4639,6 +5884,7 @@ async function createGateway(opts) {
     workspaceFs,
     registered,
     sessions,
+    token,
     async stop() {
       heartbeat.stop();
       sessions.shutdown();
@@ -4687,10 +5933,17 @@ async function runServe(args) {
       label: { type: "string", short: "l" },
       workspace: { type: "string", short: "w" },
       port: { type: "string", short: "p" },
-      bind: { type: "string", short: "b" }
+      bind: { type: "string", short: "b" },
+      "allow-origin": { type: "string", multiple: true },
+      interactive: { type: "boolean", short: "i" }
     }
   });
-  const workspace = resolve(values.workspace ?? process.cwd());
+  const cfg = await loadConfig();
+  const cfgDaemon = cfg.daemon ?? {};
+  const cfgTunnel = cfg.tunnel ?? {};
+  const workspace = resolve(
+    values.workspace ?? cfgDaemon.workspace ?? process.cwd()
+  );
   try {
     const stat2 = await promises.stat(workspace);
     if (!stat2.isDirectory()) {
@@ -4708,20 +5961,21 @@ async function runServe(args) {
     );
     return 2;
   }
-  const port = values.port ? Number.parseInt(values.port, 10) : 18790;
+  const port = values.port ? Number.parseInt(values.port, 10) : typeof cfgDaemon.port === "number" ? cfgDaemon.port : 18790;
   if (!Number.isFinite(port) || port <= 0 || port > 65535) {
     process.stderr.write(`agentproto serve: invalid --port "${values.port}".
 `);
     return 2;
   }
-  const label = values.label ?? `${userInfo().username}@${hostname()}`;
+  const label = values.label ?? cfgDaemon.label ?? `${userInfo().username}@${hostname()}`;
+  const connectFlag = values.connect ?? (cfgTunnel.autoconnect && cfgTunnel.host ? cfgTunnel.host : void 0);
   let token = values.token ?? process.env.AGENTPROTO_TOKEN;
-  if (!token && values.connect) {
-    const cred = await readHost(values.connect);
+  if (!token && connectFlag) {
+    const cred = await readHost(connectFlag);
     if (cred) {
       if (isExpired(cred)) {
         process.stderr.write(
-          `agentproto serve: \u26A0 credentials for ${values.connect} are expired (${formatExpiry(cred)}). Re-run \`agentproto auth login --host ${values.connect}\`.
+          `agentproto serve: \u26A0 credentials for ${connectFlag} are expired (${formatExpiry(cred)}). Re-run \`agentproto auth login --host ${connectFlag}\`.
 `
         );
       }
@@ -4732,21 +5986,31 @@ async function runServe(args) {
       );
     }
   }
+  const allowOriginRaw = values["allow-origin"];
+  const cliOrigins = Array.isArray(allowOriginRaw) ? allowOriginRaw : [];
+  const cfgOrigins = Array.isArray(cfgDaemon.allowedOrigins) ? cfgDaemon.allowedOrigins : [];
+  const merged = [.../* @__PURE__ */ new Set([...cfgOrigins, ...cliOrigins])];
+  const allowedOrigins = merged.length > 0 ? merged : void 0;
   const opts = {
     workspace,
     port,
-    bind: values.bind ?? "127.0.0.1",
-    ...values.connect ? { connect: values.connect } : {},
+    bind: values.bind ?? cfgDaemon.bind ?? "127.0.0.1",
+    ...connectFlag ? { connect: connectFlag } : {},
     ...token ? { token } : {},
-    label
+    label,
+    ...allowedOrigins ? { allowedOrigins } : {},
+    ...cfgDaemon.strictOrigins === true ? { strictOrigins: true } : {}
   };
   const resolveAgentAdapter = async (slug) => {
     try {
       const adapter = await resolveAdapter(slug);
       const runtime = createAgentCliRuntime(adapter.handle);
       return {
-        async startSession({ cwd }) {
-          return runtime.start({ cwd });
+        async startSession({ cwd, resumeSessionId }) {
+          return runtime.start({
+            cwd,
+            ...resumeSessionId ? { resumeSessionId } : {}
+          });
         },
         commandPreview: `${adapter.handle.bin} ${(adapter.handle.bin_args ?? []).join(" ")}`.trim()
       };
@@ -4757,6 +6021,7 @@ async function runServe(args) {
       return null;
     }
   };
+  const spawnPty = await loadNodePtyFactory();
   let gateway;
   try {
     gateway = await createGateway({
@@ -4771,7 +6036,10 @@ async function runServe(args) {
       // Discovery for UIs / operators — `GET /adapters` + `list_adapters`
       // MCP tool. Walks node_modules @agentproto/adapter-* on each call;
       // cheap enough that we don't bother caching here.
-      listAgentAdapters: listInstalledAdapters
+      listAgentAdapters: listInstalledAdapters,
+      ...spawnPty ? { spawnPty } : {},
+      ...opts.allowedOrigins ? { allowedOrigins: opts.allowedOrigins } : {},
+      ...opts.strictOrigins ? { strictOrigins: true } : {}
     });
   } catch (err) {
     process.stderr.write(
@@ -4780,48 +6048,105 @@ async function runServe(args) {
     );
     return 1;
   }
-  process.stderr.write(
-    `agentproto serve: gateway up on ${gateway.url}
-  workspace: ${gateway.workspace}
-  mcp:       ${gateway.url}/mcp
-  sessions:  ${gateway.url}/sessions
-  events:    ${gateway.url}/events
+  printBootBanner({
+    url: gateway.url,
+    workspace: gateway.workspace,
+    ptyEnabled: spawnPty != null,
+    allowedOrigins: opts.allowedOrigins,
+    strictOrigins: opts.strictOrigins === true,
+    connect: opts.connect
+  });
+  try {
+    const wsConfig = await loadWorkspacesConfig();
+    const paths = wsConfig.workspaces.map((w) => w.path);
+    const cleaned = await sweepStaleRuntimeMetas(paths, opts.workspace);
+    if (cleaned.length > 0) {
+      process.stderr.write(
+        `${color.dim}cleaned ${cleaned.length} stale runtime.json file(s) (dead PID)${color.reset}
 `
-  );
+      );
+    }
+  } catch {
+  }
   const aborter = new AbortController();
   let shuttingDown = false;
   const shutdown = async (signal) => {
     if (shuttingDown) return;
     shuttingDown = true;
-    process.stderr.write(`
-agentproto serve: ${signal} \u2014 shutting down.
-`);
+    process.stderr.write(
+      `
+${color.dim}\u2500\u2500 shutting down (${signal}) \u2500\u2500${color.reset}
+`
+    );
     aborter.abort();
     await gateway.stop().catch(() => void 0);
+    await unlinkRuntimeMeta(opts.workspace).catch(() => void 0);
     process.exit(0);
   };
   process.once("SIGINT", () => void shutdown("SIGINT"));
   process.once("SIGTERM", () => void shutdown("SIGTERM"));
+  process.once("SIGHUP", () => void shutdown("SIGHUP"));
+  if (values.interactive) {
+    process.stderr.write(
+      `${color.dim}entering interactive monitor \u2014 q in the TUI to quit (daemon + TUI both).${color.reset}
+`
+    );
+    const childArgv = [process.argv[1] ?? "", "sessions", "--watch"];
+    const child = childProc.spawn(process.execPath, childArgv, {
+      stdio: "inherit",
+      env: {
+        ...process.env,
+        AGENTPROTO_DAEMON_URL: gateway.url,
+        // `gateway.token` is the per-boot daemon bearer (different
+        // from `token`, which was the tunnel JWT). Without this, the
+        // child's restart/kill calls would 401 against its own
+        // parent — exactly the bug that closed --interactive after
+        // any failed action.
+        AGENTPROTO_DAEMON_TOKEN: gateway.token
+      }
+    });
+    await new Promise((resolve4) => {
+      child.once("exit", () => resolve4());
+      aborter.signal.addEventListener("abort", () => {
+        try {
+          child.kill("SIGTERM");
+        } catch {
+        }
+      });
+    });
+    if (!shuttingDown) {
+      aborter.abort();
+      await gateway.stop().catch(() => void 0);
+      await unlinkRuntimeMeta(opts.workspace).catch(() => void 0);
+    }
+    return 0;
+  }
   if (!opts.connect) {
     process.stderr.write(
-      `agentproto serve: running local-only (no --connect). Press Ctrl-C to stop.
+      `${color.dim}Press Ctrl-C to stop.${color.reset}
 `
     );
-    await new Promise((resolve3) => {
-      aborter.signal.addEventListener("abort", () => resolve3());
+    await new Promise((resolve4) => {
+      aborter.signal.addEventListener("abort", () => resolve4());
     });
     return 0;
   }
   process.stderr.write(
-    `agentproto serve: tunnel \u2014 connecting to ${opts.connect} as '${opts.label}'\u2026
+    `${color.dim}tunnel \xB7 connecting to ${opts.connect} as '${opts.label}'\u2026${color.reset}
 `
   );
   let backoffMs = opts.reconnectMinMs ?? 1e3;
   const backoffMax = opts.reconnectMaxMs ?? 3e4;
+  const reconnectState = { immediate: false };
   while (!aborter.signal.aborted) {
     try {
-      await runOneTunnel(opts, gateway, aborter.signal);
+      await runOneTunnel(opts, gateway, spawnPty, aborter.signal, reconnectState);
       backoffMs = opts.reconnectMinMs ?? 1e3;
+      if (reconnectState.immediate) {
+        reconnectState.immediate = false;
+        continue;
+      }
+      await sleep(2e3, aborter.signal);
     } catch (err) {
       if (aborter.signal.aborted) break;
       const msg = err instanceof Error ? err.message : String(err);
@@ -4836,17 +6161,17 @@ agentproto serve: ${signal} \u2014 shutting down.
   }
   return 0;
 }
-async function runOneTunnel(opts, gateway, signal) {
+async function runOneTunnel(opts, gateway, spawnPty, signal, reconnectState) {
   if (!opts.connect) throw new Error("runOneTunnel: --connect not set");
   const headers = {
     "user-agent": "agentproto/0.1.0-alpha"
   };
   if (opts.token) headers.authorization = `Bearer ${opts.token}`;
   const ws = new WebSocket(opts.connect, { headers });
-  await new Promise((resolve3, reject) => {
+  await new Promise((resolve4, reject) => {
     const onOpen = () => {
       ws.off("error", onError);
-      resolve3();
+      resolve4();
     };
     const onError = (err) => {
       ws.off("open", onOpen);
@@ -4866,16 +6191,86 @@ async function runOneTunnel(opts, gateway, signal) {
   process.stderr.write(`agentproto serve: tunnel up.
 `);
   const sink = wrapWebSocket(ws);
+  const keepaliveInterval = setInterval(() => {
+    try {
+      sink.send({ t: "ping", nonce: randomUUID() });
+    } catch {
+    }
+  }, 3e4);
   const server = createTunnelServer({
     sink,
     label: opts.label,
-    pty: false,
+    pty: spawnPty !== null,
+    ...spawnPty ? { spawnPty } : {},
     // Generic HTTP-relay upstream for tunnel `http_request` frames.
     // Cloud-side callers (e.g. the API's local-daemon filesystem
     // provider) can now route MCP JSON-RPC + any other HTTP through
     // the daemon without needing a public URL. We point at the local
     // gateway since that's where `/mcp`, `/sessions`, `/events` live.
     httpUpstream: gateway.url,
+    // WS forwarding upstream — daemon dials the local gateway's WS
+    // endpoints (/sessions/:id/pty, etc) and pipes frames to the host.
+    // Used by the cloud tunnel pod so browsers on mobile can attach to
+    // interactive PTY sessions even though the daemon is only reachable
+    // through the host (not directly).
+    dialUpstreamWs: async ({ url, protocols, headers: headers2 }) => {
+      const upstreamHeaders = {
+        ...headers2
+      };
+      if (!upstreamHeaders["origin"] && !upstreamHeaders["Origin"]) {
+        try {
+          const u = new URL(url);
+          const httpScheme = u.protocol === "wss:" ? "https:" : "http:";
+          upstreamHeaders["Origin"] = `${httpScheme}//${u.host}`;
+        } catch {
+        }
+      }
+      return await new Promise((resolve4, reject) => {
+        const sock = new WebSocket(url, protocols ? [...protocols] : void 0, {
+          headers: upstreamHeaders
+        });
+        const onceOpen = () => {
+          sock.off("error", onceError);
+          sock.off("unexpected-response", onceUnexpected);
+          resolve4({
+            protocol: sock.protocol ?? "",
+            send: (data, sendOpts) => {
+              sock.send(data, { binary: sendOpts.binary });
+            },
+            close: (code, reason) => {
+              try {
+                sock.close(code, reason);
+              } catch {
+              }
+            },
+            onMessage: (handler) => {
+              sock.on("message", (raw, isBinary) => {
+                handler(raw, isBinary);
+              });
+            },
+            onClose: (handler) => {
+              sock.on("close", (code, reason) => {
+                handler(code, reason.toString("utf8"));
+              });
+            },
+            onError: (handler) => {
+              sock.on("error", (err) => handler(err));
+            }
+          });
+        };
+        const onceError = (err) => {
+          sock.off("open", onceOpen);
+          reject(err);
+        };
+        const onceUnexpected = (_req, res) => {
+          sock.off("open", onceOpen);
+          reject(new Error(`Unexpected server response: ${res.statusCode ?? 0}`));
+        };
+        sock.once("open", onceOpen);
+        sock.once("error", onceError);
+        sock.once("unexpected-response", onceUnexpected);
+      });
+    },
     // v0 authorize hook: trust the bearer-authenticated host completely.
     // Token possession proves the host was provisioned for this daemon.
     // Per-spawn policy filtering will land alongside the policy.toml.
@@ -4895,33 +6290,93 @@ async function runOneTunnel(opts, gateway, signal) {
         kind: "agent-cli",
         label: `tunnel: ${request.command.split("/").pop() ?? request.command}`
       });
+    },
+    // Graceful drain hook — flip the outer loop's "reconnect immediately"
+    // flag and close the WS so the supervisor reconnects without backoff.
+    // Host will follow up with close(1012) ~2s later as a hard backstop.
+    onReconnectSoon: ({ reasonMs }) => {
+      process.stderr.write(
+        `agentproto serve: host signaled drain (reasonMs=${reasonMs ?? "?"}) \u2014 reconnecting immediately
+`
+      );
+      reconnectState.immediate = true;
+      try {
+        ws.close(1e3, "host_drain");
+      } catch {
+      }
     }
   });
-  await new Promise((resolve3) => {
+  await new Promise((resolve4) => {
     const offClose = sink.onClose(() => {
+      clearInterval(keepaliveInterval);
       offClose();
-      resolve3();
+      resolve4();
     });
     if (signal.aborted) {
-      server.close().finally(() => resolve3());
+      clearInterval(keepaliveInterval);
+      server.close().finally(() => resolve4());
     }
     signal.addEventListener("abort", () => {
-      server.close().finally(() => resolve3());
+      clearInterval(keepaliveInterval);
+      server.close().finally(() => resolve4());
     });
   });
   process.stderr.write(`agentproto serve: tunnel closed.
 `);
 }
 function sleep(ms, signal) {
-  return new Promise((resolve3) => {
-    if (signal.aborted) return resolve3();
-    const timer = setTimeout(resolve3, ms);
+  return new Promise((resolve4) => {
+    if (signal.aborted) return resolve4();
+    const timer = setTimeout(resolve4, ms);
     signal.addEventListener("abort", () => {
       clearTimeout(timer);
-      resolve3();
+      resolve4();
     });
   });
 }
+function printBootBanner(opts) {
+  const c = color;
+  const home = process.env.HOME ?? "";
+  const workspace = home && opts.workspace.startsWith(home) ? "~" + opts.workspace.slice(home.length) : opts.workspace;
+  const ptyState = opts.ptyEnabled ? `${c.green}enabled${c.reset} ${c.dim}(node-pty)${c.reset}` : `${c.amber}disabled${c.reset} ${c.dim}(install node-pty to enable)${c.reset}`;
+  let origins;
+  if (opts.strictOrigins) {
+    origins = opts.allowedOrigins && opts.allowedOrigins.length > 0 ? `${c.amber}STRICT${c.reset} ${opts.allowedOrigins.join(" \xB7 ")} ${c.dim}(localhost defaults disabled)${c.reset}` : `${c.red}STRICT \xB7 empty allowlist${c.reset} ${c.dim}(every Origin will 401 \u2014 only Bearer-token works)${c.reset}`;
+  } else {
+    origins = opts.allowedOrigins && opts.allowedOrigins.length > 0 ? opts.allowedOrigins.join(" \xB7 ") + ` ${c.dim}+ localhost (default)${c.reset}` : `${c.dim}localhost:* only (default)${c.reset}`;
+  }
+  const mode = opts.connect ? `${c.cyan}tunnel${c.reset} ${c.dim}\u2192 ${opts.connect}${c.reset}` : `${c.dim}local-only${c.reset}`;
+  const line = `${c.dim}\u2500${c.reset}`;
+  process.stderr.write(
+    `
+${line} ${c.bold}agentproto${c.reset} ${c.dim}\xB7${c.reset} gateway up ${c.dim}\xB7${c.reset} ${c.cyan}${opts.url}${c.reset} ${line}
+  ${c.dim}workspace${c.reset}    ${workspace}
+  ${c.dim}pty${c.reset}          ${ptyState}
+  ${c.dim}origins${c.reset}      ${origins}
+  ${c.dim}endpoints${c.reset}    /mcp \xB7 /sessions \xB7 /events \xB7 /sessions/:id/pty ${c.dim}(WS)${c.reset}
+  ${c.dim}mode${c.reset}         ${mode}
+
+`
+  );
+}
+var _isTty = !!process.stderr.isTTY;
+var color = _isTty ? {
+  reset: "\x1B[0m",
+  bold: "\x1B[1m",
+  dim: "\x1B[2m",
+  green: "\x1B[32m",
+  amber: "\x1B[33m",
+  cyan: "\x1B[36m",
+  red: "\x1B[31m"
+} : {
+  reset: "",
+  bold: "",
+  dim: "",
+  green: "",
+  amber: "",
+  cyan: "",
+  red: ""
+};
 
 export { listInstalledAdapters, resolveAdapter, runInstall, runRun, runServe };
 //# sourceMappingURL=index.mjs.map