@gleapai/kai-bridge 0.2.9 → 0.5.0

package/src/preview.mjs

@@ -3,16 +3,28 @@
 // Each repo may commit a `.gleap/dev.yaml`:
 //
 //   services:
-//     api: { cwd: Server,   run: "npm run dev", port: 9000, health: /health }
-//     web: { cwd: Frontend, run: "npm start",   port: 3000, env: { API_URL: "http://localhost:9000" } }
+//     api: { cwd: Server,   run: "npm run dev", port: 9000, health: /health, kind: api, openapi: docs/openapi.json,
+//            reload: restart, requires: [{ name: mongodb, port: 27017 }] }
+//     web: { cwd: Frontend, run: "npm start",   port: 3000, env: { API_URL: "http://localhost:9000" }, protocol: http }
 //   preview: web
+//   companions: [github.com/owner/api]
+//   verify: { readOnly: true, endpoints: [/api/v1/tickets], loginVia: github.com/owner/web }
+//   external: [https://cdn.example.com]
+//   auth: { storageState: <command>, loginCheck: { path, selector },
+//           apiToken: { from: localStorage, origin: web, key: token, header: Authorization, prefix: "Bearer " } }
 //
 // Worktree mode: every service gets a FREE port (the user's own dev server
 // may already own the declared one) — `PORT` is set and `${port:<name>}`
 // placeholders in `env`/`run` are substituted, so `API_URL: http://localhost:${port:api}`
 // follows the re-assignment. Local mode: a service whose declared port is
-// already listening is adopted as "your running dev server" instead of
-// started twice.
+// already listening is adopted as "your running dev server" — but ONLY when
+// the listener's working directory is inside the repo (ports.mjs); anything
+// else on that port is `port_busy`, with pid / command / cwd for the card.
+//
+// Every failure is a `PreviewError` (preview-errors.mjs) with a code the
+// dashboard turns into a diagnosis: dependency_missing, port_busy,
+// deps_failed, env_missing, service_crashed, … — classified from the whole
+// log tail before anything is truncated.
 //
 // Logs go to `~/.kai/logs/services/<session>/<service>.log` so Kai can
 // `tail` them; the timeline only gets one line per start/stop/failure.
@@ -21,13 +33,55 @@
 // later tier (needs relay infra).
 
 import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
 import { createServer, connect } from "node:net";
-import { existsSync, mkdirSync, openSync, readFileSync } from "node:fs";
-import { networkInterfaces } from "node:os";
-import { join, resolve, basename } from "node:path";
+import { request as httpsRequest } from "node:https";
+import { existsSync, mkdirSync, openSync, readFileSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { homedir, networkInterfaces } from "node:os";
+import { dirname, join, resolve, basename, posix as posixPath, win32 as win32Path } from "node:path";
+import { fileURLToPath } from "node:url";
 import YAML from "yaml";
 
+import { PreviewError, classifyLogTail, detectMonorepo, logTailSummary, missingEnvKeys, stripOpenFlag } from "./preview-errors.mjs";
+import { canAdoptPort, describeBusyPort, describeListener as lsofDescribeListener } from "./ports.mjs";
+import { copyPrimaryEnvFiles } from "./workspace.mjs";
+
+const DEFAULT_RUNNER_DIR = join(dirname(fileURLToPath(import.meta.url)), "..", "runner");
+import { installCommandFor } from "./deps.mjs";
+
 export const DEV_CONFIG_PATHS = [".gleap/dev.yaml", ".gleap/dev.yml"];
+export const SERVICE_KINDS = new Set(["web", "api"]);
+export const RELOAD_MODES = new Set(["hot", "restart"]);
+export const PROTOCOLS = new Set(["http", "https"]);
+export const DEPS_INSTALL_TIMEOUT_MS = 10 * 60_000;
+export const DEPS_MARKER = ".kai-installed";
+/** Progress ticks during long waits (install, readiness) — the booting heartbeat. */
+export const PROGRESS_TICK_MS = 30_000;
+/** Post-ready settle before the re-probe (env override for tests: KAI_PREVIEW_SETTLE_MS). Read at construction time. */
+const DEFAULT_SETTLE_MS = Symbol("default");
+const defaultSettleMs = () => Math.max(0, Number(process.env.KAI_PREVIEW_SETTLE_MS ?? 3_000) || 0);
+const KNOWN_TOP_KEYS = new Set(["services", "preview", "companions", "auth", "verify", "external"]);
+const KNOWN_SERVICE_KEYS = new Set(["name", "cwd", "run", "port", "health", "env", "readyTimeoutMs", "kind", "openapi", "protocol", "reload", "requires"]);
+const KNOWN_AUTH_KEYS = new Set(["storageState", "loginCheck", "apiToken"]);
+
+const EMPTY_CONFIG = () => ({ services: {}, preview: null, companions: [], auth: { storageState: null, loginCheck: null, apiToken: null }, verify: { readOnly: null, endpoints: [], loginVia: null }, external: [], unknownKeys: [], error: null });
+
+/**
+ * Wrap a service/install command so it runs with the daemon's own node
+ * first on PATH. Under launchd the daemon's PATH is frozen at install
+ * time (service.mjs), so we run through a login shell to pick up
+ * nvm/pnpm shims — but on macOS a login shell runs `path_helper`, which
+ * moves `/usr/local/bin` ahead of every inherited entry and never
+ * sources `.zshrc` (where nvm lives). A stale `/usr/local/bin/node`
+ * then wins over the nvm node the daemon itself runs on, and Vite
+ * refuses to start. Prepending inside the command string survives that
+ * reordering; prepending on `env.PATH` does not.
+ */
+export function withDaemonNode(cmd, nodeBin = dirname(process.execPath)) {
+  const quoted = `'${nodeBin.replace(/'/g, `'\\''`)}'`;
+  return `export PATH=${quoted}:"$PATH"; ${cmd}`;
+}
 
 export function readDevConfig(repoRoot) {
   for (const rel of DEV_CONFIG_PATHS) {
@@ -37,14 +91,31 @@ export function readDevConfig(repoRoot) {
       const parsed = YAML.parse(readFileSync(p, "utf8")) || {};
       return normalizeDevConfig(parsed);
     } catch (err) {
-      return { services: {}, preview: null, companions: [], error: `${rel}: ${err?.message || err}` };
+      return { ...EMPTY_CONFIG(), error: `${rel}: ${err?.message || err}` };
     }
   }
   return null;
 }
 
+function normalizeOriginList(list) {
+  const out = [];
+  for (const entry of Array.isArray(list) ? list : typeof list === "string" ? [list] : []) {
+    try {
+      const u = new URL(String(entry).trim());
+      if (u.protocol === "http:" || u.protocol === "https:") out.push(u.origin.toLowerCase());
+    } catch {
+      /* junk */
+    }
+  }
+  return [...new Set(out)];
+}
+
 export function normalizeDevConfig(raw) {
   const services = {};
+  const unknownKeys = [];
+  if (raw && typeof raw === "object" && !Array.isArray(raw)) {
+    for (const k of Object.keys(raw)) if (!KNOWN_TOP_KEYS.has(k)) unknownKeys.push(k);
+  }
   // Accept both shapes: `services: {api: {...}}` and the list form
   // `services: [- name: api ...]` people naturally write in YAML —
   // Object.entries on an array yields index keys, which used to name
@@ -54,6 +125,16 @@ export function normalizeDevConfig(raw) {
     : raw?.services || {};
   for (const [name, s] of Object.entries(rawServices)) {
     if (!s || typeof s !== "object" || !s.run) continue;
+    for (const k of Object.keys(s)) if (!KNOWN_SERVICE_KEYS.has(k)) unknownKeys.push(`services.${name}.${k}`);
+    const kind = typeof s.kind === "string" && SERVICE_KINDS.has(s.kind.toLowerCase()) ? s.kind.toLowerCase() : null;
+    const protocol = typeof s.protocol === "string" && PROTOCOLS.has(s.protocol.toLowerCase()) ? s.protocol.toLowerCase() : "http";
+    const reload = typeof s.reload === "string" && RELOAD_MODES.has(s.reload.toLowerCase()) ? s.reload.toLowerCase() : null;
+    const requires = [];
+    for (const r of Array.isArray(s.requires) ? s.requires : []) {
+      const port = Number(r?.port);
+      if (!Number.isInteger(port) || port <= 0) continue;
+      requires.push({ name: typeof r?.name === "string" && r.name.trim() ? r.name.trim() : `service on :${port}`, port });
+    }
     services[name] = {
       name,
       cwd: typeof s.cwd === "string" ? s.cwd : ".",
@@ -62,9 +143,45 @@ export function normalizeDevConfig(raw) {
       health: typeof s.health === "string" ? s.health : null,
       env: s.env && typeof s.env === "object" ? Object.fromEntries(Object.entries(s.env).map(([k, v]) => [k, String(v)])) : {},
       readyTimeoutMs: Number.isFinite(Number(s.readyTimeoutMs)) ? Number(s.readyTimeoutMs) : 90_000,
+      kind, // null = auto (probe content-type after boot)
+      openapi: typeof s.openapi === "string" && s.openapi.trim() ? s.openapi.trim() : null,
+      protocol,
+      reload, // null = default for the kind (hot for web, restart for api)
+      requires,
     };
   }
   const preview = typeof raw?.preview === "string" && services[raw.preview] ? raw.preview : Object.keys(services)[0] || null;
+  // Optional sign-in hooks for Verify (0.4.0):
+  //   auth:
+  //     storageState: "node scripts/test-login.mjs"   # prints Playwright storageState JSON (or a path to it)
+  //     loginCheck: { path: /account, selector: "[data-testid=user-menu]" }
+  //     apiToken: { from: localStorage, origin: web, key: token, header: Authorization, prefix: "Bearer " }
+  // `storageState` replaces the user's saved sign-in record; `loginCheck`
+  // replaces the probe's login-wall heuristic (selector visible = signed in);
+  // `apiToken` says where the app keeps its API credential so the daemon can
+  // hand `http_request` an auth header derived from the injected sign-in.
+  const rawAuth = raw?.auth && typeof raw.auth === "object" ? raw.auth : {};
+  for (const k of Object.keys(rawAuth)) if (!KNOWN_AUTH_KEYS.has(k)) unknownKeys.push(`auth.${k}`);
+  const loginCheck =
+    rawAuth.loginCheck && typeof rawAuth.loginCheck === "object" && typeof rawAuth.loginCheck.selector === "string" && rawAuth.loginCheck.selector.trim()
+      ? { path: typeof rawAuth.loginCheck.path === "string" && rawAuth.loginCheck.path.trim() ? rawAuth.loginCheck.path.trim() : "/", selector: rawAuth.loginCheck.selector.trim() }
+      : null;
+  const rawToken = rawAuth.apiToken && typeof rawAuth.apiToken === "object" ? rawAuth.apiToken : null;
+  const apiToken =
+    rawToken && typeof rawToken.key === "string" && rawToken.key.trim()
+      ? {
+          from: rawToken.from === "cookie" ? "cookie" : "localStorage",
+          origin: typeof rawToken.origin === "string" && rawToken.origin.trim() ? rawToken.origin.trim() : preview,
+          key: rawToken.key.trim(),
+          header: typeof rawToken.header === "string" && /^[A-Za-z0-9-]+$/.test(rawToken.header.trim()) ? rawToken.header.trim() : "Authorization",
+          prefix: typeof rawToken.prefix === "string" ? rawToken.prefix : "Bearer ",
+        }
+      : null;
+  const auth = {
+    storageState: typeof rawAuth.storageState === "string" && rawAuth.storageState.trim() ? rawAuth.storageState.trim() : null,
+    loginCheck,
+    apiToken,
+  };
   // Companion repos this preview needs running alongside (an API for a
   // frontend, etc). Entries are repo keys as reported by the device scan
   // ("github.com/owner/name") — strings, or {repo, optional} objects.
@@ -75,14 +192,30 @@ export function normalizeDevConfig(raw) {
     if (!repo) continue;
     companions.push({ repo: repo.toLowerCase().trim(), optional: !!(entry && typeof entry === "object" && entry.optional) });
   }
-  return { services, preview, companions, error: null };
+  // Verify policy: `readOnly` null = default (true when the run exercises an
+  // API service — a shared database must not be written by a tester).
+  const rawVerify = raw?.verify && typeof raw.verify === "object" ? raw.verify : {};
+  const verify = {
+    readOnly: typeof rawVerify.readOnly === "boolean" ? rawVerify.readOnly : null,
+    endpoints: (Array.isArray(rawVerify.endpoints) ? rawVerify.endpoints : []).map((e) => String(e).trim()).filter(Boolean).slice(0, 50),
+    loginVia: typeof rawVerify.loginVia === "string" && rawVerify.loginVia.trim() ? rawVerify.loginVia.trim().toLowerCase() : null,
+  };
+  return { services, preview, companions, auth, verify, external: normalizeOriginList(raw?.external), unknownKeys, error: null };
+}
+
+/** The reload mode a service actually uses (`hot` unless declared / api). */
+export function effectiveReload(svc, kind = svc?.kind) {
+  if (svc?.reload) return svc.reload;
+  return kind === "api" ? "restart" : "hot";
 }
 
 /**
  * No-config fallback: infer a single dev service from the repo's root
  * package.json. `.gleap/dev.yaml` stays the durable override — callers
  * check `readDevConfig` first. Returns null when nothing runnable is
- * found (no package.json, or no dev/start/serve script).
+ * found (no package.json, or no dev/start/serve script), and
+ * `{ needsConfig: true, hint }` for a workspace root (turbo / nx / lerna /
+ * pnpm -r / yarn workspaces) where guessing a command would be wrong.
  */
 export function detectDevConfig(repoRoot) {
   const pkgPath = join(repoRoot, "package.json");
@@ -93,6 +226,8 @@ export function detectDevConfig(repoRoot) {
   } catch {
     return null;
   }
+  const mono = detectMonorepo(repoRoot, pkg, { exists: existsSync });
+  if (mono) return { needsConfig: true, hint: mono.hint };
   const scripts = pkg.scripts && typeof pkg.scripts === "object" ? pkg.scripts : {};
   const script = ["dev", "start", "serve"].find((s) => typeof scripts[s] === "string" && scripts[s].trim());
   if (!script) return null;
@@ -153,6 +288,14 @@ export function getFreePort() {
   });
 }
 
+/** First port in [port, port + tries) nobody is listening on, else null. */
+export async function findFreePortNear(port, tries = 10) {
+  for (let p = port; p < port + tries && p <= 65535; p++) {
+    if (!(await isPortListening(p))) return p;
+  }
+  return null;
+}
+
 export function lanAddress() {
   for (const list of Object.values(networkInterfaces())) {
     for (const i of list || []) if (i.family === "IPv4" && !i.internal) return i.address;
@@ -165,56 +308,148 @@ export function substitutePorts(value, ports) {
   return String(value).replace(/\$\{port:([\w-]+)\}/g, (_, name) => String(ports[name] ?? ""));
 }
 
-async function waitForReady({ port, health, timeoutMs }) {
+/** GET `url` accepting self-signed certificates (dev https); resolves `{ status, contentType }` or null. */
+export function fetchInsecure(url, { timeoutMs = 2_000 } = {}) {
+  return new Promise((resolveP) => {
+    if (!/^https:/i.test(url)) {
+      fetch(url, { signal: AbortSignal.timeout(timeoutMs), redirect: "manual" })
+        .then((res) => resolveP({ status: res.status, contentType: res.headers.get("content-type") || "" }))
+        .catch(() => resolveP(null));
+      return;
+    }
+    let done = false;
+    const finish = (v) => {
+      if (done) return;
+      done = true;
+      resolveP(v);
+    };
+    try {
+      const req = httpsRequest(url, { method: "GET", rejectUnauthorized: false, timeout: timeoutMs }, (res) => {
+        finish({ status: res.statusCode ?? 0, contentType: String(res.headers["content-type"] || "") });
+        res.resume();
+      });
+      req.on("timeout", () => {
+        req.destroy();
+        finish(null);
+      });
+      req.on("error", () => finish(null));
+      req.end();
+    } catch {
+      finish(null);
+    }
+  });
+}
+
+/** Content-type ≠ text/html → an API (no UI to click through). Web when unknown. */
+export function kindFromContentType(contentType) {
+  const ct = String(contentType || "").toLowerCase();
+  if (!ct) return "web";
+  return ct.includes("text/html") ? "web" : "api";
+}
+
+async function waitForReady({ port, health, timeoutMs, protocol = "http", onTick = () => {}, tickMs = PROGRESS_TICK_MS }) {
   const deadline = Date.now() + timeoutMs;
+  const startedAt = Date.now();
+  let nextTick = startedAt + tickMs;
   while (Date.now() < deadline) {
     if (health) {
-      try {
-        // `localhost`, not 127.0.0.1 — the server may be IPv6-only (see
-        // isPortListening); Node's fetch tries both families.
-        const res = await fetch(`http://localhost:${port}${health.startsWith("/") ? health : `/${health}`}`, { signal: AbortSignal.timeout(2000) });
-        if (res.ok || (res.status >= 300 && res.status < 500)) return true;
-      } catch {
-        /* not yet */
-      }
+      // `localhost`, not 127.0.0.1 — the server may be IPv6-only (see
+      // isPortListening); Node's fetch tries both families.
+      const res = await fetchInsecure(`${protocol}://localhost:${port}${health.startsWith("/") ? health : `/${health}`}`, { timeoutMs: 2000 });
+      if (res && (res.status < 300 || (res.status >= 300 && res.status < 500))) return true;
     } else if (await isPortListening(port)) {
       return true;
     }
+    if (Date.now() >= nextTick) {
+      onTick(Math.round((Date.now() - startedAt) / 1000));
+      nextTick = Date.now() + tickMs;
+    }
     await new Promise((r) => setTimeout(r, 1000));
   }
   return false;
 }
 
+function lockfileHash(cwd) {
+  for (const name of ["pnpm-lock.yaml", "yarn.lock", "package-lock.json", "bun.lockb", "bun.lock"]) {
+    const p = join(cwd, name);
+    if (!existsSync(p)) continue;
+    try {
+      return createHash("sha1").update(readFileSync(p)).digest("hex");
+    } catch {
+      /* unreadable lockfile — treat as none */
+    }
+  }
+  return "none";
+}
+
+/** Runs `cmd` through the user's login shell (darwin) or the platform shell, capturing output into `fd`. */
+function spawnShell(cmd, { cwd, env, fd, detached = false }) {
+  if (process.platform !== "win32") cmd = withDaemonNode(cmd);
+  if (process.platform === "darwin") {
+    // Under launchd the daemon's PATH is frozen at install time
+    // (service.mjs), so nvm/pnpm shims don't resolve with a bare
+    // `shell: true`. A login shell rebuilds the user's real PATH.
+    return spawn("/bin/zsh", ["-lc", cmd], { cwd, env, stdio: ["ignore", fd, fd], detached });
+  }
+  // Windows has no process groups to kill and `detached` would open a
+  // console window — taskkill /T does the tree.
+  return spawn(cmd, { cwd, env, shell: true, stdio: ["ignore", fd, fd], detached: process.platform !== "win32" && detached, windowsHide: true });
+}
+
 /**
  * Runs the services of one repo binding for the lifetime of a turn (or
  * longer — the daemon keeps them per session until the session ends).
  */
 export class ServiceRunner {
-  constructor({ kaiHome, sessionId, log = () => {}, onStatus = () => {} }) {
+  /**
+   * `preferredPort({ repoKey, service })` → a port to TRY before falling
+   * back to a random free one (the daemon injects a stable hash of
+   * repo + service into 43000-43999, so a saved sign-in's origins keep
+   * matching across sessions). Only used when the port is actually free.
+   * `describeListener(port)` (ports.mjs by default) decides adoption;
+   * `onServiceExit({ name, code, repoRoot, repoKey, logPath, error, errorCode, detail })`
+   * fires when a service that had become ready dies on its own;
+   * `onProcess(name, pid, "add" | "remove")` lets the daemon persist pids.
+   */
+  constructor({ kaiHome, sessionId, log = () => {}, onStatus = () => {}, preferredPort = null, describeListener = null, settleMs = DEFAULT_SETTLE_MS, onServiceExit = () => {}, onProcess = () => {}, home = homedir() } = {}) {
+    if (settleMs === DEFAULT_SETTLE_MS) settleMs = defaultSettleMs();
     this.kaiHome = kaiHome;
     this.sessionId = sessionId;
     this.log = log;
     this.onStatus = onStatus;
+    this.preferredPort = typeof preferredPort === "function" ? preferredPort : null;
+    this.describeListener = typeof describeListener === "function" ? describeListener : (port) => lsofDescribeListener(port);
+    this.settleMs = Math.max(0, Number(settleMs) || 0);
+    this.onServiceExit = onServiceExit;
+    this.onProcess = onProcess;
+    this.home = home;
     this.processes = new Map(); // name → child
     this.ports = {}; // name → port
     this.adopted = new Set();
+    this.adoptedCwd = new Map();
+    this.stopping = new Set(); // names being stopped on purpose (no crash report)
+    this.serviceRoots = new Map(); // service name → repo root
+    this.repoKeys = new Map(); // service name → repo key
+    this.meta = new Map(); // service name → { svc, repoRoot, repoKey, mode, cwd, logPath, kind, protocol, ready, envSource }
+    this.registered = new Map(); // repoRoot → [svc] (renamed, in config order)
     this.logDir = join(kaiHome, "logs", "services", String(sessionId).replace(/[^\w.-]/g, "_"));
   }
 
   /**
-   * Start (or adopt) every service in `config` relative to `repoRoot`.
-   * Returns `{ services: [{name, port, url, logPath, adopted, ready}], preview: {name, url, lanUrl} | null }`.
+   * Register a repo's services and assign their ports WITHOUT booting —
+   * called for every config (session repos + companions) before any boot,
+   * so `${port:x}` cross-references resolve regardless of boot order.
+   * Idempotent per repo root. Throws `PreviewError` (`port_busy`) when a
+   * declared port is held by a process that is not this repo's.
    */
-  async start(repoRoot, config, { mode = "worktree" } = {}) {
-    mkdirSync(this.logDir, { recursive: true });
-    const out = [];
+  async assignPorts(repoRoot, config, { mode = "worktree", repoKey = null, envSource = null } = {}) {
+    if (this.registered.has(repoRoot)) return this.registered.get(repoRoot);
     // Same service name from a DIFFERENT repo is a collision, not a
     // reuse: silently sharing the port map entry made the second repo
     // ride the first one's port and never boot. Uniquify with the repo
     // folder as prefix and say so — committed configs should pick
     // collision-safe names, but the runtime must not break when they
     // don't.
-    this.serviceRoots ??= new Map();
     const services = Object.values(config.services).map((svc) => {
       const owner = this.serviceRoots.get(svc.name);
       if (owner && owner !== repoRoot) {
@@ -223,102 +458,309 @@ export class ServiceRunner {
         svc = { ...svc, name: unique };
       }
       this.serviceRoots.set(svc.name, repoRoot);
+      if (repoKey) this.repoKeys.set(svc.name, repoKey);
       return svc;
     });
-    const previewName = config.preview && !services.some((s) => s.name === config.preview)
-      ? services.find((s) => s.name.endsWith(`-${config.preview}`))?.name ?? config.preview
-      : config.preview;
-    // Assign ports first so cross-references resolve.
+    const previewName =
+      config.preview && !services.some((s) => s.name === config.preview) ? (services.find((s) => s.name.endsWith(`-${config.preview}`))?.name ?? config.preview) : config.preview;
     for (const svc of services) {
+      if (!this.meta.has(svc.name)) {
+        this.meta.set(svc.name, { svc, repoRoot, repoKey, mode, cwd: resolve(repoRoot, svc.cwd), logPath: join(this.logDir, `${svc.name}.log`), kind: svc.kind, protocol: svc.protocol, ready: false, envSource, previewName });
+      }
       if (this.ports[svc.name]) continue;
       const declared = svc.port;
-      if (mode === "local" && declared && (await isPortListening(declared))) {
-        this.ports[svc.name] = declared;
-        this.adopted.add(svc.name);
-      } else if (declared && !(await isPortListening(declared))) {
+      if (declared && !(await isPortListening(declared))) {
         this.ports[svc.name] = declared;
-      } else {
-        this.ports[svc.name] = await getFreePort();
-      }
-    }
-    for (const svc of services) {
-      const port = this.ports[svc.name];
-      const logPath = join(this.logDir, `${svc.name}.log`);
-      if (this.adopted.has(svc.name)) {
-        out.push({ name: svc.name, port, url: `http://localhost:${port}`, logPath: null, adopted: true, ready: true });
-        this.onStatus(`Using your running ${svc.name} on :${port}`);
         continue;
       }
-      if (this.processes.has(svc.name)) {
-        out.push({ name: svc.name, port, url: `http://localhost:${port}`, logPath, adopted: false, ready: true });
-        continue;
+      if (declared) {
+        // Someone listens on the declared port. Ours (cwd inside the repo)
+        // in local mode → adopt. Anything else → busy: local mode cannot
+        // move (the app is wired to that port), worktree mode can — unless
+        // the run command hard-codes the number.
+        const listener = await this.describeListener(declared).catch(() => null);
+        if (mode === "local" && canAdoptPort({ listener, repoRoot })) {
+          this.ports[svc.name] = declared;
+          this.adopted.add(svc.name);
+          // Remember WHICH checkout serves it (may be a sibling worktree) so
+          // branch/commit/dirty describe the code actually running.
+          if (listener?.cwd) this.adoptedCwd.set(svc.name, listener.cwd);
+          continue;
+        }
+        const busy = describeBusyPort(declared, listener, { home: this.home });
+        const hardCoded = new RegExp(`(^|[^0-9])${declared}([^0-9]|$)`).test(`${svc.run} ${Object.values(svc.env).join(" ")}`);
+        if (mode === "local" || hardCoded) {
+          throw new PreviewError(`${svc.name}: ${busy.message}${mode === "local" ? "" : ` The run command pins that port, so it cannot be moved.`}`, {
+            code: "port_busy",
+            repo: repoKey,
+            service: svc.name,
+            detail: busy.detail,
+          });
+        }
       }
-      const cwd = resolve(repoRoot, svc.cwd);
-      const env = {
-        ...process.env,
-        PORT: String(port),
-        ...Object.fromEntries(Object.entries(svc.env).map(([k, v]) => [k, substitutePorts(v, this.ports)])),
-        KAI_SESSION_ID: String(this.sessionId),
-        BROWSER: "none",
-      };
-      const fd = openSync(logPath, "a");
-      // Fresh worktrees have no node_modules — running the dev command
-      // straight into `command not found` was the #1 preview failure.
-      await this.ensureDeps(cwd, { env, fd, logPath });
-      const cmd = substitutePorts(svc.run, this.ports);
-      // Under launchd the daemon's PATH is frozen at install time
-      // (service.mjs), so nvm/pnpm shims don't resolve with a bare
-      // `shell: true`. A login shell rebuilds the user's real PATH.
-      const child =
-        process.platform === "darwin"
-          ? spawn("/bin/zsh", ["-lc", cmd], { cwd, env, stdio: ["ignore", fd, fd], detached: true })
-          : spawn(cmd, { cwd, env, shell: true, stdio: ["ignore", fd, fd], detached: true });
-      child.on("exit", (code) => {
-        this.processes.delete(svc.name);
-        this.log("info", "service.exit", { name: svc.name, code });
-        if (code && code !== 0) this.onStatus(`${svc.name} exited with code ${code} — see ${logPath}`);
-      });
-      this.processes.set(svc.name, child);
-      this.onStatus(`Starting ${svc.name} (${svc.run}) on :${port}`);
-      // Bail as soon as the process dies (command not found, crash on
-      // boot) instead of polling a dead port for the full timeout.
-      const ready = await Promise.race([
-        waitForReady({ port, health: svc.health, timeoutMs: svc.readyTimeoutMs }),
-        new Promise((resolveP) => child.once("exit", () => setTimeout(() => resolveP(false), 300))),
-      ]);
-      this.onStatus(ready ? `${svc.name} ready on http://localhost:${port}` : `${svc.name} did not become ready within ${Math.round(svc.readyTimeoutMs / 1000)}s — see ${logPath}`);
-      out.push({ name: svc.name, port, url: `http://localhost:${port}`, logPath, adopted: false, ready });
+      this.ports[svc.name] = (declared ? await findFreePortNear(declared) : await this.stablePort(repoKey, svc.name)) ?? (await getFreePort());
     }
+    this.registered.set(repoRoot, services);
+    this.previewNames ??= new Map();
+    this.previewNames.set(repoRoot, previewName);
+    return services;
+  }
+
+  /**
+   * Start (or adopt) every service in `config` relative to `repoRoot`.
+   * Returns `{ services: [{name, port, url, logPath, adopted, ready, kind, protocol}], preview: {name, url, lanUrl} | null }`.
+   * Throws `PreviewError` for a service that cannot boot; a service that
+   * boots but never becomes ready is returned with `ready: false` plus the
+   * classified `error` / `errorCode` / `errorDetail` from its log.
+   */
+  async start(repoRoot, config, { mode = "worktree", repoKey = null, envSource = null } = {}) {
+    mkdirSync(this.logDir, { recursive: true });
+    const services = await this.assignPorts(repoRoot, config, { mode, repoKey, envSource });
+    const out = [];
+    for (const svc of services) out.push(await this.bootService(svc.name));
+    const previewName = this.previewNames?.get(repoRoot) ?? null;
     const previewSvc = previewName ? out.find((s) => s.name === previewName) : null;
     const lan = lanAddress();
     return {
       services: out,
-      preview: previewSvc ? { name: previewSvc.name, url: previewSvc.url, lanUrl: lan ? `http://${lan}:${previewSvc.port}` : null, adopted: !!previewSvc.adopted } : null,
+      preview: previewSvc
+        ? { name: previewSvc.name, url: previewSvc.url, lanUrl: lan ? `${previewSvc.protocol}://${lan}:${previewSvc.port}` : null, adopted: !!previewSvc.adopted, kind: previewSvc.kind, protocol: previewSvc.protocol, ...(previewSvc.adopted && previewSvc.cwd ? { adoptedCwd: previewSvc.cwd } : {}) }
+        : null,
     };
   }
 
+  describeService(name) {
+    const m = this.meta.get(name);
+    const port = this.ports[name];
+    const url = `${m?.protocol ?? "http"}://localhost:${port}`;
+    const adopted = this.adopted.has(name);
+    return { name, port, url, logPath: adopted ? null : m?.logPath ?? null, adopted, ready: !!m?.ready, kind: m?.kind ?? "web", protocol: m?.protocol ?? "http", repoKey: m?.repoKey ?? null, repoRoot: m?.repoRoot ?? null, cwd: (adopted ? this.adoptedCwd.get(name) : null) ?? m?.cwd ?? null };
+  }
+
+  /** Boot one registered service (adopted / already running → described only). */
+  async bootService(name) {
+    const m = this.meta.get(name);
+    if (!m) throw new PreviewError(`Unknown service ${name}`, { code: "other", service: name });
+    const { svc, repoRoot, repoKey, cwd, logPath } = m;
+    const port = this.ports[name];
+    if (this.adopted.has(name)) {
+      m.ready = true;
+      if (!m.kindProbed) await this.probeKind(m, port);
+      this.onStatus(`Using your running ${name} on :${port}`);
+      return this.describeService(name);
+    }
+    if (this.processes.has(name)) return this.describeService(name);
+    if (!existsSync(cwd)) {
+      throw new PreviewError(`${name}: the service directory ${svc.cwd} does not exist in ${repoRoot}.`, { code: "no_dev_config", repo: repoKey, service: name, detail: { cwd } });
+    }
+    // Gitignored env files never reach a fresh worktree — copy the primary
+    // checkout's PER SERVICE CWD (a Server/ under a monorepo root has its own
+    // .env). Never overwrites existing files.
+    if (m.envSource && resolve(m.envSource) !== resolve(repoRoot)) {
+      const copied = copyPrimaryEnvFiles(resolve(m.envSource, svc.cwd), cwd);
+      if (copied.length) this.log("info", "preview.env.copied", { cwd, copied });
+    }
+    // Declared infrastructure (Mongo, Redis, …) is checked BEFORE the boot:
+    // instant and precise, instead of a 90 s readiness timeout ending in a
+    // log-tail guess.
+    for (const req of svc.requires || []) {
+      if (!(await isPortListening(req.port))) {
+        throw new PreviewError(`${name} needs ${req.name} on :${req.port}, but nothing is listening there. Start it, then retry.`, {
+          code: "dependency_missing",
+          repo: repoKey,
+          service: name,
+          detail: { dependency: req.name, port: req.port },
+        });
+      }
+    }
+    const env = {
+      ...process.env,
+      PORT: String(port),
+      ...Object.fromEntries(Object.entries(svc.env).map(([k, v]) => [k, substitutePorts(v, this.ports)])),
+      KAI_SESSION_ID: String(this.sessionId),
+      BROWSER: "none",
+    };
+    const fd = openSync(logPath, "a");
+    // Fresh worktrees have no node_modules — running the dev command
+    // straight into `command not found` was the #1 preview failure. The
+    // install is authoritative: when it fails, the dev command never runs.
+    await this.ensureDeps(cwd, { env, fd, logPath, service: name, repoKey });
+    const cmd = stripOpenFlag(substitutePorts(svc.run, this.ports));
+    const child = spawnShell(cmd, { cwd, env, fd, detached: true });
+    m.ready = false;
+    child.on("exit", (code) => {
+      this.processes.delete(name);
+      this.onProcess(name, child.pid, "remove");
+      this.log("info", "service.exit", { name, code });
+      const deliberate = this.stopping.has(name);
+      this.stopping.delete(name);
+      if (deliberate) return;
+      if (code && code !== 0) this.onStatus(`${name} exited with code ${code} — see ${logPath}`);
+      if (!m.ready) return; // boot failure — reported by the boot path below
+      // A service that was READY died on its own: the preview is broken now,
+      // not at the next click. The daemon posts service_crashed.
+      m.ready = false;
+      const classified = classifyLogTail(this.readLog(logPath));
+      void Promise.resolve(
+        this.onServiceExit({
+          name,
+          code,
+          repoRoot,
+          repoKey,
+          logPath,
+          error: classified?.line ?? `${name} exited with code ${code ?? "?"}`,
+          errorCode: classified?.code ?? "service_crashed",
+          detail: classified?.detail ?? null,
+        }),
+      ).catch(() => {});
+    });
+    this.processes.set(name, child);
+    this.onProcess(name, child.pid, "add");
+    this.onStatus(`Starting ${name} (${cmd}) on :${port}`);
+    // Bail as soon as the process dies (command not found, crash on
+    // boot) instead of polling a dead port for the full timeout.
+    let ready = await Promise.race([
+      waitForReady({ port, health: svc.health, timeoutMs: svc.readyTimeoutMs, protocol: svc.protocol, onTick: (s) => this.onStatus(`Still starting ${name} (${s}s)…`) }),
+      new Promise((resolveP) => child.once("exit", () => setTimeout(() => resolveP(false), 300))),
+    ]);
+    if (ready && this.settleMs > 0) {
+      // Many dev servers open the port, then crash on their first real
+      // request (a missing env var, a DB refusing). Give them a moment and
+      // look again before calling the preview "running".
+      await new Promise((r) => setTimeout(r, this.settleMs));
+      const alive = this.processes.has(name) && (await isPortListening(port));
+      if (!alive) ready = false;
+    }
+    m.ready = ready;
+    if (!ready) {
+      const tail = this.readLog(logPath);
+      const classified = classifyLogTail(tail);
+      const envKeys = classified ? [] : missingEnvKeys(cwd, { exists: existsSync, read: (p) => readFileSync(p, "utf8"), env });
+      const errorCode = classified?.code ?? (envKeys.length ? "env_missing" : "service_crashed");
+      const error = classified?.line ?? (envKeys.length ? `${name} did not start — ${envKeys.length} key${envKeys.length === 1 ? "" : "s"} from .env.example missing: ${envKeys.join(", ")}` : logTailSummary(tail) || `${name} did not become ready within ${Math.round(svc.readyTimeoutMs / 1000)}s`);
+      this.onStatus(`${name} did not become ready — ${error} (see ${logPath})`);
+      return { ...this.describeService(name), ready: false, error, errorCode, errorDetail: classified?.detail ?? (envKeys.length ? { envKeys } : null) };
+    }
+    this.onStatus(`${name} ready on ${svc.protocol}://localhost:${port}`);
+    await this.probeKind(m, port);
+    return this.describeService(name);
+  }
+
+  /** `kind` auto-detection: the root's content-type (once per service). */
+  async probeKind(m, port) {
+    m.kindProbed = true;
+    if (m.kind) return;
+    // An HTML error page (Express' default 404) is not a UI: only a 2xx
+    // decides; otherwise the health path gets a say before we default to web.
+    const root = await fetchInsecure(`${m.protocol}://localhost:${port}/`, { timeoutMs: 3000 });
+    if (root && root.status < 300) {
+      m.kind = kindFromContentType(root.contentType);
+      return;
+    }
+    const health = m.svc?.health;
+    if (health) {
+      const res = await fetchInsecure(`${m.protocol}://localhost:${port}${health.startsWith("/") ? health : `/${health}`}`, { timeoutMs: 3000 });
+      if (res && res.status < 300) {
+        m.kind = kindFromContentType(res.contentType);
+        return;
+      }
+    }
+    // A UI always serves something at "/"; a 404 there (whatever its
+    // content-type — Express renders HTML) is the signature of an API.
+    if (root && root.status === 404) {
+      m.kind = "api";
+      return;
+    }
+    m.kind = root && root.contentType && !String(root.contentType).toLowerCase().includes("text/html") ? "api" : "web";
+  }
+
+  readLog(logPath) {
+    try {
+      return readFileSync(logPath, "utf8").slice(-20_000);
+    } catch {
+      return "";
+    }
+  }
+
+  /** The resolver's preferred port when it is valid and free; null otherwise. */
+  async stablePort(repoKey, service) {
+    if (!this.preferredPort || !repoKey) return null;
+    let port = null;
+    try {
+      port = await this.preferredPort({ repoKey, service });
+    } catch {
+      return null;
+    }
+    if (!Number.isInteger(port) || port < 1024 || port > 65535) return null;
+    if (Object.values(this.ports).includes(port)) return null;
+    return (await isPortListening(port)) ? null : port;
+  }
+
+  /** `[{ name, url, repoKey, kind, protocol, openapi, repoRoot, adopted }]` for every service this runner owns — the login flows' origin table. */
+  describeServices() {
+    return Object.entries(this.ports).map(([name, port]) => {
+      const m = this.meta.get(name);
+      return { name, url: `${m?.protocol ?? "http"}://localhost:${port}`, repoKey: this.repoKeys.get(name) ?? null, kind: m?.kind ?? "web", protocol: m?.protocol ?? "http", openapi: m?.svc?.openapi ?? null, repoRoot: m?.repoRoot ?? null, adopted: this.adopted.has(name), cwd: m?.cwd ?? null };
+    });
+  }
+
+  /** Every service of a repo root (names). */
+  servicesOf(repoRoot) {
+    return (this.registered.get(repoRoot) || []).map((s) => s.name);
+  }
+
+  /** Any service on https? → the browser needs `--ignore-https-errors`. */
+  usesHttps() {
+    return [...this.meta.values()].some((m) => m.protocol === "https");
+  }
+
   /**
    * Install JS dependencies when the service dir has a package.json but
-   * no node_modules (fresh worktree). Package manager by lockfile; up
-   * to 5 minutes; output goes to the service log. No-op otherwise.
+   * no node_modules (fresh worktree) or the lockfile changed since our
+   * last install (marker `node_modules/.kai-installed`). Package manager
+   * by lockfile, preflighted (`command -v`); up to 10 minutes; output to
+   * the service log. Authoritative: a failed install throws
+   * `PreviewError(deps_failed)` and the dev command never runs.
    */
-  async ensureDeps(cwd, { env, fd, logPath }) {
-    if (!existsSync(join(cwd, "package.json")) || existsSync(join(cwd, "node_modules"))) return;
-    const pm = existsSync(join(cwd, "pnpm-lock.yaml")) ? "pnpm" : existsSync(join(cwd, "yarn.lock")) ? "yarn" : "npm";
-    const installCmd = `${pm} install`;
+  async ensureDeps(cwd, { env, fd, logPath, service = null, repoKey = null }) {
+    if (!existsSync(join(cwd, "package.json"))) return { installed: false };
+    const marker = join(cwd, "node_modules", DEPS_MARKER);
+    const hash = lockfileHash(cwd);
+    if (existsSync(join(cwd, "node_modules"))) {
+      // The user's own install (no marker) is theirs — never re-run it under
+      // them. Our own install is redone only when the lockfile changed.
+      if (!existsSync(marker)) return { installed: false };
+      let previous = "";
+      try {
+        previous = readFileSync(marker, "utf8").trim();
+      } catch {
+        /* unreadable marker → reinstall */
+      }
+      if (previous === hash) return { installed: false };
+    }
+    const pm = existsSync(join(cwd, "pnpm-lock.yaml")) ? "pnpm" : existsSync(join(cwd, "yarn.lock")) ? "yarn" : existsSync(join(cwd, "bun.lockb")) || existsSync(join(cwd, "bun.lock")) ? "bun" : "npm";
+    if (!(await this.commandExists(pm, env))) {
+      throw new PreviewError(`${pm} is not installed on this machine (needed to install ${service ?? basename(cwd)}'s dependencies).`, {
+        code: "deps_failed",
+        repo: repoKey,
+        service,
+        detail: { command: pm, cwd },
+      });
+    }
+    const installCmd = installCommandFor(cwd);
     this.onStatus(`Installing dependencies (${installCmd}) — first preview in this workspace…`);
     this.log("info", "service.install", { cwd, pm });
+    const startedAt = Date.now();
+    const tick = setInterval(() => this.onStatus(`Still installing dependencies (${Math.round((Date.now() - startedAt) / 1000)}s)…`), PROGRESS_TICK_MS);
+    tick.unref?.();
     const code = await new Promise((resolveP) => {
-      const child =
-        process.platform === "darwin"
-          ? spawn("/bin/zsh", ["-lc", installCmd], { cwd, env, stdio: ["ignore", fd, fd] })
-          : spawn(installCmd, { cwd, env, shell: true, stdio: ["ignore", fd, fd] });
+      const child = spawnShell(installCmd, { cwd, env, fd });
       const timer = setTimeout(() => {
         try {
           child.kill("SIGTERM");
         } catch {}
-        resolveP(-1);
-      }, 5 * 60_000);
+        resolveP("timeout");
+      }, DEPS_INSTALL_TIMEOUT_MS);
       child.on("exit", (c) => {
         clearTimeout(timer);
         resolveP(c ?? -1);
@@ -328,11 +770,44 @@ export class ServiceRunner {
         resolveP(-1);
       });
     });
-    if (code !== 0) this.onStatus(`${installCmd} exited with code ${code} — see ${logPath}`);
+    clearInterval(tick);
+    if (code !== 0) {
+      const classified = classifyLogTail(this.readLog(logPath));
+      const why = code === "timeout" ? `timed out after ${Math.round(DEPS_INSTALL_TIMEOUT_MS / 60_000)} minutes` : `exited with code ${code}`;
+      throw new PreviewError(`${installCmd} ${why}${classified?.line ? ` — ${classified.line}` : ""} (see ${logPath})`, {
+        code: "deps_failed",
+        repo: repoKey,
+        service,
+        detail: { command: installCmd, cwd, ...(classified?.detail || {}) },
+      });
+    }
+    try {
+      mkdirSync(join(cwd, "node_modules"), { recursive: true });
+      writeFileSync(marker, `${hash}\n`);
+    } catch {
+      /* marker is an optimisation */
+    }
+    return { installed: true };
   }
 
-  stopAll() {
-    for (const [name, child] of this.processes) {
+  /** `command -v <pm>` through the same shell the services use (login shell on macOS). */
+  commandExists(cmd, env) {
+    return new Promise((resolveP) => {
+      const probe = process.platform === "win32" ? spawn("where", [cmd], { env, stdio: "ignore", windowsHide: true }) : process.platform === "darwin" ? spawn("/bin/zsh", ["-lc", `command -v ${cmd}`], { env, stdio: "ignore" }) : spawn("sh", ["-c", `command -v ${cmd}`], { env, stdio: "ignore" });
+      probe.on("exit", (c) => resolveP(c === 0));
+      probe.on("error", () => resolveP(false));
+    });
+  }
+
+  /** Kill one service's process tree; resolves when the process is gone (bounded). */
+  async stopService(name, { timeoutMs = 5_000 } = {}) {
+    const child = this.processes.get(name);
+    if (!child) return;
+    this.stopping.add(name);
+    const gone = new Promise((r) => child.once("exit", r));
+    if (process.platform === "win32") {
+      spawn("taskkill", ["/PID", String(child.pid), "/T", "/F"], { stdio: "ignore", windowsHide: true }).on("error", () => {});
+    } else {
       try {
         process.kill(-child.pid, "SIGTERM");
       } catch {
@@ -342,9 +817,60 @@ export class ServiceRunner {
           /* gone */
         }
       }
+    }
+    this.log("info", "service.stop", { name });
+    await Promise.race([gone, new Promise((r) => setTimeout(r, timeoutMs))]);
+    if (this.processes.has(name)) {
+      try {
+        process.platform === "win32" ? child.kill() : process.kill(-child.pid, "SIGKILL");
+      } catch {
+        /* gone */
+      }
+    }
+  }
+
+  stopAll() {
+    for (const [name, child] of this.processes) {
+      this.stopping.add(name);
+      if (process.platform === "win32") {
+        spawn("taskkill", ["/PID", String(child.pid), "/T", "/F"], { stdio: "ignore", windowsHide: true }).on("error", () => {});
+      } else {
+        try {
+          process.kill(-child.pid, "SIGTERM");
+        } catch {
+          try {
+            child.kill("SIGTERM");
+          } catch {
+            /* gone */
+          }
+        }
+      }
       this.log("info", "service.stop", { name });
     }
     this.processes.clear();
+    for (const m of this.meta.values()) m.ready = false;
+  }
+
+  /**
+   * Restart the services of one repo root on their SAME ports (the fix
+   * changed code a `reload: restart` service does not hot-reload). Adopted
+   * services are the user's own dev server and are never touched — they
+   * come back as `{ adopted: true, restarted: false }`. Returns the
+   * re-described services.
+   */
+  async restart(repoRoot, { only = null } = {}) {
+    const names = this.servicesOf(repoRoot).filter((n) => !only || only.includes(n));
+    const out = [];
+    for (const name of names) {
+      if (this.adopted.has(name)) {
+        out.push({ ...this.describeService(name), restarted: false });
+        continue;
+      }
+      await this.stopService(name);
+      const started = await this.bootService(name);
+      out.push({ ...started, restarted: true });
+    }
+    return out;
   }
 
   /** Prompt section telling the agent what is running + how to verify. */
@@ -361,12 +887,157 @@ export class ServiceRunner {
   }
 }
 
-/** The Playwright MCP server registration for the turn (stdio, headless). */
-export function previewMcpServer(runnerDir) {
-  return {
-    id: "gleap_preview",
-    name: "gleap_preview",
-    command: process.execPath,
-    args: [join(runnerDir, "..", "node_modules", "@playwright", "mcp", "cli.js"), "--headless", "--isolated"],
-  };
+/** Where the bundled Playwright MCP + its Playwright live (npm may hoist or nest them). */
+export function playwrightPaths(runnerDir) {
+  const mcpCli = join(runnerDir, "..", "node_modules", "@playwright", "mcp", "cli.js");
+  let playwrightCli = null;
+  let bundledChromium = null;
+  try {
+    // `playwright` exports no `./cli.js` subpath — resolve the (exported)
+    // package.json and take cli.js from the same directory.
+    playwrightCli = join(dirname(createRequire(mcpCli).resolve("playwright/package.json")), "cli.js");
+    // playwright-core's public `executablePath()` is where the bundled
+    // build lives whether or not it is installed — the presence check
+    // for ensurePreviewBrowser.
+    bundledChromium = createRequire(playwrightCli)("playwright-core").chromium.executablePath();
+  } catch {
+    /* MCP not installed (tests, broken install) — callers treat null as "unknown" */
+  }
+  return { mcpCli, playwrightCli, bundledChromium };
+}
+
+/**
+ * Pure: is a system Chrome available for `--browser chrome`? Playwright's
+ * `chrome` channel launches the user's own installation — no download,
+ * and the pages look like what the developer sees. Injected `exists` /
+ * `env` keep this testable per platform.
+ */
+export function resolvePreviewBrowser({ platform = process.platform, exists = existsSync, env = process.env } = {}) {
+  // Path flavour follows the TARGET platform, so the table is testable
+  // for every OS from any OS.
+  const p = platform === "win32" ? win32Path : posixPath;
+  const candidates = [];
+  if (platform === "darwin") {
+    candidates.push("/Applications/Google Chrome.app", p.join(env.HOME || homedir(), "Applications", "Google Chrome.app"));
+  } else if (platform === "win32") {
+    for (const root of [env.ProgramFiles, env["ProgramFiles(x86)"], env.LOCALAPPDATA]) {
+      if (root) candidates.push(p.join(root, "Google", "Chrome", "Application", "chrome.exe"));
+    }
+  } else {
+    for (const dir of String(env.PATH || "").split(p.delimiter).filter(Boolean)) {
+      candidates.push(p.join(dir, "google-chrome"), p.join(dir, "google-chrome-stable"));
+    }
+  }
+  return candidates.some((p) => exists(p)) ? "chrome" : null;
+}
+
+/** The exact command a user runs by hand when the automatic browser install fails (shown on the `no_browser` card). */
+export function browserInstallCommand({ playwrightCli, withDeps = false } = {}) {
+  const cli = playwrightCli || "node_modules/@playwright/mcp/node_modules/playwright/cli.js";
+  return `${withDeps ? "sudo " : ""}node ${cli} install${withDeps ? " --with-deps" : ""} chromium`;
+}
+
+/**
+ * Make sure SOME browser can launch before a verify turn: system Chrome
+ * wins; otherwise the bundled Chromium must be in Playwright's cache —
+ * and nothing installs it today (the `@playwright/mcp` dependency ships
+ * no browser), so download it once (`playwright install chromium`, 5-min
+ * cap, output to the daemon log). On Linux with passwordless sudo the
+ * install adds `--with-deps` (the shared libraries Chromium needs).
+ * Resolves `{ browser: "chrome" | "chromium" | null, installed, ok,
+ * error?, command? }` — `command` is what to run by hand when it failed.
+ * Never throws. `install` / `canSudo` are injectable for tests.
+ */
+export async function ensurePreviewBrowser({ runnerDir, log = () => {}, exists = existsSync, platform = process.platform, env = process.env, install, canSudo } = {}) {
+  if (resolvePreviewBrowser({ platform, exists, env })) return { browser: "chrome", installed: false, ok: true };
+  const paths = playwrightPaths(runnerDir ?? DEFAULT_RUNNER_DIR);
+  if (paths.bundledChromium && exists(paths.bundledChromium)) return { browser: "chromium", installed: false, ok: true };
+  if (!paths.playwrightCli) {
+    return { browser: null, installed: false, ok: false, error: "Playwright is not installed next to kai-bridge — reinstall @gleapai/kai-bridge.", command: "npm install -g @gleapai/kai-bridge" };
+  }
+  const withDeps = platform === "linux" && (await (canSudo ?? defaultCanSudo)());
+  const installArgs = ["install", ...(withDeps ? ["--with-deps"] : []), "chromium"];
+  const command = browserInstallCommand({ playwrightCli: paths.playwrightCli, withDeps });
+  log("info", "browser.install.start", { cli: paths.playwrightCli, withDeps });
+  const runInstall =
+    install ??
+    ((cli) =>
+      new Promise((resolveP) => {
+        const child = withDeps
+          ? spawn("sudo", ["-n", process.execPath, cli, ...installArgs], { stdio: ["ignore", "pipe", "pipe"], env: { ...process.env } })
+          : spawn(process.execPath, [cli, ...installArgs], { stdio: ["ignore", "pipe", "pipe"], env: { ...process.env } });
+        let tail = "";
+        const onData = (d) => {
+          const line = String(d).trim();
+          if (!line) return;
+          tail = `${tail}\n${line}`.slice(-2000);
+          log("info", "browser.install", { line: line.slice(0, 300) });
+        };
+        child.stdout.on("data", onData);
+        child.stderr.on("data", onData);
+        const timer = setTimeout(() => {
+          try {
+            child.kill("SIGTERM");
+          } catch {}
+          resolveP({ ok: false, error: "playwright install chromium timed out after 5 minutes" });
+        }, 5 * 60_000);
+        child.on("error", (err) => {
+          clearTimeout(timer);
+          resolveP({ ok: false, error: err.message });
+        });
+        child.on("exit", (code) => {
+          clearTimeout(timer);
+          resolveP(code === 0 ? { ok: true } : { ok: false, error: `playwright install chromium exited ${code}${tail ? ` — ${tail.trim().split("\n").at(-1)}` : ""}` });
+        });
+      }));
+  const res = await runInstall(paths.playwrightCli, { withDeps, args: installArgs });
+  log(res.ok ? "info" : "warn", "browser.install.done", { ok: res.ok, error: res.error });
+  return { browser: res.ok ? "chromium" : null, installed: res.ok, ok: !!res.ok, ...(res.ok ? {} : { error: res.error, command }) };
+}
+
+function defaultCanSudo() {
+  return new Promise((resolveP) => {
+    try {
+      const child = spawn("sudo", ["-n", "true"], { stdio: "ignore" });
+      child.on("exit", (c) => resolveP(c === 0));
+      child.on("error", () => resolveP(false));
+    } catch {
+      resolveP(false);
+    }
+  });
+}
+
+/**
+ * The Playwright MCP server registration for the turn (stdio, headless,
+ * always `--isolated`: the profile lives in memory). Verify turns add
+ * `outputDir` (recordings + screenshots land there for the host to
+ * upload), `caps` (`devtools` = video/tracing, `testing` = browser_verify_*,
+ * `storage` = browser_storage_state for the final sign-in refresh), an
+ * optional `secretsFile` (dotenv; the MCP substitutes secret NAMES typed
+ * into fields and masks the values), and — when a saved sign-in is
+ * injected — `storageStateFile` (re-read by the MCP on every new context,
+ * so it must outlive the turn) plus `allowedOrigins` (every other request
+ * is aborted: the injected cookies can only ever be sent to the preview).
+ * `ignoreHttpsErrors` for `protocol: https` dev servers (self-signed).
+ * `disabledTools` rides on the entry for the runner (Claude
+ * `disallowedTools`, Codex `disabled_tools`) — `browser_set_storage_state`
+ * is off so the agent can never load a state file of its choosing.
+ */
+export function previewMcpServer(runnerDir, { outputDir, caps, secretsFile, browser, storageStateFile, allowedOrigins, disabledTools, ignoreHttpsErrors } = {}) {
+  const args = [playwrightPaths(runnerDir).mcpCli, "--headless", "--isolated"];
+  args.push("--viewport-size", "1280x800");
+  const capList = Array.isArray(caps) ? caps : typeof caps === "string" && caps ? caps.split(",") : [];
+  if (capList.length > 0) args.push(`--caps=${capList.map((c) => String(c).trim()).filter(Boolean).join(",")}`);
+  if (outputDir) args.push("--output-dir", outputDir);
+  if (secretsFile) args.push("--secrets", secretsFile);
+  if (storageStateFile) args.push("--storage-state", storageStateFile);
+  const origins = (Array.isArray(allowedOrigins) ? allowedOrigins : []).map((o) => String(o).trim()).filter(Boolean);
+  if (origins.length > 0) args.push("--allowed-origins", [...new Set(origins)].join(";"));
+  if (ignoreHttpsErrors) args.push("--ignore-https-errors");
+  const channel = browser === undefined ? resolvePreviewBrowser() : browser;
+  if (channel) args.push("--browser", channel);
+  const entry = { id: "gleap_preview", name: "gleap_preview", command: process.execPath, args };
+  const disabled = (Array.isArray(disabledTools) ? disabledTools : []).map((t) => String(t).trim()).filter(Boolean);
+  if (disabled.length > 0) entry.disabledTools = disabled;
+  return entry;
 }