@gleapai/kai-bridge 0.9.0 → 0.10.0

package/src/ps.mjs

@@ -0,0 +1,152 @@
+// `kai-bridge ps` — what this machine is running right now, grouped by
+// Kai Code session. Read-only: it never talks to the daemon, it reads
+// the files the daemon keeps for crash recovery (daemon.mjs):
+//
+//   ~/.kai/daemon.lock               pid of the running daemon
+//   ~/.kai/state/inflight.json       turns in progress (+ runner pid, session meta)
+//   ~/.kai/state/preview-pids.json   dev-server processes (+ port, session meta)
+//
+// Liveness is `kill -0`. Dead pids are LABELLED, never cleaned up — the
+// daemon owns those files (reportInterruptedTurns / adoptPreviewPids).
+// `collectProcessList` is the one source of truth for the text view,
+// `--json`, and any host UI (a menu-bar widget) that wants the same list.
+
+import { readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+import { KAI_HOME } from "./config.mjs";
+import { installedVersionOrNull } from "./selfupdate.mjs";
+
+export function pidAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    // EPERM: the process exists but belongs to someone else — still alive.
+    return err?.code === "EPERM";
+  }
+}
+
+function readJson(path, fallback) {
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return fallback;
+  }
+}
+
+function readDaemon(kaiHome, isAlive, version) {
+  const lock = join(kaiHome, "daemon.lock");
+  let pid = null;
+  let startedAt = null;
+  try {
+    pid = Number(readFileSync(lock, "utf8").trim()) || null;
+    // The lock is written once, when the daemon starts (acquireLock).
+    startedAt = statSync(lock).mtime.toISOString();
+  } catch {
+    /* no lock — no daemon */
+  }
+  const running = pid != null && isAlive(pid);
+  return { running, pid, version, startedAt: running ? startedAt : null };
+}
+
+/** Pre-0.5.0 inflight files held bare turn ids. */
+function normaliseInflight(raw) {
+  return (Array.isArray(raw) ? raw : []).map((e) => (typeof e === "string" ? { turnId: e } : e)).filter((e) => e && typeof e.turnId === "string");
+}
+
+/**
+ * `{ daemon: { running, pid, version, startedAt }, sessions: [{ sessionId,
+ * title, sessionUrl, repos, turns: [...], services: [...] }] }`.
+ * Turn state: running | exited (runner pid gone, daemon still up) |
+ * interrupted (daemon down). Service state: running | dead.
+ */
+export function collectProcessList({ kaiHome = KAI_HOME, isAlive = pidAlive, version = installedVersionOrNull() } = {}) {
+  const daemon = readDaemon(kaiHome, isAlive, version);
+  const inflight = normaliseInflight(readJson(join(kaiHome, "state", "inflight.json"), []));
+  const previewPids = readJson(join(kaiHome, "state", "preview-pids.json"), []);
+  const services = (Array.isArray(previewPids) ? previewPids : []).filter((e) => e && Number.isInteger(e.pid));
+
+  const sessions = new Map(); // sessionId (or null) → session block, in first-seen order
+  const sessionFor = (entry) => {
+    const id = typeof entry.sessionId === "string" ? entry.sessionId : null;
+    let s = sessions.get(id);
+    if (!s) {
+      s = { sessionId: id, title: null, sessionUrl: null, repos: [], turns: [], services: [] };
+      sessions.set(id, s);
+    }
+    // Every entry denormalises the session meta; the first one that has it wins.
+    if (!s.title && typeof entry.title === "string") s.title = entry.title;
+    if (!s.sessionUrl && typeof entry.sessionUrl === "string") s.sessionUrl = entry.sessionUrl;
+    if (!s.repos.length && Array.isArray(entry.repos)) s.repos = entry.repos.filter((r) => typeof r === "string");
+    return s;
+  };
+
+  for (const e of inflight) {
+    const pid = Number.isInteger(e.pid) ? e.pid : null;
+    const state = !daemon.running ? "interrupted" : pid != null && !isAlive(pid) ? "exited" : "running";
+    sessionFor(e).turns.push({ turnId: e.turnId, agent: e.agent ?? null, harness: e.harness ?? null, profileId: e.profileId ?? null, pid, startedAt: e.startedAt ?? null, state });
+  }
+  for (const e of services) {
+    sessionFor(e).services.push({ name: e.name ?? null, pid: e.pid, port: Number.isInteger(e.port) ? e.port : null, startedAt: e.startedAt ?? null, state: isAlive(e.pid) ? "running" : "dead" });
+  }
+  return { daemon, sessions: [...sessions.values()] };
+}
+
+// ── text view ───────────────────────────────────────────────────────
+
+/** "2h 13m", "3m 12s", "45s" — how long since `iso`. */
+export function formatAge(iso, now = Date.now()) {
+  const ms = iso ? now - Date.parse(iso) : NaN;
+  if (!Number.isFinite(ms) || ms < 0) return "?";
+  const s = Math.floor(ms / 1000);
+  if (s < 60) return `${s}s`;
+  const m = Math.floor(s / 60);
+  if (m < 60) return `${m}m ${s % 60}s`;
+  const h = Math.floor(m / 60);
+  if (h < 24) return `${h}h ${m % 60}m`;
+  return `${Math.floor(h / 24)}d ${h % 24}h`;
+}
+
+/** Minutes-and-up version for long-lived dev servers ("14m", "2h 13m"). */
+function formatUptime(iso, now) {
+  const age = formatAge(iso, now);
+  return age.endsWith("s") && !age.includes("m") ? age : age.replace(/ \d+s$/, "");
+}
+
+function turnLine(t, now) {
+  const who = [t.agent ?? "turn", t.harness && t.profileId ? `${t.harness}/${t.profileId}` : t.harness ?? ""].filter(Boolean);
+  const state =
+    t.state === "running" ? `running ${formatAge(t.startedAt, now)}` : t.state === "exited" ? "exited — runner gone, daemon still winding it down" : "interrupted — daemon is down";
+  return `  turn   ${t.turnId.padEnd(26)} ${who[0].padEnd(16)} ${(who[1] ?? "").padEnd(16)} ${(t.pid != null ? `pid ${t.pid}` : "").padEnd(10)} ${state}`;
+}
+
+function serviceLine(s, now) {
+  const state = s.state === "running" ? `up ${formatUptime(s.startedAt, now)}` : "dead — stale entry";
+  return `  dev    ${(s.name ?? "?").padEnd(26)} ${"".padEnd(16)} ${"".padEnd(16)} ${`pid ${s.pid}`.padEnd(10)} ${(s.port != null ? `:${s.port}` : "").padEnd(7)} ${state}`;
+}
+
+export function formatProcessList(list, { now = Date.now() } = {}) {
+  const lines = [];
+  const d = list.daemon;
+  lines.push(
+    d.running
+      ? `daemon:   running · pid ${d.pid}${d.version ? ` · v${d.version}` : ""} · up ${formatUptime(d.startedAt, now)}`
+      : `daemon:   not running${d.pid ? ` (stale lock, pid ${d.pid})` : ""} — run \`kai-bridge start\` or \`kai-bridge install\``,
+  );
+  if (!list.sessions.length) {
+    lines.push("", "nothing running on this machine");
+    return lines.join("\n");
+  }
+  for (const s of list.sessions) {
+    lines.push("");
+    const head = [`session ${s.sessionId ?? "(unknown)"}`, s.title ? `"${s.title}"` : "(untitled)"];
+    if (s.repos.length) head.push(s.repos.join(", "));
+    lines.push(head.join("  "));
+    if (s.sessionUrl) lines.push(`  ${s.sessionUrl}`);
+    for (const t of s.turns) lines.push(turnLine(t, now));
+    for (const sv of s.services) lines.push(serviceLine(sv, now));
+  }
+  return lines.join("\n");
+}

package/src/repository-setup.mjs

@@ -27,7 +27,7 @@ export function locateRepository(rawPath, repoKey) {
   return target;
 }
 
-export function cloneRepository({ remote, name, root, repoKey, timeoutMs = 180_000 }, spawnGit = spawn) {
+export function cloneRepository({ remote, name, root, repoKey, timeoutMs = 180_000, gitEnv = null }, spawnGit = spawn) {
   if (typeof remote !== 'string' || !(/^(https?|ssh):\/\/\S+$/i.test(remote) || /^[\w.-]+@[\w.-]+:\S+$/.test(remote))) {
     return Promise.reject(new Error('This repository has an unsupported clone URL.'));
   }
@@ -53,7 +53,7 @@ export function cloneRepository({ remote, name, root, repoKey, timeoutMs = 180_0
           stdio: ['ignore', 'ignore', 'pipe'],
           detached: process.platform !== 'win32',
           env: { ...process.env, GIT_TERMINAL_PROMPT: '0', GIT_ASKPASS: 'echo', SSH_ASKPASS: 'echo',
-            GIT_SSH_COMMAND: process.env.GIT_SSH_COMMAND || 'ssh -o BatchMode=yes' },
+            GIT_SSH_COMMAND: process.env.GIT_SSH_COMMAND || 'ssh -o BatchMode=yes', ...(gitEnv || {}) },
         });
         let stderr = '';
         let timedOut = false;

package/src/service.mjs

@@ -60,13 +60,6 @@ ${envXml}
 `;
 }
 
-/** The desktop-session variables a headed browser needs (Linux only). */
-export function displayEnv(env = process.env) {
-  const out = {};
-  for (const k of ["DISPLAY", "WAYLAND_DISPLAY", "XAUTHORITY", "DBUS_SESSION_BUS_ADDRESS", "XDG_RUNTIME_DIR"]) if (env[k]) out[k] = env[k];
-  return out;
-}
-
 export function renderSystemdUnit({ program, args, env = {} }) {
   const q = (s) => `"${String(s).replace(/"/g, '\\"')}"`;
   return `[Unit]
@@ -102,10 +95,6 @@ export function install({ binPath, logDir, env = {} }) {
     PATH: process.env.PATH || "/usr/local/bin:/usr/bin:/bin",
     HOME: homedir(),
     ...(process.env.SSH_AUTH_SOCK ? { SSH_AUTH_SOCK: process.env.SSH_AUTH_SOCK } : {}),
-    // Linux: a systemd --user unit starts without the desktop session's
-    // display — the headed sign-in window (preview-login.mjs) needs it.
-    // Captured at install time, like PATH.
-    ...(os === "linux" ? displayEnv(process.env) : {}),
     ...env,
   };
   if (os === "darwin") {

package/src/setup.mjs

@@ -3,7 +3,7 @@
 //   1. pair this machine with the user's Gleap account
 //   2. offer the background service (start at login, restart on crash)
 //   3. offer harness sign-ins (Claude Code / Codex / Cursor), inline
-//   4. make sure a browser exists for previews / Verify (Chrome, else Chromium)
+//   4. make sure a browser exists for previews (Chrome, else Chromium)
 //   5. say it's done, nicely
 //
 // Runs from `kai-bridge setup`, from a bare `kai-bridge` on an unpaired
@@ -247,10 +247,10 @@ export async function runSetup({ binPath, prompter = makePrompter() } = {}) {
     out("");
 
     // 4 ── Browser for previews --------------------------------------
-    // Verify turns drive the preview in a real browser. System Chrome
-    // needs nothing; otherwise Playwright's Chromium is downloaded once
-    // here (the daemon would do it lazily before the first verify turn,
-    // which is a bad moment to wait for 150 MB).
+    // The preview warm-up and the agent's browser tools need a real
+    // browser. System Chrome needs nothing; otherwise Playwright's Chromium
+    // is downloaded once here (the daemon would do it lazily before the
+    // first preview, which is a bad moment to wait for 150 MB).
     out("Step 4 — browser for previews:");
     try {
       const { ensurePreviewBrowser } = await import("./preview.mjs");

package/src/tunnel-binary.mjs

@@ -0,0 +1,109 @@
+// Where `cloudflared` comes from, in order: the machine's own (PATH, so a
+// `brew install cloudflared` wins), the copy this bridge downloaded before
+// (`~/.kai/bin`), else a download of the pinned release from Cloudflare's
+// GitHub, checked against the SHA-256 published in that release's notes.
+// Anything else → `dependency_missing` with the install hint; the
+// dashboard renders it and "Make public" retries.
+import { spawn, execFile } from "node:child_process";
+import { createHash } from "node:crypto";
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { PreviewError } from "./preview-errors.mjs";
+
+const exec = promisify(execFile);
+
+export const CLOUDFLARED_VERSION = "2026.9.1";
+/**
+ * Release assets + their SHA-256 — the `assets[].digest` of
+ * https://api.github.com/repos/cloudflare/cloudflared/releases/tags/2026.9.1
+ * (the checksum block in the release NOTES hashes the unpacked macOS
+ * binaries, not the .tgz files that get downloaded).
+ */
+export const CLOUDFLARED_ASSETS = {
+  "darwin-x64": { asset: "cloudflared-darwin-amd64.tgz", sha256: "ff0d3b51d5ff70eceef89d6b32145fee985018a2174596a5dbe405e2766e2ac4" },
+  "darwin-arm64": { asset: "cloudflared-darwin-arm64.tgz", sha256: "c27ab8fd0aa489449e3d201eb02f957ef460a13b613662928b1b23394bf1bcfe" },
+  "linux-x64": { asset: "cloudflared-linux-amd64", sha256: "03f1f25d1cc93b9ad6c60569d44060bc4f17ed97075760ed8cfca4b12dcd68cc" },
+  "linux-arm64": { asset: "cloudflared-linux-arm64", sha256: "3d97437c71848bd8df68041e12436b484a661d95073ea1937f01a845ce88faa3" },
+  "win32-x64": { asset: "cloudflared-windows-amd64.exe", sha256: "2837888cc0f5d58f15b6dc478376de90b4d3ba5241c7947455d1e0a0df429712" },
+};
+
+export const INSTALL_HINT = "Install it (macOS: brew install cloudflared · Debian/Ubuntu: apt install cloudflared · Windows: winget install Cloudflare.cloudflared) and make the preview public again.";
+
+const missing = (device, why) =>
+  new PreviewError(`cloudflared is not installed on ${device}${why ? ` (${why})` : ""}. ${INSTALL_HINT}`, { code: "dependency_missing", kind: "machine", detail: { dependency: "cloudflared" } });
+
+/** `command -v cloudflared` through a login shell on macOS (launchd PATH is frozen at install time). */
+export function commandOnPath(cmd, spawnImpl = spawn) {
+  return new Promise((resolveP) => {
+    const probe =
+      process.platform === "win32"
+        ? spawnImpl("where", [cmd], { stdio: "ignore", windowsHide: true })
+        : process.platform === "darwin"
+          ? spawnImpl("/bin/zsh", ["-lc", `command -v ${cmd}`], { stdio: "ignore" })
+          : spawnImpl("sh", ["-c", `command -v ${cmd}`], { stdio: "ignore" });
+    probe.on("exit", (c) => resolveP(c === 0));
+    probe.on("error", () => resolveP(false));
+  });
+}
+
+export const managedBinaryPath = (kaiHome) => join(kaiHome, "bin", process.platform === "win32" ? "cloudflared.exe" : "cloudflared");
+
+/**
+ * Resolve the binary to run. `download` / `onPath` are injectable for tests.
+ * Returns the command (bare `cloudflared` when it is on PATH, else a full path).
+ */
+export async function resolveCloudflared({ kaiHome, device = "this device", log = () => {}, onPath = commandOnPath, download = downloadCloudflared } = {}) {
+  if (await onPath("cloudflared")) return "cloudflared";
+  const managed = managedBinaryPath(kaiHome);
+  if (existsSync(managed)) return managed;
+  const target = CLOUDFLARED_ASSETS[`${process.platform}-${process.arch}`];
+  if (!target) throw missing(device, `no download for ${process.platform}-${process.arch}`);
+  try {
+    log("info", "tunnel.binary.download", { version: CLOUDFLARED_VERSION, asset: target.asset });
+    await download({ target, managed, kaiHome });
+    return managed;
+  } catch (err) {
+    log("warn", "tunnel.binary.download_failed", { error: err?.message });
+    throw missing(device, `download failed: ${err?.message || err}`);
+  }
+}
+
+/** Fetch the pinned asset, verify its SHA-256, unpack (macOS ships a .tgz), install atomically. */
+export async function downloadCloudflared({ target, managed, kaiHome }) {
+  const url = `https://github.com/cloudflare/cloudflared/releases/download/${CLOUDFLARED_VERSION}/${target.asset}`;
+  const res = await fetch(url, { redirect: "follow", signal: AbortSignal.timeout(120_000) });
+  if (!res.ok) throw new Error(`HTTP ${res.status} for ${url}`);
+  const bytes = Buffer.from(await res.arrayBuffer());
+  const sum = createHash("sha256").update(bytes).digest("hex");
+  if (sum !== target.sha256) throw new Error(`checksum mismatch for ${target.asset}`);
+  const dir = join(kaiHome, "bin");
+  mkdirSync(dir, { recursive: true });
+  const tmp = join(dir, `.${target.asset}.${process.pid}`);
+  writeFileSync(tmp, bytes);
+  try {
+    if (target.asset.endsWith(".tgz")) {
+      const unpack = join(dir, `.unpack-${process.pid}`);
+      mkdirSync(unpack, { recursive: true });
+      await exec("tar", ["-xzf", tmp, "-C", unpack]);
+      renameSync(join(unpack, "cloudflared"), managed);
+      rmSync(unpack, { recursive: true, force: true });
+    } else {
+      renameSync(tmp, managed);
+    }
+  } finally {
+    rmSync(tmp, { force: true });
+  }
+  if (process.platform !== "win32") chmodSync(managed, 0o755);
+  writeFileSync(join(dir, "cloudflared.version"), CLOUDFLARED_VERSION);
+  return managed;
+}
+
+/** The version a managed copy was downloaded as (null for a PATH install). */
+export const managedVersion = (kaiHome) => {
+  try {
+    return readFileSync(join(kaiHome, "bin", "cloudflared.version"), "utf8").trim() || null;
+  } catch {
+    return null;
+  }
+};

package/src/tunnel.mjs

@@ -0,0 +1,227 @@
+// Public preview links — the device side. Runs ONE `cloudflared` for this
+// device (the Server owns the tunnel and its hostnames, see
+// `POST /devices/me/public-hosts`) and owns the hostname → local port
+// route table. Routes are ref-counted by session so two sessions sharing
+// an adopted companion (two web repos, one API) keep one route alive
+// until the last of them stops.
+//
+// A locally-managed cloudflared does NOT reload its config file, so every
+// route change writes `~/.kai/tunnel/config.yml` and swaps the process:
+// the new one starts first, the old one is stopped once the new one has
+// registered (the documented zero-downtime way, a "replica" for a second).
+//
+// State under KAI_HOME: tunnel/credentials.json (0600), tunnel/config.yml,
+// logs/tunnel.log, state/tunnel.json (pid + routes, so a restarted daemon
+// can kill a survivor and re-route the previews it resumed).
+import { spawn } from "node:child_process";
+import { chmodSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+export const RESTART_BACKOFF_MS = [1_000, 2_000, 5_000, 10_000];
+/** How long a fresh cloudflared gets to register before the old one is stopped anyway. */
+export const SWAP_READY_TIMEOUT_MS = 10_000;
+
+/** `config.yml` — one ingress rule per hostname, catch-all last (cloudflared refuses a file without it). */
+export function renderTunnelConfig({ tunnelId, credentialsPath, routes }) {
+  const lines = [`tunnel: ${tunnelId}`, `credentials-file: ${credentialsPath}`, "no-autoupdate: true", "ingress:"];
+  for (const [hostname, r] of [...routes].sort(([a], [b]) => a.localeCompare(b))) {
+    lines.push(`  - hostname: ${hostname}`, `    service: ${r.protocol}://localhost:${r.port}`, "    originRequest:");
+    // Vite 7 / Next compare Host with their allowed hosts — hand the app the Host it expects.
+    lines.push(`      httpHostHeader: localhost:${r.port}`);
+    if (r.protocol === "https") lines.push("      noTLSVerify: true");
+  }
+  lines.push("  - service: http_status:404");
+  return lines.join("\n") + "\n";
+}
+
+export class TunnelManager {
+  /** `spawnImpl` / `now` / `sleep` are injectable for tests. */
+  constructor({ kaiHome, log = () => {}, spawnImpl = spawn, sleep = (ms) => new Promise((r) => setTimeout(r, ms)) } = {}) {
+    this.kaiHome = kaiHome;
+    this.log = log;
+    this.spawnImpl = spawnImpl;
+    this.sleep = sleep;
+    this.dir = join(kaiHome, "tunnel");
+    this.credentialsPath = join(this.dir, "credentials.json");
+    this.configPath = join(this.dir, "config.yml");
+    this.logPath = join(kaiHome, "logs", "tunnel.log");
+    this.statePath = join(kaiHome, "state", "tunnel.json");
+    this.binary = "cloudflared";
+    this.tunnelId = null;
+    this.routes = new Map(); // hostname → { port, protocol, owners: Set<sessionId> }
+    this.child = null;
+    this.restarts = 0;
+    this.applying = Promise.resolve();
+  }
+
+  /** Credentials from the Server (`{ AccountTag, TunnelID, TunnelSecret }`), written only when they changed. */
+  ensureRunning({ tunnelId, credentials }) {
+    mkdirSync(this.dir, { recursive: true });
+    const json = JSON.stringify(credentials);
+    let current = null;
+    try {
+      current = readFileSync(this.credentialsPath, "utf8");
+    } catch {
+      /* first time */
+    }
+    if (current !== json) {
+      writeFileSync(this.credentialsPath, json, { mode: 0o600 });
+      chmodSync(this.credentialsPath, 0o600);
+    }
+    this.tunnelId = tunnelId;
+  }
+
+  /** Replace this session's routes; a hostname another session still uses just gains an owner (or moves port). */
+  setRoutes(sessionId, routes) {
+    for (const r of this.routes.values()) r.owners.delete(sessionId);
+    for (const { hostname, port, protocol = "http" } of routes) {
+      const existing = this.routes.get(hostname);
+      if (existing) {
+        existing.port = port;
+        existing.protocol = protocol;
+        existing.owners.add(sessionId);
+      } else {
+        this.routes.set(hostname, { port, protocol, owners: new Set([sessionId]) });
+      }
+    }
+    this.prune();
+    return this.apply();
+  }
+
+  removeSession(sessionId) {
+    for (const r of this.routes.values()) r.owners.delete(sessionId);
+    this.prune();
+    return this.apply();
+  }
+
+  routesFor(sessionId) {
+    return [...this.routes].filter(([, r]) => r.owners.has(sessionId)).map(([hostname, r]) => ({ hostname, port: r.port, protocol: r.protocol }));
+  }
+
+  prune() {
+    for (const [hostname, r] of this.routes) if (r.owners.size === 0) this.routes.delete(hostname);
+  }
+
+  /** Serialised: the config is rewritten and the process swapped (or stopped when nothing is routed). */
+  apply() {
+    this.applying = this.applying.then(() => this.applyNow()).catch((err) => this.log("warn", "tunnel.apply.failed", { error: err?.message }));
+    return this.applying;
+  }
+
+  async applyNow() {
+    this.saveState();
+    if (this.routes.size === 0) {
+      await this.stop();
+      return;
+    }
+    if (!this.tunnelId) throw new Error("tunnel credentials missing");
+    mkdirSync(this.dir, { recursive: true });
+    writeFileSync(this.configPath, renderTunnelConfig({ tunnelId: this.tunnelId, credentialsPath: this.credentialsPath, routes: this.routes }));
+    const old = this.child;
+    this.child = null;
+    const next = await this.spawnCloudflared();
+    if (old) await this.kill(old);
+    this.child = next;
+    this.saveState();
+  }
+
+  /** Start a cloudflared on the current config; resolves once it registered with the edge (or after the cap). */
+  async spawnCloudflared() {
+    mkdirSync(join(this.kaiHome, "logs"), { recursive: true });
+    const fd = openSync(this.logPath, "a");
+    const child = this.spawnImpl(this.binary, ["tunnel", "--config", this.configPath, "--no-autoupdate", "run", this.tunnelId], { stdio: ["ignore", "pipe", "pipe"], windowsHide: true });
+    let ready;
+    const registered = new Promise((r) => (ready = r));
+    const tee = (chunk) => {
+      const text = String(chunk);
+      try {
+        writeFileSync(fd, text);
+      } catch {
+        /* log rotated away */
+      }
+      if (/Registered tunnel connection/i.test(text)) ready();
+    };
+    child.stdout?.on("data", tee);
+    child.stderr?.on("data", tee);
+    child.on("exit", (code, signal) => {
+      closeSync(fd);
+      ready();
+      if (this.child !== child) return; // replaced or stopped on purpose
+      this.child = null;
+      this.log("warn", "tunnel.exited", { code, signal });
+      if (this.routes.size === 0) return;
+      // Crashed while previews are public: back off and come back.
+      const delay = RESTART_BACKOFF_MS[Math.min(this.restarts, RESTART_BACKOFF_MS.length - 1)];
+      this.restarts += 1;
+      this.sleep(delay).then(() => {
+        if (!this.child && this.routes.size > 0) this.apply();
+      });
+    });
+    child.on("error", (err) => this.log("error", "tunnel.spawn.failed", { error: err?.message }));
+    await Promise.race([registered, this.sleep(SWAP_READY_TIMEOUT_MS)]);
+    this.restarts = child.exitCode === null ? 0 : this.restarts;
+    return child;
+  }
+
+  async kill(child) {
+    if (!child || child.exitCode !== null || child.signalCode !== null) return;
+    const gone = new Promise((r) => child.once("exit", r));
+    try {
+      child.kill("SIGTERM");
+    } catch {
+      return;
+    }
+    await Promise.race([gone, this.sleep(5_000).then(() => child.kill("SIGKILL"))]);
+  }
+
+  async stop() {
+    const child = this.child;
+    this.child = null;
+    await this.kill(child);
+    this.saveState();
+  }
+
+  /**
+   * Daemon start: end a cloudflared the previous daemon life left behind,
+   * keep the routes of sessions whose previews were resumed, drop the rest.
+   */
+  async resume({ liveSessionIds = [], resolveBinary = null } = {}) {
+    let state = null;
+    try {
+      state = JSON.parse(readFileSync(this.statePath, "utf8"));
+    } catch {
+      /* nothing to resume */
+    }
+    if (Number.isInteger(state?.pid)) {
+      try {
+        process.kill(state.pid, "SIGTERM");
+      } catch {
+        /* already gone */
+      }
+    }
+    const live = new Set(liveSessionIds);
+    for (const [hostname, r] of Object.entries(state?.routes || {})) {
+      const owners = new Set((r.owners || []).filter((s) => live.has(s)));
+      if (owners.size) this.routes.set(hostname, { port: r.port, protocol: r.protocol || "http", owners });
+    }
+    if (this.routes.size && state?.tunnelId && existsSync(this.credentialsPath)) {
+      this.tunnelId = state.tunnelId;
+      // The binary lives wherever "Make public" found it (PATH or ~/.kai/bin) — ask again.
+      if (resolveBinary) this.binary = await resolveBinary();
+      await this.apply();
+    } else {
+      this.routes.clear();
+      this.saveState();
+    }
+  }
+
+  saveState() {
+    try {
+      mkdirSync(join(this.kaiHome, "state"), { recursive: true });
+      const routes = Object.fromEntries([...this.routes].map(([h, r]) => [h, { port: r.port, protocol: r.protocol, owners: [...r.owners] }]));
+      writeFileSync(this.statePath, JSON.stringify({ pid: this.child?.pid ?? null, tunnelId: this.tunnelId, routes }), { mode: 0o600 });
+    } catch (err) {
+      this.log("warn", "tunnel.state.failed", { error: err?.message });
+    }
+  }
+}