@primusclaw/connector 0.1.4 → 0.1.6

package/dist/cli.js

@@ -1,16 +1,300 @@
 #!/usr/bin/env node
 
+// src/cli.ts
+import { fileURLToPath as fileURLToPath3 } from "node:url";
+
 // src/commands.ts
-import fs16 from "node:fs";
-import os6 from "node:os";
-import path17 from "node:path";
+import fs19 from "node:fs";
+import os9 from "node:os";
+import path21 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 +342,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 +358,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 +388,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 +482,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 +566,11 @@ var RevokedError = class extends Error {
   }
 };
 var HttpError = class extends Error {
-  constructor(status2, code, path18) {
-    super(`${path18} answered ${status2} ${code}`);
+  constructor(status2, code, path22) {
+    super(`${path22} answered ${status2} ${code}`);
     this.status = status2;
     this.code = code;
-    this.path = path18;
+    this.path = path22;
   }
   status;
   code;
@@ -363,8 +594,8 @@ var ClawClient = class {
       ...extra
     };
   }
-  async send(method, path18, body, signal) {
-    const url = this.o.server + path18;
+  async send(method, path22, body, signal) {
+    const url = this.o.server + path22;
     for (let attempt = 0; ; attempt++) {
       const headers = await this.headers(body === void 0 ? {} : { "content-type": "application/json" });
       let res;
@@ -376,7 +607,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} ${path22}: ${errMessage(e)}`);
       }
       if (res.status !== 401) return res;
       const err = await errorCode(res);
@@ -385,12 +616,12 @@ var ClawClient = class {
         this.o.tokens.invalidate();
         continue;
       }
-      throw new HttpError(401, err, path18);
+      throw new HttpError(401, err, path22);
     }
   }
-  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, path22, body) {
+    const res = await this.send(method, path22, body);
+    if (!res.ok) throw new HttpError(res.status, await errorCode(res), path22);
     const parsed = await res.json().catch(() => null);
     return isObject(parsed) && isObject(parsed.data) ? parsed.data : {};
   }
@@ -439,21 +670,21 @@ var ClawClient = class {
     };
     try {
       arm();
-      const path18 = `/v1/remote-agents/connectors/${cid}/commands`;
+      const path22 = `/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 + path22, { 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 ${path22}: ${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, path22);
       }
-      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), path22);
       try {
         for await (const frame of readSse(res.body, arm)) yield frame;
       } catch (e) {
@@ -477,55 +708,6 @@ import fs4 from "node:fs";
 import os from "node:os";
 import path4 from "node:path";
 import { parse as parseToml } from "smol-toml";
-
-// src/roots.ts
-import fs3 from "node:fs";
-import path3 from "node:path";
-function realRoot(root) {
-  try {
-    return fs3.realpathSync.native(root);
-  } catch {
-    return null;
-  }
-}
-var inside = (child, root) => child === root || child.startsWith(root.endsWith(path3.sep) ? root : root + path3.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" };
-  let real;
-  try {
-    real = fs3.realpathSync.native(cwd);
-  } catch {
-    return { ok: false, reason: "cwd_not_found" };
-  }
-  try {
-    if (!fs3.statSync(real).isDirectory()) return { ok: false, reason: "cwd_not_directory" };
-  } catch {
-    return { ok: false, reason: "cwd_not_found" };
-  }
-  for (const root of roots) {
-    const r = realRoot(root);
-    if (r && inside(real, r)) return { ok: true, real };
-  }
-  return { ok: false, reason: "cwd_outside_roots" };
-}
-function relativeInside(p, cwd) {
-  const abs = path3.resolve(cwd, p);
-  let real;
-  try {
-    real = fs3.realpathSync.native(abs);
-  } catch {
-    try {
-      real = path3.join(fs3.realpathSync.native(path3.dirname(abs)), path3.basename(abs));
-    } catch {
-      return null;
-    }
-  }
-  if (!inside(real, cwd)) return null;
-  return path3.relative(cwd, real).split(path3.sep).join("/");
-}
-
-// src/config.ts
 var ConfigError = class extends Error {
   constructor(problems) {
     super(`agents.toml: ${problems.join("; ")}`);
@@ -541,7 +723,8 @@ var PRESETS = {
     args: ["-y", "@agentclientprotocol/claude-agent-acp@0.99.0"],
     askMode: "default",
     safeModes: ["default", "plan"],
-    unattended: { askMode: "bypassPermissions" }
+    unattended: { askMode: "bypassPermissions" },
+    readOnly: ["plan"]
   },
   // Existing Claude Code sessions, taken over from the phone. The kind is the opaque label a chat client picks an icon
   // from; it says what the entry is for, not which product serves it. Same adapter and same ask mode as `claude`.
@@ -553,7 +736,8 @@ var PRESETS = {
     askMode: "default",
     safeModes: ["default", "plan"],
     attach: true,
-    unattended: { askMode: "bypassPermissions" }
+    unattended: { askMode: "bypassPermissions" },
+    readOnly: ["plan"]
   },
   codex: {
     kind: "codex",
@@ -571,7 +755,8 @@ var PRESETS = {
     args: ["acp"],
     askMode: "ask",
     safeModes: ["ask", "plan"],
-    unattended: { askMode: "agent", args: ["--force", "acp"] }
+    unattended: { askMode: "agent", args: ["--force", "acp"] },
+    readOnly: ["ask", "plan"]
   }
 };
 var ID_RE = /^[A-Za-z0-9._-]{1,64}$/;
@@ -656,7 +841,6 @@ function parseConfig(text, defaults = {}) {
     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`);
-      else if (!realRoot(r)) problems.push(`${label}: root ${r} does not exist`);
     }
     const env = {};
     if (raw.env !== void 0) {
@@ -692,13 +876,56 @@ function parseConfig(text, defaults = {}) {
       askingModes: [...asking],
       allowUnsafeModes: allowUnsafe,
       unattended: !asking.has(askMode),
+      // What the preset measured; a custom agent declares nothing here.
+      readOnlyModes: [...preset?.readOnly ?? []],
       autoAllow: [...globalAllow, ...own],
       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) => path4.resolve(expandHome(a.env.CLAUDE_CONFIG_DIR ?? process.env.CLAUDE_CONFIG_DIR ?? path4.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)) {
@@ -734,7 +961,9 @@ function sampleApprovals(approval) {
   return { unattended: never.filter((id) => SAMPLE_ACTIVE.includes(id)), parked: never.filter((id) => !SAMPLE_ACTIVE.includes(id)) };
 }
 var SAMPLE_NOTES = {
-  "claude-attach": "# Take over a Claude Code conversation that already exists on this machine (exit it in the terminal first)."
+  "claude-attach": "# Take over a Claude Code conversation that already exists on this machine (exit it in the terminal first).",
+  cursor: `# Cursor asks before it runs a command but cannot ask before it edits a file, so with approval "ask" its sessions are
+# read-only (ask and plan modes): they answer questions and change nothing. To let it write code, set approval = "never".`
 };
 var NEVER_NOTE = `# No per-step approval: this agent runs like it does in your terminal. A phone session writes files and runs
 # commands without asking, and the phone shows it as unattended. To go back to asking, set it to "ask".`;
@@ -1007,7 +1236,6 @@ async function deviceLogin(o) {
 import fs6 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"));
 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";
@@ -1029,50 +1257,46 @@ 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 (!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 || 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 (!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() || path6.join(home, ".claude");
+    const unreadable = [];
+    for (const file of [path6.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";
@@ -1318,21 +1542,23 @@ function hooksStatus(configDir) {
 }
 
 // src/connector.ts
-import fs14 from "node:fs";
+import fs16 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 { spawn as spawn2 } from "node:child_process";
 import fs9 from "node:fs";
 import path9 from "node:path";
 import { Readable, Writable } from "node:stream";
 import * as acp from "@agentclientprotocol/sdk";
+var AUTH_STATUS_METHOD = "_auth/status_update";
 var AdapterProcess = class _AdapterProcess {
   constructor(child, pid, registry) {
     this.child = child;
@@ -1343,21 +1569,28 @@ var AdapterProcess = class _AdapterProcess {
   pid;
   registry;
   caps = {};
+  /** The ways to sign in the adapter offered at `initialize` (`authMethods`), for `authenticate`. */
+  authMethods = [];
+  /** The last sign-in it reported, if it reports one; see {@link waitAuthStatus}. */
+  authStatus = null;
   exited = false;
   conn;
+  authWaiters = [];
   static async start(o) {
     fs9.mkdirSync(path9.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 = fs9.openSync(o.logFile, "a", 384);
-    const child = spawn(o.cfg.command, o.cfg.args, {
-      cwd: o.cwd,
-      env: { ...process.env, ...o.cfg.env },
+    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);
       throw e;
@@ -1413,7 +1646,12 @@ var AdapterProcess = class _AdapterProcess {
       if (ctx.method.startsWith("cursor/")) return await o.hooks.onExtension(ctx.method, ctx.params ?? {});
       throw acp.RequestError.methodNotFound(ctx.method);
     }).onNotification("*", async (ctx) => {
-      o.hooks.onNotification(ctx.method, ctx.params ?? {});
+      const params = ctx.params ?? {};
+      if (ctx.method === AUTH_STATUS_METHOD && params.authStatus && typeof params.authStatus.kind === "string") {
+        a.authStatus = { kind: params.authStatus.kind, ...typeof params.authStatus.label === "string" ? { label: params.authStatus.label } : {} };
+        for (const w of a.authWaiters.splice(0)) w();
+      }
+      o.hooks.onNotification(ctx.method, params);
     });
     a.conn = app.connect(acp.ndJsonStream(Writable.toWeb(child.stdin), Readable.toWeb(child.stdout)));
     try {
@@ -1423,12 +1661,46 @@ var AdapterProcess = class _AdapterProcess {
         "initialize"
       );
       a.caps = init.agentCapabilities ?? {};
+      const methods2 = init.authMethods;
+      a.authMethods = Array.isArray(methods2) ? methods2.filter((m) => typeof m === "object" && m !== null) : [];
     } catch (e) {
       await a.kill();
       throw e;
     }
     return a;
   }
+  /** Whether the adapter says it reports its sign-in (`agentCapabilities._meta.authStatus`). */
+  get reportsAuth() {
+    const meta = this.caps._meta;
+    return !!meta && typeof meta === "object" && meta.authStatus !== void 0;
+  }
+  /**
+   * The sign-in the adapter reports, waiting up to `ms` for its first report (claude-agent-acp sends it shortly after
+   * `initialize`, and again for each new session). Null when it reports nothing in that time: not known, not "none".
+   */
+  async waitAuthStatus(ms) {
+    if (this.authStatus || !this.reportsAuth || ms <= 0) return this.authStatus;
+    await new Promise((resolve) => {
+      const done = () => {
+        clearTimeout(t);
+        const i = this.authWaiters.indexOf(done);
+        if (i >= 0) this.authWaiters.splice(i, 1);
+        resolve();
+      };
+      const t = setTimeout(done, ms);
+      t.unref?.();
+      this.authWaiters.push(done);
+    });
+    return this.authStatus;
+  }
+  /** The id of an `authenticate` method that signs in with an API key the adapter reads from its own environment. */
+  apiKeyMethod() {
+    for (const m of this.authMethods) {
+      const id = typeof m.id === "string" ? m.id : typeof m.methodId === "string" ? m.methodId : null;
+      if (id === "api-key") return id;
+    }
+    return null;
+  }
   request(method, params, timeoutMs = 6e4) {
     return withTimeout(this.conn.agent.request(method, params), timeoutMs, method);
   }
@@ -1504,6 +1776,155 @@ function isRemoteCommandType(v) {
   return typeof v === "string" && REMOTE_COMMAND_TYPES.includes(v);
 }
 
+// src/roots.ts
+import fs10 from "node:fs";
+import path10 from "node:path";
+function realRoot(root) {
+  try {
+    return fs10.realpathSync.native(root);
+  } catch {
+    return null;
+  }
+}
+var inside = (child, root) => child === root || child.startsWith(root.endsWith(path10.sep) ? root : root + path10.sep);
+function checkCwd(cwd, roots) {
+  if (typeof cwd !== "string" || cwd === "" || cwd.includes("\0")) return { ok: false, reason: "invalid_cwd" };
+  if (!path10.isAbsolute(cwd)) return { ok: false, reason: "cwd_not_absolute" };
+  let real;
+  try {
+    real = fs10.realpathSync.native(cwd);
+  } catch {
+    return { ok: false, reason: "cwd_not_found" };
+  }
+  try {
+    if (!fs10.statSync(real).isDirectory()) return { ok: false, reason: "cwd_not_directory" };
+  } catch {
+    return { ok: false, reason: "cwd_not_found" };
+  }
+  for (const root of roots) {
+    const r = realRoot(root);
+    if (r && inside(real, r)) return { ok: true, real };
+  }
+  return { ok: false, reason: "cwd_outside_roots" };
+}
+var stalled = /* @__PURE__ */ new Set();
+var Stalled = class extends Error {
+};
+async function bounded(what, f, ms) {
+  if (stalled.has(what)) throw new Stalled(what);
+  let timer;
+  const call = f();
+  const late = new Promise((_, reject) => {
+    timer = setTimeout(() => reject(new Stalled(what)), ms);
+    timer.unref?.();
+  });
+  try {
+    return await Promise.race([call, late]);
+  } catch (e) {
+    if (e instanceof Stalled) {
+      stalled.add(what);
+      void call.then(() => stalled.delete(what), () => stalled.delete(what));
+    }
+    throw e;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+var realpathOf = (p, ms, f = fs10.promises) => bounded(p, () => f.realpath(p), ms);
+var isDir = async (p, ms, f = fs10.promises) => {
+  try {
+    return (await bounded(`stat:${p}`, () => f.stat(p), ms)).isDirectory();
+  } catch (e) {
+    if (e instanceof Stalled) throw e;
+    return false;
+  }
+};
+async function resolveCwd(cwd, roots, o) {
+  const ms = o.timeoutMs ?? 1e4;
+  if (typeof cwd !== "string" || cwd.trim() === "" || cwd.includes("\0")) return { ok: false, reason: "invalid_cwd" };
+  const typed = cwd.trim();
+  let candidates;
+  if (typed === "~" || typed.startsWith("~/")) candidates = [path10.join(o.home, typed.slice(2))];
+  else if (path10.isAbsolute(typed)) candidates = [typed];
+  else if (typed.startsWith("~")) return { ok: false, reason: "cwd_not_absolute" };
+  else {
+    const clean = path10.normalize(typed).replace(/\/+$/, "");
+    if (clean === ".." || clean.startsWith("../")) return { ok: false, reason: "cwd_outside_roots" };
+    candidates = [.../* @__PURE__ */ new Set([
+      ...roots.map((r) => path10.join(r, clean)),
+      ...roots.filter((r) => path10.basename(r) === clean)
+    ])];
+  }
+  const realRoots = [];
+  const down = [];
+  await Promise.all(roots.map(async (r) => {
+    try {
+      realRoots.push(await realpathOf(r, ms, o.fs));
+    } catch {
+      down.push(path10.resolve(r));
+    }
+  }));
+  const underDown = (p) => down.some((r) => inside(path10.resolve(p), r));
+  const hits = /* @__PURE__ */ new Map();
+  let unavailable = false;
+  for (const c of candidates) {
+    if (underDown(c)) {
+      unavailable = true;
+      continue;
+    }
+    let real;
+    try {
+      real = await realpathOf(c, ms, o.fs);
+    } catch (e) {
+      if (e instanceof Stalled) unavailable = true;
+      continue;
+    }
+    let dir;
+    try {
+      dir = await isDir(real, ms, o.fs);
+    } catch {
+      unavailable = true;
+      continue;
+    }
+    if (!dir) {
+      if (candidates.length === 1) return { ok: false, reason: "cwd_not_directory" };
+      continue;
+    }
+    if (realRoots.some((r) => inside(real, r))) hits.set(real, true);
+    else if (candidates.length === 1) return { ok: false, reason: "cwd_outside_roots" };
+  }
+  if (hits.size > 1) return { ok: false, reason: "cwd_ambiguous" };
+  if (hits.size === 1) return { ok: true, real: [...hits.keys()][0] };
+  return { ok: false, reason: unavailable ? "root_unavailable" : "cwd_not_found" };
+}
+async function rootProblems(agents, timeoutMs = 1e4) {
+  const out = [];
+  await Promise.all(agents.flatMap((a) => a.roots.map(async (r) => {
+    try {
+      const real = await realpathOf(r, timeoutMs);
+      if (!await isDir(real, timeoutMs)) out.push(`${a.id}: root ${r} is not a directory; sessions there are refused`);
+    } catch (e) {
+      out.push(e instanceof Stalled ? `${a.id}: root ${r} does not answer (a stalled network mount?); its sessions are refused (root_unavailable) until it does` : `${a.id}: root ${r} does not exist (yet); its sessions are refused until it does (create it, or fix roots in agents.toml)`);
+    }
+  })));
+  return out.sort();
+}
+function relativeInside(p, cwd) {
+  const abs = path10.resolve(cwd, p);
+  let real;
+  try {
+    real = fs10.realpathSync.native(abs);
+  } catch {
+    try {
+      real = path10.join(fs10.realpathSync.native(path10.dirname(abs)), path10.basename(abs));
+    } catch {
+      return null;
+    }
+  }
+  if (!inside(real, cwd)) return null;
+  return path10.relative(cwd, real).split(path10.sep).join("/");
+}
+
 // src/attach.ts
 var TwinCheckError = class extends Error {
 };
@@ -1511,6 +1932,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 +1955,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;
@@ -1580,6 +2004,14 @@ var AttachSupport = class {
     });
     return this.refreshing;
   }
+  /** Where the listing adapter starts: the first root that is there now (a root may be missing), else the home directory. */
+  async listingDir() {
+    for (const r of this.agent.roots) {
+      const v = await resolveCwd(r, [r], { home: os3.homedir(), timeoutMs: 5e3 });
+      if (v.ok) return v.real;
+    }
+    return os3.homedir();
+  }
   async doRefresh() {
     let adapter = null;
     this.noteHooks();
@@ -1588,9 +2020,9 @@ var AttachSupport = class {
         cfg: this.agent,
         registry: this.d.registry,
         sessionId: `list-${this.agent.id}`,
-        cwd: this.agent.roots[0] ?? os3.homedir(),
+        cwd: await this.listingDir(),
         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
       });
@@ -1602,7 +2034,8 @@ var AttachSupport = class {
         const res = await adapter.request("session/list", cursor ? { cursor } : {}, 3e4);
         for (const s of Array.isArray(res.sessions) ? res.sessions : []) {
           if (!isObject(s) || typeof s.sessionId !== "string" || !SESSION_REF_RE.test(s.sessionId) || typeof s.cwd !== "string") continue;
-          const where = checkCwd(s.cwd, this.agent.roots);
+          if (!path11.isAbsolute(s.cwd)) continue;
+          const where = await resolveCwd(s.cwd, this.agent.roots, { home: os3.homedir(), timeoutMs: 5e3 });
           if (!where.ok) continue;
           const at = typeof s.updatedAt === "string" ? Date.parse(s.updatedAt) : NaN;
           found.set(s.sessionId.toLowerCase(), {
@@ -1649,13 +2082,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 +2212,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 +2267,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 +2287,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 +2344,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 +2387,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 +2409,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 +2429,227 @@ 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");
+  const own = env.CLAW_CONNECTOR_CONFIG_DIR?.trim();
+  if (one) return { config: own ? path12.resolve(own) : 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: own ? path12.resolve(own) : 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 serviceEnvFile = (d) => path12.join(d.config, "service-env.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");
+var doctorFile = (d) => path12.join(d.state, "doctor.json");
+var keepaliveStampFile = (d) => path12.join(d.state, "keepalive-last");
 
 // 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 +2657,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 +2671,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 +2686,74 @@ 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 path15 from "node:path";
+
+// src/hints.ts
+import path14 from "node:path";
+function agentFamily(a) {
+  const words = [a.command, ...a.args].map((s) => path14.basename(s));
+  if (words.some((s) => s.includes("claude-agent-acp") || s.includes("claude-code-acp"))) return "claude";
+  if (words.some((s) => s.includes("codex-acp"))) return "codex";
+  const cmd = path14.basename(a.command);
+  if (cmd === "agent" || cmd === "cursor-agent") return "cursor";
+  if (a.kind === "claude" || a.kind === "attach") return "claude";
+  if (a.kind === "codex" || a.kind === "cursor") return a.kind;
+  return "other";
+}
+var SIGN_IN = {
+  claude: `Claude Code is not signed in on that machine: run "claude" there and sign in with /login, or set ANTHROPIC_API_KEY (or your gateway's ANTHROPIC_AUTH_TOKEN) for this agent in agents.toml under [agents.env]; a service installed from a shell that has the variable keeps it too`,
+  codex: `Codex is not signed in on that machine: run "codex login" there (or "codex login --with-api-key"), or set OPENAI_API_KEY for this agent in agents.toml under [agents.env]`,
+  cursor: `Cursor is not signed in on that machine: run "agent login" there, or set CURSOR_API_KEY for this agent in agents.toml under [agents.env]`,
+  other: `the agent is not signed in on that machine: sign it in there, then try again`
+};
+var DOCTOR = `run "claw-connector doctor" on that machine; it names the fix`;
+var HINTS = {
+  invalid_cwd: "give the folder to work in: a full path, ~/path, or the name of a folder inside one of this agent's roots",
+  cwd_not_absolute: "give the folder as a full path, as ~/path, or as the name of a folder inside one of this agent's roots",
+  cwd_not_found: "that folder does not exist on that machine: pick an existing folder inside one of this agent's roots, or create it there first",
+  cwd_not_directory: "that is a file, not a folder: pick a folder inside one of this agent's roots",
+  cwd_ambiguous: "more than one of this agent's roots has a folder by that name: give its full path",
+  cwd_outside_roots: "this agent may only work inside its roots (agents.toml on that machine): pick a folder inside one of them, or add the folder to roots there and restart the connector",
+  cwd_mismatch: "that conversation belongs to another folder: take it over without naming a folder, or name the one it was started in",
+  root_unavailable: "the folder's disk is not answering on that machine (a network mount that is down or not mounted yet): try again in a minute, or check the mount there",
+  unknown_agent: "that machine no longer offers this agent: check agents.toml there, then restart the connector",
+  too_many_sessions: "that machine already runs the most sessions it allows at once (10): close one, then try again",
+  mode_not_allowed: `that mode does not ask before each step, and this agent may use such a mode only with approval = "never" in agents.toml on that machine`,
+  mode_unavailable: `the agent does not offer the mode this machine requires for it: ${DOCTOR}`,
+  mode_not_enforced: `the agent would not run in a mode that asks before each step (often because Claude's own settings default to bypassPermissions): ${DOCTOR}, or set approval = "never" for this agent there`,
+  mode_not_confirmed: `the agent did not confirm the mode this machine requires: ${DOCTOR}`,
+  mode_mismatch: `the agent switched to a mode other than the one this machine requires: ${DOCTOR}`,
+  adapter_start_failed: `the agent's program could not start on that machine (not installed, not on the service's PATH, or the download failed): ${DOCTOR}`,
+  adapter_error: `the agent failed while opening the session: ${DOCTOR}; the adapter's log is in the connector's logs directory there`,
+  adapter_protocol: `the agent answered in a way the connector does not understand: ${DOCTOR}, and update the agent's adapter`,
+  adapter_cannot_resume: "this agent cannot reopen an earlier session: start a new one",
+  adapter_gone: "the agent stopped while the session was opening: try again",
+  resume_not_supported: "this agent starts new conversations only: start a new session instead of continuing one",
+  resume_ref_required: "this agent only takes over conversations that already exist on that machine: pick one from its list, or use the agent that starts new ones",
+  invalid_resume_ref: "that is not a conversation this machine lists: pick one from its list",
+  attach_unavailable: "taking over conversations is not available for this agent on that machine: start a new session instead",
+  already_attached: "that conversation is already open from the chat: use that session",
+  unknown_session: "that machine no longer has this conversation (or it is outside the agent's roots): pick another one from its list",
+  catalog_unavailable: `that machine could not list its conversations just now: try again; if it keeps failing, ${DOCTOR}`,
+  session_live: "that conversation is open in a terminal on that machine: exit it there (/exit), then try again",
+  recently_written: "that conversation was written to a moment ago: wait a few seconds, then try again",
+  twin_check_failed: "the connector could not check whether a terminal holds that conversation open: try again in a moment",
+  too_many_queued_prompts: "five messages are already waiting for this session: wait for the agent to finish one",
+  text_required: "the message was empty",
+  session_closed: "the session has already ended: start a new one"
+};
+function hintFor(reason, agent) {
+  if (reason === "agent_auth_required") return SIGN_IN[agent ? agentFamily(agent) : "other"];
+  return HINTS[reason] ?? null;
+}
+function withHint(data, agent) {
+  const hint = hintFor(data.reason, agent);
+  return hint ? { ...data, hint } : data;
+}
 
 // src/permissions.ts
 import { randomUUID } from "node:crypto";
@@ -2097,7 +2881,17 @@ 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,
+  rootCheckMs: 1e4,
+  authWaitMs: 3e3
+};
+var READ_ONLY_REASON = "read_only_live_session";
 var SessionRefusal = class extends Error {
   constructor(reason, message) {
     super(message ?? reason);
@@ -2105,6 +2899,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;
@@ -2159,9 +2954,25 @@ var Session = class {
    */
   twinSeen = false;
   turnRunning = false;
+  /**
+   * The connector is going away (stopped, or restarted by its supervisor) and will come back. What this process cannot
+   * finish is left recorded for the next run instead of being ended here: the running turn (no `turn_end`), its waiting
+   * permission requests (still pending), and the prompts queued behind it (not counted as handled, so Claw delivers them
+   * again). See {@link SessionManager.recover}.
+   */
+  stopping = false;
   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) {
@@ -2191,7 +3002,7 @@ var Session = class {
     return this.noAskWarning || this.currentMode !== null && !this.agent.askingModes.includes(this.currentMode);
   }
   shownModes() {
-    return this.modes.filter((m) => this.modeAllowed(m.id)).map((m) => ({ ...m, unattended: !this.agent.askingModes.includes(m.id) }));
+    return this.modes.filter((m) => this.modeAllowed(m.id)).map((m) => ({ ...m, unattended: !this.agent.askingModes.includes(m.id), ...this.agent.readOnlyModes.includes(m.id) ? { read_only: true } : {} }));
   }
   // --- starting ----------------------------------------------------------------
   /** `session.new`: start the adapter, create the ACP session, lock the mode. A refusal closes the session with a reason. */
@@ -2220,6 +3031,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 +3048,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 +3210,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: path15.join(this.env.logDir, `adapter-${this.agent.id}.log`),
       version: this.env.version
     }).catch((e) => {
       throw new SessionRefusal("adapter_start_failed", errMessage(e));
@@ -2328,19 +3223,20 @@ var Session = class {
     this.modeSeen = [];
     try {
       if (how === "new") {
-        const res = await adapter.request("session/new", { cwd: this.cwd, mcpServers: [] });
+        const res = await this.signedIn(adapter, () => 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);
+        await this.refuseSignedOut(adapter);
       } else {
         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 this.signedIn(adapter, () => 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 this.signedIn(adapter, () => adapter.requestUnbounded("session/load", { sessionId: this.acpId, cwd: this.cwd, mcpServers: [], ...claudeSessionMeta(this.agent) })));
           } finally {
             this.replaying = false;
           }
@@ -2355,6 +3251,43 @@ var Session = class {
       throw e instanceof SessionRefusal ? e : mapAdapterError(e);
     }
   }
+  /**
+   * `open` (a `session/new`), signing the adapter in first when it needs that and can do it by itself: an adapter that
+   * answers "Authentication required" and offers an `api-key` method, while its environment holds a key it reads
+   * (codex-acp: OPENAI_API_KEY or CODEX_API_KEY), is told to `authenticate` with it and asked once more. Without this a
+   * Codex agent set up with only an API key never opened a session. The key itself is never sent: the adapter reads
+   * its own environment. (codex-acp then keeps the key in its auth.json, as `codex login --with-api-key` does.)
+   */
+  async signedIn(adapter, open) {
+    try {
+      return await open();
+    } catch (e) {
+      const method = adapter.apiKeyMethod();
+      if (mapAdapterError(e).reason !== "agent_auth_required" || !method || !this.hasApiKey()) throw e;
+      this.audit("agent_authenticate", { method });
+      try {
+        await adapter.request("authenticate", { methodId: method });
+      } catch (ae) {
+        throw new SessionRefusal("agent_auth_required", `authenticate ${method} failed: ${errMessage(ae)}`);
+      }
+      return await open();
+    }
+  }
+  /** Whether the adapter's environment (the connector's, with the agent's `[agents.env]` over it) holds an OpenAI/Codex key. */
+  hasApiKey() {
+    const env = { ...process.env, ...this.agent.env };
+    return ["CODEX_API_KEY", "OPENAI_API_KEY"].some((k) => typeof env[k] === "string" && env[k].trim() !== "");
+  }
+  /**
+   * An adapter that reports its sign-in (claude-agent-acp) and says there is none: the session would open, say it is
+   * ready and fail at its first message with "Authentication required". A new session is refused now instead, with the
+   * fix. A session that already exists (resumed after an idle recycle or a restart) is not: its prompts say why and it
+   * stays, so it carries on once someone signs in on the machine.
+   */
+  async refuseSignedOut(adapter) {
+    const st = await adapter.waitAuthStatus(this.env.timing.authWaitMs);
+    if (st?.kind === "none") throw new SessionRefusal("agent_auth_required", `the agent reports that it is not signed in${st.label ? ` (${st.label})` : ""}`);
+  }
   /** Take the modes and the mode config option out of a `session/new|resume|load` answer. */
   absorb(res) {
     const modes = res.modes;
@@ -2381,7 +3314,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 +3370,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");
@@ -2489,7 +3423,7 @@ var Session = class {
     this.adapter = null;
     const hadTurn = this.turnRunning;
     const cancelled = this.book.cancelAll();
-    for (const actionId of cancelled) this.emit("permission_resolved", { actionId, optionId: null, outcome: "cancelled", by: "adapter_exit" });
+    if (!this.stopping) for (const actionId of cancelled) this.emit("permission_resolved", { actionId, optionId: null, outcome: "cancelled", by: "adapter_exit" });
     if (!this.closed) this.audit("adapter_exited", { code: info.code, signal: info.signal, during_turn: hadTurn });
   }
   onUpdate(update, params) {
@@ -2538,16 +3472,20 @@ var Session = class {
       kind: str(toolCall.kind, 64),
       input: boundedInput(toolCall.rawInput),
       toolCallId: str(toolCall.toolCallId, 128)
-    }, (optionId) => optionId === null ? { outcome: { outcome: "cancelled" } } : { outcome: { outcome: "selected", optionId } });
+    }, (optionId) => optionId === null ? { outcome: { outcome: "cancelled" } } : { outcome: { outcome: "selected", optionId } }, true);
   }
   /** Put a question on the phone and wait for the answer, a cancel or the timeout. `shape` turns the answer into what the adapter expects. */
-  askPerson(options, info, shape) {
+  askPerson(options, info, shape, permission = false) {
     return new Promise((resolve) => {
       const p = this.book.open(options, (actionId) => redactDeep({ actionId, ...info, options, timeout_ms: this.book.ttl }), (optionId) => {
-        this.env.store.removePending(this.id, p.actionId);
+        if (!this.stopping) {
+          this.env.store.removePending(this.id, p.actionId);
+          if (this.book.size === 0) this.env.store.markWaiting(this.id, false);
+        }
         resolve(shape(optionId));
       });
       this.env.store.addPending(this.id, p.actionId);
+      this.env.store.markWaiting(this.id, true, permission);
       this.audit("permission_requested", { action_id: p.actionId, tool: info.tool, tool_kind: info.kind, options: options.map((o) => o.optionId) });
       this.emit("permissionRequest", p.payload);
     });
@@ -2616,6 +3554,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();
@@ -2623,11 +3567,16 @@ var Session = class {
     this.queue.push({ text, cmdId, cmdSeq, started });
     if (!this.turnRunning) void this.pump();
   }
-  /** Prompts that will now never run (the process is being stopped): they count as handled. */
-  dropQueued() {
+  /** Prompts that will now never run here: they count as handled, unless (`keep`) the connector is only restarting and the next run should get them again. */
+  dropQueued(keep = false) {
     const q = this.queue;
     this.queue = [];
-    for (const item of q) item.started();
+    if (!keep) for (const item of q) item.started();
+  }
+  /** The connector is about to stop its adapters and will come back: see {@link stopping}. */
+  shutdown() {
+    this.stopping = true;
+    this.dropQueued(true);
   }
   async pump() {
     if (this.turnRunning) return;
@@ -2651,6 +3600,7 @@ var Session = class {
         this.audit("prompt_refused", { reason: refused.reason, detail: refused.detail.slice(0, 300) });
         this.rejectCommand("prompt", cmdId, refused.reason, cmdSeq);
         this.emit("turn_end", { stopReason: "error", error: refused.reason, cmd_id: cmdId, cmd_seq: cmdSeq });
+        this.env.store.endTurn(this.id);
         return;
       }
     }
@@ -2658,7 +3608,11 @@ var Session = class {
       await this.ensureAdapter();
     } catch (e) {
       started();
-      this.emit("turn_end", { stopReason: "error", error: e instanceof SessionRefusal ? e.reason : "adapter_unavailable", cmd_id: cmdId, cmd_seq: cmdSeq });
+      const reason = e instanceof SessionRefusal ? e.reason : "adapter_unavailable";
+      const hint = hintFor(reason, this.agent);
+      this.emit("turn_end", { stopReason: "error", error: reason, ...hint ? { hint } : {}, cmd_id: cmdId, cmd_seq: cmdSeq });
+      this.env.store.endTurn(this.id);
+      if (reason === "agent_auth_required") return;
       return this.refuse(e);
     }
     const a = this.adapter;
@@ -2667,13 +3621,22 @@ var Session = class {
     const watch = support ? this.watchTwins(support, this.acpId) : null;
     try {
       const reply = a.requestUnbounded("session/prompt", { sessionId: this.acpId, prompt: [{ type: "text", text }] });
+      const now = (/* @__PURE__ */ new Date()).toISOString();
+      this.env.store.beginTurn({ session_id: this.id, cmd_id: cmdId, cmd_seq: cmdSeq, started_at: now });
+      this.env.store.patch(this.id, { used_at: now });
       started();
       const res = await reply;
       const usage = isObject(res.usage) ? res.usage : void 0;
-      this.emit("turn_end", { stopReason: typeof res.stopReason === "string" ? res.stopReason : "end_turn", ...usage ? { usage } : {}, cmd_id: cmdId, cmd_seq: cmdSeq });
+      this.endTurn({ stopReason: typeof res.stopReason === "string" ? res.stopReason : "end_turn", ...usage ? { usage } : {}, cmd_id: cmdId, cmd_seq: cmdSeq });
     } catch (e) {
-      this.audit("turn_failed", { error: errMessage(e) });
-      this.emit("turn_end", { stopReason: "error", error: errMessage(e).slice(0, 300), cmd_id: cmdId, cmd_seq: cmdSeq });
+      if (!this.stopping) this.audit("turn_failed", { error: errMessage(e) });
+      const r = mapAdapterError(e);
+      if (r.reason === "agent_auth_required") {
+        this.endTurn({ stopReason: "error", error: r.reason, message: errMessage(e).slice(0, 300), hint: hintFor(r.reason, this.agent), cmd_id: cmdId, cmd_seq: cmdSeq });
+        if (this.adapter === a) await this.dropAdapter();
+      } else {
+        this.endTurn({ stopReason: "error", error: errMessage(e).slice(0, 300), cmd_id: cmdId, cmd_seq: cmdSeq });
+      }
     } finally {
       this.markTranscript();
       if (watch) {
@@ -2718,6 +3681,12 @@ var Session = class {
     }
     return null;
   }
+  /** The turn is over: say so and forget it. Not while the connector is going away: the next run ends or continues it. */
+  endTurn(data) {
+    if (this.stopping) return;
+    this.emit("turn_end", data);
+    this.env.store.endTurn(this.id);
+  }
   /** What size the transcript is as this connector leaves it: after it starts the session and after every turn. */
   markTranscript() {
     if (this.agent.attach && this.acpId) this.transcriptMark = this.env.attach.get(this.agent.id)?.transcriptSize(this.acpId) ?? null;
@@ -2732,10 +3701,15 @@ 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");
     } catch (e) {
+      if (e instanceof SessionRefusal && e.reason === "agent_auth_required") return this.rejectCommand("resume", cmdId, e.reason);
       return this.refuse(e);
     }
     this.audit("session_resumed", { mode: this.currentMode, unattended: this.unattended });
@@ -2774,6 +3748,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;
@@ -2781,7 +3756,7 @@ var Session = class {
     await this.dropAdapter();
     this.env.store.patch(this.id, { status: "closed" });
     this.audit("session_closed", { reason });
-    this.emit("session_closed", { reason });
+    this.emit("session_closed", withHint({ reason }, this.agent));
   }
   /** A session that cannot be opened (or kept safe) is closed with the reason, never left half-open. */
   async refuse(e) {
@@ -2793,7 +3768,7 @@ var Session = class {
   /** A command refused; a prompt's refusal names it by `cmd_seq` too, as its turn_end would. */
   rejectCommand(type, cmdId, reason, cmdSeq = null) {
     this.audit("command_rejected", { type, cmd_id: cmdId, reason });
-    this.emit("command_rejected", { type, cmd_id: cmdId, reason, ...cmdSeq !== null ? { cmd_seq: cmdSeq } : {} });
+    this.emit("command_rejected", withHint({ type, cmd_id: cmdId, reason, ...cmdSeq !== null ? { cmd_seq: cmdSeq } : {} }, this.agent));
   }
 };
 function mapAdapterError(e) {
@@ -2818,7 +3793,10 @@ function limitStrings(value, max) {
 }
 
 // src/manager.ts
+import os5 from "node:os";
 var MAX_ACTIVE_SESSIONS = 10;
+var RECOVER_NOTICE_MS = 4 * 36e5;
+var CONTINUE_PROMPT = "[claw-connector] The connector on this machine restarted while you were waiting for my permission, so that request was cancelled. Continue the task from where you left off, and ask again for anything that still needs my permission.";
 var cmdSeqOf = (cmd) => Number.isSafeInteger(cmd.cmd_seq) ? cmd.cmd_seq : null;
 var SessionManager = class {
   constructor(env) {
@@ -2832,6 +3810,15 @@ var SessionManager = class {
   agent(id) {
     return typeof id === "string" ? this.env.config.agents.find((a) => a.id === id) : void 0;
   }
+  /** The folder a phone asked for, as this agent would see it: `~` is the home its adapter runs with. */
+  where(cwd, agent) {
+    return resolveCwd(typeof cwd === "string" ? cwd : "", agent.roots, { home: agent.env.HOME?.trim() || os5.homedir(), timeoutMs: this.env.timing.rootCheckMs });
+  }
+  /** A session refused before it had a process: audited, and closed with its reason and what to do about it. */
+  refuseNew(sid, reason, agent, extra = {}) {
+    this.env.audit.record("session_refused", { session_id: sid, ...agent ? { agent_id: agent.id } : {}, reason, ...extra });
+    this.env.emit(sid, "session_closed", withHint({ reason }, agent));
+  }
   /**
    * Commands of one session run one after another; sessions run side by side.
    * `handled` is called exactly once, when the command counts as carried out: for most that is when the
@@ -2881,8 +3868,20 @@ var SessionManager = class {
       return false;
     }
     const s = await this.lookup(sid);
-    if (!s) {
-      this.env.emit(sid, "session_closed", { reason: "unknown_session" });
+    if (s === null) {
+      this.env.emit(sid, "session_closed", { reason: "unknown_session", hint: "the session has already ended on that machine: start a new one" });
+      return false;
+    }
+    if (!(s instanceof Session)) {
+      if (type === "close") {
+        this.env.store.patch(sid, { status: "closed" });
+        this.env.audit.record("session_closed", { session_id: sid, reason: "closed" });
+        this.env.emit(sid, "session_closed", { reason: "closed" });
+        return false;
+      }
+      const seq = cmdSeqOf(cmd);
+      this.env.audit.record("command_rejected", { type, cmd_id: cmdId, reason: s.unavailable });
+      this.env.emit(sid, "command_rejected", withHint({ type, cmd_id: cmdId, reason: s.unavailable, ...seq !== null ? { cmd_seq: seq } : {} }, s.agent));
       return false;
     }
     switch (type) {
@@ -2916,31 +3915,20 @@ var SessionManager = class {
   async sessionNew(cmd) {
     const sid = cmd.session_id;
     if (this.sessions.has(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) });
-      this.env.emit(sid, "session_closed", { reason: "unknown_agent" });
+    if (this.env.store.get(sid)?.read_only) {
+      await this.lookup(sid);
       return;
     }
+    const agent = this.agent(cmd.agent_id);
+    if (!agent) return this.refuseNew(sid, "unknown_agent", null, { agent_id: String(cmd.agent_id).slice(0, 64) });
     const ref = cmd.resume_ref;
     if (agent.attach) return this.attachNew(cmd, agent);
-    if (ref !== void 0 && ref !== null) {
-      this.env.audit.record("session_refused", { session_id: sid, agent_id: agent.id, reason: "resume_not_supported" });
-      this.env.emit(sid, "session_closed", { reason: "resume_not_supported" });
-      return;
-    }
-    const verdict = checkCwd(typeof cmd.cwd === "string" ? cmd.cwd : "", agent.roots);
-    if (!verdict.ok) {
-      this.env.audit.record("session_refused", { session_id: sid, agent_id: agent.id, reason: verdict.reason, cwd: String(cmd.cwd).slice(0, 300) });
-      this.env.emit(sid, "session_closed", { reason: verdict.reason });
-      return;
-    }
+    if (ref !== void 0 && ref !== null) return this.refuseNew(sid, "resume_not_supported", agent);
+    const verdict = await this.where(cmd.cwd, agent);
+    if (!verdict.ok) return this.refuseNew(sid, verdict.reason, agent, { cwd: String(cmd.cwd).slice(0, 300) });
+    if (this.sessions.has(sid)) return;
     const active = [...this.sessions.values()].filter((s2) => !s2.closed).length;
-    if (active >= MAX_ACTIVE_SESSIONS) {
-      this.env.audit.record("session_refused", { session_id: sid, agent_id: agent.id, reason: "too_many_sessions" });
-      this.env.emit(sid, "session_closed", { reason: "too_many_sessions" });
-      return;
-    }
+    if (active >= MAX_ACTIVE_SESSIONS) return this.refuseNew(sid, "too_many_sessions", agent);
     const s = new Session(sid, agent, verdict.real, this.env);
     this.sessions.set(sid, s);
     await s.create(typeof cmd.mode === "string" ? cmd.mode : null);
@@ -2952,10 +3940,7 @@ var SessionManager = class {
    */
   async attachNew(cmd, agent) {
     const sid = cmd.session_id;
-    const refuse = (reason, extra = {}) => {
-      this.env.audit.record("session_refused", { session_id: sid, agent_id: agent.id, reason, ...extra });
-      this.env.emit(sid, "session_closed", { reason });
-    };
+    const refuse = (reason, extra = {}) => this.refuseNew(sid, reason, agent, extra);
     const ref = typeof cmd.resume_ref === "string" ? cmd.resume_ref : "";
     if (!ref) return refuse("resume_ref_required");
     if (!SESSION_REF_RE.test(ref)) return refuse("invalid_resume_ref");
@@ -2963,13 +3948,13 @@ 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 {
       const found = await support.resolve(want);
       if (!found.ok) return refuse(found.reason);
-      const asked = checkCwd(typeof cmd.cwd === "string" ? cmd.cwd : "", agent.roots);
+      const asked = await this.where(cmd.cwd, agent);
       if (!asked.ok) return refuse(asked.reason, { cwd: String(cmd.cwd).slice(0, 300) });
       if (asked.real !== found.item.cwd) return refuse("cwd_mismatch", { cwd: String(cmd.cwd).slice(0, 300) });
       const s = new Session(sid, agent, found.item.cwd, this.env, found.item.ref);
@@ -2983,27 +3968,40 @@ 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. */
+  /**
+   * A session this process knows, or one it made earlier (before a restart) and can bring back; `unavailable` when its
+   * folder's disk does not answer now (the session is kept for later).
+   */
   async lookup(sid) {
     const have = this.sessions.get(sid);
     if (have) return have;
     const rec = this.env.store.get(sid);
     if (!rec || rec.status !== "active") return null;
     const agent = this.agent(rec.agent_id);
-    const verdict = agent ? checkCwd(rec.cwd, agent.roots) : null;
+    const verdict = agent ? await this.where(rec.cwd, agent) : null;
     if (!agent || !verdict?.ok) {
+      if (agent && verdict && !verdict.ok && verdict.reason === "root_unavailable") return { unavailable: verdict.reason, agent };
       this.env.store.patch(sid, { status: "closed" });
-      this.env.audit.record("session_refused", { session_id: sid, reason: agent ? "cwd_outside_roots" : "unknown_agent" });
-      this.env.emit(sid, "session_closed", { reason: agent ? "cwd_outside_roots" : "unknown_agent" });
+      this.refuseNew(sid, agent ? verdict && !verdict.ok ? verdict.reason : "cwd_outside_roots" : "unknown_agent", agent ?? null);
       return null;
     }
+    const raced = this.sessions.get(sid);
+    if (raced) return raced;
     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();
@@ -3011,11 +4009,62 @@ var SessionManager = class {
   get pendingPermissions() {
     return [...this.sessions.values()].reduce((n, s) => n + s.pendingCount, 0);
   }
-  /** The kill switch: every adapter process, now. Sessions stay recorded and can be resumed. */
-  async killAll(reason) {
+  /**
+   * After a restart (a crash, a kill, a supervisor's restart, an upgrade): every turn the previous run left running is
+   * ended or carried on, and every session used lately is told it is back (`session_recovered`), once.
+   *
+   * A turn whose agent was waiting for a person's permission for a tool call, cut off no longer ago than a card lives, in a
+   * session of an agent that always asks, goes on with {@link CONTINUE_PROMPT} under the same prompt (`cmd_id`,
+   * `cmd_seq`): the agent asks again, so the card comes back, and the prompt's own `turn_end` still ends it. Not while
+   * the kill switch is on (`mayContinue`). Any other turn ends with `turn_end` `error: "connector_restarted"`, naming its
+   * prompt, so the phone stops waiting for it; whether the agent finished what it was doing is in the conversation, which
+   * the next message resumes.
+   */
+  recover(o) {
+    const now = o.now ?? Date.now();
+    const told = /* @__PURE__ */ new Set();
+    for (const t of this.env.store.listTurns()) {
+      const sid = t.session_id;
+      const rec = this.env.store.get(sid);
+      const active = rec?.status === "active";
+      const agent = rec ? this.agent(rec.agent_id) : void 0;
+      const asks = agent !== void 0 && !agent.allowUnsafeModes && rec?.mode !== null && rec?.mode !== void 0 && agent.askingModes.includes(rec.mode);
+      const waiting = Boolean(t.waiting_permission);
+      const recent = o.downForMs !== null && o.downForMs <= this.env.timing.permissionTtlMs;
+      if (o.mayContinue && active && asks && waiting && recent) {
+        this.env.audit.record("turn_continued", { session_id: sid, cmd_id: t.cmd_id, cmd_seq: t.cmd_seq, down_ms: o.downForMs });
+        this.env.emit(sid, "session_recovered", { reason: "connector_restart", interrupted: true, continuing: true, cmd_id: t.cmd_id, cmd_seq: t.cmd_seq });
+        void this.handle({ cmd_id: t.cmd_id ?? `continue-${t.cmd_seq ?? sid}`, type: "prompt", session_id: sid, text: CONTINUE_PROMPT, ...t.cmd_seq !== null ? { cmd_seq: t.cmd_seq } : {} }, () => {
+          if (this.env.store.turn(sid)?.started_at === t.started_at) this.env.store.endTurn(sid);
+        });
+      } else {
+        this.env.audit.record("turn_interrupted", { session_id: sid, cmd_id: t.cmd_id, cmd_seq: t.cmd_seq, waiting, down_ms: o.downForMs });
+        if (active) this.env.emit(sid, "session_recovered", { reason: "connector_restart", interrupted: true, continuing: false, cmd_id: t.cmd_id, cmd_seq: t.cmd_seq });
+        this.env.emit(sid, "turn_end", { stopReason: "error", error: "connector_restarted", cmd_id: t.cmd_id, cmd_seq: t.cmd_seq });
+        this.env.store.endTurn(sid);
+      }
+      told.add(sid);
+    }
+    for (const sid of this.env.store.ids()) {
+      const rec = this.env.store.get(sid);
+      if (told.has(sid) || rec?.status !== "active" || !rec.used_at) continue;
+      const used = Date.parse(rec.used_at);
+      if (!Number.isFinite(used) || now - used > RECOVER_NOTICE_MS) continue;
+      this.env.emit(sid, "session_recovered", { reason: "connector_restart", interrupted: false, continuing: false });
+    }
+  }
+  /**
+   * Every adapter process, now. Sessions stay recorded and can be resumed. `restarting`: the connector is only going away
+   * for a while (stopped, or restarted by its supervisor); what is in flight is left for the next run ({@link recover})
+   * instead of being ended, and queued prompts are delivered again. Otherwise (the kill switch: revoked, paused) every
+   * turn ends here and queued prompts count as handled.
+   */
+  async killAll(reason, restarting = false) {
     for (const s of this.sessions.values()) {
       this.env.audit.record("session_killed", { session_id: s.id, reason });
-      s.dropQueued();
+      if (restarting) s.shutdown();
+      else s.dropQueued();
+      s.stopTail();
     }
     await this.env.registry.killAll();
     this.sessions.clear();
@@ -3023,8 +4072,8 @@ var SessionManager = class {
 };
 
 // src/outbox.ts
-import fs12 from "node:fs";
-import path14 from "node:path";
+import fs13 from "node:fs";
+import path16 from "node:path";
 var DROPPABLE_TYPES = /* @__PURE__ */ new Set([
   "agent_message_chunk",
   "agent_thought_chunk",
@@ -3051,35 +4100,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) => path16.join(this.dir, `${safeName(sid)}.jsonl`);
+  metaFile = (sid) => path16.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(path16.join(this.dir, `${base}.meta.json`), "utf8"));
       } catch {
       }
       let sid = null;
-      const file = path14.join(this.dir, `${base}.jsonl`);
+      const file = path16.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 +4146,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(path16.join(this.dir, `${base}.meta.json`)).mtimeMs > TOMBSTONE_MS) {
+            for (const f of [`${base}.meta.json`, `${base}.jsonl`]) fs13.rmSync(path16.join(this.dir, f), { force: true });
             continue;
           }
         } catch {
@@ -3120,7 +4169,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 +4198,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 +4237,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 +4256,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 +4264,27 @@ var Outbox = class {
 };
 
 // src/session-store.ts
-import fs13 from "node:fs";
-import path15 from "node:path";
+import fs14 from "node:fs";
+import path17 from "node:path";
 var SessionStore = class {
   constructor(file) {
     this.file = file;
     this.pendingFile = `${file}.pending`;
+    this.turnsFile = `${file}.turns`;
+    try {
+      const raw = JSON.parse(fs14.readFileSync(this.turnsFile, "utf8"));
+      if (raw && typeof raw === "object" && !Array.isArray(raw)) {
+        for (const [k, t] of Object.entries(raw)) if (t && typeof t.session_id === "string") this.turns[k] = t;
+      }
+    } catch {
+    }
     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 {
     }
@@ -3236,6 +4293,8 @@ var SessionStore = class {
   recs = {};
   pending = [];
   pendingFile;
+  turns = {};
+  turnsFile;
   get(id) {
     return this.recs[id];
   }
@@ -3257,36 +4316,509 @@ var SessionStore = class {
     this.pending.push({ session_id: sessionId, action_id: actionId });
     this.savePending();
   }
-  removePending(sessionId, actionId) {
-    const before = this.pending.length;
-    this.pending = this.pending.filter((p) => !(p.session_id === sessionId && p.action_id === actionId));
-    if (this.pending.length !== before) this.savePending();
+  removePending(sessionId, actionId) {
+    const before = this.pending.length;
+    this.pending = this.pending.filter((p) => !(p.session_id === sessionId && p.action_id === actionId));
+    if (this.pending.length !== before) this.savePending();
+  }
+  /** Return what was pending and forget it. */
+  takePending() {
+    const out = this.pending;
+    this.pending = [];
+    if (out.length) this.savePending();
+    return out;
+  }
+  savePending() {
+    fs14.mkdirSync(path17.dirname(this.pendingFile), { recursive: true, mode: 448 });
+    const tmp = `${this.pendingFile}.${process.pid}.tmp`;
+    fs14.writeFileSync(tmp, JSON.stringify(this.pending), { mode: 384 });
+    fs14.renameSync(tmp, this.pendingFile);
+  }
+  /**
+   * The turn a session's agent is running. It lives in the adapter's memory, so a connector that dies (or is stopped)
+   * mid-turn would leave the prompt open for ever: the next run reads these and ends or continues each one.
+   */
+  beginTurn(t) {
+    this.turns[t.session_id] = t;
+    this.saveTurns();
+  }
+  /** The turn's agent is waiting for a person (`true`; `permission`: a tool call's permission request), or no longer (`false`). */
+  markWaiting(sessionId, waiting, permission = false) {
+    const t = this.turns[sessionId];
+    if (!t) return;
+    const next = { ...t, waiting, waiting_permission: waiting && (permission || Boolean(t.waiting_permission)) };
+    if (Boolean(t.waiting) === next.waiting && Boolean(t.waiting_permission) === next.waiting_permission) return;
+    this.turns[sessionId] = next;
+    this.saveTurns();
+  }
+  turn(sessionId) {
+    return this.turns[sessionId];
+  }
+  endTurn(sessionId) {
+    if (!(sessionId in this.turns)) return;
+    delete this.turns[sessionId];
+    this.saveTurns();
+  }
+  /** The turns recorded as running. Each stays until it is ended ({@link endTurn}) or a new turn of its session replaces it. */
+  listTurns() {
+    return Object.values(this.turns).map((t) => ({ ...t }));
+  }
+  saveTurns() {
+    fs14.mkdirSync(path17.dirname(this.turnsFile), { recursive: true, mode: 448 });
+    const tmp = `${this.turnsFile}.${process.pid}.tmp`;
+    fs14.writeFileSync(tmp, JSON.stringify(this.turns), { mode: 384 });
+    fs14.renameSync(tmp, this.turnsFile);
+  }
+  ids() {
+    return Object.keys(this.recs);
+  }
+  save() {
+    fs14.mkdirSync(path17.dirname(this.file), { recursive: true, mode: 448 });
+    const tmp = `${this.file}.${process.pid}.tmp`;
+    fs14.writeFileSync(tmp, JSON.stringify(this.recs), { mode: 384 });
+    fs14.renameSync(tmp, this.file);
+  }
+};
+
+// src/doctor.ts
+import { spawn as spawn3 } from "node:child_process";
+import fs15 from "node:fs";
+import fsp from "node:fs/promises";
+import os6 from "node:os";
+import path18 from "node:path";
+import { parse as parseToml2 } from "smol-toml";
+var FS_TIMEOUT_MS = 5e3;
+async function within2(p, ms = FS_TIMEOUT_MS) {
+  let t;
+  const late = new Promise((resolve) => {
+    t = setTimeout(() => resolve(null), ms);
+    t.unref?.();
+  });
+  p.catch(() => void 0);
+  try {
+    return await Promise.race([p, late]);
+  } finally {
+    clearTimeout(t);
+  }
+}
+var errnoOf = async (p) => within2(p.then(() => "", (e) => e.code ?? "EIO"));
+var fileExists = async (f) => await errnoOf(fsp.access(f)) === "";
+async function readText(f) {
+  return within2(fsp.readFile(f, "utf8").catch(() => null));
+}
+async function readJson(file) {
+  const t = await readText(file);
+  if (t === null) return null;
+  try {
+    const v = JSON.parse(t);
+    return isObject(v) ? v : null;
+  } catch {
+    return null;
+  }
+}
+var NODE_MIN_MAJOR = 22;
+var RECHECK_MS = 15 * 6e4;
+var KEEPALIVE_STALE_MS = 15 * 6e4;
+var PROBE_TIMEOUT_MS = 15e3;
+var PIPE_GRACE_MS = 500;
+var MAX_REPORTED2 = 6;
+function runProbe(cmd, args, env, signal, timeoutMs = PROBE_TIMEOUT_MS, input, ownGroup = true) {
+  return new Promise((resolve) => {
+    if (signal?.aborted) return resolve({ code: null, out: "stopped" });
+    let out = "";
+    let child;
+    try {
+      child = spawn3(cmd, args, { env, cwd: os6.homedir(), detached: ownGroup, stdio: [input === void 0 ? "ignore" : "pipe", "pipe", "pipe"], windowsHide: true });
+    } catch (e) {
+      return resolve({ code: null, out: errMessage(e) });
+    }
+    if (input !== void 0) {
+      child.stdin?.on("error", () => void 0);
+      child.stdin?.end(input);
+    }
+    const take = (b) => {
+      if (out.length < 256 * 1024) out += b.toString("utf8");
+    };
+    child.stdout?.on("data", take);
+    child.stderr?.on("data", take);
+    const killGroup = () => {
+      try {
+        if (child.pid) process.kill(ownGroup ? -child.pid : child.pid, "SIGKILL");
+      } catch {
+      }
+    };
+    let settled = false;
+    const finish = (code) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", onAbort);
+      killGroup();
+      child.stdout?.destroy();
+      child.stderr?.destroy();
+      resolve({ code, out: out.trim() });
+    };
+    const onAbort = () => finish(null);
+    const timer = setTimeout(() => finish(null), timeoutMs);
+    signal?.addEventListener("abort", onAbort, { once: true });
+    child.once("error", (e) => {
+      out = errMessage(e);
+      finish(null);
+    });
+    const ended = (st) => new Promise((res) => {
+      if (!st || st.readableEnded) res();
+      else {
+        st.once("end", () => res());
+        st.once("close", () => res());
+      }
+    });
+    const drained = Promise.all([ended(child.stdout), ended(child.stderr)]);
+    child.once("exit", (code) => {
+      const grace = setTimeout(() => finish(code), PIPE_GRACE_MS);
+      void drained.then(() => {
+        clearTimeout(grace);
+        finish(code);
+      });
+    });
+  });
+}
+function defaultDeps(env, over = {}) {
+  const signal = over.signal;
+  const ownGroup = over.ownGroup ?? true;
+  const run2 = (cmd, args, e) => runProbe(cmd, args, e, signal, PROBE_TIMEOUT_MS, void 0, ownGroup);
+  return {
+    env,
+    platform: process.platform,
+    home: os6.homedir(),
+    user: env.USER || (() => {
+      try {
+        return os6.userInfo().username;
+      } catch {
+        return "";
+      }
+    })(),
+    nodeVersion: process.versions.node,
+    uid: process.getuid?.() ?? null,
+    now: () => Date.now(),
+    probe: run2,
+    crontab: async () => {
+      const r = await run2("crontab", ["-l"], env);
+      return r.code === 0 ? r.out : null;
+    },
+    exec: (cmd, args) => run2(cmd, args, env),
+    writable: async (dir) => {
+      const code = await errnoOf(fsp.access(dir, fs15.constants.W_OK));
+      return code === "" ? null : code ?? "ETIMEDOUT";
+    },
+    get: async (url) => {
+      try {
+        const r = await fetch(url, { signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(8e3)]) : AbortSignal.timeout(8e3), redirect: "manual" });
+        await r.body?.cancel().catch(() => void 0);
+        return { status: r.status };
+      } catch (e) {
+        const cause = e.cause;
+        return { error: cause instanceof Error ? `${errMessage(e)} (${cause.message})` : errMessage(e) };
+      }
+    },
+    ...over
+  };
+}
+async function which(cmd, pathVar) {
+  const executable = async (p) => await within2(fsp.stat(p).then(async (st) => st.isFile() && await fsp.access(p, fs15.constants.X_OK).then(() => true, () => false), () => false)) === true;
+  if (cmd.includes("/")) return await executable(cmd) ? cmd : null;
+  for (const dir of (pathVar ?? "").split(path18.delimiter)) {
+    if (!dir) continue;
+    const p = path18.join(dir, cmd);
+    if (await executable(p)) return p;
+  }
+  return null;
+}
+var agentEnv = (env, a) => ({ ...env, ...a.env });
+function familyOf(a) {
+  const words = [a.command, ...a.args].map((s) => path18.basename(s));
+  if (words.some((s) => s.includes("claude-agent-acp") || s.includes("claude-code-acp"))) return "claude";
+  if (words.some((s) => s.includes("codex-acp"))) return "codex";
+  if (path18.basename(a.command) === "agent" || path18.basename(a.command) === "cursor-agent") return "cursor";
+  return "other";
+}
+var LOGIN_FIX = {
+  claude: "claude auth login",
+  codex: "codex login",
+  cursor: "agent login"
+};
+function installFix(cmd, family) {
+  const base = path18.basename(cmd);
+  if (base === "npx" || base === "node") return "install Node.js 22 or newer (it brings npx): https://nodejs.org";
+  if (family === "cursor") return "install the Cursor CLI: curl https://cursor.com/install -fsS | bash";
+  return `install ${base}, or set this agent's command in agents.toml to its full path`;
+}
+var set = (env, name) => typeof env[name] === "string" && env[name] !== "";
+async function claudeSignedIn(env, d) {
+  const keys = ["ANTHROPIC_API_KEY", "ANTHROPIC_AUTH_TOKEN", "CLAUDE_CODE_OAUTH_TOKEN", "CLAUDE_CODE_USE_BEDROCK", "CLAUDE_CODE_USE_VERTEX", "CLAUDE_CODE_USE_FOUNDRY"];
+  if (keys.some((k) => set(env, k))) return true;
+  const dir = env.CLAUDE_CONFIG_DIR?.trim() || path18.join(d.home, ".claude");
+  const settings = await readJson(path18.join(dir, "settings.json"));
+  if (settings && (typeof settings.apiKeyHelper === "string" || isObject(settings.env) && keys.some((k) => typeof settings.env[k] === "string"))) return true;
+  const claude = await which("claude", env.PATH);
+  if (claude) {
+    const r = await d.probe(claude, ["auth", "status", "--json"], env);
+    try {
+      const v = JSON.parse(r.out.slice(r.out.indexOf("{")));
+      if (isObject(v) && typeof v.loggedIn === "boolean") return v.loggedIn;
+    } catch {
+    }
+  }
+  if (await fileExists(path18.join(dir, ".credentials.json"))) return true;
+  if (d.platform === "darwin") return null;
+  return false;
+}
+async function codexAuth(env, d) {
+  const home = env.CODEX_HOME?.trim() || path18.join(d.home, ".codex");
+  let cfg = {};
+  try {
+    const t = await readText(path18.join(home, "config.toml"));
+    if (t !== null) cfg = parseToml2(t);
+  } catch {
+  }
+  const name = typeof cfg.model_provider === "string" ? cfg.model_provider : "openai";
+  const providers = isObject(cfg.model_providers) ? cfg.model_providers : {};
+  const provider = isObject(providers[name]) ? providers[name] : null;
+  if (name !== "openai" && provider && provider.requires_openai_auth !== true) {
+    const key = typeof provider.env_key === "string" ? provider.env_key : null;
+    if (!key || set(env, key)) return { ok: true };
+    if (!/^[A-Za-z_][A-Za-z0-9_]{0,127}$/.test(key)) return { ok: false, detail: `Codex's model provider "${name.slice(0, 64)}" has an env_key that is not a variable name`, fix: `set env_key in ${path18.join(home, "config.toml")} to the NAME of the variable that holds the key` };
+    return { ok: false, detail: `Codex uses the model provider "${name}", which reads ${key}, and ${key} is not set where the connector runs`, fix: `set ${key} for this agent: add it to the agent's env in agents.toml, or export it before starting the connector` };
+  }
+  if (set(env, "OPENAI_API_KEY")) return { ok: true };
+  const codex = await which("codex", env.PATH);
+  if (codex) {
+    const r = await d.probe(codex, ["login", "status"], env);
+    if (r.code === 0 && !/not logged in/i.test(r.out)) return { ok: true };
+    if (/not logged in/i.test(r.out)) return { ok: false, detail: "Codex is not signed in on this machine", fix: LOGIN_FIX.codex };
+  }
+  if (await fileExists(path18.join(home, "auth.json"))) return { ok: true };
+  if (codex || typeof cfg.cli_auth_credentials_store === "string" && cfg.cli_auth_credentials_store !== "file") return null;
+  return { ok: false, detail: "Codex is not signed in on this machine", fix: "npm install -g @openai/codex, then: codex login" };
+}
+async function checkAll(input, d) {
+  const ok = [];
+  const problems = [...input.before ?? []];
+  const add = (p) => problems.push(p);
+  const major = Number(d.nodeVersion.split(".")[0]);
+  if (!Number.isFinite(major) || major < NODE_MIN_MAJOR) {
+    add({ code: "node_too_old", severity: "fail", detail: `Node.js ${d.nodeVersion} is older than ${NODE_MIN_MAJOR}`, fix: `install Node.js ${NODE_MIN_MAJOR} or newer (https://nodejs.org), then: npm install -g @primusclaw/connector` });
+  } else ok.push(`Node.js ${d.nodeVersion}`);
+  const servicePath = input.by === "doctor" ? await installedServicePath(input.dirs) : null;
+  const same = (x, y) => x.length === y.length && x.every((v, i) => v === y[i]);
+  const checked = input.agents.filter((a) => !(a.attach && input.agents.some((b) => !b.attach && b.command === a.command && same(b.args, a.args) && same(b.roots, a.roots))));
+  const perAgent = await Promise.all(checked.map(async (a) => {
+    const env = agentEnv(d.env, a);
+    const family = familyOf(a);
+    const out = { ok: [], problems: [] };
+    const found = await which(a.command, env.PATH);
+    if (!found) {
+      out.problems.push({ code: "agent_cli_missing", severity: "fail", agent: a.id, detail: `${a.command} (the program agent ${a.id} runs) is not on PATH`, fix: installFix(a.command, family) });
+    } else {
+      out.ok.push(`${a.id}: ${a.command} is ${found}`);
+      if (servicePath !== null && a.env.PATH === void 0 && !await which(a.command, servicePath)) {
+        out.problems.push({ code: "service_path_missing", severity: "fail", agent: a.id, detail: `the installed service's PATH does not find ${a.command}, so the service cannot start agent ${a.id}`, fix: "claw-connector service install  (run it again from this shell: it carries this shell's PATH into the service)" });
+      }
+    }
+    if (family === "claude") {
+      const signed = await claudeSignedIn(env, d);
+      if (signed === false) out.problems.push({ code: "agent_not_signed_in", severity: "fail", agent: a.id, detail: "Claude Code is not signed in on this machine", fix: LOGIN_FIX.claude });
+      else if (signed) out.ok.push(`${a.id}: Claude Code is signed in`);
+    } else if (family === "codex") {
+      const auth = await codexAuth(env, d);
+      if (auth && !auth.ok) out.problems.push({ code: "agent_not_signed_in", severity: "fail", agent: a.id, detail: auth.detail, fix: auth.fix });
+      else if (auth?.ok) out.ok.push(`${a.id}: Codex can sign in`);
+    }
+    for (const root of a.roots) {
+      const why = await within2(Promise.resolve(d.writable(root)), d.fsTimeoutMs) ?? "ETIMEDOUT";
+      if (why === "ETIMEDOUT") continue;
+      if (why === null) out.ok.push(`${a.id}: ${root} is writable`);
+      else {
+        out.problems.push(why === "ENOENT" ? { code: "root_missing", severity: "fail", agent: a.id, detail: `${root} (a root of agent ${a.id}) does not exist`, fix: `mkdir -p ${shq(root)}  (or change roots in agents.toml)` } : { code: "root_not_writable", severity: "fail", agent: a.id, detail: `${root} (a root of agent ${a.id}) is not writable by ${d.user || "this user"}${why === "EROFS" ? " (a read-only file system)" : ""}`, fix: await rootFix(root, why, d) });
+      }
+    }
+    return out;
+  }));
+  for (const r of perAgent) {
+    ok.push(...r.ok);
+    problems.push(...r.problems);
+  }
+  for (const [upper, lower] of [["HTTPS_PROXY", "https_proxy"], ["HTTP_PROXY", "http_proxy"], ["NO_PROXY", "no_proxy"]]) {
+    const u = d.env[upper];
+    const l = d.env[lower];
+    if (u !== void 0 && l !== void 0 && u !== l) {
+      add({ code: "proxy_mismatch", severity: "warn", detail: `${upper} and ${lower} are set to different values${l === "" || u === "" ? " (one of them is empty)" : ""}; agents that read ${lower} (git, curl) take ${l === "" ? "no proxy" : "the other one"}`, fix: `export ${lower}="$${upper}"  (or unset the one you do not mean)` });
+    }
+  }
+  for (const name of ["HTTPS_PROXY", "https_proxy", "HTTP_PROXY", "http_proxy"]) {
+    const v = d.env[name];
+    if (!v) continue;
+    try {
+      new URL(v);
+    } catch {
+      add({ code: "proxy_invalid", severity: "warn", detail: `${name} is not a URL`, fix: `export ${name}=http://HOST:PORT  (or unset it)` });
+    }
+  }
+  await checkSupervisor(input, d, ok, add);
+  if (input.by === "doctor" && input.server) {
+    const r = await d.get(`${input.server.replace(/\/+$/, "")}/health`);
+    const shown = withoutUserinfo(input.server);
+    if ("status" in r && r.status < 500) ok.push(`Claw answers at ${shown}`);
+    else {
+      const why = "status" in r ? `HTTP ${r.status}` : r.error;
+      const proxied = ["HTTPS_PROXY", "https_proxy"].some((k) => set(d.env, k));
+      const untrusted = /certificate|self[- ]signed|UNABLE_TO_GET_ISSUER|CERT_/i.test(why);
+      if (untrusted) {
+        add({
+          code: "claw_tls_untrusted",
+          severity: "fail",
+          detail: `Node.js does not trust the certificate of ${shown} (${why.split(input.server).join(shown)})`,
+          fix: "export NODE_USE_SYSTEM_CA=1  (Node.js then trusts the CAs this machine trusts; or NODE_EXTRA_CA_CERTS=/path/to/ca.pem), then run the connector again; an installed service: claw-connector service install again so it carries it"
+        });
+      } else add({
+        code: "claw_unreachable",
+        severity: "fail",
+        detail: `${shown} does not answer (${why.split(input.server).join(shown)})`,
+        fix: proxied && !set(d.env, "NODE_USE_ENV_PROXY") ? "export NODE_USE_ENV_PROXY=1  (Node.js only uses HTTPS_PROXY when it is set; needs Node 22.21+ or 24+), then run the connector again" : `check that this machine reaches it: curl -sS ${shown.replace(/\/+$/, "")}/health`
+      });
+    }
+  }
+  return { checked_at: new Date(d.now()).toISOString(), by: input.by, ok, problems: dedupe(problems) };
+}
+function withoutUserinfo(v) {
+  try {
+    const u = new URL(v);
+    return `${u.protocol}//${u.host}${u.pathname === "/" && !v.endsWith("/") ? "" : u.pathname}`;
+  } catch {
+    return v.replace(/\/\/[^/@]*@/, "//").replace(/[?#].*$/, "");
   }
-  /** Return what was pending and forget it. */
-  takePending() {
-    const out = this.pending;
-    this.pending = [];
-    if (out.length) this.savePending();
-    return out;
+}
+function dedupe(ps) {
+  const seen = /* @__PURE__ */ new Set();
+  return ps.filter((p) => {
+    const k = `${p.code}\0${p.detail}`;
+    if (seen.has(k)) return false;
+    seen.add(k);
+    return true;
+  });
+}
+async function rootFix(root, why, d) {
+  if (why === "EROFS") return "pick a root on a writable disk in agents.toml";
+  const owner = await within2(fsp.stat(root).then((st) => st.uid, () => null));
+  if (owner !== null && d.uid !== null && owner !== d.uid) return `pick a root you own in agents.toml (${root} belongs to uid ${owner})`;
+  return `chmod u+w ${shq(root)}  (or pick a root you own in agents.toml)`;
+}
+var shq = (s) => /^[A-Za-z0-9_./~:@%+-]+$/.test(s) ? s : `'${s.replace(/'/g, `'\\''`)}'`;
+async function installedSupervisorOf(dirs) {
+  const v = await readJson(serviceFile(dirs));
+  return v && typeof v.supervisor === "string" ? v.supervisor : null;
+}
+async function checkSupervisor(input, d, ok, add) {
+  const sup = await installedSupervisorOf(input.dirs);
+  if (sup === null) {
+    add({ code: "no_service", severity: "warn", detail: "the connector is not installed as a service: nothing starts it again after it dies or the machine restarts", fix: "claw-connector service install" });
+    return;
   }
-  savePending() {
-    fs13.mkdirSync(path15.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);
+  if (sup === "systemd") {
+    if (d.platform !== "linux") return;
+    const linger = await d.exec("loginctl", ["show-user", d.user, "-p", "Linger", "--value"]);
+    if (linger.code === 0 && linger.out.trim() !== "yes") {
+      add({ code: "linger_off", severity: "warn", detail: "the systemd user service stops when you log out and does not start at boot", fix: `loginctl enable-linger ${d.user}` });
+    } else ok.push("service: systemd --user");
+    return;
   }
-  ids() {
-    return Object.keys(this.recs);
+  if (sup === "script") {
+    const last = await within2(fsp.stat(keepaliveStampFile(input.dirs)).then((st) => st.mtimeMs, () => 0)) ?? 0;
+    if (d.now() - last <= KEEPALIVE_STALE_MS) {
+      ok.push("service: keep-alive script, called recently");
+      return;
+    }
+    const script = keepaliveFile(input.dirs);
+    const tab = await d.crontab();
+    if (tab !== null && tab.split("\n").some((l) => !l.trim().startsWith("#") && l.includes(script))) {
+      ok.push("service: keep-alive script in crontab");
+      return;
+    }
+    add({
+      code: "keepalive_not_scheduled",
+      severity: "warn",
+      detail: `nothing has run ${script} in the last ${KEEPALIVE_STALE_MS / 6e4} minutes: after a restart the connector stays offline`,
+      fix: `add to crontab -e (or the container's startup hook): */5 * * * * sh ${script}`
+    });
+    return;
   }
-  save() {
-    fs13.mkdirSync(path15.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);
+  ok.push(`service: ${sup}`);
+}
+async function installedServicePath(dirs, home = os6.homedir(), xdgConfig) {
+  const v = await readJson(serviceFile(dirs));
+  if (!v) return null;
+  if (typeof v.path === "string") return v.path;
+  if (v.supervisor === "script") {
+    const m = (await readText(keepaliveFile(dirs)))?.match(/^export PATH='((?:[^']|'\\'')*)'$/m);
+    return m ? m[1].replace(/'\\''/g, "'") : null;
+  }
+  if (v.supervisor === "systemd") {
+    const unit = await readText(path18.join(xdgConfig?.trim() || path18.join(home, ".config"), "systemd", "user", "claw-connector.service"));
+    const m = unit?.match(/^Environment="PATH=((?:[^"\\]|\\.)*)"$/m);
+    return m ? m[1].replace(/\\(.)/g, "$1").replace(/%%/g, "%") : null;
+  }
+  if (v.supervisor === "launchd") {
+    const plist = await readText(path18.join(home, "Library", "LaunchAgents", "com.primusclaw.connector.plist"));
+    const m = plist?.match(/<key>PATH<\/key><string>([^<]*)<\/string>/);
+    return m ? m[1].replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&amp;/g, "&") : null;
   }
-};
+  return null;
+}
+function agentHealth(report, agentId) {
+  const cut = (s, n) => s.length > n ? `${s.slice(0, n - 1)}\u2026` : s;
+  const mine = report.problems.filter((p) => p.agent === void 0 || p.agent === agentId);
+  mine.sort((a, b) => a.severity === b.severity ? 0 : a.severity === "fail" ? -1 : 1);
+  return {
+    checked_at: report.checked_at,
+    problems: mine.slice(0, MAX_REPORTED2).map((p) => ({ code: p.code, severity: p.severity, scope: p.agent === void 0 ? "machine" : "agent", detail: cut(p.detail, 200), fix: cut(p.fix, 200) }))
+  };
+}
+function writeReport(dirs, report) {
+  try {
+    fs15.mkdirSync(dirs.state, { recursive: true, mode: 448 });
+    const file = doctorFile(dirs);
+    const tmp = `${file}.${process.pid}.tmp`;
+    fs15.writeFileSync(tmp, JSON.stringify(report, null, 2) + "\n", { mode: 384 });
+    fs15.renameSync(tmp, file);
+  } catch {
+  }
+}
+function formatReport(r) {
+  const lines = r.ok.map((l) => `ok    ${l}`);
+  for (const p of r.problems) {
+    lines.push(`${p.severity === "fail" ? "FAIL" : "warn"}  ${p.agent ? `${p.agent}: ` : ""}${p.detail}`);
+    lines.push(`      fix: ${p.fix}`);
+  }
+  const fails = r.problems.filter((p) => p.severity === "fail").length;
+  const warns = r.problems.length - fails;
+  lines.push("");
+  lines.push(r.problems.length === 0 ? "No problems found." : `${fails} problem${fails === 1 ? " that stops" : "s that stop"} sessions, ${warns} warning${warns === 1 ? "" : "s"}.`);
+  return lines;
+}
 
 // src/connector.ts
+function withHealth(base, health, limit = REMOTE_AGENT_LIMITS.maxCapabilitiesBytes / 2) {
+  if (!health) return base;
+  const size = (c) => new TextEncoder().encode(JSON.stringify(c)).length;
+  const problems = [...health.problems];
+  for (; ; ) {
+    const caps = { ...base, health: { ...health, problems } };
+    if (size(caps) <= limit) return caps;
+    if (problems.length === 0) return base;
+    problems.pop();
+  }
+}
+var RESTART_RECONNECT_GAP_MS = 5e3;
+var READ_ONLY_HINT = `sessions of this agent start read-only: it answers and plans but changes no file. To let phone sessions write code, set approval = "never" for this agent in agents.toml on that machine and restart the connector`;
 var DEFAULT_TIMING = {
   ...DEFAULT_SESSION_TIMING,
   heartbeatMs: REMOTE_AGENT_TIMING.heartbeatMs,
@@ -3297,11 +4829,17 @@ var DEFAULT_TIMING = {
   backoffMaxMs: 6e4,
   pausePollMs: 1e3,
   catalogMs: 12e4,
+  sessionsWatchMs: 1e4,
   attachCliMs: 8e3,
   recentWriteMs: 1e4,
   authFailLimit: 4,
-  authFailWindowMs: 12e4
+  authFailWindowMs: 12e4,
+  healthMs: RECHECK_MS,
+  healthMinGapMs: 5e3,
+  limitRetryMs: 10 * 6e4
 };
+var CONNECTOR_LIMIT_HINT = "Claw already holds the most connectors one person may have, so it will not register this machine: remove machines you no longer use (in the chat: /agents, or claw-connector logout on that machine). This connector tries again every 10 minutes by itself.";
+var isConnectorLimit = (e) => e instanceof HttpError && e.status === 409 && e.code === "connector_limit_reached";
 var CommandLedger = class {
   inflight = /* @__PURE__ */ new Set();
   inflightIds = /* @__PURE__ */ new Set();
@@ -3402,6 +4940,11 @@ var Connector = class {
   lastFrame = "";
   wakeSender = null;
   wakeHeartbeat = null;
+  /** The last health report (null until the first check finishes, or when none is configured). */
+  healthReport = null;
+  wakeHealth = null;
+  healthAsked = false;
+  lastHealthAsk = 0;
   streamCtl = null;
   ctl = new AbortController();
   /** Every event leaves through here: scrubbed of credential shapes, numbered, written to disk, then posted. */
@@ -3423,8 +4966,19 @@ 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 readOnly = a.readOnlyModes.includes(a.askMode);
       const support = this.attach.get(a.id);
+      const base = withHealth({
+        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 } : {},
+        ...a.readOnlyModes.length ? { read_only_modes: a.readOnlyModes } : {},
+        ...readOnly ? { edits: false, edits_hint: READ_ONLY_HINT } : {}
+      }, this.healthReport ? agentHealth(this.healthReport, a.id) : null);
       const capabilities = support ? fitResumable(base, await support.resumable()) : base;
       return { agent_id: a.id, kind: a.kind, name: a.name, capabilities };
     }));
@@ -3432,7 +4986,7 @@ var Connector = class {
   // --- identity -------------------------------------------------------------------
   readIdentity() {
     try {
-      const raw = JSON.parse(fs14.readFileSync(identityFile(this.d.dirs), "utf8"));
+      const raw = JSON.parse(fs16.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 +4997,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);
+    fs16.mkdirSync(this.d.dirs.state, { recursive: true, mode: 448 });
+    fs16.writeFileSync(`${file}.tmp`, JSON.stringify(st), { mode: 384 });
+    fs16.renameSync(`${file}.tmp`, file);
   }
   /** Use the connector id this machine already has, or register a new one. */
   async identify(forceNew = false) {
@@ -3487,6 +5041,7 @@ var Connector = class {
    * fix and ends the run with its message.
    */
   async startup() {
+    let atLimit = false;
     for (let attempt = 0; !this.ctl.signal.aborted; attempt++) {
       try {
         await this.identify();
@@ -3497,6 +5052,17 @@ var Connector = class {
           await this.onRevoked(e);
           return "revoked";
         }
+        if (isConnectorLimit(e)) {
+          if (!atLimit) {
+            atLimit = true;
+            this.d.log.error(CONNECTOR_LIMIT_HINT, { error: errMessage(e) });
+            this.d.audit.record("connector_limit_reached", {});
+            recordDisconnect(this.d.dirs, { reason: "connector_limit_reached", detail: CONNECTOR_LIMIT_HINT });
+          }
+          await sleep(this.timing.limitRetryMs, this.ctl.signal);
+          while (!this.ctl.signal.aborted && fs16.existsSync(pauseFile(this.d.dirs))) await sleep(this.timing.pausePollMs, this.ctl.signal);
+          continue;
+        }
         if (!isTransient(e)) throw e;
         this.d.log.warn("cannot reach Claw yet; will retry", { error: errMessage(e), attempt });
         await sleep(backoffMs(attempt, this.timing.backoffMinMs, this.timing.backoffMaxMs), this.ctl.signal);
@@ -3552,7 +5118,7 @@ var Connector = class {
   }
   async pauseWatcher() {
     while (!this.ctl.signal.aborted) {
-      const want = fs14.existsSync(pauseFile(this.d.dirs));
+      const want = fs16.existsSync(pauseFile(this.d.dirs));
       if (want && !this.paused) {
         this.paused = true;
         this.d.audit.record("paused");
@@ -3567,6 +5133,63 @@ var Connector = class {
       await sleep(this.timing.pausePollMs, this.ctl.signal);
     }
   }
+  /**
+   * Check the machine at start, every `healthMs`, and when asked (`recheckHealth`: `claw-connector doctor` signals a running
+   * connector after it ran). A changed result is sent with an early heartbeat. A check that throws keeps the last report, and
+   * a stop never waits for one: it must never take the connection down. Nothing here touches the file system itself (the
+   * checks run in a child process: see commands.ts `runHealth`), so a stalled disk cannot reach this process.
+   */
+  async healthWatcher() {
+    const check = this.d.health;
+    if (!check) return;
+    while (!this.ctl.signal.aborted) {
+      this.healthAsked = false;
+      try {
+        const before = this.healthReport ? JSON.stringify(this.healthReport.problems) : null;
+        let onAbort = () => {
+        };
+        const stopped = new Promise((resolve) => {
+          onAbort = () => resolve(null);
+          if (this.ctl.signal.aborted) resolve(null);
+          else this.ctl.signal.addEventListener("abort", onAbort, { once: true });
+        });
+        let report;
+        try {
+          report = await Promise.race([check(this.ctl.signal), stopped]);
+        } finally {
+          this.ctl.signal.removeEventListener("abort", onAbort);
+        }
+        if (report === null) break;
+        this.healthReport = report;
+        if (JSON.stringify(this.healthReport.problems) !== before) {
+          this.d.log.info("health", { problems: this.healthReport.problems.map((p) => `${p.agent ?? "machine"}:${p.code}`) });
+          this.wakeHeartbeat?.();
+        }
+      } catch (e) {
+        this.d.log.warn("health check failed", { error: errMessage(e) });
+      }
+      if (this.healthAsked) continue;
+      await new Promise((resolve) => {
+        const done = () => {
+          clearTimeout(t);
+          this.wakeHealth = null;
+          this.ctl.signal.removeEventListener("abort", done);
+          resolve();
+        };
+        const t = setTimeout(done, this.timing.healthMs);
+        this.wakeHealth = done;
+        this.ctl.signal.addEventListener("abort", done, { once: true });
+      });
+    }
+  }
+  /** Check the machine again now (a `doctor` run asks; at most once per `healthMinGapMs`, so a burst of asks is one check). */
+  recheckHealth() {
+    const now = Date.now();
+    if (now - this.lastHealthAsk < this.timing.healthMinGapMs) return;
+    this.lastHealthAsk = now;
+    this.healthAsked = true;
+    this.wakeHealth?.();
+  }
   // --- the loops -----------------------------------------------------------------------
   /** Post events in batches, one request at a time and in order, until everything is acknowledged. */
   async sender() {
@@ -3606,6 +5229,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 +5312,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 +5323,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 +5332,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,50 +5370,57 @@ 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 });
+    fs16.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 });
       this.emit(p.session_id, "permission_resolved", { actionId: p.action_id, optionId: null, outcome: "cancelled", by: "connector_restart" });
     }
+    let downForMs = null;
+    try {
+      downForMs = Math.max(0, Date.now() - fs16.statSync(identityFile(this.d.dirs)).mtimeMs);
+    } catch {
+    }
     const pidf = pidFile(this.d.dirs);
     let leftover = false;
     try {
-      fs14.readFileSync(pidf);
+      fs16.readFileSync(pidf);
       leftover = true;
     } catch {
     }
     if (leftover) {
       let last;
       try {
-        last = fs14.statSync(identityFile(this.d.dirs)).mtime.toISOString();
+        last = fs16.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));
+    fs16.writeFileSync(pidf, JSON.stringify({ pid: process.pid, start: processStart(process.pid) ?? "" }), { mode: 384 });
+    this.paused = fs16.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.manager.recover({ downForMs, mayContinue: !this.paused && !fs16.existsSync(pauseFile(this.d.dirs)) });
       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(), this.healthWatcher()]);
       result = this.revoked ? "revoked" : this.authFailed ? "auth_failed" : "stopped";
     } catch (e) {
       failure = errMessage(e);
       throw e;
     } finally {
-      await this.manager.killAll(this.revoked ? "revoked" : "stopped").catch(() => void 0);
+      await this.manager.killAll(this.revoked ? "revoked" : "stopped", !this.revoked && !this.authFailed).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 });
+      fs16.rmSync(pidf, { force: true });
     }
     return result;
   }
@@ -3779,12 +5436,13 @@ var Connector = class {
 };
 
 // src/service.ts
-import { spawn as spawn2, spawnSync } from "node:child_process";
-import fs15 from "node:fs";
-import os5 from "node:os";
-import path16 from "node:path";
+import { spawn as spawn4, spawnSync } from "node:child_process";
+import fs17 from "node:fs";
+import os7 from "node:os";
+import path19 from "node:path";
 import { fileURLToPath } from "node:url";
 import { parseArgs } from "node:util";
+import { parse as parseToml3 } from "smol-toml";
 var SUPERVISORS = ["systemd", "launchd", "script"];
 var UNIT = "claw-connector.service";
 var LABEL = "com.primusclaw.connector";
@@ -3793,11 +5451,14 @@ var NEEDS_PERSON = 78;
 var CARRIED_ENV = [
   "PATH",
   "CLAW_CONNECTOR_HOME",
+  "CLAW_CONNECTOR_CONFIG_DIR",
   "XDG_CONFIG_HOME",
   "XDG_STATE_HOME",
   "CLAUDE_CONFIG_DIR",
   "CODEX_HOME",
   "NODE_EXTRA_CA_CERTS",
+  "NODE_USE_SYSTEM_CA",
+  "NODE_USE_ENV_PROXY",
   "SSL_CERT_FILE",
   "HTTPS_PROXY",
   "https_proxy",
@@ -3805,27 +5466,97 @@ var CARRIED_ENV = [
   "http_proxy",
   "NO_PROXY",
   "no_proxy",
-  "LANG"
+  "LANG",
+  "IS_SANDBOX",
+  "npm_config_registry",
+  "NPM_CONFIG_REGISTRY",
+  "npm_config_proxy",
+  "npm_config_https_proxy",
+  "AWS_REGION",
+  "AWS_PROFILE",
+  "CLOUD_ML_REGION",
+  "GOOGLE_APPLICATION_CREDENTIALS"
 ];
-var SECRET_NAME = /KEY|TOKEN|SECRET|PASSWORD|CREDENTIAL/i;
+var AGENT_SETTING = /^(?:ANTHROPIC|CLAUDE_CODE|OPENAI|CODEX|CURSOR)_/;
+var TERMINAL_SESSION = /^(?:CLAUDE_CODE_(?:ENTRYPOINT|SSE_PORT|SESSION|CHILD_SESSION|MESSAGING|EXECPATH|IDE|GIT_BASH)|CODEX_(?:SANDBOX|THREAD|SESSION|MANAGED|INTERNAL|CI))/;
+var SECRET_NAME = /KEY|TOKEN(?!S)|SECRET|PASSWORD|CREDENTIAL/i;
+var AGENT_SECRETS = [
+  "ANTHROPIC_API_KEY",
+  "ANTHROPIC_AUTH_TOKEN",
+  "CLAUDE_CODE_OAUTH_TOKEN",
+  "ANTHROPIC_CUSTOM_HEADERS",
+  "OPENAI_API_KEY",
+  "CODEX_API_KEY",
+  "CURSOR_API_KEY",
+  "AWS_ACCESS_KEY_ID",
+  "AWS_SECRET_ACCESS_KEY",
+  "AWS_SESSION_TOKEN"
+];
+var NEVER_CARRIED = /* @__PURE__ */ new Set(["CLAW_CONNECTOR_KEY"]);
+function accountName(env, uid, userInfo = os7.userInfo) {
+  if (env.USER) return env.USER;
+  if (env.LOGNAME) return env.LOGNAME;
+  try {
+    return userInfo().username;
+  } catch {
+    return String(uid);
+  }
+}
+function cronDaemonRunning(proc = "/proc") {
+  let self;
+  let pids;
+  try {
+    self = fs17.readlinkSync(`${proc}/self/ns/mnt`);
+    pids = fs17.readdirSync(proc).filter((n) => /^\d+$/.test(n));
+  } catch {
+    return false;
+  }
+  for (const pid of pids) {
+    try {
+      if (!/^(?:cron|crond|busybox)$/.test(fs17.readFileSync(`${proc}/${pid}/comm`, "utf8").trim())) continue;
+      if (!/cron/.test(fs17.readFileSync(`${proc}/${pid}/cmdline`, "utf8"))) continue;
+      if (fs17.readlinkSync(`${proc}/${pid}/ns/mnt`) === self) return true;
+    } catch {
+    }
+  }
+  return false;
+}
+function systemCrontab() {
+  return {
+    readCrontab: () => {
+      if (!cronDaemonRunning()) return null;
+      const r = spawnSync("crontab", ["-l"], { encoding: "utf8", timeout: 1e4, stdio: ["ignore", "pipe", "pipe"] });
+      if (r.error) return null;
+      return r.status === 0 ? r.stdout : /no crontab/i.test(r.stderr ?? "") ? "" : null;
+    },
+    writeCrontab: (text) => {
+      const r = spawnSync("crontab", ["-"], { input: text, encoding: "utf8", timeout: 1e4, stdio: ["pipe", "pipe", "pipe"] });
+      return !r.error && r.status === 0;
+    }
+  };
+}
 function deps(ctx) {
   const d = ctx.service ?? {};
+  const uid = d.uid ?? (process.getuid?.() ?? 0);
+  const cron = d.readCrontab && d.writeCrontab ? null : systemCrontab();
   return {
     platform: d.platform ?? process.platform,
-    home: d.home ?? os5.homedir(),
-    uid: d.uid ?? (process.getuid?.() ?? 0),
-    user: d.user ?? (ctx.env.USER || os5.userInfo().username),
+    home: d.home ?? os7.homedir(),
+    uid,
+    user: d.user ?? accountName(ctx.env, uid),
+    readCrontab: d.readCrontab ?? cron.readCrontab,
+    writeCrontab: d.writeCrontab ?? cron.writeCrontab,
     exec: d.exec ?? ((cmd, args) => {
       const r = spawnSync(cmd, args, { encoding: "utf8", timeout: 3e4, stdio: ["ignore", "pipe", "pipe"] });
       return { code: r.error ? null : r.status, out: `${r.stdout ?? ""}${r.stderr ?? ""}`.trim() };
     }),
     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 ?? (() => fs17.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) => path19.join(ctx.env.XDG_CONFIG_HOME?.trim() || path19.join(d.home, ".config"), "systemd", "user", UNIT);
+var launchdPlistPath = (d) => path19.join(d.home, "Library", "LaunchAgents", `${LABEL}.plist`);
 function detectSupervisor(d) {
   if (d.platform === "darwin") return "launchd";
   if (!d.systemdBooted()) return "script";
@@ -3835,29 +5566,71 @@ function detectSupervisor(d) {
 var hasUserinfo = (v) => {
   try {
     const u = new URL(v);
-    return u.username !== "" || u.password !== "";
+    if (u.username !== "" || u.password !== "") return true;
   } catch {
-    return /\/\/[^/]*@/.test(v);
   }
+  return /\/\/[^/\s]*@/.test(v);
 };
-function carriedEnv(env, extra = []) {
+function codexEnvKeys(env, home) {
+  const dir = env.CODEX_HOME?.trim() || path19.join(home, ".codex");
+  try {
+    const doc = parseToml3(fs17.readFileSync(path19.join(dir, "config.toml"), "utf8"));
+    const providers = isObject(doc.model_providers) ? doc.model_providers : {};
+    return Object.values(providers).flatMap((p) => isObject(p) && typeof p.env_key === "string" && /^[A-Za-z_][A-Za-z0-9_]*$/.test(p.env_key) ? [p.env_key] : []);
+  } catch {
+    return [];
+  }
+}
+function carriedEnv(env, extra = [], secretNames = AGENT_SECRETS) {
   const vars = [];
+  const secrets = [];
   const refused = [];
   const withheld = [];
-  for (const name of /* @__PURE__ */ new Set([...CARRIED_ENV, ...extra])) {
-    if (!CARRIED_ENV.includes(name) && SECRET_NAME.test(name)) {
-      refused.push(name);
+  const settings = Object.keys(env).filter((k) => AGENT_SETTING.test(k) && !TERMINAL_SESSION.test(k)).sort();
+  for (const name of /* @__PURE__ */ new Set([...CARRIED_ENV, ...settings, ...secretNames, ...extra])) {
+    if (NEVER_CARRIED.has(name)) {
+      if (extra.includes(name)) refused.push(name);
       continue;
     }
     const v = env[name];
     if (v === void 0 || v === "") continue;
-    if (/proxy$/i.test(name) && hasUserinfo(v) && !extra.includes(name)) {
+    const proxy = /proxy$/i.test(name);
+    const secret = !CARRIED_ENV.includes(name) && (SECRET_NAME.test(name) || secretNames.includes(name)) || !proxy && hasUserinfo(v);
+    if (secret) {
+      secrets.push([name, v]);
+      continue;
+    }
+    if (proxy && hasUserinfo(v) && !extra.includes(name)) {
+      withheld.push(name);
+      continue;
+    }
+    if (/[\r\n]/.test(v)) {
       withheld.push(name);
       continue;
     }
     vars.push([name, v]);
   }
-  return { vars, refused, withheld };
+  return { vars, secrets, refused, withheld };
+}
+function applyServiceEnv(agents, kept, env) {
+  const used = /* @__PURE__ */ new Set();
+  for (const a of agents) {
+    for (const [k, v] of Object.entries(kept)) {
+      if (env[k] !== void 0 || Object.hasOwn(a.env, k)) continue;
+      a.env = { ...a.env, [k]: v };
+      used.add(k);
+    }
+  }
+  return [...used].sort();
+}
+function loadServiceEnv(file) {
+  try {
+    const raw = JSON.parse(fs17.readFileSync(file, "utf8"));
+    if (!isObject(raw)) return {};
+    return Object.fromEntries(Object.entries(raw).filter((e) => typeof e[1] === "string" && !NEVER_CARRIED.has(e[0])));
+  } catch {
+    return {};
+  }
 }
 var sdEnv = (s) => `"${s.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/%/g, "%%")}"`;
 var sdQuote = (s) => sdEnv(s).replace(/\$/g, "$$$$");
@@ -3875,12 +5648,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 +5699,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(fs17.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 +5719,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 });
+  fs17.mkdirSync(ctx.dirs.state, { recursive: true, mode: 448 });
+  fs17.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 +5735,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 = spawn4(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,13 +5764,14 @@ 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) fs17.rmSync(pidf, { force: true });
   }
 }
 async function cmdSupervise(_args, ctx) {
   return supervise(ctx);
 }
-async function ensure(ctx, d, h) {
+async function ensure(ctx, d, h, o = {}) {
+  if (!o.byInstall) stampKeepalive(ctx);
   const sup = supervisorPid(ctx);
   if (sup !== null) {
     ctx.out(`supervisor running (pid ${sup})`);
@@ -4011,17 +5787,24 @@ 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);
+  fs17.mkdirSync(ctx.dirs.state, { recursive: true, mode: 448 });
+  const log = fs17.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 = spawn4(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);
+    fs17.closeSync(log);
   }
   return 0;
 }
+function stampKeepalive(ctx) {
+  try {
+    fs17.mkdirSync(ctx.dirs.state, { recursive: true, mode: 448 });
+    fs17.writeFileSync(keepaliveStampFile(ctx.dirs), (/* @__PURE__ */ new Date()).toISOString() + "\n", { mode: 384 });
+  } catch {
+  }
+}
 async function cmdService(args, ctx, h) {
   const [sub, ...rest] = args;
   const usage = "usage: claw-connector service install|uninstall|status [--supervisor systemd|launchd|script] [--env NAME ...]";
@@ -4048,7 +5831,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(fs17.readFileSync(serviceFile(ctx.dirs), "utf8"));
     if (isObject(raw) && typeof raw.supervisor === "string" && SUPERVISORS.includes(raw.supervisor)) return raw.supervisor;
   } catch {
   }
@@ -4068,11 +5851,67 @@ 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`);
 }
+var UnsafeDirError = class extends Error {
+};
+function writeSecretFile(file, body) {
+  const dir = path19.dirname(file);
+  fs17.mkdirSync(dir, { recursive: true, mode: 448 });
+  let dfd;
+  try {
+    dfd = fs17.openSync(dir, fs17.constants.O_RDONLY | (fs17.constants.O_DIRECTORY ?? 0) | (fs17.constants.O_NOFOLLOW ?? 0));
+  } catch (e) {
+    throw new UnsafeDirError(`${dir} cannot be opened as a directory of its own (${e.code ?? errMessage(e)}; a link is not followed): the agents' sign-in variables are not written there (set CLAW_CONNECTOR_CONFIG_DIR to a directory of your own)`);
+  }
+  try {
+    const st = fs17.fstatSync(dfd);
+    const uid = process.getuid?.();
+    if (!st.isDirectory() || uid !== void 0 && st.uid !== uid) {
+      throw new UnsafeDirError(`${dir} is ${!st.isDirectory() ? "not a directory" : "owned by another account"}: the agents' sign-in variables are not written there (set CLAW_CONNECTOR_CONFIG_DIR to a directory of your own)`);
+    }
+    if ((st.mode & 63) !== 0) fs17.fchmodSync(dfd, 448);
+    let anchored;
+    if (fs17.existsSync(`/proc/self/fd/${dfd}`)) anchored = `/proc/self/fd/${dfd}`;
+    else {
+      const real = fs17.realpathSync(dir);
+      const rs = fs17.statSync(real);
+      if (rs.dev !== st.dev || rs.ino !== st.ino) throw new UnsafeDirError(`${dir} changed while it was being checked; the agents' sign-in variables are not written there`);
+      const weak = renamableAncestor(real);
+      if (weak) throw new UnsafeDirError(`${weak} can be changed by other accounts, so ${dir} could be swapped while the agents' sign-in variables are written; they are not written there (set CLAW_CONNECTOR_CONFIG_DIR to a directory of your own)`);
+      anchored = real;
+    }
+    const tmp = path19.join(anchored, `${path19.basename(file)}.${process.pid}.${Date.now()}.tmp`);
+    const fd = fs17.openSync(tmp, fs17.constants.O_WRONLY | fs17.constants.O_CREAT | fs17.constants.O_EXCL | (fs17.constants.O_NOFOLLOW ?? 0), 384);
+    try {
+      fs17.writeSync(fd, body);
+      fs17.fchmodSync(fd, 384);
+    } finally {
+      fs17.closeSync(fd);
+    }
+    fs17.renameSync(tmp, path19.join(anchored, path19.basename(file)));
+  } finally {
+    fs17.closeSync(dfd);
+  }
+}
+function renamableAncestor(dir, uid = process.getuid?.()) {
+  for (let p = path19.dirname(path19.resolve(dir)); ; p = path19.dirname(p)) {
+    let st;
+    try {
+      st = fs17.lstatSync(p);
+    } catch {
+      return p;
+    }
+    if (!st.isDirectory()) return p;
+    const owner = st.uid === 0 || uid === void 0 || st.uid === uid;
+    const sticky = (st.mode & 512) !== 0;
+    if (!owner || (st.mode & 18) !== 0 && !sticky) return p;
+    if (p === path19.dirname(p)) return null;
+  }
+}
 function writeFile600(file, body, mode = 384) {
-  fs15.mkdirSync(path16.dirname(file), { recursive: true, mode: 448 });
+  fs17.mkdirSync(path19.dirname(file), { recursive: true, mode: 448 });
   const tmp = `${file}.${process.pid}.tmp`;
-  fs15.writeFileSync(tmp, body, { mode });
-  fs15.renameSync(tmp, file);
+  fs17.writeFileSync(tmp, body, { mode });
+  fs17.renameSync(tmp, file);
 }
 async function install(ctx, d, h, sup, extra) {
   const problem = h.preflight(ctx);
@@ -4080,13 +5919,22 @@ 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 (!fs17.existsSync(d.cli)) {
     ctx.err(`${d.cli} does not exist (a source checkout needs "npm run build" first)`);
     return 1;
   }
-  const { vars, refused, withheld } = carriedEnv(ctx.env, extra);
-  for (const r of refused) ctx.err(`--env ${r}: not carried into the service (it looks like a credential)`);
-  for (const w of withheld) ctx.err(`${w}: not carried into the service because it holds a password; if the connector needs it, install again with --env ${w} (it is then written into the 0600 unit file)`);
+  const { vars, secrets, refused, withheld } = carriedEnv(ctx.env, extra, [...AGENT_SECRETS, ...codexEnvKeys(ctx.env, d.home)]);
+  for (const r of refused) ctx.err(`--env ${r}: not carried into the service (it is the connector's own key, kept in credentials.json)`);
+  for (const w of withheld) {
+    ctx.err(/[\r\n]/.test(ctx.env[w] ?? "") ? `${w}: not carried into the service because its value spans several lines` : `${w}: not carried into the service because it holds a password; if the connector needs it, install again with --env ${w} (it is then written into the 0600 unit file)`);
+  }
+  try {
+    saveServiceEnv(ctx, secrets);
+  } catch (e) {
+    if (!(e instanceof UnsafeDirError)) throw e;
+    ctx.err(`cannot install the service: ${e.message}`);
+    return 1;
+  }
   const manual = h.runningPid(ctx);
   if (manual !== null && supervisorPid(ctx) === null) {
     await h.stop(ctx);
@@ -4096,7 +5944,7 @@ async function install(ctx, d, h, sup, extra) {
   if (sup === "systemd") {
     const unit = systemdUnitPath(ctx, d);
     writeFile600(unit, systemdUnit(d, vars));
-    recordInstalled(ctx, "systemd");
+    recordInstalled(ctx, "systemd", vars);
     if (!d.systemdBooted()) {
       ctx.err("systemd is not this machine's init (no /run/systemd/system): use --supervisor script");
       return 1;
@@ -4119,7 +5967,7 @@ async function install(ctx, d, h, sup, extra) {
   } else if (sup === "launchd") {
     const plist = launchdPlistPath(d);
     writeFile600(plist, launchdPlist(d, vars, runLogFile(ctx.dirs)));
-    recordInstalled(ctx, "launchd");
+    recordInstalled(ctx, "launchd", vars);
     d.exec("launchctl", ["bootout", `gui/${d.uid}/${LABEL}`]);
     const r = d.exec("launchctl", ["bootstrap", `gui/${d.uid}`, plist]);
     if (r.code !== 0) {
@@ -4130,33 +5978,126 @@ async function install(ctx, d, h, sup, extra) {
   } else {
     const script = keepaliveFile(ctx.dirs);
     writeFile600(script, keepaliveScript(d, vars), 448);
-    recordInstalled(ctx, "script");
-    const code = await ensure(ctx, d, h);
+    recordInstalled(ctx, "script", vars);
+    const code = await ensure(ctx, d, h, { byInstall: true });
     if (code !== 0) return code;
-    ctx.out(`wrote ${script}. This machine has no systemd: the supervisor restarts the connector 5 s after it dies, but`);
-    ctx.out("nothing starts the supervisor after a reboot or a container restart. Add both of these (crontab -e, or your container's startup hook):");
-    ctx.out(`  @reboot sh ${script}`);
-    ctx.out(`  */5 * * * * sh ${script}`);
+    ctx.out(`wrote ${script}. This machine has no systemd: the supervisor restarts the connector 5 s after it dies.`);
+    scheduleKeepalive(ctx, d, script);
   }
   return 0;
 }
-function recordInstalled(ctx, sup) {
-  writeFile600(serviceFile(ctx.dirs), JSON.stringify({ supervisor: sup, installed_at: (/* @__PURE__ */ new Date()).toISOString() }));
+var cronLines = (script) => [`@reboot sh ${sh(script)} >/dev/null 2>&1`, `*/5 * * * * sh ${sh(script)} >/dev/null 2>&1`];
+function scheduleKeepalive(ctx, d, script) {
+  const tab = d.readCrontab();
+  const want = cronLines(script);
+  if (tab !== null) {
+    const lines = tab.split("\n");
+    if (lines[lines.length - 1] === "") lines.pop();
+    const kept = lines.filter((l) => !want.includes(l.trim()));
+    if (d.writeCrontab([...kept, ...want].join("\n") + "\n")) {
+      ctx.out(`added to your crontab, so it comes back after a reboot and within 5 minutes of the supervisor dying:`);
+      for (const l of want) ctx.out(`  ${l}`);
+      return;
+    }
+    ctx.err("could not write your crontab (crontab -); add the lines below by hand");
+  }
+  ctx.out("No cron daemon runs here: after a reboot or a container restart NOTHING starts the connector again.");
+  ctx.out("Run this from the container's startup command (it does nothing while the connector is up; ~/.bashrc works too, then it");
+  ctx.out("comes back when you next open a shell):");
+  ctx.out(`  sh ${sh(script)} >/dev/null 2>&1`);
+  const where = ephemeralWhere(ctx.dirs.config);
+  if (where) ctx.out(`Note: ${where}`);
+}
+function withoutOurCron(d, script) {
+  const tab = d.readCrontab();
+  if (tab === null) return null;
+  const ours = cronLines(script);
+  const lines = tab.split("\n");
+  if (lines[lines.length - 1] === "") lines.pop();
+  const kept = lines.filter((l) => !ours.includes(l.trim()));
+  return { tab: kept.length ? kept.join("\n") + "\n" : "", removed: lines.length - kept.length };
+}
+var EPHEMERAL_FS = /* @__PURE__ */ new Set(["overlay", "overlayfs", "aufs", "tmpfs"]);
+var PERSISTENT_FS = /^(?:ceph|nfs|nfs4|lustre|wekafs|gpfs|beegfs|cifs|smb3|fuse\.(?:ceph|juicefs|s3fs|gcsfuse|sshfs|rclone))$/;
+function readMounts(text) {
+  let raw = text;
+  if (raw === void 0) {
+    try {
+      raw = fs17.readFileSync("/proc/self/mountinfo", "utf8");
+    } catch {
+      return [];
+    }
+  }
+  const out = [];
+  for (const line of raw.split("\n")) {
+    const dash = line.indexOf(" - ");
+    if (dash < 0) continue;
+    const fields = line.slice(0, dash).split(" ");
+    const point = fields[4]?.replace(/\\([0-7]{3})/g, (_m, o) => String.fromCharCode(parseInt(o, 8)));
+    const fstype = line.slice(dash + 3).split(" ")[0];
+    if (point && fstype) out.push({ point, fstype });
+  }
+  return out;
+}
+function mountOf(p, mounts) {
+  let best = null;
+  for (const m of mounts) {
+    const inside2 = p === m.point || p.startsWith(m.point.endsWith("/") ? m.point : `${m.point}/`);
+    if (inside2 && (!best || m.point.length >= best.point.length)) best = m;
+  }
+  return best;
+}
+function ephemeralWhere(configDir, mounts = readMounts()) {
+  let real = configDir;
+  for (let p = configDir; ; p = path19.dirname(p)) {
+    try {
+      real = path19.join(fs17.realpathSync(p), path19.relative(p, configDir));
+      break;
+    } catch {
+      if (p === path19.dirname(p)) break;
+    }
+  }
+  const m = mountOf(real, mounts);
+  if (!m || !EPHEMERAL_FS.has(m.fstype)) return null;
+  const persistent = [...new Set(mounts.filter((x) => PERSISTENT_FS.test(x.fstype) && !x.point.startsWith("/proc") && !x.point.startsWith("/sys")).map((x) => x.point))].filter((pt) => {
+    try {
+      fs17.accessSync(pt, fs17.constants.W_OK);
+      return true;
+    } catch {
+      return false;
+    }
+  }).slice(0, 3);
+  return `agents.toml and the sign-in are in ${configDir}, on the container's own file system (${m.fstype}), which is lost when the container is recreated. Keep them on storage that outlives it: export CLAW_CONNECTOR_CONFIG_DIR=<a directory of yours on ${persistent.length ? persistent.join(" or ") : "a persistent volume"}>/claw-connector in your shell profile and the container's startup command, then run init and login again (the state directory, with its pid and lock files, stays where it is).`;
+}
+function saveServiceEnv(ctx, secrets) {
+  const file = serviceEnvFile(ctx.dirs);
+  const before = loadServiceEnv(file);
+  const merged = { ...before, ...Object.fromEntries(secrets) };
+  const names = Object.keys(merged).sort();
+  if (names.length === 0) return;
+  writeSecretFile(file, JSON.stringify(merged, null, 2) + "\n");
+  const fresh = secrets.map(([k]) => k);
+  const kept = names.filter((n) => !fresh.includes(n));
+  ctx.out(`the agents' sign-in for the service (in ${file}, mode 0600, never in a unit): ${[...fresh, ...kept.map((k) => `${k} (kept from before)`)].join(", ")}`);
+}
+function recordInstalled(ctx, sup, vars) {
+  const p = vars.find(([k]) => k === "PATH")?.[1];
+  writeFile600(serviceFile(ctx.dirs), JSON.stringify({ supervisor: sup, installed_at: (/* @__PURE__ */ new Date()).toISOString(), ...p !== void 0 ? { path: p } : {} }));
 }
 async function uninstall(ctx, d, sup) {
-  fs15.rmSync(serviceFile(ctx.dirs), { force: true });
+  fs17.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 = fs17.existsSync(unit);
+    fs17.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 = fs17.existsSync(plist);
+    fs17.rmSync(plist, { force: true });
     ctx.out(had ? `stopped and removed ${plist}` : `no LaunchAgent at ${plist}`);
   } else {
     const pid = supervisorPid(ctx);
@@ -4166,9 +6107,15 @@ 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 });
-    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.`);
+    const had = fs17.existsSync(script);
+    fs17.rmSync(script, { force: true });
+    const cron = withoutOurCron(d, script);
+    const cronGone = cron !== null && cron.removed > 0 && d.writeCrontab(cron.tab);
+    ctx.out(`${pid !== null ? `stopped the supervisor (pid ${pid}) and the connector; ` : ""}${had ? `removed ${script}` : "no keep-alive script"}${cronGone ? " and its crontab lines" : ". Remove any startup-hook or cron line that calls it."}`);
+  }
+  if (fs17.existsSync(serviceEnvFile(ctx.dirs))) {
+    fs17.rmSync(serviceEnvFile(ctx.dirs), { force: true });
+    ctx.out(`removed ${serviceEnvFile(ctx.dirs)} (the agents' sign-in variables kept for the service)`);
   }
   return 0;
 }
@@ -4184,6 +6131,8 @@ function status(ctx, d, h, json) {
   const st = {
     installed: sup,
     active,
+    /** The names (never the values) of the agents' sign-in variables the service keeps. */
+    agent_env: Object.keys(loadServiceEnv(serviceEnvFile(ctx.dirs))).sort(),
     running: h.runningPid(ctx),
     needs_login: needsLogin(ctx.dirs),
     recent_disconnects: recentDisconnects(ctx.dirs, 5)
@@ -4194,21 +6143,108 @@ function status(ctx, d, h, json) {
   }
   ctx.out(`service:    ${sup ? `${sup} (${active})` : "not installed; run: claw-connector service install"}`);
   ctx.out(`connector:  ${st.running !== null ? `running (pid ${st.running})` : "not running"}`);
+  if (st.agent_env.length) ctx.out(`agent env:  ${st.agent_env.join(", ")} (from ${serviceEnvFile(ctx.dirs)})`);
   if (st.needs_login) ctx.out(`problem:    needs a new sign-in: ${st.needs_login.reason}; run: claw-connector login`);
   for (const x of st.recent_disconnects) ctx.out(`down:       ${x.at} ${x.reason}${x.detail ? ` (${x.detail})` : ""}`);
   return 0;
 }
 
 // src/version.ts
-var VERSION = "0.1.4";
+var VERSION = "0.1.6";
+
+// src/probe.ts
+import fs18 from "node:fs";
+import os8 from "node:os";
+import path20 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 fs18.statSync(r).isDirectory();
+  } catch {
+    return false;
+  }
+}) ?? os8.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 = fs18.mkdtempSync(path20.join(os8.tmpdir(), "claw-probe-"));
+  const registry = new ChildRegistry(path20.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: path20.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: ${path20.join(o.logDir, `adapter-${a.id}.log`)})`);
+  } finally {
+    await adapter?.kill().catch(() => void 0);
+    fs18.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
@@ -4224,8 +6260,18 @@ Usage: claw-connector <command> [options]
   service install|uninstall|status [--supervisor systemd|launchd|script] [--env NAME ...]
                            keep "run" up: started at login/boot, restarted 5 s after it dies, never restarted
                            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
+                           systemd) writes a keep-alive script and adds it to crontab, or says what must call it.
+                           The agents' settings in this shell (PATH, proxies, ANTHROPIC_BASE_URL...) go into the
+                           service; their sign-in variables (ANTHROPIC_API_KEY, OPENAI_API_KEY...) and any --env
+                           named like a credential go into service-env.json (0600), never into the unit
   status [--json]          what is running, signed in, paused, the last disconnect and why
+  doctor [--agent ID] [--json]
+                           check this machine before a phone session fails on it, one fix per problem: Node, each
+                           agent's program on PATH (and on the installed service's PATH), Claude Code / Codex signed
+                           in, the roots writable, the proxy variables, Claw's certificate, the service and Claw
+                           itself; then start each agent's adapter, open a session (no prompt) and check that it
+                           offers the modes agents.toml needs. Exit 1 when something stops sessions. A running
+                           connector repeats the machine checks and shows them in the chat; init runs the adapter check
   pause                    stop every agent now and stay offline until "resume"
   resume                   undo "pause"
   stop                     stop the running connector and every agent it started
@@ -4233,18 +6279,23 @@ Usage: claw-connector <command> [options]
   --version, --help
 
 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.
+(audit.jsonl, logs, outbox); set CLAW_CONNECTOR_HOME to keep everything under one directory, and
+CLAW_CONNECTOR_CONFIG_DIR to keep only the configuration and sign-in elsewhere (storage that outlives a container).
 `;
-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 ?? os9.hostname() });
+  applyServiceEnv(cfg.agents, loadServiceEnv(serviceEnvFile(ctx.dirs)), ctx.env);
+  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 +6320,16 @@ 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 "health-check":
+        return await cmdHealthCheck(ctx, ctx.stdin ?? readStdin);
       case "pause":
         return await cmdPause(ctx);
       case "resume":
@@ -4313,16 +6369,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 });
+  fs19.mkdirSync(path21.dirname(file), { recursive: true, mode: 448 });
   try {
-    fs16.writeFileSync(file, sampleConfig(approval), { mode: 384, flag: "wx" });
+    fs19.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.`);
@@ -4331,13 +6387,37 @@ async function cmdInit(args, ctx) {
     if (e.code !== "EEXIST") throw e;
     ctx.out(`${file} already exists; left alone${values.approval?.length ? ` (to change an agent's approval, set approval = "ask" or "never" in its [[agents]] table)` : ""}`);
   }
+  const where = ephemeralWhere(ctx.dirs.config);
+  if (where) ctx.out(`note: ${where}`);
   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 (!fs19.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 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 +6425,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) => path21.resolve(ctx.env.CLAUDE_CONFIG_DIR?.trim() || path21.join(os9.homedir(), ".claude"));
 function claudeDirs(ctx, flag) {
-  if (flag !== void 0) return [path17.resolve(flag)];
+  if (flag !== void 0) return [path21.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) => path21.resolve(a.env.CLAUDE_CONFIG_DIR ?? ctx.env.CLAUDE_CONFIG_DIR?.trim() ?? path21.join(os9.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 (!fs19.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 +6457,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 && !fs19.existsSync(dir)) {
           ctx.err(`no Claude Code directory at ${dir}; pass --config-dir to name one`);
           code = EXIT.failure;
           continue;
@@ -4402,11 +6482,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(fs19.readFileSync(file, "utf8"));
     revoked = isObject(raw) && raw.revoked === true;
   } catch {
   }
-  if (revoked) fs16.rmSync(file, { force: true });
+  if (revoked) fs19.rmSync(file, { force: true });
 }
 async function cmdLogin(args, ctx) {
   const { values } = parseArgs2({
@@ -4441,7 +6521,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 ?? os9.hostname();
   const tok = await deviceLogin({ identityUrl, deviceName, fetch: ctx.fetch, print: ctx.out });
   saveCredentials(file, {
     v: 1,
@@ -4461,14 +6541,14 @@ async function cmdLogin(args, ctx) {
 }
 function runningPid(ctx) {
   try {
-    const raw = JSON.parse(fs16.readFileSync(pidFile(ctx.dirs), "utf8"));
+    const raw = JSON.parse(fs19.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 +6558,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) {
@@ -4506,10 +6587,16 @@ async function cmdRun(args, ctx) {
   const client2 = new ClawClient({ server, tokens, fetch: ctx.fetch });
   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 });
+  const connector2 = new Connector({ config: cfg, dirs: ctx.dirs, client: client2, server, audit, log, version: VERSION, timing: ctx.timing, health: runHealth(ctx, cfg) });
+  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}`);
+  for (const a of cfg.agents) if (a.readOnlyModes.includes(a.askMode)) ctx.out(`note: ${a.id}: its sessions start read-only (${a.askMode} mode changes no file); to let phone sessions write code, set approval = "never" on it in agents.toml`);
+  void rootProblems(cfg.agents).then((ps) => {
+    for (const p of ps) ctx.out(`warning: ${p}`);
+  }, () => void 0);
   try {
     const result = await connector2.run();
     if (result === "revoked") {
@@ -4522,6 +6609,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) {
@@ -4536,6 +6627,94 @@ async function cmdRun(args, ctx) {
     throw e;
   }
 }
+async function cmdDoctor(args, ctx) {
+  const { values } = parseArgs2({ args, strict: true, options: { agent: { type: "string" }, json: { type: "boolean" } } });
+  const before = [];
+  const notes = [];
+  let cfg = null;
+  let creds = null;
+  try {
+    cfg = loadCfg(ctx, notes);
+  } catch (e) {
+    const missing = !fs19.existsSync(configFile(ctx.dirs));
+    const roots = e instanceof ConfigError ? e.problems.map((p) => /^agent (\S+): root (.+) does not exist$/.exec(p)) : [];
+    if (roots.length && roots.every((m) => m !== null)) {
+      for (const m of roots) before.push({ code: "root_missing", severity: "fail", agent: m[1], detail: `${m[2]} (a root of agent ${m[1]}) does not exist`, fix: `mkdir -p ${shq(m[2])}  (or change roots in ${configFile(ctx.dirs)})` });
+    } else before.push({ code: "config_invalid", severity: "fail", detail: errMessage(e), fix: missing ? "claw-connector init" : `edit ${configFile(ctx.dirs)}` });
+  }
+  const agents = cfg ? values.agent ? cfg.agents.filter((a) => a.id === values.agent) : cfg.agents : [];
+  if (cfg && agents.length === 0) {
+    if (values.agent) {
+      ctx.err(`no agent ${JSON.stringify(values.agent)} in agents.toml`);
+      return EXIT.failure;
+    }
+    before.push({ code: "config_invalid", severity: "fail", detail: "agents.toml defines no agents", fix: `add an [[agents]] table to ${configFile(ctx.dirs)}  (claw-connector init writes a sample)` });
+  }
+  try {
+    creds = loadCredentials(credentialsFile(ctx.dirs));
+  } catch (e) {
+    before.push({ code: "not_signed_in", severity: "fail", detail: errMessage(e), fix: "claw-connector login" });
+  }
+  if (!creds && !before.some((p) => p.code === "not_signed_in")) before.push({ code: "not_signed_in", severity: "fail", detail: "this connector is not signed in to Claw", fix: "claw-connector login" });
+  const nl = needsLogin(ctx.dirs);
+  if (nl) before.push({ code: "needs_login", severity: "fail", detail: `needs a new sign-in: ${nl.reason}`, fix: "claw-connector login" });
+  let server = null;
+  try {
+    server = serverUrl(ctx, void 0, cfg, creds);
+  } catch {
+  }
+  const report = await checkAll({ dirs: ctx.dirs, agents, by: "doctor", server, before }, ctx.doctor ?? defaultDeps(ctx.env));
+  writeReport(ctx.dirs, report);
+  const warnings = cfg ? noAsk(ctx, { ...cfg, agents }) : [];
+  const results = agents.length ? redactDeep(await (ctx.probe ?? probeAgents)(agents, { logDir: logDir(ctx.dirs), version: VERSION })) : [];
+  const adaptersOk = results.every((r) => r.ok);
+  const machineOk = !report.problems.some((p) => p.severity === "fail");
+  if (values.json) {
+    ctx.out(JSON.stringify({ version: VERSION, ok: adaptersOk, machine_ok: machineOk, notes, warnings, agents: results, environment: report }, null, 2));
+  } else {
+    ctx.out(`claw-connector ${VERSION} doctor${cfg ? ` (${cfg.name})` : ""}`);
+    for (const l of formatReport(report)) ctx.out(l);
+    if (results.length) {
+      ctx.out("");
+      ctx.out("each agent's adapter (a session opened without a prompt):");
+      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);
+    }
+  }
+  const running = runningPid(ctx);
+  if (running !== null) {
+    try {
+      (ctx.askRecheck ?? ((pid) => process.kill(pid, "SIGWINCH")))(running);
+      if (!values.json) ctx.out("The running connector checks the machine again now and shows the result in the chat.");
+    } catch {
+    }
+  }
+  return adaptersOk && machineOk ? EXIT.ok : EXIT.failure;
+}
+var HEALTH_CHILD_MS = 6e4;
+function runHealth(ctx, cfg) {
+  if (ctx.doctor) return () => checkAll({ dirs: ctx.dirs, agents: cfg.agents, by: "run" }, ctx.doctor);
+  const cli = ctx.cli ?? ctx.service?.cli ?? fileURLToPath2(import.meta.url);
+  const node = ctx.node ?? process.execPath;
+  return async (signal) => {
+    const r = await runProbe(node, [cli, "health-check"], ctx.env, signal, HEALTH_CHILD_MS, JSON.stringify({ agents: cfg.agents }));
+    const v = JSON.parse(r.out.slice(r.out.indexOf("{")));
+    if (!isObject(v) || typeof v.checked_at !== "string" || !Array.isArray(v.problems)) throw new Error(`health-check answered ${r.code === null ? "nothing in time" : `exit ${r.code}`}`);
+    return v;
+  };
+}
+async function cmdHealthCheck(ctx, stdin) {
+  const v = JSON.parse(await stdin());
+  const agents = isObject(v) && Array.isArray(v.agents) ? v.agents : [];
+  ctx.out(JSON.stringify(await checkAll({ dirs: ctx.dirs, agents, by: "run" }, defaultDeps(ctx.env, { ownGroup: false }))));
+  return EXIT.ok;
+}
+async function readStdin() {
+  const chunks = [];
+  for await (const c of process.stdin) chunks.push(c);
+  return Buffer.concat(chunks).toString("utf8");
+}
 function cmdStatus(args, ctx) {
   const { values } = parseArgs2({ args, strict: true, options: { json: { type: "boolean" } } });
   let creds = null;
@@ -4559,7 +6738,7 @@ function cmdStatus(args, ctx) {
   }
   let connectorId = null;
   try {
-    const raw = JSON.parse(fs16.readFileSync(identityFile(ctx.dirs), "utf8"));
+    const raw = JSON.parse(fs19.readFileSync(identityFile(ctx.dirs), "utf8"));
     if (isObject(raw) && typeof raw.connector_id === "string") connectorId = raw.connector_id;
   } catch {
   }
@@ -4567,7 +6746,7 @@ function cmdStatus(args, ctx) {
   const status2 = {
     version: VERSION,
     running: runningPid(ctx),
-    paused: fs16.existsSync(pauseFile(ctx.dirs)),
+    paused: fs19.existsSync(pauseFile(ctx.dirs)),
     signed_in: creds ? { kind: creds.kind, server: creds.server, device_name: creds.device_name ?? null } : null,
     connector_id: connectorId,
     agents,
@@ -4579,7 +6758,9 @@ function cmdStatus(args, ctx) {
     warnings,
     /** Why the connection last went down, and whether only a new sign-in can bring it back. */
     last_disconnect: recentDisconnects(ctx.dirs, 1)[0] ?? null,
-    needs_login: needsLogin(ctx.dirs)
+    needs_login: needsLogin(ctx.dirs),
+    /** The last `doctor` report's problems (null: doctor never ran). */
+    doctor: lastDoctor(ctx)
   };
   if (values.json) {
     ctx.out(JSON.stringify(status2, null, 2));
@@ -4593,11 +6774,22 @@ function cmdStatus(args, ctx) {
   if (status2.needs_login) ctx.out(`problem:    needs a new sign-in: ${status2.needs_login.reason}; run: claw-connector login`);
   for (const p of status2.problems) ctx.out(`problem:    ${p}`);
   for (const w of status2.warnings) ctx.out(`warning:    ${w}`);
+  if (status2.doctor) ctx.out(`doctor:     ${status2.doctor.problems.length ? `${status2.doctor.problems.length} problem(s) at ${status2.doctor.checked_at}; run: claw-connector doctor` : `no problems at ${status2.doctor.checked_at}`}`);
+  else ctx.out("doctor:     never run; run: claw-connector doctor");
   return EXIT.ok;
 }
+function lastDoctor(ctx) {
+  try {
+    const raw = JSON.parse(fs19.readFileSync(doctorFile(ctx.dirs), "utf8"));
+    if (!isObject(raw) || typeof raw.checked_at !== "string" || !Array.isArray(raw.problems)) return null;
+    return { checked_at: raw.checked_at, problems: raw.problems.filter(isObject).map((p) => ({ code: String(p.code), ...typeof p.agent === "string" ? { agent: p.agent } : {}, fix: String(p.fix) })) };
+  } catch {
+    return null;
+  }
+}
 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 });
+  fs19.mkdirSync(ctx.dirs.state, { recursive: true, mode: 448 });
+  fs19.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 +6799,15 @@ async function cmdPause(ctx) {
   return EXIT.ok;
 }
 function cmdResume(ctx) {
-  fs16.rmSync(pauseFile(ctx.dirs), { force: true });
+  fs19.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) {
+    fs19.mkdirSync(ctx.dirs.state, { recursive: true, mode: 448 });
+    fs19.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 +6815,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`);
     }
+    fs19.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(fs19.readFileSync(file, "utf8"));
+    mine = isObject(raw) && raw.pid === process.pid && raw.start === (processStart(process.pid) ?? "");
+  } catch {
+    return false;
+  }
+  if (mine) fs19.rmSync(file, { force: true });
+  return mine;
+}
 function storedConnector(ctx) {
   try {
-    const raw = JSON.parse(fs16.readFileSync(identityFile(ctx.dirs), "utf8"));
+    const raw = JSON.parse(fs19.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 +6907,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 });
+  fs19.rmSync(file, { force: true });
+  if (rowGone) fs19.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}).`);
@@ -4739,12 +6946,16 @@ var onSignal = () => {
 };
 main(process.argv.slice(2), {
   dirs: resolveDirs(),
+  cli: fileURLToPath3(import.meta.url),
   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);
+    process.on("SIGWINCH", () => c.recheckHealth());
   }
 }).then((code) => process.exit(code), (e) => {
   process.stderr.write(`fatal: ${e instanceof Error ? e.stack : String(e)}