@gleapai/kai-bridge 0.2.0

package/src/daemon.mjs

@@ -0,0 +1,904 @@
+// The always-on part: one outbound realtime subscription for commands,
+// REST for everything the device reports. Idles at ~0 CPU; reconnects
+// with backoff; keeps the machine awake only while a turn runs.
+//
+// Commands arrive on `private-bridge-<deviceId>` (Sockudo / Pusher
+// protocol, the same channel family the dashboard uses):
+//   bridge.turn.start   { commandId, turnId, sessionId, profileId, repos:[{key, mode, base, carryUncommitted}], ...AgentRunOpts }
+//   bridge.turn.cancel  { turnId }
+//   bridge.repo.clone   { commandId, remote, name }
+//   bridge.profile.login{ commandId, profileId }
+//   bridge.rescan       {}
+
+import { spawn } from "node:child_process";
+import { appendFileSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join, resolve as resolvePath } from "node:path";
+import { homedir, platform } from "node:os";
+
+import { BridgeApi, createEventBatcher } from "./api.mjs";
+import { KAI_HOME, defaultConfig, loadConfig, saveConfig } from "./config.mjs";
+import { runTurn } from "./executor.mjs";
+import { createManagedProfile, describeProfiles, managedConfigDir, ambientConfigDir, openLoginTerminal, probeUsageLimits } from "./profiles.mjs";
+import { defaultRoots, groupByRepo, preferredCloneRoot, scanRoots, toDeviceRepoReport } from "./repos.mjs";
+import { collectChanges, commitAndPush, copyPrimaryEnvFiles, materializeBinding, sessionSlug, worktreePath } from "./workspace.mjs";
+import { ServiceRunner, detectDevConfig, previewMcpServer, readDevConfig } from "./preview.mjs";
+import { describeHarnesses, installHarness } from "./harnesses.mjs";
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const RUNNER_DIR = join(dirname(fileURLToPath(import.meta.url)), "..", "runner");
+
+/** Lock paths held by daemons in THIS process (cross-process uses the file). */
+const HELD_LOCKS = new Set();
+const REALTIME_RETRY_MS = 15_000;
+const HEARTBEAT_MS = 30_000;
+const USAGE_REFRESH_MS = 10 * 60_000;
+const VERSION = "0.1.0";
+
+export function createLogger(kaiHome = KAI_HOME) {
+  mkdirSync(join(kaiHome, "logs"), { recursive: true });
+  const file = join(kaiHome, "logs", "bridge.log");
+  return (level, msg, data) => {
+    const line = `${new Date().toISOString()} ${level} ${msg}${data ? " " + JSON.stringify(data) : ""}`;
+    try {
+      appendFileSync(file, line + "\n");
+    } catch {
+      /* best-effort */
+    }
+    if (process.env.KAI_BRIDGE_FOREGROUND === "1" || level === "error") process.stderr.write(line + "\n");
+  };
+}
+
+/**
+ * Resolve profiles from config; ambient/managed dirs derived here.
+ *
+ * The three ambient profiles (one per harness) are always present, even
+ * if the stored config predates a harness or lost entries: a missing
+ * ambient entry would silently remove that harness from the dashboard
+ * picker with nothing to click to get it back.
+ */
+export function resolveProfiles(config, kaiHome = KAI_HOME) {
+  const stored = config.profiles || [];
+  const missing = defaultConfig().profiles.filter(
+    (d) => !stored.some((p) => p.id === d.id || (p.kind !== "managed" && p.harness === d.harness)),
+  );
+  return [...stored, ...missing].map((p) => ({
+    ...p,
+    configDir: p.kind === "managed" ? managedConfigDir(p.harness, p.id, kaiHome) : ambientConfigDir(p.harness),
+  }));
+}
+
+/** Keep the machine awake for the duration of a turn (macOS caffeinate). */
+function keepAwake() {
+  if (platform() !== "darwin") return () => {};
+  try {
+    // `-w <pid>`: caffeinate exits when THIS process does, however it
+    // dies. Without it a crash or `kill -9` orphans an assertion that
+    // keeps the machine awake — and draining — all night.
+    const p = spawn("caffeinate", ["-dimsu", "-w", String(process.pid)], { stdio: "ignore" });
+    // spawn reports ENOENT asynchronously; unhandled, it would take the
+    // daemon down in the middle of a turn.
+    p.on("error", () => {});
+    return () => {
+      try {
+        p.kill();
+      } catch {
+        /* gone */
+      }
+    };
+  } catch {
+    return () => {};
+  }
+}
+
+export class BridgeDaemon {
+  constructor({ config = loadConfig(), kaiHome = KAI_HOME, log = createLogger(kaiHome), realtimeFactory } = {}) {
+    this.config = config;
+    this.kaiHome = kaiHome;
+    this.log = log;
+    this.api = new BridgeApi({ apiBase: config.apiBase, token: config.device?.token });
+    this.realtimeFactory = realtimeFactory;
+    this.running = new Map(); // turnId → AbortController
+    this.services = new Map(); // sessionId → ServiceRunner (lives across turns)
+    this.repoGroups = [];
+    this.usageByProfile = new Map(); // profileId → plan-usage snapshot (claude only)
+    this.stopped = false;
+  }
+
+  async scanRepos() {
+    const roots = [...defaultRoots(), ...(this.config.roots || [])];
+    const checkouts = scanRoots(roots);
+    this.repoGroups = groupByRepo(checkouts, this.config.primaryOverrides || {});
+    this.log("info", "repos.scanned", { roots: roots.length, repos: this.repoGroups.length });
+    return this.repoGroups;
+  }
+
+  async hello() {
+    const profiles = await describeProfiles(resolveProfiles(this.config, this.kaiHome), this.usageByProfile);
+    const repos = toDeviceRepoReport(this.repoGroups);
+    return this.api.hello({
+      name: this.config.device?.name,
+      platform: platform(),
+      version: VERSION,
+      harnesses: describeHarnesses(this.kaiHome).map(({ binary, ...h }) => h),
+      profiles,
+      repos,
+      roots: [...defaultRoots(), ...(this.config.roots || [])],
+      repoModes: this.config.repoModes || {},
+    });
+  }
+
+  async start() {
+    if (!this.config.device?.token) throw new Error("Not paired — run `kai-bridge login` first.");
+    // Exactly one daemon per machine. Two would both receive every
+    // command on the shared channel and run two agents in the SAME
+    // worktree — interleaved events, racing pushes, mangled diffs. Very
+    // easy to hit: `kai-bridge install` and then `kai-bridge start`.
+    this.acquireLock();
+    // A previous run that was killed (reboot, crash, `kill -9`) never got
+    // to report its turns. Tell the server before doing anything else,
+    // so those sessions settle instead of spinning.
+    await this.reportInterruptedTurns();
+    await this.scanRepos();
+    // The first hello must not kill the daemon: the server may be
+    // restarting (deploys, local nodemon) — retry with backoff instead
+    // of exiting, exactly like every later heartbeat survives a gap.
+    for (let delay = 5_000; ; delay = Math.min(delay * 2, 60_000)) {
+      try {
+        await this.hello();
+        break;
+      } catch (err) {
+        if (err?.status === 401 || err?.status === 403) {
+          // Permanent: retrying a revoked token forever, silently, is
+          // how a device ends up "connected" and dead for days.
+          this.onApiError("hello", err);
+          this.releaseLock();
+          const revoked = new Error("This machine is no longer connected to Gleap — run `kai-bridge login`.");
+          // Lets the CLI exit 0 under the service: launchd must treat a
+          // revoked pairing as a deliberate stop, not a crash to retry.
+          revoked.code = "REVOKED";
+          throw revoked;
+        }
+        this.log("warn", "hello.retry", { error: err?.message, nextInMs: delay });
+        await new Promise((r) => setTimeout(r, delay));
+      }
+    }
+    this.connectRealtime();
+    // REF'd on purpose: this timer is what keeps the process alive. With
+    // it unref'd, a realtime socket that gave up for good left no handle
+    // behind, node exited 0, and launchd's SuccessfulExit:false meant the
+    // machine stayed offline until the next login — silently.
+    this.heartbeat = setInterval(() => {
+      this.api
+        .heartbeat({ running: [...this.running.keys()] })
+        .catch((err) => this.onApiError("heartbeat", err));
+    }, HEARTBEAT_MS);
+    // Plan-usage windows for the composer popover. Fire-and-forget on a
+    // slow cadence, unref'd (the heartbeat keeps the process alive), and
+    // NEVER in hello's path — the probe spawns the CLI (~2s per profile).
+    void this.refreshUsageLimits();
+    this.usageTimer = setInterval(() => void this.refreshUsageLimits(), USAGE_REFRESH_MS);
+    this.usageTimer.unref?.();
+    this.log("info", "started", { device: this.config.device.id });
+  }
+
+  /**
+   * Probe each claude profile's plan-usage windows and, when anything
+   * changed, push the fresh profile list via hello (idempotent $set on
+   * the server). Skipped entirely while a turn is running — the probe
+   * competes for the same login.
+   */
+  async refreshUsageLimits() {
+    if (this.stopped || this.running.size > 0) return;
+    let changed = false;
+    for (const p of resolveProfiles(this.config, this.kaiHome)) {
+      if (p.harness !== "claude") continue;
+      try {
+        const prev = this.usageByProfile.get(p.id) ?? null;
+        const usage = (await probeUsageLimits(p.harness, p.configDir, this.kaiHome)) ?? null;
+        // `fetchedAt` alone must not count as a change or every probe
+        // would trigger a hello.
+        const comparable = (v) => (v ? JSON.stringify({ ...v, fetchedAt: null }) : "null");
+        if (comparable(usage) !== comparable(prev)) changed = true;
+        if (usage) this.usageByProfile.set(p.id, usage);
+        else this.usageByProfile.delete(p.id);
+      } catch (err) {
+        this.log("warn", "usage.probe.failed", { profile: p.id, error: err?.message });
+      }
+    }
+    if (changed && !this.stopped) {
+      await this.hello().catch((err) => this.log("warn", "usage.hello.failed", { error: err?.message }));
+      this.log("info", "usage.refreshed", { profiles: this.usageByProfile.size });
+    }
+  }
+
+  stop() {
+    this.stopped = true;
+    clearInterval(this.heartbeat);
+    clearInterval(this.usageTimer);
+    if (this.realtimeRetry) clearTimeout(this.realtimeRetry);
+    for (const ctrl of this.running.values()) ctrl.abort();
+    for (const runner of this.services.values()) runner.stopAll();
+    this.realtime?.disconnect?.();
+    this.releaseLock();
+  }
+
+  // ── single instance ────────────────────────────────────────────────
+  get lockPath() {
+    return join(this.kaiHome, "daemon.lock");
+  }
+
+  acquireLock() {
+    mkdirSync(this.kaiHome, { recursive: true });
+    // Same-process guard: the pid check below can't see a second daemon
+    // living inside this very process (the Desktop host embeds one).
+    if (HELD_LOCKS.has(this.lockPath)) {
+      throw new Error("kai-bridge is already running on this machine (in this process).");
+    }
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+      try {
+        writeFileSync(this.lockPath, String(process.pid), { flag: "wx" });
+        this.holdsLock = true;
+        HELD_LOCKS.add(this.lockPath);
+        process.on("exit", () => this.releaseLock());
+        return;
+      } catch (err) {
+        if (err.code !== "EEXIST") throw err;
+        const pid = Number(readFileSync(this.lockPath, "utf8").trim());
+        if (pid && pid !== process.pid) {
+          try {
+            process.kill(pid, 0);
+            throw new Error(`kai-bridge is already running on this machine (pid ${pid}).`);
+          } catch (e) {
+            if (e.code !== "ESRCH") throw e;
+          }
+        }
+        // Stale lock from a killed process — take it.
+        rmSync(this.lockPath, { force: true });
+      }
+    }
+  }
+
+  releaseLock() {
+    if (!this.holdsLock) return;
+    this.holdsLock = false;
+    HELD_LOCKS.delete(this.lockPath);
+    try {
+      rmSync(this.lockPath, { force: true });
+    } catch {
+      /* best effort */
+    }
+  }
+
+  // ── crash recovery ─────────────────────────────────────────────────
+  get inflightPath() {
+    return join(this.kaiHome, "state", "inflight.json");
+  }
+
+  readInflight() {
+    try {
+      return JSON.parse(readFileSync(this.inflightPath, "utf8"));
+    } catch {
+      return [];
+    }
+  }
+
+  writeInflight(ids) {
+    try {
+      mkdirSync(join(this.kaiHome, "state"), { recursive: true });
+      writeFileSync(this.inflightPath, JSON.stringify(ids));
+    } catch {
+      /* best effort */
+    }
+  }
+
+  rememberInflight(turnId) {
+    this.writeInflight([...new Set([...this.readInflight(), turnId])]);
+  }
+
+  forgetInflight(turnId) {
+    this.writeInflight(this.readInflight().filter((id) => id !== turnId));
+  }
+
+  /** Turns this machine was running when it was killed — report them dead. */
+  async reportInterruptedTurns() {
+    const ids = this.readInflight();
+    if (!ids.length) return;
+    this.writeInflight([]);
+    for (const turnId of ids) {
+      this.log("warn", "turn.interrupted", { turnId });
+      await this.api
+        .turnResult(turnId, {
+          status: "failed",
+          error: `${this.config.device?.name || "This machine"} restarted while the turn was running — send the message again to retry.`,
+        })
+        .catch(() => {});
+    }
+  }
+
+  /**
+   * The realtime client retries a refused connection forever, but two
+   * states are terminal: six failed reconnects of an ESTABLISHED socket
+   * (a rolling deploy behind a load balancer looks exactly like that),
+   * and a `refused` close code. Both used to log one line and leave the
+   * device subscribed to nothing while still heartbeating — online in
+   * the dashboard, deaf in practice. Reconnect from scratch instead.
+   */
+  handleRealtimeState(state) {
+    this.log("info", "realtime", { state });
+    const text = String(state || "");
+    if (text === "connected") {
+      this.realtimeDown = false;
+      // Anything published while we were away is gone — Pusher-style
+      // events aren't replayed. Re-announce and pull whatever the server
+      // still thinks we should be running.
+      void this.reconcileAfterReconnect();
+      return;
+    }
+    if (text === "disconnected" || text.startsWith("error") || text.startsWith("subscription_error")) {
+      this.realtimeDown = true;
+      if (this.stopped || this.realtimeRetry) return;
+      this.realtimeRetry = setTimeout(() => {
+        this.realtimeRetry = null;
+        if (this.stopped) return;
+        this.log("info", "realtime.reconnect");
+        try {
+          this.realtime?.disconnect?.();
+        } catch {
+          /* already gone */
+        }
+        this.connectRealtime();
+      }, REALTIME_RETRY_MS);
+    }
+  }
+
+  /**
+   * After a gap (sleep, wifi, deploy) ask the server what it still
+   * believes we're running and pick those turns up. Without this, a
+   * session started while the lid was closed simply never ran.
+   */
+  async reconcileAfterReconnect() {
+    try {
+      await this.hello();
+    } catch (err) {
+      this.log("warn", "reconnect.hello.failed", { error: err.message });
+      return;
+    }
+    try {
+      const pending = await this.api.pendingTurns();
+      for (const turn of pending?.turns || []) {
+        if (this.running.has(turn.turnId)) continue;
+        this.log("info", "turn.recovered", { turnId: turn.turnId });
+        void this.startTurn(turn).catch((err) => this.log("error", "turn.recover.failed", { error: err.message }));
+      }
+    } catch (err) {
+      // Older server without the endpoint: the server-side sweep still
+      // fails orphaned turns, so this is a nice-to-have, not a must.
+      this.log("debug", "pending.unavailable", { error: err.message });
+    }
+  }
+
+  /** A 401/403 means this device was unpaired — retrying forever is noise. */
+  onApiError(where, err) {
+    if (err?.status === 401 || err?.status === 403) {
+      if (!this.authLost) {
+        this.authLost = true;
+        this.log("error", "auth.invalid", { where, status: err.status });
+        process.stderr.write(
+          "\nThis machine is no longer connected to Gleap (it may have been disconnected in Settings → Devices).\n" +
+            "Reconnect it with:  kai-bridge login\n\n",
+        );
+        // Post-start (heartbeat exists): a revoked device can never
+        // recover on its own — every later call would 403 too, so the
+        // daemon would sit "running" and warn forever while the machine
+        // is dead in the picker. Shut down deliberately with exit 0:
+        // launchd's SuccessfulExit:false leaves an intentional stop
+        // alone (a crash-restart loop would just hammer the API with
+        // more 403s). `kai-bridge login` starting again brings it back.
+        if (this.heartbeat) {
+          this.stop();
+          setTimeout(() => process.exit(0), 500).unref?.();
+          process.exitCode = 0;
+        }
+      }
+      return;
+    }
+    this.log("warn", `${where}.failed`, { error: err.message });
+  }
+
+  connectRealtime() {
+    const factory = this.realtimeFactory ?? defaultRealtimeFactory;
+    this.realtime = factory({
+      config: this.config,
+      channel: `private-bridge-${this.config.device.id}`,
+      onEvent: (name, data) => this.handleCommand(name, data).catch((err) => this.log("error", "command.failed", { name, error: err.message })),
+      onState: (state) => this.handleRealtimeState(state),
+    });
+  }
+
+  async handleCommand(name, data) {
+    this.log("info", "command", { name, turnId: data?.turnId, commandId: data?.commandId });
+    switch (name) {
+      case "bridge.turn.start":
+        return this.startTurn(data);
+      case "bridge.turn.cancel":
+        this.running.get(data.turnId)?.abort();
+        return;
+      case "bridge.rescan":
+        await this.scanRepos();
+        return this.hello();
+      case "bridge.repo.clone":
+        return this.cloneRepo(data);
+      case "bridge.repo.locate":
+        return this.locateRepo(data);
+      case "bridge.profile.login":
+        return this.profileLogin(data);
+      case "bridge.harness.install":
+        return this.harnessInstall(data);
+      case "bridge.session.close":
+        this.services.get(data.sessionId)?.stopAll();
+        this.services.delete(data.sessionId);
+        this.clearPreviewIdleTimer(data.sessionId);
+        return;
+      case "bridge.preview.start":
+        return this.previewStart(data);
+      case "bridge.preview.stop":
+        return this.previewStop(data);
+      default:
+        this.log("warn", "command.unknown", { name });
+    }
+  }
+
+  /**
+   * On-demand preview (dashboard "Start preview"): boot the repos' dev
+   * services inside the session's EXISTING worktrees. Resolves paths by
+   * existence only — materializing checkouts is the turn path's job, so
+   * a pruned worktree is an error, not a re-clone.
+   */
+  async previewStart({ sessionId, title, repos }) {
+    const report = (payload) =>
+      this.api.sessionPreview(sessionId, payload).catch((err) => this.log("warn", "preview.report.failed", { error: err.message }));
+    await report({ status: "starting" });
+    try {
+      // Pass 1 — resolve every session repo (checkout, env, config) and
+      // collect the companion repos their configs ask for, before booting
+      // anything: companions must boot FIRST so `${port:x}` cross-refs
+      // resolve in the shared per-session port map.
+      const resolved = [];
+      const companionWants = new Map(); // repo key → { optional }
+      for (const r of repos || []) {
+        const group = this.repoGroups.find((g) => g.key === r.key);
+        if (!group) {
+          await report({ status: "error", error: `Repository ${r.key} is not checked out on this device.` });
+          return;
+        }
+        const mode = r.mode || this.config.repoModes?.[r.key] || "worktree";
+        const cwd = mode === "local" ? group.primary.path : worktreePath(this.kaiHome, group.name, sessionSlug(sessionId, title));
+        if (!existsSync(cwd)) {
+          await report({
+            status: "error",
+            error: `The workspace for this session is gone on this device — send Kai a message to recreate it, then start the preview again.`,
+          });
+          return;
+        }
+        // Gitignored env files never reach a fresh worktree — copy the
+        // primary checkout's so env-dependent apps (the dashboard itself)
+        // don't boot blank. Never overwrites existing files.
+        if (mode !== "local") {
+          const copied = copyPrimaryEnvFiles(group.primary.path, cwd);
+          if (copied.length) this.log("info", "preview.env.copied", { cwd, copied });
+        }
+        const config = readDevConfig(cwd) ?? detectDevConfig(cwd);
+        if (!config) continue;
+        if (config.error) {
+          await report({ status: "error", error: config.error });
+          return;
+        }
+        for (const c of config.companions || []) {
+          if ((repos || []).some((sr) => sr.key === c.repo)) continue; // already part of the session
+          const prev = companionWants.get(c.repo);
+          // Required by any config → required overall.
+          companionWants.set(c.repo, { optional: (prev ? prev.optional : true) && c.optional });
+        }
+        resolved.push({ key: r.key, cwd, config, mode });
+      }
+      if (!resolved.length) {
+        await report({ status: "error", error: "No dev config found — add .gleap/dev.yaml to the repo (services + preview)." });
+        return;
+      }
+      const runner = this.runnerFor(sessionId, (message) => this.log("info", "preview.status", { sessionId, message }));
+      // Pass 2 — companions: clone when missing, then boot from the
+      // PRIMARY checkout in local mode, so an already-running dev server
+      // on the declared port is adopted instead of duplicated.
+      const companionPreviews = [];
+      for (const [key, { optional }] of companionWants) {
+        try {
+          const group = await this.ensureCompanionCheckout(key, report);
+          const config = readDevConfig(group.primary.path) ?? detectDevConfig(group.primary.path);
+          if (!config) throw new Error(`no dev config — add .gleap/dev.yaml to ${key}`);
+          if (config.error) throw new Error(config.error);
+          const started = await this.bootRepoWithConfig(runner, group.primary.path, config, "local");
+          if (started.preview) companionPreviews.push({ repo: key, ...started.preview });
+        } catch (err) {
+          if (optional) {
+            this.log("warn", "preview.companion.skipped", { sessionId, repo: key, error: err.message });
+            continue;
+          }
+          runner.stopAll();
+          this.services.delete(sessionId);
+          await report({ status: "error", error: `Companion ${key}: ${err.message}` });
+          return;
+        }
+      }
+      // Pass 3 — the session repos themselves (worktree mode boots its
+      // own copy on a free port: it must serve the changed code).
+      const previews = [];
+      for (const { key, cwd, config, mode } of resolved) {
+        try {
+          const started = await this.bootRepoWithConfig(runner, cwd, config, mode);
+          if (started.preview) previews.push({ repo: key, ...started.preview });
+        } catch (err) {
+          runner.stopAll();
+          this.services.delete(sessionId);
+          await report({ status: "error", error: err.message });
+          return;
+        }
+      }
+      this.armPreviewIdleTimer(sessionId);
+      await report({ status: "running", previews: [...previews, ...companionPreviews] });
+    } catch (err) {
+      this.log("error", "preview.start.failed", { sessionId, error: err.message });
+      await report({ status: "error", error: err.message });
+    }
+  }
+
+  /**
+   * Boot one repo's services with an already-resolved config; throws a
+   * readable error (with the failing service's log tail) when a service
+   * never becomes ready — a "running" preview must not 404.
+   */
+  async bootRepoWithConfig(runner, cwd, config, mode) {
+    const started = await runner.start(cwd, config, { mode });
+    const dead = started.services.find((s) => !s.adopted && !s.ready);
+    if (dead) {
+      let tail = "";
+      try {
+        const raw = readFileSync(dead.logPath, "utf8");
+        tail = raw.trim().split("\n").slice(-3).join(" · ").slice(0, 300);
+      } catch {}
+      throw new Error(`${dead.name} did not start${tail ? ` — ${tail}` : ""}`);
+    }
+    return started;
+  }
+
+  /**
+   * A companion repo must exist on this machine. Cloned → its group.
+   * Not cloned → clone it into the preferred root (github.com keys only
+   * — the key itself is the remote address) and rescan.
+   */
+  async ensureCompanionCheckout(key, report) {
+    let group = this.repoGroups.find((g) => g.key === key);
+    if (group) return group;
+    const [host, owner, name] = String(key).split("/");
+    if (host !== "github.com" || !owner || !name) {
+      throw new Error(`not cloned on this device — clone it, then start the preview again`);
+    }
+    await report({ status: "starting", error: null, note: `Cloning ${name}…` });
+    this.log("info", "preview.companion.clone", { key });
+    await this.cloneRepo({ remote: `https://github.com/${owner}/${name}.git`, name });
+    group = this.repoGroups.find((g) => g.key === key);
+    if (!group) throw new Error(`clone finished but the repository was not discovered — check the daemon log`);
+    return group;
+  }
+
+  /**
+   * Previews are for looking at, not for hosting: stop everything after
+   * 30 idle minutes (Lukas 08-26 — was 4h). Re-armed on every (re)start,
+   * cleared on manual stop and session close. Turn-path services are
+   * unaffected until a preview start adopts the same runner.
+   */
+  armPreviewIdleTimer(sessionId) {
+    this.previewIdleTimers ??= new Map();
+    this.clearPreviewIdleTimer(sessionId);
+    const t = setTimeout(() => {
+      this.previewIdleTimers.delete(sessionId);
+      const runner = this.services.get(sessionId);
+      if (!runner) return;
+      runner.stopAll();
+      this.services.delete(sessionId);
+      this.log("info", "preview.idle.stopped", { sessionId });
+      this.api
+        .sessionPreview(sessionId, { status: "stopped", error: "Stopped automatically after 30 minutes." })
+        .catch((err) => this.log("warn", "preview.report.failed", { error: err.message }));
+    }, this.previewIdleMs ?? 30 * 60 * 1000);
+    t.unref?.();
+    this.previewIdleTimers.set(sessionId, t);
+  }
+
+  clearPreviewIdleTimer(sessionId) {
+    const t = this.previewIdleTimers?.get(sessionId);
+    if (t) clearTimeout(t);
+    this.previewIdleTimers?.delete(sessionId);
+  }
+
+  async previewStop({ sessionId }) {
+    this.services.get(sessionId)?.stopAll();
+    this.services.delete(sessionId);
+    this.clearPreviewIdleTimer(sessionId);
+    await this.api.sessionPreview(sessionId, { status: "stopped" }).catch((err) => this.log("warn", "preview.report.failed", { error: err.message }));
+  }
+
+  /** One ServiceRunner per session, shared by the turn path and on-demand preview. */
+  runnerFor(sessionId, onStatus) {
+    let runner = this.services.get(sessionId);
+    if (!runner) {
+      runner = new ServiceRunner({ kaiHome: this.kaiHome, sessionId, log: this.log, onStatus });
+      this.services.set(sessionId, runner);
+    }
+    return runner;
+  }
+
+  /** Map the Server's repo bindings onto local checkouts; throw a readable error when one is missing. */
+  bindRepos(turn) {
+    const bound = [];
+    for (const r of turn.repos || []) {
+      const group = this.repoGroups.find((g) => g.key === r.key);
+      if (!group) throw new Error(`Repository ${r.key} is not checked out on this device.`);
+      const mode = r.mode || this.config.repoModes?.[r.key] || "worktree";
+      const ws = materializeBinding({
+        kaiHome: this.kaiHome,
+        repo: { name: group.name, primaryPath: group.primary.path, defaultBranch: group.primary.defaultBranch },
+        binding: { mode, base: r.base, carryUncommitted: r.carryUncommitted },
+        sessionId: turn.sessionId,
+        title: turn.title,
+      });
+      bound.push({ key: r.key, ...ws });
+      // Remember the choice per repo (the UI asks once, then sticks).
+      this.config.repoModes = { ...(this.config.repoModes || {}), [r.key]: mode };
+    }
+    saveConfig(this.config, this.kaiHome);
+    return bound;
+  }
+
+  async startTurn(turn) {
+    const { turnId } = turn;
+    if (this.running.has(turnId)) return;
+    const ctrl = new AbortController();
+    this.running.set(turnId, ctrl);
+    const releaseAwake = keepAwake();
+    let outcome = null;
+    this.rememberInflight(turnId);
+    const batcher = createEventBatcher({ api: this.api, turnId, onError: (err) => this.log("warn", "events.post.failed", { error: err.message }) });
+    try {
+      const profile = resolveProfiles(this.config, this.kaiHome).find((p) => p.id === turn.profileId) ?? { id: "gleap-key", kind: "gleap-key", harness: turn.harness };
+      const bound = this.bindRepos(turn);
+      // Multi-repo: the runner's cwd is the first repo; the others are
+      // reachable as siblings under the same worktree root or by their
+      // local paths — the prompt lists them.
+      const workDir = bound[0]?.cwd;
+      if (!workDir) throw new Error("Turn has no repositories.");
+      const repoNote = bound.length > 1 ? `\n\nRepositories for this task:\n${bound.map((b) => `- ${b.key}: ${b.cwd}`).join("\n")}` : "";
+      // Preview tier A: start the repos' dev services (from .gleap/dev.yaml)
+      // once per session, tell the agent where they run, and hand it the
+      // Playwright MCP so it can verify in a real browser.
+      const previewNote = await this.startServices(turn, bound, batcher);
+      const mcpServers = previewNote ? [...(turn.mcpServers || []), previewMcpServer(RUNNER_DIR)] : turn.mcpServers;
+      const res = await runTurn({
+        turn: { ...turn, task: `${turn.task}${repoNote}${previewNote}`, mcpServers },
+        profile,
+        workDir,
+        kaiHome: this.kaiHome,
+        signal: ctrl.signal,
+        onEvent: (ev) => batcher.push(ev),
+        onLog: (l) => this.log("debug", "runner", { line: l.slice(0, 500) }),
+      });
+      await batcher.flush();
+      const completed = !ctrl.signal.aborted && res.code === 0 && !res.rateLimited;
+      const changes = bound.map((b) => {
+        const diff = collectChanges(b.cwd);
+        // Build turns in worktree mode publish the session branch so the
+        // Server can open the PR; plan turns and local mode never push.
+        const shouldPush = completed && b.mode === "worktree" && !turn.planMode && diff.files.length > 0;
+        const push = shouldPush
+          ? commitAndPush(b.cwd, { branch: b.branch, message: `${turn.title || "Kai Code changes"}\n\nSession ${turn.sessionId} · run on ${this.config.device?.name || "a paired device"}` })
+          : null;
+        return { key: b.key, mode: b.mode, branch: b.branch, base: b.base, ...diff, push };
+      });
+      // Built OUTSIDE the report call: if posting the result throws, the
+      // catch below must not turn a finished turn into a failed one. The
+      // work is already committed and pushed at this point.
+      outcome = {
+        status: ctrl.signal.aborted ? "cancelled" : res.rateLimited ? "rate_limited" : res.code === 0 ? "completed" : "failed",
+        exitCode: res.code,
+        result: res.result,
+        // The runner's own failure text (e.g. the engine's usage-limit
+        // message) — the Server prefers this over its generic fallback.
+        ...(res.lastError && res.code !== 0 ? { error: res.lastError.replace(/^acp-runner: /, "").slice(0, 500) } : {}),
+        changes,
+        profileId: profile.id,
+      };
+    } catch (err) {
+      this.log("error", "turn.failed", { turnId, error: err.message });
+      await batcher.flush().catch(() => {});
+      outcome = outcome ?? { status: "failed", error: err.message };
+    } finally {
+      // One report, retried until it lands — a dropped result is what
+      // leaves a session spinning forever in the dashboard.
+      if (outcome) {
+        await this.api
+          .turnResult(turnId, outcome, {
+            onRetry: (err, attempt, delay) =>
+              this.log("warn", "result.retry", { turnId, attempt, nextInMs: delay, error: err.message }),
+          })
+          .catch((err) => this.log("error", "result.lost", { turnId, error: err.message }));
+      }
+      this.forgetInflight(turnId);
+      releaseAwake();
+      this.running.delete(turnId);
+    }
+  }
+
+  /** Start/adopt dev services for the turn's repos; returns the prompt note ("" when no dev.yaml). */
+  async startServices(turn, bound, batcher) {
+    const notes = [];
+    const previews = [];
+    for (const b of bound) {
+      // Turn path starts ONLY committed .gleap/dev.yaml services — the
+      // package.json heuristic is reserved for the user-initiated
+      // "Start preview" (auto-booting every node repo's dev server on
+      // every turn would be a heavyweight surprise).
+      const committed = readDevConfig(b.cwd);
+      const config = committed;
+      if (!committed && !turn.planMode) {
+        // Nudge the agent to make the setup durable once it has learned it.
+        notes.push(
+          `\n\nNo .gleap/dev.yaml found in ${b.key}. If you figure out how this project's dev server runs, ` +
+            `write .gleap/dev.yaml (services: { <name>: { cwd, run, port, health } }, preview: <name>) ` +
+            `so Gleap can run live previews for this repo in future sessions.`,
+        );
+      }
+      if (!config) continue;
+      if (config.error) {
+        batcher.push({ type: "text", message: `⚠️ ${config.error}` });
+        continue;
+      }
+      const runner = this.runnerFor(turn.sessionId, (message) =>
+        batcher.push({ type: "tool_status", message, toolName: "DevServer", toolSummary: message, toolStatus: "completed", toolPartId: `svc-${Date.now()}` }),
+      );
+      try {
+        const started = await runner.start(b.cwd, config, { mode: b.mode });
+        notes.push(runner.describeForAgent(started));
+        if (started.preview) previews.push({ repo: b.key, ...started.preview });
+      } catch (err) {
+        this.log("error", "services.start.failed", { repo: b.key, error: err.message });
+        batcher.push({ type: "text", message: `⚠️ Could not start dev services for ${b.key}: ${err.message}` });
+      }
+    }
+    if (previews.length > 0) {
+      // Session-keyed report (new servers) with the turn-keyed route as
+      // fallback for servers that predate it.
+      await this.api
+        .sessionPreview(turn.sessionId, { status: "running", previews })
+        .catch(() => this.api.turnPreview(turn.turnId, { previews }))
+        .catch((err) => this.log("warn", "preview.report.failed", { error: err.message }));
+    }
+    return notes.join("");
+  }
+
+  async cloneRepo({ commandId, remote, name }) {
+    // Prefer the directory the machine's repos already live in (e.g.
+    // ~/Documents/Gleap), not the bare scan root that discovered them
+    // (~/Documents) — "Clone here" should land next to the other checkouts.
+    const root = preferredCloneRoot(this.repoGroups, (this.config.roots || [])[0] ?? defaultRoots()[0]);
+    if (!root) throw new Error("No scan root to clone into — add one with `kai-bridge repo roots add <dir>`.");
+    const target = join(root, name);
+    await new Promise((resolve, reject) => {
+      const p = spawn("git", ["clone", remote, target], { stdio: "ignore" });
+      p.on("close", (code) => (code === 0 ? resolve() : reject(new Error(`git clone exited ${code}`))));
+      p.on("error", reject);
+    });
+    await this.scanRepos();
+    await this.hello();
+    if (commandId) await this.api.commandAck(commandId, { ok: true, path: target });
+  }
+
+  /**
+   * Manual escape from auto-discovery: point a repo at a checkout the
+   * scan never found (cloned outside the scan roots, a second working
+   * copy, a remote whose URL doesn't match the connected one).
+   *
+   * The folder's PARENT becomes a scan root too, so everything else
+   * living beside it is discovered from now on — the common case is a
+   * whole workspace directory the defaults didn't cover. Passing only a
+   * path (no repoKey) is exactly that: "also look in here".
+   */
+  async locateRepo({ commandId, repoKey, path: rawPath }) {
+    try {
+      const target = resolvePath(String(rawPath || "").replace(/^~(?=$|\/)/, homedir()));
+      if (!existsSync(target)) throw new Error(`${target} does not exist on this machine.`);
+      if (repoKey && !existsSync(join(target, ".git"))) {
+        throw new Error(`${target} is not a git checkout.`);
+      }
+      const root = repoKey ? dirname(target) : target;
+      this.config.roots = [...new Set([...(this.config.roots || []), root])];
+      if (repoKey) {
+        this.config.primaryOverrides = { ...(this.config.primaryOverrides || {}), [repoKey]: target };
+      }
+      saveConfig(this.config, this.kaiHome);
+      await this.scanRepos();
+      await this.hello();
+      // Report what the checkout's remote actually resolves to: a
+      // mismatch is why the repo was missing in the first place, and the
+      // dashboard can say so instead of silently doing nothing.
+      const found = repoKey ? this.repoGroups.find((g) => g.key === repoKey) : null;
+      if (commandId) {
+        await this.api.commandAck(commandId, {
+          ok: !repoKey || !!found,
+          path: target,
+          root,
+          ...(repoKey && !found
+            ? { error: `${target} is a checkout of a different repository than ${repoKey}.` }
+            : {}),
+        });
+      }
+    } catch (err) {
+      this.log("error", "repo.locate.failed", { error: err.message });
+      if (commandId) await this.api.commandAck(commandId, { ok: false, error: err.message }).catch(() => {});
+    }
+  }
+
+  async harnessInstall({ commandId, harness }) {
+    const lines = [];
+    try {
+      const res = await installHarness(harness, { kaiHome: this.kaiHome, onLog: (l) => { lines.push(l); this.log("info", "harness.install", { harness, line: l }); } });
+      await this.hello();
+      if (commandId) await this.api.commandAck(commandId, { ok: res.ok, version: res.version, log: lines });
+    } catch (err) {
+      this.log("error", "harness.install.failed", { harness, error: err.message });
+      if (commandId) await this.api.commandAck(commandId, { ok: false, error: err.message, log: lines }).catch(() => {});
+    }
+  }
+
+  async profileLogin({ commandId, profileId }) {
+    const profile = resolveProfiles(this.config, this.kaiHome).find((p) => p.id === profileId);
+    if (!profile) throw new Error(`Unknown profile ${profileId}`);
+    if (profile.kind === "managed") createManagedProfile(profile.harness, profile.id, this.kaiHome);
+    // Logins are interactive: open a terminal on this machine running the
+    // harness's own login under the profile's config dir, and re-announce
+    // the profile state once it exits.
+    const child = openLoginTerminal(profile.harness, profile.configDir);
+    if (!child) throw new Error(`Could not open a terminal for ${profile.harness} login on this device.`);
+    child.unref?.();
+    if (commandId) await this.api.commandAck(commandId, { ok: true, opened: "terminal" });
+    const poll = setInterval(() => this.hello().catch(() => {}), 15_000);
+    poll.unref?.();
+    setTimeout(() => clearInterval(poll), 10 * 60_000).unref?.();
+  }
+}
+
+/** Default realtime transport: @sockudo/client against the Gleap realtime host. */
+export function defaultRealtimeFactory({ config, channel, onEvent, onState }) {
+  let client = null;
+  (async () => {
+    const { default: Sockudo } = await import("@sockudo/client");
+    client = new Sockudo(config.realtime.appKey, {
+      wsHost: config.realtime.wsHost,
+      wssPort: 443,
+      forceTLS: true,
+      enabledTransports: ["ws", "wss"],
+      protocolVersion: 2,
+      connectionRecovery: true,
+      channelAuthorization: {
+        endpoint: `${config.apiBase}/gleapcode/bridge/devices/me/pusher`,
+        transport: "ajax",
+        headers: { Authorization: `Bearer ${config.device.token}` },
+      },
+    });
+    client.connection?.bind?.("state_change", (s) => onState(s.current));
+    const ch = client.subscribe(channel);
+    ch.bind_global?.((name, data) => {
+      if (typeof name === "string" && name.startsWith("bridge.")) onEvent(name, data);
+    });
+  })().catch((err) => onState(`error:${err.message}`));
+  return { disconnect: () => client?.disconnect?.() };
+}