@hover-dev/core 0.9.0 → 0.11.0

package/README.md

@@ -17,7 +17,9 @@ The local Node service. Owns:
 | `detect.ts` | `detectAgents()`, `resolveBinForAgent()`, `resolveOnPath()` — PATH scanning |
 | `argv.ts` | `buildArgv()` — protocol-aware argv construction, throws `UnsupportedAgentProtocolError` for `acp` / `pi-rpc` |
 | `invoke.ts` | `invokeAgent()` — async-iterable spawning + stdout streaming |
-| `claude.ts` | Claude Code descriptor: `claude -p`, stream-json parser, sandbox flags |
+| `claude.ts` | Claude Code descriptor: `claude -p`, stream-json parser, hard sandbox flags |
+| `codex.ts` | OpenAI Codex CLI descriptor: `codex exec --json`, JSONL parser, soft sandbox (`--sandbox read-only`) |
+| `cursor.ts` | Cursor CLI descriptor (v0.9): stream-JSON / NDJSON parser, soft sandbox |
 
 To add an agent: implement an `AgentDescriptor`, register it in `registry.ts`. Done.
 
@@ -43,7 +45,7 @@ pnpm smoke http://localhost:5173/ "log in then add a todo named 'verify hover'"
 Environment variables:
 
 - `HOVER_CDP` — CDP URL (default `http://localhost:9222`)
-- `HOVER_AGENT` — agent id (omit to auto-detect; tries the user's stated preference, then the first installed agent in registry order — `claude` → `codex` today)
+- `HOVER_AGENT` — agent id (omit to auto-detect; tries the user's stated preference, then the first installed agent in registry order — `claude` → `codex` → `cursor-agent` today)
 - `HOVER_MODEL` — model for the agent (default `sonnet`, much cheaper than opus)
 
 ## Sandboxing (what the smoke test enforces)

package/dist/agents/aider.d.ts

@@ -0,0 +1,16 @@
+import type { AgentDescriptor, ParserState } from './types.js';
+export declare const aiderAgent: AgentDescriptor;
+/**
+ * Test-only escape hatches, same pattern as cursor.ts / codex.ts.
+ */
+export declare const __testing: {
+    freshState: () => ParserState;
+    resetCounters: (state: ParserState) => void;
+    getState: (state: ParserState) => {
+        runningLines: number;
+        runningSessionId: string | undefined;
+        collectedText: string[];
+        sawErrorEvent: boolean;
+    };
+};
+//# sourceMappingURL=aider.d.ts.map

package/dist/agents/aider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aider.d.ts","sourceRoot":"","sources":["../../src/agents/aider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAA8B,WAAW,EAAE,MAAM,YAAY,CAAC;AAsH3F,eAAO,MAAM,UAAU,EAAE,eA0GxB,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,SAAS;sBACJ,WAAW;2BACJ,WAAW;sBAChB,WAAW;;;;;;CAS9B,CAAC"}

package/dist/agents/aider.js

@@ -0,0 +1,169 @@
+function aiderState(state) {
+    if (typeof state.runningLines !== 'number') {
+        state.runningLines = 0;
+        state.collectedText = [];
+        state.sawErrorEvent = false;
+        state.runningSessionId = undefined;
+    }
+    return state;
+}
+function resetAiderCounters(s) {
+    s.runningLines = 0;
+    s.collectedText = [];
+    s.sawErrorEvent = false;
+    s.runningSessionId = undefined;
+}
+/**
+ * Aider has no system-prompt flag, so we prepend this preface to the user
+ * prompt (same approach as cursor.ts). The agent treats it as the leading
+ * user-message text.
+ */
+const AIDER_PROMPT_PREFACE = [
+    'You are operating in Hover, a browser-testing tool.',
+    'Use ONLY the MCP playwright tools (prefixed `mcp__playwright__` / `mcp__hover-playwright__`) to drive the browser.',
+    'Do NOT use shell, file-edit, web-search, or any other built-in tool.',
+    'Do NOT navigate to a URL the user is already on; check the page state via `browser_snapshot` first.',
+    'When the task is complete, emit a short summary and stop.',
+].join(' ');
+/**
+ * Lines we treat as noise and drop instead of surfacing as text events.
+ * Aider chatters with status lines that would clutter the widget panel.
+ * Conservative list — anything we don't explicitly skip falls through.
+ */
+function isNoiseLine(line) {
+    const t = line.trim();
+    if (!t)
+        return true;
+    // Common aider boilerplate / banner lines.
+    if (/^Aider v\d/i.test(t))
+        return true;
+    if (/^Main model:/i.test(t))
+        return true;
+    if (/^Weak model:/i.test(t))
+        return true;
+    if (/^Git repo:/i.test(t))
+        return true;
+    if (/^Repo-map:/i.test(t))
+        return true;
+    if (/^VSCode terminal detected/i.test(t))
+        return true;
+    if (/^Use \/help/i.test(t))
+        return true;
+    if (/^Tokens:.*sent.*received/i.test(t))
+        return true;
+    if (/^─{3,}$/.test(t))
+        return true; // horizontal rule
+    return false;
+}
+function detectErrorLine(line) {
+    // Aider prints errors / API failures with a leading marker.
+    return /^(error|fatal|api error|litellm.*error)/i.test(line.trim());
+}
+export const aiderAgent = {
+    id: 'aider',
+    binName: 'aider',
+    protocol: 'argv',
+    streamFormat: 'plain-text',
+    sandboxStrength: 'soft',
+    display: {
+        label: 'Aider',
+        tagline: 'Aider — soft sandbox, plain-text stream, no MCP support',
+        homepage: 'https://aider.chat',
+        installHint: 'pipx install aider-chat',
+    },
+    buildArgs(opts) {
+        // Prepend HOVER-mode preface plus any caller-supplied appendSystemPrompt
+        // to the prompt. Aider has no --append-system-prompt flag, so this is
+        // the closest functional analogue (same trick as cursor.ts).
+        const preface = opts.appendSystemPrompt && opts.appendSystemPrompt.trim().length > 0
+            ? `${AIDER_PROMPT_PREFACE} ${opts.appendSystemPrompt}`
+            : AIDER_PROMPT_PREFACE;
+        const finalPrompt = `${preface}\n\n${opts.prompt}`;
+        const args = ['--message', finalPrompt];
+        // Auto-confirm every prompt so the run doesn't hang.
+        args.push('--yes-always');
+        // Make stdout line-buffered instead of character-streamed; friendlier
+        // for our per-line parseEvent loop.
+        args.push('--no-stream');
+        // Defang git side-effects. Aider's default behaviour is to auto-commit
+        // every edit it makes; for a browser-driving agent that should never
+        // edit files this is still a hazard if cwd is a stale repo.
+        args.push('--no-auto-commits');
+        args.push('--no-git');
+        if (opts.model) {
+            args.push('--model', opts.model);
+        }
+        // Aider's `--restore-chat-history` is a boolean (no session-id form);
+        // we deliberately do NOT pass it. `opts.sessionId` is ignored because
+        // there is no way to select a specific past session by ID.
+        // No equivalents for --max-budget-usd / --allowedTools / --mcp-config /
+        // --append-system-prompt — all four are absent from aider.
+        return args;
+    },
+    parseEvent(line, state = {}) {
+        const s = aiderState(state);
+        const out = [];
+        // Emit a synthetic session_start on the very first non-empty line so
+        // the widget gets the same shape it expects from JSON-based agents.
+        if (!s.runningSessionId) {
+            // Cheap unique id; aider has no real session_id we can echo. The
+            // Math.random() suffix is load-bearing — two states created in the
+            // same millisecond would otherwise collide and break per-invocation
+            // session tracking.
+            const rand = Math.random().toString(36).slice(2, 8);
+            s.runningSessionId = `aider-${Date.now().toString(36)}-${rand}`;
+            out.push({ kind: 'session_start', sessionId: s.runningSessionId });
+        }
+        if (isNoiseLine(line))
+            return out;
+        if (detectErrorLine(line)) {
+            s.sawErrorEvent = true;
+            out.push({ kind: 'text', text: line.trim() });
+            return out;
+        }
+        // Treat everything else as assistant text. Aider has no per-tool events
+        // so we cannot emit tool_use / tool_result — see file-header doc comment.
+        s.runningLines += 1;
+        s.collectedText.push(line.trim());
+        out.push({ kind: 'text', text: line.trim() });
+        return out;
+    },
+    /**
+     * Aider doesn't emit a terminal event — the child process simply exits
+     * after the final printed line. Synthesize session_end from accumulated
+     * state, same pattern as codex.ts.
+     */
+    onStreamEnd(exitCode, state = {}) {
+        const s = aiderState(state);
+        // The "summary" is the last non-empty text line, which is typically
+        // aider's final answer. If we collected nothing, leave it undefined
+        // rather than fabricating.
+        const lastText = s.collectedText.length > 0
+            ? s.collectedText[s.collectedText.length - 1]
+            : undefined;
+        return {
+            kind: 'session_end',
+            turns: s.runningLines,
+            // costUsd intentionally undefined — aider's "Tokens:" status line is
+            // ad-hoc text, not a stable API. We don't fabricate a number.
+            isError: s.sawErrorEvent || (exitCode != null && exitCode !== 0),
+            summary: lastText,
+        };
+    },
+};
+/**
+ * Test-only escape hatches, same pattern as cursor.ts / codex.ts.
+ */
+export const __testing = {
+    freshState: () => ({}),
+    resetCounters: (state) => resetAiderCounters(aiderState(state)),
+    getState: (state) => {
+        const s = aiderState(state);
+        return {
+            runningLines: s.runningLines,
+            runningSessionId: s.runningSessionId,
+            collectedText: [...s.collectedText],
+            sawErrorEvent: s.sawErrorEvent,
+        };
+    },
+};

package/dist/agents/gemini.d.ts

@@ -0,0 +1,17 @@
+import type { AgentDescriptor, ParserState } from './types.js';
+export declare const geminiAgent: AgentDescriptor;
+/**
+ * Test-only escape hatches, same pattern as cursor.ts / codex.ts.
+ */
+export declare const __testing: {
+    freshState: () => ParserState;
+    resetCounters: (state: ParserState) => void;
+    getState: (state: ParserState) => {
+        runningTurns: number;
+        runningSessionId: string | undefined;
+        runningModel: string | undefined;
+        lastAssistantText: string | undefined;
+        sawErrorEvent: boolean;
+    };
+};
+//# sourceMappingURL=gemini.d.ts.map

package/dist/agents/gemini.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gemini.d.ts","sourceRoot":"","sources":["../../src/agents/gemini.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAA8B,WAAW,EAAE,MAAM,YAAY,CAAC;AA4K3F,eAAO,MAAM,WAAW,EAAE,eAiJzB,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,SAAS;sBACJ,WAAW;2BACJ,WAAW;sBAChB,WAAW;;;;;;;CAU9B,CAAC"}

package/dist/agents/gemini.js

@@ -0,0 +1,197 @@
+function geminiState(state) {
+    if (typeof state.runningTurns !== 'number') {
+        state.runningTurns = 0;
+        state.runningSessionId = undefined;
+        state.runningModel = undefined;
+        state.lastAssistantText = undefined;
+        state.sawErrorEvent = false;
+        state.toolNameByUseId = new Map();
+    }
+    return state;
+}
+function resetGeminiCounters(s) {
+    s.runningTurns = 0;
+    s.runningSessionId = undefined;
+    s.runningModel = undefined;
+    s.lastAssistantText = undefined;
+    s.sawErrorEvent = false;
+    s.toolNameByUseId.clear();
+}
+/** Strip the `mcp__playwright__` / `mcp__hover-playwright__` prefix so tool
+ *  names match the normalised names claude / codex / cursor / qwen emit. */
+function stripMcpPrefix(raw) {
+    return raw.replace(/^mcp__playwright__/, '').replace(/^mcp__hover-playwright__/, '');
+}
+/**
+ * Extract assistant text from a `message` event whose `content` may be a
+ * plain string OR an array of `{type:'text', text}` content blocks. Gemini's
+ * docs aren't explicit on which shape ships per build, so we handle both.
+ */
+function extractMessageText(ev) {
+    if (typeof ev.content === 'string') {
+        const t = ev.content.trim();
+        return t.length > 0 ? t : undefined;
+    }
+    if (Array.isArray(ev.content)) {
+        const parts = ev.content
+            .filter(b => b.type === 'text' && typeof b.text === 'string')
+            .map(b => b.text.trim())
+            .filter(t => t.length > 0);
+        return parts.length > 0 ? parts.join('\n') : undefined;
+    }
+    return undefined;
+}
+const GEMINI_PROMPT_PREFACE = [
+    'You are operating in Hover, a browser-testing tool.',
+    'Use ONLY the MCP playwright tools (prefixed `mcp__playwright__` / `mcp__hover-playwright__`) to drive the browser.',
+    'Do NOT use shell, file-edit, web-search, or any other built-in tool.',
+    'Do NOT navigate to a URL the user is already on; check the page state via `browser_snapshot` first.',
+    'When the task is complete, emit a short summary and stop.',
+].join(' ');
+export const geminiAgent = {
+    id: 'gemini',
+    binName: 'gemini',
+    protocol: 'argv',
+    streamFormat: 'json-lines',
+    sandboxStrength: 'soft',
+    display: {
+        label: 'Gemini',
+        tagline: 'Google Gemini — soft sandbox (no built-in tool deny-list)',
+        homepage: 'https://github.com/google-gemini/gemini-cli',
+        installHint: 'npm install -g @google/gemini-cli',
+    },
+    buildArgs(opts) {
+        // Gemini has no --append-system-prompt CLI flag (only the
+        // GEMINI_SYSTEM_MD env var which writes a file). Prepend the HOVER-mode
+        // preface to the prompt instead — same pattern as cursor.ts / aider.ts.
+        const preface = opts.appendSystemPrompt && opts.appendSystemPrompt.trim().length > 0
+            ? `${GEMINI_PROMPT_PREFACE} ${opts.appendSystemPrompt}`
+            : GEMINI_PROMPT_PREFACE;
+        const finalPrompt = `${preface}\n\n${opts.prompt}`;
+        const args = ['-p', finalPrompt];
+        // NDJSON streaming output.
+        args.push('--output-format', 'stream-json');
+        // Auto-approve all tool calls so the run doesn't hang. The newer
+        // canonical form is --approval-mode=yolo; --yolo is deprecated but
+        // still accepted in 2026-05. We use the modern form.
+        args.push('--approval-mode', 'yolo');
+        if (opts.model) {
+            args.push('--model', opts.model);
+        }
+        if (opts.sessionId) {
+            // --resume <id> is the documented form. -r is the alias. The single
+            // string 'latest' picks the most recent session; we only pass an
+            // explicit id, never the literal 'latest'.
+            args.push('--resume', opts.sessionId);
+        }
+        // MCP servers configured via `gemini mcp add` at install time — no
+        // per-invocation --mcp-config equivalent.
+        // No equivalent for --max-budget-usd or --allowedTools / --disallowedTools
+        // in the disable-built-ins sense.
+        return args;
+    },
+    parseEvent(line, state = {}) {
+        if (!line.trim())
+            return [];
+        let ev;
+        try {
+            ev = JSON.parse(line);
+        }
+        catch {
+            return [{ kind: 'raw', line }];
+        }
+        const s = geminiState(state);
+        const out = [];
+        if (ev.type === 'init') {
+            resetGeminiCounters(s);
+            s.runningModel = ev.model;
+            if (ev.session_id) {
+                s.runningSessionId = ev.session_id;
+                out.push({ kind: 'session_start', sessionId: ev.session_id, model: ev.model });
+            }
+            return out;
+        }
+        if (ev.type === 'message') {
+            // Only count and surface assistant messages — user echoes (the
+            // role:'user' message events) don't count as turns from our POV.
+            if (ev.role === 'assistant' || ev.role === undefined) {
+                s.runningTurns += 1;
+                out.push({ kind: 'usage', turns: s.runningTurns });
+                const text = extractMessageText(ev);
+                if (text) {
+                    s.lastAssistantText = text;
+                    out.push({ kind: 'text', text });
+                }
+            }
+            return out;
+        }
+        if (ev.type === 'tool_use') {
+            const rawName = ev.name ?? '';
+            const tool = stripMcpPrefix(rawName);
+            if (ev.id)
+                s.toolNameByUseId.set(ev.id, tool);
+            out.push({ kind: 'tool_use', tool, input: ev.input });
+            return out;
+        }
+        if (ev.type === 'tool_result') {
+            const isError = ev.is_error === true;
+            out.push({ kind: 'tool_result', isError });
+            return out;
+        }
+        if (ev.type === 'result') {
+            // result.stats may carry turns; prefer it over our running count.
+            const turns = ev.stats?.turns ?? ev.stats?.model?.turns ?? s.runningTurns;
+            const isError = ev.is_error === true || ev.error !== undefined && ev.error !== null;
+            if (isError)
+                s.sawErrorEvent = true;
+            out.push({
+                kind: 'session_end',
+                turns,
+                // costUsd intentionally undefined — gemini's stats block does not
+                // include $ figures.
+                isError,
+                summary: ev.response ?? s.lastAssistantText,
+            });
+            return out;
+        }
+        if (ev.type === 'error') {
+            s.sawErrorEvent = true;
+            const msg = ev.message ?? ev.error?.message ?? `[gemini] error`;
+            out.push({ kind: 'text', text: msg });
+            return out;
+        }
+        return [];
+    },
+    /**
+     * Gemini's `result` event already produces a session_end via parseEvent;
+     * this fallback is for the case where the child exits without emitting a
+     * `result` (e.g. crash, signal). Same shape as cursor.ts / qwen.ts.
+     */
+    onStreamEnd(exitCode, state = {}) {
+        const s = geminiState(state);
+        return {
+            kind: 'session_end',
+            turns: s.runningTurns,
+            // costUsd intentionally undefined — see parseEvent note.
+            isError: s.sawErrorEvent || (exitCode != null && exitCode !== 0),
+            summary: s.lastAssistantText,
+        };
+    },
+};
+/**
+ * Test-only escape hatches, same pattern as cursor.ts / codex.ts.
+ */
+export const __testing = {
+    freshState: () => ({}),
+    resetCounters: (state) => resetGeminiCounters(geminiState(state)),
+    getState: (state) => {
+        const s = geminiState(state);
+        return {
+            runningTurns: s.runningTurns,
+            runningSessionId: s.runningSessionId,
+            runningModel: s.runningModel,
+            lastAssistantText: s.lastAssistantText,
+            sawErrorEvent: s.sawErrorEvent,
+        };
+    },
+};

package/dist/agents/qwen.d.ts

@@ -0,0 +1,17 @@
+import type { AgentDescriptor, ParserState } from './types.js';
+export declare const qwenAgent: AgentDescriptor;
+/**
+ * Test-only escape hatches, same pattern as cursor.ts / codex.ts.
+ */
+export declare const __testing: {
+    freshState: () => ParserState;
+    resetCounters: (state: ParserState) => void;
+    getState: (state: ParserState) => {
+        runningTurns: number;
+        runningSessionId: string | undefined;
+        runningModel: string | undefined;
+        lastAssistantText: string | undefined;
+        sawErrorEvent: boolean;
+    };
+};
+//# sourceMappingURL=qwen.d.ts.map

package/dist/agents/qwen.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"qwen.d.ts","sourceRoot":"","sources":["../../src/agents/qwen.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAA8B,WAAW,EAAE,MAAM,YAAY,CAAC;AAiK3F,eAAO,MAAM,SAAS,EAAE,eAqJvB,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,SAAS;sBACJ,WAAW;2BACJ,WAAW;sBAChB,WAAW;;;;;;;CAU9B,CAAC"}

package/dist/agents/qwen.js

@@ -0,0 +1,183 @@
+function qwenState(state) {
+    if (typeof state.runningTurns !== 'number') {
+        state.runningTurns = 0;
+        state.runningSessionId = undefined;
+        state.runningModel = undefined;
+        state.lastAssistantText = undefined;
+        state.sawErrorEvent = false;
+        state.toolNameByUseId = new Map();
+    }
+    return state;
+}
+function resetQwenCounters(s) {
+    s.runningTurns = 0;
+    s.runningSessionId = undefined;
+    s.runningModel = undefined;
+    s.lastAssistantText = undefined;
+    s.sawErrorEvent = false;
+    s.toolNameByUseId.clear();
+}
+/** Strip the `mcp__playwright__` / `mcp__hover-playwright__` prefix so tool
+ *  names match the normalised names claude / codex / cursor emit. */
+function stripMcpPrefix(raw) {
+    return raw.replace(/^mcp__playwright__/, '').replace(/^mcp__hover-playwright__/, '');
+}
+const QWEN_PROMPT_PREFACE = [
+    'You are operating in Hover, a browser-testing tool.',
+    'Use ONLY the MCP playwright tools (prefixed `mcp__playwright__` / `mcp__hover-playwright__`) to drive the browser.',
+    'Do NOT use shell, file-edit, web-search, or any other built-in tool.',
+    'Do NOT navigate to a URL the user is already on; check the page state via `browser_snapshot` first.',
+    'When the task is complete, emit a short summary and stop.',
+].join(' ');
+export const qwenAgent = {
+    id: 'qwen',
+    binName: 'qwen',
+    protocol: 'argv',
+    streamFormat: 'json-lines',
+    sandboxStrength: 'soft',
+    display: {
+        label: 'Qwen Code',
+        tagline: 'Qwen Code — soft sandbox (no built-in tool deny-list)',
+        homepage: 'https://github.com/QwenLM/qwen-code',
+        installHint: 'npm install -g @qwen-code/qwen-code@latest',
+    },
+    buildArgs(opts) {
+        const args = ['-p', opts.prompt];
+        // NDJSON streaming output.
+        args.push('--output-format', 'stream-json');
+        // Auto-approve all tool calls so the run doesn't hang. The newer
+        // canonical form is --approval-mode=yolo; --yolo is deprecated but
+        // still works in 2026-05. We use the modern form.
+        args.push('--approval-mode', 'yolo');
+        if (opts.model) {
+            args.push('--model', opts.model);
+        }
+        if (opts.sessionId) {
+            // --resume <sessionId> is the documented headless form. --continue
+            // (no arg) picks the most recent — NOT what we want when a specific
+            // session was passed.
+            args.push('--resume', opts.sessionId);
+        }
+        // Qwen has a real --append-system-prompt flag — use it instead of
+        // prepending to the user prompt. Concatenate the standing Hover-mode
+        // preface with whatever the caller appended.
+        const sysPrompt = opts.appendSystemPrompt && opts.appendSystemPrompt.trim().length > 0
+            ? `${QWEN_PROMPT_PREFACE} ${opts.appendSystemPrompt}`
+            : QWEN_PROMPT_PREFACE;
+        args.push('--append-system-prompt', sysPrompt);
+        // MCP servers configured in ~/.qwen/settings.json — no per-invocation
+        // --mcp-config equivalent. Same constraint as cursor / codex.
+        // No equivalent for --max-budget-usd or --allowedTools / --disallowedTools.
+        return args;
+    },
+    parseEvent(line, state = {}) {
+        if (!line.trim())
+            return [];
+        let ev;
+        try {
+            ev = JSON.parse(line);
+        }
+        catch {
+            return [{ kind: 'raw', line }];
+        }
+        const s = qwenState(state);
+        const out = [];
+        if (ev.type === 'system' && ev.subtype === 'session_start') {
+            resetQwenCounters(s);
+            s.runningModel = ev.model;
+            if (ev.session_id) {
+                s.runningSessionId = ev.session_id;
+                out.push({ kind: 'session_start', sessionId: ev.session_id, model: ev.model });
+            }
+            return out;
+        }
+        if (ev.type === 'assistant' && ev.message) {
+            s.runningTurns += 1;
+            // Emit a usage event so the widget can advance its turn counter.
+            // costUsd intentionally omitted — qwen doesn't publish $ in stream.
+            out.push({ kind: 'usage', turns: s.runningTurns });
+            for (const block of ev.message.content ?? []) {
+                if (block.type === 'text') {
+                    const text = block.text?.trim();
+                    if (text) {
+                        s.lastAssistantText = text;
+                        out.push({ kind: 'text', text });
+                    }
+                }
+                else if (block.type === 'tool_use') {
+                    const rawName = block.name ?? '';
+                    const tool = stripMcpPrefix(rawName);
+                    if (block.id)
+                        s.toolNameByUseId.set(block.id, tool);
+                    out.push({ kind: 'tool_use', tool, input: block.input });
+                }
+            }
+            return out;
+        }
+        // tool_result blocks are wrapped in `user` messages (Anthropic Messages
+        // convention). We surface them as tool_result events.
+        if (ev.type === 'user' && ev.message) {
+            for (const block of ev.message.content ?? []) {
+                if (block.type === 'tool_result') {
+                    const isError = block.is_error === true;
+                    out.push({ kind: 'tool_result', isError });
+                }
+            }
+            return out;
+        }
+        if (ev.type === 'result') {
+            const isError = ev.is_error === true ||
+                (typeof ev.subtype === 'string' && /error|fail/i.test(ev.subtype));
+            if (isError)
+                s.sawErrorEvent = true;
+            out.push({
+                kind: 'session_end',
+                turns: s.runningTurns,
+                // costUsd intentionally undefined — qwen doesn't publish $.
+                isError,
+                summary: ev.result ?? s.lastAssistantText,
+            });
+            return out;
+        }
+        // Qwen emits various error envelopes mid-stream; surface them as text.
+        if (ev.type && /error/i.test(ev.type)) {
+            s.sawErrorEvent = true;
+            const msg = ev.error?.message ?? ev.text ?? ev.result ?? `[qwen] ${ev.type}`;
+            out.push({ kind: 'text', text: msg });
+            return out;
+        }
+        return [];
+    },
+    /**
+     * Qwen's `result` event already produces a session_end via parseEvent;
+     * this fallback is for the case where the child exits without emitting a
+     * `result` (e.g. crash, signal). Mirrors codex.ts / cursor.ts shape.
+     */
+    onStreamEnd(exitCode, state = {}) {
+        const s = qwenState(state);
+        return {
+            kind: 'session_end',
+            turns: s.runningTurns,
+            // costUsd intentionally undefined — see parseEvent note.
+            isError: s.sawErrorEvent || (exitCode != null && exitCode !== 0),
+            summary: s.lastAssistantText,
+        };
+    },
+};
+/**
+ * Test-only escape hatches, same pattern as cursor.ts / codex.ts.
+ */
+export const __testing = {
+    freshState: () => ({}),
+    resetCounters: (state) => resetQwenCounters(qwenState(state)),
+    getState: (state) => {
+        const s = qwenState(state);
+        return {
+            runningTurns: s.runningTurns,
+            runningSessionId: s.runningSessionId,
+            runningModel: s.runningModel,
+            lastAssistantText: s.lastAssistantText,
+            sawErrorEvent: s.sawErrorEvent,
+        };
+    },
+};

package/dist/agents/registry.d.ts

@@ -2,13 +2,15 @@ import type { AgentDescriptor } from './types.js';
 /**
  * Registry of agents Hover can drive.
  *
- * To add support for another agent (e.g. aider, gemini, cline, continue,
- * qwen, kilo), implement its AgentDescriptor in its own file and register
- * it here. The rest of the system — detect, argv, invoke, service, widget —
- * works without further changes.
+ * To add support for another agent (e.g. cline, continue, kilo), implement
+ * its AgentDescriptor in its own file and register it here. The rest of the
+ * system — detect, argv, invoke, service, widget — works without further
+ * changes.
  *
  * Insertion order is the order shown in the widget's agent dropdown, so put
- * the recommended primary first.
+ * the recommended primary first. The two hard-sandbox / first-party agents
+ * (claude, codex) lead; the soft-sandbox third-party agents follow in the
+ * order they were added.
  */
 export declare const AGENTS: Record<string, AgentDescriptor>;
 export declare function getAgent(id: string): AgentDescriptor | undefined;

package/dist/agents/registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/agents/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAKlD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAIlD,CAAC;AAEF,wBAAgB,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAEhE;AAED,+DAA+D;AAC/D,wBAAgB,UAAU,IAAI,eAAe,EAAE,CAE9C"}
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/agents/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAQlD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAOlD,CAAC;AAEF,wBAAgB,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAEhE;AAED,+DAA+D;AAC/D,wBAAgB,UAAU,IAAI,eAAe,EAAE,CAE9C"}

package/dist/agents/registry.js

@@ -1,21 +1,29 @@
 import { claudeAgent } from './claude.js';
 import { codexAgent } from './codex.js';
 import { cursorAgent } from './cursor.js';
+import { aiderAgent } from './aider.js';
+import { geminiAgent } from './gemini.js';
+import { qwenAgent } from './qwen.js';
 /**
  * Registry of agents Hover can drive.
  *
- * To add support for another agent (e.g. aider, gemini, cline, continue,
- * qwen, kilo), implement its AgentDescriptor in its own file and register
- * it here. The rest of the system — detect, argv, invoke, service, widget —
- * works without further changes.
+ * To add support for another agent (e.g. cline, continue, kilo), implement
+ * its AgentDescriptor in its own file and register it here. The rest of the
+ * system — detect, argv, invoke, service, widget — works without further
+ * changes.
  *
  * Insertion order is the order shown in the widget's agent dropdown, so put
- * the recommended primary first.
+ * the recommended primary first. The two hard-sandbox / first-party agents
+ * (claude, codex) lead; the soft-sandbox third-party agents follow in the
+ * order they were added.
  */
 export const AGENTS = {
     [claudeAgent.id]: claudeAgent,
     [codexAgent.id]: codexAgent,
     [cursorAgent.id]: cursorAgent,
+    [aiderAgent.id]: aiderAgent,
+    [geminiAgent.id]: geminiAgent,
+    [qwenAgent.id]: qwenAgent,
 };
 export function getAgent(id) {
     return AGENTS[id];

package/dist/scripts/bench-multi-tab.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=bench-multi-tab.d.ts.map

package/dist/scripts/bench-multi-tab.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bench-multi-tab.d.ts","sourceRoot":"","sources":["../../src/scripts/bench-multi-tab.ts"],"names":[],"mappings":""}

package/dist/scripts/bench-multi-tab.js

@@ -0,0 +1,192 @@
+/**
+ * Benchmark agent success rate on the multi-tab "Pay with PayHover" flow.
+ *
+ * Why this exists — v0.10's central theme is "agent can drive cross-tab
+ * flows in the wild." The system-prompt addendum (cdpHint.ts rule 5/6/7)
+ * is the lever we're tuning. This script gives us a number to tune
+ * against: across N iterations, how often does the agent get from
+ * "browse the store" to "Order placed"?
+ *
+ * Per iteration the agent has to:
+ *   1. Browse the e-commerce store, add 1+ items to cart, go to checkout.
+ *   2. Fill the shipping form.
+ *   3. Pick "Pay with PayHover" (opens a new tab at localhost:5177).
+ *   4. Switch to the new tab, fill card number + CVV, click Continue.
+ *   5. Wait ~600ms for the simulated 3DS pre-check.
+ *   6. Fill the 6-digit OTP (always 123456 in the sandbox).
+ *   7. Click Confirm. The provider tab closes itself.
+ *   8. Switch back to the original tab, observe the "Order placed" view.
+ *
+ * Steps 3, 4, 7, 8 are the failure-prone ones.
+ *
+ * Assumes:
+ *   - Debug Chrome on :9222 (run `pnpm smoke:chrome`).
+ *   - e-commerce on :5174 AND payment-provider on :5177 both running
+ *     (run `pnpm dev:example:e-commerce` and `pnpm dev:example:payment-provider`
+ *     in two terminals before invoking this).
+ *
+ * Usage:
+ *   pnpm --filter @hover-dev/core exec tsx src/scripts/bench-multi-tab.ts [n]
+ *   pnpm bench-multi-tab [n]
+ *
+ * `n` defaults to 5. Per-iteration timeout is 5 minutes — multi-tab flows
+ * are slow because the agent does a lot of browser_snapshot calls.
+ *
+ * Output: per-run pass/fail + final summary (success rate, median wall
+ * time, median turns, median cost in $). A/B prompt changes by running
+ * once on each branch and comparing.
+ */
+import { WebSocket } from 'ws';
+import { startService } from '../service.js';
+const PROMPT = process.env.HOVER_BENCH_PROMPT ??
+    [
+        'Open http://localhost:5174 (Hover Store).',
+        'Add any item to the cart, go to checkout, fill the shipping form with',
+        'realistic values, then choose "Pay with PayHover". A new tab opens at',
+        'the payment provider — switch to it, fill in card 4242 4242 4242 4242',
+        'with CVV 123, click Continue, wait for the OTP step, enter 123456,',
+        'click Confirm. The popup will close. Switch back to the original tab',
+        'and verify the order shows as placed.',
+    ].join(' ');
+const ITERATIONS = Number(process.argv[2] ?? 5);
+const PER_RUN_TIMEOUT_MS = 5 * 60 * 1000;
+async function singleRun(idx) {
+    process.stderr.write(`\n[bench-multi-tab] run ${idx + 1}/${ITERATIONS}\n`);
+    const service = await startService({
+        port: 0,
+        agentId: 'claude',
+        model: 'sonnet',
+        cdpUrl: 'http://localhost:9222',
+        devRoot: process.cwd(),
+    });
+    return new Promise((resolve) => {
+        const ws = new WebSocket(`ws://127.0.0.1:${service.port}`);
+        const t0 = performance.now();
+        let turns = 0;
+        let costUsd = null;
+        let resolved = false;
+        const finish = (result) => {
+            if (resolved)
+                return;
+            resolved = true;
+            try {
+                ws.close(1000);
+            }
+            catch { /* already closed */ }
+            service.close().finally(() => resolve(result));
+        };
+        const timeout = setTimeout(() => {
+            finish({
+                ok: false,
+                wallMs: performance.now() - t0,
+                turns,
+                costUsd,
+                reason: `timed out after ${PER_RUN_TIMEOUT_MS / 1000}s`,
+            });
+        }, PER_RUN_TIMEOUT_MS);
+        ws.on('open', () => {
+            ws.send(JSON.stringify({ type: 'command', payload: { text: PROMPT } }));
+        });
+        ws.on('message', (raw) => {
+            let msg;
+            try {
+                msg = JSON.parse(raw.toString());
+            }
+            catch {
+                return;
+            }
+            if (msg.type !== 'event')
+                return;
+            const ev = msg.payload;
+            if (ev.kind === 'tool_use') {
+                turns += 1;
+                if (process.env.HOVER_BENCH_VERBOSE === '1') {
+                    const ev2 = ev;
+                    process.stderr.write(`    [turn ${turns}] ${ev2.name ?? '<tool>'}\n`);
+                }
+            }
+            if (ev.kind === 'session_end') {
+                clearTimeout(timeout);
+                const evAny = ev;
+                if (typeof evAny.costUsd === 'number')
+                    costUsd = evAny.costUsd;
+                finish({
+                    ok: !evAny.isError,
+                    wallMs: performance.now() - t0,
+                    turns,
+                    costUsd,
+                    reason: evAny.isError ? 'agent reported error' : undefined,
+                });
+            }
+        });
+        ws.on('error', (err) => {
+            clearTimeout(timeout);
+            finish({
+                ok: false,
+                wallMs: performance.now() - t0,
+                turns,
+                costUsd,
+                reason: `WS error: ${err.message}`,
+            });
+        });
+    });
+}
+function median(xs) {
+    if (xs.length === 0)
+        return 0;
+    const sorted = [...xs].sort((a, b) => a - b);
+    const mid = Math.floor(sorted.length / 2);
+    return sorted.length % 2 === 0
+        ? (sorted[mid - 1] + sorted[mid]) / 2
+        : sorted[mid];
+}
+function fmtMs(ms) {
+    return `${(ms / 1000).toFixed(1)}s`;
+}
+function fmtUsd(usd) {
+    return usd == null ? '–' : `$${usd.toFixed(4)}`;
+}
+async function main() {
+    process.stderr.write(`[bench-multi-tab] ${ITERATIONS} iterations, per-run timeout ${PER_RUN_TIMEOUT_MS / 1000}s\n`);
+    process.stderr.write(`[bench-multi-tab] prompt: ${PROMPT.slice(0, 80)}…\n`);
+    const results = [];
+    for (let i = 0; i < ITERATIONS; i++) {
+        try {
+            const r = await singleRun(i);
+            results.push(r);
+            const status = r.ok ? '✓ PASS' : '✗ FAIL';
+            process.stderr.write(`[bench-multi-tab] run ${i + 1}: ${status} · ${fmtMs(r.wallMs)} · ${r.turns} turns · ${fmtUsd(r.costUsd)}${r.reason ? ` · ${r.reason}` : ''}\n`);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            results.push({ ok: false, wallMs: 0, turns: 0, costUsd: null, reason: msg });
+            process.stderr.write(`[bench-multi-tab] run ${i + 1}: ✗ FAIL · setup error · ${msg}\n`);
+        }
+    }
+    const passes = results.filter((r) => r.ok);
+    const successRate = passes.length / results.length;
+    process.stderr.write('\n[bench-multi-tab] summary\n');
+    process.stderr.write(`  success rate: ${(successRate * 100).toFixed(0)}% (${passes.length}/${results.length})\n`);
+    if (passes.length > 0) {
+        process.stderr.write(`  median wall:  ${fmtMs(median(passes.map((r) => r.wallMs)))}\n`);
+        process.stderr.write(`  median turns: ${median(passes.map((r) => r.turns)).toFixed(0)}\n`);
+        const costs = passes.map((r) => r.costUsd).filter((c) => c != null);
+        if (costs.length > 0) {
+            process.stderr.write(`  median cost:  ${fmtUsd(median(costs))}\n`);
+        }
+    }
+    if (passes.length < results.length) {
+        process.stderr.write(`\n  failures:\n`);
+        results.forEach((r, i) => {
+            if (!r.ok)
+                process.stderr.write(`    run ${i + 1}: ${r.reason ?? 'unknown'}\n`);
+        });
+    }
+    // Exit non-zero if EVERY run failed — useful for CI plumbing later. A
+    // partial-pass run still exits 0 so we collect signal across branches.
+    process.exit(passes.length === 0 ? 1 : 0);
+}
+main().catch((err) => {
+    process.stderr.write(`[bench-multi-tab] fatal: ${err instanceof Error ? err.stack ?? err.message : String(err)}\n`);
+    process.exit(1);
+});

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

@@ -1 +1 @@
-{"version":3,"file":"cdpHint.d.ts","sourceRoot":"","sources":["../../src/service/cdpHint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,UAAU,GAAG;IAAG,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE;AAa7C,wBAAgB,YAAY,CAAC,IAAI,EAAE,GAAG,EAAE,GAAG,MAAM,CA4FhD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,GAAG,EAAE,GAAG,MAAM,CAYtD"}
+{"version":3,"file":"cdpHint.d.ts","sourceRoot":"","sources":["../../src/service/cdpHint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,UAAU,GAAG;IAAG,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE;AAa7C,wBAAgB,YAAY,CAAC,IAAI,EAAE,GAAG,EAAE,GAAG,MAAM,CAmIhD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,GAAG,EAAE,GAAG,MAAM,CAYtD"}

package/dist/service/cdpHint.js

@@ -101,6 +101,45 @@ export function buildCdpHint(tabs) {
         `  4. To see the current page state, call browser_snapshot first. Only`,
         `     navigate if you actually need a different URL.`,
         ``,
+        `Multi-tab + cross-origin flows (Stripe Checkout, OAuth login, "Pay with X" popups):`,
+        ``,
+        `  5. When you click something that may open a new tab (target=_blank, a`,
+        `     window.open trigger, a "Pay with …" / "Sign in with …" button), the`,
+        `     popup tab is where the next user-visible step happens — but your tools`,
+        `     stay anchored to the prior tab until you switch. After such a click:`,
+        ``,
+        `       a) Call browser_tabs(action='list') to see if a new tab appeared.`,
+        `          A new entry at a different origin is the popup.`,
+        `       b) Call browser_tabs(action='select', idx=<popup idx>) to focus it,`,
+        `          then browser_snapshot the new tab and proceed.`,
+        `       c) When the popup closes (it usually does so on success/cancel —`,
+        `          window.close() or after a redirect chain), browser_tabs(list)`,
+        `          will no longer show it. The current page may be invalid; call`,
+        `          browser_tabs(action='select', idx=0) to refocus the original tab,`,
+        `          then browser_snapshot it. The original tab's DOM may have updated`,
+        `          via a postMessage handler (e.g. it should now show a "Success" or`,
+        `          "Payment complete" state).`,
+        `       d) If the original tab's snapshot looks unchanged (still showing the`,
+        `          checkout form / login button), the postMessage handler may not`,
+        `          have fired yet or may not exist. Wait once with`,
+        `          browser_wait_for_text("<expected success copy>", timeout=3000)`,
+        `          before concluding the flow is broken.`,
+        ``,
+        `  6. OAuth-style redirect chains: when a tab redirects through several`,
+        `     origins (myapp → identity provider → /callback?code=… → myapp), watch`,
+        `     browser_tabs after each browser_snapshot — the same tab idx can switch`,
+        `     origin underneath you. The URL in browser_tabs(list) is authoritative.`,
+        ``,
+        `  7. Cross-origin cookie/session updates: after the popup closes and you're`,
+        `     back on the original tab, the server-set session cookie may be present`,
+        `     in the browser but the React state hasn't yet picked it up. The most`,
+        `     likely cause is a missing or slow postMessage handler — NOT a real`,
+        `     bug yet. Try browser_wait_for_text once for the expected logged-in`,
+        `     copy with a 3s timeout. If nothing shows, report it as a Finding`,
+        `     ("Original tab did not update after popup closed — likely missing`,
+        `     postMessage listener or auth refresh"); do NOT browser_navigate to`,
+        `     same-origin to force a refresh (rule #2 still applies).`,
+        ``,
         `Narration format — affects how the widget renders your run for the user:`,
         ``,
         `  Before each LOGICAL STEP (a coherent unit of work like "Open the login`,

package/dist/service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AAqEA,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,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gFAAgF;IAChF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;6EAGyE;IACzE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;uBAImB;IACnB,OAAO,CAAC,EAAE,mBAAmB,EAAE,CAAC;CACjC;AAED,MAAM,WAAW,aAAa;IAC5B;4EACwE;IACxE,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAiDD,wBAAsB,YAAY,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CAmrB/E"}
+{"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,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gFAAgF;IAChF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;6EAGyE;IACzE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;uBAImB;IACnB,OAAO,CAAC,EAAE,mBAAmB,EAAE,CAAC;CACjC;AAED,MAAM,WAAW,aAAa;IAC5B;4EACwE;IACxE,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAiDD,wBAAsB,YAAY,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CAswB/E"}

package/dist/service.js

@@ -13,6 +13,7 @@
  *     { type: 'skill-saved',     payload: { name, path } }
  *     { type: 'skill-exists',    payload: { slug, existingPath } }
  *     { type: 'skills-list',     payload: { skills: SkillSummary[] } }
+ *     { type: 'specs-list',      payload: { specs: SpecSummary[] } }
  *     { type: 'spec-saved',      payload: { name, path } }
  *     { type: 'spec-exists',     payload: { slug, existingPath } }
  *     { type: 'case-csv-saved',  payload: { name, path } }
@@ -20,7 +21,12 @@
  *     { type: 'error',           payload: { message } }
  *
  *   client → server
- *     { type: 'command',       payload: { text, sessionId? } }
+ *     { 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: 'cancel' }
  *     { type: 'check-cdp',     payload: { pageUrl } }                 // "is this widget in the debug Chrome?"
  *     { type: 'launch-chrome', payload: { pageUrl } }                 // start debug Chrome, navigate to pageUrl
@@ -29,6 +35,7 @@
  *     { type: 'save-spec',     payload: { name, description, steps, assertions?, overwrite? } }
  *     { type: 'save-case-csv', payload: { name, description, steps, assertions?, jiraProjectKey?, labels?, overwrite? } }
  *     { type: 'list-skills' }
+ *     { type: 'list-specs' }                                            // ask for every spec under __vibe_tests__/, with parsed JSDoc headers
  *     { 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
  *
@@ -48,6 +55,7 @@ import { getAgent } from './agents/registry.js';
 import { getPreflight, invalidatePreflight } from './playwright/preflightCache.js';
 import { resolveMcpConfig } from './playwright/resolveMcpConfig.js';
 import { listSkills } from './skills/writeSkill.js';
+import { listSpecs } from './specs/listSpecs.js';
 import { send, sendIfOpen } from './service/types.js';
 import { buildCdpHint, buildCdpHintResume } from './service/cdpHint.js';
 import { handleCheckCdp, handleLaunchChrome, handleFocusDebug, } from './service/cdpHandlers.js';
@@ -525,6 +533,15 @@ export async function startService(opts) {
                 send(ws, { type: 'skills-list', payload: { skills } });
                 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 } });
+                return;
+            }
             if (msg.type === 'save-spec') {
                 await handleSaveArtifact(ws, msg, devRoot, SPEC_CONFIG);
                 return;
@@ -551,6 +568,15 @@ export async function startService(opts) {
             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 }`, we collect tool_use events server-side
+            // into a SkillStep[] and, on session_end with no error, overwrite the
+            // existing __vibe_tests__/<slug>.spec.ts. This is the 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())
                 return;
             if (busy) {
@@ -563,6 +589,16 @@ export async function startService(opts) {
             busy = true;
             cancelled = false;
             inflight = new AbortController();
+            // Re-record step collector — populated as tool_use events stream by,
+            // consumed at session_end to overwrite the original spec. Empty unless
+            // reRecordSlug is set on this command. We seed with a synthetic
+            // `user` step so writeSpec's JSDoc Original-prompt: line carries the
+            // text the agent was actually given (which is the prompt we read out
+            // of the existing spec — the same one we're regenerating).
+            const reRecordSteps = [];
+            if (reRecordSlug) {
+                reRecordSteps.push({ kind: 'user', text });
+            }
             try {
                 // Build the MCP config first — it's pure local file IO and lets
                 // us assert plugin-contributed servers landed in the config even
@@ -684,6 +720,61 @@ export async function startService(opts) {
                     if (cancelled || ws.readyState !== WebSocket.OPEN)
                         return;
                     send(ws, { type: 'event', payload: ev });
+                    // Re-record collection. Mirror what widget client.js does on the
+                    // way past tool_use events: accumulate into a SkillStep[] so we
+                    // can write a fresh spec when the session ends. We do this only
+                    // when this command was launched in re-record mode; ordinary
+                    // commands don't need server-side step retention (widget owns
+                    // that for normal saves).
+                    if (reRecordSlug && ev.kind === 'tool_use') {
+                        reRecordSteps.push({
+                            kind: 'step',
+                            tool: ev.tool,
+                            input: ev.input,
+                        });
+                    }
+                    if (reRecordSlug && ev.kind === 'session_end') {
+                        // Cancelled or errored runs: don't overwrite — the existing
+                        // spec is still valid. Tell the client what happened.
+                        if (ev.isError) {
+                            sendIfOpen(ws, {
+                                type: 'error',
+                                payload: {
+                                    message: `Re-record failed: ${ev.summary ?? 'agent reported an error'}. ` +
+                                        `Original spec left unchanged.`,
+                                },
+                            });
+                        }
+                        else {
+                            // Snapshot the agent's final summary into a synthetic `done`
+                            // step so writeSpec's `Outcome:` header reflects the new run.
+                            if (ev.summary) {
+                                reRecordSteps.push({ kind: 'done', summary: ev.summary });
+                            }
+                            // Overwrite. writeSpec uses the slug to name the file; we
+                            // pass the original slug verbatim so the path is stable.
+                            try {
+                                const { writeSpec } = await import('./specs/writeSpec.js');
+                                const result = await writeSpec({
+                                    devRoot,
+                                    name: reRecordSlug,
+                                    steps: reRecordSteps,
+                                    overwrite: true,
+                                });
+                                sendIfOpen(ws, {
+                                    type: 'spec-saved',
+                                    payload: { name: reRecordSlug, path: result.path },
+                                });
+                            }
+                            catch (e) {
+                                const m = e instanceof Error ? e.message : String(e);
+                                sendIfOpen(ws, {
+                                    type: 'error',
+                                    payload: { message: `Re-record could not write spec: ${m}` },
+                                });
+                            }
+                        }
+                    }
                 }
             }
             catch (err) {

package/dist/specs/listSpecs.d.ts

@@ -0,0 +1,40 @@
+export interface SpecSummary {
+    /** Path-relative slug, e.g. `login-and-counter`. Identifies the spec. */
+    slug: string;
+    /** Absolute path to the .spec.ts file. */
+    path: string;
+    /** `Original prompt:` parsed from the JSDoc header. `null` for
+     *  hand-authored specs that have no header — they list but can't be
+     *  re-recorded automatically. */
+    originalPrompt: string | null;
+    /** First line of `Outcome:` from the JSDoc header, if present. */
+    outcome: string | null;
+    /** Number of `Steps:` lines parsed (informational only). */
+    stepCount: number;
+    /** File mtime in ms — used to show "saved 2 hours ago" in the UI. */
+    mtimeMs: number;
+}
+export interface SpecHeader {
+    /** Raw text of `Original prompt:` line, or null when absent. */
+    originalPrompt: string | null;
+    /** First line of `Outcome:`. */
+    outcome: string | null;
+    /** Step lines from the `Steps:` block, in order. */
+    steps: string[];
+    /** Lines from the `Expected:` block, in order. */
+    expected: string[];
+}
+/**
+ * Parse the JSDoc header that `writeSpec.ts` emits. Tolerant of:
+ *   - Specs without any JSDoc (returns all-null).
+ *   - Hand-edited specs where users reordered or trimmed sections.
+ *   - Long prompts that wrap across lines (we take only the first line).
+ */
+export declare function parseSpecHeader(source: string): SpecHeader;
+/**
+ * List every `*.spec.ts` file under `<devRoot>/__vibe_tests__/` with its
+ * parsed header. Returns newest-first by mtime so the widget overlay shows
+ * recently-saved specs at the top.
+ */
+export declare function listSpecs(devRoot: string): Promise<SpecSummary[]>;
+//# sourceMappingURL=listSpecs.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"listSpecs.d.ts","sourceRoot":"","sources":["../../src/specs/listSpecs.ts"],"names":[],"mappings":"AAkBA,MAAM,WAAW,WAAW;IAC1B,yEAAyE;IACzE,IAAI,EAAE,MAAM,CAAC;IACb,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb;;qCAEiC;IACjC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,kEAAkE;IAClE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,4DAA4D;IAC5D,SAAS,EAAE,MAAM,CAAC;IAClB,qEAAqE;IACrE,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,UAAU;IACzB,gEAAgE;IAChE,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,gCAAgC;IAChC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,oDAAoD;IACpD,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,kDAAkD;IAClD,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,CAsB1D;AA4BD;;;;GAIG;AACH,wBAAsB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAkCvE"}

package/dist/specs/listSpecs.js

@@ -0,0 +1,114 @@
+/**
+ * List + parse Hover-generated Playwright specs under `<devRoot>/__vibe_tests__/`.
+ *
+ * Used by:
+ *   - The widget's "Specs" overlay tab (server pushes a SpecSummary[] list).
+ *   - The CLI's `hover re-record <spec>` subcommand (parses one spec for its
+ *     `Original prompt:` JSDoc header).
+ *
+ * Hand-authored specs (no Hover JSDoc header) are listed but reported with
+ * `originalPrompt: null` — the UI / CLI surfaces that "this spec can't be
+ * re-recorded automatically; the natural-language intent isn't recorded."
+ *
+ * Mirrors the listSkills shape so widget UI can use the same row renderer.
+ */
+import { readdir, readFile } from 'node:fs/promises';
+import { stat } from 'node:fs/promises';
+import { join } from 'node:path';
+/**
+ * Parse the JSDoc header that `writeSpec.ts` emits. Tolerant of:
+ *   - Specs without any JSDoc (returns all-null).
+ *   - Hand-edited specs where users reordered or trimmed sections.
+ *   - Long prompts that wrap across lines (we take only the first line).
+ */
+export function parseSpecHeader(source) {
+    // JSDoc block right after the @playwright/test import (or at file top).
+    // We don't require it to be the very first JSDoc — there could be a
+    // banner comment from a linter. We DO require it to appear before the
+    // first `test(` / `test.describe(` so that long file footers can't
+    // confuse the parser.
+    const beforeFirstTest = source.split(/^\s*(?:test|test\.describe)\s*\(/m)[0] ?? source;
+    const blockMatch = beforeFirstTest.match(/\/\*\*([\s\S]*?)\*\//);
+    if (!blockMatch) {
+        return { originalPrompt: null, outcome: null, steps: [], expected: [] };
+    }
+    const block = blockMatch[1];
+    const originalPrompt = extractScalar(block, /^\s*\*\s*Original prompt:\s*(.+?)\s*$/m);
+    const outcome = extractScalar(block, /^\s*\*\s*Outcome:\s*(.+?)\s*$/m);
+    return {
+        originalPrompt,
+        outcome,
+        steps: extractList(block, /^\s*\*\s*Steps:\s*$/m),
+        expected: extractList(block, /^\s*\*\s*Expected:\s*$/m),
+    };
+}
+function extractScalar(block, re) {
+    const m = block.match(re);
+    return m ? m[1].trim() : null;
+}
+/**
+ * Extract a JSDoc list-style block. Given a header regex matching "Steps:"
+ * or "Expected:", read subsequent ` * <indented line>` lines until the next
+ * top-level marker (blank ` *` line or another `Section:` header).
+ */
+function extractList(block, headerRe) {
+    const match = block.match(headerRe);
+    if (!match)
+        return [];
+    const start = (match.index ?? 0) + match[0].length;
+    const tail = block.slice(start);
+    const lines = [];
+    for (const raw of tail.split('\n')) {
+        // Stop at a blank JSDoc line (` *` only) or another `Section:` header.
+        if (/^\s*\*\s*$/.test(raw))
+            break;
+        if (/^\s*\*\s*\w[\w ]*:\s*$/.test(raw) || /^\s*\*\s*\w[\w ]*:\s/.test(raw))
+            break;
+        const m = raw.match(/^\s*\*\s*(?:[•\-\*\d.]\s*)*(.+?)\s*$/);
+        if (m && m[1])
+            lines.push(m[1]);
+    }
+    return lines;
+}
+/**
+ * List every `*.spec.ts` file under `<devRoot>/__vibe_tests__/` with its
+ * parsed header. Returns newest-first by mtime so the widget overlay shows
+ * recently-saved specs at the top.
+ */
+export async function listSpecs(devRoot) {
+    const root = join(devRoot, '__vibe_tests__');
+    let entries;
+    try {
+        entries = await readdir(root);
+    }
+    catch {
+        return [];
+    }
+    const summaries = [];
+    for (const entry of entries) {
+        if (!entry.endsWith('.spec.ts'))
+            continue;
+        const path = join(root, entry);
+        let content;
+        let mtimeMs = 0;
+        try {
+            content = await readFile(path, 'utf-8');
+            const st = await stat(path);
+            mtimeMs = st.mtimeMs;
+        }
+        catch {
+            continue;
+        }
+        const header = parseSpecHeader(content);
+        summaries.push({
+            slug: entry.replace(/\.spec\.ts$/, ''),
+            path,
+            originalPrompt: header.originalPrompt,
+            outcome: header.outcome,
+            stepCount: header.steps.length,
+            mtimeMs,
+        });
+    }
+    summaries.sort((a, b) => b.mtimeMs - a.mtimeMs);
+    return summaries;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hover-dev/core",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "Hover's local Node service: agent invocation, Playwright CDP preflight, WebSocket bridge.",
   "license": "Apache-2.0",
   "author": "Hyperyond",
@@ -75,6 +75,7 @@
     "verify-spec": "tsx src/scripts/verify-spec.ts",
     "ws-smoke": "tsx src/scripts/ws-smoke.ts",
     "bench-ttfb": "tsx src/scripts/bench-ttfb.ts",
+    "bench-multi-tab": "tsx src/scripts/bench-multi-tab.ts",
     "test": "vitest run",
     "test:watch": "vitest"
   },