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

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, readFile, unlink, 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}`
+          );
+        }
       }
     }
   }
@@ -102,8 +106,8 @@ async function collectAgentprotoNamespaceRoots(start) {
   for (let depth = 0; depth < 16; depth++) {
     for (const candidate of candidatesAt(cur)) {
       try {
-        const stat2 = await promises.stat(candidate);
-        if (stat2.isDirectory()) roots.push(candidate);
+        const stat3 = await promises.stat(candidate);
+        if (stat3.isDirectory()) roots.push(candidate);
       } catch {
       }
     }
@@ -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 });
     });
   });
 }
@@ -481,9 +485,315 @@ async function saveLedger(path, ledger) {
   await chmod(path, 384).catch(() => {
   });
 }
+async function runInstallProfile(slug, args) {
+  const { values } = parseArgs({
+    args: [...args],
+    allowPositionals: true,
+    strict: true,
+    options: {
+      force: { type: "boolean", short: "f" },
+      "dry-run": { type: "boolean" },
+      "skip-setup": { type: "boolean" },
+      cwd: { type: "string" },
+      package: { type: "string" }
+    }
+  });
+  if (!slug.startsWith("runtime-profile/")) {
+    process.stderr.write(
+      `agentproto install: expected slug starting with 'runtime-profile/', got '${slug}'.
+`
+    );
+    return 2;
+  }
+  const profileName = slug.slice("runtime-profile/".length);
+  if (!/^[a-z][a-z0-9-]*$/.test(profileName)) {
+    process.stderr.write(
+      `agentproto install: invalid profile name '${profileName}'. Lower-kebab only.
+`
+    );
+    return 2;
+  }
+  let packageName;
+  if (typeof values.package === "string" && values.package) {
+    packageName = values.package;
+  } else {
+    const aliased = await readProfileAlias(profileName);
+    packageName = aliased ?? `@agentproto/runtime-profile-${profileName}`;
+  }
+  let mod;
+  try {
+    mod = await import(packageName);
+  } catch (err) {
+    const cause = err instanceof Error ? err.message : String(err);
+    process.stderr.write(
+      `agentproto install: could not load profile package '${packageName}'. Install it first with: npm i -g ${packageName}
+  cause: ${cause}
+`
+    );
+    return 1;
+  }
+  const filesDir = typeof mod.FILES_DIR === "string" ? mod.FILES_DIR : null;
+  const loadProfileManifest = mod.loadProfileManifest;
+  if (!filesDir || !loadProfileManifest) {
+    process.stderr.write(
+      `agentproto install: profile package '${packageName}' does not export FILES_DIR + loadProfileManifest.
+`
+    );
+    return 1;
+  }
+  const manifest = await loadProfileManifest();
+  const cwd = values.cwd ? resolve(values.cwd) : process.cwd();
+  const dryRun = values["dry-run"] === true;
+  const force = values.force === true;
+  process.stdout.write(
+    `agentproto install ${slug} v${manifest.version} \u2192 ${cwd}
+  ${manifest.description}
+`
+  );
+  const ledgerPath = ledgerPathFor2(profileName);
+  const prevLedger = await loadLedger2(ledgerPath);
+  const newLedger = {
+    slug,
+    version: manifest.version,
+    installedAt: prevLedger?.installedAt ?? (/* @__PURE__ */ new Date()).toISOString(),
+    updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    files: []
+  };
+  let applied = 0;
+  let skipped = 0;
+  let failed = 0;
+  for (const entry of manifest.files) {
+    const src = resolve(filesDir, entry.src);
+    const dest = resolve(cwd, entry.dest);
+    const prev = prevLedger?.files.find((f) => f.dest === entry.dest) ?? null;
+    try {
+      const srcBuf = await readFile(src);
+      const result = await applyStrategy({
+        strategy: entry.strategy,
+        srcBuf,
+        dest,
+        prev,
+        force,
+        dryRun
+      });
+      newLedger.files.push({
+        dest: entry.dest,
+        strategy: entry.strategy,
+        hashAfter: result.hashAfter,
+        appliedAt: result.wrote ? (/* @__PURE__ */ new Date()).toISOString() : prev?.appliedAt ?? (/* @__PURE__ */ new Date()).toISOString()
+      });
+      if (result.wrote) {
+        applied += 1;
+        process.stdout.write(`  ${result.action.padEnd(10)} ${entry.dest}
+`);
+        if (entry.executable && !dryRun) {
+          await chmod(dest, 493);
+        }
+      } else {
+        skipped += 1;
+        process.stdout.write(`  ${result.action.padEnd(10)} ${entry.dest}
+`);
+      }
+    } catch (err) {
+      failed += 1;
+      const msg = err instanceof Error ? err.message : String(err);
+      process.stderr.write(`  FAIL       ${entry.dest} \u2014 ${msg}
+`);
+    }
+  }
+  if (!dryRun) {
+    await saveLedger2(ledgerPath, newLedger);
+  }
+  process.stdout.write(
+    `agentproto install ${slug}: ${applied} applied, ${skipped} skipped, ${failed} failed${dryRun ? " (dry-run)" : ""}
+`
+  );
+  return failed === 0 ? 0 : 1;
+}
+async function applyStrategy(opts) {
+  const { strategy, srcBuf, dest, prev, force, dryRun } = opts;
+  const destExists = await fileExists(dest);
+  if (strategy === "preserve") {
+    if (destExists) {
+      const currentHash = await hashFile(dest);
+      return { wrote: false, action: "preserve", hashAfter: currentHash };
+    }
+    if (!dryRun) {
+      await ensureDir(dirname(dest));
+      await writeFile(dest, srcBuf);
+    }
+    return { wrote: true, action: "create", hashAfter: sha256(srcBuf) };
+  }
+  if (strategy === "overwrite") {
+    const srcHash = sha256(srcBuf);
+    if (destExists && !force) {
+      const destHash = await hashFile(dest);
+      if (destHash === srcHash) {
+        return { wrote: false, action: "unchanged", hashAfter: destHash };
+      }
+      if (prev && prev.hashAfter !== destHash) {
+        return {
+          wrote: false,
+          action: "user-edit",
+          hashAfter: destHash
+        };
+      }
+    }
+    if (!dryRun) {
+      await ensureDir(dirname(dest));
+      await writeFile(dest, srcBuf);
+    }
+    return {
+      wrote: true,
+      action: destExists ? "update" : "create",
+      hashAfter: srcHash
+    };
+  }
+  if (strategy === "merge-json-deep") {
+    const srcJson = parseJsonOrThrow(srcBuf.toString("utf8"), "src");
+    let merged = srcJson;
+    if (destExists) {
+      const destRaw = await readFile(dest, "utf8");
+      const destJson = parseJsonOrThrow(destRaw, "dest");
+      merged = deepMerge(destJson, srcJson);
+    }
+    const out = `${JSON.stringify(merged, null, 2)}
+`;
+    const outBuf = Buffer.from(out, "utf8");
+    const outHash = sha256(outBuf);
+    if (destExists) {
+      const destHash = await hashFile(dest);
+      if (destHash === outHash) {
+        return { wrote: false, action: "unchanged", hashAfter: destHash };
+      }
+    }
+    if (!dryRun) {
+      await ensureDir(dirname(dest));
+      await writeFile(dest, outBuf);
+    }
+    return {
+      wrote: true,
+      action: destExists ? "merge" : "create",
+      hashAfter: outHash
+    };
+  }
+  if (strategy === "append") {
+    const srcText = srcBuf.toString("utf8");
+    if (destExists) {
+      const destText = await readFile(dest, "utf8");
+      if (destText.includes(srcText)) {
+        return {
+          wrote: false,
+          action: "unchanged",
+          hashAfter: sha256(Buffer.from(destText, "utf8"))
+        };
+      }
+      const out = `${destText.endsWith("\n") ? destText : `${destText}
+`}${srcText}`;
+      const outBuf = Buffer.from(out, "utf8");
+      if (!dryRun) {
+        await ensureDir(dirname(dest));
+        await writeFile(dest, outBuf);
+      }
+      return { wrote: true, action: "append", hashAfter: sha256(outBuf) };
+    }
+    if (!dryRun) {
+      await ensureDir(dirname(dest));
+      await writeFile(dest, srcBuf);
+    }
+    return { wrote: true, action: "create", hashAfter: sha256(srcBuf) };
+  }
+  throw new Error(`Unknown strategy: ${strategy}`);
+}
+function deepMerge(target, source) {
+  if (target && source && typeof target === "object" && typeof source === "object" && !Array.isArray(target) && !Array.isArray(source)) {
+    const out = { ...target };
+    for (const [k, v] of Object.entries(source)) {
+      out[k] = deepMerge(target[k], v);
+    }
+    return out;
+  }
+  if (Array.isArray(target) && Array.isArray(source)) {
+    const seen = /* @__PURE__ */ new Set();
+    const out = [];
+    for (const item of [...target, ...source]) {
+      const key = JSON.stringify(item);
+      if (seen.has(key)) continue;
+      seen.add(key);
+      out.push(item);
+    }
+    return out;
+  }
+  return source ?? target;
+}
+function parseJsonOrThrow(raw, side) {
+  try {
+    return JSON.parse(raw);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    throw new Error(`merge-json-deep ${side} not valid JSON: ${msg}`);
+  }
+}
+function sha256(buf) {
+  return createHash("sha256").update(buf).digest("hex");
+}
+async function hashFile(path) {
+  const buf = await readFile(path);
+  return sha256(buf);
+}
+async function fileExists(path) {
+  try {
+    await stat(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function ensureDir(dir) {
+  try {
+    await stat(dir);
+  } catch {
+    await mkdir(dir, { recursive: true });
+  }
+}
+function ledgerPathFor2(profileName) {
+  return join(homedir(), ".agentproto", "profiles", `${profileName}.json`);
+}
+async function loadLedger2(path) {
+  try {
+    const raw = await readFile(path, "utf8");
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+async function saveLedger2(path, ledger) {
+  await ensureDir(dirname(path));
+  await writeFile(path, `${JSON.stringify(ledger, null, 2)}
+`);
+}
+async function readProfileAlias(profileName) {
+  const base = process.env["AGENTPROTO_HOME"] ?? join(homedir(), ".agentproto");
+  const path = join(base, "config.json");
+  try {
+    const raw = await readFile(path, "utf8");
+    const parsed = JSON.parse(raw);
+    const aliased = parsed.profileAliases?.[profileName];
+    return typeof aliased === "string" ? aliased : null;
+  } catch {
+    return null;
+  }
+}
 
 // src/commands/install.ts
 async function runInstall(args) {
+  const slugPeek = args.find((a) => !a.startsWith("-"));
+  if (slugPeek?.startsWith("runtime-profile/")) {
+    return runInstallProfile(
+      slugPeek,
+      args.filter((a) => a !== slugPeek)
+    );
+  }
   const { values, positionals } = parseArgs({
     args: [...args],
     allowPositionals: true,
@@ -776,7 +1086,7 @@ async function runDownloadInstaller(opts) {
     }
     if (extractCode !== 0) return extractCode;
     const srcBin = join(extractDir, opts.extractBin);
-    const binDir = process.env["AGENTPROTO_BIN_DIR"] ?? join(homedir2(), ".local", "bin");
+    const binDir = process.env["AGENTPROTO_BIN_DIR"] ?? join(homedir3(), ".local", "bin");
     await mkdir(binDir, { recursive: true });
     const destBin = join(binDir, opts.extractBin.split("/").pop());
     const cpCode = await spawnInherit("cp", ["-p", srcBin, destBin]);
@@ -802,19 +1112,19 @@ async function runDownloadInstaller(opts) {
     });
   }
 }
-function homedir2() {
+function homedir3() {
   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 +1132,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 +1329,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 +1591,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 +1617,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;
@@ -1503,12 +1941,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 +2418,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 +2444,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 +2463,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 +2480,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 +2606,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 +2724,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 +2750,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 +2770,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 +2807,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;
@@ -2421,22 +2903,49 @@ function registerSessionTools(server, opts) {
     }
   );
   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.",
+    "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.",
     {
-      onlyAlive: z.boolean().optional().describe("Filter to status running/starting/mounting only. Default false.")
+      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) => {
-      const all = registry.list();
-      const filtered = input2.onlyAlive ? all.filter(
-        (s) => s.status === "running" || s.status === "starting" || s.status === "mounting"
-      ) : all;
+      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: filtered }, null, 2)
-          }
+          { type: "text", text: JSON.stringify({ sessions: rows }, null, 2) }
+        ]
+      };
+    }
+  );
+  server.tool(
+    "list_agent_sessions",
+    "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 only. Default false.")
+    },
+    async (input2) => {
+      const all = registry.list();
+      const filtered = input2.onlyAlive ? all.filter((s) => s.status === "running" || s.status === "starting") : all;
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({ sessions: filtered }, null, 2)
+          }
         ]
       };
     }
@@ -2792,6 +3301,206 @@ function registerSessionTools(server, opts) {
       };
     }
   );
+  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).`
+      }
+    ],
+    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 {
+        }
+      }
+      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";
@@ -2964,6 +3673,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 +3702,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 +3841,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 +3925,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 +3972,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 +4185,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 +4389,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 +4411,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 +4434,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 +4557,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 +4637,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 +4663,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 +4762,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 +4891,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 +5007,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 +5069,8 @@ function createSessionsRegistry(opts) {
         desc,
         child: input2.child,
         recentLines: [],
+        recentBytes: [],
+        recentBytesSize: 0,
         emitter: new EventEmitter(),
         busy: false,
         textBuf: "",
@@ -3829,6 +5108,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 +5122,8 @@ function createSessionsRegistry(opts) {
         agentSession: input2.agentSession,
         adapterSlug: input2.adapterSlug,
         recentLines: [],
+        recentBytes: [],
+        recentBytesSize: 0,
         emitter: new EventEmitter(),
         busy: false,
         textBuf: "",
@@ -3860,14 +5148,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 +5274,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 +5344,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 +5363,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 +5643,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 +5718,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 +5743,7 @@ function quickTunnelProvider() {
           if (match) {
             settled = true;
             clearTimeout(timer);
-            resolve7(match[0]);
+            resolve8(match[0]);
           }
         };
         proc.stderr?.on("data", onData);
@@ -4249,15 +5792,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();
         });
       });
     }
@@ -4336,7 +5879,7 @@ var RemoteController = class {
     let bearerTokenHash = "";
     if (exposesGateway) {
       bearerToken = randomBytes(32).toString("base64url");
-      bearerTokenHash = sha256(bearerToken);
+      bearerTokenHash = sha2562(bearerToken);
     }
     const state = {
       provider: providerId,
@@ -4401,7 +5944,7 @@ function pickProvider(id) {
   const _exhaustive = id;
   throw new Error(`unknown remote provider: ${String(_exhaustive)}`);
 }
-function sha256(input2) {
+function sha2562(input2) {
   return createHash("sha256").update(input2).digest("hex");
 }
 function errToMessage(err) {
@@ -4494,7 +6037,7 @@ var WorkspacePathError = class extends Error {
 };
 function createWorkspaceFs(opts) {
   const root = resolve(opts.workspace);
-  function resolvePath32(path) {
+  function resolvePath42(path) {
     if (typeof path !== "string" || path.length === 0) {
       throw new WorkspacePathError("path must be a non-empty string");
     }
@@ -4514,18 +6057,18 @@ function createWorkspaceFs(opts) {
   }
   return {
     async readFile(path) {
-      const abs = resolvePath32(path);
+      const abs = resolvePath42(path);
       const buf = await readFile(abs);
       return buf.toString("utf8");
     },
     async writeFile(path, content) {
-      const abs = resolvePath32(path);
+      const abs = resolvePath42(path);
       await mkdir(dirname(abs), { recursive: true });
       await writeFile(abs, content);
     },
     async exists(path) {
       try {
-        const abs = resolvePath32(path);
+        const abs = resolvePath42(path);
         return existsSync(abs);
       } catch {
         return false;
@@ -4557,7 +6100,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 +6139,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 +6181,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 +6203,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 +6212,7 @@ async function createGateway(opts) {
     workspaceFs,
     registered,
     sessions,
+    token,
     async stop() {
       heartbeat.stop();
       sessions.shutdown();
@@ -4687,13 +6261,20 @@ 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()) {
+    const stat3 = await promises.stat(workspace);
+    if (!stat3.isDirectory()) {
       process.stderr.write(
         `agentproto serve: --workspace "${workspace}" is not a directory.
 `
@@ -4708,20 +6289,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 +6314,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 +6349,7 @@ async function runServe(args) {
       return null;
     }
   };
+  const spawnPty = await loadNodePtyFactory();
   let gateway;
   try {
     gateway = await createGateway({
@@ -4771,7 +6364,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 +6376,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 +6489,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 +6519,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 +6618,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