@gleapai/kai-bridge 0.9.1 → 0.10.0

package/src/preview.mjs

@@ -9,10 +9,7 @@ import { previewPorts } from './preview-ports.mjs';
 //     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>}`
@@ -36,6 +33,8 @@ import { previewPorts } from './preview-ports.mjs';
 import { spawn } from "node:child_process";
 import { createHash } from "node:crypto";
 import { createServer, connect } from "node:net";
+
+import { Gateway } from "./gateway.mjs";
 import { request as httpsRequest } from "node:https";
 import { existsSync, mkdirSync, openSync, readFileSync, writeFileSync } from "node:fs";
 import { createRequire } from "node:module";
@@ -62,11 +61,36 @@ 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_TOP_KEYS = new Set(["services", "preview", "companions", "external", "reverseCompanions"]);
 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"]);
+/** Stable preview ports: hash(repoKey + service) into this window. */
+export const STABLE_PORT_MIN = 43000;
+export const STABLE_PORT_SPAN = 1000;
+
+const EMPTY_CONFIG = () => ({ services: {}, preview: null, companions: [], reverseCompanions: true, external: [], unknownKeys: [], error: null });
+
+/** Deterministic port in [43000, 43999] for a repo's service — the same across sessions. */
+export function preferredStablePort(repoKey, serviceName) {
+  const h = createHash("sha1").update(`${String(repoKey || "").toLowerCase()} ${String(serviceName || "")}`).digest();
+  return STABLE_PORT_MIN + (h.readUInt32BE(0) % STABLE_PORT_SPAN);
+}
+
+/** The `playwright` the bundled MCP ships — `null` when it is not installed. */
+export function loadPlaywright(runnerDir) {
+  try {
+    const req = createRequire(join(runnerDir, "..", "node_modules", "@playwright", "mcp", "package.json"));
+    return req("playwright");
+  } catch {
+    return null;
+  }
+}
 
-const EMPTY_CONFIG = () => ({ services: {}, preview: null, companions: [], auth: { storageState: null, loginCheck: null, apiToken: null }, verify: { readOnly: null, endpoints: [], loginVia: null }, external: [], unknownKeys: [], error: null });
+/** Launch options for the warm-up browser: `chrome` when the user's Chrome exists (no download), else the bundled build. */
+export function launchOptionsFor({ headless = true, browser = resolvePreviewBrowser() } = {}) {
+  const opts = { headless: !!headless };
+  if (browser) opts.channel = browser;
+  return opts;
+}
 
 /**
  * Wrap a service/install command so it runs with the daemon's own node
@@ -152,37 +176,6 @@ export function normalizeDevConfig(raw) {
     };
   }
   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.
@@ -193,15 +186,9 @@ export function normalizeDevConfig(raw) {
     if (!repo) continue;
     companions.push({ repo: repo.toLowerCase().trim(), optional: !!(entry && typeof entry === "object" && entry.optional) });
   }
-  // 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 };
+  // `reverseCompanions: false` keeps this repo out of previews of the repos it
+  // names as companions (a frontend normally boots alongside its API's ticket).
+  return { services, preview, companions, reverseCompanions: raw?.reverseCompanions !== false, external: normalizeOriginList(raw?.external), unknownKeys, error: null };
 }
 
 /** The reload mode a service actually uses (`hot` unless declared / api). */
@@ -304,14 +291,25 @@ export function lanAddress() {
   return null;
 }
 
-/** `${port:api}` → assigned port of service `api`. */
+/**
+ * `${port:api}` → assigned port of service `api`, `${url:api}` → its URL.
+ * Compatibility for configs written before public links: a browser-facing
+ * `http://localhost:${port:api}` becomes the public URL when `api` has one
+ * (`127.0.0.1:${port:…}` is the server-to-server form and stays local).
+ */
 export function substitutePorts(value, ports, urls = {}) {
-  return String(value).replace(/\$\{port:([\w-]+)\}/g, (_, name) => String(ports[name] ?? "")).replace(/\$\{url:([\w-]+)\}/g, (_, name) => {
-    if (!urls[name]) throw new Error(`Service URL is not available for ${name}.`);
-    return urls[name];
-  });
+  return String(value)
+    .replace(/https?:\/\/localhost:\$\{port:([\w-]+)\}/g, (match, name) => (/^https:\/\//.test(urls[name] || "") ? urls[name] : match))
+    .replace(/\$\{port:([\w-]+)\}/g, (_, name) => String(ports[name] ?? ""))
+    .replace(/\$\{url:([\w-]+)\}/g, (_, name) => {
+      if (!urls[name]) throw new Error(`Service URL is not available for ${name}.`);
+      return urls[name];
+    });
 }
 
+/** Does a service bake another service's address into its env or command (and so must restart when addresses change)? */
+export const bakesServiceUrl = (svc) => /\$\{url:|https?:\/\/localhost:\$\{port:/.test(`${svc?.run ?? ""} ${Object.values(svc?.env || {}).join(" ")}`);
+
 /** GET `url` accepting self-signed certificates (dev https); resolves `{ status, contentType }` or null. */
 export function fetchInsecure(url, { timeoutMs = 2_000 } = {}) {
   return new Promise((resolveP) => {
@@ -351,11 +349,13 @@ export function kindFromContentType(contentType) {
   return ct.includes("text/html") ? "web" : "api";
 }
 
-async function waitForReady({ port, health, timeoutMs, protocol = "http", onTick = () => {}, tickMs = PROGRESS_TICK_MS }) {
+async function waitForReady({ port, health, timeoutMs, protocol = "http", onTick = () => {}, tickMs = PROGRESS_TICK_MS, isCancelled = () => false }) {
   const deadline = Date.now() + timeoutMs;
   const startedAt = Date.now();
   let nextTick = startedAt + tickMs;
   while (Date.now() < deadline) {
+    // The process is gone — stop polling (and ticking "Still starting…") for the full timeout.
+    if (isCancelled()) return false;
     if (health) {
       // `localhost`, not 127.0.0.1 — the server may be IPv6-only (see
       // isPortListening); Node's fetch tries both families.
@@ -405,6 +405,24 @@ function spawnShell(cmd, { cwd, env, fd, detached = false }) {
  * 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).
  */
+/** End a dev server's whole process group (Windows: its tree); never throws. */
+export function killTree(pid, signal = "SIGTERM") {
+  if (!Number.isInteger(pid)) return;
+  if (process.platform === "win32") {
+    spawn("taskkill", ["/PID", String(pid), "/T", "/F"], { stdio: "ignore", windowsHide: true }).on("error", () => {});
+    return;
+  }
+  try {
+    process.kill(-pid, signal);
+  } catch {
+    try {
+      process.kill(pid, signal);
+    } catch {
+      /* gone */
+    }
+  }
+}
+
 export class ServiceRunner {
   /**
    * `preferredPort({ repoKey, service })` → a port to TRY before falling
@@ -416,8 +434,14 @@ export class ServiceRunner {
    * fires when a service that had become ready dies on its own;
    * `onProcess(name, pid, "add" | "remove", { port })` lets the daemon persist pids.
    */
-  constructor({ kaiHome, sessionId, log = () => {}, onStatus = () => {}, preferredPort = null, describeListener = null, settleMs = DEFAULT_SETTLE_MS, onServiceExit = () => {}, onProcess = () => {}, home = homedir() } = {}) {
+  constructor({ kaiHome, sessionId, log = () => {}, onStatus = () => {}, preferredPort = null, describeListener = null, settleMs = DEFAULT_SETTLE_MS, onServiceExit = () => {}, onProcess = () => {}, home = homedir(), gateway = true } = {}) {
     if (settleMs === DEFAULT_SETTLE_MS) settleMs = defaultSettleMs();
+    // Sign-in gateway (gateway.mjs) in front of every bridge-started http
+    // service: the public port is the gateway's, the app runs on `appPort`.
+    this.gatewayEnabled = gateway !== false;
+    this.gateways = new Map(); // service name → Gateway
+    this.resumedPids = new Map(); // service name → pid of a dev server re-adopted from a previous daemon life
+    this.warmed = false;
     this.kaiHome = kaiHome;
     this.sessionId = sessionId;
     this.serviceUrls = {};
@@ -448,7 +472,7 @@ export class ServiceRunner {
    * Idempotent per repo root. Throws `PreviewError` (`port_busy`) when a
    * declared port is held by a process that is not this repo's.
    */
-  async assignPorts(repoRoot, config, { mode = "worktree", repoKey = null, envSource = null } = {}) {
+  async assignPorts(repoRoot, config, { mode = "worktree", repoKey = null, envSource = null, publicHosts = 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
@@ -477,6 +501,7 @@ export class ServiceRunner {
       const declared = svc.port;
       const owner = `${this.sessionId}/${repoRoot}/${svc.name}`;
       const pinned = !!declared && (mode === 'local' || new RegExp(`(^|[^0-9])${declared}([^0-9]|$)`).test(`${svc.run} ${Object.values(svc.env).join(' ')}`));
+      this.meta.get(svc.name).pinned = pinned;
       if (declared && !(await isPortListening(declared))) {
         this.ports[svc.name] = await previewPorts.reserve(owner, declared, pinned, isPortListening);
         continue;
@@ -509,8 +534,13 @@ export class ServiceRunner {
       const preferred = (declared ? await findFreePortNear(declared) : await this.stablePort(repoKey, svc.name)) ?? (await getFreePort());
       this.ports[svc.name] = await previewPorts.reserve(owner, preferred, false, isPortListening);
     }
+    // Public mode: `${url:x}` resolves to the service's public address (the
+    // browser bundle bakes it in), `${port:x}` stays the local port.
+    this.publicHosts ??= {};
     for (const svc of services) {
-      this.serviceUrls[svc.name] = `${svc.protocol || 'http'}://localhost:${this.ports[svc.name]}`;
+      const hostname = publicHosts?.[svc.name] ?? null;
+      if (hostname) this.publicHosts[svc.name] = hostname;
+      this.serviceUrls[svc.name] = hostname ? `https://${hostname}` : `${svc.protocol || 'http'}://localhost:${this.ports[svc.name]}`;
     }
     this.registered.set(repoRoot, services);
     this.previewNames ??= new Map();
@@ -536,7 +566,7 @@ export class ServiceRunner {
     return {
       services: out,
       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 } : {}) }
+        ? { name: previewSvc.name, url: previewSvc.url, lanUrl: lan ? `${previewSvc.protocol}://${lan}:${previewSvc.port}` : null, ...(previewSvc.publicUrl ? { publicUrl: previewSvc.publicUrl } : {}), adopted: !!previewSvc.adopted, kind: previewSvc.kind, protocol: previewSvc.protocol, ...(previewSvc.adopted && previewSvc.cwd ? { adoptedCwd: previewSvc.cwd } : {}) }
         : null,
     };
   }
@@ -546,7 +576,25 @@ export class ServiceRunner {
     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 };
+    const hostname = this.publicHosts?.[name] ?? null;
+    return { name, port, url, ...(hostname ? { publicUrl: `https://${hostname}` } : {}), 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, fronted: this.gateways.has(name), appPort: m?.appPort ?? null };
+  }
+
+  /** Can a gateway front this service? Not adopted, not pinned to its port, plain http, and switched on. */
+  canFront(name) {
+    const m = this.meta.get(name);
+    return !!m && this.gatewayEnabled && !this.adopted.has(name) && !m.pinned && m.mode !== "local" && (m.protocol ?? "http") === "http";
+  }
+
+  gatewayFor(name) {
+    return this.gateways.get(name) ?? null;
+  }
+
+  async closeGateway(name) {
+    const gw = this.gateways.get(name);
+    if (!gw) return;
+    this.gateways.delete(name);
+    await gw.close().catch(() => {});
   }
 
   /** Boot one registered service (adopted / already running → described only). */
@@ -561,7 +609,7 @@ export class ServiceRunner {
       this.onStatus(`Using your running ${name} on :${port}`);
       return this.describeService(name);
     }
-    if (this.processes.has(name)) return this.describeService(name);
+    if (this.processes.has(name) || this.resumedPids.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 } });
     }
@@ -585,9 +633,25 @@ export class ServiceRunner {
         });
       }
     }
+    // Gateway first, so the public port answers ("starting…") while the app
+    // boots and every later request — the user's browser, the agent's
+    // browser tools — reaches the app through it.
+    let appPort = port;
+    if (this.canFront(name)) {
+      await this.closeGateway(name);
+      appPort = await getFreePort();
+      const gw = new Gateway({ listenPort: port, upstreamPort: appPort, upstreamProtocol: svc.protocol, name, log: this.log });
+      try {
+        await gw.listen();
+      } catch (err) {
+        throw new PreviewError(`${name}: could not open the preview port ${port} for the gateway (${err?.message || err}).`, { code: "port_busy", repo: repoKey, service: name, detail: { port } });
+      }
+      this.gateways.set(name, gw);
+    }
+    m.appPort = appPort === port ? null : appPort;
     const env = {
       ...process.env,
-      PORT: String(port),
+      PORT: String(appPort),
       ...Object.fromEntries(Object.entries(svc.env).map(([k, v]) => [k, substitutePorts(v, this.ports, this.serviceUrls)])),
       KAI_SESSION_ID: String(this.sessionId),
       BROWSER: "none",
@@ -600,6 +664,7 @@ export class ServiceRunner {
     const cmd = stripOpenFlag(substitutePorts(svc.run, this.ports, this.serviceUrls));
     const child = spawnShell(cmd, { cwd, env, fd, detached: true });
     m.ready = false;
+    let stoppedByUs = false;
     child.on("exit", (code) => {
       // An old shell can exit after a replacement has been admitted.
       if (this.processes.get(name) !== child) return;
@@ -608,6 +673,7 @@ export class ServiceRunner {
       this.log("info", "service.exit", { name, code });
       const deliberate = this.stopping.has(name);
       this.stopping.delete(name);
+      stoppedByUs = deliberate;
       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
@@ -634,7 +700,7 @@ export class ServiceRunner {
     // 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)…`) }),
+      waitForReady({ port: appPort, health: svc.health, timeoutMs: svc.readyTimeoutMs, protocol: svc.protocol, onTick: (s) => this.onStatus(`Still starting ${name} (${s}s)…`), isCancelled: () => this.processes.get(name) !== child }),
       new Promise((resolveP) => child.once("exit", () => setTimeout(() => resolveP(false), 300))),
     ]);
     if (ready && this.settleMs > 0) {
@@ -642,19 +708,24 @@ export class ServiceRunner {
       // 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));
+      const alive = this.processes.has(name) && (await isPortListening(appPort));
       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 });
+      // The `.env.example` guess only when it can be the cause: not for a
+      // service the bridge itself stopped mid-boot, and not for one that
+      // already came up with this very env earlier in this preview (a
+      // dashboard with 25 optional keys missing boots fine — 2026-09-21).
+      const envKeys = classified || stoppedByUs || m.everReady ? [] : 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`);
+      const error = classified?.line ?? (envKeys.length ? `${name} did not start — ${envKeys.length} key${envKeys.length === 1 ? "" : "s"} from .env.example missing: ${envKeys.join(", ")}` : (stoppedByUs ? `${name} was stopped while it was starting` : 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) };
     }
+    m.everReady = true;
     this.onStatus(`${name} ready on ${svc.protocol}://localhost:${port}`);
     await this.probeKind(m, port);
     return this.describeService(name);
@@ -710,7 +781,7 @@ export class ServiceRunner {
     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. */
+  /** `[{ name, url, repoKey, kind, protocol, openapi, repoRoot, adopted }]` for every service this runner owns. */
   describeServices() {
     return Object.entries(this.ports).map(([name, port]) => {
       const m = this.meta.get(name);
@@ -723,11 +794,6 @@ export class ServiceRunner {
     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) or the lockfile changed since our
@@ -815,10 +881,11 @@ export class ServiceRunner {
 
   /** Kill one service's process tree; resolves when the process is gone (bounded). */
   async stopService(name, { timeoutMs = 5_000 } = {}) {
+    await this.closeGateway(name);
     const child = this.processes.get(name);
-    if (!child) return;
+    if (!child) return this.stopResumed(name, { timeoutMs });
     this.stopping.add(name);
-    const port = this.ports[name];
+    const port = this.meta.get(name)?.appPort ?? this.ports[name];
     let timer;
     const gone = child.exitCode !== null || child.signalCode !== null
       ? Promise.resolve()
@@ -856,10 +923,114 @@ export class ServiceRunner {
     const forceDeadline = Date.now() + 1000;
     while (port && await isPortListening(port) && Date.now() < forceDeadline) await new Promise(r => setTimeout(r, 50));
     if (port && await isPortListening(port)) throw new PreviewError(`${name} did not release port ${port}; retry after checking the service.`, { code: 'port_busy', service: name });
+    // The stop may have won on the 5 s timer, before the exit handler ran:
+    // leave nothing behind that lets the next boot mistake it for running.
+    if (this.processes.get(name) === child) {
+      this.processes.delete(name);
+      this.onProcess(name, child.pid, "remove");
+    }
+    this.stopping.delete(name);
+    const m = this.meta.get(name);
+    if (m) m.ready = false;
+  }
+
+  /** End a dev server re-adopted from a previous daemon life (pid only, no ChildProcess). */
+  async stopResumed(name, { timeoutMs = 5_000 } = {}) {
+    const pid = this.resumedPids.get(name);
+    if (!pid) return;
+    this.resumedPids.delete(name);
+    const port = this.meta.get(name)?.appPort ?? this.ports[name];
+    killTree(pid, "SIGTERM");
+    this.log("info", "service.stop", { name, pid, resumed: true });
+    const deadline = Date.now() + timeoutMs;
+    while (port && (await isPortListening(port)) && Date.now() < deadline) await new Promise((r) => setTimeout(r, 50));
+    if (port && (await isPortListening(port))) killTree(pid, "SIGKILL");
+    const m = this.meta.get(name);
+    if (m) m.ready = false;
+  }
+
+  /**
+   * Let the dev servers OUTLIVE this daemon: close the in-process gateways
+   * (the next daemon re-binds the public ports) and forget the processes
+   * without ending them. `snapshot()` is what the next daemon resumes from.
+   */
+  detach() {
+    for (const gw of this.gateways.values()) void gw.close().catch(() => {});
+    this.gateways.clear();
+    for (const child of this.processes.values()) {
+      child.removeAllListeners("exit");
+      child.unref?.();
+    }
+    this.processes.clear();
+    this.resumedPids.clear();
+    previewPorts.releaseSession(this.sessionId);
+  }
+
+  /** Everything the next daemon needs to re-adopt these services (JSON-safe). */
+  snapshot() {
+    const services = [];
+    for (const [name, port] of Object.entries(this.ports)) {
+      const m = this.meta.get(name);
+      if (!m) continue;
+      const adopted = this.adopted.has(name);
+      const pid = adopted ? null : this.processes.get(name)?.pid ?? this.resumedPids.get(name) ?? null;
+      if (!adopted && !pid) continue;
+      services.push({ name, pid, port, appPort: m.appPort ?? null, protocol: m.protocol ?? "http", kind: m.kind ?? "web", repoKey: m.repoKey ?? null, repoRoot: m.repoRoot, mode: m.mode, cwd: m.cwd, logPath: m.logPath, adopted, envSource: m.envSource ?? null, svc: m.svc, previewName: m.previewName ?? null, ready: !!m.ready });
+    }
+    return { services, previewNames: [...(this.previewNames ?? new Map())], warmed: !!this.warmed };
+  }
+
+  /**
+   * Re-adopt the services of a snapshot whose processes are still alive
+   * and listening: registers them exactly as `assignPorts` + `bootService`
+   * would, re-opens the gateways on their public ports. Returns the
+   * services that could NOT be resumed (dead pid, port silent) — the
+   * caller decides whether a partial resume is acceptable.
+   */
+  async resume(snapshot, { kill = process.kill } = {}) {
+    const failed = [];
+    for (const svc of snapshot?.services ?? []) {
+      const alive = svc.adopted ? true : (() => { try { kill(svc.pid, 0); return true; } catch { return false; } })();
+      const listening = await isPortListening(svc.appPort ?? svc.port);
+      if (!alive || !listening) {
+        failed.push({ name: svc.name, pid: svc.pid, alive, listening });
+        continue;
+      }
+      this.meta.set(svc.name, { svc: svc.svc, repoRoot: svc.repoRoot, repoKey: svc.repoKey, mode: svc.mode, cwd: svc.cwd, logPath: svc.logPath, kind: svc.kind, protocol: svc.protocol, ready: true, envSource: svc.envSource, previewName: svc.previewName, appPort: svc.appPort ?? null, pinned: false, kindProbed: true });
+      this.ports[svc.name] = svc.port;
+      this.serviceUrls[svc.name] = `${svc.protocol}://localhost:${svc.port}`;
+      this.serviceRoots.set(svc.name, svc.repoRoot);
+      if (svc.repoKey) this.repoKeys.set(svc.name, svc.repoKey);
+      const list = this.registered.get(svc.repoRoot) ?? [];
+      if (!list.some((x) => x.name === svc.name)) list.push(svc.svc);
+      this.registered.set(svc.repoRoot, list);
+      if (svc.adopted) this.adopted.add(svc.name);
+      else this.resumedPids.set(svc.name, svc.pid);
+      await previewPorts.reserve(`${this.sessionId}/${svc.repoRoot}/${svc.name}`, svc.port, true, async () => false).catch(() => {});
+      if (svc.appPort && this.gatewayEnabled) {
+        const gw = new Gateway({ listenPort: svc.port, upstreamPort: svc.appPort, upstreamProtocol: svc.protocol, name: svc.name, log: this.log });
+        try {
+          await gw.listen();
+          this.gateways.set(svc.name, gw);
+        } catch (err) {
+          failed.push({ name: svc.name, pid: svc.pid, alive, listening, gateway: err?.message });
+        }
+      }
+    }
+    this.previewNames = new Map(snapshot?.previewNames ?? []);
+    this.warmed = !!snapshot?.warmed;
+    return failed;
   }
 
   stopAll() {
     previewPorts.releaseSession(this.sessionId);
+    for (const gw of this.gateways.values()) void gw.close().catch(() => {});
+    this.gateways.clear();
+    for (const [name, pid] of this.resumedPids) {
+      killTree(pid, "SIGTERM");
+      this.log("info", "service.stop", { name, pid, resumed: true });
+    }
+    this.resumedPids.clear();
     for (const [name, child] of this.processes) {
       this.stopping.add(name);
       if (process.platform === "win32") {
@@ -903,6 +1074,36 @@ export class ServiceRunner {
     return out;
   }
 
+  /**
+   * Flip a LIVE runner between local and public addresses without a full
+   * re-boot. `${url:x}` resolves to the public origin from now on (or back
+   * to localhost with `null`); only the services whose env / run command
+   * reference a `${url:…}` restart — a browser bundle bakes the origin in
+   * at boot — on their SAME ports. An API, a worker, an adopted dev server
+   * keep running. Returns the names that were restarted.
+   */
+  async setPublicHosts(publicHosts) {
+    this.publicHosts = { ...(publicHosts || {}) };
+    for (const [name, m] of this.meta) {
+      const hostname = this.publicHosts[name];
+      this.serviceUrls[name] = hostname ? `https://${hostname}` : `${m.protocol ?? "http"}://localhost:${this.ports[name]}`;
+    }
+    const restarted = [];
+    for (const [name, m] of this.meta) {
+      if (this.adopted.has(name) || !bakesServiceUrl(m.svc)) continue;
+      this.log("info", "service.readdress", { name, publicUrl: this.serviceUrls[name] });
+      await this.stopService(name);
+      const started = await this.bootService(name);
+      // Ready AND actually ours: a boot that returned early on a stale process entry is not a restart.
+      if (!started.ready || !(this.processes.has(name) || this.resumedPids.has(name))) {
+        throw new PreviewError(`${name} did not come back${started.error ? ` — ${started.error}` : ""}`, { code: started.errorCode || "service_crashed", repo: m.repoKey, service: name, detail: { ...(started.errorDetail || {}), logPath: started.logPath } });
+      }
+      restarted.push(name);
+    }
+    if (restarted.length) this.warmed = false; // a restarted dev server compiles again
+    return restarted;
+  }
+
   /** Prompt section telling the agent what is running + how to verify. */
   describeForAgent(started) {
     if (!started || started.services.length === 0) return "";
@@ -968,7 +1169,7 @@ export function browserInstallCommand({ playwrightCli, withDeps = false } = {})
 }
 
 /**
- * Make sure SOME browser can launch before a verify turn: system Chrome
+ * Make sure SOME browser can launch for the preview (warm-up, browser MCP): 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
@@ -1038,36 +1239,25 @@ function defaultCanSudo() {
 }
 
 /**
- * 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.
+ * The Playwright MCP server registration for a coding turn with a live
+ * preview (stdio, headless, always `--isolated`: the profile lives in
+ * memory and is thrown away with the turn).
  */
-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");
+/** Playwright MCP per-call ceilings (see the args below). */
+export const MCP_NAVIGATION_TIMEOUT_MS = 240_000;
+export const MCP_ACTION_TIMEOUT_MS = 45_000;
+
+export function previewMcpServer(runnerDir, { browser } = {}) {
+  const args = [playwrightPaths(runnerDir).mcpCli, "--headless", "--isolated", "--viewport-size", "1280x800"];
+  // A dev build of a big app (thousands of unbundled modules, measured
+  // 2026-09-15 on the Gleap dashboard: DOMContentLoaded 50-90 s in a fresh
+  // profile) blows through the MCP's defaults — 60 s per navigation and 5 s
+  // per action (that 5 s is also the screenshot ceiling: "waiting for fonts
+  // to load"). The agent then burns its run on timeouts instead of
+  // testing. Give both room; a fast app never notices.
+  args.push("--timeout-navigation", String(MCP_NAVIGATION_TIMEOUT_MS));
+  args.push("--timeout-action", String(MCP_ACTION_TIMEOUT_MS));
   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;
+  return { id: "gleap_preview", name: "gleap_preview", command: process.execPath, args };
 }

package/src/service.mjs

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