@hover-dev/core 0.15.0 → 0.17.0

package/dist/service.js

@@ -10,75 +10,133 @@
  *     { type: 'hello',           payload: { agentId, model, version } }
  *     { type: 'event',           payload: InvokeEvent }              // see agents/types.ts
  *     { type: 'cdp-status',      payload: { state, reason?, matchingTabUrl?, browser?, launching? } }
- *     { type: 'specs-list',      payload: { specs: SpecSummary[] } }
- *     { type: 'seeds-list',      payload: { seeds: { name, note, signature, code, source }[] } }
  *     { type: 'spec-saved',      payload: { name, path } }
  *     { type: 'spec-exists',     payload: { slug, existingPath } }
- *     { type: 'case-csv-saved',  payload: { name, path } }
- *     { type: 'case-csv-exists', payload: { slug, existingPath } }
  *     { type: 'error',           payload: { message } }
  *
  *   client → server
- *     { type: 'command',       payload: { text, sessionId?, reRecord?: { slug } } }
- *                                                  // when reRecord.slug is set, the
- *                                                  // service collects tool_use events
- *                                                  // into a step list and on a clean
- *                                                  // session_end overwrites
- *                                                  // __vibe_tests__/<slug>.spec.ts
+ *     { type: 'command',       payload: { text, sessionId? } }
  *     { type: 'cancel' }
- *     { type: 'check-cdp',     payload: { pageUrl } }                 // "is this widget in the debug Chrome?"
  *     { type: 'launch-chrome', payload: { pageUrl } }                 // start debug Chrome, navigate to pageUrl
- *     { type: 'focus-debug',   payload: { pageUrl } }                 // bringToFront the matching tab in debug Chrome
  *     { type: 'save-spec',     payload: { name, description, steps, assertions?, overwrite? } }
- *     { type: 'save-case-csv', payload: { name, description, steps, assertions?, jiraProjectKey?, labels?, overwrite? } }
- *     { type: 'list-specs' }                                            // ask for every spec under __vibe_tests__/, with parsed JSDoc headers
- *     { type: 'list-seeds' }                                            // ask for built-in + .hover/rules/ translation seeds (read-only)
- *     { type: 'list-agents' }                                          // ask for the full agent registry + install status
  *     { type: 'switch-agent',  payload: { agentId } }                  // set the service's current agent; broadcasts to all connections
+ *     { type: 'reveal-source', payload: { source } }                   // relay a data-hover-source value to other clients (F2 page→editor)
  *
  *   server → client (in addition to those documented in the file body):
+ *     { type: 'reveal-source', payload: { source } }                   // relayed to non-origin clients (the VSCode ext jumps the editor)
  *     { type: 'agents',        payload: { current: string, available: AgentAvailability[] } }
  *     { type: 'modes',         payload: { current: string|null, available: ModeEntry[] } }
  *     { type: '<plugin-namespaced>', payload: <plugin-specific> }
  *
  *   client → server (plugin-aware additions):
  *     { type: 'set-mode',      payload: { modeId: string|null } }   // null = exit moded operation
- *     { type: 'list-modes' }
  */
 import { WebSocketServer, WebSocket } from 'ws';
+import { fileURLToPath } from 'node:url';
+import { dirname, join, resolve } from 'node:path';
+import { runDir } from './specs/sidecar.js';
+import { readdirSync, statSync, mkdirSync, readFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
 import { runSession } from './runSession.js';
 import { readConventions } from './service/conventions.js';
 import { optimizeSpecWithAgent } from './specs/optimizeSpecWithAgent.js';
-import { promoteOptimized, discardOptimized } from './specs/optimizeSpec.js';
+import { parseRunFailures } from './specs/runFailures.js';
+import { buildHealPrompt, healLabel } from './specs/healPrompt.js';
 import { listAgentAvailability, pickPrimaryAgent, } from './agents/detect.js';
 import { getAgent } from './agents/registry.js';
 import { getPreflight, invalidatePreflight } from './playwright/preflightCache.js';
-import { resolveMcpConfig } from './playwright/resolveMcpConfig.js';
-import { launchDebugChrome } from './playwright/launchChrome.js';
-import { listSpecs } from './specs/listSpecs.js';
-import { readSeeds, BUILTIN_SEEDS } from './specs/seeds.js';
+import { resolveMcpConfig, mcpToolPrefix } from './playwright/resolveMcpConfig.js';
+import { launchDebugChrome, closeDebugChrome } from './playwright/launchChrome.js';
+import { writeSessionRecord, parseFindings, tallyTools } from './sessions/sessions.js';
+import { resolveModeBehavior, isBuiltinMode, BUILTIN_MODES } from './modes.js';
+import { CJK_RE, ZH_OUTPUT_DIRECTIVE, GROUNDED_ACTUATION_DENY, REPORTING_DIRECTIVE, NARRATION_DIRECTIVE, ASK_FORMAT_DIRECTIVE, EXPLORATION_CHECKPOINT_DIRECTIVE, GROUNDED_ACTUATION_DIRECTIVE, RECON_DIRECTIVE, QA_EXPLORATION_DIRECTIVE, QA_VERIFY_DEFER_SECURITY_DIRECTIVE, } from './agentDirectives.js';
+import { loadMemory, formatMemoryForPrompt, writeFact } from './memory/businessMemory.js';
+import { writeQaReport } from './qa/qaReport.js';
+import { finalizeCandidates } from './qa/candidates.js';
+import { QA_INTENSITY, asQaIntensity, qaBudgetDirective } from './qa/intensity.js';
+import { classifyInstruction } from './qa/classify.js';
 import { send, sendIfOpen } from './service/types.js';
+import { handleRelayMessage } from './service/relayHandlers.js';
 import { buildCdpHint, buildCdpHintResume } from './service/cdpHint.js';
-import { handleCheckCdp, handleLaunchChrome, handleFocusDebug, } from './service/cdpHandlers.js';
-import { handleSaveArtifact, SPEC_CONFIG, CASE_CSV_CONFIG, } from './service/saveHandlers.js';
+import { handleLaunchChrome, } from './service/cdpHandlers.js';
+import { handleSaveArtifact, SPEC_CONFIG, } from './service/saveHandlers.js';
 import { CURRENT_API_VERSION, } from './plugin-api.js';
+/** Tools whose steps crystallize to a replayable line (grounded actuations +
+ *  navigation). Used to build a FALLBACK QA candidate from a completed run when
+ *  the agent never called record_candidate — so crystallization doesn't depend
+ *  on the agent's compliance. Structural typing avoids a SkillStep import. */
+const CRYSTALLIZABLE_TOOLS = new Set([
+    'click_control', 'fill_control', 'select_control', 'check_control',
+    'upload_file', 'assert_visible', 'browser_navigate',
+]);
+function bareToolName(tool) {
+    return tool.replace(/^mcp__[a-z0-9_-]+?__/, '');
+}
+function isCrystallizableStep(s) {
+    return s.kind === 'step' && !!s.tool && !s.isError && CRYSTALLIZABLE_TOOLS.has(bareToolName(s.tool));
+}
+/** A real interaction (not just navigation) — so a fallback candidate isn't a
+ *  lone goto with nothing to replay. */
+function isRealAction(s) {
+    return !!s.tool && bareToolName(s.tool) !== 'browser_navigate';
+}
+/** The source-reader MCP server (codeContext). Id → the `mcp__hoversource`
+ *  tool prefix; script path resolved relative to this module so it works from
+ *  dist/. Spawned only when codeContext is enabled. */
+const SOURCE_MCP_ID = 'hoversource'; // no hyphen — see CONTROL_MCP_ID note below
+const SOURCE_MCP_SCRIPT = resolve(dirname(fileURLToPath(import.meta.url)), 'mcp', 'sourceServer.js');
+/** The control-actuation MCP server (always on) — force-toggles sr-only hidden
+ *  radios/checkboxes the locked-down Playwright `browser_click` can't actuate. */
+// NOTE: no hyphen. Claude forms MCP tool names as `mcp__<config-id>__<tool>`
+// keeping the id verbatim, but our allow-list prefix sanitizes non-alphanumerics
+// to `_` (mcpToolPrefix). A hyphenated id ('hover-control') yields allow
+// `mcp__hover_control` which does NOT prefix-match the tool `mcp__hover-control__*`,
+// so every actuation call gets denied by the hard sandbox. Keep it alphanumeric.
+const CONTROL_MCP_ID = 'hovercontrol';
+const CONTROL_MCP_SCRIPT = resolve(dirname(fileURLToPath(import.meta.url)), 'mcp', 'actuateServer.js');
 // ClientMessage + send moved to ./service/types.ts so the cdp + save
 // handler modules can share them. See those files for the wire shape.
 const PROTOCOL_VERSION = 1;
 const PORT_RETRIES = 10;
-/** CJK-presence test — mirrors voice.js's detectLanguage. Any Han character
- *  in the prompt flips the agent's prose output to Chinese. */
-const CJK_RE = /[一-鿿]/;
-/** Appended to the agent's system prompt when the user's prompt contains CJK,
- *  so the human-facing prose (verification summary / ## Findings / step
- *  narration) comes back in Chinese — matching how Voice mode picks a Chinese
- *  TTS voice for the same prompt. Deliberately scoped to PROSE only: the agent
- *  must still use the page's real (often English) accessible names, labels,
- *  and selectors when driving the browser. */
-const ZH_OUTPUT_DIRECTIVE = '用户使用中文下达指令。请用简体中文撰写所有面向用户的文字输出：验证结论摘要、' +
-    '`## Findings` 区块（bug / 问题 / 备注）、以及每一步的中文描述。' +
-    '注意：这只影响你写给用户看的文字。操作浏览器时仍要使用页面真实的（通常是英文的）' +
-    '角色名、标签、可访问名称和选择器——不要把它们翻译成中文。';
+/** An isolated, empty cwd for the agent when the user picks "Isolated" memory.
+ *  `claude` keys its auto-memory by the absolute cwd path and discovers CLAUDE.md
+ *  by walking up from cwd — so running in a throwaway temp dir (no .git / no
+ *  ancestor CLAUDE.md) loads NONE of the user's project memory or CLAUDE.md,
+ *  while their ~/.claude credentials (OAuth) stay intact. The default ("shared")
+ *  keeps cwd = devRoot so the agent gets the project's context. */
+function isolatedAgentCwd() {
+    const dir = resolve(tmpdir(), 'hover-agent-cwd');
+    try {
+        mkdirSync(dir, { recursive: true });
+    }
+    catch { /* best-effort */ }
+    return dir;
+}
+/** The most-recently-written `.png` in a directory (by mtime), or null. Used to
+ *  resolve which screenshot a `browser_take_screenshot` just produced — the
+ *  agent often lets the MCP auto-name the file, so the name isn't in the tool
+ *  input; the freshest png in the run's output dir is it. Best-effort: never
+ *  throws (a missing dir / race just yields null). */
+function newestPng(dir) {
+    try {
+        let best = null;
+        let bestMtime = -1;
+        for (const f of readdirSync(dir)) {
+            if (!f.toLowerCase().endsWith('.png'))
+                continue;
+            const p = resolve(dir, f);
+            const mtime = statSync(p).mtimeMs;
+            if (mtime > bestMtime) {
+                bestMtime = mtime;
+                best = p;
+            }
+        }
+        return best;
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Try to bind a WebSocketServer to <host>:<port>. Resolves with the wss on
  * success; rejects with the bind error (typically EADDRINUSE) on failure.
@@ -129,11 +187,6 @@ export async function startService(opts) {
     const preferred = opts.agentId ?? process.env.HOVER_AGENT;
     const primary = await pickPrimaryAgent(preferred);
     let currentAgentId = primary?.descriptor.id ?? preferred ?? 'claude';
-    // Optional model API key the widget supplied (set-api-key). Held in memory
-    // for this service's lifetime only — never written to disk, never logged.
-    // Injected into the spawned CLI's env so a user without a logged-in
-    // subscription can drive Hover on their own key.
-    let currentApiKey = process.env.ANTHROPIC_API_KEY ?? process.env.OPENAI_API_KEY ?? undefined;
     if (!primary) {
         // Nothing installed — still bind so the widget can show a helpful
         // "install one of these" dialog. Commands will fail with
@@ -145,15 +198,56 @@ export async function startService(opts) {
     else if (preferred && preferred !== primary.descriptor.id) {
         process.stderr.write(`[hover] requested agent "${preferred}" is not installed; falling back to "${primary.descriptor.id}".\n`);
     }
-    const model = opts.model ?? 'sonnet';
+    let model = opts.model ?? 'sonnet';
+    // Reasoning-effort level for runs (set via set-effort; undefined = agent/model
+    // default). Threaded into invokeAgent alongside model.
+    let currentEffort = opts.effort;
+    // Local LLM endpoint (set via set-local-endpoint): when the qwen agent is
+    // active, this OpenAI-compatible base URL is injected so qwen drives the
+    // user's self-hosted model instead of a hosted one.
+    let currentLocalBaseUrl;
+    // BYOK (set via set-byok): when present, runs are driven by the protocol's
+    // matching CLI with the user's key + base URL + model injected via env,
+    // instead of the local-CLI agent's own logged-in auth. null = use the CLI.
+    let currentByok = null;
+    // Protocol → CLI: Anthropic drives claude (hard sandbox), Gemini drives the
+    // gemini CLI, OpenAI / Azure / OpenAI-compatible gateways drive codex.
+    const byokAgentFor = (protocol) => protocol === 'anthropic' ? 'claude' : protocol === 'gemini' ? 'gemini' : 'codex';
+    // Protocol → auth env vars the matching CLI reads. Only set what's provided
+    // so an empty base URL leaves the CLI on its own default endpoint.
+    const byokEnvFor = (b) => {
+        const env = {};
+        if (b.protocol === 'anthropic') {
+            if (b.apiKey)
+                env.ANTHROPIC_API_KEY = b.apiKey;
+            if (b.baseUrl)
+                env.ANTHROPIC_BASE_URL = b.baseUrl;
+        }
+        else if (b.protocol === 'gemini') {
+            if (b.apiKey) {
+                env.GEMINI_API_KEY = b.apiKey;
+                env.GOOGLE_API_KEY = b.apiKey;
+            }
+            if (b.baseUrl)
+                env.GOOGLE_GEMINI_BASE_URL = b.baseUrl;
+        }
+        else {
+            // openai / azure / gateways — OpenAI-compatible, driven via codex.
+            if (b.apiKey)
+                env.OPENAI_API_KEY = b.apiKey;
+            if (b.baseUrl)
+                env.OPENAI_BASE_URL = b.baseUrl;
+        }
+        return env;
+    };
     // No default budget cap — long real-world flows (form filling, multi-step
     // checkouts) routinely run past the old $0.50 ceiling and got cut off
     // mid-run. The widget shows the running $ counter in the header instead,
     // so the user can hit Stop when they've seen enough. Pass maxBudgetUsd
     // explicitly (or via the Vite plugin option) if a hard ceiling is needed.
     const maxBudgetUsd = opts.maxBudgetUsd;
-    const optimizeMode = opts.optimizeMode ?? 'suggest';
     const cdpUrl = opts.cdpUrl ?? 'http://localhost:9222';
+    const userDataDir = opts.userDataDir;
     const devRoot = opts.devRoot ?? process.cwd();
     const wss = await pickAndBind('127.0.0.1', requestedPort, PORT_RETRIES);
     const port = wss.address().port;
@@ -163,7 +257,7 @@ export async function startService(opts) {
     // forced an explicit one, but in that case mode-contributed servers
     // are silently dropped — we log a warning the first time it happens.
     let warnedExplicitMcpOverride = false;
-    const buildMcpConfig = () => {
+    const buildMcpConfig = (shotDir, sourceGate = 'ask') => {
         if (opts.mcpConfig) {
             const activePlugin = currentModeId ? pluginsByModeId.get(currentModeId) : null;
             if (activePlugin?.mcpServers?.length && !warnedExplicitMcpOverride) {
@@ -180,7 +274,7 @@ export async function startService(opts) {
             for (const p of plugins) {
                 for (const srv of p.mcpServers ?? []) {
                     const scope = srv.activeInModes ?? (p.mode ? [p.mode.id] : []);
-                    const inMode = scope.includes('*') || scope.includes(currentModeId);
+                    const inMode = scope.includes('*') || scope.includes(currentModeId) || apiScopeOk(scope) || pentestScopeOk(scope);
                     if (!inMode)
                         continue;
                     extra.push({
@@ -195,6 +289,41 @@ export async function startService(opts) {
                 }
             }
         }
+        // codeContext (opt-in, all modes): the fenced read-only source reader.
+        // 'deny' drops it entirely; 'ask' makes it gate each read through the editor
+        // (HOVER_APPROVAL_PORT); 'always' lets it read without asking.
+        if (opts.codeContext && sourceGate !== 'deny') {
+            extra.push({
+                id: SOURCE_MCP_ID,
+                command: process.execPath,
+                args: [SOURCE_MCP_SCRIPT],
+                env: {
+                    HOVER_PROJECT_ROOT: devRoot,
+                    HOVER_SOURCE_GATE: sourceGate === 'ask' ? 'ask' : 'allow',
+                    ...(sourceGate === 'ask' ? { HOVER_APPROVAL_PORT: String(port) } : {}),
+                },
+            });
+        }
+        // Control actuation (always on, all modes): force-toggles sr-only hidden
+        // radios/checkboxes the locked-down Playwright click can't actuate. Drives
+        // the same debug Chrome over CDP; crystallizes to a normal .check() step.
+        extra.push({
+            id: CONTROL_MCP_ID,
+            command: process.execPath,
+            args: [CONTROL_MCP_SCRIPT],
+            // HOVER_APPROVAL_PORT: the control MCP's ask_user tool reaches the editor
+            // over the service WS. HOVER_PROJECT_ROOT: where upload_file writes its
+            // placeholder fixture and resolves relative paths. HOVER_SHOT_DIR: where
+            // take_screenshot writes (the same per-run dir the service scans), so its
+            // viewport PNGs surface in the chat exactly like browser_take_screenshot's.
+            env: {
+                HOVER_CDP_URL: cdpUrl,
+                HOVER_DEV_URL: opts.devUrl ?? cdpUrl,
+                HOVER_APPROVAL_PORT: String(port),
+                HOVER_PROJECT_ROOT: devRoot,
+                ...(shotDir ? { HOVER_SHOT_DIR: shotDir } : {}),
+            },
+        });
         // Single-Chrome model: the Playwright MCP always points at the one debug
         // Chrome on the normal cdpUrl. (Pre-single-Chrome this branched to a
         // mode-specific port like 9333; there's no second Chrome anymore.)
@@ -205,6 +334,10 @@ export async function startService(opts) {
             // Suffix the filename by the mode so different mode toggles within
             // one service produce distinct config files (debugging aid).
             suffix: currentModeId ?? undefined,
+            // Screenshots / traces land in the run's own folder
+            // (.hover/runs/<conv>/<runId>/screenshots), grouped per run, instead of
+            // the MCP server's default OS temp dir.
+            outputDir: shotDir,
         });
     };
     // Surface post-listen errors instead of crashing the host process.
@@ -239,11 +372,45 @@ export async function startService(opts) {
     }
     /** id of the currently-active mode, or null for normal (unmoded) mode. */
     let currentModeId = null;
+    /**
+     * The single in-flight agent run, held at SERVICE scope (not per-connection)
+     * so it SURVIVES the widget's WS dropping. The widget lives in the page the
+     * agent drives, so any agent navigation (a pentest payload in the URL, an
+     * HMR reload) tears the widget down and closes its socket — but the agent is
+     * still happily driving the tab over CDP and recording findings server-side.
+     * Killing it on every navigation made pentest mode (which navigates
+     * constantly) unusable. Instead: detach on close, keep streaming to whichever
+     * ws is attached, and only abort if no widget reconnects within the grace
+     * window. Single active run — Hover binds 127.0.0.1 for one local user.
+     */
+    const RECONNECT_GRACE_MS = 15_000;
+    let activeRun = null;
+    /** QA candidate flows recorded by the agent this run (via record_candidate).
+     *  Buffered here (connection scope, visible to both the message handler and
+     *  the run lifecycle); reset at each run start; resolved to real steps and
+     *  emitted as `qa-candidates` at run end. */
+    let runCandidates = [];
+    /** Reset recipe discovered by recon this run (via record_reset_recipe). Buffered
+     *  here, forwarded to the extension's env store (.hover/environments.json, which
+     *  the extension owns) at run end, keyed to the run's env. */
+    let runResetRecipe = null;
+    /** In-flight source-read approval requests: correlation id → the source-MCP
+     *  socket that asked, so the editor's response can be routed back to it. */
+    const pendingApprovals = new Map();
+    /** In-flight ask_user prompts: correlation id → the control-MCP socket that
+     *  asked, so the editor's answer routes back to the waiting agent. */
+    const pendingAsks = new Map();
+    /** Send a run event to whichever ws is currently attached (survives reconnect). */
+    const emitToRun = (msg) => {
+        const c = activeRun?.client;
+        if (c && c.readyState === WebSocket.OPEN)
+            send(c, msg);
+    };
     /** Chrome-proxy settings a plugin's `hover:service:start` hook set on us
      *  (security's resident MITM). RESIDENT for the whole session — set once
      *  before Chrome launches, never cleared on mode change — so the single
      *  debug Chrome is born with `--proxy-server` + the SPKI pin and entering
-     *  Security mode is just a runtime flip of the proxy, not a Chrome relaunch.
+     *  API-testing mode is just a runtime flip of the proxy, not a Chrome relaunch.
      *  Read by `effectiveLaunchExtras()` and threaded into every cdp handler
      *  (check-cdp / launch-chrome / focus-debug) plus the initial auto-launch. */
     let residentChromeProxy = null;
@@ -252,30 +419,67 @@ export async function startService(opts) {
      *  Merged with the manifest-declared env when the agent's spawn-time
      *  MCP config is built. */
     const mcpEnvOverrides = new Map();
+    // QA "API capability": QA is a built-in mode, but when its API capability is
+    // on it COMPOSES the api-test plugin's runtime — flips the resident MITM to
+    // intercept, exposes the api-test MCP tools, and adds its prompt — so the QA
+    // agent can inspect/replay/test the app's API calls alongside the UI flows.
+    const apiTestPlugin = plugins.find((p) => p.mode?.id === 'api-test') ?? null;
+    /** Is the API capability ACTUALLY usable? The plugin must be loaded AND its
+     *  resident MITM proxy must be up (set at service:start). "Available" gates the
+     *  UI toggle so a user can never turn ON something that would then fail. */
+    const apiCapabilityAvailable = () => !!apiTestPlugin && residentChromeProxy !== null;
+    /** Set per QA run when the API capability is on + available — drives the MCP
+     *  config, the prompt, and the activate/deactivate of the resident proxy. */
+    let apiActiveThisRun = false;
+    /** A plugin's mode-scoped contribution also applies when it's the api-test
+     *  plugin being composed into the current QA run. */
+    const apiScopeOk = (scope) => apiActiveThisRun && scope.includes('api-test');
+    // QA "Pentest capability": same composition as API, but the pentest plugin —
+    // offensive (attacks the OWN dev app), origin-locked, writes a findings report.
+    // Mutually exclusive with the API capability (the plugins conflict). Default
+    // OFF; the editor confirms before enabling.
+    const pentestPlugin = plugins.find((p) => p.mode?.id === 'pentest') ?? null;
+    const pentestCapabilityAvailable = () => !!pentestPlugin && residentChromeProxy !== null;
+    let pentestActiveThisRun = false;
+    const pentestScopeOk = (scope) => pentestActiveThisRun && scope.includes('pentest');
+    // QA two-pass: when a QA run has BOTH API + Pentest on, run two sequenced
+    // phases (verify first, pentest last) so the destructive pentest can't corrupt
+    // the verification and each phase gets a fresh, budget-bounded context. The
+    // verify phase runs first; this holds the queued pentest-phase command, which
+    // the verify run's finally re-dispatches.
+    let pendingPhase2 = null;
     /** The cdp-handler extras (proxy) threaded into launch-chrome / check-cdp /
      *  focus-debug and the initial auto-launch. In the single-Chrome model this
      *  is driven purely by the RESIDENT proxy (set in `hover:service:start`),
      *  NOT by the active mode — there is one Chrome on the normal CDP port that
-     *  is always proxied; entering Security mode flips the proxy's behaviour,
+     *  is always proxied; entering API-testing mode flips the proxy's behaviour,
      *  it does not relaunch Chrome on a different port. Returns undefined when
      *  no plugin set a resident proxy (the common no-security case), so plain
      *  Hover is byte-for-byte unchanged. */
     const effectiveLaunchExtras = () => {
-        if (!residentChromeProxy)
+        if (!residentChromeProxy && !userDataDir)
             return undefined;
-        return { proxy: residentChromeProxy };
+        return {
+            ...(residentChromeProxy ? { proxy: residentChromeProxy } : {}),
+            ...(userDataDir ? { userDataDir } : {}),
+        };
     };
     /** Send the current mode catalogue to one ws (or all if undefined). */
     const broadcastModes = (target) => {
-        const available = plugins
-            .filter((p) => Boolean(p.mode))
-            .map((p) => ({
-            id: p.mode.id,
-            label: p.mode.label,
-            description: p.mode.description,
-            pluginName: p.name,
-        }));
-        const payload = { current: currentModeId, available };
+        // The picker lists ONLY the built-in modes (Flow implicit + QA). The
+        // api-test / pentest PLUGINS still load — but they're surfaced as QA
+        // capability TOGGLES (apiCapabilityAvailable / pentestCapabilityAvailable
+        // below), NOT as standalone modes. (Listing plugin-contributed modes here is
+        // the old, removed UX: the mode picker is now Flow + QA Testing only.)
+        const builtins = BUILTIN_MODES.map((m) => ({ id: m.id, label: m.label, description: m.description, accent: m.accent }));
+        const payload = {
+            current: currentModeId,
+            available: builtins,
+            // Whether QA's API / Pentest capabilities can actually run (plugin loaded +
+            // MITM up). Gates the QA toggles so "on" always works.
+            apiCapabilityAvailable: apiCapabilityAvailable(),
+            pentestCapabilityAvailable: pentestCapabilityAvailable(),
+        };
         const targets = target ? [target] : [...wss.clients];
         for (const client of targets) {
             if (client.readyState === WebSocket.OPEN) {
@@ -325,6 +529,14 @@ export async function startService(opts) {
         if (newModeId) {
             const next = pluginsByModeId.get(newModeId);
             if (!next) {
+                // A built-in non-Flow mode (QA) is core-owned, not plugin-contributed —
+                // no activate hook / sidecars to run, just record it. Anything else is a
+                // genuinely unknown mode.
+                if (isBuiltinMode(newModeId)) {
+                    currentModeId = newModeId;
+                    broadcastModes();
+                    return;
+                }
                 throw new Error(`[hover] unknown modeId "${newModeId}"`);
             }
             currentModeId = newModeId;
@@ -390,7 +602,7 @@ export async function startService(opts) {
     wss.on('connection', ws => {
         send(ws, {
             type: 'hello',
-            payload: { agentId: currentAgentId, model, version: PROTOCOL_VERSION, optimizeMode },
+            payload: { agentId: currentAgentId, model, version: PROTOCOL_VERSION },
         });
         // Send the agent list as a follow-up event so the widget can render the
         // dropdown immediately on connect / reconnect (e.g. after HMR). The
@@ -410,20 +622,42 @@ export async function startService(opts) {
         // Send the mode catalogue too, so the widget can render the mode
         // toggle immediately. Empty list when no plugins are loaded.
         broadcastModes(ws);
-        let busy = false;
-        let inflight = null;
-        let cancelled = false;
-        // If the page reloads (e.g. AI navigated to a same-origin URL), the WS
-        // connection drops. Abort the in-flight agent so we don't leave an
-        // orphan claude process driving the now-vanished browser tab.
+        // Re-attach to a run that's still in flight (the previous widget dropped —
+        // most commonly the agent navigated and reloaded the page the widget lives
+        // in). Cancel the pending abort, point the run's event stream at this fresh
+        // socket, and tell the widget so it can restore its "running" UI. Without
+        // this the run would be killed on every agent navigation.
+        // Only re-attach during a genuine reconnect GAP (the prior client is gone).
+        // If a live client is still attached, this is a SECOND widget (e.g. the
+        // user's regular tab alongside the debug-Chrome tab — both inject a widget
+        // on the same origin and open their own socket). Seizing the stream would
+        // silence the first widget and let the second's close abort a healthy run,
+        // so leave a second concurrent widget in idle UI rather than hijacking.
+        if (activeRun && activeRun.client === null) {
+            if (activeRun.graceTimer) {
+                clearTimeout(activeRun.graceTimer);
+                activeRun.graceTimer = null;
+            }
+            activeRun.client = ws;
+            send(ws, { type: 'run-active', payload: { prompt: activeRun.prompt } });
+        }
+        // If the widget's socket closes while a run it owns is in flight, DON'T
+        // abort — the agent is still driving the tab over CDP. Detach this ws and
+        // start a grace window; a reconnecting widget (above) cancels the abort.
+        // Only if nobody comes back do we abort, so we still never leave an orphan.
         ws.on('close', () => {
-            inflight?.abort();
+            if (activeRun && activeRun.client === ws) {
+                activeRun.client = null;
+                activeRun.graceTimer = setTimeout(() => {
+                    activeRun?.abort.abort();
+                }, RECONNECT_GRACE_MS);
+            }
         });
         const cancel = () => {
-            if (!busy)
+            if (!activeRun)
                 return;
-            cancelled = true;
-            inflight?.abort();
+            activeRun.cancelled = true;
+            activeRun.abort.abort();
             // Send a synthetic session_end so the widget resets to idle immediately.
             // The for-await loop below short-circuits on `cancelled`, so no events
             // from the dying child will arrive after this.
@@ -433,7 +667,7 @@ export async function startService(opts) {
             // stays false because the agent didn't fail: the user chose to
             // end the run. The widget renders this as a neutral "Stopped"
             // state rather than a red Failed card.
-            send(ws, {
+            emitToRun({
                 type: 'event',
                 payload: {
                     kind: 'session_end',
@@ -443,7 +677,10 @@ export async function startService(opts) {
                 },
             });
         };
-        ws.on('message', async (data) => {
+        // Named (not an inline arrow) so a QA run with both API + Pentest on can
+        // re-enter it for a sequenced second phase — see the phase split + the
+        // re-dispatch in the command path's finally.
+        const onClientMessage = async (data) => {
             let msg;
             try {
                 msg = JSON.parse(data.toString());
@@ -455,12 +692,59 @@ export async function startService(opts) {
                 cancel();
                 return;
             }
-            if (msg.type === 'list-modes') {
-                broadcastModes(ws);
+            // Stateless relays (reveal-source / source-approval-* / ask-user-*) — see
+            // service/relayHandlers.ts. They route between sockets without touching the
+            // run's mutable state, so they live outside this closure.
+            if (handleRelayMessage(ws, msg, {
+                wss,
+                activeRunClient: () => activeRun?.client,
+                pendingApprovals,
+                pendingAsks,
+            }))
+                return;
+            // record-fact (from the control MCP's record_fact tool): persist a learned
+            // business rule into .hover/memory/. ONLY in QA/API modes — ignored
+            // elsewhere so Flow/Pentest never write business memory. Best-effort:
+            // a memory write must never break anything (it isn't even acked).
+            if (msg.type === 'record-fact') {
+                const f = msg.payload?.fact;
+                if (f && f.title && f.rule && (currentModeId === 'qa' || currentModeId === 'api-test')) {
+                    const types = ['business-rule', 'expected-behavior', 'validation', 'access-policy'];
+                    const type = types.includes(f.type) ? f.type : 'business-rule';
+                    void writeFact(devRoot, { name: f.title, description: f.title, type, body: f.rule }).then((r) => {
+                        if ('error' in r)
+                            process.stderr.write(`[hover/qa] record-fact write failed: ${r.error}\n`);
+                    });
+                }
+                return;
+            }
+            // record-candidate (from the control MCP's record_candidate tool): buffer a
+            // QA candidate flow. The MCP already captured the flow's real grounded
+            // steps, so we just hold them. ONLY in QA mode; emitted as `qa-candidates`
+            // at run end — never acked, never blocks a run.
+            if (msg.type === 'record-candidate') {
+                const c = msg.payload?.candidate;
+                if (c && typeof c.name === 'string' && Array.isArray(c.steps) && currentModeId === 'qa') {
+                    runCandidates.push({
+                        name: c.name,
+                        description: typeof c.description === 'string' ? c.description : undefined,
+                        steps: c.steps,
+                    });
+                }
+                return;
+            }
+            // record-reset-recipe (from the control MCP's record_reset_recipe tool): the
+            // agent's state-reset classification for this app/env, discovered during
+            // recon. Buffer it; forwarded to the extension at run end (it owns
+            // .hover/environments.json), keyed to runEnv. Best-effort, never acked.
+            if (msg.type === 'record-reset-recipe') {
+                const r = msg.payload?.recipe;
+                if (r && typeof r.tier === 'number')
+                    runResetRecipe = r;
                 return;
             }
             if (msg.type === 'set-mode') {
-                if (busy) {
+                if (activeRun) {
                     send(ws, {
                         type: 'error',
                         payload: { message: 'set-mode: a command is already running; stop it first' },
@@ -475,7 +759,7 @@ export async function startService(opts) {
                     });
                     return;
                 }
-                if (wanted !== null && !pluginsByModeId.has(wanted)) {
+                if (wanted !== null && !isBuiltinMode(wanted) && !pluginsByModeId.has(wanted)) {
                     send(ws, {
                         type: 'error',
                         payload: { message: `set-mode: unknown modeId "${wanted}"` },
@@ -495,13 +779,6 @@ export async function startService(opts) {
                 }
                 return;
             }
-            if (msg.type === 'list-agents') {
-                // Force a refresh — the user may have just installed a new CLI
-                // and clicked the dropdown to see the change.
-                const available = await getAvailability(true);
-                send(ws, { type: 'agents', payload: { current: currentAgentId, available } });
-                return;
-            }
             if (msg.type === 'switch-agent') {
                 const wanted = msg.payload?.agentId;
                 if (typeof wanted !== 'string' || !wanted) {
@@ -515,7 +792,7 @@ export async function startService(opts) {
                 // Refuse to switch mid-flight; the user's running command would
                 // otherwise outlive its own descriptor and the events it produces
                 // would be parsed against the wrong wire format.
-                if (busy) {
+                if (activeRun) {
                     send(ws, {
                         type: 'error',
                         payload: { message: 'switch-agent: a command is already running; stop it first' },
@@ -537,46 +814,68 @@ export async function startService(opts) {
                 await broadcastAgents();
                 return;
             }
-            if (msg.type === 'set-api-key') {
-                // The widget supplies (or clears) a model API key. Stored in memory
-                // only and injected into the spawned CLI's env at invoke time — never
-                // persisted, never logged, never echoed back. Empty/missing clears it.
-                const key = msg.payload?.key;
-                currentApiKey = typeof key === 'string' && key.trim() ? key.trim() : undefined;
-                const envVar = getAgent(currentAgentId)?.apiKeyEnv;
-                send(ws, { type: 'api-key-status', payload: { hasKey: !!currentApiKey, envVar } });
+            if (msg.type === 'set-model') {
+                // Persist the model for subsequent runs (sonnet / opus / haiku / …).
+                // Refuse mid-run so an in-flight invocation keeps the model it started
+                // with. Applies from the next command.
+                const wanted = msg.payload?.model;
+                if (typeof wanted !== 'string' || !wanted) {
+                    send(ws, { type: 'error', payload: { message: 'set-model: model is required' } });
+                    return;
+                }
+                if (activeRun) {
+                    send(ws, { type: 'error', payload: { message: 'set-model: a command is already running; stop it first' } });
+                    return;
+                }
+                model = wanted;
+                send(ws, { type: 'hello', payload: { agentId: currentAgentId, model, version: PROTOCOL_VERSION } });
                 return;
             }
-            if (msg.type === 'list-specs') {
-                // Widget asks for every spec under <devRoot>/__vibe_tests__/ so it
-                // can render the Specs tab in the Saved-sessions overlay. Each
-                // summary carries `originalPrompt` (parsed from the JSDoc header)
-                // so the Re-record button can resubmit it as a normal command.
-                const specs = await listSpecs(devRoot);
-                send(ws, { type: 'specs-list', payload: { specs } });
+            if (msg.type === 'set-effort') {
+                // Reasoning-effort level for subsequent runs (empty string clears it →
+                // the agent/model default). Refused mid-run, like set-model.
+                const wanted = msg.payload?.effort;
+                if (typeof wanted !== 'string') {
+                    send(ws, { type: 'error', payload: { message: 'set-effort: effort is required' } });
+                    return;
+                }
+                if (activeRun) {
+                    send(ws, { type: 'error', payload: { message: 'set-effort: a command is already running; stop it first' } });
+                    return;
+                }
+                currentEffort = wanted || undefined;
                 return;
             }
-            if (msg.type === 'list-seeds') {
-                // Widget's Seeds tab: show which translation seeds Hover sees — the
-                // built-in set + whatever the user dropped in <devRoot>/.hover/rules/.
-                // Read-only; users add seeds by hand (no download path).
-                const builtinNames = new Set(BUILTIN_SEEDS.map(s => s.name));
-                const seeds = (await readSeeds(devRoot)).map(s => ({
-                    name: s.name,
-                    note: s.note ?? '',
-                    signature: s.signature,
-                    code: s.example?.code ?? '',
-                    source: builtinNames.has(s.name) ? 'builtin' : 'project',
-                }));
-                send(ws, { type: 'seeds-list', payload: { seeds } });
+            if (msg.type === 'set-local-endpoint') {
+                // Base URL of the user's self-hosted OpenAI-compatible endpoint for the
+                // Local LLM agent (qwen-code as host). Empty string clears it.
+                const url = msg.payload?.baseUrl;
+                if (typeof url !== 'string') {
+                    send(ws, { type: 'error', payload: { message: 'set-local-endpoint: baseUrl is required' } });
+                    return;
+                }
+                currentLocalBaseUrl = url || undefined;
                 return;
             }
-            if (msg.type === 'save-spec') {
-                await handleSaveArtifact(ws, msg, devRoot, SPEC_CONFIG);
+            if (msg.type === 'set-byok') {
+                // BYOK config for subsequent runs, or null to fall back to the
+                // local-CLI agent's own auth. Refused mid-run, like set-model.
+                if (activeRun) {
+                    send(ws, { type: 'error', payload: { message: 'set-byok: a command is already running; stop it first' } });
+                    return;
+                }
+                const c = msg.payload?.config;
+                currentByok = c && typeof c.protocol === 'string' ? c : null;
                 return;
             }
-            if (msg.type === 'save-case-csv') {
-                await handleSaveArtifact(ws, msg, devRoot, CASE_CSV_CONFIG);
+            if (msg.type === 'refresh-agents') {
+                // Re-scan PATH (the user just installed a CLI) and re-broadcast.
+                await getAvailability(true);
+                await broadcastAgents();
+                return;
+            }
+            if (msg.type === 'save-spec') {
+                await handleSaveArtifact(ws, msg, devRoot, SPEC_CONFIG);
                 return;
             }
             // Stage 7 (F7) widget flow: optimize a saved spec, then promote/discard
@@ -590,8 +889,15 @@ export async function startService(opts) {
                     return;
                 }
                 try {
+                    // Optimize is text-only refinement — run it on a CHEAP model: the
+                    // user's `hover.optimizeModel` setting if set, else the agent's
+                    // cheapModel (e.g. claude → haiku), else the session model. Keeps the
+                    // refinement affordable (and viable to run often) without a big model.
+                    const optimizeModel = (typeof msg.payload?.optimizeModel === 'string' && msg.payload.optimizeModel)
+                        || getAgent(currentAgentId)?.cheapModel
+                        || model;
                     const res = await optimizeSpecWithAgent(devRoot, slug, {
-                        agentId: currentAgentId, model, maxBudgetUsd, apiKey: currentApiKey,
+                        agentId: currentAgentId, model: optimizeModel, maxBudgetUsd,
                     });
                     send(ws, { type: 'optimize-result', payload: { slug, original: res.original, candidate: res.code } });
                 }
@@ -601,31 +907,30 @@ export async function startService(opts) {
                 }
                 return;
             }
-            if (msg.type === 'promote-optimized') {
+            // Self-heal Stage 2: build the heal prompt for a failed spec and bounce it
+            // back. The extension then runs it through the normal run path (runPrompt →
+            // command), so the repair streams into chat and crystallizes like any run —
+            // no run-path surgery. The failing locator comes from the latest Playwright
+            // run JSON (parseRunFailures); absent → buildHealPrompt degrades gracefully.
+            if (msg.type === 'heal-spec') {
                 const slug = msg.payload?.slug;
-                if (typeof slug !== 'string' || !slug) {
-                    send(ws, { type: 'error', payload: { message: 'promote-optimized: slug is required' } });
+                const specSource = typeof msg.payload?.specSource === 'string' ? msg.payload.specSource : '';
+                if (typeof slug !== 'string' || !slug || !specSource) {
+                    send(ws, { type: 'error', payload: { message: 'heal-spec: slug and specSource are required' } });
                     return;
                 }
+                let failures = [];
                 try {
-                    const path = await promoteOptimized(devRoot, slug);
-                    send(ws, { type: 'optimized-promoted', payload: { slug, path } });
-                    send(ws, { type: 'specs-list', payload: { specs: await listSpecs(devRoot) } });
-                }
-                catch (err) {
-                    const m = err instanceof Error ? err.message : String(err);
-                    send(ws, { type: 'error', payload: { message: `promote-optimized: ${m}` } });
-                }
-                return;
-            }
-            if (msg.type === 'discard-optimized') {
-                const slug = msg.payload?.slug;
-                if (typeof slug !== 'string' || !slug) {
-                    send(ws, { type: 'error', payload: { message: 'discard-optimized: slug is required' } });
-                    return;
+                    const runsDir = join(devRoot, '.hover', 'runs');
+                    const files = readdirSync(runsDir).filter((f) => f.endsWith('.json')).sort();
+                    const newest = files.at(-1);
+                    if (newest) {
+                        failures = parseRunFailures(readFileSync(join(runsDir, newest), 'utf-8'))
+                            .filter((f) => f.specFile.includes(slug));
+                    }
                 }
-                await discardOptimized(devRoot, slug);
-                send(ws, { type: 'optimized-discarded', payload: { slug } });
+                catch { /* no runs ledger yet — heal from the spec source alone */ }
+                send(ws, { type: 'heal-ready', payload: { slug, prompt: buildHealPrompt(slug, specSource, failures), label: healLabel(slug) } });
                 return;
             }
             // v0.12 — plugin-contributed save handlers. Lookup is O(plugins),
@@ -661,62 +966,212 @@ export async function startService(opts) {
                 });
                 return;
             }
-            if (msg.type === 'check-cdp') {
-                await handleCheckCdp(ws, msg, cdpUrl, effectiveLaunchExtras());
-                return;
-            }
             if (msg.type === 'launch-chrome') {
                 await handleLaunchChrome(ws, msg, cdpUrl, effectiveLaunchExtras());
                 return;
             }
-            if (msg.type === 'focus-debug') {
-                await handleFocusDebug(ws, msg, cdpUrl, effectiveLaunchExtras());
-                return;
-            }
             if (msg.type !== 'command')
                 return;
-            const text = msg.payload?.text;
+            const rawText = msg.payload?.text;
             const resumeSessionId = typeof msg.payload?.sessionId === 'string' && msg.payload.sessionId.length > 0
                 ? msg.payload.sessionId
                 : undefined;
-            // Re-record mode: when the client (widget Specs tab or hover CLI)
-            // passes `reRecord: { slug }`, runSession collects the tool_use events
-            // into a SpecStep[] and, on a clean finish, we overwrite the existing
-            // __vibe_tests__/<slug>.spec.ts. Same flow the widget uses for "Save as
-            // Spec", but the spec already exists and is being regenerated for the
-            // current UI.
-            const reRecordSlug = msg.payload && typeof msg.payload === 'object' && 'reRecord' in msg.payload
-                ? msg.payload.reRecord?.slug
-                : undefined;
-            if (typeof text !== 'string' || !text.trim())
+            if (typeof rawText !== 'string' || !rawText.trim())
                 return;
-            if (busy) {
+            // `let` (typed string): the classify gate (below) may substitute a refined
+            // instruction (e.g. "read the page" → "test this page") before the run uses it.
+            let text = rawText;
+            if (activeRun) {
                 send(ws, {
                     type: 'error',
-                    payload: { message: 'A command is already running on this connection.' },
+                    payload: { message: 'A command is already running.' },
                 });
                 return;
             }
-            busy = true;
-            cancelled = false;
-            inflight = new AbortController();
+            const run = {
+                abort: new AbortController(),
+                cancelled: false,
+                client: ws,
+                graceTimer: null,
+                prompt: text,
+            };
+            activeRun = run;
+            // Session-ledger state — declared outside the try so the catch path can
+            // still record an aborted / thrown run (the spend view wants those too).
+            const sessionStartedAt = new Date().toISOString();
+            // One id per run, generated NOW (run start), so the ledger record, the
+            // screenshots, and the QA report all share one folder. Replaces the old
+            // split between an end-based record id and a start-based screenshotTag.
+            const runId = `${sessionStartedAt.replace(/[:.]/g, '-')}-${Math.random().toString(16).slice(2, 6)}`;
+            // The chat conversation this run belongs to (from the editor); groups all
+            // its runs under one folder so deleting a conversation removes them.
+            const conversationId = typeof msg.payload?.conversationId === 'string' && msg.payload.conversationId
+                ? msg.payload.conversationId
+                : 'default';
+            const runDirPath = runDir(devRoot, conversationId, runId);
+            const runShotDir = join(runDirPath, 'screenshots');
+            let sessionEnd = {};
+            // Findings + clean summary parsed from the ORIGINAL session_end summary,
+            // captured before that summary is stripped of its ## Findings block for the
+            // chat. recordSession reuses these so the ledger record + QA report keep the
+            // findings (re-parsing the stripped summary would lose them).
+            let runParsed = null;
+            let sessionRecorded = false;
+            runCandidates = []; // fresh per run — QA candidate flows accumulate below
+            runResetRecipe = null; // fresh per run — recon may set it
+            pendingPhase2 = null; // cleared each run; the phase split below may re-arm it
+            // Reproducibility context captured up front (snapshot the mode now so a
+            // mid-run switch can't smear it; the rest are filled as the run learns
+            // them). Account labels are LABELS ONLY — never the credentials.
+            const runMode = currentModeId;
+            // QA intensity (per-run): Quick / Standard / Deep — bounds exploration with
+            // a hard model-spend ceiling so "explore the whole app" can't run away.
+            // Only meaningful in QA mode; ignored elsewhere.
+            const runIntensity = asQaIntensity(msg.payload?.intensity);
+            // QA API capability (per-run): when QA's API toggle is on AND the MITM is
+            // available, compose the api-test runtime into this run. The UI only lets
+            // the user turn it on when available, so "on" must actually work — if it's
+            // requested but unavailable, say so loudly (don't silently degrade).
+            const caps = msg.payload?.capabilities;
+            const isPhase2 = msg.payload?.__phase2 === true;
+            const pentestWanted = runMode === 'qa' && caps?.pentest === true && pentestCapabilityAvailable();
+            const apiWanted = runMode === 'qa' && (caps?.api === true || caps?.api === undefined) && apiCapabilityAvailable();
+            // Two-pass: pentest is destructive, so it always runs as a SECOND phase
+            // after the verify phase (functional [+ API]). A first QA run with pentest
+            // on runs verify now and queues a fresh-session pentest phase; the pentest
+            // phase (isPhase2) then runs pentest alone.
+            const splitting = !isPhase2 && pentestWanted;
+            if (splitting) {
+                pentestActiveThisRun = false; // phase 1 = verify (functional + API if on)
+                apiActiveThisRun = apiWanted;
+                pendingPhase2 = {
+                    type: 'command',
+                    payload: { ...msg.payload, capabilities: { api: false, pentest: true }, sessionId: undefined, __phase2: true },
+                };
+            }
+            else {
+                // Normal QA (no pentest), OR the queued pentest phase itself. Pentest and
+                // API never run in the same phase.
+                pentestActiveThisRun = pentestWanted;
+                apiActiveThisRun = !pentestActiveThisRun && apiWanted;
+            }
+            // Defensive: the UI only enables these toggles when available, so an
+            // explicit "on" should always be honoured. If it somehow isn't, log it
+            // (the run continues as functional-only rather than failing the run).
+            if (runMode === 'qa' && caps?.api === true && !apiActiveThisRun && !pentestActiveThisRun && !splitting && !apiCapabilityAvailable()) {
+                process.stderr.write('[hover/qa] API capability requested but the api-test runtime is unavailable; running functional-only.\n');
+            }
+            if (runMode === 'qa' && caps?.pentest === true && !pentestCapabilityAvailable()) {
+                process.stderr.write('[hover/qa] Pentest capability requested but the pentest runtime is unavailable; running functional-only.\n');
+            }
+            const runResumeOf = resumeSessionId;
+            const runEnv = (() => {
+                const e = msg.payload?.env;
+                return e && typeof e === 'object' ? { id: e.id, name: e.name } : undefined;
+            })();
+            let runTargetUrl;
+            let runAccountLabels;
+            const recordSession = async (outcome, stepCount, detail) => {
+                if (sessionRecorded)
+                    return;
+                sessionRecorded = true;
+                const endedAt = new Date().toISOString();
+                // Prefer the findings captured at session_end (from the un-stripped
+                // summary); fall back to parsing detail.summary (error/abort paths).
+                const parsed = runParsed ?? (detail?.summary ? parseFindings(detail.summary) : { summary: '', findings: [] });
+                const toolCounts = detail?.steps ? tallyTools(detail.steps) : undefined;
+                const target = runTargetUrl || runEnv ? { url: runTargetUrl, id: runEnv?.id, name: runEnv?.name } : undefined;
+                const rec = await writeSessionRecord(devRoot, conversationId, runId, {
+                    startedAt: sessionStartedAt,
+                    endedAt,
+                    durationMs: Date.parse(endedAt) - Date.parse(sessionStartedAt),
+                    agent: currentAgentId,
+                    model,
+                    mode: runMode,
+                    prompt: text,
+                    outcome,
+                    errorReason: detail?.errorReason,
+                    summary: parsed.summary || undefined,
+                    findings: parsed.findings.length ? parsed.findings : undefined,
+                    toolCounts: toolCounts && Object.keys(toolCounts).length ? toolCounts : undefined,
+                    target: target ? { url: target.url, envId: target.id, envName: target.name } : undefined,
+                    accountLabels: runAccountLabels,
+                    resumeOf: runResumeOf,
+                    turns: sessionEnd.turns,
+                    costUsd: sessionEnd.costUsd,
+                    tokensUsed: sessionEnd.tokens,
+                    stepCount,
+                });
+                // QA mode is report-first: persist a durable Markdown findings report
+                // (mirrors pentest's report file; the chat already shows the Findings
+                // card live). Best-effort — never breaks the run/ledger.
+                if (runMode === 'qa') {
+                    const r = await writeQaReport(runDirPath, {
+                        prompt: text,
+                        summary: parsed.summary,
+                        findings: parsed.findings,
+                        endedAt,
+                        targetUrl: runTargetUrl,
+                    });
+                    if ('error' in r)
+                        process.stderr.write(`[hover/qa] report write failed: ${r.error}\n`);
+                    // Surface the report as a clickable artifact in the chat (mirrors the
+                    // screenshot event). The editor opens it on click.
+                    else if (!run.cancelled)
+                        emitToRun({ type: 'qa-report', payload: { path: r.path } });
+                }
+                // Let the active mode's plugin persist its own per-run artifacts bound to
+                // this session id (e.g. api-test writes .hover/api/<id>.json). Best-effort.
+                const sid = rec && 'id' in rec ? rec.id : null;
+                const runEndPlugin = runMode ? pluginsByModeId.get(runMode) : null;
+                if (sid && runEndPlugin?.hooks?.['hover:run:end']) {
+                    try {
+                        await runEndPlugin.hooks['hover:run:end']({ devRoot, broadcast: broadcastPluginEvent, sessionId: sid });
+                    }
+                    catch (err) {
+                        process.stderr.write(`[hover] plugin "${runEndPlugin.name}" run:end failed: ${err instanceof Error ? err.message : String(err)}\n`);
+                    }
+                }
+                // QA + API: persist this run's captured API traffic/checks, then flip the
+                // resident MITM back to passthrough (stop recording). Best-effort.
+                if (apiActiveThisRun && apiTestPlugin) {
+                    try {
+                        if (sid)
+                            await apiTestPlugin.hooks?.['hover:run:end']?.({ devRoot, broadcast: broadcastPluginEvent, sessionId: sid });
+                        await apiTestPlugin.hooks?.['hover:mode:deactivate']?.({ devRoot, broadcast: broadcastPluginEvent, modeId: 'qa' });
+                    }
+                    catch (err) {
+                        process.stderr.write(`[hover/qa] api-test compose (run:end) failed: ${err instanceof Error ? err.message : String(err)}\n`);
+                    }
+                    apiActiveThisRun = false;
+                }
+                // QA + Pentest: stop recording (back to passthrough). The findings are in
+                // the agent's report; a deep PoC report is available via Save. Best-effort.
+                if (pentestActiveThisRun && pentestPlugin) {
+                    try {
+                        await pentestPlugin.hooks?.['hover:mode:deactivate']?.({ devRoot, broadcast: broadcastPluginEvent, modeId: 'qa' });
+                    }
+                    catch (err) {
+                        process.stderr.write(`[hover/qa] pentest compose (run:end) failed: ${err instanceof Error ? err.message : String(err)}\n`);
+                    }
+                    pentestActiveThisRun = false;
+                }
+            };
             try {
                 // Build the MCP config first — it's pure local file IO and lets
                 // us assert plugin-contributed servers landed in the config even
                 // when CDP preflight subsequently fails (useful for smoke tests
                 // that don't have a real debug Chrome wired up).
-                const mcpConfig = buildMcpConfig();
+                // This run's screenshots go in its own folder
+                // (.hover/conversations/<conversationId>/<runId>/screenshots) — runShotDir,
+                // computed at run start so the ledger record + report + shots all share it.
+                const sourceGate = msg.payload?.sourceAccess ?? 'ask';
+                const mcpConfig = buildMcpConfig(runShotDir, sourceGate);
                 // Preflight: refuse to invoke if CDP isn't reachable. Otherwise the
                 // Playwright MCP server would silently launch its own Chromium —
                 // and Hover's premise is to drive the user's existing Chrome (with
                 // their dev state, cookies, devtools open), never spawn a fresh one.
-                // In an active mode, the relevant CDP endpoint may be the mode's
-                // own port (e.g. 9333 for security), not the default cdpUrl.
-                const preflightExtras = effectiveLaunchExtras();
-                const preflightCdpUrl = preflightExtras?.cdpPort
-                    ? `http://localhost:${preflightExtras.cdpPort}`
-                    : cdpUrl;
-                const cdp = await getPreflight(preflightCdpUrl);
+                const cdp = await getPreflight(cdpUrl);
                 if (!cdp.ok) {
                     send(ws, {
                         type: 'event',
@@ -726,14 +1181,85 @@ export async function startService(opts) {
                             summary: cdp.reason,
                         },
                     });
+                    // A preflight failure is the most common "why did my run die" — make
+                    // it a diagnostic ledger row rather than silently returning.
+                    await recordSession('error', 0, { errorReason: cdp.reason });
                     return;
                 }
+                // Target URL for the ledger: the localhost tab (the dev server) if we
+                // have one, else the first tab.
+                runTargetUrl =
+                    cdp.tabs?.find((t) => /localhost|127\.0\.0\.1/.test(t.url))?.url ?? cdp.tabs?.[0]?.url;
+                // ── Pre-flight classify gate (QA only) ──────────────────────────────
+                // Route the instruction with a cheap one-shot call BEFORE paying for the
+                // full exploratory run. Fresh user instructions only — skip on resume and
+                // on the internal pentest phase-2 re-dispatch (both already vetted).
+                // Fail-open (→ go) lives inside classifyInstruction, so a hiccup never
+                // blocks a legitimate run. 'refuse' / 'clarify' emit a 0-step session_end
+                // and return WITHOUT creating a run folder or ledger record (ephemeral,
+                // like the CDP check); the extension renders a plain reply / clickable
+                // options from the same event a 0-action run produces.
+                if (runMode === 'qa' && !resumeSessionId && !isPhase2 && typeof text === 'string') {
+                    // Show immediate activity for the ~1s classify (flips the UI to
+                    // "Working"); the real run emits its own session_start on 'go'.
+                    emitToRun({ type: 'event', payload: { kind: 'session_start', sessionId: '' } });
+                    const classifyAgentId = currentByok ? byokAgentFor(currentByok.protocol) : currentAgentId;
+                    let classifyMemory;
+                    try {
+                        classifyMemory = formatMemoryForPrompt(await loadMemory(devRoot)) || undefined;
+                    }
+                    catch { /* best-effort */ }
+                    const verdict = await classifyInstruction({
+                        agentId: classifyAgentId,
+                        instruction: text,
+                        pageUrl: runTargetUrl,
+                        pageTitle: cdp.tabs?.find((t) => t.url === runTargetUrl)?.title,
+                        memory: classifyMemory,
+                        // Cheap + fast for claude; BYOK / other agents use their configured model.
+                        model: classifyAgentId === 'claude' && !currentByok ? 'haiku' : currentByok?.model || model,
+                        effort: currentEffort,
+                        cwd: msg.payload?.isolateContext === true ? isolatedAgentCwd() : devRoot,
+                        env: currentByok
+                            ? byokEnvFor(currentByok)
+                            : classifyAgentId === 'qwen' && currentLocalBaseUrl
+                                ? { OPENAI_BASE_URL: currentLocalBaseUrl, OPENAI_API_KEY: process.env.OPENAI_API_KEY || 'local' }
+                                : undefined,
+                        signal: run.abort.signal,
+                    });
+                    if (run.cancelled)
+                        return; // user hit Stop during classify
+                    if (verdict.route === 'refuse') {
+                        pendingPhase2 = null; // don't let a queued pentest phase fire on a refused instruction
+                        emitToRun({
+                            type: 'event',
+                            payload: {
+                                kind: 'session_end',
+                                isError: false,
+                                summary: verdict.reason || 'I can only help test this app — tell me a page, feature, or flow to test.',
+                            },
+                        });
+                        return;
+                    }
+                    if (verdict.route === 'clarify' && verdict.options && verdict.options.length >= 2) {
+                        pendingPhase2 = null;
+                        const question = verdict.reason || 'What would you like me to test?';
+                        const block = ['```hover-ask', ...verdict.options.map((o) => `- ${o}`), '```'].join('\n');
+                        emitToRun({
+                            type: 'event',
+                            payload: { kind: 'session_end', isError: false, summary: `${question}\n\n${block}` },
+                        });
+                        return;
+                    }
+                    // 'go' — run it, substituting the re-interpreted instruction if any.
+                    if (verdict.refinedInstruction)
+                        text = verdict.refinedInstruction;
+                }
                 // Build a system-prompt addendum telling the agent about the user's
                 // current tab. The most common waste we observed: agent calls
                 // browser_navigate to the same URL the user is already on, triggering
-                // a wasteful full-page reload that also destroys the Hover widget
-                // momentarily (the widget re-injects + recovers, but the agent's
-                // own session sometimes gets confused).
+                // a wasteful full-page reload that discards the app state the run had
+                // built up (login session, form input, position in a flow) — so the
+                // agent has to redo work and sometimes loses track of where it was.
                 // First turn pays the full rules + narration block; follow-up
                 // turns (`resumeSessionId` set) get only the volatile tab list.
                 // The static rules are already in the prior turn's context, and
@@ -765,12 +1291,37 @@ export async function startService(opts) {
                         // is always-on (treated as if activeInModes was '*').
                         const scope = add.activeInModes ?? (p.mode ? [p.mode.id] : ['*']);
                         const inScope = scope.includes('*') ||
-                            (currentModeId !== null && scope.includes(currentModeId));
+                            (currentModeId !== null && scope.includes(currentModeId)) ||
+                            apiScopeOk(scope) ||
+                            pentestScopeOk(scope);
                         if (inScope) {
                             appendSystemPrompt = `${appendSystemPrompt}\n\n${add.text}`;
                         }
                     }
                 }
+                // codeContext: tell the agent the fenced source reader exists, so it
+                // proactively reads the real code (better selectors/routes when
+                // authoring; white-box confirmation when probing) instead of only
+                // guessing from the rendered DOM.
+                if (opts.codeContext) {
+                    appendSystemPrompt = `${appendSystemPrompt}\n\nYou also have read-only access to this project's source via mcp__hoversource (read_source / list_source), fenced to the repo (secrets, keys, .env, .git, node_modules and build output are refused). Use it to read the actual component / route / API code — write tests against the real selectors and, when probing for security issues, confirm a finding against the server code (the query, the authz check) rather than guessing from the page alone.\n\nIMPORTANT — when you get stuck or confused, READ THE CODE before concluding anything: a control you can't operate (a click that does nothing, a field that won't take input), validation that blocks you with no visible reason, a conditional section that won't appear. Use list_source / read_source to open that component's source and look at the real markup, CSS (e.g. visually-hidden / sr-only inputs), event handlers, and state wiring. Base your diagnosis and your next action on what the code actually does — never assert a framework / state / onChange bug you have not seen in the source. Reading source may require the user's one-click approval; if a read is declined or unavailable, just continue from what you can observe on the page and report honestly — do not retry the read in a loop, and do not fall back to guessing an unseen cause.`;
+                }
+                // Test accounts the prompt referenced via @label (resolved by the editor
+                // from its vault). Injected here, NOT in the user-visible transcript, so
+                // the agent can log in; the literal values it types are redacted out of
+                // the saved spec (writeSpec redactions). Never echoed to the user.
+                const runAccounts = Array.isArray(msg.payload?.accounts) ? msg.payload.accounts : [];
+                if (runAccounts.length) {
+                    // Ledger keeps LABELS ONLY — never the username/password.
+                    runAccountLabels = runAccounts.map((a) => a.label);
+                    const lines = runAccounts.map(a => {
+                        const role = a.role ? ` (${a.role})` : '';
+                        const user = a.username ? `username ${JSON.stringify(a.username)}` : 'username not on file';
+                        const pass = a.password ? `, password ${JSON.stringify(a.password)}` : '';
+                        return `- @${a.label}${role}: ${user}${pass}`;
+                    }).join('\n');
+                    appendSystemPrompt = `${appendSystemPrompt}\n\nTest accounts available for this run — when the task refers to an @label, log in using that account's credentials. Use them ONLY to fill authentication fields; never print or echo them in your replies or summaries.\n${lines}`;
+                }
                 // Mirror the prompt's language in the agent's *prose* output — the
                 // verification summary (Result card), the ## Findings block, and the
                 // step narration — the same way Voice mode mirrors it in TTS. A
@@ -782,87 +1333,273 @@ export async function startService(opts) {
                 if (CJK_RE.test(text)) {
                     appendSystemPrompt = `${appendSystemPrompt}\n\n${ZH_OUTPUT_DIRECTIVE}`;
                 }
+                // The report is about the app, never the tooling (all modes).
+                appendSystemPrompt = `${appendSystemPrompt}\n\n${REPORTING_DIRECTIVE}`;
+                // Keep interim narration to one short line per intent (all modes).
+                appendSystemPrompt = `${appendSystemPrompt}\n\n${NARRATION_DIRECTIVE}`;
+                // ASK_FORMAT (propose choices when the request is vague) + EXPLORATION_
+                // CHECKPOINT (ask before stopping with scope left) are for the DIRECTED
+                // modes. QA is autonomous: a vague request means "explore the whole app",
+                // NOT "ask what to test", and QA_EXPLORATION owns its own stop condition —
+                // so skip both for QA (they made QA ask-at-start instead of exploring).
+                if (currentModeId !== 'qa') {
+                    appendSystemPrompt = `${appendSystemPrompt}\n\n${ASK_FORMAT_DIRECTIVE}`;
+                    appendSystemPrompt = `${appendSystemPrompt}\n\n${EXPLORATION_CHECKPOINT_DIRECTIVE}`;
+                }
+                // Grounded actuation — the agent uses mcp__hover-control__* instead of
+                // the Playwright interaction tools, so saved selectors are role+name,
+                // never a confabulated getByText. Driven by the mode's behavior (Flow +
+                // QA: yes; plugin modes: no), NOT by `currentModeId === null` — a future
+                // built-in mode (QA) has a non-null id but still wants grounded steps.
+                const groundedActuation = resolveModeBehavior(currentModeId).groundedActuation;
+                if (groundedActuation) {
+                    appendSystemPrompt = `${appendSystemPrompt}\n\n${GROUNDED_ACTUATION_DIRECTIVE}`;
+                }
+                // State-reset recon (debt-2 reproducible-state-isolation): ONLY when the
+                // extension explicitly asks (it knows whether this env already has a
+                // recipe). Off by default — recon clears client state, which would wipe a
+                // logged-in session, so it must never run unsolicited or on a plain Flow
+                // recording. (Engine plumbing is live; the extension opt-in is piece C.)
+                if (groundedActuation && msg.payload?.reconReset === true) {
+                    appendSystemPrompt = `${appendSystemPrompt}\n\n${RECON_DIRECTIVE}`;
+                }
+                // QA mode: autonomous exploratory testing on top of grounded actuation,
+                // bounded by the run's intensity budget (so the agent paces itself and
+                // always writes a report rather than running away on cost).
+                if (currentModeId === 'qa') {
+                    appendSystemPrompt = `${appendSystemPrompt}\n\n${QA_EXPLORATION_DIRECTIVE}`;
+                    appendSystemPrompt = `${appendSystemPrompt}\n\n${qaBudgetDirective(runIntensity)}`;
+                    // Two-pass: this is the functional verify pass with a pentest pass
+                    // queued behind it — keep it functional-only so it doesn't duplicate
+                    // the pentest pass's security work (the overlap that read like a
+                    // double security run).
+                    if (splitting)
+                        appendSystemPrompt = `${appendSystemPrompt}\n\n${QA_VERIFY_DEFER_SECURITY_DIRECTIVE}`;
+                }
+                // Business memory (QA + API modes only): inject what earlier runs learned
+                // about THIS app so the agent doesn't re-ask answered business questions.
+                // Best-effort — a memory read must never block a run.
+                if (currentModeId === 'qa' || currentModeId === 'api-test') {
+                    try {
+                        const mem = formatMemoryForPrompt(await loadMemory(devRoot));
+                        if (mem)
+                            appendSystemPrompt = `${appendSystemPrompt}\n\n${mem}`;
+                    }
+                    catch { /* memory is best-effort */ }
+                }
                 // Snapshot the agent id so a switch-agent message during the run
                 // can't smear two agents across one invocation. (We also gate
-                // switch-agent on `busy`, but defense in depth.) runSession gates the
-                // allow/deny lists on the agent's sandboxStrength internally.
-                const invokedAgentId = currentAgentId;
+                // switch-agent on an active run, but defense in depth.) runSession gates
+                // the allow/deny lists on the agent's sandboxStrength internally.
+                // BYOK overrides the active CLI: the protocol picks which CLI is
+                // driven; key/base/model are injected via env below. Otherwise the
+                // user's selected local-CLI agent runs with its own auth.
+                const invokedAgentId = currentByok ? byokAgentFor(currentByok.protocol) : currentAgentId;
+                const effectiveModel = currentByok?.model || model;
                 // Active mode's plugin-contributed MCP server ids — added to the
                 // hard-sandbox allow list so Claude can actually call them. Claude
                 // sanitises non-alphanumeric chars in the id when forming tool
-                // names (e.g. "@hover-dev/security:flows" → "mcp__hover_dev_security_flows"),
+                // names (e.g. "@hover-dev/api-test:flows" → "mcp__hover_dev_api_test_flows"),
                 // and `--allowedTools mcp__foo` matches every tool under that
                 // prefix. We pass the prefix `mcp__<sanitized>` so all of the
                 // server's tools are reachable.
-                const sanitize = (s) => s.replace(/[^a-zA-Z0-9]+/g, '_').replace(/^_+|_+$/g, '');
-                const activePluginMcpIds = [];
+                // Control actuation is always reachable (every mode).
+                const activePluginMcpIds = [mcpToolPrefix(CONTROL_MCP_ID)];
                 if (currentModeId) {
                     for (const p of plugins) {
                         for (const srv of p.mcpServers ?? []) {
                             const scope = srv.activeInModes ?? (p.mode ? [p.mode.id] : []);
-                            if (scope.includes('*') || scope.includes(currentModeId)) {
-                                activePluginMcpIds.push(`mcp__${sanitize(srv.id)}`);
+                            if (scope.includes('*') || scope.includes(currentModeId) || apiScopeOk(scope) || pentestScopeOk(scope)) {
+                                activePluginMcpIds.push(mcpToolPrefix(srv.id));
                             }
                         }
                     }
                 }
+                // codeContext: the fenced source reader is allowed in every mode.
+                if (opts.codeContext)
+                    activePluginMcpIds.push(mcpToolPrefix(SOURCE_MCP_ID));
+                // Mark a per-run boundary on the active mode's plugin (api-test scopes its
+                // recorded checks to this run, not the whole session). Best-effort.
+                const runStartPlugin = currentModeId ? pluginsByModeId.get(currentModeId) : null;
+                if (runStartPlugin?.hooks?.['hover:run:start']) {
+                    try {
+                        await runStartPlugin.hooks['hover:run:start']({ devRoot, broadcast: broadcastPluginEvent });
+                    }
+                    catch (err) {
+                        process.stderr.write(`[hover] plugin "${runStartPlugin.name}" run:start failed: ${err instanceof Error ? err.message : String(err)}\n`);
+                    }
+                }
+                // QA + API capability: compose the api-test runtime into this QA run —
+                // flip the resident MITM to intercept (activate) + mark its run boundary,
+                // so the QA agent's API calls are captured/replayable. Mirror-undone at
+                // run end. Best-effort: a hook failure must not break the functional run.
+                if (apiActiveThisRun && apiTestPlugin) {
+                    try {
+                        await apiTestPlugin.hooks?.['hover:mode:activate']?.({
+                            devRoot,
+                            broadcast: broadcastPluginEvent,
+                            modeId: 'qa',
+                            setChromeProxy(proxy) { residentChromeProxy = proxy; },
+                            setMcpServerEnv(id, env) { mcpEnvOverrides.set(id, env); },
+                        });
+                        await apiTestPlugin.hooks?.['hover:run:start']?.({ devRoot, broadcast: broadcastPluginEvent });
+                    }
+                    catch (err) {
+                        process.stderr.write(`[hover/qa] api-test compose (run:start) failed: ${err instanceof Error ? err.message : String(err)}\n`);
+                    }
+                }
+                // QA + Pentest capability: compose the pentest runtime — flip the resident
+                // MITM to intercept so the agent's offensive probes are recorded. The
+                // PENTEST_SYSTEM_PROMPT (origin-locked, own-app) is added via the scope
+                // checks above. Mirror-undone at run end. Best-effort.
+                if (pentestActiveThisRun && pentestPlugin) {
+                    try {
+                        await pentestPlugin.hooks?.['hover:mode:activate']?.({
+                            devRoot,
+                            broadcast: broadcastPluginEvent,
+                            modeId: 'qa',
+                            setChromeProxy(proxy) { residentChromeProxy = proxy; },
+                            setMcpServerEnv(id, env) { mcpEnvOverrides.set(id, env); },
+                        });
+                        await pentestPlugin.hooks?.['hover:run:start']?.({ devRoot, broadcast: broadcastPluginEvent });
+                    }
+                    catch (err) {
+                        process.stderr.write(`[hover/qa] pentest compose (run:start) failed: ${err instanceof Error ? err.message : String(err)}\n`);
+                    }
+                }
+                // Screenshot previews: this run's MCP output dir (same path buildMcpConfig
+                // uses) + a flag tracking whether the last tool_use was a screenshot, so
+                // we can surface the freshly-written png to the chat as a tool_result lands.
+                // (runShotDir is the run folder's screenshots/, computed at run start.)
+                let pendingShot = null;
+                let lastShotPath = null;
                 const runResult = await runSession({
                     agentId: invokedAgentId,
                     prompt: text,
                     sessionId: resumeSessionId,
                     mcpConfig,
-                    // cwd = devRoot so the agent runs against the project (and Claude
-                    // Code reads its CLAUDE.md, if any).
-                    cwd: devRoot,
+                    // Memory setting: "shared" (default) → cwd = devRoot, so the agent
+                    // gets the project's CLAUDE.md + Claude Code auto-memory. "isolated"
+                    // → a throwaway temp cwd, so NONE of the user's CLAUDE.md / memory
+                    // leaks into the test agent.
+                    cwd: msg.payload?.isolateContext === true ? isolatedAgentCwd() : devRoot,
                     appendSystemPrompt,
                     // mcp__playwright covers every browser tool; active-mode plugin MCP
                     // servers are appended. (Save-as-Skill retired → no Skill tool.)
                     allowedToolsExtra: activePluginMcpIds,
+                    // Normal mode: deny the Playwright interaction tools so the agent
+                    // must use the grounded mcp__hover-control__* actuation tools.
+                    disallowedToolsExtra: groundedActuation ? GROUNDED_ACTUATION_DENY : undefined,
                     maxBudgetUsd,
-                    model,
-                    apiKey: currentApiKey,
-                    signal: inflight.signal,
+                    // QA runs are bounded by the chosen intensity's STEP ceiling
+                    // (--max-turns); the prompt paces against the same number.
+                    maxTurns: runMode === 'qa' ? QA_INTENSITY[runIntensity].maxSteps : undefined,
+                    model: effectiveModel,
+                    effort: currentEffort,
+                    // BYOK: inject the protocol's auth env (key + base URL) into the
+                    // matching CLI. Otherwise, Local LLM (qwen host): point qwen at the
+                    // user's OpenAI-compatible endpoint via env (the endpoint's key, if
+                    // any, falls back to the ambient OPENAI_API_KEY / a placeholder).
+                    env: currentByok
+                        ? byokEnvFor(currentByok)
+                        : invokedAgentId === 'qwen' && currentLocalBaseUrl
+                            ? { OPENAI_BASE_URL: currentLocalBaseUrl, OPENAI_API_KEY: process.env.OPENAI_API_KEY || 'local' }
+                            : undefined,
+                    signal: run.abort.signal,
                 }, (ev) => {
-                    if (cancelled || ws.readyState !== WebSocket.OPEN)
-                        return;
-                    send(ws, { type: 'event', payload: ev });
-                });
-                // Re-record: write a fresh spec from the steps runSession accumulated
-                // (`user` → `step`* → `done`). Only on a clean, non-cancelled finish —
-                // a cancelled/aborted run throws out of runSession into the catch
-                // below, and an errored agent leaves the original spec untouched.
-                if (reRecordSlug && !cancelled) {
-                    if (runResult.isError) {
-                        sendIfOpen(ws, {
-                            type: 'error',
-                            payload: {
-                                message: `Re-record failed: ${runResult.summary || 'agent reported an error'}. ` +
-                                    `Original spec left unchanged.`,
-                            },
-                        });
+                    // Cost/turns/tokens for the session ledger ride the session_end
+                    // event — snoop them off the stream. Also track the running `usage`
+                    // totals so an aborted/errored run still records partial spend.
+                    if (ev.kind === 'session_end') {
+                        sessionEnd = { turns: ev.turns, costUsd: ev.costUsd, tokens: ev.tokens };
+                        // Structured-first: parse the agent's JSON findings block, hand the
+                        // editor the clean summary + structured findings (so the Findings
+                        // card renders from data, not a Markdown scrape). All modes.
+                        if (typeof ev.summary === 'string' && ev.summary) {
+                            const parsed = parseFindings(ev.summary);
+                            runParsed = parsed; // keep for the ledger record + QA report
+                            ev.summary = parsed.summary;
+                            ev.findings = parsed.findings;
+                        }
                     }
-                    else {
-                        try {
-                            const { writeSpec } = await import('./specs/writeSpec.js');
-                            const written = await writeSpec({
-                                devRoot,
-                                name: reRecordSlug,
-                                steps: runResult.steps,
-                                overwrite: true,
-                            });
-                            sendIfOpen(ws, {
-                                type: 'spec-saved',
-                                payload: { name: reRecordSlug, path: written.path },
-                            });
+                    else if (ev.kind === 'usage') {
+                        sessionEnd = {
+                            turns: ev.turns ?? sessionEnd.turns,
+                            costUsd: ev.costUsd ?? sessionEnd.costUsd,
+                            tokens: ev.tokens ?? sessionEnd.tokens,
+                        };
+                    }
+                    // Screenshot preview: a take_screenshot tool_use writes a png by the
+                    // time its tool_result lands — resolve the freshest png in the run's
+                    // output dir and surface it to the chat. Best-effort, never throws.
+                    if (ev.kind === 'tool_use') {
+                        const bare = String(ev.tool ?? '').replace(/^mcp__.*?__/, '');
+                        // browser_take_screenshot (Playwright, plugin modes) OR take_screenshot
+                        // (hover-control, grounded modes — viewport only, never resizes the
+                        // page). Both write a PNG into the run's shot dir; we surface the
+                        // freshest one in the chat.
+                        if (bare === 'browser_take_screenshot' || bare === 'take_screenshot') {
+                            // browser_take_screenshot may be full-page; take_screenshot is
+                            // always viewport. Carry `full` so the chat can collapse a
+                            // full+viewport burst and keep the full-page one.
+                            pendingShot = { full: Boolean(ev.input?.fullPage) };
+                        }
+                    }
+                    else if (ev.kind === 'tool_result' && pendingShot) {
+                        const full = pendingShot.full;
+                        pendingShot = null;
+                        const shot = newestPng(runShotDir);
+                        // Dedupe exact repeats by path (a duplicated tool_use/result resolves
+                        // to the same freshest png); distinct full/viewport shots have
+                        // distinct paths and are coalesced downstream by the chat instead.
+                        if (shot && shot !== lastShotPath && !run.cancelled) {
+                            lastShotPath = shot;
+                            emitToRun({ type: 'screenshot', payload: { path: shot, full } });
                         }
-                        catch (e) {
-                            const m = e instanceof Error ? e.message : String(e);
-                            sendIfOpen(ws, {
-                                type: 'error',
-                                payload: { message: `Re-record could not write spec: ${m}` },
-                            });
+                    }
+                    // Stream to whichever ws is attached NOW — survives the widget
+                    // reconnecting mid-run (emitToRun is a no-op during a reconnect gap).
+                    if (run.cancelled)
+                        return;
+                    emitToRun({ type: 'event', payload: ev });
+                });
+                // Append to the `.hover/sessions/` ledger (best-effort, never throws).
+                // `saved`/`specSlug` are patched in later by markSessionSaved when the
+                // user crystallizes — save-spec arrives as a separate WS message.
+                await recordSession(run.cancelled ? 'aborted' : runResult.isError ? 'error' : 'completed', runResult.steps.filter((s) => s.kind === 'step').length, {
+                    summary: runResult.summary,
+                    errorReason: runResult.isError ? runResult.summary : undefined,
+                    steps: runResult.steps,
+                });
+                // QA Stage 4: resolve the agent's recorded candidate flows to their real
+                // recorded steps and offer them as one-click "Crystallize" cards. Steps
+                // are the actual hover-control actuations (record==replay), so each
+                // candidate crystallizes to a clean, runnable spec. Candidates are
+                // functional regression artifacts — the pentest phase produces a findings
+                // report, not specs, so it never offers them (and avoids duplicating the
+                // verify phase's candidates).
+                if (runMode === 'qa' && !pentestActiveThisRun && !run.cancelled) {
+                    // Fallback: the agent may finish a clean flow but never call
+                    // record_candidate (compliance is unreliable, esp. on short directed
+                    // tasks). If it recorded none, offer the whole completed run's grounded
+                    // actuations as ONE candidate — crystallization shouldn't depend on the
+                    // agent remembering to mark it. Deterministic; the user renames at the
+                    // Crystallize prompt. Skipped on error runs and when nothing was acted.
+                    if (runCandidates.length === 0 && !runResult.isError) {
+                        const grounded = runResult.steps.filter(isCrystallizableStep);
+                        if (grounded.some(isRealAction)) {
+                            runCandidates.push({ name: 'Recorded flow', steps: grounded });
                         }
                     }
+                    const resolved = finalizeCandidates(runCandidates);
+                    if (resolved.length)
+                        emitToRun({ type: 'qa-candidates', payload: { candidates: resolved } });
+                }
+                // Forward a recon-discovered reset recipe to the extension (it owns
+                // .hover/environments.json), keyed to this run's env. The extension
+                // persists it onto the env record (piece C); harmless if unhandled.
+                if (runResetRecipe && runEnv && !run.cancelled) {
+                    emitToRun({ type: 'reset-recipe', payload: { envId: runEnv.id, recipe: runResetRecipe } });
                 }
             }
             catch (err) {
@@ -872,32 +1609,46 @@ export async function startService(opts) {
                 // widget to reconcile two terminal events for one run. CDP isn't
                 // suspect either — the user just stopped — so skip preflight
                 // invalidation too.
-                if (!cancelled) {
+                if (!run.cancelled) {
                     const message = err instanceof Error ? err.message : String(err);
                     const errorEvent = {
                         kind: 'session_end',
                         isError: true,
                         summary: message,
                     };
-                    sendIfOpen(ws, { type: 'event', payload: errorEvent });
+                    emitToRun({ type: 'event', payload: errorEvent });
+                    await recordSession('error', 0, { errorReason: message });
                     // Force the next command to re-probe CDP. The error could be from
                     // Chrome dying, MCP spawning a stray Chromium, the user closing
                     // their debug window — anything that would make a cached "all
-                    // healthy" result lie. Invalidate the mode-effective URL (see
-                    // preflightCdpUrl above) — not the static cdpUrl — so security
-                    // mode invalidations don't no-op against the default port.
-                    const invalExtras = effectiveLaunchExtras();
-                    const invalCdpUrl = invalExtras?.cdpPort
-                        ? `http://localhost:${invalExtras.cdpPort}`
-                        : cdpUrl;
-                    invalidatePreflight(invalCdpUrl);
+                    // healthy" result lie.
+                    invalidatePreflight(cdpUrl);
+                }
+                else {
+                    // User-initiated cancel — still worth a ledger row (spend view).
+                    await recordSession('aborted', 0, { errorReason: 'Cancelled by the user.' });
                 }
             }
             finally {
-                busy = false;
-                inflight = null;
+                if (run.graceTimer)
+                    clearTimeout(run.graceTimer);
+                activeRun = null;
             }
-        });
+            // QA two-pass: a verify run with a pentest phase queued behind it. Now that
+            // this (verify) run has finished and activeRun is clear, kick off the
+            // pentest phase as a fresh re-entry — UNLESS the user cancelled. Each phase
+            // is its own agent session (fresh context), so this is the token-cheap way
+            // to sequence them; the pentest phase carries __phase2 so it can't re-split.
+            if (pendingPhase2 && !run.cancelled) {
+                const next = pendingPhase2;
+                pendingPhase2 = null;
+                void onClientMessage(Buffer.from(JSON.stringify(next)));
+            }
+            else {
+                pendingPhase2 = null;
+            }
+        };
+        ws.on('message', onClientMessage);
     });
     // ───────────────────────── service:start + single Chrome ─────────────────
     // Fire plugin `hover:service:start` hooks BEFORE launching Chrome, so a
@@ -941,6 +1692,7 @@ export async function startService(opts) {
             url: launchUrl,
             port: launchPort,
             proxy: residentChromeProxy ?? undefined,
+            userDataDir,
         })
             .then((r) => {
             if (!r.ok) {
@@ -954,6 +1706,20 @@ export async function startService(opts) {
     return {
         port,
         async close() {
+            // Kill any in-flight run FIRST. The run is held at service scope and is
+            // only torn down by aborting its signal (invoke.ts SIGTERMs the agent
+            // child on abort). wss.close() below stops the listener but does NOT
+            // terminate established client sockets, so no ws.on('close') fires — so
+            // without this the agent child would keep driving the debug Chrome as an
+            // orphan after the dev server is gone, and a pending grace timer would
+            // fire abort() 15s into the void.
+            if (activeRun) {
+                if (activeRun.graceTimer)
+                    clearTimeout(activeRun.graceTimer);
+                activeRun.cancelled = true;
+                activeRun.abort.abort();
+                activeRun = null;
+            }
             // Deactivate the active mode first, then run every plugin's
             // shutdown hook (regardless of which mode is active — a plugin may
             // own background state even outside its mode). Best-effort: log
@@ -981,6 +1747,26 @@ export async function startService(opts) {
             await new Promise((res, rej) => {
                 wss.close(err => (err ? rej(err) : res()));
             });
+            // Multi-host model: a per-session host owns its own Chrome (distinct
+            // userDataDir + CDP port). Tear that Chrome down with the host so the
+            // slot's CDP port frees up and a session reusing the slot gets a fresh
+            // browser — not the previous session's logged-in profile. The legacy
+            // single-Chrome model (no userDataDir) deliberately leaves its Chrome
+            // running, reused across runs / dev-server restarts.
+            if (userDataDir) {
+                const launchPort = (() => {
+                    try {
+                        return Number(new URL(cdpUrl).port) || 9222;
+                    }
+                    catch {
+                        return 9222;
+                    }
+                })();
+                try {
+                    await closeDebugChrome(launchPort);
+                }
+                catch { /* best-effort */ }
+            }
         },
     };
 }