@primusclaw/connector 0.1.4 → 0.1.5

package/dist/cli.js

@@ -1,16 +1,297 @@
 #!/usr/bin/env node
 
 // src/commands.ts
-import fs16 from "node:fs";
-import os6 from "node:os";
-import path17 from "node:path";
+import fs18 from "node:fs";
+import os7 from "node:os";
+import path19 from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 import { parseArgs as parseArgs2 } from "node:util";
 
-// src/audit.ts
+// src/adapter-install.ts
+import { spawn } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 
+// src/util.ts
+import { createHash } from "node:crypto";
+var sleep = (ms, signal) => new Promise((resolve) => {
+  if (signal?.aborted) return resolve();
+  const t = setTimeout(done, ms);
+  function done() {
+    signal?.removeEventListener("abort", done);
+    clearTimeout(t);
+    resolve();
+  }
+  signal?.addEventListener("abort", done, { once: true });
+});
+var sha256 = (s) => createHash("sha256").update(s).digest("hex");
+var isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+var errMessage = (e) => e instanceof Error ? e.message : String(e);
+function truncateBytes(text, max) {
+  const bytes = Buffer.byteLength(text, "utf8");
+  if (bytes <= max) return { text, truncated: false, bytes };
+  let cut = Buffer.from(text, "utf8").subarray(0, max).toString("utf8");
+  if (cut.endsWith("\uFFFD")) cut = cut.slice(0, -1);
+  return { text: `${cut}
+[truncated, ${bytes} bytes in all]`, truncated: true, bytes };
+}
+function backoffMs(attempt, minMs, maxMs, random = Math.random) {
+  const raw = Math.min(maxMs, minMs * 2 ** Math.min(attempt, 30));
+  return Math.round(raw * (0.5 + random() / 2));
+}
+var stderrLogger = (quiet = false) => {
+  const w = (level) => (msg, extra) => {
+    if (quiet && level === "info") return;
+    process.stderr.write(`${(/* @__PURE__ */ new Date()).toISOString()} ${level} ${msg}${extra ? " " + JSON.stringify(extra) : ""}
+`);
+  };
+  return { info: w("info"), warn: w("warn"), error: w("error") };
+};
+var UrlError = class extends Error {
+};
+function secureUrl(raw, what) {
+  let u;
+  try {
+    u = new URL(raw);
+  } catch {
+    throw new UrlError(`${what} is not a valid URL: ${JSON.stringify(raw.slice(0, 80))}`);
+  }
+  const loopback = u.hostname === "localhost" || u.hostname === "[::1]" || /^127(\.\d{1,3}){3}$/.test(u.hostname);
+  if (u.protocol !== "https:" && !(u.protocol === "http:" && loopback)) {
+    throw new UrlError(`${what} must be an https:// URL (http:// is accepted only for localhost), got ${u.protocol}//${u.host}`);
+  }
+  return raw.replace(/\/+$/, "");
+}
+
+// src/adapter-install.ts
+var PINNED_RE = /^((?:@[a-z0-9][a-z0-9._~-]*\/)?[a-z0-9][a-z0-9._~-]*)@(\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?)$/;
+var INSTALL_WAIT_MS = 5 * 6e4;
+var INSTALL_TIMEOUT_MS = 15 * 6e4;
+var RETRY_AFTER_MS = 10 * 6e4;
+function pinnedPackage(cfg) {
+  const base = path.basename(cfg.command).replace(/\.(cmd|exe)$/i, "");
+  if (base !== "npx") return null;
+  const [flag, spec, ...rest] = cfg.args;
+  if (flag !== "-y" && flag !== "--yes" || typeof spec !== "string") return null;
+  const m = PINNED_RE.exec(spec);
+  if (!m) return null;
+  return { spec, name: m[1], version: m[2], rest };
+}
+function npmCommand(env) {
+  const exe = process.platform === "win32" ? "npm.cmd" : "npm";
+  for (const d of (env.PATH ?? "").split(path.delimiter)) if (d && isExecutable(path.join(d, exe))) return exe;
+  const sibling = path.join(path.dirname(process.execPath), exe);
+  return isExecutable(sibling) ? sibling : exe;
+}
+function isExecutable(f) {
+  try {
+    fs.accessSync(f, fs.constants.X_OK);
+    return fs.statSync(f).isFile();
+  } catch {
+    return false;
+  }
+}
+var npmInstaller = ({ dir, spec, env, timeoutMs }) => new Promise((resolve, reject) => {
+  const args = ["install", "--prefix", dir, "--no-save", "--no-package-lock", "--no-audit", "--no-fund", "--omit=dev", "--loglevel=error", spec];
+  let out = "";
+  const p = spawn(npmCommand(env), args, { cwd: dir, env, stdio: ["ignore", "pipe", "pipe"], shell: process.platform === "win32", timeout: timeoutMs, killSignal: "SIGKILL" });
+  const keep = (d) => {
+    out = (out + d.toString("utf8")).slice(-2e3);
+  };
+  p.stdout.on("data", keep);
+  p.stderr.on("data", keep);
+  p.once("error", (e) => reject(new Error(`could not run npm: ${errMessage(e)}`)));
+  p.once("exit", (code, signal) => {
+    if (code === 0) resolve();
+    else reject(new Error(`npm install ${spec} ${signal ? `was killed (${signal})` : `exited ${code}`}${out.trim() ? `: ${out.trim().split("\n").slice(-3).join(" | ")}` : ""}`));
+  });
+});
+function binOf(pkgDir, pkg) {
+  let raw;
+  try {
+    raw = JSON.parse(fs.readFileSync(path.join(pkgDir, "package.json"), "utf8"));
+  } catch {
+    return null;
+  }
+  if (!isObject(raw) || raw.version !== pkg.version) return null;
+  const short = pkg.name.split("/").pop();
+  let rel = null;
+  if (typeof raw.bin === "string") rel = raw.bin;
+  else if (isObject(raw.bin)) {
+    const entries = Object.entries(raw.bin);
+    rel = entries.length === 1 ? entries[0][1] : raw.bin[short];
+  }
+  if (typeof rel !== "string" || !rel) return null;
+  const file = path.resolve(pkgDir, rel);
+  if (!file.startsWith(pkgDir + path.sep)) return null;
+  try {
+    return fs.statSync(file).isFile() ? file : null;
+  } catch {
+    return null;
+  }
+}
+function runByNode(file) {
+  let head = "";
+  try {
+    const fd = fs.openSync(file, "r");
+    try {
+      const b = Buffer.alloc(128);
+      head = b.subarray(0, fs.readSync(fd, b, 0, 128, 0)).toString("utf8");
+    } finally {
+      fs.closeSync(fd);
+    }
+  } catch {
+    return false;
+  }
+  if (head.startsWith("#!")) return /\bnode\b/.test(head.split("\n")[0]);
+  return /\.(c|m)?js$/.test(file);
+}
+var AdapterStore = class {
+  constructor(dir, o) {
+    this.dir = dir;
+    this.o = o;
+    this.installer = o.installer ?? npmInstaller;
+  }
+  dir;
+  o;
+  pending = /* @__PURE__ */ new Map();
+  failedAt = /* @__PURE__ */ new Map();
+  installer;
+  /** Where a package lives once installed. */
+  finalDir(pkg) {
+    return path.join(this.dir, `${pkg.name.replace("/", "+")}@${pkg.version}`);
+  }
+  /** The installed bin script, or null when there is no complete install. */
+  installed(pkg) {
+    return binOf(path.join(this.finalDir(pkg), "node_modules", ...pkg.name.split("/")), pkg);
+  }
+  /** Whether an install of this package is running in this process. */
+  installing(pkg) {
+    return this.pending.has(pkg.spec);
+  }
+  /**
+   * Install `pkg` unless it is there. Never throws: null when it could not be installed (the reason goes to `say`).
+   * One install per package at a time in this process; another process installing the same one is harmless.
+   */
+  install(pkg, env, say = () => {
+  }) {
+    const have = this.installed(pkg);
+    if (have) return Promise.resolve(have);
+    const running = this.pending.get(pkg.spec);
+    if (running) return running;
+    const p = this.doInstall(pkg, env, say).finally(() => this.pending.delete(pkg.spec));
+    this.pending.set(pkg.spec, p);
+    return p;
+  }
+  async doInstall(pkg, env, say) {
+    const final = this.finalDir(pkg);
+    const started = Date.now();
+    let tmp = null;
+    try {
+      fs.mkdirSync(this.dir, { recursive: true, mode: 448 });
+      this.sweepAbandoned(pkg);
+      tmp = fs.mkdtempSync(path.join(this.dir, `.install-${pkg.name.replace("/", "+")}@${pkg.version}-`));
+      say(`installing ${pkg.spec} into ${final} (once; an adapter with its dependencies is a few hundred MB, so this can take a few minutes)`);
+      await this.installer({ dir: tmp, spec: pkg.spec, env, timeoutMs: INSTALL_TIMEOUT_MS });
+      if (!binOf(path.join(tmp, "node_modules", ...pkg.name.split("/")), pkg)) throw new Error(`npm reported success but ${pkg.spec} has no runnable bin in ${tmp}`);
+      if (!this.installed(pkg)) {
+        if (fs.existsSync(final)) fs.renameSync(final, `${final}.stale-${process.pid}-${Date.now()}`);
+        try {
+          fs.renameSync(tmp, final);
+          tmp = null;
+        } catch (e) {
+          if (!this.installed(pkg)) throw e;
+        }
+      }
+      for (const f of fs.readdirSync(this.dir)) if (f.startsWith(`${path.basename(final)}.stale-`)) fs.rmSync(path.join(this.dir, f), { recursive: true, force: true });
+      const bin = this.installed(pkg);
+      if (!bin) throw new Error(`${pkg.spec} is not runnable after the install`);
+      this.failedAt.delete(pkg.spec);
+      say(`installed ${pkg.spec} in ${Math.round((Date.now() - started) / 1e3)} s`);
+      return bin;
+    } catch (e) {
+      this.failedAt.set(pkg.spec, this.now());
+      say(`could not install ${pkg.spec}: ${errMessage(e)}; sessions start it through npx instead (slower, and needs the registry each time)`);
+      return null;
+    } finally {
+      if (tmp) fs.rmSync(tmp, { recursive: true, force: true });
+    }
+  }
+  /** Install directories a killed connector left behind (older than any install can take). */
+  sweepAbandoned(pkg) {
+    const prefix = `.install-${pkg.name.replace("/", "+")}@${pkg.version}-`;
+    for (const f of fs.readdirSync(this.dir)) {
+      if (!f.startsWith(prefix)) continue;
+      const p = path.join(this.dir, f);
+      try {
+        if (Date.now() - fs.statSync(p).mtimeMs > 2 * INSTALL_TIMEOUT_MS) fs.rmSync(p, { recursive: true, force: true });
+      } catch {
+      }
+    }
+  }
+  now() {
+    return (this.o.now ?? Date.now)();
+  }
+  /**
+   * How to start an agent's adapter for a session in `cwd`. A pinned package that is installed runs from here; one
+   * whose install is running is waited for (at most `waitMs`); otherwise npx runs as configured, in this directory.
+   */
+  async launch(cfg, cwd, env) {
+    const pkg = pinnedPackage(cfg);
+    if (!pkg) return { command: cfg.command, args: cfg.args, cwd, installed: false };
+    let bin = this.installed(pkg);
+    if (!bin) {
+      const failed = this.failedAt.get(pkg.spec);
+      if (failed === void 0) {
+        const job = this.o.autoInstall ? this.install(pkg, env) : this.pending.get(pkg.spec);
+        if (job) bin = await raceTimeout(job, this.o.waitMs ?? INSTALL_WAIT_MS);
+      } else if (this.o.autoInstall && !this.installing(pkg) && this.now() - failed >= RETRY_AFTER_MS) {
+        void this.install(pkg, env);
+      }
+    }
+    if (bin) return runByNode(bin) ? { command: process.execPath, args: [bin, ...pkg.rest], cwd, installed: true } : { command: bin, args: pkg.rest, cwd, installed: true };
+    fs.mkdirSync(this.dir, { recursive: true, mode: 448 });
+    return { command: cfg.command, args: cfg.args, cwd: this.dir, installed: false };
+  }
+};
+function raceTimeout(p, ms) {
+  let timer;
+  const t = new Promise((resolve) => {
+    timer = setTimeout(() => resolve(null), ms);
+    timer.unref?.();
+  });
+  return Promise.race([p, t]).finally(() => clearTimeout(timer));
+}
+var store = null;
+function useAdapterStore(s) {
+  store = s;
+}
+function adapterStore() {
+  return store;
+}
+function pinnedOf(agents, base = process.env) {
+  const seen = /* @__PURE__ */ new Map();
+  for (const a of agents) {
+    const pkg = pinnedPackage(a);
+    if (pkg && !seen.has(pkg.spec)) seen.set(pkg.spec, { pkg, env: { ...base, ...a.env } });
+  }
+  return [...seen.values()];
+}
+async function installAll(s, agents, base, say) {
+  for (const { pkg, env } of pinnedOf(agents, base)) {
+    if (s.installed(pkg)) {
+      say(`${pkg.spec} is installed`);
+      continue;
+    }
+    await s.install(pkg, env, say);
+  }
+}
+var adaptersDir = (stateDir) => path.join(stateDir, "adapters");
+
+// src/audit.ts
+import fs2 from "node:fs";
+import path2 from "node:path";
+
 // src/redact.ts
 var MASK = "[hidden]";
 var B64 = "[A-Za-z0-9+/=_-]";
@@ -58,12 +339,12 @@ function redactDeep(value) {
 
 // src/audit.ts
 function fileAudit(file, now = Date.now) {
-  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 448 });
+  fs2.mkdirSync(path2.dirname(file), { recursive: true, mode: 448 });
   return {
     record(kind, detail = {}) {
       const line = JSON.stringify({ ts: new Date(now()).toISOString(), ...redactDeep(detail), kind });
       try {
-        fs.appendFileSync(file, line + "\n", { mode: 384 });
+        fs2.appendFileSync(file, line + "\n", { mode: 384 });
       } catch {
         process.stderr.write(`audit write failed: ${kind}
 `);
@@ -74,65 +355,12 @@ function fileAudit(file, now = Date.now) {
 
 // src/children.ts
 import { execFileSync } from "node:child_process";
-import fs2 from "node:fs";
-import path2 from "node:path";
-
-// src/util.ts
-import { createHash } from "node:crypto";
-var sleep = (ms, signal) => new Promise((resolve) => {
-  if (signal?.aborted) return resolve();
-  const t = setTimeout(done, ms);
-  function done() {
-    signal?.removeEventListener("abort", done);
-    clearTimeout(t);
-    resolve();
-  }
-  signal?.addEventListener("abort", done, { once: true });
-});
-var sha256 = (s) => createHash("sha256").update(s).digest("hex");
-var isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
-var errMessage = (e) => e instanceof Error ? e.message : String(e);
-function truncateBytes(text, max) {
-  const bytes = Buffer.byteLength(text, "utf8");
-  if (bytes <= max) return { text, truncated: false, bytes };
-  let cut = Buffer.from(text, "utf8").subarray(0, max).toString("utf8");
-  if (cut.endsWith("\uFFFD")) cut = cut.slice(0, -1);
-  return { text: `${cut}
-[truncated, ${bytes} bytes in all]`, truncated: true, bytes };
-}
-function backoffMs(attempt, minMs, maxMs, random = Math.random) {
-  const raw = Math.min(maxMs, minMs * 2 ** Math.min(attempt, 30));
-  return Math.round(raw * (0.5 + random() / 2));
-}
-var stderrLogger = (quiet = false) => {
-  const w = (level) => (msg, extra) => {
-    if (quiet && level === "info") return;
-    process.stderr.write(`${(/* @__PURE__ */ new Date()).toISOString()} ${level} ${msg}${extra ? " " + JSON.stringify(extra) : ""}
-`);
-  };
-  return { info: w("info"), warn: w("warn"), error: w("error") };
-};
-var UrlError = class extends Error {
-};
-function secureUrl(raw, what) {
-  let u;
-  try {
-    u = new URL(raw);
-  } catch {
-    throw new UrlError(`${what} is not a valid URL: ${JSON.stringify(raw.slice(0, 80))}`);
-  }
-  const loopback = u.hostname === "localhost" || u.hostname === "[::1]" || /^127(\.\d{1,3}){3}$/.test(u.hostname);
-  if (u.protocol !== "https:" && !(u.protocol === "http:" && loopback)) {
-    throw new UrlError(`${what} must be an https:// URL (http:// is accepted only for localhost), got ${u.protocol}//${u.host}`);
-  }
-  return raw.replace(/\/+$/, "");
-}
-
-// src/children.ts
+import fs3 from "node:fs";
+import path3 from "node:path";
 function processStart(pid) {
   try {
     if (process.platform === "linux") {
-      const stat = fs2.readFileSync(`/proc/${pid}/stat`, "utf8");
+      const stat = fs3.readFileSync(`/proc/${pid}/stat`, "utf8");
       const rest = stat.slice(stat.lastIndexOf(")") + 2).split(" ");
       return rest[19] ?? null;
     }
@@ -157,10 +385,10 @@ var ChildRegistry = class {
   file;
   recs = /* @__PURE__ */ new Map();
   save() {
-    fs2.mkdirSync(path2.dirname(this.file), { recursive: true, mode: 448 });
+    fs3.mkdirSync(path3.dirname(this.file), { recursive: true, mode: 448 });
     const tmp = `${this.file}.${process.pid}.tmp`;
-    fs2.writeFileSync(tmp, JSON.stringify([...this.recs.values()]), { mode: 384 });
-    fs2.renameSync(tmp, this.file);
+    fs3.writeFileSync(tmp, JSON.stringify([...this.recs.values()]), { mode: 384 });
+    fs3.renameSync(tmp, this.file);
   }
   add(rec) {
     const full = { ...rec, start: rec.start ?? processStart(rec.pid) ?? "", started_at: (/* @__PURE__ */ new Date()).toISOString() };
@@ -251,7 +479,7 @@ var ChildRegistry = class {
 };
 function readRecords(file) {
   try {
-    const raw = JSON.parse(fs2.readFileSync(file, "utf8"));
+    const raw = JSON.parse(fs3.readFileSync(file, "utf8"));
     return Array.isArray(raw) ? raw.filter((r) => Number.isInteger(r?.pid) && Number.isInteger(r?.pgid) && r.pgid > 1) : [];
   } catch {
     return [];
@@ -335,11 +563,11 @@ var RevokedError = class extends Error {
   }
 };
 var HttpError = class extends Error {
-  constructor(status2, code, path18) {
-    super(`${path18} answered ${status2} ${code}`);
+  constructor(status2, code, path20) {
+    super(`${path20} answered ${status2} ${code}`);
     this.status = status2;
     this.code = code;
-    this.path = path18;
+    this.path = path20;
   }
   status;
   code;
@@ -363,8 +591,8 @@ var ClawClient = class {
       ...extra
     };
   }
-  async send(method, path18, body, signal) {
-    const url = this.o.server + path18;
+  async send(method, path20, body, signal) {
+    const url = this.o.server + path20;
     for (let attempt = 0; ; attempt++) {
       const headers = await this.headers(body === void 0 ? {} : { "content-type": "application/json" });
       let res;
@@ -376,7 +604,7 @@ var ClawClient = class {
           signal: signal ?? AbortSignal.timeout(this.o.requestTimeoutMs ?? 2e4)
         });
       } catch (e) {
-        throw new TransportError(`${method} ${path18}: ${errMessage(e)}`);
+        throw new TransportError(`${method} ${path20}: ${errMessage(e)}`);
       }
       if (res.status !== 401) return res;
       const err = await errorCode(res);
@@ -385,12 +613,12 @@ var ClawClient = class {
         this.o.tokens.invalidate();
         continue;
       }
-      throw new HttpError(401, err, path18);
+      throw new HttpError(401, err, path20);
     }
   }
-  async json(method, path18, body) {
-    const res = await this.send(method, path18, body);
-    if (!res.ok) throw new HttpError(res.status, await errorCode(res), path18);
+  async json(method, path20, body) {
+    const res = await this.send(method, path20, body);
+    if (!res.ok) throw new HttpError(res.status, await errorCode(res), path20);
     const parsed = await res.json().catch(() => null);
     return isObject(parsed) && isObject(parsed.data) ? parsed.data : {};
   }
@@ -439,21 +667,21 @@ var ClawClient = class {
     };
     try {
       arm();
-      const path18 = `/v1/remote-agents/connectors/${cid}/commands`;
+      const path20 = `/v1/remote-agents/connectors/${cid}/commands`;
       const headers = await this.headers({ accept: "text/event-stream", ...opts.lastEventId ? { "last-event-id": String(opts.lastEventId) } : {} });
       let res;
       try {
-        res = await this.f(this.o.server + path18, { headers, signal: stop.signal });
+        res = await this.f(this.o.server + path20, { headers, signal: stop.signal });
       } catch (e) {
-        throw new TransportError(timedOut ? `no response for ${opts.watchdogMs} ms` : `GET ${path18}: ${errMessage(e)}`);
+        throw new TransportError(timedOut ? `no response for ${opts.watchdogMs} ms` : `GET ${path20}: ${errMessage(e)}`);
       }
       if (res.status === 401) {
         const err = await errorCode(res);
         if (err === "revoked") throw new RevokedError();
         this.o.tokens.invalidate();
-        throw new HttpError(401, err, path18);
+        throw new HttpError(401, err, path20);
       }
-      if (!res.ok || !res.body) throw new HttpError(res.status, await errorCode(res), path18);
+      if (!res.ok || !res.body) throw new HttpError(res.status, await errorCode(res), path20);
       try {
         for await (const frame of readSse(res.body, arm)) yield frame;
       } catch (e) {
@@ -473,33 +701,33 @@ async function errorCode(res) {
 }
 
 // src/config.ts
-import fs4 from "node:fs";
+import fs5 from "node:fs";
 import os from "node:os";
-import path4 from "node:path";
+import path5 from "node:path";
 import { parse as parseToml } from "smol-toml";
 
 // src/roots.ts
-import fs3 from "node:fs";
-import path3 from "node:path";
+import fs4 from "node:fs";
+import path4 from "node:path";
 function realRoot(root) {
   try {
-    return fs3.realpathSync.native(root);
+    return fs4.realpathSync.native(root);
   } catch {
     return null;
   }
 }
-var inside = (child, root) => child === root || child.startsWith(root.endsWith(path3.sep) ? root : root + path3.sep);
+var inside = (child, root) => child === root || child.startsWith(root.endsWith(path4.sep) ? root : root + path4.sep);
 function checkCwd(cwd, roots) {
   if (typeof cwd !== "string" || cwd === "" || cwd.includes("\0")) return { ok: false, reason: "invalid_cwd" };
-  if (!path3.isAbsolute(cwd)) return { ok: false, reason: "cwd_not_absolute" };
+  if (!path4.isAbsolute(cwd)) return { ok: false, reason: "cwd_not_absolute" };
   let real;
   try {
-    real = fs3.realpathSync.native(cwd);
+    real = fs4.realpathSync.native(cwd);
   } catch {
     return { ok: false, reason: "cwd_not_found" };
   }
   try {
-    if (!fs3.statSync(real).isDirectory()) return { ok: false, reason: "cwd_not_directory" };
+    if (!fs4.statSync(real).isDirectory()) return { ok: false, reason: "cwd_not_directory" };
   } catch {
     return { ok: false, reason: "cwd_not_found" };
   }
@@ -510,19 +738,19 @@ function checkCwd(cwd, roots) {
   return { ok: false, reason: "cwd_outside_roots" };
 }
 function relativeInside(p, cwd) {
-  const abs = path3.resolve(cwd, p);
+  const abs = path4.resolve(cwd, p);
   let real;
   try {
-    real = fs3.realpathSync.native(abs);
+    real = fs4.realpathSync.native(abs);
   } catch {
     try {
-      real = path3.join(fs3.realpathSync.native(path3.dirname(abs)), path3.basename(abs));
+      real = path4.join(fs4.realpathSync.native(path4.dirname(abs)), path4.basename(abs));
     } catch {
       return null;
     }
   }
   if (!inside(real, cwd)) return null;
-  return path3.relative(cwd, real).split(path3.sep).join("/");
+  return path4.relative(cwd, real).split(path4.sep).join("/");
 }
 
 // src/config.ts
@@ -585,7 +813,7 @@ var strList = (v, what, problems) => {
   }
   return v;
 };
-var expandHome = (p) => p === "~" ? os.homedir() : p.startsWith("~/") ? path4.join(os.homedir(), p.slice(2)) : p;
+var expandHome = (p) => p === "~" ? os.homedir() : p.startsWith("~/") ? path5.join(os.homedir(), p.slice(2)) : p;
 function parseConfig(text, defaults = {}) {
   const problems = [];
   let doc;
@@ -652,10 +880,10 @@ function parseConfig(text, defaults = {}) {
       } else asking.add(askMode);
     }
     if (asking.has(askMode) && !safeModes.includes(askMode)) safeModes.push(askMode);
-    const roots = strList(raw.roots, `${label}.roots`, problems).map((r) => path4.resolve(expandHome(r)));
+    const roots = strList(raw.roots, `${label}.roots`, problems).map((r) => path5.resolve(expandHome(r)));
     if (roots.length === 0) problems.push(`${label}: roots is required (an agent with no allowed directory is never offered)`);
     for (const r of roots) {
-      if (r === path4.parse(r).root) problems.push(`${label}: a root may not be the filesystem root`);
+      if (r === path5.parse(r).root) problems.push(`${label}: a root may not be the filesystem root`);
       else if (!realRoot(r)) problems.push(`${label}: root ${r} does not exist`);
     }
     const env = {};
@@ -696,9 +924,50 @@ function parseConfig(text, defaults = {}) {
       attach
     });
   });
+  if (Array.isArray(rawAgents)) agents.push(...existingSessionAgents(rawAgents, agents, problems));
   if (problems.length) throw new ConfigError(problems);
   return { server, identityUrl, name, allowUnsafeModes, dropMessagePatterns, agents };
 }
+var EXISTING_SESSIONS_SUFFIX = "-sessions";
+function existingSessionAgents(rawAgents, agents, problems) {
+  const out = [];
+  const configDir = (a) => path5.resolve(expandHome(a.env.CLAUDE_CONFIG_DIR ?? process.env.CLAUDE_CONFIG_DIR ?? path5.join(os.homedir(), ".claude")));
+  const ids = new Set(agents.map((a) => a.id));
+  for (const raw of rawAgents) {
+    if (!isObject(raw) || typeof raw.id !== "string") continue;
+    const flag = raw.existing_sessions;
+    if (flag !== void 0 && typeof flag !== "boolean") {
+      problems.push(`agent ${raw.id}: existing_sessions must be true or false`);
+      continue;
+    }
+    if (flag !== void 0 && raw.preset !== "claude") {
+      problems.push(`agent ${raw.id}: existing_sessions only applies to an agent made from the claude preset`);
+      continue;
+    }
+    if (raw.preset !== "claude" || flag === false) continue;
+    const src = agents.find((a) => a.id === raw.id);
+    if (!src) continue;
+    if ([...agents, ...out].some((a) => a.attach && configDir(a) === configDir(src))) continue;
+    const id = `${src.id.slice(0, 64 - EXISTING_SESSIONS_SUFFIX.length)}${EXISTING_SESSIONS_SUFFIX}`;
+    if (ids.has(id)) continue;
+    ids.add(id);
+    const name = src.name === PRESETS.claude.name ? PRESETS["claude-attach"].name : `${src.name} (existing sessions)`.slice(0, 128);
+    out.push({
+      ...src,
+      id,
+      kind: PRESETS["claude-attach"].kind,
+      name,
+      args: [...src.args],
+      roots: [...src.roots],
+      env: { ...src.env },
+      safeModes: [...src.safeModes],
+      askingModes: [...src.askingModes],
+      autoAllow: [...src.autoAllow],
+      attach: { cli: "claude" }
+    });
+  }
+  return out;
+}
 function parseAutoAllow(raw, at, problems) {
   if (raw === void 0) return [];
   if (!Array.isArray(raw)) {
@@ -710,7 +979,7 @@ function parseAutoAllow(raw, at, problems) {
     if (!isObject(r) || typeof r.kind !== "string" || typeof r.path_glob !== "string" || !r.kind || !r.path_glob) {
       return void problems.push(`${at}[${i}] needs a kind and a path_glob`);
     }
-    if (path4.isAbsolute(r.path_glob) || r.path_glob.split("/").includes("..")) {
+    if (path5.isAbsolute(r.path_glob) || r.path_glob.split("/").includes("..")) {
       return void problems.push(`${at}[${i}].path_glob must be relative to the working directory and may not contain ..`);
     }
     rules.push({ kind: r.kind, pathGlob: r.path_glob });
@@ -720,7 +989,7 @@ function parseAutoAllow(raw, at, problems) {
 function loadConfig(file, defaults = {}) {
   let text;
   try {
-    text = fs4.readFileSync(file, "utf8");
+    text = fs5.readFileSync(file, "utf8");
   } catch (e) {
     if (e.code === "ENOENT") throw new ConfigError([`${file} does not exist; run "claw-connector init" to create one`]);
     throw e;
@@ -767,8 +1036,8 @@ ${SAMPLE_AGENTS.map(agent).join("\n\n")}
 var SAMPLE_CONFIG = sampleConfig();
 
 // src/credentials.ts
-import fs5 from "node:fs";
-import path5 from "node:path";
+import fs6 from "node:fs";
+import path6 from "node:path";
 var DEFAULT_CLIENT_ID = "claw-connector";
 var CONNECTOR_SCOPE = "claw.connector";
 var CredentialsError = class extends Error {
@@ -783,20 +1052,20 @@ var TransientAuthError = class extends Error {
 function loadCredentials(file) {
   let fd;
   try {
-    fd = fs5.openSync(file, "r");
+    fd = fs6.openSync(file, "r");
   } catch (e) {
     if (e.code === "ENOENT") return null;
     throw e;
   }
   let text;
   try {
-    const st = fs5.fstatSync(fd);
+    const st = fs6.fstatSync(fd);
     if (process.platform !== "win32" && (st.mode & 63) !== 0) {
       throw new CredentialsError(`${file} is readable by other users (mode ${(st.mode & 511).toString(8)}); run: chmod 600 ${file}`);
     }
-    text = fs5.readFileSync(fd, "utf8");
+    text = fs6.readFileSync(fd, "utf8");
   } finally {
-    fs5.closeSync(fd);
+    fs6.closeSync(fd);
   }
   let raw;
   try {
@@ -810,11 +1079,11 @@ function loadCredentials(file) {
   return raw;
 }
 function saveCredentials(file, creds) {
-  fs5.mkdirSync(path5.dirname(file), { recursive: true, mode: 448 });
+  fs6.mkdirSync(path6.dirname(file), { recursive: true, mode: 448 });
   const tmp = `${file}.${process.pid}.tmp`;
-  fs5.writeFileSync(tmp, JSON.stringify(creds, null, 2) + "\n", { mode: 384 });
-  fs5.chmodSync(tmp, 384);
-  fs5.renameSync(tmp, file);
+  fs6.writeFileSync(tmp, JSON.stringify(creds, null, 2) + "\n", { mode: 384 });
+  fs6.chmodSync(tmp, 384);
+  fs6.renameSync(tmp, file);
 }
 var KeyTokenProvider = class {
   constructor(key) {
@@ -1004,10 +1273,9 @@ async function deviceLogin(o) {
 }
 
 // src/claude-mode.ts
-import fs6 from "node:fs";
+import fs7 from "node:fs";
 import os2 from "node:os";
-import path6 from "node:path";
-var isClaude = (a) => !a.attach && [a.command, ...a.args].some((s) => s.includes("claude-agent-acp"));
+import path7 from "node:path";
 function managedSettingsFile(platform = process.platform) {
   if (platform === "darwin") return "/Library/Application Support/ClaudeCode/managed-settings.json";
   if (platform === "win32") return "C:\\Program Files\\ClaudeCode\\managed-settings.json";
@@ -1016,7 +1284,7 @@ function managedSettingsFile(platform = process.platform) {
 function readSettings(file, unreadable) {
   let text;
   try {
-    text = fs6.readFileSync(file, "utf8");
+    text = fs7.readFileSync(file, "utf8");
   } catch (e) {
     if (e.code !== "ENOENT") unreadable.push(file);
     return null;
@@ -1029,67 +1297,63 @@ function readSettings(file, unreadable) {
     return null;
   }
 }
-function claudeStartMode(o) {
-  const home = o.env.HOME?.trim() || os2.homedir();
-  const configDir = o.env.CLAUDE_CONFIG_DIR?.trim() || path6.join(home, ".claude");
-  const files = [
-    ["user", path6.join(configDir, "settings.json")],
-    ...o.cwd === null ? [] : [
-      ["project", path6.join(o.cwd, ".claude", "settings.json")],
-      ["local", path6.join(o.cwd, ".claude", "settings.local.json")]
-    ],
-    ["managed", o.managedFile ?? managedSettingsFile()]
-  ];
-  const unreadable = [];
-  let raw;
-  let from = null;
-  let disable;
-  for (const [source, file] of files) {
-    const s = readSettings(file, unreadable);
-    const perms = s && isObject(s.permissions) ? s.permissions : null;
-    if (!perms) continue;
-    if (perms.defaultMode !== void 0) {
-      raw = perms.defaultMode;
-      from = [source, file];
-    }
-    if (perms.disableBypassPermissionsMode !== void 0) disable = perms.disableBypassPermissionsMode;
-  }
-  let bypass = raw === "bypassPermissions" && from !== null && from[0] !== "project" && from[0] !== "local";
-  if (bypass) {
-    const euid = o.euid === void 0 ? process.geteuid?.() ?? null : o.euid;
-    if (euid === 0 && !o.env.IS_SANDBOX || disable === "disable") bypass = false;
-  }
-  return { bypass, file: bypass ? from[1] : null, unreadable };
-}
-function noAskWarnings(agents, env, opts = {}) {
+var runsClaudeAdapter = (a) => [a.command, ...a.args].some((s) => s.includes("claude-agent-acp"));
+var currentEuid = (euid) => euid === void 0 ? process.geteuid?.() ?? null : euid;
+function applyRootSandbox(agents, env, opts = {}) {
+  if (currentEuid(opts.euid) !== 0 || env.IS_SANDBOX) return [];
+  const out = [];
+  for (const a of agents) {
+    if (!runsClaudeAdapter(a) || !a.allowUnsafeModes || Object.hasOwn(a.env, "IS_SANDBOX")) continue;
+    a.env = { ...a.env, IS_SANDBOX: "1" };
+    out.push(`${a.id}: running as root, where Claude Code offers bypassPermissions only with IS_SANDBOX set; set IS_SANDBOX=1 for this agent's adapter because it runs without per-step approval`);
+  }
+  return out;
+}
+function bypassUnavailableWarnings(agents, env, opts = {}) {
   const out = [];
+  const euid = currentEuid(opts.euid);
   for (const a of agents) {
-    if (!isClaude(a) || a.allowUnsafeModes) continue;
-    const r = claudeStartMode({ env: { ...env, ...a.env }, cwd: null, ...opts });
-    if (r.bypass) {
-      out.push(`${a.id}: sessions will be refused (mode_not_enforced): Claude defaults to bypassPermissions here (permissions.defaultMode in ${r.file}); set approval = "never" on this agent or change defaultMode`);
+    if (!runsClaudeAdapter(a) || !a.allowUnsafeModes || a.askMode !== "bypassPermissions") continue;
+    const merged = { ...env, ...a.env };
+    if (euid === 0 && !merged.IS_SANDBOX) {
+      out.push(`${a.id}: sessions will be refused (mode_unavailable): Claude Code offers bypassPermissions to root only with IS_SANDBOX set, and this agent's env sets IS_SANDBOX to an empty value; remove IS_SANDBOX from its env, or set approval = "ask"`);
+      continue;
+    }
+    const home = merged.HOME?.trim() || os2.homedir();
+    const configDir = merged.CLAUDE_CONFIG_DIR?.trim() || path7.join(home, ".claude");
+    const unreadable = [];
+    for (const file of [path7.join(configDir, "settings.json"), opts.managedFile ?? managedSettingsFile()]) {
+      const s = readSettings(file, unreadable);
+      const perms = s && isObject(s.permissions) ? s.permissions : null;
+      if (perms?.disableBypassPermissionsMode === "disable") {
+        out.push(`${a.id}: sessions will be refused (mode_unavailable): permissions.disableBypassPermissionsMode is "disable" in ${file}, so Claude Code does not offer bypassPermissions; remove that setting, or set approval = "ask" on this agent`);
+        break;
+      }
     }
-    for (const f of r.unreadable) out.push(`${a.id}: cannot tell whether Claude defaults to bypassPermissions: ${f} is not readable JSON`);
   }
   return out;
 }
+function claudeSessionMeta(a) {
+  if (!runsClaudeAdapter(a) || a.attach || a.allowUnsafeModes) return {};
+  return { _meta: { claudeCode: { options: { allowDangerouslySkipPermissions: false } } } };
+}
 
 // src/hooks.ts
-import fs8 from "node:fs";
-import path8 from "node:path";
+import fs9 from "node:fs";
+import path9 from "node:path";
 
 // src/terminals.ts
-import fs7 from "node:fs";
-import path7 from "node:path";
+import fs8 from "node:fs";
+import path8 from "node:path";
 var SESSION_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 var TERMINALS_DIR = "claw-connector-terminals";
-var terminalsDir = (configDir) => path7.join(configDir, TERMINALS_DIR);
+var terminalsDir = (configDir) => path8.join(configDir, TERMINALS_DIR);
 var UNREADABLE_GRACE_MS = 6e4;
 var MAX_STDIN = 1 << 20;
 function localPidDomain() {
   if (process.platform !== "linux") return null;
   try {
-    return `linux:${fs7.readFileSync("/etc/machine-id", "utf8").trim()}:${fs7.readlinkSync("/proc/self/ns/pid")}`;
+    return `linux:${fs8.readFileSync("/etc/machine-id", "utf8").trim()}:${fs8.readlinkSync("/proc/self/ns/pid")}`;
   } catch {
     return null;
   }
@@ -1120,7 +1384,7 @@ function readTerminals(configDir, localDomain, now = Date.now()) {
   const dir = terminalsDir(configDir);
   let names;
   try {
-    names = fs7.readdirSync(dir);
+    names = fs8.readdirSync(dir);
   } catch (e) {
     if (e.code === "ENOENT") return [];
     throw e;
@@ -1128,15 +1392,15 @@ function readTerminals(configDir, localDomain, now = Date.now()) {
   const out = [];
   for (const name of names) {
     if (!name.endsWith(".json")) continue;
-    const file = path7.join(dir, name);
+    const file = path8.join(dir, name);
     let doc;
     try {
-      doc = JSON.parse(fs7.readFileSync(file, "utf8"));
+      doc = JSON.parse(fs8.readFileSync(file, "utf8"));
     } catch (e) {
       if (e.code === "ENOENT") continue;
       let age = Infinity;
       try {
-        age = now - fs7.statSync(file).mtimeMs;
+        age = now - fs8.statSync(file).mtimeMs;
       } catch {
       }
       if (age < UNREADABLE_GRACE_MS) throw new Error(`${file} is unreadable (${e.message.split("\n")[0]})`);
@@ -1163,19 +1427,19 @@ var shellQuote = (s) => `'${s.replace(/'/g, `'\\''`)}'`;
 function hookCommand(node, script, arg, configDir) {
   return `${shellQuote(node)} ${shellQuote(script)} ${arg} --dir ${shellQuote(configDir)} ${MANAGED_MARK}`;
 }
-var settingsFile = (configDir) => path8.join(configDir, "settings.json");
+var settingsFile = (configDir) => path9.join(configDir, "settings.json");
 var isObject3 = (x) => typeof x === "object" && x !== null && !Array.isArray(x);
 var isOurs = (h) => isObject3(h) && h.type === "command" && typeof h.command === "string" && h.command.endsWith(` ${MANAGED_MARK}`) && OURS_RE.test(h.command);
 function load(configDir) {
   const given = settingsFile(configDir);
   let file = given;
   try {
-    file = fs8.realpathSync(given);
+    file = fs9.realpathSync(given);
   } catch {
   }
   let text;
   try {
-    text = fs8.readFileSync(file, "utf8");
+    text = fs9.readFileSync(file, "utf8");
   } catch (e) {
     if (e.code === "ENOENT") return { doc: {}, text: null, file };
     throw new HooksError(`cannot read ${given}: ${e.message}`);
@@ -1193,18 +1457,18 @@ function load(configDir) {
 function save(l, doc) {
   const indent = l.text?.match(/^([ \t]+)"/m)?.[1] ?? "  ";
   const body = JSON.stringify(doc, null, indent) + "\n";
-  fs8.mkdirSync(path8.dirname(l.file), { recursive: true, mode: 448 });
+  fs9.mkdirSync(path9.dirname(l.file), { recursive: true, mode: 448 });
   let mode = 384;
   try {
-    mode = fs8.statSync(l.file).mode & 511;
+    mode = fs9.statSync(l.file).mode & 511;
   } catch {
   }
   const tmp = `${l.file}.claw-connector.${process.pid}.tmp`;
-  fs8.writeFileSync(tmp, body, { mode });
+  fs9.writeFileSync(tmp, body, { mode });
   try {
-    fs8.renameSync(tmp, l.file);
+    fs9.renameSync(tmp, l.file);
   } catch (e) {
-    fs8.rmSync(tmp, { force: true });
+    fs9.rmSync(tmp, { force: true });
     throw e;
   }
 }
@@ -1284,7 +1548,7 @@ function uninstallHooks(configDir) {
     if (touchedAny && Object.keys(hooks).length === 0) delete doc.hooks;
   }
   if (touchedAny) save(l, doc);
-  fs8.rmSync(terminalsDir(configDir), { recursive: true, force: true });
+  fs9.rmSync(terminalsDir(configDir), { recursive: true, force: true });
   return { changed: touchedAny, file: l.file };
 }
 function hooksStatus(configDir) {
@@ -1307,7 +1571,7 @@ function hooksStatus(configDir) {
       const m = /^'((?:[^']|'\\'')*)' '((?:[^']|'\\'')*)' /.exec(String(x.command));
       if (!m) continue;
       for (const f of [m[1], m[2]].map((s) => s.replace(/'\\''/g, "'"))) {
-        if (!fs8.existsSync(f)) {
+        if (!fs9.existsSync(f)) {
           healthy = false;
           problem ??= `${f} (named by the ${h.event} hook) does not exist; run: claw-connector hooks install`;
         }
@@ -1318,19 +1582,20 @@ function hooksStatus(configDir) {
 }
 
 // src/connector.ts
-import fs14 from "node:fs";
+import fs15 from "node:fs";
 import { randomUUID as randomUUID2 } from "node:crypto";
 
 // src/attach.ts
 import { execFile, execFileSync as execFileSync2 } from "node:child_process";
-import fs10 from "node:fs";
+import fs11 from "node:fs";
 import os3 from "node:os";
-import path10 from "node:path";
+import path11 from "node:path";
+import { StringDecoder } from "node:string_decoder";
 
 // src/adapter.ts
-import { spawn } from "node:child_process";
-import fs9 from "node:fs";
-import path9 from "node:path";
+import { spawn as spawn2 } from "node:child_process";
+import fs10 from "node:fs";
+import path10 from "node:path";
 import { Readable, Writable } from "node:stream";
 import * as acp from "@agentclientprotocol/sdk";
 var AdapterProcess = class _AdapterProcess {
@@ -1346,20 +1611,22 @@ var AdapterProcess = class _AdapterProcess {
   exited = false;
   conn;
   static async start(o) {
-    fs9.mkdirSync(path9.dirname(o.logFile), { recursive: true, mode: 448 });
-    const log = fs9.openSync(o.logFile, "a", 384);
-    const child = spawn(o.cfg.command, o.cfg.args, {
-      cwd: o.cwd,
-      env: { ...process.env, ...o.cfg.env },
+    fs10.mkdirSync(path10.dirname(o.logFile), { recursive: true, mode: 448 });
+    const env = { ...process.env, ...o.cfg.env };
+    const run2 = await adapterStore()?.launch(o.cfg, o.cwd, env) ?? { command: o.cfg.command, args: o.cfg.args, cwd: o.cwd };
+    const log = fs10.openSync(o.logFile, "a", 384);
+    const child = spawn2(run2.command, run2.args, {
+      cwd: run2.cwd,
+      env,
       stdio: ["pipe", "pipe", "pipe"],
       // Its own process group, so the whole tree (an npx wrapper and the agent below it) can be stopped as one.
       detached: true
     });
     await new Promise((resolve, reject) => {
       child.once("spawn", () => resolve());
-      child.once("error", (e) => reject(new Error(`could not start ${o.cfg.command}: ${errMessage(e)}`)));
+      child.once("error", (e) => reject(new Error(`could not start ${run2.command}: ${errMessage(e)}`)));
     }).catch((e) => {
-      fs9.closeSync(log);
+      fs10.closeSync(log);
       throw e;
     });
     const pid = child.pid;
@@ -1369,7 +1636,7 @@ var AdapterProcess = class _AdapterProcess {
     const flushLine = (line) => {
       const text = redactText(line).text;
       try {
-        fs9.writeSync(log, text + "\n");
+        fs10.writeSync(log, text + "\n");
       } catch {
       }
       try {
@@ -1395,7 +1662,7 @@ var AdapterProcess = class _AdapterProcess {
         tail = "";
       }
       try {
-        fs9.closeSync(log);
+        fs10.closeSync(log);
       } catch {
       }
     });
@@ -1511,6 +1778,9 @@ var SESSION_REF_RE = SESSION_ID_RE;
 var MAX_REPORTED = 12;
 var MAX_LIST_PAGES = 8;
 var MAX_TITLE = 80;
+var MAX_WAITING_FOR = 60;
+var UNKNOWN_RELIST_MS = 2e4;
+var MAX_WATCHED_PROJECT_DIRS = 200;
 var MAX_SCANNED_PROJECT_DIRS = 2e3;
 var UNREADABLE_GRACE_MS2 = 6e4;
 var NO_HOOKS = {
@@ -1531,7 +1801,7 @@ var AttachSupport = class {
   constructor(agent, d) {
     this.agent = agent;
     this.d = d;
-    this.configDir = path10.resolve(agent.env.CLAUDE_CONFIG_DIR ?? d.env.CLAUDE_CONFIG_DIR ?? path10.join(os3.homedir(), ".claude"));
+    this.configDir = path11.resolve(agent.env.CLAUDE_CONFIG_DIR ?? d.env.CLAUDE_CONFIG_DIR ?? path11.join(os3.homedir(), ".claude"));
   }
   agent;
   d;
@@ -1590,7 +1860,7 @@ var AttachSupport = class {
         sessionId: `list-${this.agent.id}`,
         cwd: this.agent.roots[0] ?? os3.homedir(),
         hooks: NO_HOOKS,
-        logFile: path10.join(this.d.logDir, `adapter-${this.agent.id}.log`),
+        logFile: path11.join(this.d.logDir, `adapter-${this.agent.id}.log`),
         version: this.d.version,
         initTimeoutMs: 3e4
       });
@@ -1649,13 +1919,108 @@ var AttachSupport = class {
     } else if (this.now() - this.listedAt > this.d.catalogMs) void this.refreshCatalog();
     const live = await within(this.liveEntries().catch(() => null), capMs, null);
     const attached = this.d.attachedRefs();
-    return this.listed.slice(0, MAX_REPORTED).map((l) => ({
-      ref: l.ref,
-      title: l.title,
-      cwd: l.cwd,
-      updated_at: Math.floor(l.updatedAt / 1e3),
-      state: attached.has(l.ref) ? "attached" : live === null ? "unknown" : live.some((e) => e.sessionId.toLowerCase() === l.ref) ? "live" : "idle"
-    }));
+    return this.listed.slice(0, MAX_REPORTED).map((l) => {
+      const holders = live?.filter((e) => e.sessionId.toLowerCase() === l.ref) ?? [];
+      const state = attached.has(l.ref) ? "attached" : live === null ? "unknown" : holders.length ? "live" : "idle";
+      const out = { ref: l.ref, title: l.title, cwd: l.cwd, updated_at: Math.floor(l.updatedAt / 1e3), state };
+      if (state === "live") Object.assign(out, liveActivity(holders));
+      return out;
+    });
+  }
+  // --- noticing a change without starting anything ----------------------------------------
+  lastPrint = null;
+  lastUnknownList = 0;
+  /**
+   * A cheap look, with no process started: the names and modification times of Claude Code's session registry files (one
+   * is written when a terminal opens a conversation, rewritten when it starts or finishes a turn or starts waiting, and
+   * removed when it exits) and of its projects directory (a new working directory). True when something changed since
+   * the previous look, so that the caller reports at once rather than at the next heartbeat. A live conversation inside
+   * the roots whose transcript exists but which the list does not have yet (a terminal just opened it), or a new transcript
+   * in a project folder inside the roots (one a terminal ran and already ended), is listed again first, at most every
+   * {@link UNKNOWN_RELIST_MS} (a change inside that time is listed when it is up). The first look only learns what is there.
+   */
+  async poll() {
+    const print = this.fingerprint();
+    const projects = this.projectsPrint();
+    if (print === this.lastPrint && projects === this.lastProjects && !this.relistDue) return false;
+    const first = this.lastPrint === null;
+    const looked = print !== this.lastPrint || projects !== this.lastProjects;
+    const newTranscript = !first && projects !== this.lastProjects;
+    this.lastPrint = print;
+    this.lastProjects = projects;
+    let rows;
+    try {
+      rows = readRegistry(this.configDir, this.localDomain, this.now());
+    } catch {
+      rows = null;
+    }
+    if (looked && (newTranscript || rows !== null && this.unlistedLive(rows))) this.relistDue = true;
+    let relisted = false;
+    if (this.relistDue && this.now() - this.lastUnknownList >= UNKNOWN_RELIST_MS) {
+      this.relistDue = false;
+      this.lastUnknownList = this.now();
+      relisted = await within(this.refreshCatalog().then(() => true), 6e4, false);
+    }
+    const summary = (rows === null ? "unreadable;" : "") + this.listed.slice(0, MAX_REPORTED).map((l) => {
+      const holders = (rows ?? []).filter((e) => e.sessionId.toLowerCase() === l.ref);
+      return `${l.ref}:${holders.length ? liveActivity(holders).activity ?? "live" : "-"}:${liveActivity(holders).waiting_for ?? ""}`;
+    }).join(",");
+    const changed = summary !== this.lastSummary;
+    this.lastSummary = summary;
+    return changed && (!first || relisted);
+  }
+  lastSummary = "";
+  lastProjects = null;
+  /** A change asked for a new list that the rate limit has held back; the next look makes it. */
+  relistDue = false;
+  /**
+   * The project folders inside the roots (Claude Code names one after the working directory, every non-alphanumeric
+   * turned into "-") with their modification times: one changes when a conversation is started in it. At most
+   * {@link MAX_WATCHED_PROJECT_DIRS} of them, so a huge config directory is not walked every few seconds.
+   */
+  projectsPrint() {
+    const projects = path11.join(this.configDir, "projects");
+    const prefixes = this.agent.roots.map((r) => r.replace(/[^A-Za-z0-9]/g, "-"));
+    const parts = [];
+    try {
+      parts.push(`projects:${fs11.statSync(projects).mtimeMs}`);
+      for (const name of fs11.readdirSync(projects).sort()) {
+        if (!prefixes.some((p) => name.startsWith(p))) continue;
+        if (parts.length > MAX_WATCHED_PROJECT_DIRS) break;
+        try {
+          parts.push(`${name}:${fs11.statSync(path11.join(projects, name)).mtimeMs}`);
+        } catch {
+        }
+      }
+    } catch {
+      parts.push("no-projects");
+    }
+    return parts.join("|");
+  }
+  fingerprint() {
+    const parts = [];
+    const dir = path11.join(this.configDir, "sessions");
+    try {
+      for (const name of fs11.readdirSync(dir).sort()) {
+        if (!name.endsWith(".json")) continue;
+        try {
+          parts.push(`${name}:${fs11.statSync(path11.join(dir, name)).mtimeMs}`);
+        } catch {
+        }
+      }
+    } catch {
+      parts.push("no-sessions");
+    }
+    return parts.join("|");
+  }
+  /** Whether a process holds open a conversation in the roots, with a transcript on disk, that the last list did not have. */
+  unlistedLive(rows) {
+    return rows.some((e) => {
+      const ref = e.sessionId.toLowerCase();
+      if (e.foreign || !SESSION_REF_RE.test(ref) || !e.cwd || this.listed.some((l) => l.ref === ref)) return false;
+      if (!checkCwd(e.cwd, this.agent.roots).ok) return false;
+      return fs11.existsSync(path11.join(this.configDir, "projects", e.cwd.replace(/[^A-Za-z0-9]/g, "-"), `${ref}.jsonl`));
+    });
   }
   // --- the twin check ----------------------------------------------------------------
   /**
@@ -1684,7 +2049,7 @@ var AttachSupport = class {
       const file = this.transcriptFile(want);
       let age = null;
       try {
-        if (file) age = this.now() - fs10.statSync(file).mtimeMs;
+        if (file) age = this.now() - fs11.statSync(file).mtimeMs;
       } catch {
       }
       if (age !== null && age < this.d.recentWriteMs) return { ok: false, reason: "recently_written", detail: `its transcript was written ${Math.max(0, Math.round(age / 1e3))} s ago` };
@@ -1739,7 +2104,19 @@ var AttachSupport = class {
   transcriptSize(ref) {
     const file = SESSION_REF_RE.test(ref) ? this.transcriptFile(ref.toLowerCase()) : null;
     try {
-      return file ? fs10.statSync(file).size : null;
+      return file ? fs11.statSync(file).size : null;
+    } catch {
+      return null;
+    }
+  }
+  /** Where the conversation's transcript is, or null when it cannot be found (yet). */
+  transcriptPath(ref) {
+    const file = SESSION_REF_RE.test(ref) ? this.transcriptFile(ref.toLowerCase()) : null;
+    if (!file) return null;
+    try {
+      const root = fs11.realpathSync(path11.join(this.configDir, "projects"));
+      const real = fs11.realpathSync(file);
+      return real.startsWith(root + path11.sep) && real.endsWith(`${ref.toLowerCase()}.jsonl`) ? real : null;
     } catch {
       return null;
     }
@@ -1747,24 +2124,24 @@ var AttachSupport = class {
   /** `<config dir>/projects/<working directory with every non-alphanumeric turned into "-">/<id>.jsonl`, found by name when that guess misses. */
   transcriptFile(ref) {
     const cached = this.transcripts.get(ref);
-    if (cached && fs10.existsSync(cached)) return cached;
+    if (cached && fs11.existsSync(cached)) return cached;
     this.transcripts.delete(ref);
-    const projects = path10.join(this.configDir, "projects");
+    const projects = path11.join(this.configDir, "projects");
     const remember = (f) => {
       this.transcripts.set(ref, f);
       return f;
     };
     const known = this.listed.find((l) => l.ref === ref);
     if (known) {
-      const guess = path10.join(projects, known.cwd.replace(/[^A-Za-z0-9]/g, "-"), `${ref}.jsonl`);
-      if (fs10.existsSync(guess)) return remember(guess);
+      const guess = path11.join(projects, known.cwd.replace(/[^A-Za-z0-9]/g, "-"), `${ref}.jsonl`);
+      if (fs11.existsSync(guess)) return remember(guess);
     }
     try {
       let n = 0;
-      for (const dir of fs10.readdirSync(projects)) {
+      for (const dir of fs11.readdirSync(projects)) {
         if (++n > MAX_SCANNED_PROJECT_DIRS) break;
-        const f = path10.join(projects, dir, `${ref}.jsonl`);
-        if (fs10.existsSync(f)) return remember(f);
+        const f = path11.join(projects, dir, `${ref}.jsonl`);
+        if (fs11.existsSync(f)) return remember(f);
       }
     } catch {
     }
@@ -1804,30 +2181,37 @@ function parseAgentsJson(text) {
   const out = [];
   for (const x of raw) {
     if (isObject(x) && typeof x.pid === "number" && Number.isInteger(x.pid) && typeof x.sessionId === "string") {
-      out.push({ pid: x.pid, sessionId: x.sessionId, status: typeof x.status === "string" ? x.status : null, foreign: false });
+      out.push({
+        pid: x.pid,
+        sessionId: x.sessionId,
+        status: typeof x.status === "string" ? x.status : null,
+        foreign: false,
+        waitingFor: typeof x.waitingFor === "string" ? x.waitingFor : null,
+        cwd: typeof x.cwd === "string" ? x.cwd : null
+      });
     }
   }
   return out;
 }
 function readRegistry(configDir, localDomain, now = Date.now()) {
-  const dir = path10.join(configDir, "sessions");
+  const dir = path11.join(configDir, "sessions");
   let names;
   try {
-    names = fs10.readdirSync(dir);
+    names = fs11.readdirSync(dir);
   } catch (e) {
     throw new TwinCheckError(`${dir}: ${errMessage(e)}`);
   }
   const out = [];
   for (const name of names) {
     if (!name.endsWith(".json")) continue;
-    const file = path10.join(dir, name);
+    const file = path11.join(dir, name);
     let doc;
     try {
-      doc = JSON.parse(fs10.readFileSync(file, "utf8"));
+      doc = JSON.parse(fs11.readFileSync(file, "utf8"));
     } catch (e) {
       let age = Infinity;
       try {
-        age = now - fs10.statSync(file).mtimeMs;
+        age = now - fs11.statSync(file).mtimeMs;
       } catch {
       }
       if (age < UNREADABLE_GRACE_MS2) throw new TwinCheckError(`${file} is unreadable (${errMessage(e).split("\n")[0]})`);
@@ -1840,14 +2224,21 @@ function readRegistry(configDir, localDomain, now = Date.now()) {
       if (!isAlive(doc.pid)) continue;
       if (process.platform === "linux" && typeof doc.procStart === "string" && processStart(doc.pid) !== doc.procStart) continue;
     }
-    out.push({ pid: doc.pid, sessionId: doc.sessionId, status: typeof doc.status === "string" ? doc.status : null, foreign });
+    out.push({
+      pid: doc.pid,
+      sessionId: doc.sessionId,
+      status: typeof doc.status === "string" ? doc.status : null,
+      foreign,
+      waitingFor: typeof doc.waitingFor === "string" ? doc.waitingFor : null,
+      cwd: typeof doc.cwd === "string" ? doc.cwd : null
+    });
   }
   return out;
 }
 function processGroup(pid) {
   try {
     if (process.platform === "linux") {
-      const stat = fs10.readFileSync(`/proc/${pid}/stat`, "utf8");
+      const stat = fs11.readFileSync(`/proc/${pid}/stat`, "utf8");
       return Number(stat.slice(stat.lastIndexOf(")") + 2).split(" ")[2]) || null;
     }
     return Number(execFileSync2("ps", ["-o", "pgid=", "-p", String(pid)], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim()) || null;
@@ -1855,6 +2246,16 @@ function processGroup(pid) {
     return null;
   }
 }
+function liveActivity(holders) {
+  const waiting = holders.find((e) => e.status === "waiting");
+  if (waiting) {
+    const why = waiting.waitingFor ? cleanTitle(waiting.waitingFor).slice(0, MAX_WAITING_FOR) : "";
+    return why ? { activity: "waiting", waiting_for: why } : { activity: "waiting" };
+  }
+  if (holders.some((e) => e.status === "busy")) return { activity: "working" };
+  if (holders.some((e) => e.status === "idle")) return { activity: "idle" };
+  return {};
+}
 function cleanTitle(raw) {
   const one = redactText(raw).text.replace(/[\u0000-\u001f\u007f]+/g, " ").replace(/\s+/g, " ").trim();
   return one.length > MAX_TITLE ? `${one.slice(0, MAX_TITLE - 1)}\u2026` : one;
@@ -1865,70 +2266,223 @@ function fitResumable(base, items, limit = REMOTE_AGENT_LIMITS.maxCapabilitiesBy
   for (; ; ) {
     const caps = { ...base, resumable: items.slice(0, n) };
     if (size(caps) <= limit) return caps;
-    if (n === 0) return base;
+    if (n === 0) {
+      const { watch_live: _watch, ...rest } = base;
+      return size(base) > limit && size(rest) < size(base) ? rest : base;
+    }
     n--;
   }
 }
+var MAX_TOOL_TITLE = 200;
+function transcriptUpdates(line) {
+  let doc;
+  try {
+    doc = JSON.parse(line);
+  } catch {
+    return [];
+  }
+  if (!isObject(doc) || doc.isSidechain === true || doc.isMeta === true) return [];
+  if (doc.type !== "user" && doc.type !== "assistant") return [];
+  const msg = isObject(doc.message) ? doc.message : null;
+  if (!msg) return [];
+  const text = (type, t) => t.trim() ? [{ type, update: { sessionUpdate: type, content: { type: "text", text: t } } }] : [];
+  if (typeof msg.content === "string") return text(doc.type === "user" ? "user_message_chunk" : "agent_message_chunk", msg.content);
+  if (!Array.isArray(msg.content)) return [];
+  const out = [];
+  for (const block of msg.content) {
+    if (!isObject(block)) continue;
+    if (block.type === "text" && typeof block.text === "string") {
+      out.push(...text(doc.type === "user" ? "user_message_chunk" : "agent_message_chunk", block.text));
+    } else if (doc.type === "assistant" && block.type === "tool_use" && typeof block.id === "string") {
+      out.push({ type: "tool_call", update: { sessionUpdate: "tool_call", toolCallId: block.id, title: toolTitle(block.name, block.input), kind: "other", status: "in_progress", rawInput: isObject(block.input) ? block.input : {} } });
+    } else if (doc.type === "user" && block.type === "tool_result" && typeof block.tool_use_id === "string") {
+      const result = resultText(block.content);
+      out.push({ type: "tool_call_update", update: {
+        sessionUpdate: "tool_call_update",
+        toolCallId: block.tool_use_id,
+        status: block.is_error === true ? "failed" : "completed",
+        ...result ? { content: [{ type: "content", content: { type: "text", text: result } }] } : {}
+      } });
+    }
+  }
+  return out;
+}
+function toolTitle(name, input) {
+  const tool = typeof name === "string" && name ? name : "Tool";
+  const i = isObject(input) ? input : {};
+  const what = [i.description, i.command, i.file_path, i.path, i.pattern, i.url].find((v) => typeof v === "string" && v.trim() !== "");
+  return cleanTitleTo(what ? `${tool}: ${what}` : tool, MAX_TOOL_TITLE);
+}
+function resultText(content) {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content.filter((c) => isObject(c) && c.type === "text" && typeof c.text === "string").map((c) => c.text).join("\n");
+}
+function cleanTitleTo(raw, max) {
+  const one = raw.replace(/[\u0000-\u001f\u007f]+/g, " ").replace(/\s+/g, " ").trim();
+  return one.length > max ? `${one.slice(0, max - 1)}\u2026` : one;
+}
+var TAIL_BACKLOG_BYTES = 64 * 1024;
+var TAIL_READ_BYTES = 256 * 1024;
+var TAIL_MAX_LINE = 1024 * 1024;
+var TAIL_BACKLOG_UPDATES = 20;
+var TranscriptTail = class {
+  constructor(locate) {
+    this.locate = locate;
+  }
+  locate;
+  offset = null;
+  partial = "";
+  skipping = false;
+  /** A read can end inside a character; the decoder keeps its first bytes for the next one. */
+  decoder = new StringDecoder("utf8");
+  /** The last updates already in the transcript (at most {@link TAIL_BACKLOG_UPDATES}); from here on `poll()` reads what is new. */
+  backlog() {
+    const file = this.locate();
+    if (!file) return [];
+    let fd = null;
+    try {
+      fd = fs11.openSync(file, "r");
+      const size = fs11.fstatSync(fd).size;
+      const start = Math.max(0, size - TAIL_BACKLOG_BYTES);
+      const buf = Buffer.alloc(size - start);
+      const n = buf.length ? fs11.readSync(fd, buf, 0, buf.length, start) : 0;
+      this.offset = start + n;
+      this.decoder = new StringDecoder("utf8");
+      let text = this.decoder.write(buf.subarray(0, n));
+      if (start > 0) text = text.slice(text.indexOf("\n") + 1);
+      const end = text.lastIndexOf("\n");
+      this.partial = end === text.length - 1 ? "" : text.slice(end + 1);
+      const updates = text.slice(0, end + 1).split("\n").flatMap((l) => l ? transcriptUpdates(l) : []);
+      return updates.slice(-TAIL_BACKLOG_UPDATES);
+    } catch {
+      return [];
+    } finally {
+      if (fd !== null) fs11.closeSync(fd);
+    }
+  }
+  /** Start from the end without reading what is there (a watcher that was already following, after a restart). */
+  fromEnd() {
+    const file = this.locate();
+    try {
+      this.offset = file ? fs11.statSync(file).size : null;
+    } catch {
+      this.offset = null;
+    }
+    this.partial = "";
+    this.decoder = new StringDecoder("utf8");
+  }
+  /** What was appended since the last look. */
+  poll() {
+    const file = this.locate();
+    if (!file) return [];
+    let fd = null;
+    try {
+      fd = fs11.openSync(file, "r");
+      const size = fs11.fstatSync(fd).size;
+      if (this.offset === null) this.offset = 0;
+      if (size < this.offset) {
+        this.offset = size;
+        this.partial = "";
+        this.decoder = new StringDecoder("utf8");
+        return [];
+      }
+      if (size === this.offset) return [];
+      const buf = Buffer.alloc(Math.min(TAIL_READ_BYTES, size - this.offset));
+      const n = fs11.readSync(fd, buf, 0, buf.length, this.offset);
+      this.offset += n;
+      return this.take(this.decoder.write(buf.subarray(0, n)));
+    } catch {
+      return [];
+    } finally {
+      if (fd !== null) fs11.closeSync(fd);
+    }
+  }
+  take(chunk) {
+    const text = this.partial + chunk;
+    const end = text.lastIndexOf("\n");
+    if (end < 0) {
+      this.partial = text;
+      if (this.partial.length > TAIL_MAX_LINE) {
+        this.partial = "";
+        this.skipping = true;
+      }
+      return [];
+    }
+    this.partial = text.slice(end + 1);
+    const lines = text.slice(0, end).split("\n");
+    if (this.skipping) {
+      lines.shift();
+      this.skipping = false;
+    }
+    if (this.partial.length > TAIL_MAX_LINE) {
+      this.partial = "";
+      this.skipping = true;
+    }
+    return lines.flatMap((l) => l ? transcriptUpdates(l) : []);
+  }
+};
 
 // src/health.ts
-import fs11 from "node:fs";
-import path12 from "node:path";
+import fs12 from "node:fs";
+import path13 from "node:path";
 
 // src/paths.ts
 import os4 from "node:os";
-import path11 from "node:path";
+import path12 from "node:path";
 function resolveDirs(env = process.env, home = os4.homedir()) {
   const one = env.CLAW_CONNECTOR_HOME?.trim();
-  if (one) return { config: path11.join(one, "config"), state: path11.join(one, "state") };
-  const cfg = env.XDG_CONFIG_HOME?.trim() || path11.join(home, ".config");
-  const st = env.XDG_STATE_HOME?.trim() || path11.join(home, ".local", "state");
-  return { config: path11.join(cfg, "claw-connector"), state: path11.join(st, "claw-connector") };
-}
-var configFile = (d) => path11.join(d.config, "agents.toml");
-var credentialsFile = (d) => path11.join(d.config, "credentials.json");
-var identityFile = (d) => path11.join(d.state, "connector.json");
-var sessionsFile = (d) => path11.join(d.state, "sessions.json");
-var childrenFile = (d) => path11.join(d.state, "children.json");
-var pidFile = (d) => path11.join(d.state, "connector.pid");
-var pauseFile = (d) => path11.join(d.state, "paused");
-var auditFile = (d) => path11.join(d.state, "audit.jsonl");
-var outboxDir = (d) => path11.join(d.state, "outbox");
-var logDir = (d) => path11.join(d.state, "logs");
-var disconnectsFile = (d) => path11.join(d.state, "disconnects.jsonl");
-var needsLoginFile = (d) => path11.join(d.state, "needs-login.json");
-var supervisorPidFile = (d) => path11.join(d.state, "supervisor.pid");
-var runLogFile = (d) => path11.join(d.state, "run.log");
-var keepaliveFile = (d) => path11.join(d.state, "keepalive.sh");
-var serviceFile = (d) => path11.join(d.state, "service.json");
+  if (one) return { config: path12.join(one, "config"), state: path12.join(one, "state") };
+  const cfg = env.XDG_CONFIG_HOME?.trim() || path12.join(home, ".config");
+  const st = env.XDG_STATE_HOME?.trim() || path12.join(home, ".local", "state");
+  return { config: path12.join(cfg, "claw-connector"), state: path12.join(st, "claw-connector") };
+}
+var configFile = (d) => path12.join(d.config, "agents.toml");
+var credentialsFile = (d) => path12.join(d.config, "credentials.json");
+var identityFile = (d) => path12.join(d.state, "connector.json");
+var sessionsFile = (d) => path12.join(d.state, "sessions.json");
+var childrenFile = (d) => path12.join(d.state, "children.json");
+var pidFile = (d) => path12.join(d.state, "connector.pid");
+var pauseFile = (d) => path12.join(d.state, "paused");
+var stopRequestFile = (d) => path12.join(d.state, "stop-requested.json");
+var auditFile = (d) => path12.join(d.state, "audit.jsonl");
+var outboxDir = (d) => path12.join(d.state, "outbox");
+var logDir = (d) => path12.join(d.state, "logs");
+var disconnectsFile = (d) => path12.join(d.state, "disconnects.jsonl");
+var needsLoginFile = (d) => path12.join(d.state, "needs-login.json");
+var supervisorPidFile = (d) => path12.join(d.state, "supervisor.pid");
+var runLogFile = (d) => path12.join(d.state, "run.log");
+var keepaliveFile = (d) => path12.join(d.state, "keepalive.sh");
+var serviceFile = (d) => path12.join(d.state, "service.json");
 
 // src/health.ts
 var MAX_BYTES = 128 * 1024;
 function recordDisconnect(dirs, d) {
   const file = disconnectsFile(dirs);
   try {
-    fs11.mkdirSync(path12.dirname(file), { recursive: true, mode: 448 });
-    const fd = fs11.openSync(file, "a+", 384);
+    fs12.mkdirSync(path13.dirname(file), { recursive: true, mode: 448 });
+    const fd = fs12.openSync(file, "a+", 384);
     let lines = null;
     try {
-      fs11.writeSync(fd, JSON.stringify({ at: d.at ?? (/* @__PURE__ */ new Date()).toISOString(), reason: d.reason, ...d.detail ? { detail: d.detail.slice(0, 300) } : {} }) + "\n");
-      const size = fs11.fstatSync(fd).size;
+      fs12.writeSync(fd, JSON.stringify({ at: d.at ?? (/* @__PURE__ */ new Date()).toISOString(), reason: d.reason, ...d.detail ? { detail: d.detail.slice(0, 300) } : {} }) + "\n");
+      const size = fs12.fstatSync(fd).size;
       if (size > MAX_BYTES) {
         const buf = Buffer.alloc(size);
         let got = 0;
         while (got < size) {
-          const n = fs11.readSync(fd, buf, got, size - got, got);
+          const n = fs12.readSync(fd, buf, got, size - got, got);
           if (n === 0) break;
           got += n;
         }
         lines = buf.subarray(0, got).toString("utf8").split("\n").filter(Boolean);
       }
     } finally {
-      fs11.closeSync(fd);
+      fs12.closeSync(fd);
     }
     if (lines) {
       const tmp = `${file}.${process.pid}.tmp`;
-      fs11.writeFileSync(tmp, lines.slice(Math.floor(lines.length / 2)).join("\n") + "\n", { mode: 384 });
-      fs11.renameSync(tmp, file);
+      fs12.writeFileSync(tmp, lines.slice(Math.floor(lines.length / 2)).join("\n") + "\n", { mode: 384 });
+      fs12.renameSync(tmp, file);
     }
   } catch {
   }
@@ -1936,7 +2490,7 @@ function recordDisconnect(dirs, d) {
 function recentDisconnects(dirs, n = 1) {
   try {
     const out = [];
-    for (const line of fs11.readFileSync(disconnectsFile(dirs), "utf8").split("\n").filter(Boolean).slice(-n)) {
+    for (const line of fs12.readFileSync(disconnectsFile(dirs), "utf8").split("\n").filter(Boolean).slice(-n)) {
       try {
         const v = JSON.parse(line);
         if (isObject(v) && typeof v.at === "string" && typeof v.reason === "string") out.push({ at: v.at, reason: v.reason, ...typeof v.detail === "string" ? { detail: v.detail } : {} });
@@ -1950,14 +2504,14 @@ function recentDisconnects(dirs, n = 1) {
 }
 function markNeedsLogin(dirs, reason) {
   try {
-    fs11.mkdirSync(dirs.state, { recursive: true, mode: 448 });
-    fs11.writeFileSync(needsLoginFile(dirs), JSON.stringify({ at: (/* @__PURE__ */ new Date()).toISOString(), reason: reason.slice(0, 300) }), { mode: 384 });
+    fs12.mkdirSync(dirs.state, { recursive: true, mode: 448 });
+    fs12.writeFileSync(needsLoginFile(dirs), JSON.stringify({ at: (/* @__PURE__ */ new Date()).toISOString(), reason: reason.slice(0, 300) }), { mode: 384 });
   } catch {
   }
 }
 function needsLogin(dirs) {
   try {
-    const v = JSON.parse(fs11.readFileSync(needsLoginFile(dirs), "utf8"));
+    const v = JSON.parse(fs12.readFileSync(needsLoginFile(dirs), "utf8"));
     if (isObject(v) && typeof v.reason === "string") return { at: typeof v.at === "string" ? v.at : "", reason: v.reason };
     return { at: "", reason: "unreadable needs-login.json" };
   } catch (e) {
@@ -1965,11 +2519,11 @@ function needsLogin(dirs) {
   }
 }
 function clearNeedsLogin(dirs) {
-  fs11.rmSync(needsLoginFile(dirs), { force: true });
+  fs12.rmSync(needsLoginFile(dirs), { force: true });
 }
 
 // src/session.ts
-import path13 from "node:path";
+import path14 from "node:path";
 
 // src/permissions.ts
 import { randomUUID } from "node:crypto";
@@ -2097,7 +2651,15 @@ var PermissionBook = class {
 };
 
 // src/session.ts
-var DEFAULT_SESSION_TIMING = { idleMs: 30 * 6e4, permissionTtlMs: 10 * 6e4, modeConfirmMs: 3e3, twinWatchMs: 1e3 };
+var DEFAULT_SESSION_TIMING = {
+  idleMs: 30 * 6e4,
+  permissionTtlMs: 10 * 6e4,
+  modeConfirmMs: 3e3,
+  twinWatchMs: 1e3,
+  spectateMs: 1e3,
+  spectateCheckMs: 5e3
+};
+var READ_ONLY_REASON = "read_only_live_session";
 var SessionRefusal = class extends Error {
   constructor(reason, message) {
     super(message ?? reason);
@@ -2105,6 +2667,7 @@ var SessionRefusal = class extends Error {
   }
   reason;
 };
+var BYPASS_HINT = ` (Claude Code offers it to root only with IS_SANDBOX set, and never when permissions.disableBypassPermissionsMode is "disable"; "claw-connector doctor" names the fix)`;
 var MAX_TOOL_OUTPUT_BYTES = 8 * 1024;
 var MAX_QUEUED_PROMPTS = 5;
 var PERMISSION_WARNING_RE = /canUseTool will not be invoked/i;
@@ -2162,6 +2725,15 @@ var Session = class {
   queue = [];
   launching = null;
   idle;
+  /**
+   * The conversation is open in a terminal: this session only reads its transcript and shows it (see {@link spectate}).
+   * No adapter is ever started for it, and every command that would write is refused.
+   */
+  readOnly = false;
+  tail = null;
+  tailTimer;
+  lastTerminalCheck = 0;
+  checkingTerminal = false;
   book;
   // --- helpers -----------------------------------------------------------------
   emit(type, data) {
@@ -2220,6 +2792,11 @@ var Session = class {
     if (requestedMode && !this.agent.safeModes.includes(requestedMode) && !this.agent.allowUnsafeModes) {
       return this.refuse(new SessionRefusal("mode_not_allowed", `mode ${requestedMode} needs approval = "never" for this agent (or allow_unsafe_modes) on this machine`));
     }
+    const support = this.env.attach.get(this.agent.id);
+    if (support && this.acpId) {
+      const verdict = await support.check(this.acpId, { transcript: false });
+      if (!verdict.ok && verdict.reason === "session_live") return this.spectate(support, title, verdict.detail);
+    }
     if (requestedMode) this.targetMode = requestedMode;
     try {
       await this.launch("resume");
@@ -2232,6 +2809,85 @@ var Session = class {
     this.emit("session_started", { acp_session_id: this.acpId, agent_id: this.agent.id, kind: this.agent.kind, cwd: this.cwd, title, attached: true, modes: this.shownModes(), currentMode: this.currentMode, unattended: this.unattended });
     this.touch();
   }
+  // --- read-only: a conversation open in a terminal ------------------------------------
+  /**
+   * Show a conversation that a terminal has open without taking it over. Nothing is started: the transcript the terminal
+   * writes is read from its end (`TranscriptTail`, read-only) and each new line goes out as the update an adapter would
+   * have sent, scrubbed like every other event, marked `read_only`. What was there just before is sent first, marked
+   * `replay`. Prompts, mode changes and decisions are refused (`read_only_live_session`) and never reach anything that
+   * could write to the transcript. When the terminal no longer has the conversation open the session ends
+   * (`terminal_closed`): taking it over then is a new session, through the full check.
+   */
+  spectate(support, title, detail) {
+    this.readOnly = true;
+    this.tail = new TranscriptTail(() => this.acpId ? support.transcriptPath(this.acpId) : null);
+    const backlog = this.tail.backlog();
+    this.env.store.put(this.id, { agent_id: this.agent.id, acp_session_id: this.acpId, cwd: this.cwd, status: "active", mode: null, read_only: true, created_at: (/* @__PURE__ */ new Date()).toISOString() });
+    this.audit("session_spectating", { cwd: this.cwd, acp_session_id: this.acpId, detail: detail.slice(0, 300) });
+    this.emit("session_started", {
+      acp_session_id: this.acpId,
+      agent_id: this.agent.id,
+      kind: this.agent.kind,
+      cwd: this.cwd,
+      title,
+      attached: true,
+      read_only: true,
+      read_only_reason: "session_live",
+      modes: [],
+      currentMode: null,
+      unattended: false
+    });
+    this.announced = true;
+    for (const u of backlog) this.emitTranscript(u, true);
+    this.followTail(support);
+  }
+  /** After a restart: a session that was read-only is again, from the transcript's end (what was sent before is not sent twice). */
+  restoreSpectate() {
+    this.readOnly = true;
+    const support = this.env.attach.get(this.agent.id);
+    if (!support) return;
+    this.tail = new TranscriptTail(() => this.acpId ? support.transcriptPath(this.acpId) : null);
+    this.tail.fromEnd();
+    this.followTail(support);
+  }
+  followTail(support) {
+    this.lastTerminalCheck = Date.now();
+    const tick = () => {
+      if (this.closed || !this.tail) return;
+      for (const u of this.tail.poll()) this.emitTranscript(u, false);
+      if (!this.checkingTerminal && Date.now() - this.lastTerminalCheck >= this.env.timing.spectateCheckMs) void this.checkTerminal(support);
+    };
+    this.tailTimer = setInterval(tick, this.env.timing.spectateMs);
+    this.tailTimer.unref?.();
+  }
+  /** Is the conversation still open somewhere else? The cheap look first; only a look that finds nothing asks every source. */
+  async checkTerminal(support) {
+    if (!this.acpId) return;
+    this.checkingTerminal = true;
+    try {
+      this.lastTerminalCheck = Date.now();
+      if (support.peek(this.acpId, null)?.twin) return;
+      const verdict = await support.check(this.acpId, { transcript: false });
+      if (verdict.ok && !this.closed) {
+        for (const u of this.tail?.poll() ?? []) this.emitTranscript(u, false);
+        await this.close("terminal_closed");
+      }
+    } finally {
+      this.checkingTerminal = false;
+    }
+  }
+  emitTranscript(u, replay) {
+    const text = u.type === "agent_message_chunk" ? String(u.update.content?.text ?? "") : "";
+    if (text && this.env.config.dropMessagePatterns.some((re) => re.test(text))) return;
+    const data = limitStrings(redactDeep({ sessionId: this.acpId, update: u.update }), MAX_TOOL_OUTPUT_BYTES);
+    this.emit(u.type, { ...data, read_only: true, ...replay ? { replay: true } : {} });
+  }
+  /** The process is stopping: the transcript is no longer followed (the session itself stays recorded, read-only). */
+  stopTail() {
+    clearInterval(this.tailTimer);
+    this.tailTimer = void 0;
+    this.tail = null;
+  }
   /** Start (or restart) the adapter and bring the ACP session up in a verified mode. One at a time. */
   launch(how) {
     this.launching ??= this.guardedLaunch(how).finally(() => {
@@ -2315,7 +2971,7 @@ var Session = class {
       sessionId: this.id,
       cwd: this.cwd,
       hooks: this.hooks(),
-      logFile: path13.join(this.env.logDir, `adapter-${this.agent.id}.log`),
+      logFile: path14.join(this.env.logDir, `adapter-${this.agent.id}.log`),
       version: this.env.version
     }).catch((e) => {
       throw new SessionRefusal("adapter_start_failed", errMessage(e));
@@ -2328,7 +2984,7 @@ var Session = class {
     this.modeSeen = [];
     try {
       if (how === "new") {
-        const res = await adapter.request("session/new", { cwd: this.cwd, mcpServers: [] });
+        const res = await adapter.request("session/new", { cwd: this.cwd, mcpServers: [], ...claudeSessionMeta(this.agent) });
         if (typeof res.sessionId !== "string") throw new SessionRefusal("adapter_protocol", "session/new returned no session id");
         this.acpId = res.sessionId;
         this.absorb(res);
@@ -2336,11 +2992,11 @@ var Session = class {
         if (!this.acpId) throw new SessionRefusal("adapter_cannot_resume", "no adapter session to resume");
         const caps = adapter.caps.sessionCapabilities;
         if (caps?.resume) {
-          this.absorb(await adapter.request("session/resume", { sessionId: this.acpId, cwd: this.cwd, mcpServers: [] }));
+          this.absorb(await adapter.request("session/resume", { sessionId: this.acpId, cwd: this.cwd, mcpServers: [], ...claudeSessionMeta(this.agent) }));
         } else if (adapter.caps.loadSession) {
           this.replaying = true;
           try {
-            this.absorb(await adapter.requestUnbounded("session/load", { sessionId: this.acpId, cwd: this.cwd, mcpServers: [] }));
+            this.absorb(await adapter.requestUnbounded("session/load", { sessionId: this.acpId, cwd: this.cwd, mcpServers: [], ...claudeSessionMeta(this.agent) }));
           } finally {
             this.replaying = false;
           }
@@ -2381,7 +3037,7 @@ var Session = class {
   async enforceMode(mode) {
     const a = this.adapter;
     if (!a || !this.acpId) throw new SessionRefusal("adapter_gone");
-    if (this.modes.length && !this.modes.some((m) => m.id === mode)) throw new SessionRefusal("mode_unavailable", `the adapter offers no mode ${mode}`);
+    if (this.modes.length && !this.modes.some((m) => m.id === mode)) throw new SessionRefusal("mode_unavailable", `the adapter offers no mode ${mode}${mode === "bypassPermissions" ? BYPASS_HINT : ""}`);
     this.enforcing = true;
     this.modeSeen = [];
     try {
@@ -2437,6 +3093,7 @@ var Session = class {
   }
   /** `set_mode`: a user-chosen mode, only from the allowed list, always read back. */
   async setMode(modeId, cmdId) {
+    if (this.readOnly) return this.rejectCommand("set_mode", cmdId, READ_ONLY_REASON);
     if (!this.adapter) await this.ensureAdapter();
     if (!this.modeAllowed(modeId)) return this.rejectCommand("set_mode", cmdId, "mode_not_allowed");
     if (this.modes.length && !this.modes.some((m) => m.id === modeId)) return this.rejectCommand("set_mode", cmdId, "mode_unavailable");
@@ -2616,6 +3273,12 @@ var Session = class {
       this.rejectCommand("prompt", cmdId, "session_closed", cmdSeq);
       return started();
     }
+    if (this.readOnly) {
+      this.audit("prompt_refused", { reason: READ_ONLY_REASON });
+      this.rejectCommand("prompt", cmdId, READ_ONLY_REASON, cmdSeq);
+      this.emit("turn_end", { stopReason: "error", error: READ_ONLY_REASON, read_only: true, cmd_id: cmdId, cmd_seq: cmdSeq });
+      return started();
+    }
     if (this.queue.length >= MAX_QUEUED_PROMPTS) {
       this.rejectCommand("prompt", cmdId, "too_many_queued_prompts", cmdSeq);
       return started();
@@ -2732,6 +3395,10 @@ var Session = class {
   /** `resume`: bring the session back. A live adapter is NOT asked to resume (that would reset its mode); the mode is re-asserted instead. */
   async resume(cmdId) {
     if (this.closed) return this.rejectCommand("resume", cmdId, "session_closed");
+    if (this.readOnly) {
+      this.emit("session_resumed", { acp_session_id: this.acpId, read_only: true, modes: [], currentMode: null, unattended: false });
+      return;
+    }
     try {
       if (this.adapter && !this.adapter.exited) await this.enforceMode(this.targetMode);
       else await this.launch("resume");
@@ -2774,6 +3441,7 @@ var Session = class {
     if (this.closed) return;
     this.closed = true;
     clearTimeout(this.idle);
+    this.stopTail();
     this.dropQueued();
     for (const actionId of this.book.cancelAll()) this.emit("permission_resolved", { actionId, optionId: null, outcome: "cancelled", by: reason });
     const a = this.adapter;
@@ -2916,6 +3584,10 @@ var SessionManager = class {
   async sessionNew(cmd) {
     const sid = cmd.session_id;
     if (this.sessions.has(sid)) return;
+    if (this.env.store.get(sid)?.read_only) {
+      await this.lookup(sid);
+      return;
+    }
     const agent = this.agent(cmd.agent_id);
     if (!agent) {
       this.env.audit.record("session_refused", { session_id: sid, reason: "unknown_agent", agent_id: String(cmd.agent_id).slice(0, 64) });
@@ -2963,7 +3635,7 @@ var SessionManager = class {
     if (!support) return refuse("attach_unavailable");
     const want = ref.toLowerCase();
     const claim = `${agent.id}:${want}`;
-    if (this.attaching.has(claim) || [...this.sessions.values()].some((s) => !s.closed && s.agent.id === agent.id && s.acpId?.toLowerCase() === want)) return refuse("already_attached");
+    if (this.attaching.has(claim) || [...this.sessions.values()].some((s) => !s.closed && !s.readOnly && s.agent.id === agent.id && s.acpId?.toLowerCase() === want)) return refuse("already_attached");
     if ([...this.sessions.values()].filter((s) => !s.closed).length + this.attaching.size >= MAX_ACTIVE_SESSIONS) return refuse("too_many_sessions");
     this.attaching.add(claim);
     try {
@@ -2983,7 +3655,7 @@ var SessionManager = class {
   /** The ids of the existing sessions this connector holds open, by agent. */
   attachedRefs(agentId) {
     const out = /* @__PURE__ */ new Set();
-    for (const s of this.sessions.values()) if (!s.closed && s.agent.id === agentId && s.acpId) out.add(s.acpId.toLowerCase());
+    for (const s of this.sessions.values()) if (!s.closed && !s.readOnly && s.agent.id === agentId && s.acpId) out.add(s.acpId.toLowerCase());
     return out;
   }
   /** A session this process knows, or one it made earlier (before a restart) and can bring back. */
@@ -3002,8 +3674,16 @@ var SessionManager = class {
     }
     const s = new Session(sid, agent, verdict.real, this.env, rec.acp_session_id, rec.mode);
     this.sessions.set(sid, s);
+    if (rec.read_only) s.restoreSpectate();
     return s;
   }
+  /** At start: every session that was watching a terminal's conversation goes on watching it (and notices when it ends). */
+  async restoreReadOnly() {
+    for (const sid of this.env.store.ids()) {
+      const rec = this.env.store.get(sid);
+      if (rec?.read_only && rec.status === "active" && !this.sessions.has(sid)) await this.lookup(sid);
+    }
+  }
   /** After the command stream reconnects: cards still waiting are shown again. */
   resendPending() {
     for (const s of this.sessions.values()) s.resendPending();
@@ -3016,6 +3696,7 @@ var SessionManager = class {
     for (const s of this.sessions.values()) {
       this.env.audit.record("session_killed", { session_id: s.id, reason });
       s.dropQueued();
+      s.stopTail();
     }
     await this.env.registry.killAll();
     this.sessions.clear();
@@ -3023,8 +3704,8 @@ var SessionManager = class {
 };
 
 // src/outbox.ts
-import fs12 from "node:fs";
-import path14 from "node:path";
+import fs13 from "node:fs";
+import path15 from "node:path";
 var DROPPABLE_TYPES = /* @__PURE__ */ new Set([
   "agent_message_chunk",
   "agent_thought_chunk",
@@ -3051,35 +3732,35 @@ var Outbox = class {
     this.dir = opts.dir;
     this.maxBytes = opts.maxBytesPerSession ?? 5 * 1024 * 1024;
     this.now = opts.now ?? Date.now;
-    fs12.mkdirSync(this.dir, { recursive: true, mode: 448 });
+    fs13.mkdirSync(this.dir, { recursive: true, mode: 448 });
     this.load();
   }
-  eventsFile = (sid) => path14.join(this.dir, `${safeName(sid)}.jsonl`);
-  metaFile = (sid) => path14.join(this.dir, `${safeName(sid)}.meta.json`);
+  eventsFile = (sid) => path15.join(this.dir, `${safeName(sid)}.jsonl`);
+  metaFile = (sid) => path15.join(this.dir, `${safeName(sid)}.meta.json`);
   writeMeta(sid) {
     const tmp = this.metaFile(sid) + ".tmp";
-    fs12.writeFileSync(tmp, JSON.stringify(this.meta.get(sid)), { mode: 384 });
-    fs12.renameSync(tmp, this.metaFile(sid));
+    fs13.writeFileSync(tmp, JSON.stringify(this.meta.get(sid)), { mode: 384 });
+    fs13.renameSync(tmp, this.metaFile(sid));
   }
   /** Rebuild the queue from disk. The highest sequence number ever used is the larger of the meta file and the log itself. */
   load() {
     const loaded = [];
     const bases = /* @__PURE__ */ new Set();
-    for (const name of fs12.readdirSync(this.dir)) {
+    for (const name of fs13.readdirSync(this.dir)) {
       if (name.endsWith(".meta.json")) bases.add(name.slice(0, -".meta.json".length));
       else if (name.endsWith(".jsonl")) bases.add(name.slice(0, -".jsonl".length));
     }
     for (const base of bases) {
       let meta = { lastSeq: 0, acked: 0 };
       try {
-        meta = JSON.parse(fs12.readFileSync(path14.join(this.dir, `${base}.meta.json`), "utf8"));
+        meta = JSON.parse(fs13.readFileSync(path15.join(this.dir, `${base}.meta.json`), "utf8"));
       } catch {
       }
       let sid = null;
-      const file = path14.join(this.dir, `${base}.jsonl`);
+      const file = path15.join(this.dir, `${base}.jsonl`);
       let text = "";
       try {
-        text = fs12.readFileSync(file, "utf8");
+        text = fs13.readFileSync(file, "utf8");
       } catch {
       }
       for (const line of text.split("\n")) {
@@ -3097,8 +3778,8 @@ var Outbox = class {
       if (sid === null) {
         sid = base;
         try {
-          if (this.now() - fs12.statSync(path14.join(this.dir, `${base}.meta.json`)).mtimeMs > TOMBSTONE_MS) {
-            for (const f of [`${base}.meta.json`, `${base}.jsonl`]) fs12.rmSync(path14.join(this.dir, f), { force: true });
+          if (this.now() - fs13.statSync(path15.join(this.dir, `${base}.meta.json`)).mtimeMs > TOMBSTONE_MS) {
+            for (const f of [`${base}.meta.json`, `${base}.jsonl`]) fs13.rmSync(path15.join(this.dir, f), { force: true });
             continue;
           }
         } catch {
@@ -3120,7 +3801,7 @@ var Outbox = class {
     meta.lastSeq = ev.seq;
     this.meta.set(sessionId, meta);
     const line = JSON.stringify(ev);
-    fs12.appendFileSync(this.eventsFile(sessionId), line + "\n", { mode: 384 });
+    fs13.appendFileSync(this.eventsFile(sessionId), line + "\n", { mode: 384 });
     if (ev.seq === 1) this.writeMeta(sessionId);
     this.queue.push(ev);
     this.bytes.set(sessionId, (this.bytes.get(sessionId) ?? 0) + line.length);
@@ -3149,8 +3830,8 @@ var Outbox = class {
     this.writeMeta(sessionId);
     const mine = this.queue.filter((e) => e.session_id === sessionId);
     const tmp = this.eventsFile(sessionId) + ".tmp";
-    fs12.writeFileSync(tmp, mine.map((e) => JSON.stringify(e) + "\n").join(""), { mode: 384 });
-    fs12.renameSync(tmp, this.eventsFile(sessionId));
+    fs13.writeFileSync(tmp, mine.map((e) => JSON.stringify(e) + "\n").join(""), { mode: 384 });
+    fs13.renameSync(tmp, this.eventsFile(sessionId));
   }
   /** The oldest events not yet acknowledged, in the order they were appended. */
   pending(max) {
@@ -3188,7 +3869,7 @@ var Outbox = class {
     this.writeMeta(sid);
     const left = this.queue.filter((e) => e.session_id === sid);
     if (left.length === 0) {
-      fs12.writeFileSync(this.eventsFile(sid), "", { mode: 384 });
+      fs13.writeFileSync(this.eventsFile(sid), "", { mode: 384 });
       this.bytes.set(sid, 0);
       if (this.closed.has(sid)) this.forget(sid);
     } else if (left.length < this.queue.length / 2 || meta.acked > 1e3) {
@@ -3207,7 +3888,7 @@ var Outbox = class {
    * repeat. What stays is the small meta file, a tombstone, removed after {@link TOMBSTONE_MS}.
    */
   forget(sid) {
-    fs12.rmSync(this.eventsFile(sid), { force: true });
+    fs13.rmSync(this.eventsFile(sid), { force: true });
     if (this.meta.has(sid)) this.writeMeta(sid);
     this.bytes.delete(sid);
     this.closed.delete(sid);
@@ -3215,19 +3896,19 @@ var Outbox = class {
 };
 
 // src/session-store.ts
-import fs13 from "node:fs";
-import path15 from "node:path";
+import fs14 from "node:fs";
+import path16 from "node:path";
 var SessionStore = class {
   constructor(file) {
     this.file = file;
     this.pendingFile = `${file}.pending`;
     try {
-      const raw = JSON.parse(fs13.readFileSync(this.pendingFile, "utf8"));
+      const raw = JSON.parse(fs14.readFileSync(this.pendingFile, "utf8"));
       if (Array.isArray(raw)) this.pending = raw.filter((p) => p && typeof p.session_id === "string" && typeof p.action_id === "string");
     } catch {
     }
     try {
-      const raw = JSON.parse(fs13.readFileSync(file, "utf8"));
+      const raw = JSON.parse(fs14.readFileSync(file, "utf8"));
       if (raw && typeof raw === "object" && !Array.isArray(raw)) this.recs = raw;
     } catch {
     }
@@ -3270,23 +3951,24 @@ var SessionStore = class {
     return out;
   }
   savePending() {
-    fs13.mkdirSync(path15.dirname(this.pendingFile), { recursive: true, mode: 448 });
+    fs14.mkdirSync(path16.dirname(this.pendingFile), { recursive: true, mode: 448 });
     const tmp = `${this.pendingFile}.${process.pid}.tmp`;
-    fs13.writeFileSync(tmp, JSON.stringify(this.pending), { mode: 384 });
-    fs13.renameSync(tmp, this.pendingFile);
+    fs14.writeFileSync(tmp, JSON.stringify(this.pending), { mode: 384 });
+    fs14.renameSync(tmp, this.pendingFile);
   }
   ids() {
     return Object.keys(this.recs);
   }
   save() {
-    fs13.mkdirSync(path15.dirname(this.file), { recursive: true, mode: 448 });
+    fs14.mkdirSync(path16.dirname(this.file), { recursive: true, mode: 448 });
     const tmp = `${this.file}.${process.pid}.tmp`;
-    fs13.writeFileSync(tmp, JSON.stringify(this.recs), { mode: 384 });
-    fs13.renameSync(tmp, this.file);
+    fs14.writeFileSync(tmp, JSON.stringify(this.recs), { mode: 384 });
+    fs14.renameSync(tmp, this.file);
   }
 };
 
 // src/connector.ts
+var RESTART_RECONNECT_GAP_MS = 5e3;
 var DEFAULT_TIMING = {
   ...DEFAULT_SESSION_TIMING,
   heartbeatMs: REMOTE_AGENT_TIMING.heartbeatMs,
@@ -3297,6 +3979,7 @@ var DEFAULT_TIMING = {
   backoffMaxMs: 6e4,
   pausePollMs: 1e3,
   catalogMs: 12e4,
+  sessionsWatchMs: 1e4,
   attachCliMs: 8e3,
   recentWriteMs: 1e4,
   authFailLimit: 4,
@@ -3423,8 +4106,16 @@ var Connector = class {
   }
   async descriptors() {
     return Promise.all(this.d.config.agents.map(async (a) => {
-      const base = { ask_mode: a.askMode, modes: a.safeModes, roots: a.roots.slice(0, 8), protocol: 1, unattended: a.unattended, unattended_allowed: a.allowUnsafeModes };
       const support = this.attach.get(a.id);
+      const base = {
+        ask_mode: a.askMode,
+        modes: a.safeModes,
+        roots: a.roots.slice(0, 8),
+        protocol: 1,
+        unattended: a.unattended,
+        unattended_allowed: a.allowUnsafeModes,
+        ...support ? { watch_live: true } : {}
+      };
       const capabilities = support ? fitResumable(base, await support.resumable()) : base;
       return { agent_id: a.id, kind: a.kind, name: a.name, capabilities };
     }));
@@ -3432,7 +4123,7 @@ var Connector = class {
   // --- identity -------------------------------------------------------------------
   readIdentity() {
     try {
-      const raw = JSON.parse(fs14.readFileSync(identityFile(this.d.dirs), "utf8"));
+      const raw = JSON.parse(fs15.readFileSync(identityFile(this.d.dirs), "utf8"));
       if (isObject(raw) && raw.server === this.d.server && typeof raw.connector_id === "string") {
         return { server: raw.server, connector_id: raw.connector_id, cursor: typeof raw.cursor === "number" ? raw.cursor : 0, handled: Array.isArray(raw.handled) ? raw.handled.filter((x) => typeof x === "string") : [] };
       }
@@ -3443,9 +4134,9 @@ var Connector = class {
   writeIdentity() {
     const st = { server: this.d.server, connector_id: this.cid, cursor: this.ledger.cursor, handled: this.ledger.recentIds, ...this.rowRevoked ? { revoked: true } : {} };
     const file = identityFile(this.d.dirs);
-    fs14.mkdirSync(this.d.dirs.state, { recursive: true, mode: 448 });
-    fs14.writeFileSync(`${file}.tmp`, JSON.stringify(st), { mode: 384 });
-    fs14.renameSync(`${file}.tmp`, file);
+    fs15.mkdirSync(this.d.dirs.state, { recursive: true, mode: 448 });
+    fs15.writeFileSync(`${file}.tmp`, JSON.stringify(st), { mode: 384 });
+    fs15.renameSync(`${file}.tmp`, file);
   }
   /** Use the connector id this machine already has, or register a new one. */
   async identify(forceNew = false) {
@@ -3552,7 +4243,7 @@ var Connector = class {
   }
   async pauseWatcher() {
     while (!this.ctl.signal.aborted) {
-      const want = fs14.existsSync(pauseFile(this.d.dirs));
+      const want = fs15.existsSync(pauseFile(this.d.dirs));
       if (want && !this.paused) {
         this.paused = true;
         this.d.audit.record("paused");
@@ -3606,6 +4297,22 @@ var Connector = class {
       }
     }
   }
+  /** Report a change in the conversations on this machine (see {@link ConnectorTiming.sessionsWatchMs}) without waiting for the heartbeat. */
+  async sessionsWatcher() {
+    if (this.attach.size === 0) return;
+    while (!this.ctl.signal.aborted) {
+      let changed = false;
+      for (const support of this.attach.values()) {
+        try {
+          if (await support.poll()) changed = true;
+        } catch (e) {
+          this.d.log.warn("looking for changed sessions failed", { agent: support.agent.id, error: errMessage(e) });
+        }
+      }
+      if (changed && !this.paused) this.wakeHeartbeat?.();
+      await sleep(this.timing.sessionsWatchMs, this.ctl.signal);
+    }
+  }
   async heartbeater() {
     while (!this.ctl.signal.aborted) {
       await new Promise((resolve) => {
@@ -3673,6 +4380,7 @@ var Connector = class {
   async streamLoop() {
     let attempt = 0;
     let reconnect = false;
+    let lastRestartAt = -Infinity;
     while (!this.ctl.signal.aborted) {
       if (this.paused) {
         await sleep(this.timing.pausePollMs, this.ctl.signal);
@@ -3683,6 +4391,7 @@ var Connector = class {
         const sig = AbortSignal.any([this.ctl.signal, this.streamCtl.signal]);
         let got = false;
         this.lastFrame = "";
+        let restart = false;
         for await (const f of this.d.client.commands(this.cid, { lastEventId: this.ledger.highestSeen || void 0, signal: sig, watchdogMs: this.timing.watchdogMs })) {
           if (!got) {
             got = true;
@@ -3691,11 +4400,20 @@ var Connector = class {
           }
           this.onFrame(f, reconnect);
           if (f.event === "ready") reconnect = true;
+          if (f.event === "reconnect") {
+            restart = true;
+            break;
+          }
         }
         if (!this.ctl.signal.aborted && !this.paused) {
-          const why = this.lastFrame === "superseded" || this.lastFrame === "token_expired" ? this.lastFrame : "the server closed the stream (a Claw release or restart)";
+          const why = restart ? "restart" : this.lastFrame === "superseded" || this.lastFrame === "token_expired" ? this.lastFrame : "the server closed the stream (a Claw release or restart)";
           this.d.log.info("command stream ended by the server; reconnecting", { why });
           recordDisconnect(this.d.dirs, { reason: "server_closed", detail: why });
+          if (restart && Date.now() - lastRestartAt >= RESTART_RECONNECT_GAP_MS) {
+            lastRestartAt = Date.now();
+            attempt = 0;
+            continue;
+          }
         }
       } catch (e) {
         if (this.isRevocation(e)) return void await this.onRevoked(e);
@@ -3720,7 +4438,7 @@ var Connector = class {
   }
   /** Run until stopped or revoked. Always leaves no adapter process behind. */
   async run() {
-    fs14.mkdirSync(this.d.dirs.state, { recursive: true, mode: 448 });
+    fs15.mkdirSync(this.d.dirs.state, { recursive: true, mode: 448 });
     await this.registry.killAll();
     for (const p of this.store.takePending()) {
       this.d.audit.record("permission_orphaned", { session_id: p.session_id, action_id: p.action_id });
@@ -3729,32 +4447,33 @@ var Connector = class {
     const pidf = pidFile(this.d.dirs);
     let leftover = false;
     try {
-      fs14.readFileSync(pidf);
+      fs15.readFileSync(pidf);
       leftover = true;
     } catch {
     }
     if (leftover) {
       let last;
       try {
-        last = fs14.statSync(identityFile(this.d.dirs)).mtime.toISOString();
+        last = fs15.statSync(identityFile(this.d.dirs)).mtime.toISOString();
       } catch {
       }
       recordDisconnect(this.d.dirs, { reason: "process_died", detail: `the previous run ended without shutting down (killed, crashed, or the machine restarted)${last ? `; last heartbeat ${last}` : ""}`, ...last ? { at: last } : {} });
     }
-    fs14.writeFileSync(pidf, JSON.stringify({ pid: process.pid, start: processStart(process.pid) ?? "" }), { mode: 384 });
-    this.paused = fs14.existsSync(pauseFile(this.d.dirs));
+    fs15.writeFileSync(pidf, JSON.stringify({ pid: process.pid, start: processStart(process.pid) ?? "" }), { mode: 384 });
+    this.paused = fs15.existsSync(pauseFile(this.d.dirs));
     let result = "stopped";
     let failure = "";
     try {
       const up = await this.startup();
       if (up !== "ok") return result = up;
+      await this.manager.restoreReadOnly();
       this.d.audit.record("connector_online", {
         connector_id: this.cid,
         agents: this.d.config.agents.map((a) => a.id),
         paused: this.paused,
         unattended_agents: this.d.config.agents.filter((a) => a.unattended).map((a) => a.id)
       });
-      await Promise.all([this.sender(), this.heartbeater(), this.streamLoop(), this.pauseWatcher()]);
+      await Promise.all([this.sender(), this.heartbeater(), this.streamLoop(), this.pauseWatcher(), this.sessionsWatcher()]);
       result = this.revoked ? "revoked" : this.authFailed ? "auth_failed" : "stopped";
     } catch (e) {
       failure = errMessage(e);
@@ -3763,7 +4482,7 @@ var Connector = class {
       await this.manager.killAll(this.revoked ? "revoked" : "stopped").catch(() => void 0);
       const reason = this.revoked ? "revoked" : this.authFailed ? "auth_failed" : failure ? "failed" : this.paused ? "stopped_while_paused" : result;
       recordDisconnect(this.d.dirs, { reason, detail: this.authWhy || failure || void 0 });
-      fs14.rmSync(pidf, { force: true });
+      fs15.rmSync(pidf, { force: true });
     }
     return result;
   }
@@ -3779,10 +4498,10 @@ var Connector = class {
 };
 
 // src/service.ts
-import { spawn as spawn2, spawnSync } from "node:child_process";
-import fs15 from "node:fs";
+import { spawn as spawn3, spawnSync } from "node:child_process";
+import fs16 from "node:fs";
 import os5 from "node:os";
-import path16 from "node:path";
+import path17 from "node:path";
 import { fileURLToPath } from "node:url";
 import { parseArgs } from "node:util";
 var SUPERVISORS = ["systemd", "launchd", "script"];
@@ -3821,11 +4540,11 @@ function deps(ctx) {
     }),
     node: d.node ?? ctx.node ?? process.execPath,
     cli: d.cli ?? fileURLToPath(import.meta.url),
-    systemdBooted: d.systemdBooted ?? (() => fs15.existsSync("/run/systemd/system"))
+    systemdBooted: d.systemdBooted ?? (() => fs16.existsSync("/run/systemd/system"))
   };
 }
-var systemdUnitPath = (ctx, d) => path16.join(ctx.env.XDG_CONFIG_HOME?.trim() || path16.join(d.home, ".config"), "systemd", "user", UNIT);
-var launchdPlistPath = (d) => path16.join(d.home, "Library", "LaunchAgents", `${LABEL}.plist`);
+var systemdUnitPath = (ctx, d) => path17.join(ctx.env.XDG_CONFIG_HOME?.trim() || path17.join(d.home, ".config"), "systemd", "user", UNIT);
+var launchdPlistPath = (d) => path17.join(d.home, "Library", "LaunchAgents", `${LABEL}.plist`);
 function detectSupervisor(d) {
   if (d.platform === "darwin") return "launchd";
   if (!d.systemdBooted()) return "script";
@@ -3875,12 +4594,14 @@ StartLimitIntervalSec=0
 [Service]
 Type=simple
 ExecStart=${sdQuote(d.node)} ${sdQuote(d.cli)} run --supervised
+ExecStop=${sdQuote(d.node)} ${sdQuote(d.cli)} stop
 ${vars.map(([k, v]) => `Environment=${sdEnv(`${k}=${v}`)}`).join("\n")}
 Restart=on-failure
 RestartSec=${RESTART_SEC}
 # 78: revoked, sign-in refused, or no usable config. Restarting cannot help; "claw-connector login" can.
 RestartPreventExitStatus=${NEEDS_PERSON}
-# "claw-connector stop" and "systemctl --user stop" both end it cleanly (exit 0), which is not restarted.
+# "claw-connector stop" and "systemctl --user stop" (through ExecStop) both end it cleanly (exit 0), which is not
+# restarted. Any other SIGTERM ends a supervised run with exit 75, which is.
 KillMode=mixed
 TimeoutStopSec=20
 
@@ -3924,7 +4645,7 @@ exec ${sh(d.node)} ${sh(d.cli)} service ensure
 }
 function readPidRec(file) {
   try {
-    const raw = JSON.parse(fs15.readFileSync(file, "utf8"));
+    const raw = JSON.parse(fs16.readFileSync(file, "utf8"));
     if (isObject(raw) && typeof raw.pid === "number" && typeof raw.start === "string" && raw.start !== "") return { pid: raw.pid, start: raw.start };
   } catch {
   }
@@ -3944,8 +4665,8 @@ async function supervise(ctx, o = {}) {
     ctx.err(`a supervisor is already running (pid ${other})`);
     return 1;
   }
-  fs15.mkdirSync(ctx.dirs.state, { recursive: true, mode: 448 });
-  fs15.writeFileSync(pidf, JSON.stringify({ pid: process.pid, start: processStart(process.pid) ?? "" }), { mode: 384 });
+  fs16.mkdirSync(ctx.dirs.state, { recursive: true, mode: 448 });
+  fs16.writeFileSync(pidf, JSON.stringify({ pid: process.pid, start: processStart(process.pid) ?? "" }), { mode: 384 });
   let stopping2 = false;
   let child = null;
   const wake = new AbortController();
@@ -3960,7 +4681,7 @@ async function supervise(ctx, o = {}) {
   o.signal?.addEventListener("abort", () => onSig("SIGTERM"), { once: true });
   try {
     for (let round = 0; !stopping2; round++) {
-      child = spawn2(cmd, args, { stdio: ["ignore", "inherit", "inherit"], env: ctx.env });
+      child = spawn3(cmd, args, { stdio: ["ignore", "inherit", "inherit"], env: ctx.env });
       const c = child;
       const { code, signal } = await new Promise((resolve) => {
         c.once("exit", (code2, signal2) => resolve({ code: code2, signal: signal2 }));
@@ -3989,7 +4710,7 @@ async function supervise(ctx, o = {}) {
   } finally {
     for (const [s, h] of handlers) process.off(s, h);
     const rec = readPidRec(pidf);
-    if (rec?.pid === process.pid) fs15.rmSync(pidf, { force: true });
+    if (rec?.pid === process.pid) fs16.rmSync(pidf, { force: true });
   }
 }
 async function cmdSupervise(_args, ctx) {
@@ -4011,14 +4732,14 @@ async function ensure(ctx, d, h) {
     ctx.out(`the connector is running (pid ${run2}) without the supervisor; leaving it`);
     return 0;
   }
-  fs15.mkdirSync(ctx.dirs.state, { recursive: true, mode: 448 });
-  const log = fs15.openSync(runLogFile(ctx.dirs), "a", 384);
+  fs16.mkdirSync(ctx.dirs.state, { recursive: true, mode: 448 });
+  const log = fs16.openSync(runLogFile(ctx.dirs), "a", 384);
   try {
-    const p = spawn2(d.node, [d.cli, "supervise"], { detached: true, cwd: d.home, stdio: ["ignore", log, log], env: ctx.env });
+    const p = spawn3(d.node, [d.cli, "supervise"], { detached: true, cwd: d.home, stdio: ["ignore", log, log], env: ctx.env });
     p.unref();
     ctx.out(`started the supervisor (pid ${p.pid}); log: ${runLogFile(ctx.dirs)}`);
   } finally {
-    fs15.closeSync(log);
+    fs16.closeSync(log);
   }
   return 0;
 }
@@ -4048,7 +4769,7 @@ async function cmdService(args, ctx, h) {
 }
 function installedSupervisor(ctx) {
   try {
-    const raw = JSON.parse(fs15.readFileSync(serviceFile(ctx.dirs), "utf8"));
+    const raw = JSON.parse(fs16.readFileSync(serviceFile(ctx.dirs), "utf8"));
     if (isObject(raw) && typeof raw.supervisor === "string" && SUPERVISORS.includes(raw.supervisor)) return raw.supervisor;
   } catch {
   }
@@ -4069,10 +4790,10 @@ function startAfterLogin(ctx, h) {
   ctx.out(r.code === 0 ? `started the ${sup} service again` : `could not start the ${sup} service (${r.out || `exit ${r.code}`}); run: claw-connector service install`);
 }
 function writeFile600(file, body, mode = 384) {
-  fs15.mkdirSync(path16.dirname(file), { recursive: true, mode: 448 });
+  fs16.mkdirSync(path17.dirname(file), { recursive: true, mode: 448 });
   const tmp = `${file}.${process.pid}.tmp`;
-  fs15.writeFileSync(tmp, body, { mode });
-  fs15.renameSync(tmp, file);
+  fs16.writeFileSync(tmp, body, { mode });
+  fs16.renameSync(tmp, file);
 }
 async function install(ctx, d, h, sup, extra) {
   const problem = h.preflight(ctx);
@@ -4080,7 +4801,7 @@ async function install(ctx, d, h, sup, extra) {
     ctx.err(`cannot install the service yet: ${problem}`);
     return NEEDS_PERSON;
   }
-  if (!fs15.existsSync(d.cli)) {
+  if (!fs16.existsSync(d.cli)) {
     ctx.err(`${d.cli} does not exist (a source checkout needs "npm run build" first)`);
     return 1;
   }
@@ -4144,19 +4865,19 @@ function recordInstalled(ctx, sup) {
   writeFile600(serviceFile(ctx.dirs), JSON.stringify({ supervisor: sup, installed_at: (/* @__PURE__ */ new Date()).toISOString() }));
 }
 async function uninstall(ctx, d, sup) {
-  fs15.rmSync(serviceFile(ctx.dirs), { force: true });
+  fs16.rmSync(serviceFile(ctx.dirs), { force: true });
   if (sup === "systemd") {
     const unit = systemdUnitPath(ctx, d);
     d.exec("systemctl", ["--user", "disable", "--now", UNIT]);
-    const had = fs15.existsSync(unit);
-    fs15.rmSync(unit, { force: true });
+    const had = fs16.existsSync(unit);
+    fs16.rmSync(unit, { force: true });
     d.exec("systemctl", ["--user", "daemon-reload"]);
     ctx.out(had ? `stopped and removed ${unit}` : `no unit at ${unit}`);
   } else if (sup === "launchd") {
     const plist = launchdPlistPath(d);
     d.exec("launchctl", ["bootout", `gui/${d.uid}/${LABEL}`]);
-    const had = fs15.existsSync(plist);
-    fs15.rmSync(plist, { force: true });
+    const had = fs16.existsSync(plist);
+    fs16.rmSync(plist, { force: true });
     ctx.out(had ? `stopped and removed ${plist}` : `no LaunchAgent at ${plist}`);
   } else {
     const pid = supervisorPid(ctx);
@@ -4166,8 +4887,8 @@ async function uninstall(ctx, d, sup) {
       while (Date.now() < end && isAlive(pid) && processStart(pid) !== null) await sleep(100);
     }
     const script = keepaliveFile(ctx.dirs);
-    const had = fs15.existsSync(script);
-    fs15.rmSync(script, { force: true });
+    const had = fs16.existsSync(script);
+    fs16.rmSync(script, { force: true });
     ctx.out(`${pid !== null ? `stopped the supervisor (pid ${pid}) and the connector; ` : ""}${had ? `removed ${script}` : "no keep-alive script"}. Remove the @reboot and */5 lines that call it.`);
   }
   return 0;
@@ -4200,15 +4921,101 @@ function status(ctx, d, h, json) {
 }
 
 // src/version.ts
-var VERSION = "0.1.4";
+var VERSION = "0.1.5";
+
+// src/probe.ts
+import fs17 from "node:fs";
+import os6 from "node:os";
+import path18 from "node:path";
+var BYPASS_FIX = `Claude Code offers bypassPermissions to root only with IS_SANDBOX set (the connector sets it for an agent with approval = "never" unless its env names IS_SANDBOX), and never when permissions.disableBypassPermissionsMode is "disable" in its settings; fix that, or set approval = "ask" on this agent`;
+function modesOf(res) {
+  const m = isObject(res.modes) ? res.modes : null;
+  if (m && Array.isArray(m.availableModes)) return m.availableModes.filter((x) => isObject(x) && typeof x.id === "string").map((x) => x.id);
+  const opt = Array.isArray(res.configOptions) ? res.configOptions.find((o) => isObject(o) && o.category === "mode") : null;
+  if (isObject(opt) && Array.isArray(opt.options)) return opt.options.filter((x) => isObject(x) && typeof x.value === "string").map((x) => x.value);
+  return null;
+}
+var probeDir = (a) => a.roots.find((r) => {
+  try {
+    return fs17.statSync(r).isDirectory();
+  } catch {
+    return false;
+  }
+}) ?? os6.homedir();
+async function probeAgent(a, o) {
+  const cwd = probeDir(a);
+  const out = { agent: a.id, cwd, ok: false, modes: null, problems: [], notes: [] };
+  if (!a.roots.includes(cwd)) out.notes.push(`no root of this agent exists yet (${a.roots.join(", ")}); probed in ${cwd}`);
+  const tmp = fs17.mkdtempSync(path18.join(os6.tmpdir(), "claw-probe-"));
+  const registry = new ChildRegistry(path18.join(tmp, "children.json"));
+  const timeoutMs = o.timeoutMs ?? 12e4;
+  let adapter = null;
+  try {
+    adapter = await AdapterProcess.start({
+      cfg: a,
+      registry,
+      sessionId: `probe-${a.id}`,
+      cwd,
+      logFile: path18.join(o.logDir, `adapter-${a.id}.log`),
+      version: o.version,
+      initTimeoutMs: timeoutMs,
+      hooks: {
+        onUpdate: () => {
+        },
+        onNotification: () => {
+        },
+        onStderr: () => {
+        },
+        onExit: () => {
+        },
+        // No prompt is sent, so nothing should ask; anything that does is refused.
+        onPermission: async () => ({ outcome: { outcome: "cancelled" } }),
+        onExtension: async () => ({})
+      }
+    });
+    const res = await adapter.request("session/new", { cwd, mcpServers: [], ...claudeSessionMeta(a) }, timeoutMs);
+    out.modes = modesOf(res);
+    if (out.modes === null || out.modes.length === 0) {
+      out.notes.push("the adapter lists no modes; the connector sets the ask mode and reads it back when a session opens");
+      out.ok = true;
+      return out;
+    }
+    if (!out.modes.includes(a.askMode)) {
+      out.problems.push(`sessions will be refused (mode_unavailable): this agent's sessions run in ${a.askMode}${a.unattended ? ` (approval = "never")` : ""}, but the adapter offers only ${out.modes.join(", ")}${a.askMode === "bypassPermissions" ? `. ${BYPASS_FIX}` : ""}`);
+    }
+    const missing = a.safeModes.filter((m) => m !== a.askMode && !out.modes.includes(m));
+    if (missing.length) out.notes.push(`safe_modes lists ${missing.join(", ")}, which the adapter does not offer here; a phone that picks one is refused`);
+    out.ok = out.problems.length === 0;
+  } catch (e) {
+    out.problems.push(`the adapter did not open a session: ${errMessage(e)} (its log: ${path18.join(o.logDir, `adapter-${a.id}.log`)})`);
+  } finally {
+    await adapter?.kill().catch(() => void 0);
+    fs17.rmSync(tmp, { recursive: true, force: true });
+  }
+  return out;
+}
+var probeAgents = async (agents, o) => {
+  const out = [];
+  for (const a of agents) out.push(await probeAgent(a, o));
+  return out;
+};
+function probeLines(results) {
+  const lines = [];
+  for (const r of results) {
+    lines.push(`${r.agent}: ${r.ok ? "ok" : "PROBLEM"}${r.modes ? ` (modes: ${r.modes.join(", ")})` : ""}`);
+    for (const p of r.problems) lines.push(`  problem: ${p}`);
+    for (const n of r.notes) lines.push(`  note: ${n}`);
+  }
+  return lines;
+}
 
 // src/commands.ts
-var EXIT = { ok: 0, failure: 1, usage: 2, needsPerson: 78, revoked: 78 };
+var EXIT = { ok: 0, failure: 1, usage: 2, terminated: 75, needsPerson: 78, revoked: 78 };
 var HELP = `claw-connector ${VERSION}: connect the coding agents on this machine to Claw (outbound HTTPS only).
 
 Usage: claw-connector <command> [options]
 
-  init [--approval ask|never | --approval AGENT=ask|never ...] [--no-hooks]
+  init [--approval ask|never | --approval AGENT=ask|never ...] [--no-hooks] [--no-probe]
                            write a sample agents.toml, and install the Claude Code session hooks (see "hooks"; --no-hooks
                            skips that). Agents ask before every write and command by default;
                            "--approval never" (or "--approval claude=never") lets phone sessions run like your
@@ -4226,6 +5033,9 @@ Usage: claw-connector <command> [options]
                            after exit 78. systemd --user on Linux, launchd on macOS; "script" (containers without
                            systemd) writes a keep-alive script for a startup hook and a 5-minute cron line
   status [--json]          what is running, signed in, paused, the last disconnect and why
+  doctor [--agent ID] [--json]
+                           start each agent's adapter, open a session (no prompt) and check that it offers the
+                           modes agents.toml needs, so a phone session is not refused; init runs it too
   pause                    stop every agent now and stay offline until "resume"
   resume                   undo "pause"
   stop                     stop the running connector and every agent it started
@@ -4235,16 +5045,19 @@ Usage: claw-connector <command> [options]
 Files: ${"$"}XDG_CONFIG_HOME/claw-connector (agents.toml, credentials.json) and ${"$"}XDG_STATE_HOME/claw-connector
 (audit.jsonl, logs, outbox); set CLAW_CONNECTOR_HOME to keep everything under one directory.
 `;
-function loadCfg(ctx) {
-  return loadConfig(configFile(ctx.dirs), { hostname: ctx.hostname ?? os6.hostname() });
+function loadCfg(ctx, notes = []) {
+  const cfg = loadConfig(configFile(ctx.dirs), { hostname: ctx.hostname ?? os7.hostname() });
+  notes.push(...applyRootSandbox(cfg.agents, ctx.env, { euid: ctx.euid }));
+  return cfg;
 }
-var noAsk = (ctx, cfg) => noAskWarnings(cfg.agents, ctx.env, { managedFile: ctx.claudeManagedSettings, euid: ctx.euid });
+var noAsk = (ctx, cfg) => bypassUnavailableWarnings(cfg.agents, ctx.env, { managedFile: ctx.claudeManagedSettings, euid: ctx.euid });
 function serverUrl(ctx, flag, cfg, creds) {
   const v = flag ?? ctx.env.CLAW_URL ?? cfg?.server ?? creds?.server ?? null;
   return v ? secureUrl(v.trim(), "the Claw server URL") : null;
 }
 async function main(argv, ctx) {
   const [cmd, ...rest] = argv;
+  useAdapterStore(new AdapterStore(adaptersDir(ctx.dirs.state), { autoInstall: ctx.installAdapters === true }));
   try {
     switch (cmd) {
       case void 0:
@@ -4269,11 +5082,14 @@ async function main(argv, ctx) {
         return code === EXIT.needsPerson && ctx.env.CLAW_CONNECTOR_SUPERVISOR === "launchd" ? EXIT.ok : code;
       }
       case "service":
+        if (rest[0] === "install") await installAdapters(ctx, false);
         return await cmdService(rest, ctx, serviceHelpers);
       case "supervise":
         return await cmdSupervise(rest, ctx);
       case "status":
         return cmdStatus(rest, ctx);
+      case "doctor":
+        return await cmdDoctor(rest, ctx);
       case "pause":
         return await cmdPause(ctx);
       case "resume":
@@ -4313,16 +5129,16 @@ function parseApproval(values) {
   return out;
 }
 async function cmdInit(args, ctx) {
-  const { values } = parseArgs2({ args, strict: true, options: { approval: { type: "string", multiple: true }, "no-hooks": { type: "boolean" } } });
+  const { values } = parseArgs2({ args, strict: true, options: { approval: { type: "string", multiple: true }, "no-hooks": { type: "boolean" }, "no-probe": { type: "boolean" } } });
   const approval = parseApproval(values.approval ?? []);
   if (typeof approval === "string") {
     ctx.err(approval);
     return EXIT.usage;
   }
   const file = configFile(ctx.dirs);
-  fs16.mkdirSync(path17.dirname(file), { recursive: true, mode: 448 });
+  fs18.mkdirSync(path19.dirname(file), { recursive: true, mode: 448 });
   try {
-    fs16.writeFileSync(file, sampleConfig(approval), { mode: 384, flag: "wx" });
+    fs18.writeFileSync(file, sampleConfig(approval), { mode: 384, flag: "wx" });
     ctx.out(`wrote ${file}: edit the roots (the directories an agent may work in), then run: claw-connector login`);
     const { unattended, parked } = sampleApprovals(approval);
     ctx.out(unattended.length ? `no per-step approval for: ${unattended.join(", ")}. Those agents write files and run commands without asking; the phone shows such a session as unattended. To go back, set approval = "ask" on the agent.` : `every agent in this file asks before it writes a file or runs a command. To let phone sessions run like your terminal instead: claw-connector init --approval never (on a new file), or set approval = "never" on an agent.`);
@@ -4333,11 +5149,54 @@ async function cmdInit(args, ctx) {
   }
   if (!values["no-hooks"]) {
     const dir = defaultClaudeDir(ctx);
-    if (!fs16.existsSync(dir)) ctx.out(`no Claude Code directory at ${dir}; once you use Claude Code, run: claw-connector hooks install`);
+    if (!fs18.existsSync(dir)) ctx.out(`no Claude Code directory at ${dir}; once you use Claude Code, run: claw-connector hooks install`);
     else installForInit(ctx, dir);
   }
+  await installAdapters(ctx, true);
+  if (ctx.probe && !values["no-probe"]) {
+    try {
+      const cfg = loadCfg(ctx);
+      ctx.out("checking each agent's adapter (claw-connector doctor; skip with --no-probe):");
+      for (const l of probeLines(await ctx.probe(cfg.agents, { logDir: logDir(ctx.dirs), version: VERSION }))) ctx.out(l);
+    } catch (e) {
+      ctx.out(`could not check the agents yet: ${errMessage(e)}; after editing agents.toml run: claw-connector doctor`);
+    }
+  }
   return EXIT.ok;
 }
+async function cmdDoctor(args, ctx) {
+  const { values } = parseArgs2({ args, strict: true, options: { agent: { type: "string" }, json: { type: "boolean" } } });
+  const notes = [];
+  const cfg = loadCfg(ctx, notes);
+  const agents = values.agent ? cfg.agents.filter((a) => a.id === values.agent) : cfg.agents;
+  if (agents.length === 0) {
+    ctx.err(values.agent ? `no agent ${JSON.stringify(values.agent)} in agents.toml` : "agents.toml defines no agents; add an [[agents]] table");
+    return EXIT.failure;
+  }
+  const warnings = noAsk(ctx, { ...cfg, agents });
+  const results = await (ctx.probe ?? probeAgents)(agents, { logDir: logDir(ctx.dirs), version: VERSION });
+  const ok = results.every((r) => r.ok);
+  if (values.json) {
+    ctx.out(JSON.stringify({ version: VERSION, ok, notes, warnings, agents: results }, null, 2));
+  } else {
+    for (const n of notes) ctx.out(`note: ${n}`);
+    for (const w of warnings) ctx.out(`warning: ${w}`);
+    for (const l of probeLines(results)) ctx.out(l);
+  }
+  return ok ? EXIT.ok : EXIT.failure;
+}
+async function installAdapters(ctx, initFallback) {
+  const store2 = adapterStore();
+  if (!store2 || !ctx.installAdapters) return;
+  let agents;
+  try {
+    agents = loadCfg(ctx).agents;
+  } catch {
+    if (!initFallback) return;
+    agents = SAMPLE_ACTIVE.map((id) => ({ command: PRESETS[id].command, args: PRESETS[id].args, env: {} }));
+  }
+  await installAll(store2, agents, ctx.env, (l) => ctx.out(`adapters: ${l}`));
+}
 function installForInit(ctx, dir) {
   try {
     ctx.out(describeInstall(dir, installOne(ctx, dir).changed));
@@ -4345,19 +5204,19 @@ function installForInit(ctx, dir) {
     ctx.err(`hooks: ${errMessage(e)} (everything else is set up; fix it and run: claw-connector hooks install)`);
   }
 }
-var defaultClaudeDir = (ctx) => path17.resolve(ctx.env.CLAUDE_CONFIG_DIR?.trim() || path17.join(os6.homedir(), ".claude"));
+var defaultClaudeDir = (ctx) => path19.resolve(ctx.env.CLAUDE_CONFIG_DIR?.trim() || path19.join(os7.homedir(), ".claude"));
 function claudeDirs(ctx, flag) {
-  if (flag !== void 0) return [path17.resolve(flag)];
+  if (flag !== void 0) return [path19.resolve(flag)];
   let dirs = [];
   try {
-    dirs = loadCfg(ctx).agents.filter((a) => a.attach).map((a) => path17.resolve(a.env.CLAUDE_CONFIG_DIR ?? ctx.env.CLAUDE_CONFIG_DIR?.trim() ?? path17.join(os6.homedir(), ".claude")));
+    dirs = loadCfg(ctx).agents.filter((a) => a.attach).map((a) => path19.resolve(a.env.CLAUDE_CONFIG_DIR ?? ctx.env.CLAUDE_CONFIG_DIR?.trim() ?? path19.join(os7.homedir(), ".claude")));
   } catch {
   }
   return dirs.length ? [...new Set(dirs)] : [defaultClaudeDir(ctx)];
 }
 function hookScript(ctx) {
   const script = ctx.hookScript ?? fileURLToPath2(new URL("./terminal-hook.js", import.meta.url));
-  if (!fs16.existsSync(script)) throw new HooksError(`${script} does not exist (a source checkout needs "npm run build" first)`);
+  if (!fs18.existsSync(script)) throw new HooksError(`${script} does not exist (a source checkout needs "npm run build" first)`);
   return script;
 }
 function installOne(ctx, dir) {
@@ -4377,7 +5236,7 @@ function cmdHooks(args, ctx) {
   for (const dir of dirs) {
     try {
       if (sub === "install") {
-        if (values["config-dir"] === void 0 && !fs16.existsSync(dir)) {
+        if (values["config-dir"] === void 0 && !fs18.existsSync(dir)) {
           ctx.err(`no Claude Code directory at ${dir}; pass --config-dir to name one`);
           code = EXIT.failure;
           continue;
@@ -4402,11 +5261,11 @@ function forgetRevokedIdentity(ctx) {
   const file = identityFile(ctx.dirs);
   let revoked = false;
   try {
-    const raw = JSON.parse(fs16.readFileSync(file, "utf8"));
+    const raw = JSON.parse(fs18.readFileSync(file, "utf8"));
     revoked = isObject(raw) && raw.revoked === true;
   } catch {
   }
-  if (revoked) fs16.rmSync(file, { force: true });
+  if (revoked) fs18.rmSync(file, { force: true });
 }
 async function cmdLogin(args, ctx) {
   const { values } = parseArgs2({
@@ -4441,7 +5300,7 @@ async function cmdLogin(args, ctx) {
     ctx.err("login needs --identity-url <identity service URL> (or CLAW_IDENTITY_URL, or identity_url = in agents.toml)");
     return EXIT.usage;
   }
-  const deviceName = values.name ?? cfg?.name ?? ctx.hostname ?? os6.hostname();
+  const deviceName = values.name ?? cfg?.name ?? ctx.hostname ?? os7.hostname();
   const tok = await deviceLogin({ identityUrl, deviceName, fetch: ctx.fetch, print: ctx.out });
   saveCredentials(file, {
     v: 1,
@@ -4461,14 +5320,14 @@ async function cmdLogin(args, ctx) {
 }
 function runningPid(ctx) {
   try {
-    const raw = JSON.parse(fs16.readFileSync(pidFile(ctx.dirs), "utf8"));
+    const raw = JSON.parse(fs18.readFileSync(pidFile(ctx.dirs), "utf8"));
     if (isObject(raw) && typeof raw.pid === "number" && typeof raw.start === "string" && raw.start !== "" && processStart(raw.pid) === raw.start) return raw.pid;
   } catch {
   }
   return null;
 }
 async function cmdRun(args, ctx) {
-  parseArgs2({ args, strict: true, options: { supervised: { type: "boolean" } } });
+  const { values: runFlags } = parseArgs2({ args, strict: true, options: { supervised: { type: "boolean" } } });
   {
     const nl = needsLogin(ctx.dirs);
     if (nl) {
@@ -4478,8 +5337,9 @@ async function cmdRun(args, ctx) {
   }
   let cfg;
   let creds;
+  const notes = [];
   try {
-    cfg = loadCfg(ctx);
+    cfg = loadCfg(ctx, notes);
     creds = loadCredentials(credentialsFile(ctx.dirs));
   } catch (e) {
     if (e instanceof ConfigError || e instanceof CredentialsError) {
@@ -4507,8 +5367,10 @@ async function cmdRun(args, ctx) {
   const log = stderrLogger();
   const audit = fileAudit(auditFile(ctx.dirs));
   const connector2 = new Connector({ config: cfg, dirs: ctx.dirs, client: client2, server, audit, log, version: VERSION, timing: ctx.timing });
+  if (ctx.installAdapters) for (const { pkg, env } of pinnedOf(cfg.agents, ctx.env)) void adapterStore()?.install(pkg, env, (l) => ctx.out(`adapters: ${l}`));
   ctx.onConnector?.(connector2);
   ctx.out(`connecting ${cfg.agents.map((a) => a.unattended ? `${a.id} (no per-step approval)` : a.id).join(", ")} to ${server} as "${cfg.name}"`);
+  for (const n of notes) ctx.out(`note: ${n}`);
   for (const w of noAsk(ctx, cfg)) ctx.out(`warning: ${w}`);
   try {
     const result = await connector2.run();
@@ -4522,6 +5384,10 @@ async function cmdRun(args, ctx) {
       ctx.err(`Claw keeps refusing this sign-in (${connector2.authFailure}): every agent was stopped. Run login again.`);
       return EXIT.needsPerson;
     }
+    if (runFlags.supervised && !takeStopRequest(ctx)) {
+      ctx.err(`${(/* @__PURE__ */ new Date()).toISOString()} stopped by a signal that did not come from "claw-connector stop"; exit ${EXIT.terminated}, so the supervisor starts it again`);
+      return EXIT.terminated;
+    }
     return EXIT.ok;
   } catch (e) {
     if (isAuthRefusal(e) || e instanceof RevokedError || e instanceof GrantRevokedError || e instanceof CredentialsError) {
@@ -4559,7 +5425,7 @@ function cmdStatus(args, ctx) {
   }
   let connectorId = null;
   try {
-    const raw = JSON.parse(fs16.readFileSync(identityFile(ctx.dirs), "utf8"));
+    const raw = JSON.parse(fs18.readFileSync(identityFile(ctx.dirs), "utf8"));
     if (isObject(raw) && typeof raw.connector_id === "string") connectorId = raw.connector_id;
   } catch {
   }
@@ -4567,7 +5433,7 @@ function cmdStatus(args, ctx) {
   const status2 = {
     version: VERSION,
     running: runningPid(ctx),
-    paused: fs16.existsSync(pauseFile(ctx.dirs)),
+    paused: fs18.existsSync(pauseFile(ctx.dirs)),
     signed_in: creds ? { kind: creds.kind, server: creds.server, device_name: creds.device_name ?? null } : null,
     connector_id: connectorId,
     agents,
@@ -4596,8 +5462,8 @@ function cmdStatus(args, ctx) {
   return EXIT.ok;
 }
 async function cmdPause(ctx) {
-  fs16.mkdirSync(ctx.dirs.state, { recursive: true, mode: 448 });
-  fs16.writeFileSync(pauseFile(ctx.dirs), (/* @__PURE__ */ new Date()).toISOString() + "\n", { mode: 384 });
+  fs18.mkdirSync(ctx.dirs.state, { recursive: true, mode: 448 });
+  fs18.writeFileSync(pauseFile(ctx.dirs), (/* @__PURE__ */ new Date()).toISOString() + "\n", { mode: 384 });
   if (runningPid(ctx) === null) {
     const left = await new ChildRegistry(childrenFile(ctx.dirs)).killAll();
     ctx.out(`paused (the connector is not running${left.killed.length ? `; stopped ${left.killed.length} leftover agent process group(s)` : ""})`);
@@ -4607,13 +5473,15 @@ async function cmdPause(ctx) {
   return EXIT.ok;
 }
 function cmdResume(ctx) {
-  fs16.rmSync(pauseFile(ctx.dirs), { force: true });
+  fs18.rmSync(pauseFile(ctx.dirs), { force: true });
   ctx.out(runningPid(ctx) === null ? "resumed; start it with: claw-connector run" : "resumed: the running connector reconnects now");
   return EXIT.ok;
 }
 async function cmdStop(ctx, quiet = false) {
   const pid = runningPid(ctx);
   if (pid !== null) {
+    fs18.mkdirSync(ctx.dirs.state, { recursive: true, mode: 448 });
+    fs18.writeFileSync(stopRequestFile(ctx.dirs), JSON.stringify({ pid, start: processStart(pid) ?? "", at: (/* @__PURE__ */ new Date()).toISOString() }), { mode: 384 });
     process.kill(pid, "SIGTERM");
     const deadline = Date.now() + 15e3;
     while (Date.now() < deadline && isAlive(pid) && processStart(pid) !== null) await sleep(100);
@@ -4621,14 +5489,27 @@ async function cmdStop(ctx, quiet = false) {
       process.kill(pid, "SIGKILL");
       if (!quiet) ctx.out(`the connector (pid ${pid}) did not stop in 15 s and was killed`);
     }
+    fs18.rmSync(stopRequestFile(ctx.dirs), { force: true });
   }
   const left = await new ChildRegistry(childrenFile(ctx.dirs)).killAll();
   if (!quiet) ctx.out(pid === null ? `no connector running${left.killed.length ? `; stopped ${left.killed.length} leftover agent process group(s)` : ""}` : `stopped the connector${left.killed.length ? ` and ${left.killed.length} leftover agent process group(s)` : ""}`);
   return EXIT.ok;
 }
+function takeStopRequest(ctx) {
+  const file = stopRequestFile(ctx.dirs);
+  let mine = false;
+  try {
+    const raw = JSON.parse(fs18.readFileSync(file, "utf8"));
+    mine = isObject(raw) && raw.pid === process.pid && raw.start === (processStart(process.pid) ?? "");
+  } catch {
+    return false;
+  }
+  if (mine) fs18.rmSync(file, { force: true });
+  return mine;
+}
 function storedConnector(ctx) {
   try {
-    const raw = JSON.parse(fs16.readFileSync(identityFile(ctx.dirs), "utf8"));
+    const raw = JSON.parse(fs18.readFileSync(identityFile(ctx.dirs), "utf8"));
     if (isObject(raw) && typeof raw.server === "string" && typeof raw.connector_id === "string") {
       return { server: raw.server, connector_id: raw.connector_id, revoked: raw.revoked === true };
     }
@@ -4700,8 +5581,8 @@ async function cmdLogout(ctx) {
       ctx.err(`could not revoke the sign-in at the identity service (${errMessage(e)}); it was removed from this machine`);
     }
   }
-  fs16.rmSync(file, { force: true });
-  if (rowGone) fs16.rmSync(identityFile(ctx.dirs), { force: true });
+  fs18.rmSync(file, { force: true });
+  if (rowGone) fs18.rmSync(identityFile(ctx.dirs), { force: true });
   else forgetRevokedIdentity(ctx);
   if (row && notRevoked !== null) {
     ctx.err(`signed out on this machine, but connector ${row.connector_id} was NOT revoked at Claw (${notRevoked}).`);
@@ -4742,6 +5623,8 @@ main(process.argv.slice(2), {
   env: process.env,
   out: (l) => process.stdout.write(l + "\n"),
   err: (l) => process.stderr.write(l + "\n"),
+  probe: probeAgents,
+  installAdapters: true,
   onConnector: (c) => {
     connector = c;
     for (const sig of ["SIGTERM", "SIGINT", "SIGHUP"]) process.on(sig, onSignal);