@gleapai/kai-bridge 0.2.8 → 0.5.0

package/src/daemon.mjs

@@ -6,12 +6,20 @@
 // 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.turn.steer   { turnId, steer: { id, text } }   — inject into the running turn;
+//                        answered with a {type:"steer", id, outcome} turn event
 //   bridge.repo.clone   { commandId, remote, name }
 //   bridge.profile.login{ commandId, profileId }
 //   bridge.rescan       {}
+//   bridge.verify.login.start  { commandId, requestId, sessionId, repoKey, previewNeeded }  — headed sign-in window (see preview-login.mjs)
+//   bridge.verify.login.done   { commandId, requestId }                                     — "Mark done": export now
+//   bridge.verify.login.cancel { commandId, requestId }
+//   bridge.verify.evidence.retry { commandId?, turnId }  — re-upload a kept evidence dir → PUT …/verification/artifacts
+//   bridge.session.close       { sessionId }              — stops the preview, aborts the session's running turns
 
 import { spawn } from "node:child_process";
-import { appendFileSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { execFile } from "node:child_process";
 import { join, resolve as resolvePath } from "node:path";
 import { homedir, platform } from "node:os";
 
@@ -21,16 +29,54 @@ 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 { discardChanges, collectChanges, commitAndPush, copyPrimaryEnvFiles, currentBranch, materializeBinding, sessionSlug, worktreePath, ensureCommitExcludes } from "./workspace.mjs";
-import { ServiceRunner, detectDevConfig, previewMcpServer, readDevConfig } from "./preview.mjs";
+import { describeBranchChanges, discardChanges, collectChanges, commitAndPush, copyPrimaryEnvFiles, currentBranch, currentHead, materializeBinding, sessionSlug, worktreePath, ensureCommitExcludes } from "./workspace.mjs";
+import { ServiceRunner, detectDevConfig, effectiveReload, ensurePreviewBrowser, isPortListening, previewMcpServer, readDevConfig } from "./preview.mjs";
+import { ARTIFACT_MAX_AGE_MS, buildVerificationPayload, createStageHeartbeat, deriveApiAuthHeader, redactJsonlFile, sweepArtifacts, sweepOldArtifacts, unionArtifacts, writeSecretsFile } from "./verify.mjs";
+import { PreviewError, envRedactionValues, previewErrorPayload, toPreviewErrorPayload } from "./preview-errors.mjs";
+import { buildCloneCommand, collectCompanions, prefersSsh, resolveCompanionRemote } from "./companions.mjs";
+import { establishedConnections } from "./ports.mjs";
+import {
+  buildOriginMap,
+  captureLogin,
+  displayAvailable,
+  filterStorageState,
+  invertOriginMap,
+  launchOptionsFor,
+  loadPlaywright,
+  mergeFinalState,
+  normalizeOrigin,
+  parseStorageStateOutput,
+  preferredStablePort,
+  probeLogin,
+  redactDeep,
+  redactionSet,
+  rewriteStorageState,
+  storageStateIsEmpty,
+} from "./preview-login.mjs";
 import { describeHarnesses, installHarness, probeHarnessAuth } from "./harnesses.mjs";
 import { probeHarnessModels } from "./models.mjs";
-import { decideUpdate, fetchLatestVersion, installVersion, installedVersion, isNewer } from "./selfupdate.mjs";
+import { decideRestart, decideUpdate, fetchLatestVersion, installVersion, installedVersion, installedVersionOrNull, isNewer } from "./selfupdate.mjs";
 import { dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 
+const PROBE_TIMEOUT_COLD_BOOT_MS = 60_000;
+const CLONE_TIMEOUT_MS = 3 * 60_000;
+const COMPANION_MAX_DEPTH = 3;
 const RUNNER_DIR = join(dirname(fileURLToPath(import.meta.url)), "..", "runner");
 
+/** A captured landing URL moved onto the current origin map (null when its origin is not running). */
+function rewriteUrl(url, originMap) {
+  const origin = normalizeOrigin(url);
+  const to = origin && originMap ? originMap.get(origin) : null;
+  if (!to) return null;
+  try {
+    const u = new URL(String(url));
+    return `${to}${u.pathname}${u.search}${u.hash}`;
+  } catch {
+    return null;
+  }
+}
+
 /** Lock paths held by daemons in THIS process (cross-process uses the file). */
 const HELD_LOCKS = new Set();
 const REALTIME_RETRY_MS = 15_000;
@@ -112,7 +158,7 @@ export class BridgeDaemon {
     this.log = log;
     this.api = new BridgeApi({ apiBase: config.apiBase, token: config.device?.token });
     this.realtimeFactory = realtimeFactory;
-    this.running = new Map(); // turnId → AbortController
+    this.running = new Map(); // turnId → { ctrl: AbortController, control?: (obj) => boolean }
     this.services = new Map(); // sessionId → ServiceRunner (lives across turns)
     this.repoGroups = [];
     this.usageByProfile = new Map(); // profileId → plan-usage snapshot (claude only)
@@ -121,6 +167,11 @@ export class BridgeDaemon {
     this.updateAvailable = null; // newer registry version, when one exists
     this.updateError = null; // why the last self-update did not apply
     this.updating = false; // npm is replacing our files — refuse new turns
+    this.logins = new Map(); // requestId → { sessionId, repoKey, handle } — open sign-in windows (preview-login.mjs)
+    this.verifyLocks = new Map(); // `${userId}:${repoKey}` → promise chain (one probe/refresh of a sign-in at a time)
+    this.previewStatusListeners = new Map(); // sessionId → (message) => void — the booting heartbeat of a verify turn
+    this.unknownDevKeysLogged = new Set(); // "<repo>:<key>" — unknown dev.yaml keys are logged once
+    this.restartPending = false; // files on disk are a different version than the one we loaded; restart when idle
   }
 
   async scanRepos() {
@@ -146,6 +197,10 @@ export class BridgeDaemon {
       updateAvailable: this.updateAvailable || null,
       updateError: this.updateError || null,
       autoUpdate: this.config.autoUpdate !== false,
+      // Verify sign-in: can this machine open a headed Chrome window, and
+      // which sign-in requests are open right now (replayed after sleep).
+      capabilities: { display: this.displayAvailable() },
+      activeLogins: [...this.logins.keys()],
     });
   }
 
@@ -164,6 +219,12 @@ export class BridgeDaemon {
     // to report its turns. Tell the server before doing anything else,
     // so those sessions settle instead of spinning.
     await this.reportInterruptedTurns();
+    // Dev servers a killed daemon left behind would hold the declared ports
+    // (→ port_busy on the next preview) — end them; then drop evidence dirs
+    // nobody retried for two days.
+    this.killOrphanedServices();
+    const swept = sweepOldArtifacts(join(this.kaiHome, "artifacts"), { maxAgeMs: ARTIFACT_MAX_AGE_MS });
+    if (swept.length) this.log("info", "artifacts.swept", { count: swept.length });
     await this.scanRepos();
     // The first hello must not kill the daemon: the server may be
     // restarting (deploys, local nodemon) — retry with backoff instead
@@ -229,6 +290,18 @@ export class BridgeDaemon {
     if (this.stopped || this.updating) return;
     // Tests and embedded hosts (the Desktop app ships its own copy).
     if (process.env.KAI_BRIDGE_NO_SELF_UPDATE === "1") return;
+    // Someone ran `npm i -g` (or an older daemon's update landed) without
+    // restarting us: the files on disk are not the code we run. Restart
+    // into them as soon as no turn is running — BEFORE asking the registry,
+    // which needs network this check must not depend on.
+    const onDisk = installedVersionOrNull();
+    const restart = decideRestart({ loaded: VERSION, installed: onDisk, running: this.running.size + this.logins.size + this.services.size });
+    this.restartPending = restart.action === "defer";
+    if (restart.action === "restart") {
+      this.log("info", "update.restart.stale", { loaded: VERSION, installed: onDisk });
+      this.restartForUpdate();
+      return;
+    }
     let latest;
     try {
       latest = await fetchLatestVersion();
@@ -240,7 +313,10 @@ export class BridgeDaemon {
     const decision = decideUpdate({
       current: VERSION,
       latest,
-      running: this.running.size,
+      // An open sign-in window is work in flight too: replacing our files
+      // under a headed Chrome the user is typing into loses the capture —
+      // and so is a live preview someone may be looking at right now.
+      running: this.running.size + this.logins.size + this.services.size,
       autoUpdate: this.config.autoUpdate !== false,
       lastAttempt: this.config.selfUpdate?.lastAttempt ?? null,
     });
@@ -276,12 +352,12 @@ export class BridgeDaemon {
       return;
     }
     this.log("info", "update.installed", { version, restarting: true });
-    this.restartForUpdate();
+    await this.restartForUpdate();
   }
 
   /** Hand the machine to the new version: the service restarts us. */
-  restartForUpdate() {
-    this.stop();
+  async restartForUpdate() {
+    await this.stop();
     if (platform() === "win32") {
       // Task Scheduler only starts at logon — respawn ourselves instead.
       const child = spawn(process.execPath, [process.argv[1], "start"], { detached: true, stdio: "ignore", windowsHide: true });
@@ -370,6 +446,13 @@ export class BridgeDaemon {
     }
   }
 
+  /**
+   * Shut down: abort turns, stop every preview (telling the dashboard why —
+   * `stopped` / `daemon_restarted`, so the card offers Start instead of
+   * showing dead links), close sign-in windows. Resolves once the preview
+   * reports have been given a bounded chance to land (the self-update
+   * restart awaits it; sync callers may ignore the promise).
+   */
   stop() {
     this.stopped = true;
     clearInterval(this.heartbeat);
@@ -377,10 +460,19 @@ export class BridgeDaemon {
     clearInterval(this.modelsTimer);
     clearInterval(this.updateTimer);
     if (this.realtimeRetry) clearTimeout(this.realtimeRetry);
-    for (const ctrl of this.running.values()) ctrl.abort();
-    for (const runner of this.services.values()) runner.stopAll();
+    for (const entry of this.running.values()) entry.ctrl.abort();
+    const reports = [];
+    for (const [sessionId, runner] of this.services) {
+      runner.stopAll();
+      this.clearPreviewIdleTimer(sessionId);
+      reports.push(this.api.sessionPreview(sessionId, { status: "stopped", urls: [], previews: [], errorCode: "daemon_restarted", error: "kai-bridge restarted — start the preview again." }).catch(() => {}));
+    }
+    this.services.clear();
+    this.writePreviewPids([]);
+    void this.teardownLogins(() => true, "daemon stopping");
     this.realtime?.disconnect?.();
     this.releaseLock();
+    return Promise.race([Promise.allSettled(reports), new Promise((r) => setTimeout(r, 3_000).unref?.())]).then(() => undefined);
   }
 
   // ── single instance ────────────────────────────────────────────────
@@ -435,38 +527,57 @@ export class BridgeDaemon {
     return join(this.kaiHome, "state", "inflight.json");
   }
 
+  /** `[{ turnId, sessionId?, agent?, artifactsDir? }]` — pre-0.5.0 files held bare ids. */
   readInflight() {
     try {
-      return JSON.parse(readFileSync(this.inflightPath, "utf8"));
+      const raw = JSON.parse(readFileSync(this.inflightPath, "utf8"));
+      return (Array.isArray(raw) ? raw : []).map((e) => (typeof e === "string" ? { turnId: e } : e)).filter((e) => e && typeof e.turnId === "string");
     } catch {
       return [];
     }
   }
 
-  writeInflight(ids) {
+  writeInflight(entries) {
     try {
       mkdirSync(join(this.kaiHome, "state"), { recursive: true });
-      writeFileSync(this.inflightPath, JSON.stringify(ids));
+      writeFileSync(this.inflightPath, JSON.stringify(entries));
     } catch {
       /* best effort */
     }
   }
 
-  rememberInflight(turnId) {
-    this.writeInflight([...new Set([...this.readInflight(), turnId])]);
+  rememberInflight(turnId, meta = {}) {
+    const rest = this.readInflight().filter((e) => e.turnId !== turnId);
+    this.writeInflight([...rest, { turnId, ...meta }]);
   }
 
   forgetInflight(turnId) {
-    this.writeInflight(this.readInflight().filter((id) => id !== turnId));
+    this.writeInflight(this.readInflight().filter((e) => e.turnId !== turnId));
   }
 
-  /** Turns this machine was running when it was killed — report them dead. */
+  /**
+   * Turns this machine was running when it was killed — report them dead.
+   * A verify turn also gets a `blocked` report ("kai-bridge restarted
+   * mid-run") carrying whatever evidence the browser had written, so the
+   * card shows the partial recording instead of spinning.
+   */
   async reportInterruptedTurns() {
-    const ids = this.readInflight();
-    if (!ids.length) return;
+    const entries = this.readInflight();
+    if (!entries.length) return;
     this.writeInflight([]);
-    for (const turnId of ids) {
-      this.log("warn", "turn.interrupted", { turnId });
+    for (const entry of entries) {
+      const { turnId } = entry;
+      this.log("warn", "turn.interrupted", { turnId, agent: entry.agent });
+      if (entry.agent === "kai-verifier") {
+        const uploads = entry.artifactsDir ? await this.uploadSweptEvidence(turnId, entry.artifactsDir) : { uploads: [], failed: 0 };
+        await this.api
+          .turnVerification(turnId, {
+            ...buildVerificationPayload(null, uploads.uploads, { fallbackReason: "kai-bridge restarted mid-run", evidence: { failed: uploads.failed, ...(uploads.failed && entry.artifactsDir ? { kept: entry.artifactsDir } : {}) } }),
+            blockedCode: "other",
+          })
+          .catch((err) => this.log("warn", "verify.interrupted.report.failed", { turnId, error: err?.message }));
+        if (entry.artifactsDir && uploads.failed === 0) rmSync(entry.artifactsDir, { recursive: true, force: true });
+      }
       await this.api
         .turnResult(turnId, {
           status: "failed",
@@ -476,6 +587,70 @@ export class BridgeDaemon {
     }
   }
 
+  // ── preview processes across restarts ─────────────────────────────
+  get previewPidsPath() {
+    return join(this.kaiHome, "state", "preview-pids.json");
+  }
+
+  readPreviewPids() {
+    try {
+      const raw = JSON.parse(readFileSync(this.previewPidsPath, "utf8"));
+      return Array.isArray(raw) ? raw.filter((e) => e && Number.isInteger(e.pid)) : [];
+    } catch {
+      return [];
+    }
+  }
+
+  writePreviewPids(entries) {
+    try {
+      mkdirSync(join(this.kaiHome, "state"), { recursive: true });
+      writeFileSync(this.previewPidsPath, JSON.stringify(entries));
+    } catch {
+      /* best effort */
+    }
+  }
+
+  /** ServiceRunner hook: every dev-server pid is persisted while it lives. */
+  trackServicePid(sessionId, name, pid, op) {
+    if (!Number.isInteger(pid)) return;
+    const rest = this.readPreviewPids().filter((e) => e.pid !== pid);
+    this.writePreviewPids(op === "add" ? [...rest, { pid, name, sessionId, startedAt: new Date().toISOString() }] : rest);
+  }
+
+  /**
+   * Dev servers from a previous daemon life (crash, kill -9) are still
+   * bound to their ports: end their process groups (Windows: the tree) and
+   * forget them. Pids are checked for liveness first; a reused pid that no
+   * longer looks like our service is left alone.
+   */
+  killOrphanedServices({ kill = process.kill, platform = process.platform } = {}) {
+    const entries = this.readPreviewPids();
+    this.writePreviewPids([]);
+    let killed = 0;
+    for (const e of entries) {
+      try {
+        kill(e.pid, 0); // alive?
+      } catch {
+        continue;
+      }
+      try {
+        if (platform === "win32") spawn("taskkill", ["/PID", String(e.pid), "/T", "/F"], { stdio: "ignore", windowsHide: true }).on("error", () => {});
+        else {
+          try {
+            kill(-e.pid, "SIGTERM");
+          } catch {
+            kill(e.pid, "SIGTERM");
+          }
+        }
+        killed += 1;
+        this.log("warn", "preview.orphan.killed", { pid: e.pid, name: e.name, sessionId: e.sessionId });
+      } catch {
+        /* already gone */
+      }
+    }
+    return killed;
+  }
+
   /**
    * The realtime client retries a refused connection forever, but two
    * states are terminal: six failed reconnects of an ESTABLISHED socket
@@ -526,11 +701,27 @@ export class BridgeDaemon {
     }
     try {
       const pending = await this.api.pendingTurns();
+      // Cancels the server settled while we were away (reaper / watchdog):
+      // abort the orphaned run instead of reporting into a turn that ended,
+      // and never "recover" a turn that was cancelled in the same breath.
+      const cancelled = new Set((pending?.cancelledTurnIds || []).map(String));
+      for (const turnId of cancelled) {
+        const run = this.running.get(turnId);
+        if (!run) continue;
+        this.log("info", "turn.cancel.replayed", { turnId });
+        run.ctrl.abort();
+      }
       for (const turn of pending?.turns || []) {
-        if (this.running.has(turn.turnId)) continue;
+        if (this.running.has(turn.turnId) || cancelled.has(String(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 }));
       }
+      // Sign-in requests published while we were away: open their windows now.
+      for (const req of pending?.loginRequests || []) {
+        if (!req?.requestId || this.logins.has(req.requestId)) continue;
+        this.log("info", "verify.login.recovered", { requestId: req.requestId });
+        void this.loginStart(req).catch((err) => this.log("error", "verify.login.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.
@@ -591,8 +782,10 @@ export class BridgeDaemon {
         }
         return this.startTurn(data);
       case "bridge.turn.cancel":
-        this.running.get(data.turnId)?.abort();
+        this.running.get(data.turnId)?.ctrl.abort();
         return;
+      case "bridge.turn.steer":
+        return this.steerTurn(data);
       case "bridge.rescan":
         await this.scanRepos();
         // A rescan is the user's "look again" — refresh the model lists too
@@ -608,11 +801,35 @@ export class BridgeDaemon {
       case "bridge.harness.install":
         return this.harnessInstall(data);
       case "bridge.session.close":
+        // A closed session has no turn left to run: abort ours for it (the
+        // Server has already settled them; the runner just stops burning).
+        for (const [turnId, entry] of this.running) {
+          if (entry.sessionId === data.sessionId) {
+            this.log("info", "turn.abort.session_closed", { turnId, sessionId: data.sessionId });
+            entry.ctrl.abort();
+          }
+        }
         this.services.get(data.sessionId)?.stopAll();
         this.services.delete(data.sessionId);
         this.clearPreviewIdleTimer(data.sessionId);
+        // A sign-in window opened for this session has nothing to sign in to any more.
+        await this.teardownLogins((l) => l.sessionId === data.sessionId, "session closed");
+        // Pre-0.4.0 daemons kept a browser profile per session; drop leftovers.
+        rmSync(join(this.kaiHome, "browser", String(data.sessionId).replace(/[^\w.-]/g, "_")), { recursive: true, force: true });
         return;
+      case "bridge.verify.login.start":
+        return this.loginStart(data);
+      case "bridge.verify.login.done":
+        return this.loginDone(data);
+      case "bridge.verify.login.cancel":
+        return this.loginCancel(data);
+      case "bridge.verify.evidence.retry":
+        return this.retryEvidence(data);
       case "bridge.preview.start":
+        // A preview the USER started stays up until they stop it (or it
+        // idles out); one that Verify booted is released after the run.
+        (this.manualPreviews ??= new Set()).add(data.sessionId);
+        this.verifyOwnedPreviews?.delete(data.sessionId);
         return this.previewStart(data);
       case "bridge.preview.stop":
         return this.previewStop(data);
@@ -632,148 +849,270 @@ export class BridgeDaemon {
    * 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.
+   *
+   * Every failure is a structured error (`previewErrorPayload`): code +
+   * kind + repo/service + detail, classified from the whole log tail BEFORE
+   * truncation. `companionRemotes` (Server-resolved `{ key: remote }`) is
+   * how non-github companions get cloned; `note` survives onto error writes.
    */
-  async previewStart({ sessionId, title, repos }) {
-    const report = (payload) =>
-      this.api.sessionPreview(sessionId, payload).catch((err) => this.log("warn", "preview.report.failed", { error: err.message }));
+  async previewStart({ sessionId, title, repos, companionRemotes = null }) {
+    let lastNote = null;
+    const skipped = [];
+    // Every report is also RETURNED: the verify turn boots the preview
+    // through this same path and needs the final status + preview URLs.
+    const report = async (payload) => {
+      if (payload.note) lastNote = payload.note;
+      const body = payload.status === "error" ? { ...payload, urls: payload.urls ?? [], previews: payload.previews ?? [], ...(lastNote && !payload.note ? { note: lastNote } : {}), ...(skipped.length && !payload.skipped ? { skipped } : {}) } : payload;
+      await this.api.sessionPreview(sessionId, body).catch((err) => this.log("warn", "preview.report.failed", { error: err.message }));
+      return body;
+    };
+    const fail = (err, ctx = {}) => report(toPreviewErrorPayload(err, { ...ctx, skipped }));
     await report({ status: "starting" });
+    let runner = null;
     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.
+      // Pass 1 — resolve every session repo (checkout, env, config).
       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;
+          return fail(new PreviewError(`Repository ${r.key} is not checked out on this device.`, { code: "companion_missing", repo: r.key }), { repo: r.key });
         }
         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;
+        const cwd = mode === "local" ? group.primary.path : this.findSessionWorktree(group.name, sessionId, title);
+        if (!cwd || !existsSync(cwd)) {
+          return fail(new PreviewError(`The workspace for this session is gone on this device — send Kai a message to recreate it, then start the preview again.`, { code: "other", repo: r.key }), { repo: r.key });
         }
         // 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.
+        // don't boot blank (per service cwd too — ServiceRunner). 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 });
         }
-        // Config resolution order: this worktree's own config, then the
-        // PRIMARY checkout's (a repo verified by the setup agent has its
-        // dev.yaml on an unmerged config PR — session worktrees cut from
-        // the base branch don't carry it yet), then the package.json
-        // heuristic. Closes the verified-before-config-merge window.
-        const config =
-          readDevConfig(cwd) ??
-          (cwd !== group.primary.path ? readDevConfig(group.primary.path) : null) ??
-          detectDevConfig(cwd);
-        if (!config) continue;
-        if (config.error) {
-          await report({ status: "error", error: config.error });
-          return;
+        const config = this.resolveDevConfig(cwd, group, r.key);
+        if (!config) {
+          skipped.push({ repo: r.key, reason: "no_dev_config" });
+          continue;
         }
-        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 });
+        if (config.needsConfig) {
+          skipped.push({ repo: r.key, reason: "monorepo", hint: config.hint });
+          continue;
         }
-        resolved.push({ key: r.key, cwd, config, mode });
+        if (config.error) return fail(new PreviewError(config.error, { code: "no_dev_config", repo: r.key }), { repo: r.key });
+        resolved.push({ key: r.key, cwd, config, mode, envSource: mode === "local" ? null : group.primary.path });
       }
       if (!resolved.length) {
-        await report({ status: "error", error: "No dev config found — add .gleap/dev.yaml to the repo (services + preview)." });
-        return;
+        const mono = skipped.find((sk) => sk.reason === "monorepo");
+        return fail(
+          new PreviewError(
+            mono ? `${mono.repo} is a ${mono.hint} — add .gleap/dev.yaml (services + preview) so Kai knows which app to run.` : "No dev config found — add .gleap/dev.yaml to the repo (services + preview).",
+            { code: "no_dev_config", repo: skipped[0]?.repo, hint: mono?.hint },
+          ),
+        );
+      }
+      if (skipped.length) await report({ status: "starting", note: `Skipped ${skipped.map((sk) => `${sk.repo} (${sk.reason === "monorepo" ? sk.hint : "no dev config"})`).join(", ")}.` });
+
+      // Pass 2 — companions (BFS, depth ≤ 3): clone when missing (remote
+      // from the Server, never guessed for non-github), read their config
+      // from the PRIMARY checkout; a companion without a config is
+      // `companion_unconfigured` (once — no retry loop).
+      const remotes = companionRemotes && typeof companionRemotes === "object" ? companionRemotes : {};
+      const { companions } = await collectCompanions({
+        roots: resolved.map((r) => ({ key: r.key, config: r.config })),
+        maxDepth: COMPANION_MAX_DEPTH,
+        loadConfig: async (key) => {
+          try {
+            const group = await this.ensureCompanionCheckout(key, report, { remotes });
+            const config = this.resolveDevConfig(group.primary.path, group, key);
+            if (!config || config.needsConfig) return { group, unconfigured: true, hint: config?.hint ?? null };
+            if (config.error) return { group, error: config.error };
+            return { group, config };
+          } catch (err) {
+            return { failure: err };
+          }
+        },
+      });
+      for (const c of companions) {
+        if (c.config) continue;
+        if (c.optional) {
+          this.log("warn", "preview.companion.skipped", { sessionId, repo: c.key, reason: c.failure?.message || (c.unconfigured ? "unconfigured" : c.error) });
+          skipped.push({ repo: c.key, reason: c.unconfigured ? "no_dev_config" : "not_on_device" });
+          continue;
+        }
+        if (c.failure) return fail(c.failure, { repo: c.key });
+        if (c.unconfigured) {
+          return fail(new PreviewError(`Companion ${c.key} has no .gleap/dev.yaml${c.hint ? ` (${c.hint})` : ""} — configure it so its services can run alongside.`, { code: "companion_unconfigured", repo: c.key, hint: c.hint }), { repo: c.key });
+        }
+        return fail(new PreviewError(`Companion ${c.key}: ${c.error}`, { code: "no_dev_config", repo: c.key }), { repo: c.key });
       }
-      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 bootable = companions.filter((c) => c.config);
+
+      runner = this.runnerFor(sessionId);
+      // Pass 3 — ports for EVERY config (companions + session repos) before
+      // any boot, so `${port:x}` cross-references resolve whatever the order.
+      for (const c of bootable) await runner.assignPorts(c.group.primary.path, c.config, { mode: "local", repoKey: c.key });
+      for (const r of resolved) await runner.assignPorts(r.cwd, r.config, { mode: r.mode, repoKey: r.key, envSource: r.envSource });
+
+      // Pass 4 — boot companions (deepest first, local mode: an already
+      // running dev server of that repo is adopted), then the session repos
+      // (worktree mode boots its own copy: it must serve the changed code).
       const companionPreviews = [];
-      for (const [key, { optional }] of companionWants) {
+      for (const c of bootable) {
         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 });
+          const started = await this.bootRepoWithConfig(runner, c.group.primary.path, c.config, "local", c.key);
+          if (started.preview) {
+            const { adoptedCwd, ...preview } = started.preview;
+            companionPreviews.push({ repo: c.key, role: "companion", ...preview, ...this.describeCheckout(adoptedCwd || c.group.primary.path) });
+          }
         } catch (err) {
-          if (optional) {
-            this.log("warn", "preview.companion.skipped", { sessionId, repo: key, error: err.message });
+          if (c.optional) {
+            this.log("warn", "preview.companion.skipped", { sessionId, repo: c.key, error: err.message });
+            skipped.push({ repo: c.key, reason: "not_on_device" });
             continue;
           }
-          runner.stopAll();
-          this.services.delete(sessionId);
-          await report({ status: "error", error: `Companion ${key}: ${err.message}` });
-          return;
+          throw err;
         }
       }
-      // 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;
+        const started = await this.bootRepoWithConfig(runner, cwd, config, mode, key);
+        if (started.preview) {
+          const { adoptedCwd, ...preview } = started.preview;
+          previews.push({ repo: key, ...preview, ...this.describeCheckout(adoptedCwd || cwd) });
         }
       }
+      const urls = [...previews, ...companionPreviews];
+      // The landing page is a session repo's preview (never a companion's).
+      const landing = previews[0] ?? companionPreviews[0] ?? null;
       this.armPreviewIdleTimer(sessionId);
-      await report({ status: "running", previews: [...previews, ...companionPreviews] });
+      return report({ status: "running", previews: urls, urls, landingUrl: landing?.url ?? null, ...(skipped.length ? { skipped } : {}) });
     } catch (err) {
-      this.log("error", "preview.start.failed", { sessionId, error: err.message });
-      await report({ status: "error", error: err.message });
+      this.log("error", "preview.start.failed", { sessionId, error: err.message, code: err?.code });
+      runner?.stopAll();
+      this.services.delete(sessionId);
+      this.clearPreviewIdleTimer(sessionId);
+      return fail(err);
+    }
+  }
+
+  /**
+   * Config resolution order: this worktree's own config, then the PRIMARY
+   * checkout's (a repo verified by the setup agent has its dev.yaml on an
+   * unmerged config PR — session worktrees cut from the base branch don't
+   * carry it yet), then the package.json heuristic (which answers
+   * `{ needsConfig }` for workspace roots). Unknown dev.yaml keys are
+   * logged once per repo. Closes the verified-before-config-merge window.
+   */
+  resolveDevConfig(cwd, group, repoKey) {
+    const config = readDevConfig(cwd) ?? (group && cwd !== group.primary.path ? readDevConfig(group.primary.path) : null) ?? detectDevConfig(cwd);
+    // Lazily created: embedded hosts (and tests) build a daemon without
+    // running the constructor — a missing bookkeeping map must never turn
+    // a bootable preview into "Cannot read properties of undefined".
+    this.unknownDevKeysLogged ??= new Set();
+    for (const key of config?.unknownKeys || []) {
+      const id = `${repoKey}:${key}`;
+      if (this.unknownDevKeysLogged.has(id)) continue;
+      this.unknownDevKeysLogged.add(id);
+      this.log("warn", "preview.config.unknown_key", { repo: repoKey, key });
+    }
+    return config;
+  }
+
+  /** `{ branch, commit, dirty }` of a checkout for the preview's `urls[]` entries (best-effort). */
+  describeCheckout(cwd) {
+    const out = {};
+    try {
+      const branch = currentBranch(cwd);
+      if (branch) out.branch = branch;
+      const commit = currentHead(cwd);
+      if (commit) out.commit = commit;
+      out.dirty = collectChanges(cwd).files.length;
+    } catch {
+      /* not a git checkout */
+    }
+    return out;
+  }
+
+  /**
+   * The session's worktree for a repo: the exact slug when the title is
+   * known; otherwise (sign-in commands carry only the session id) the one
+   * directory under `~/.kai/worktrees/<repo>/` that ends in the session's
+   * id suffix — slugs are `<title>-<last 8 of the id>`, unique per session.
+   */
+  findSessionWorktree(repoName, sessionId, title) {
+    const exact = worktreePath(this.kaiHome, repoName, sessionSlug(sessionId, title));
+    if (existsSync(exact)) return exact;
+    const suffix = `-${String(sessionId || "").slice(-8)}`;
+    if (suffix.length < 2) return exact;
+    try {
+      const dir = join(this.kaiHome, "worktrees", repoName);
+      const hits = readdirSync(dir, { withFileTypes: true }).filter((d) => d.isDirectory() && d.name.endsWith(suffix));
+      return hits.length === 1 ? join(dir, hits[0].name) : exact;
+    } catch {
+      return exact;
     }
   }
 
   /**
    * Boot one repo's services with an already-resolved config; throws a
-   * readable error (with the failing service's log tail) when a service
+   * `PreviewError` carrying the classified log line + code 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 });
+  async bootRepoWithConfig(runner, cwd, config, mode, repoKey = null, opts = {}) {
+    const started = await runner.start(cwd, config, { mode, repoKey, ...opts });
     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}` : ""}`);
+      throw new PreviewError(`${dead.name} did not start${dead.error ? ` — ${dead.error}` : ""}`, {
+        code: dead.errorCode || "service_crashed",
+        repo: repoKey,
+        service: dead.name,
+        detail: { ...(dead.errorDetail || {}), logPath: dead.logPath },
+      });
     }
     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.
+   * A companion repo must exist on this machine. Cloned → its group. Not
+   * cloned → clone it (remote from the Server's `companionRemotes`, or the
+   * key itself for github.com; SSH when the machine's checkouts use SSH)
+   * into the preferred root and rescan. Without a remote the daemon
+   * cannot guess → `companion_missing`; a failed clone →
+   * `companion_clone_failed` with the exact command to run by hand.
    */
-  async ensureCompanionCheckout(key, report) {
+  async ensureCompanionCheckout(key, report, { remotes = {} } = {}) {
     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`);
+    const name = String(key).split("/").pop();
+    const remote = resolveCompanionRemote({ key, remotes, useSsh: prefersSsh(this.repoGroups) });
+    if (!remote || !name) {
+      throw new PreviewError(`Companion ${key} is not cloned on this device and Gleap knows no remote for it — clone it, then start the preview again.`, {
+        code: "companion_missing",
+        repo: key,
+        detail: { remote: remote ?? null },
+      });
     }
     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 });
+    this.log("info", "preview.companion.clone", { key, remote });
+    let target = null;
+    try {
+      target = await this.cloneRepo({ remote, name, timeoutMs: CLONE_TIMEOUT_MS });
+    } catch (err) {
+      throw new PreviewError(`Companion ${key} could not be cloned: ${err.message}`, {
+        code: "companion_clone_failed",
+        repo: key,
+        detail: { remote, cloneCommand: buildCloneCommand({ remote, target: err.target || target || 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`);
+    if (!group) {
+      throw new PreviewError(`Companion ${key}: the clone finished but the repository was not discovered — its remote resolves to a different key. Point Gleap at the checkout (Locate…).`, {
+        code: "companion_missing",
+        repo: key,
+        detail: { remote, cloneCommand: buildCloneCommand({ remote, target }) },
+      });
+    }
     return group;
   }
 
@@ -781,26 +1120,43 @@ export class BridgeDaemon {
    * 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. Turns never boot services
-   * themselves — they only reuse this runner while it is alive.
+   * themselves — they only reuse this runner while it is alive. "Idle"
+   * also means nobody is connected: established connections on a service
+   * port (a browser tab left open, the phone) re-arm the timer.
    */
   armPreviewIdleTimer(sessionId) {
     this.previewIdleTimers ??= new Map();
     this.clearPreviewIdleTimer(sessionId);
-    const t = setTimeout(() => {
+    const t = setTimeout(async () => {
       this.previewIdleTimers.delete(sessionId);
       const runner = this.services.get(sessionId);
       if (!runner) return;
+      if (await this.previewHasConnections(runner)) {
+        this.log("info", "preview.idle.connected", { sessionId });
+        if (this.services.get(sessionId) === runner) this.armPreviewIdleTimer(sessionId);
+        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." })
+        .sessionPreview(sessionId, { status: "stopped", urls: [], previews: [], errorCode: "idle_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);
   }
 
+  /** Any ESTABLISHED connection on one of the runner's (non-adopted) ports? Injectable for tests. */
+  async previewHasConnections(runner) {
+    const count = this.countConnections ?? ((port) => establishedConnections(port));
+    for (const [name, port] of Object.entries(runner.ports || {})) {
+      if (runner.adopted?.has(name)) continue;
+      if ((await count(port).catch(() => 0)) > 0) return true;
+    }
+    return false;
+  }
+
   clearPreviewIdleTimer(sessionId) {
     const t = this.previewIdleTimers?.get(sessionId);
     if (t) clearTimeout(t);
@@ -808,17 +1164,63 @@ export class BridgeDaemon {
   }
 
   async previewStop({ sessionId }) {
+    this.manualPreviews?.delete(sessionId);
+    this.verifyOwnedPreviews?.delete(sessionId);
+    // A sign-in window for this session has nothing left to sign in to.
+    await this.teardownLogins((l) => l.sessionId === sessionId, "preview stopped");
     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 }));
+    await this.api.sessionPreview(sessionId, { status: "stopped", urls: [], previews: [] }).catch((err) => this.log("warn", "preview.report.failed", { error: err.message }));
+  }
+
+  /**
+   * A service that had become ready died on its own (crash on the first
+   * real request, OOM, the user killed it): the preview is broken NOW. Stop
+   * the rest, drop the runner (Retry reboots cleanly) and tell the
+   * dashboard why — with the classified log line.
+   */
+  onServiceDied(sessionId, info) {
+    const runner = this.services.get(sessionId);
+    if (!runner) return Promise.resolve();
+    this.log("warn", "preview.service.died", { sessionId, name: info.name, code: info.code, errorCode: info.errorCode });
+    runner.stopAll();
+    this.services.delete(sessionId);
+    this.clearPreviewIdleTimer(sessionId);
+    return this.api
+      .sessionPreview(
+        sessionId,
+        previewErrorPayload({
+          code: info.errorCode === "service_crashed" || !info.errorCode ? "service_crashed" : info.errorCode,
+          error: `${info.name} stopped: ${info.error}`,
+          repo: info.repoKey,
+          service: info.name,
+          detail: { ...(info.detail || {}), logPath: info.logPath, exitCode: info.code },
+        }),
+      )
+      .catch((err) => this.log("warn", "preview.report.failed", { error: err.message }));
   }
 
   /** One ServiceRunner per session — created only by the on-demand preview; turns reuse it. */
-  runnerFor(sessionId, onStatus) {
+  runnerFor(sessionId) {
     let runner = this.services.get(sessionId);
     if (!runner) {
-      runner = new ServiceRunner({ kaiHome: this.kaiHome, sessionId, log: this.log, onStatus });
+      // Stable ports (hash of repo + service in 43000-43999, when free) keep
+      // a saved sign-in's origins matching from one session to the next.
+      runner = new ServiceRunner({
+        kaiHome: this.kaiHome,
+        sessionId,
+        log: this.log,
+        onStatus: (message) => {
+          this.log("info", "preview.status", { sessionId, message });
+          this.previewStatusListeners?.get(sessionId)?.(message);
+        },
+        preferredPort: ({ repoKey, service }) => preferredStablePort(repoKey, service),
+        ...(this.describeListener ? { describeListener: this.describeListener } : {}),
+        ...(this.previewSettleMs != null ? { settleMs: this.previewSettleMs } : {}),
+        onServiceExit: (info) => this.onServiceDied(sessionId, info),
+        onProcess: (name, pid, op) => this.trackServicePid(sessionId, name, pid, op),
+      });
       this.services.set(sessionId, runner);
     }
     return runner;
@@ -839,6 +1241,7 @@ export class BridgeDaemon {
         title: turn.title,
       });
       bound.push({ key: r.key, ...ws });
+      if (ws.deps) this.log("info", "deps.seed", { repo: r.key, ...ws.deps });
       // Remember the choice per repo (the UI asks once, then sticks).
       this.config.repoModes = { ...(this.config.repoModes || {}), [r.key]: mode };
     }
@@ -897,10 +1300,16 @@ export class BridgeDaemon {
     const { turnId } = turn;
     if (this.running.has(turnId)) return;
     const ctrl = new AbortController();
-    this.running.set(turnId, ctrl);
+    const entry = { ctrl, control: null, sessionId: turn.sessionId };
+    this.running.set(turnId, entry);
     const releaseAwake = keepAwake();
     let outcome = null;
-    this.rememberInflight(turnId);
+    // Verify turns (`agent: kai-verifier`): preview booted up front, browser
+    // evidence collected into an artifacts dir, report uploaded after the
+    // turn — see prepareVerifyTurn / finishVerification.
+    const isVerify = turn.agent === "kai-verifier";
+    let verify = null;
+    this.rememberInflight(turnId, { sessionId: turn.sessionId, agent: turn.agent ?? null });
     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 };
@@ -910,70 +1319,143 @@ export class BridgeDaemon {
       // local paths — the prompt lists them.
       const workDir = bound[0]?.cwd;
       if (!workDir) throw new Error("Turn has no repositories.");
-      const repoNote = this.repoBrief(turn, bound);
-      // Previews are manual-only (dashboard "Start preview") — a turn
-      // never boots dev servers on its own. When the user already has a
-      // preview running for this session, describe it to the agent and
-      // hand it the Playwright MCP so it can verify in a real browser.
-      const { note: previewNote, hasLivePreview } = await this.describeLivePreview(turn, bound, batcher);
-      const mcpServers = hasLivePreview ? [...(turn.mcpServers || []), previewMcpServer(RUNNER_DIR)] : turn.mcpServers;
+      const repoNote = isVerify ? this.verifyRepoBrief(bound) : this.repoBrief(turn, bound);
+      let previewNote = "";
+      let mcpServers = turn.mcpServers;
+      if (isVerify) {
+        verify = await this.prepareVerifyTurn(turn, bound);
+        if (!verify.ok) {
+          // Nothing to test against (preview dead) or a sign-in wall the
+          // user must clear first: file a blocked report and close the turn
+          // cleanly without spending an agent run.
+          await this.api
+            .turnVerification(turnId, { ...buildVerificationPayload(null, [], { fallbackReason: verify.error }), ...(verify.blocked || {}) })
+            .catch((err) => this.log("warn", "verify.report.failed", { turnId, error: err.message }));
+          outcome = {
+            status: "completed",
+            result: null,
+            changes: bound.map((b) => ({ key: b.key, mode: b.mode, branch: b.branch, base: b.base, cwd: b.cwd, files: [], push: false })),
+            profileId: profile.id,
+          };
+          return;
+        }
+        previewNote = verify.note;
+        // The evidence dir is where a restart mid-run finds partial footage.
+        this.rememberInflight(turnId, { sessionId: turn.sessionId, agent: turn.agent, artifactsDir: verify.artifactsDir });
+        mcpServers = [
+          ...(turn.mcpServers || []),
+          previewMcpServer(RUNNER_DIR, {
+            outputDir: verify.artifactsDir,
+            // `storage` = browser_storage_state for the final sign-in refresh;
+            // restoring an arbitrary state file is never the agent's call.
+            caps: ["devtools", "testing", "storage"],
+            secretsFile: verify.secretsFile,
+            storageStateFile: verify.storageStateFile,
+            allowedOrigins: verify.storageStateFile ? verify.allowedOrigins : null,
+            disabledTools: ["browser_set_storage_state"],
+            ignoreHttpsErrors: !!verify.ignoreHttpsErrors,
+          }),
+        ];
+        await this.postVerifyStage(turnId, "verifying");
+      } else {
+        // Previews are manual-only (dashboard "Start preview") — a turn
+        // never boots dev servers on its own. When the user already has a
+        // preview running for this session, describe it to the agent and
+        // hand it the Playwright MCP so it can verify in a real browser.
+        const live = await this.describeLivePreview(turn, bound, batcher);
+        previewNote = live.note;
+        if (live.hasLivePreview) mcpServers = [...(turn.mcpServers || []), previewMcpServer(RUNNER_DIR)];
+      }
       const res = await runTurn({
         turn: { ...turn, task: `${turn.task}${repoNote}${previewNote}`, mcpServers },
         profile,
         workDir,
         kaiHome: this.kaiHome,
+        // The verify MCP's request policy (KAI_VERIFY_*) — host-only, never in the prompt.
+        extraEnv: verify?.env ?? null,
         signal: ctrl.signal,
-        onEvent: (ev) => batcher.push(ev),
+        onSpawn: (handle) => {
+          entry.control = handle.control;
+        },
+        onEvent: (ev) => {
+          if (verify) {
+            // The tester is using the preview — it must not idle-stop
+            // under it. And the report carries LOCAL paths: keep it here,
+            // the uploaded version goes out after the turn.
+            this.armPreviewIdleTimer(turn.sessionId);
+            if (ev?.type === "verify_report") {
+              verify.report = ev.report && typeof ev.report === "object" ? ev.report : null;
+              return;
+            }
+            // Injected sign-in values (cookies, tokens) must never reach
+            // the Server in a tool row or snapshot.
+            if (verify.redact?.size) ev = redactDeep(ev, verify.redact);
+          }
+          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;
+      // Plan and verify turns are read-only: worktrees are restored, local
+      // checkouts only reported, nothing is ever committed or pushed.
+      const readOnlyTurn = !!turn.planMode || isVerify;
       const changes = [...bound, ...this.adoptSessionWorktrees(turn, bound)].map((b) => {
         ensureCommitExcludes(b.cwd, { allowDevConfig: !!turn.allowDevConfig });
-        // A plan turn must leave the worktree as it found it — see
+        // A read-only turn must leave the worktree as it found it — see
         // discardChanges. Local checkouts are the user's; only report.
-        if (turn.planMode) {
+        if (readOnlyTurn) {
           const leaked = b.mode === "worktree" ? discardChanges(b.cwd).discarded : collectChanges(b.cwd).files;
           if (leaked.length > 0) {
-            this.log("warn", "plan.changes", { turnId, repo: b.key, mode: b.mode, files: leaked.length, discarded: b.mode === "worktree" });
+            const mode = turn.planMode ? "Plan mode" : "Verification";
+            this.log("warn", `${turn.planMode ? "plan" : "verify"}.changes`, { turnId, repo: b.key, mode: b.mode, files: leaked.length, discarded: b.mode === "worktree" });
             batcher.push({
               type: "text",
               message:
                 b.mode === "worktree"
-                  ? `Plan mode is read-only — ${leaked.length} file change${leaked.length === 1 ? "" : "s"} made during planning ${leaked.length === 1 ? "was" : "were"} discarded; the build starts from the plan.`
-                  : `Plan mode is read-only, but ${leaked.length} file change${leaked.length === 1 ? "" : "s"} landed in your local checkout of ${b.key} — review them before building.`,
+                  ? `${mode} is read-only — ${leaked.length} file change${leaked.length === 1 ? "" : "s"} made during ${turn.planMode ? "planning" : "verification"} ${leaked.length === 1 ? "was" : "were"} discarded${turn.planMode ? "; the build starts from the plan" : ""}.`
+                  : `${mode} is read-only, but ${leaked.length} file change${leaked.length === 1 ? "" : "s"} landed in your local checkout of ${b.key} — review them${turn.planMode ? " before building" : ""}.`,
             });
           }
         }
         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;
+        // Server can open the PR; read-only turns and local mode never push.
+        const shouldPush = completed && b.mode === "worktree" && !readOnlyTurn && diff.files.length > 0;
         const push = shouldPush
           ? commitAndPush(b.cwd, {
               branch: b.branch,
               allowDevConfig: !!turn.allowDevConfig,
               message: `${turn.title || "Kai Code changes"}\n\nSession ${turn.sessionId} · run on ${this.config.device?.name || "a paired device"}`,
             })
-          : null;
+          : isVerify
+            ? false
+            : null;
         // `cwd` travels with the change so the dashboard can point at
         // work that stayed on this machine (files but no push).
-        return { key: b.key, mode: b.mode, branch: b.branch, base: b.base, cwd: b.cwd, adopted: b.adopted || undefined, ...diff, push };
+        // Pushed → the commit list + diff stat travel with the change so the
+        // Server can write a real pull request description.
+        const described = push?.pushed ? describeBranchChanges(b.cwd, b.base) : null;
+        return { key: b.key, mode: b.mode, branch: b.branch, base: b.base, cwd: b.cwd, adopted: b.adopted || undefined, ...diff, push, ...(described ? described : {}) };
       });
-      // The plan-mode notices above were queued AFTER the post-turn
+      // The read-only notices above were queued AFTER the post-turn
       // flush; land them before the result closes the turn (the Server
       // answers 410 for events on an ended turn).
       await batcher.flush();
+      if (verify) {
+        const finished = await this.finishVerification(turn, { ...verify, workDir, bound }, res, ctrl.signal.aborted);
+        await this.settleVerifyPreview(turn, finished?.status).catch((err) => this.log("warn", "verify.preview.release.failed", { turnId, error: err.message }));
+      }
       // 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,
+        result: verify?.redact?.size ? redactDeep(res.result, verify.redact) : 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) } : {}),
+        ...(res.lastError && res.code !== 0 ? { error: redactDeep(res.lastError.replace(/^acp-runner: /, "").slice(0, 500), verify?.redact) } : {}),
         changes,
         profileId: profile.id,
       };
@@ -992,11 +1474,865 @@ export class BridgeDaemon {
           })
           .catch((err) => this.log("error", "result.lost", { turnId, error: err.message }));
       }
+      // Test credentials and the injected / final sign-in state live on
+      // disk only for the duration of the turn.
+      for (const f of [verify?.secretsFile, verify?.storageStateFile, verify?.finalStateFile]) if (f) rmSync(f, { force: true });
+      verify?.release?.();
       this.forgetInflight(turnId);
       releaseAwake();
       this.running.delete(turnId);
-      if (this.updatePending && this.running.size === 0) void this.checkForUpdate();
+      if ((this.updatePending || this.restartPending) && this.running.size === 0 && this.logins.size === 0) void this.checkForUpdate();
+    }
+  }
+
+  // ── verify turns ───────────────────────────────────────────────────
+  /** Overridable seam (tests, embedded hosts): a browser the Playwright MCP can launch. */
+  ensurePreviewBrowser() {
+    return ensurePreviewBrowser({ runnerDir: RUNNER_DIR, log: this.log });
+  }
+
+  /** Seams for the sign-in flows (tests inject a fake Playwright / probe / capture). */
+  loadPlaywright() {
+    return loadPlaywright(RUNNER_DIR);
+  }
+  displayAvailable() {
+    return displayAvailable();
+  }
+  probeLogin(opts) {
+    return probeLogin(opts);
+  }
+  captureLogin(opts) {
+    return captureLogin(opts);
+  }
+
+  /** Where a verify turn's injected sign-in state lives (0600, deleted with the turn). */
+  loginStateDir() {
+    return join(this.kaiHome, "state", "preview-login");
+  }
+
+  /** The agent's final browser-state export — inside the turn's evidence dir (the MCP's only writable root besides the repo). */
+  finalStateFileFor(artifactsDir) {
+    return join(artifactsDir, "state", "final-storage-state.json");
+  }
+
+  /** Best-effort stage transition for the dashboard's Verify card (booting → verifying → saving). */
+  async postVerifyStage(turnId, stage, note) {
+    // The note often relays the agent's last line — markdown emphasis
+    // ("**Confirming…**") must not reach the card as literal asterisks.
+    const plain = typeof note === "string" ? note.replace(/[#*`>_]/g, "").replace(/\s+/g, " ").trim().slice(0, 200) : "";
+    try {
+      await this.api.turnVerificationStage(turnId, { stage, ...(plain ? { note: plain } : {}) });
+    } catch (err) {
+      this.log("debug", "verify.stage.failed", { turnId, stage, error: err?.message });
+    }
+  }
+
+  /**
+   * One probe / refresh of a sign-in at a time per user + repo: two verify
+   * turns racing the same record would both refresh it (one 409s) and
+   * could probe a preview the other is still booting.
+   */
+  withVerifyLock(key, fn) {
+    return this.acquireVerifyLock(key).then(async (release) => {
+      try {
+        return await fn();
+      } finally {
+        release();
+      }
+    });
+  }
+
+  /**
+   * Acquire the per user+repo verify lock; resolves with `release()`. A
+   * turn that injected a saved sign-in keeps it until its final refresh
+   * has landed: two agent runs presenting the same refresh token in
+   * parallel is exactly what rotation-based IdPs revoke on.
+   */
+  acquireVerifyLock(key) {
+    this.verifyLockHolders ??= new Set(); // keys currently HELD (the map also lists waiters)
+    this.verifyLocks ??= new Map();
+    const prev = this.verifyLocks.get(key) ?? Promise.resolve();
+    let release;
+    const held = new Promise((resolve) => {
+      let done = false;
+      release = () => {
+        if (done) return;
+        done = true;
+        this.verifyLockHolders.delete(key);
+        resolve();
+      };
+    });
+    const next = prev.catch(() => {}).then(() => held);
+    this.verifyLocks.set(key, next);
+    next.finally(() => {
+      if (this.verifyLocks.get(key) === next) this.verifyLocks.delete(key);
+    });
+    return prev
+      .catch(() => {})
+      .then(() => {
+        this.verifyLockHolders.add(key);
+        return release;
+      });
+  }
+
+  /** The verifier's repo brief: where the checkouts are, and that they are read-only. */
+  verifyRepoBrief(bound) {
+    const lines = ["", "", "Repositories in this session (read-only for this verification turn — you cannot commit or push, and every file change is discarded when the turn ends):"];
+    for (const b of bound) lines.push(`- ${b.key}: ${b.cwd}${b.branch ? ` (branch ${b.branch}${b.base ? `, base ${b.base}` : ""})` : ""}`);
+    return lines.join("\n");
+  }
+
+  /**
+   * dev.yaml `auth.storageState: <command>` — run in the repo checkout,
+   * stdout is Playwright storageState JSON (or the path of a JSON file).
+   * Replaces the user's saved sign-in for this repo. Null on any failure.
+   */
+  async storageStateFromCommand(command, cwd) {
+    return new Promise((resolveP) => {
+      const cb = (err, stdout) => {
+        if (err) {
+          this.log("warn", "verify.login.command.failed", { error: err.message });
+          return resolveP(null);
+        }
+        resolveP(parseStorageStateOutput(stdout, { read: (p) => readFileSync(p, "utf8") }));
+      };
+      const opts = { cwd, timeout: 60_000, maxBuffer: 16 * 1024 * 1024, env: { ...process.env, BROWSER: "none" } };
+      if (process.platform === "darwin") execFile("/bin/zsh", ["-lc", command], opts, cb);
+      else execFile(command, [], { ...opts, shell: true }, cb);
+    });
+  }
+
+  /**
+   * Boot (or re-describe) the session's preview, make sure a browser can
+   * launch, decide the sign-in (dev.yaml command → saved record → none),
+   * PROBE it headless, and lay out the turn's evidence dir + state files +
+   * optional secrets file. Resolves `{ ok: false, error, blocked? }`
+   * (`blocked` = `{ blockedCode, loginPath?, firstTime? }` for the report)
+   * or `{ ok: true, artifactsDir, secretsFile, storageStateFile,
+   * finalStateFile, allowedOrigins, injected, redact, note, report: null }`.
+   */
+  async prepareVerifyTurn(turn, bound = []) {
+    const repoKeys = (turn.repos || []).map((r) => r.key).filter(Boolean).sort();
+    const lockKey = `${turn.userId ?? turn.ownerUserId ?? "device"}:${repoKeys.join(",")}`;
+    if (this.verifyLockHolders?.has(lockKey)) {
+      // Another verify run of this repo holds its sign-in — say so instead
+      // of sitting on "Starting the app…" until it finishes.
+      this.log("info", "verify.lock.wait", { turnId: turn.turnId, lockKey });
+      await this.postVerifyStage(turn.turnId, "booting", "Waiting for another verification of this repo on this machine to finish…");
     }
+    const release = await this.acquireVerifyLock(lockKey);
+    let result;
+    try {
+      result = await this.prepareVerifyTurnLocked(turn, bound);
+    } catch (err) {
+      release();
+      throw err;
+    }
+    if (result?.ok && result.injected) {
+      // Hold the repo's sign-in for the whole run — released by startTurn's
+      // finally (after finishVerification refreshed the record).
+      return { ...result, release };
+    }
+    release();
+    return result;
+  }
+
+  async prepareVerifyTurnLocked(turn, bound) {
+    const { turnId, sessionId } = turn;
+    // Lazy browser check — setup usually did this; a machine that skipped
+    // it downloads Chromium now (best-effort: without a browser the agent
+    // reports `blocked` itself).
+    const browser = await this.ensurePreviewBrowser().catch((err) => ({ ok: false, error: err?.message }));
+    if (!browser?.ok) {
+      // No browser, no test — say so with the exact command (Linux/Windows
+      // machines without Chrome and a failed Chromium download) instead of
+      // letting the agent discover it on its first navigate.
+      this.log("warn", "verify.browser.unavailable", { turnId, error: browser?.error });
+      return {
+        ok: false,
+        error: `No browser is available on this machine for the verification: ${browser?.error || "Chromium is not installed."}${browser?.command ? ` Run \`${browser.command}\` on this machine, then retry.` : ""}`,
+        blocked: { blockedCode: "no_browser" },
+      };
+    }
+    const channel = browser?.browser === "chrome" ? "chrome" : null;
+    // previewStart is idempotent on a live runner (booted services are
+    // only re-described) and reports starting/running to the dashboard
+    // exactly like the manual button. A cold boot is its own stage, and
+    // every runner status line during it (installing, still starting,
+    // ready) reaches the Verify card as a `booting` note — the heartbeat.
+    const coldBoot = !this.services.has(sessionId);
+    if (coldBoot && !this.manualPreviews?.has(sessionId)) (this.verifyOwnedPreviews ??= new Set()).add(sessionId);
+    if (coldBoot) await this.postVerifyStage(turnId, "booting");
+    const heartbeat = createStageHeartbeat((note) => this.postVerifyStage(turnId, "booting", note), { minIntervalMs: this.stageHeartbeatMs ?? 5_000 });
+    this.previewStatusListeners ??= new Map();
+    this.previewStatusListeners.set(sessionId, heartbeat.note);
+    let preview;
+    try {
+      preview = await this.previewStart({ sessionId, title: turn.title, repos: turn.repos, companionRemotes: turn.companionRemotes ?? null });
+    } finally {
+      this.previewStatusListeners?.delete(sessionId);
+      heartbeat.stop();
+    }
+    if (preview?.status !== "running") {
+      // The preview's structured error IS the diagnosis: its code becomes the
+      // verification's blockedCode (companion_missing, port_busy, deps_failed,
+      // …) so the card offers the right verb; `preview_unreachable` only
+      // when nothing more specific is known.
+      const code = preview?.errorCode && preview.errorCode !== "other" ? preview.errorCode : "preview_unreachable";
+      return {
+        ok: false,
+        error: preview?.error ? `The preview could not be started: ${preview.error}` : "The preview could not be started.",
+        blocked: { blockedCode: code },
+      };
+    }
+    // After a fix turn, services that do not hot-reload (`reload: restart`,
+    // the default for APIs) must run the fixed code before the probe.
+    const restartNotes = await this.restartChangedServices(turn, sessionId);
+    const artifactsDir = join(this.kaiHome, "artifacts", String(turnId).replace(/[^\w.-]/g, "_"));
+    mkdirSync(artifactsDir, { recursive: true });
+    let secretsFile = null;
+    let secretNames = [];
+    if (turn.verifySecrets && typeof turn.verifySecrets === "object") {
+      const dir = join(this.kaiHome, "state", "verify-secrets");
+      mkdirSync(dir, { recursive: true });
+      const path = join(dir, `${String(turnId).replace(/[^\w.-]/g, "_")}.env`);
+      secretNames = writeSecretsFile(path, turn.verifySecrets);
+      if (secretNames.length > 0) secretsFile = path;
+    }
+    const previews = preview.previews || [];
+    const runner = this.services.get(sessionId);
+    const services = runner?.describeServices?.() ?? previews.map((p) => ({ name: p.name, url: p.url }));
+    const previewOrigins = [...new Set([...services.map((s) => normalizeOrigin(s.url)), ...previews.map((p) => normalizeOrigin(p.url))].filter(Boolean))];
+    const primaryKey = (turn.repos || [])[0]?.key;
+    // The landing page is a session repo's web preview (an API has no UI to land on).
+    const webPreviews = previews.filter((p) => p.kind !== "api");
+    const landingUrl = webPreviews.find((p) => p.repo === primaryKey)?.url ?? webPreviews[0]?.url ?? previews.find((p) => p.repo === primaryKey)?.url ?? previews[0]?.url ?? services[0]?.url ?? null;
+
+    // ── sign-in: dev.yaml command → saved record → none ──────────────
+    const primary = bound?.[0] ?? null;
+    const devConfig = primary?.cwd ? readDevConfig(primary.cwd) : null;
+    const auth = devConfig?.auth ?? null;
+    // Every dev.yaml in the session (external origins, verify policy) — the
+    // primary's wins on conflicts.
+    const configs = (bound || []).map((b) => (b?.cwd ? readDevConfig(b.cwd) : null)).filter(Boolean);
+    const external = [...new Set(configs.flatMap((c) => c.external || []))];
+    // The state filter accepts the declared `external` origins too: the
+    // browser is allowed to talk to them, so a token the app keeps there is
+    // part of "signed in". Cookies stay localhost-only (filterStorageState).
+    const stateOrigins = [...new Set([...previewOrigins, ...external])];
+    let injected = null; // { source: "command" | "record", state, record?, originMap? }
+    if (auth?.storageState && primary?.cwd) {
+      const state = await this.storageStateFromCommand(auth.storageState, primary.cwd);
+      if (state) injected = { source: "command", state: filterStorageState(state, stateOrigins).state, record: null, originMap: null };
+      else this.log("warn", "verify.login.command.empty", { turnId });
+    } else if (turn.loginRecordAvailable) {
+      const record = await this.api.turnPreviewLogin(turnId).catch((err) => {
+        this.log("warn", "verify.login.record.failed", { turnId, error: err?.message });
+        return null;
+      });
+      if (record?.storageState) {
+        const originMap = buildOriginMap(record.services, services);
+        const state = rewriteStorageState(record.storageState, originMap);
+        this.log("info", "verify.login.record", { turnId, version: record.version, mapped: originMap.size, cookies: state.cookies.length, origins: state.origins.length });
+        injected = { source: "record", state, record, originMap };
+      }
+    }
+
+    // ── probe: does the preview consider us signed in? ───────────────
+    // An API-only preview (no web service) has nothing to render a login
+    // wall on — the agent's http_request answers 401/403 → needs_login.
+    let probe = { result: "unknown", storageState: null, loginPath: null };
+    const hasWebService = services.some((svc) => svc.kind !== "api") || webPreviews.length > 0;
+    if (landingUrl && hasWebService) {
+      const pw = this.loadPlaywright();
+      probe = await this.probeLogin({
+        pw,
+        launchOptions: launchOptionsFor({ headless: true, browser: channel }),
+        storageState: injected?.state ?? null,
+        url: injected?.record?.landingUrl ? rewriteUrl(injected.record.landingUrl, injected.originMap) ?? landingUrl : landingUrl,
+        previewOrigins,
+        loginPaths: injected?.record?.loginPaths ?? [],
+        loginCheck: auth?.loginCheck ?? null,
+        // A dev server that just booted still compiles its first page (vite's
+        // cold transform of a large app takes 30-60 s) — give it room, or the
+        // probe answers `unknown` and a login wall goes unnoticed.
+        timeoutMs: coldBoot ? PROBE_TIMEOUT_COLD_BOOT_MS : undefined,
+        log: this.log,
+      });
+    }
+    // "Continue without signing in" (`previewLoginOptional`) means: run
+    // unauthenticated rather than block — whether there is no record at all
+    // or the saved one no longer works.
+    if (probe.result === "needs_login" && turn.previewLoginOptional === true) {
+      this.log("info", "verify.login.optional", { turnId, hadRecord: injected !== null });
+      injected = null;
+      probe = { result: "unknown", storageState: null, loginPath: probe.loginPath };
+    }
+    if (probe.result === "needs_login") {
+      rmSync(artifactsDir, { recursive: true, force: true });
+      if (secretsFile) rmSync(secretsFile, { force: true });
+      const firstTime = injected === null;
+      return {
+        ok: false,
+        error: firstTime
+          ? "The preview asks for a sign-in. Sign in once on this device so Kai can test the app."
+          : "The saved sign-in for this preview no longer works — sign in again on this device.",
+        blocked: { blockedCode: "needs_login", ...(probe.loginPath ? { loginPath: probe.loginPath } : {}), firstTime },
+      };
+    }
+
+    // ── state files for the MCP ──────────────────────────────────────
+    let storageStateFile = null;
+    let finalStateFile = null;
+    let redact = new Set();
+    let probeExport = null;
+    if (injected && !storageStateIsEmpty(injected.state)) {
+      const dir = this.loginStateDir();
+      mkdirSync(dir, { recursive: true, mode: 0o700 });
+      const safe = String(turnId).replace(/[^\w.-]/g, "_");
+      storageStateFile = join(dir, `${safe}.json`);
+      // The persona's final `browser_storage_state` export must land INSIDE
+      // the MCP's `--output-dir`: the Playwright MCP refuses any `filename`
+      // outside its output dir / the client cwd (`File access denied …
+      // outside allowed roots`), so a path under ~/.kai/state would make the
+      // agent's last action fail on every signed-in run and the record would
+      // never refresh. A `.json` is not an artifact extension — the sweep
+      // never uploads it — and it is read before the evidence dir is deleted.
+      finalStateFile = this.finalStateFileFor(artifactsDir);
+      mkdirSync(dirname(finalStateFile), { recursive: true, mode: 0o700 });
+      // The probe context's own export (with IndexedDB) when the probe ran;
+      // the rewritten record otherwise (probe unknown → proceed anyway).
+      probeExport = probe.result === "ok" && probe.storageState ? filterStorageState(probe.storageState, stateOrigins).state : injected.state;
+      writeFileSync(storageStateFile, JSON.stringify(probeExport), { mode: 0o600 });
+      redact = new Set([...redactionSet(injected.state), ...redactionSet(probeExport)]);
+    }
+    // `.env*` values of the repos + service dirs are secrets too: a tool row
+    // that echoes one (a config dump, an error message) must not carry it
+    // to the Server.
+    for (const value of this.envRedactionValues(bound, services)) redact.add(value);
+    const allowedOrigins = [...previewOrigins, ...external, "http://localhost:*", "http://127.0.0.1:*", "https://localhost:*", "https://127.0.0.1:*"];
+    // ── API evidence: the verify MCP's request policy ───────────────
+    const apiServices = services.filter((svc) => svc.kind === "api");
+    const verifyPolicy = configs.find((c) => c.verify)?.verify ?? devConfig?.verify ?? { readOnly: null, endpoints: [], loginVia: null };
+    const readOnly = verifyPolicy.readOnly ?? apiServices.length > 0;
+    const env = {
+      KAI_VERIFY_READ_ONLY: readOnly ? "1" : "0",
+      KAI_VERIFY_ORIGINS: [...new Set([...previewOrigins, ...external])].join(";"),
+      KAI_VERIFY_EVIDENCE_DIR: artifactsDir,
+    };
+    // The app's own API credential (dev.yaml `auth.apiToken`) read from the
+    // injected sign-in → `Authorization: Bearer …` for http_request. The
+    // value goes to the MCP by env only and joins the redaction set.
+    const apiAuth = deriveApiAuthHeader(auth?.apiToken, probeExport ?? injected?.state ?? null, services);
+    if (apiAuth) {
+      env.KAI_VERIFY_AUTH_HEADER = apiAuth.value;
+      if (apiAuth.token.length >= 8) redact.add(apiAuth.token);
+    }
+    return {
+      ok: true,
+      artifactsDir,
+      secretsFile,
+      storageStateFile,
+      finalStateFile,
+      allowedOrigins,
+      previewOrigins,
+      stateOrigins,
+      external,
+      // Companions run the code they have checked out — their HEADs travel
+      // with the report so "verified" can never be claimed for a stale API.
+      companionRevisions: previews
+        .filter((p) => p.role === "companion" && p.repo && p.commit)
+        .map((p) => ({ repo: p.repo, commit: p.commit, role: "companion", ...(p.branch ? { branch: p.branch } : {}), ...(p.dirty > 0 ? { dirty: p.dirty } : {}) })),
+      ignoreHttpsErrors: !!runner?.usesHttps?.(),
+      env,
+      readOnly,
+      injected: injected ? { ...injected, probeExport } : null,
+      redact,
+      note: this.verifyPreviewNote(sessionId, previews, secretNames, artifactsDir, {
+        signedIn: !!storageStateFile,
+        finalStateFile,
+        services,
+        readOnly,
+        endpoints: verifyPolicy.endpoints || [],
+        external,
+        restartNotes,
+        apiAuth: !!apiAuth,
+      }),
+      report: null,
+    };
+  }
+
+  /**
+   * After a fix turn (`turn.changedRepos` = repo keys the fix touched):
+   * restart the changed repos' services whose reload mode is `restart`
+   * (declared, or the default for `kind: api`) on their same ports. Adopted
+   * services are the user's own dev server — never restarted, the task
+   * note says so. Returns the note lines for the agent.
+   */
+  async restartChangedServices(turn, sessionId) {
+    const changed = Array.isArray(turn.changedRepos) ? turn.changedRepos.map((k) => String(k).toLowerCase()) : [];
+    const runner = this.services.get(sessionId);
+    if (!changed.length || !runner) return [];
+    const notes = [];
+    const byRoot = new Map(); // repoRoot → { key, names }
+    for (const svc of runner.describeServices()) {
+      if (!svc.repoKey || !changed.includes(String(svc.repoKey).toLowerCase()) || !svc.repoRoot) continue;
+      const meta = runner.meta?.get(svc.name);
+      if (effectiveReload(meta?.svc, svc.kind) !== "restart") continue;
+      if (svc.adopted) {
+        notes.push(`${svc.name} is your already-running dev server and was not restarted — make sure it serves the fixed code.`);
+        continue;
+      }
+      const entry = byRoot.get(svc.repoRoot) ?? { key: svc.repoKey, names: [] };
+      entry.names.push(svc.name);
+      byRoot.set(svc.repoRoot, entry);
+    }
+    for (const [repoRoot, { key, names }] of byRoot) {
+      await this.postVerifyStage(turn.turnId, "booting", `Restarting ${names.join(", ")} with the fix…`);
+      this.log("info", "verify.restart", { turnId: turn.turnId, repo: key, services: names });
+      try {
+        const restarted = await runner.restart(repoRoot, { only: names });
+        const dead = restarted.find((r) => r.restarted && !r.ready);
+        if (dead) notes.push(`${dead.name} did not come back after the restart${dead.error ? ` — ${dead.error}` : ""} (see ${dead.logPath}).`);
+        else notes.push(`${names.join(", ")} ${names.length === 1 ? "was" : "were"} restarted with the fix.`);
+      } catch (err) {
+        this.log("warn", "verify.restart.failed", { turnId: turn.turnId, repo: key, error: err?.message });
+        notes.push(`${names.join(", ")} could not be restarted with the fix: ${err?.message}`);
+      }
+    }
+    return notes;
+  }
+
+  /** Secrets from `.env*` files at the repo roots + service cwds (values ≥ 12 chars, placeholders excluded). */
+  envRedactionValues(bound, services) {
+    const dirs = new Set([...(bound || []).map((b) => b?.cwd).filter(Boolean), ...(services || []).map((svc) => svc?.cwd).filter(Boolean)]);
+    const texts = [];
+    for (const dir of dirs) {
+      let names = [];
+      try {
+        names = readdirSync(dir).filter((n) => n === ".env" || (n.startsWith(".env.") && !/\.(example|sample|template)$/.test(n)));
+      } catch {
+        continue;
+      }
+      for (const name of names) {
+        try {
+          texts.push(readFileSync(join(dir, name), "utf8"));
+        } catch {
+          /* unreadable */
+        }
+      }
+    }
+    return envRedactionValues(texts);
+  }
+
+  /** Task suffix for the verifier: the preview URLs (web + API services), where evidence goes, the secrets by name, the sign-in state, the request policy. */
+  verifyPreviewNote(sessionId, previews, secretNames = [], artifactsDir = null, { signedIn = false, finalStateFile = null, services = null, readOnly = false, endpoints = [], external = [], restartNotes = [], apiAuth = false } = {}) {
+    const runner = this.services.get(sessionId);
+    const apiNames = new Set((services || []).filter((svc) => svc.kind === "api").map((svc) => svc.name));
+    const webPreviews = previews.filter((p) => !apiNames.has(p.name));
+    const lines = webPreviews.map((p) => {
+      const logPath = runner && !p.adopted ? join(runner.logDir, `${p.name}.log`) : null;
+      return `- ${p.repo}${p.name && p.name !== p.repo ? ` (${p.name})` : ""}: ${p.url}${p.adopted ? " (your already-running dev server)" : ""}${logPath ? ` · logs: ${logPath}` : ""}`;
+    });
+    const parts = ["", "", "This is a verification turn: do not modify files, do not commit."];
+    if (lines.length > 0) {
+      parts.push(`Dev services running for this session:\n${lines.join("\n")}`);
+      parts.push(
+        "Use the `gleap_preview` browser tools (browser_navigate, browser_snapshot, browser_start_video, browser_video_chapter, browser_take_screenshot, browser_stop_video, …) against these URLs. " +
+          "Tail the service logs with the Read/Bash tools if a page fails to load.",
+      );
+    }
+    const apiServices = (services || []).filter((svc) => svc.kind === "api");
+    if (apiServices.length > 0) {
+      const apiLines = apiServices.map((svc) => {
+        const logPath = runner && !svc.adopted ? join(runner.logDir, `${svc.name}.log`) : null;
+        return `- ${svc.repoKey ? `${svc.repoKey} (${svc.name})` : svc.name}: ${svc.url}${svc.openapi ? ` · OpenAPI: ${svc.openapi}` : ""}${svc.adopted ? " (your already-running dev server)" : ""}${logPath ? ` · logs: ${logPath}` : ""}`;
+      });
+      parts.push(
+        `API services (no UI):\n${apiLines.join("\n")}\n` +
+          `Exercise them with the \`http_request\` tool from the \`kai_verify\` MCP server (one call per check, \`check\` set to what it proves) — the HTTP transcript it records is uploaded with your report as evidence; curl is not available. ` +
+          `Resolve real paths from the OpenAPI spec (or the router files) before calling. ` +
+          (readOnly
+            ? "This run is READ-ONLY (shared database): only GET/HEAD/OPTIONS go through — anything else is refused and recorded as skipped; list such endpoints under `untested`. "
+            : "Writes are allowed in this run — prefer creating throwaway records and say what you created in the report. ") +
+          (apiAuth ? "The app's own authentication is added to your requests automatically; never paste tokens. " : "A 401/403 means the API needs a sign-in you do not have: report `blocked` / `needs_login` with the endpoint's path, never a failed check. ") +
+          (endpoints.length ? `Endpoints the repo asks you to cover: ${endpoints.join(", ")}. ` : "") +
+          (lines.length === 0 ? "There is no web UI in this run — no recording is needed; the transcript and the report are the evidence." : ""),
+      );
+    }
+    if (lines.length === 0 && apiServices.length === 0) {
+      parts.push(`Dev services running for this session:\n${previews.map((p) => `- ${p.repo}: ${p.url}`).join("\n") || "- (none)"}`);
+    }
+    if (external.length > 0) parts.push(`External origins the app talks to (allowed for the browser and http_request): ${external.join(", ")}.`);
+    if (restartNotes.length > 0) parts.push(restartNotes.join(" "));
+    if (artifactsDir) {
+      // The MCP resolves a relative `filename` against the CLIENT
+      // workspace (the repo worktree), where it would be discarded with
+      // the turn — only absolute paths under the output dir (or no
+      // filename at all) reach the evidence dir.
+      parts.push(
+        `Evidence directory: ${artifactsDir} — every screenshot and video in it is uploaded with your report. Pass every screenshot/video \`filename\` as an ABSOLUTE path inside it (e.g. \`${join(artifactsDir, "01-home.png")}\`, \`${join(artifactsDir, "verification.webm")}\`), never a bare relative name, and list the paths the tools print back in your report.`,
+      );
+    }
+    if (secretNames.length > 0) {
+      parts.push(
+        `Test credentials are available as secrets: ${secretNames.join(", ")}. Type the secret NAME into the form field (e.g. \`${secretNames[0]}\`) — the browser substitutes the real value and masks it in every response. Do not ask the user for these.`,
+      );
+    }
+    if (signedIn && finalStateFile) {
+      parts.push(
+        `The browser is already signed in to the preview (the user's saved sign-in is loaded). Final browser state path: ${finalStateFile} — as your LAST browser action, after \`browser_stop_video\` and before \`report_verification\`, call \`browser_storage_state\` with exactly this absolute path as \`filename\` so the sign-in stays fresh. ` +
+          `Never read, list or copy anything under ${this.loginStateDir()} — it is the daemon's private state. Never paste cookies, tokens or storage values into the report, todos or summary.`,
+      );
+    } else {
+      parts.push(
+        "If a page asks you to sign in (password field, one-time code, a Sign in / Log in button, a redirect to an identity provider) and no secrets are listed, do not ask the user and do not type into the form: stop the video, screenshot the wall, and file `report_verification` with `status: blocked`, `blockedCode: needs_login` and `loginPath` set to the wall's URL path.",
+      );
+    }
+    parts.push("If the change has nothing a tester can exercise from the running app, file `report_verification` with `status: blocked` and `blockedCode: not_verifiable` — never invent a check. A `passed` report needs at least one real check.");
+    return parts.join("\n\n").replace(/^\n\n\n\n/, "\n\n");
+  }
+
+  /**
+   * After a verify turn: sweep the evidence dir (the agent may have
+   * forgotten the recording), upload every file, then post the report
+   * with URLs in place of paths (redacted: nothing from the injected
+   * sign-in may leak). No report from the agent → `blocked` with the swept
+   * evidence; a report with zero checks → `blocked` / `no_report` (the
+   * payload builder). A turn CANCELLED before any report skips the uploads
+   * altogether (nobody asked for that footage). `evidence: { failed, kept }`
+   * tells the Server how many uploads failed and where the files still are
+   * (`bridge.verify.evidence.retry` re-uploads them). Then, when a saved
+   * sign-in was injected and the agent left its final `browser_storage_state`
+   * export, refresh the record (CAS on the version we read). The dir is
+   * deleted only when everything landed; otherwise it stays for the retry /
+   * `kai-bridge doctor`.
+   */
+  async finishVerification(turn, verify, res, cancelled) {
+    const { turnId } = turn;
+    await this.postVerifyStage(turnId, "saving");
+    const redact = verify.redact?.size ? (v) => redactDeep(v, verify.redact) : (v) => v;
+    const report = verify.report ? redact(verify.report) : null;
+    // Verify turns never push, so the Server cannot derive the tested heads
+    // from `changes[]` — stamp them here (repo key → HEAD of the checkout).
+    // Companions booted alongside carry `role: "companion"` (their HEAD is
+    // the code the API under test actually served).
+    const revisions = [
+      ...(verify.bound || [])
+        .map((b) => ({ repo: b.key, commit: currentHead(b.cwd) }))
+        .filter((r) => r.repo && r.commit),
+      ...(verify.companionRevisions || []),
+    ];
+    const fallbackReason = cancelled
+      ? "The verification was cancelled before Kai filed a report."
+      : res.code !== 0
+        ? `The verification turn failed${res.lastError ? `: ${res.lastError.replace(/^acp-runner: /, "").slice(0, 300)}` : ""}.`
+        : "Kai finished without filing a verification report";
+    let uploads = [];
+    let uploadFailures = 0;
+    if (cancelled && !report) {
+      this.log("info", "verify.cancelled.no_uploads", { turnId });
+    } else {
+      const swept = await this.uploadSweptEvidence(turnId, verify.artifactsDir, { report, redact: verify.redact, workDir: verify.workDir, signedIn: !!verify.storageStateFile });
+      uploads = swept.uploads;
+      uploadFailures = swept.failed;
+    }
+    const evidence = { failed: uploadFailures, ...(uploadFailures > 0 ? { kept: verify.artifactsDir } : {}) };
+    const payload = redact({ ...buildVerificationPayload(report, uploads, { fallbackReason, cancelled, evidence, readOnly: typeof verify.readOnly === "boolean" ? verify.readOnly : null }), revisions });
+    let reported = false;
+    try {
+      await this.api.turnVerification(turnId, payload, {
+        onRetry: (err, attempt, delay) => this.log("warn", "verify.report.retry", { turnId, attempt, nextInMs: delay, error: err.message }),
+      });
+      reported = true;
+    } catch (err) {
+      this.log("error", "verify.report.failed", { turnId, error: err.message });
+    }
+    this.log("info", "verify.reported", { turnId, status: payload.status, blockedCode: payload.blockedCode, checks: payload.checks.length, artifacts: uploads.length, uploadFailures, reported });
+    // The final-state export lives in the evidence dir: refresh the record
+    // from it BEFORE the dir is deleted.
+    await this.refreshPreviewLogin(turn, verify);
+    if ((reported && uploadFailures === 0) || (cancelled && !report)) rmSync(verify.artifactsDir, { recursive: true, force: true });
+    else this.log("warn", "verify.artifacts.kept", { turnId, dir: verify.artifactsDir });
+    return { status: payload.status };
+  }
+
+  /**
+   * A preview that Verify booted for itself is released once the run has
+   * settled — a manual preview keeps running until the user stops it. A
+   * `failed` run with fix attempts left keeps the app up: the fix turn's
+   * auto re-verify is seconds away and the Server restarts changed services.
+   */
+  async settleVerifyPreview(turn, status) {
+    const sessionId = turn?.sessionId;
+    if (!sessionId || !this.verifyOwnedPreviews?.has(sessionId)) return false;
+    if (this.manualPreviews?.has(sessionId)) return false;
+    const loop = turn.loop && typeof turn.loop === "object" ? turn.loop : null;
+    const retryPending = status === "failed" && loop && Number(loop.attempt ?? 0) < Number(loop.max ?? 0);
+    if (retryPending) return false;
+    this.log("info", "verify.preview.released", { sessionId, status });
+    await this.previewStop({ sessionId });
+    return true;
+  }
+
+  /**
+   * Sweep an evidence dir, union it with the report's declared artifacts,
+   * redact the HTTP transcript in place, upload everything. Resolves
+   * `{ uploads: [{ artifact, url }], failed }`. Trace archives are dropped
+   * from signed-in runs (they contain every request with its cookies).
+   */
+  async uploadSweptEvidence(turnId, artifactsDir, { report = null, redact = null, workDir = null, signedIn = false } = {}) {
+    const swept = sweepArtifacts(artifactsDir).filter((p) => !(signedIn && /\.zip$/i.test(p)));
+    const artifacts = unionArtifacts(report, swept, { outputDir: artifactsDir, workDir }).filter((a) => !(signedIn && a.kind === "trace"));
+    const uploads = [];
+    let failed = 0;
+    for (const artifact of artifacts) {
+      if (artifact.kind === "requests") redactJsonlFile(artifact.path, redact);
+      try {
+        const { url } = await this.api.uploadArtifact(turnId, artifact.path, artifact.contentType, {
+          onRetry: (err, attempt, delay) => this.log("warn", "verify.upload.retry", { turnId, file: artifact.path, attempt, nextInMs: delay, error: err.message }),
+        });
+        uploads.push({ artifact, url });
+      } catch (err) {
+        failed += 1;
+        this.log("warn", "verify.upload.failed", { turnId, file: artifact.path, error: err.message });
+      }
+    }
+    return { uploads, failed, swept: swept.length };
+  }
+
+  /**
+   * `bridge.verify.evidence.retry { turnId }`: the evidence dir kept after
+   * failed uploads is swept and uploaded again; the Server unions the
+   * artifacts by URL (`PUT …/verification/artifacts`) and clears
+   * `evidenceMissing`. The dir goes once everything landed.
+   */
+  async retryEvidence({ commandId, turnId }) {
+    const ack = (payload) => (commandId ? this.api.commandAck(commandId, payload).catch((err) => this.log("warn", "verify.evidence.ack.failed", { turnId, error: err?.message })) : Promise.resolve());
+    if (!turnId) return ack({ ok: false, error: "evidence retry without a turnId" });
+    const dir = join(this.kaiHome, "artifacts", String(turnId).replace(/[^\w.-]/g, "_"));
+    if (!existsSync(dir)) {
+      this.log("warn", "verify.evidence.retry.missing", { turnId, dir });
+      return ack({ ok: false, error: "The evidence for this run is no longer on this machine." });
+    }
+    const { uploads, failed, swept } = await this.uploadSweptEvidence(turnId, dir);
+    const artifacts = uploads.map((u) => ({ label: u.artifact.label, url: u.url, contentType: u.artifact.contentType, kind: u.artifact.kind, ...(u.artifact.count > 0 ? { count: u.artifact.count } : {}) }));
+    const evidence = { failed, ...(failed > 0 ? { kept: dir } : {}) };
+    try {
+      await this.api.putVerificationArtifacts(turnId, { artifacts, evidence });
+    } catch (err) {
+      this.log("error", "verify.evidence.retry.failed", { turnId, error: err?.message });
+      return ack({ ok: false, error: err?.message || String(err), uploaded: artifacts.length, failed });
+    }
+    this.log("info", "verify.evidence.retried", { turnId, swept, uploaded: artifacts.length, failed });
+    if (failed === 0) rmSync(dir, { recursive: true, force: true });
+    return ack({ ok: true, uploaded: artifacts.length, failed });
+  }
+
+  /**
+   * The agent's final `browser_storage_state` export (cookies + localStorage
+   * — what the app may have rotated during the run) merged over the probe
+   * export's IndexedDB, filtered to the preview origins, mapped BACK onto
+   * the record's captured origins, and PUT with the version we read. 409 =
+   * another run refreshed first → ours is discarded. Only for injected
+   * records (a dev.yaml command owns its own state).
+   */
+  async refreshPreviewLogin(turn, verify) {
+    const { turnId } = turn;
+    const record = verify.injected?.record;
+    if (!record?.id || verify.injected.source !== "record" || !verify.finalStateFile) return;
+    let final;
+    try {
+      if (!existsSync(verify.finalStateFile)) {
+        this.log("info", "verify.login.refresh.skipped", { turnId, reason: "no final state" });
+        return;
+      }
+      final = JSON.parse(readFileSync(verify.finalStateFile, "utf8"));
+    } catch (err) {
+      this.log("warn", "verify.login.refresh.unreadable", { turnId, error: err?.message });
+      return;
+    }
+    const merged = mergeFinalState(verify.injected.probeExport, final);
+    const { state: filtered, counts } = filterStorageState(merged, verify.stateOrigins ?? verify.previewOrigins);
+    const back = rewriteStorageState(filtered, invertOriginMap(verify.injected.originMap));
+    if (storageStateIsEmpty(back)) {
+      this.log("info", "verify.login.refresh.skipped", { turnId, reason: "empty state" });
+      return;
+    }
+    try {
+      await this.api.refreshPreviewLogin(record.id, { storageState: back, basedOnVersion: record.version });
+      this.log("info", "verify.login.refreshed", { turnId, recordId: record.id, basedOnVersion: record.version, ...counts });
+    } catch (err) {
+      this.log(err?.status === 409 ? "info" : "warn", err?.status === 409 ? "verify.login.refresh.stale" : "verify.login.refresh.failed", { turnId, recordId: record.id, error: err?.message });
+    }
+  }
+
+  // ── sign-in windows (bridge.verify.login.*) ────────────────────────
+  /**
+   * Open a headed Chrome at the preview for the user to sign in; the
+   * capture uploads the filtered storage state against `requestId`. Acks
+   * `{ ok: true, opened: true }` once the window is up, `{ ok: false,
+   * error }` when this machine cannot (updating, no display, preview dead).
+   * Idempotent per requestId (the Server replays after sleep).
+   */
+  async loginStart({ commandId, requestId, sessionId, repoKey, previewNeeded, title, repos }) {
+    const ack = (payload) => (commandId ? this.api.commandAck(commandId, payload).catch((err) => this.log("warn", "verify.login.ack.failed", { requestId, error: err?.message })) : Promise.resolve());
+    const status = (payload) => this.api.previewLoginStatus(requestId, payload).catch((err) => this.log("warn", "verify.login.status.failed", { requestId, error: err?.message }));
+    if (!requestId) {
+      await ack({ ok: false, error: "Sign-in request without a requestId." });
+      return;
+    }
+    if (this.logins.has(requestId)) {
+      await ack({ ok: true, opened: true, replayed: true });
+      return;
+    }
+    const entry = { requestId, sessionId, repoKey, handle: null, startedAt: Date.now() };
+    this.logins.set(requestId, entry);
+    try {
+      if (this.updating) throw new Error("This machine is updating kai-bridge — try again in a minute.");
+      if (!this.displayAvailable()) throw new Error("This machine has no display to open a sign-in window on.");
+      const pw = this.loadPlaywright();
+      if (!pw?.chromium) throw new Error("Playwright is not installed next to kai-bridge — reinstall @gleapai/kai-bridge.");
+      const browser = await this.ensurePreviewBrowser().catch((err) => ({ ok: false, error: err?.message }));
+      if (!browser?.ok) throw new Error(browser?.error || "No browser is available on this machine.");
+      // Liveness first: booting a cold preview can take minutes, and the
+      // Server fails a request nobody acknowledged as "device unreachable".
+      // `accepted` moves the request off pending without claiming a window.
+      await ack({ ok: true, accepted: true });
+      // The preview must be up for the user to sign in to — boot it (or,
+      // when it already runs, only re-describe it: previewStart is
+      // idempotent on a live runner and we need its URLs either way).
+      // `repos`/`title` may be absent on the command; then the request's
+      // repo is the whole session and the worktree is looked up by id.
+      const sessionRepos = Array.isArray(repos) && repos.length ? repos : [{ key: repoKey }];
+      this.log("info", "verify.login.preview", { requestId, sessionId, previewNeeded: !!previewNeeded, live: this.services.has(sessionId) });
+      const preview = await this.previewStart({ sessionId, title, repos: sessionRepos });
+      if (preview?.status !== "running") throw new Error(preview?.error ? `The preview could not be started: ${preview.error}` : "The preview could not be started.");
+      entry.previews = preview.previews || [];
+      const runner = this.services.get(sessionId);
+      const services = runner?.describeServices?.() ?? (entry.previews || []).map((p) => ({ name: p.name, url: p.url }));
+      const previewOrigins = [...new Set([...services.map((s) => normalizeOrigin(s.url)), ...(entry.previews || []).map((p) => normalizeOrigin(p.url))].filter(Boolean))];
+      // dev.yaml `external` origins may hold part of the app's own sign-in
+      // state — keepable, but never "back on the app" for the detection.
+      const external = [...new Set([...new Set((services || []).map((s) => s.repoRoot).filter(Boolean))].flatMap((root) => readDevConfig(root)?.external || []))];
+      const url = (entry.previews || []).find((p) => p.repo === repoKey)?.url ?? (entry.previews || [])[0]?.url ?? services[0]?.url;
+      if (!url) throw new Error("The preview has no URL to open.");
+      // Keep the preview alive while the window is open (the idle timer
+      // would otherwise stop the app under the user's nose).
+      this.armPreviewIdleTimer(sessionId);
+      const handle = await this.captureLogin({
+        pw,
+        launchOptions: launchOptionsFor({ headless: false, browser: browser.browser === "chrome" ? "chrome" : null }),
+        url,
+        previewOrigins,
+        stateOrigins: [...previewOrigins, ...external],
+        services: services.map((s) => ({ name: s.name, origin: normalizeOrigin(s.url) })),
+        onStatus: (st, extra) => {
+          this.log("info", "verify.login.status", { requestId, status: st, ...(extra?.error ? { error: extra.error } : {}) });
+          return status({ status: st, ...(extra?.error ? { error: String(extra.error) } : {}) });
+        },
+        onSaved: async (payload, counts) => {
+          await this.api.uploadPreviewLogin(requestId, payload, {
+            tries: 3,
+            onRetry: (err, attempt, delay) => this.log("warn", "verify.login.upload.retry", { requestId, attempt, nextInMs: delay, error: err.message }),
+          });
+          this.log("info", "verify.login.saved", { requestId, repoKey, ...counts, loginPaths: payload.loginPaths.length });
+        },
+        log: this.log,
+      });
+      void handle.finished.then((outcome) => {
+        this.logins.delete(requestId);
+        this.log("info", "verify.login.finished", { requestId, status: outcome?.status, error: outcome?.error });
+        this.hello().catch(() => {});
+        if ((this.updatePending || this.restartPending) && this.running.size === 0 && this.logins.size === 0) void this.checkForUpdate();
+      });
+      if (entry.cancelled) {
+        // Cancelled while Chrome was still launching (the Server has already
+        // settled the request): close the window it just opened, no ack of
+        // `opened`, no status (the cancel already answered).
+        this.log("info", "verify.login.cancelled.launching", { requestId });
+        await handle.cancel();
+        await ack({ ok: false, error: "The sign-in was cancelled before the window opened." });
+        return;
+      }
+      entry.handle = handle;
+      await ack({ ok: true, opened: true });
+      await status({ status: "opened" });
+      // Re-announce right away: `activeLogins` is how the dashboard knows a window is open.
+      await this.hello().catch((err) => this.log("warn", "verify.login.hello.failed", { requestId, error: err?.message }));
+    } catch (err) {
+      this.logins.delete(requestId);
+      this.log("error", "verify.login.start.failed", { requestId, error: err?.message });
+      await ack({ ok: false, error: err?.message || String(err) });
+      await status({ status: "failed", error: err?.message || String(err) });
+    }
+  }
+
+  /** "Mark done": export whatever the window holds now (the heuristic may have missed the sign-in). */
+  async loginDone({ commandId, requestId }) {
+    try {
+      const entry = this.logins.get(requestId);
+      if (!entry?.handle) throw new Error("No sign-in window is open for this request on this machine.");
+      await entry.handle.done();
+      if (commandId) await this.api.commandAck(commandId, { ok: true });
+    } catch (err) {
+      this.log("warn", "verify.login.done.failed", { requestId, error: err?.message });
+      if (commandId) await this.api.commandAck(commandId, { ok: false, error: err?.message || String(err) }).catch(() => {});
+    }
+  }
+
+  async loginCancel({ commandId, requestId }) {
+    try {
+      const entry = this.logins.get(requestId);
+      if (!entry) throw new Error("No sign-in window is open for this request on this machine.");
+      if (entry.handle) await entry.handle.cancel();
+      // Still launching: loginStart closes the window as soon as it is up.
+      else entry.cancelled = true;
+      if (commandId) await this.api.commandAck(commandId, { ok: true });
+    } catch (err) {
+      this.log("warn", "verify.login.cancel.failed", { requestId, error: err?.message });
+      if (commandId) await this.api.commandAck(commandId, { ok: false, error: err?.message || String(err) }).catch(() => {});
+    }
+  }
+
+  /** Close every sign-in window matching `filter` (session close, shutdown). */
+  async teardownLogins(filter, reason) {
+    if (!this.logins?.size) return;
+    const victims = [...this.logins.values()].filter((l) => {
+      try {
+        return filter(l);
+      } catch {
+        return false;
+      }
+    });
+    for (const l of victims) {
+      this.log("info", "verify.login.teardown", { requestId: l.requestId, reason });
+      this.logins.delete(l.requestId);
+      l.cancelled = true; // still launching → loginStart closes it on arrival
+      await l.handle?.cancel?.().catch(() => {});
+    }
+  }
+
+  /**
+   * Mid-turn steering: forward the message to the running runner's stdin
+   * control channel. The runner answers with a `steer` turn event
+   * (outcome injected / promptRequired / …) that rides the normal event
+   * batcher. When the turn is not running here (already ended, never
+   * started, laptop was asleep) we answer `promptRequired` ourselves so
+   * the Server queues the message for the next turn instead of waiting
+   * for its timeout.
+   */
+  async steerTurn({ turnId, steer }) {
+    const id = String(steer?.id || "");
+    const text = typeof steer?.text === "string" ? steer.text : "";
+    if (!turnId || !id || !text.trim()) return;
+    const entry = this.running.get(turnId);
+    const delivered = entry?.control ? entry.control({ type: "steer", id, text }) : false;
+    this.log("info", delivered ? "turn.steer" : "turn.steer.miss", { turnId, id, running: !!entry });
+    if (delivered) return;
+    await this.api
+      .turnEvents(turnId, [{ type: "steer", id, outcome: "promptRequired" }])
+      .catch((err) => this.log("warn", "turn.steer.report.failed", { turnId, id, error: err?.message }));
   }
 
   /**
@@ -1052,21 +2388,70 @@ export class BridgeDaemon {
     return { note: notes.join(""), hasLivePreview: previews.length > 0 };
   }
 
-  async cloneRepo({ commandId, remote, name }) {
+  /**
+   * Clone `remote` into the preferred root as `name`. Hardened for
+   * unattended runs: no credential prompts (`GIT_TERMINAL_PROMPT=0`,
+   * `GIT_ASKPASS=echo`), stderr captured for the error, bounded by
+   * `timeoutMs` (default 3 min). Resolves the checkout path; throws an Error
+   * carrying `.target` and the stderr tail. As a command handler
+   * (`bridge.repo.clone`) it acks ok/error instead of throwing.
+   */
+  async cloneRepo({ commandId, remote, name, timeoutMs = CLONE_TIMEOUT_MS }) {
     // 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);
-    });
+    const fail = async (err) => {
+      if (commandId) {
+        await this.api.commandAck(commandId, { ok: false, error: err.message, ...(err.cloneCommand ? { cloneCommand: err.cloneCommand } : {}) }).catch(() => {});
+        return null;
+      }
+      throw err;
+    };
+    if (!root) return fail(new Error("No scan root to clone into — add one with `kai-bridge repo roots add <dir>`."));
+    const target = join(root, String(name || "").replace(/[^\w.-]/g, "-") || "repo");
+    if (existsSync(target)) {
+      const err = new Error(`${target} already exists — remove it or point Gleap at it (Locate…).`);
+      err.target = target;
+      return fail(err);
+    }
+    try {
+      await new Promise((resolve, reject) => {
+        const p = spawn("git", ["clone", remote, target], {
+          stdio: ["ignore", "ignore", "pipe"],
+          env: { ...process.env, GIT_TERMINAL_PROMPT: "0", GIT_ASKPASS: "echo", SSH_ASKPASS: "echo", GIT_SSH_COMMAND: process.env.GIT_SSH_COMMAND || "ssh -o BatchMode=yes" },
+        });
+        let stderr = "";
+        p.stderr.on("data", (d) => {
+          stderr = `${stderr}${d}`.slice(-4000);
+        });
+        const timer = setTimeout(() => {
+          try {
+            p.kill("SIGTERM");
+          } catch {}
+          reject(Object.assign(new Error(`git clone timed out after ${Math.round(timeoutMs / 60_000)} minutes`), { target, stderr }));
+        }, timeoutMs);
+        p.on("close", (code) => {
+          clearTimeout(timer);
+          if (code === 0) return resolve();
+          const tail = stderr.trim().split("\n").filter(Boolean).slice(-2).join(" · ").slice(0, 300);
+          reject(Object.assign(new Error(`git clone exited ${code}${tail ? ` — ${tail}` : ""}`), { target, stderr, code }));
+        });
+        p.on("error", (err) => {
+          clearTimeout(timer);
+          reject(Object.assign(err, { target }));
+        });
+      });
+    } catch (err) {
+      this.log("error", "repo.clone.failed", { remote, target, error: err.message });
+      rmSync(target, { recursive: true, force: true });
+      err.cloneCommand = buildCloneCommand({ remote, target });
+      return fail(err);
+    }
     await this.scanRepos();
-    await this.hello();
+    await this.hello().catch(() => {});
     if (commandId) await this.api.commandAck(commandId, { ok: true, path: target });
+    return target;
   }
 
   /**