@hover-dev/core 0.15.0 → 0.16.0

package/dist/playwright/resolveMcpConfig.js

@@ -3,6 +3,14 @@ import { mkdirSync, writeFileSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
 import { tmpdir } from 'node:os';
 import process from 'node:process';
+/** The `mcp__<id>` tool-name prefix Claude Code exposes a plugin MCP server's
+ *  tools under: non-alphanumerics collapse to `_` and edges are trimmed (e.g.
+ *  `@hover-dev/security:flows` → `mcp__hover_dev_security_flows`). Used to build
+ *  the hard-sandbox allow-list. Single source so the service and the CLI scan
+ *  command can't drift on how the prefix is derived. */
+export function mcpToolPrefix(serverId) {
+    return `mcp__${serverId.replace(/[^a-zA-Z0-9]+/g, '_').replace(/^_+|_+$/g, '')}`;
+}
 export function resolveMcpConfig(opts) {
     // Resolve the package's main file, then walk back to its package root.
     // Using `package.json` as the resolution target is the documented
@@ -46,8 +54,13 @@ export function resolveMcpConfig(opts) {
     const config = { mcpServers };
     const outDir = resolve(tmpdir(), 'hover');
     mkdirSync(outDir, { recursive: true });
-    const suffix = opts.suffix ? `-${opts.suffix}` : '';
-    const outPath = resolve(outDir, `mcp-config-${opts.port}${suffix}.json`);
+    // Sanitise the suffix before it lands in a filesystem path — it's derived
+    // from plugin/mode ids, so guard against path separators and other unsafe
+    // characters slipping into the filename.
+    const safeSuffix = opts.suffix
+        ? `-${opts.suffix.replace(/[^a-zA-Z0-9._-]+/g, '_')}`
+        : '';
+    const outPath = resolve(outDir, `mcp-config-${opts.port}${safeSuffix}.json`);
     writeFileSync(outPath, JSON.stringify(config, null, 2), 'utf-8');
     return outPath;
 }

package/dist/plugin-api.d.ts

@@ -40,6 +40,13 @@ export interface HoverPluginMode {
     /** Mode ids this mode cannot be active alongside. Two plugins both
      *  needing an exclusive proxy would set each other here. */
     conflictsWith?: string[];
+    /** CSS colour the widget tints to while this mode is engaged — the mode
+     *  bar, launcher, and panel chrome all retint to it. Any CSS colour the
+     *  user's Chrome accepts (the widget derives the dim/hover/ink/tint shades
+     *  from it via `color-mix`). Defaults to security orange (`#fb923c`) when
+     *  omitted, so a plugin only sets this to stand apart — e.g. pentest's
+     *  `#ef4444` red signalling "offensive mode". */
+    accent?: string;
 }
 export interface HoverPluginMcpServer {
     /** Stable, namespaced id (`@hover-dev/security:flows`). Host enforces

package/dist/plugin-api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin-api.d.ts","sourceRoot":"","sources":["../src/plugin-api.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"plugin-api.d.ts","sourceRoot":"","sources":["../src/plugin-api.ts"],"names":[],"mappings":"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"}

package/dist/runSession.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runSession.d.ts","sourceRoot":"","sources":["../src/runSession.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAGxD,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB;oFACgF;IAChF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,mEAAmE;IACnE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;6EACyE;IACzE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;yCAEqC;IACrC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;+EAC2E;IAC3E,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC7B;oFACgF;IAChF,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,2DAA2D;IAC3D,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B;mCAC+B;IAC/B,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,yCAAyC;IACzC,OAAO,EAAE,MAAM,CAAC;IAChB,qDAAqD;IACrD,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,wBAAsB,UAAU,CAC9B,IAAI,EAAE,iBAAiB,EACvB,OAAO,EAAE,CAAC,EAAE,EAAE,WAAW,KAAK,IAAI,GACjC,OAAO,CAAC,gBAAgB,CAAC,CAuD3B"}
+{"version":3,"file":"runSession.d.ts","sourceRoot":"","sources":["../src/runSession.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAGxD,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB;oFACgF;IAChF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,mEAAmE;IACnE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;6EACyE;IACzE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;yCAEqC;IACrC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;+EAC2E;IAC3E,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC7B;oFACgF;IAChF,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,2DAA2D;IAC3D,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B;mCAC+B;IAC/B,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,yCAAyC;IACzC,OAAO,EAAE,MAAM,CAAC;IAChB,qDAAqD;IACrD,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,wBAAsB,UAAU,CAC9B,IAAI,EAAE,iBAAiB,EACvB,OAAO,EAAE,CAAC,EAAE,EAAE,WAAW,KAAK,IAAI,GACjC,OAAO,CAAC,gBAAgB,CAAC,CA4D3B"}

package/dist/runSession.js

@@ -70,6 +70,11 @@ export async function runSession(opts, onEvent) {
                 isError = true;
         }
     }
+    // On abort (opts.signal), invokeAgent SIGTERMs the child and no session_end
+    // arrives, so the error flag above never gets set. Honour the doc contract
+    // ("True if the run ended in error or was aborted") by flipping it here.
+    if (opts.signal?.aborted)
+        isError = true;
     if (summary)
         steps.push({ kind: 'done', summary });
     return { steps, summary, isError };

package/dist/service/cdpHandlers.d.ts

@@ -14,13 +14,9 @@ import type { WebSocket } from 'ws';
 import { type LaunchOptions } from '../playwright/launchChrome.js';
 import { type ClientMessage } from './types.js';
 /** Extra launch options surfaced from the active mode (security plugin
- *  needs proxy + spki + separate profile + non-default CDP port). When
- *  none are set, behaviour is identical to pre-v0.7 normal-mode launch. */
-export type LaunchExtras = Pick<LaunchOptions, 'userDataDir' | 'proxy'> & {
-    /** Override CDP port (mode-specific, e.g. 9333 for security). When set,
-     *  this also wins over the `port` parsed from cdpUrl. */
-    cdpPort?: number;
-};
+ *  needs a resident proxy + spki). When none are set, behaviour is identical
+ *  to pre-v0.7 normal-mode launch. */
+export type LaunchExtras = Pick<LaunchOptions, 'proxy'>;
 /**
  * "Is this widget running inside the debug Chrome?" The widget asks this on
  * connect (and after every status-changing event) so it can render itself as

package/dist/service/cdpHandlers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cdpHandlers.d.ts","sourceRoot":"","sources":["../../src/service/cdpHandlers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC;AAEpC,OAAO,EAAqB,KAAK,aAAa,EAAE,MAAM,+BAA+B,CAAC;AACtF,OAAO,EAAQ,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AAEtD;;2EAE2E;AAC3E,MAAM,MAAM,YAAY,GAAG,IAAI,CAAC,aAAa,EAAE,aAAa,GAAG,OAAO,CAAC,GAAG;IACxE;6DACyD;IACzD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAClC,EAAE,EAAE,SAAS,EACb,GAAG,EAAE,aAAa,EAClB,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,YAAY,GACpB,OAAO,CAAC,IAAI,CAAC,CAWf;AAED;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,EAAE,EAAE,SAAS,EACb,GAAG,EAAE,aAAa,EAClB,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,YAAY,GACpB,OAAO,CAAC,IAAI,CAAC,CAkCf;AAED;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CACpC,EAAE,EAAE,SAAS,EACb,GAAG,EAAE,aAAa,EAClB,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,YAAY,GACpB,OAAO,CAAC,IAAI,CAAC,CAaf"}
+{"version":3,"file":"cdpHandlers.d.ts","sourceRoot":"","sources":["../../src/service/cdpHandlers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC;AAEpC,OAAO,EAAqB,KAAK,aAAa,EAAE,MAAM,+BAA+B,CAAC;AACtF,OAAO,EAAQ,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AAEtD;;sCAEsC;AACtC,MAAM,MAAM,YAAY,GAAG,IAAI,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC;AAExD;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAClC,EAAE,EAAE,SAAS,EACb,GAAG,EAAE,aAAa,EAClB,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,YAAY,GACpB,OAAO,CAAC,IAAI,CAAC,CAQf;AAED;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,EAAE,EAAE,SAAS,EACb,GAAG,EAAE,aAAa,EAClB,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,YAAY,GACpB,OAAO,CAAC,IAAI,CAAC,CA4Bf;AAED;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CACpC,EAAE,EAAE,SAAS,EACb,GAAG,EAAE,aAAa,EAClB,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,YAAY,GACpB,OAAO,CAAC,IAAI,CAAC,CAUf"}

package/dist/service/cdpHandlers.js

@@ -27,10 +27,7 @@ export async function handleCheckCdp(ws, msg, cdpUrl, extras) {
         send(ws, { type: 'error', payload: { message: 'check-cdp: pageUrl is required' } });
         return;
     }
-    const effectiveCdpUrl = extras?.cdpPort
-        ? `http://localhost:${extras.cdpPort}`
-        : cdpUrl;
-    const status = await checkCdpStatus(effectiveCdpUrl, pageUrl);
+    const status = await checkCdpStatus(cdpUrl, pageUrl);
     send(ws, { type: 'cdp-status', payload: status });
 }
 /**
@@ -48,7 +45,7 @@ export async function handleLaunchChrome(ws, msg, cdpUrl, extras) {
     // Tell the widget we're launching so it can render a spinner immediately —
     // findChromeBinary + spawn + ready-poll can take a few seconds.
     send(ws, { type: 'cdp-status', payload: { state: 'no-cdp', launching: true } });
-    const port = extras?.cdpPort ?? (() => {
+    const port = (() => {
         try {
             return Number(new URL(cdpUrl).port) || 9222;
         }
@@ -59,19 +56,13 @@ export async function handleLaunchChrome(ws, msg, cdpUrl, extras) {
     const result = await launchDebugChrome({
         url: pageUrl,
         port,
-        userDataDir: extras?.userDataDir,
         proxy: extras?.proxy,
     });
     if (!result.ok) {
         send(ws, { type: 'cdp-status', payload: { state: 'no-cdp', reason: result.reason } });
         return;
     }
-    // Re-check status against the port we actually launched on, so a mode-
-    // specific port (9333 for security) doesn't get probed at 9222.
-    const effectiveCdpUrl = extras?.cdpPort
-        ? `http://localhost:${extras.cdpPort}`
-        : cdpUrl;
-    const status = await checkCdpStatus(effectiveCdpUrl, pageUrl);
+    const status = await checkCdpStatus(cdpUrl, pageUrl);
     send(ws, { type: 'cdp-status', payload: status });
 }
 /**
@@ -87,10 +78,7 @@ export async function handleFocusDebug(ws, msg, cdpUrl, extras) {
         send(ws, { type: 'error', payload: { message: 'focus-debug: pageUrl is required' } });
         return;
     }
-    const effectiveCdpUrl = extras?.cdpPort
-        ? `http://localhost:${extras.cdpPort}`
-        : cdpUrl;
-    const result = await focusDebugTab(effectiveCdpUrl, pageUrl);
+    const result = await focusDebugTab(cdpUrl, pageUrl);
     if (!result.ok) {
         send(ws, { type: 'error', payload: { message: `focus-debug: ${result.reason}` } });
     }

package/dist/service.d.ts

@@ -29,6 +29,12 @@ export interface ServiceOptions {
      *  see the proxy; moving it here is what enables the single-Chrome model.
      *  Default false (shims pass it through from their own option). */
     autoLaunchChrome?: boolean;
+    /** Opt-in: give the agent READ-ONLY, fenced access to the project's source
+     *  via a `read_source` / `list_source` MCP server (in addition to Playwright
+     *  MCP), in every mode. Lets it author against real selectors/routes and do
+     *  white-box security/pentest. Fenced to devRoot, secrets/keys/.git/build
+     *  excluded, no write/exec. Default false — the agent stays browser-only. */
+    codeContext?: boolean;
     /** The dev-server URL the auto-launched Chrome should open. Each shim knows
      *  its own framework's dev URL and passes it here. Defaults to the cdp host
      *  if unset, but shims should always provide it. */

package/dist/service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AA6EA,OAAO,EAEL,KAAK,mBAAmB,EAEzB,MAAM,iBAAiB,CAAC;AAEzB,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;oFACgF;IAChF,YAAY,CAAC,EAAE,KAAK,GAAG,SAAS,GAAG,IAAI,CAAC;IACxC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gFAAgF;IAChF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;gFAG4E;IAC5E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;uBAImB;IACnB,OAAO,CAAC,EAAE,mBAAmB,EAAE,CAAC;IAChC;;;;;;uEAMmE;IACnE,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B;;wDAEoD;IACpD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,aAAa;IAC5B;4EACwE;IACxE,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAiED,wBAAsB,YAAY,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CA64B/E"}
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AA+EA,OAAO,EAEL,KAAK,mBAAmB,EAEzB,MAAM,iBAAiB,CAAC;AAQzB,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;oFACgF;IAChF,YAAY,CAAC,EAAE,KAAK,GAAG,SAAS,GAAG,IAAI,CAAC;IACxC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gFAAgF;IAChF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;gFAG4E;IAC5E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;uBAImB;IACnB,OAAO,CAAC,EAAE,mBAAmB,EAAE,CAAC;IAChC;;;;;;uEAMmE;IACnE,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B;;;;iFAI6E;IAC7E,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;wDAEoD;IACpD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,aAAa;IAC5B;4EACwE;IACxE,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAiED,wBAAsB,YAAY,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CA49B/E"}

package/dist/service.js

@@ -46,6 +46,8 @@
  *     { type: 'list-modes' }
  */
 import { WebSocketServer, WebSocket } from 'ws';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
 import { runSession } from './runSession.js';
 import { readConventions } from './service/conventions.js';
 import { optimizeSpecWithAgent } from './specs/optimizeSpecWithAgent.js';
@@ -53,7 +55,7 @@ import { promoteOptimized, discardOptimized } from './specs/optimizeSpec.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 { resolveMcpConfig, mcpToolPrefix } from './playwright/resolveMcpConfig.js';
 import { launchDebugChrome } from './playwright/launchChrome.js';
 import { listSpecs } from './specs/listSpecs.js';
 import { readSeeds, BUILTIN_SEEDS } from './specs/seeds.js';
@@ -62,6 +64,11 @@ 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 { CURRENT_API_VERSION, } from './plugin-api.js';
+/** The source-reader MCP server (codeContext). Id → the `mcp__hover_source`
+ *  tool prefix; script path resolved relative to this module so it works from
+ *  dist/. Spawned only when codeContext is enabled. */
+const SOURCE_MCP_ID = 'hover-source';
+const SOURCE_MCP_SCRIPT = resolve(dirname(fileURLToPath(import.meta.url)), 'mcp', 'sourceServer.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;
@@ -195,6 +202,15 @@ export async function startService(opts) {
                 }
             }
         }
+        // codeContext (opt-in, all modes): the fenced read-only source reader.
+        if (opts.codeContext) {
+            extra.push({
+                id: SOURCE_MCP_ID,
+                command: process.execPath,
+                args: [SOURCE_MCP_SCRIPT],
+                env: { HOVER_PROJECT_ROOT: devRoot },
+            });
+        }
         // 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.)
@@ -239,6 +255,25 @@ 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;
+    /** 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
@@ -273,6 +308,9 @@ export async function startService(opts) {
             id: p.mode.id,
             label: p.mode.label,
             description: p.mode.description,
+            // Widget retints to this while the mode is engaged (falls back to
+            // security orange in the widget when absent).
+            accent: p.mode.accent,
             pluginName: p.name,
         }));
         const payload = { current: currentModeId, available };
@@ -410,20 +448,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 +493,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',
@@ -460,7 +520,7 @@ export async function startService(opts) {
                 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' },
@@ -515,7 +575,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' },
@@ -690,16 +750,21 @@ export async function startService(opts) {
                 : undefined;
             if (typeof text !== 'string' || !text.trim())
                 return;
-            if (busy) {
+            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;
             try {
                 // Build the MCP config first — it's pure local file IO and lets
                 // us assert plugin-contributed servers landed in the config even
@@ -710,13 +775,7 @@ export async function startService(opts) {
                 // 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',
@@ -771,6 +830,13 @@ export async function startService(opts) {
                         }
                     }
                 }
+                // 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__hover_source (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.`;
+                }
                 // 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
@@ -784,8 +850,8 @@ export async function startService(opts) {
                 }
                 // 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.
+                // switch-agent on an active run, but defense in depth.) runSession gates
+                // the allow/deny lists on the agent's sandboxStrength internally.
                 const invokedAgentId = currentAgentId;
                 // Active mode's plugin-contributed MCP server ids — added to the
                 // hard-sandbox allow list so Claude can actually call them. Claude
@@ -794,18 +860,20 @@ export async function startService(opts) {
                 // 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 = [];
                 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)}`);
+                                activePluginMcpIds.push(mcpToolPrefix(srv.id));
                             }
                         }
                     }
                 }
+                // codeContext: the fenced source reader is allowed in every mode.
+                if (opts.codeContext)
+                    activePluginMcpIds.push(mcpToolPrefix(SOURCE_MCP_ID));
                 const runResult = await runSession({
                     agentId: invokedAgentId,
                     prompt: text,
@@ -821,19 +889,21 @@ export async function startService(opts) {
                     maxBudgetUsd,
                     model,
                     apiKey: currentApiKey,
-                    signal: inflight.signal,
+                    signal: run.abort.signal,
                 }, (ev) => {
-                    if (cancelled || ws.readyState !== WebSocket.OPEN)
+                    // 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;
-                    send(ws, { type: 'event', payload: ev });
+                    emitToRun({ 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 (reRecordSlug && !run.cancelled) {
                     if (runResult.isError) {
-                        sendIfOpen(ws, {
+                        emitToRun({
                             type: 'error',
                             payload: {
                                 message: `Re-record failed: ${runResult.summary || 'agent reported an error'}. ` +
@@ -850,14 +920,14 @@ export async function startService(opts) {
                                 steps: runResult.steps,
                                 overwrite: true,
                             });
-                            sendIfOpen(ws, {
+                            emitToRun({
                                 type: 'spec-saved',
                                 payload: { name: reRecordSlug, path: written.path },
                             });
                         }
                         catch (e) {
                             const m = e instanceof Error ? e.message : String(e);
-                            sendIfOpen(ws, {
+                            emitToRun({
                                 type: 'error',
                                 payload: { message: `Re-record could not write spec: ${m}` },
                             });
@@ -872,30 +942,25 @@ 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 });
                     // 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);
                 }
             }
             finally {
-                busy = false;
-                inflight = null;
+                if (run.graceTimer)
+                    clearTimeout(run.graceTimer);
+                activeRun = null;
             }
         });
     });
@@ -954,6 +1019,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

package/dist/specs/optimizeSpec.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"optimizeSpec.d.ts","sourceRoot":"","sources":["../../src/specs/optimizeSpec.ts"],"names":[],"mappings":"AAcA,OAAO,EAAc,KAAK,WAAW,EAAE,MAAM,cAAc,CAAC;AAC5D,OAAO,EAA4B,KAAK,QAAQ,EAAE,MAAM,YAAY,CAAC;AAErE,qBAAa,aAAc,SAAQ,KAAK;gBAC1B,OAAO,EAAE,MAAM;CAI5B;AAED,wEAAwE;AACxE,MAAM,MAAM,UAAU,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAE7D,MAAM,WAAW,cAAc;IAC7B,wEAAwE;IACxE,aAAa,EAAE,MAAM,CAAC;IACtB,sCAAsC;IACtC,IAAI,EAAE,MAAM,CAAC;IACb;2EACuE;IACvE,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,wBAAsB,YAAY,CAChC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,UAAU,GACrB,OAAO,CAAC,cAAc,CAAC,CAsCzB;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,WAAW,GAAG,IAAI,EAC3B,KAAK,GAAE,QAAQ,EAAO,GACrB,MAAM,CAmDR;AAED,kEAAkE;AAClE,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAI/C;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAahF;AAMD;;gCAEgC;AAChC,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAYrF;AAED;+BAC+B;AAC/B,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEnF"}
+{"version":3,"file":"optimizeSpec.d.ts","sourceRoot":"","sources":["../../src/specs/optimizeSpec.ts"],"names":[],"mappings":"AAeA,OAAO,EAAc,KAAK,WAAW,EAAE,MAAM,cAAc,CAAC;AAC5D,OAAO,EAA4B,KAAK,QAAQ,EAAE,MAAM,YAAY,CAAC;AAGrE,qBAAa,aAAc,SAAQ,KAAK;gBAC1B,OAAO,EAAE,MAAM;CAI5B;AAED,wEAAwE;AACxE,MAAM,MAAM,UAAU,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAE7D,MAAM,WAAW,cAAc;IAC7B,wEAAwE;IACxE,aAAa,EAAE,MAAM,CAAC;IACtB,sCAAsC;IACtC,IAAI,EAAE,MAAM,CAAC;IACb;2EACuE;IACvE,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,wBAAsB,YAAY,CAChC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,UAAU,GACrB,OAAO,CAAC,cAAc,CAAC,CA2CzB;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,WAAW,GAAG,IAAI,EAC3B,KAAK,GAAE,QAAQ,EAAO,GACrB,MAAM,CAmDR;AAED,kEAAkE;AAClE,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAI/C;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAWhF;AAyBD;;gCAEgC;AAChC,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAYrF;AAED;+BAC+B;AAC/B,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEnF"}

package/dist/specs/optimizeSpec.js

@@ -12,8 +12,10 @@
  */
 import { readFile, mkdir, writeFile, rm } from 'node:fs/promises';
 import { join } from 'node:path';
+import { Project } from 'ts-morph';
 import { sidecarDir } from './sidecar.js';
 import { readSeeds, relevantSeeds } from './seeds.js';
+import { softBatch } from './softBatch.js';
 export class OptimizeError extends Error {
     constructor(message) {
         super(message);
@@ -41,11 +43,15 @@ export async function optimizeSpec(devRoot, slug, runCodegen) {
         .map(s => s.tool));
     const seeds = relevantSeeds(await readSeeds(devRoot), specTools);
     const raw = await runCodegen(buildOptimizePrompt(draft, sidecar, seeds));
-    const code = extractCode(raw);
-    const check = validateSpecCode(code);
+    const llmCode = extractCode(raw);
+    const check = validateSpecCode(llmCode);
     if (!check.ok) {
         throw new OptimizeError(`optimization rejected — ${check.errors.join('; ')}`);
     }
+    // Deterministic finishing step: the LLM decided WHAT to assert; soft-batch
+    // applies the safe mechanical rewrite (trailing run of independent assertions
+    // → expect.soft) surgically on its output. See softBatch.ts for the guard.
+    const code = softBatch(llmCode).code;
     const dir = join(devRoot, '__vibe_tests__', '.hover', 'optimized');
     await mkdir(dir, { recursive: true });
     // `.spec.ts.draft`, never `*.spec.ts` — Playwright's glob must not collect a
@@ -133,12 +139,28 @@ export function validateSpecCode(code) {
     if (!/from\s+['"](@playwright\/test|\.\/fixtures)['"]/.test(code)) {
         errors.push('missing @playwright/test (or ./fixtures) import');
     }
-    const open = (code.match(/\{/g) ?? []).length;
-    const close = (code.match(/\}/g) ?? []).length;
-    if (open !== close)
-        errors.push('unbalanced braces');
+    if (hasSyntaxError(code))
+        errors.push('has a syntax error');
     return { ok: errors.length === 0, errors };
 }
+/**
+ * Real syntax check via the TypeScript parser (the same ts-morph the soft-batch
+ * step uses). Replaces a naive `{`/`}` count that mis-flagged a valid spec
+ * asserting on a string like 'a { b' — braces inside string literals are not
+ * structural. We look at SYNTACTIC diagnostics only: a candidate references
+ * `page` / `expect` / `@playwright/test` that aren't resolvable in this throwaway
+ * project, so SEMANTIC ("cannot find module", "implicitly any") diagnostics are
+ * expected and must be ignored — only a genuine parse error (an unbalanced
+ * brace, a stray token) should reject the optimization.
+ */
+function hasSyntaxError(code) {
+    const project = new Project({
+        useInMemoryFileSystem: true,
+        compilerOptions: { allowJs: true },
+    });
+    const sf = project.createSourceFile('__candidate.ts', code, { overwrite: true });
+    return project.getProgram().getSyntacticDiagnostics(sf).length > 0;
+}
 function candidatePathFor(devRoot, slug) {
     return join(devRoot, '__vibe_tests__', '.hover', 'optimized', `${slug}.spec.ts.draft`);
 }

package/dist/specs/softBatch.d.ts

@@ -0,0 +1,14 @@
+/** A trailing run with fewer than this many assertions is left alone —
+ *  `expect.soft` only earns its keep when ≥2 failures could be collected. */
+export declare const MIN_RUN = 2;
+export interface SoftBatchResult {
+    /** The (possibly) rewritten source. */
+    code: string;
+    /** Whether anything changed. */
+    changed: boolean;
+    /** How many assertions were softened across all tests. */
+    softened: number;
+}
+/** Run the soft-batch step over a spec's source text. Pure: text in, text out. */
+export declare function softBatch(source: string): SoftBatchResult;
+//# sourceMappingURL=softBatch.d.ts.map

package/dist/specs/softBatch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"softBatch.d.ts","sourceRoot":"","sources":["../../src/specs/softBatch.ts"],"names":[],"mappings":"AAgCA;6EAC6E;AAC7E,eAAO,MAAM,OAAO,IAAI,CAAC;AAEzB,MAAM,WAAW,eAAe;IAC9B,uCAAuC;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,gCAAgC;IAChC,OAAO,EAAE,OAAO,CAAC;IACjB,0DAA0D;IAC1D,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,kFAAkF;AAClF,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,eAAe,CAuBzD"}