@mknrt/autotests-overkill 1.2.5 → 1.3.0

package/README.md

@@ -47,6 +47,34 @@ Repository-local development:
 
 ## Daily workflow
 
+### Integrated local Cypress runtime
+
+For the `autotests2` checkout, run `npm run mcp:setup` there once and restart Codex. The same Overkill connection now includes its own browser debugger; no HTTP service, separate browser MCP, browser port configuration, or manual Cypress launch is required. The setup uses the installed npm package; a local Overkill checkout can be selected explicitly during development. It verifies the MCP handshake before registering it with Codex. The published package contains the runtime and does not require a sibling source checkout.
+
+Ask Codex to run a spec, diagnose its failure, inspect the page, fix the test, and rerun it. The existing asset/selector/blueprint tools remain available for authoring. Codex edits files using its normal editor; the MCP provides execution and evidence.
+
+| Tool | Behavior |
+| --- | --- |
+| `start_cypress_run` | Starts one existing spec; returns `runId` immediately. Optional `mode` (`run` or `open`), `debug`, `repeats`, `retries`, `browser`, `timeoutSeconds`. |
+| `get_cypress_run` | Reads status, log, errors and attempts, screenshots/videos, captured failure DOM, and observed flakiness. Also reads completed archives after reconnecting. |
+| `inspect_cypress_browser` | `snapshot`, `screenshot`, `evaluate`, `pause`, `resume` in the run's actual Cypress browser. Select live AUT or runner, or an explicit execution context. |
+| `stop_cypress_run` | Stops the run and its browser while retaining evidence. |
+| `cypress_tap` | Open-mode sessions, status, specs, reruns, Command Log/reporter, command snapshots, pin/clear, DOM, ARIA, and element inspection. |
+
+`debug: true` pauses before each test; `resume` continues the command queue. CDP pause/resume is also supported. JavaScript evaluation can change page state. A normal completed run may contain failed tests: check the outcomes, not only process status. Repeats and retries report observed mixed outcomes, not a statistical guarantee of stability.
+
+Managed runs launch the project's installed Cypress Node CLI directly on Windows or Linux/WSL using the opt-in companion config/support bridge. No Bash, PowerShell wrapper, or shell interpolation is required. Shutdown terminates the Windows process tree or POSIX process group. The runner removes inherited `ELECTRON_RUN_AS_NODE`, disables guest telemetry in child processes, escapes bracketed spec names, and allocates local debug/snapshot ports. Ordinary Cypress runs keep their behavior. One managed run per checkout avoids shared fixture/report races. A disconnected MCP session stops its active run. Evidence lives in `.overkill-cache/cypress-runs/<runId>/repeat-N/`; failed attempts keep separate errors and pre-cleanup DOM. DOM and console/network output are bounded and redact credentials; raw network bodies and headers are not collected by default. Local diagnostic runs do not publish dashboard launches.
+
+Requirements: Node.js 22.5+ for Overkill (Cypress 16 requires Node.js 22.12+ on the 22.x line), existing project dependencies, Windows or Linux/WSL, and an installed Chromium browser. On this checkout `chrome-for-testing` is the default. Headed debugging requires the desktop display available to Cypress. No dependency installation is performed by setup. `npm run mcp:check` in `autotests2` runs the full deterministic debug/failure/retry/corrected-rerun check against a temporary local page; afterward its generated spec is archived in `.overkill-cache/selfcheck-specs/` outside ordinary Cypress discovery.
+
+For completed-run command logs and time travel, start with `start_cypress_run({ spec: "cypress/e2e/example.cy.js", mode: "open" })`. Poll `get_cypress_run` until `tap.status` is `requested`, then call `cypress_tap({ action: "status", sessionId, requestId })` with the returned IDs. The managed UI stays alive after the spec completes, until stopped, timed out, or disconnected. Its `get_cypress_run.status` describes the process; TAP describes the selected spec. Open mode permits one session, with `cypress_tap` `run` for reruns; use run mode for independent `repeats`.
+
+TAP status adds `verdict`, `stale`, `timedOut`, and `testsExecuted`. Trust `passed` only when `verdict` is `passed`; `no_tests` means nothing executed. Reruns remember the previous `startedAt` and suppress its verdict until the requested spec starts. A build stuck in loading is bounded by `runTimeoutSeconds` (default 900); `timeoutMs` bounds each CLI request separately. Each new run supersedes the earlier `requestId`.
+
+Use `reporter` for test IDs and command logs, `command` with `testId`/`commandId` for snapshots, then `pin` with the same IDs and optional `at: "before"` or `"after"`. `dom`, `aria`, and `inspect` read the completed or pinned page. Release with `pin` and `clear: true`. Attempts and pin indices start at 1; element-match indices start at 0. Existing project sessions can be discovered using `sessions`; ambiguous sessions require an explicit `sessionId`. During a managed run, TAP mutations are restricted to its owned open session.
+
+[TAP requires Cypress 15.21+ and a Chromium open-mode session](https://docs.cypress.io/app/tooling/cypress-tap). It does not inspect `cypress run`, and retained snapshots depend on `numTestsKeptInMemory`. Use CDP inspection for live paused state. On Windows, the TAP child preserves Cypress exit codes and lets pending asynchronous work finish before exiting, avoiding the Node forced-exit shutdown race; its timeout still applies. TAP CLI/session version mismatches are reported as errors; raw network bodies and headers are omitted from TAP console-property output. Avoid manually changing the open runner's pin while TAP is inspecting it.
+
 1. Refresh local knowledge with `npm run index`.
 2. Start the MCP server through the consumer repository's `.codex/config.toml`, or run `npx autotests-overkill mcp` directly for manual checks.
 3. Use `find_frontend_contract`, `find_existing_test_assets`, and `generate_spec_blueprint` for a new feature draft.

package/dist/src/mcp/cypressTools.d.ts

@@ -0,0 +1,2 @@
+import type { ToolDefinition } from './registerTools.js';
+export declare function cypressTools(): ToolDefinition[];

package/dist/src/mcp/cypressTools.js

@@ -0,0 +1,66 @@
+import { z } from 'zod';
+import { buildToolOutput, toolOutputSchema } from '../contracts/toolOutput.js';
+import { cypressTapInput } from '../runtime/cypressTap.js';
+import { cypressRuntime } from '../runtime/cypressRuntime.js';
+function report(summary, data, actions = []) {
+    return buildToolOutput({
+        summary, evidence: [{ type: 'report', label: 'Managed Cypress runtime', metadata: { runtime: data } }],
+        recommended_actions: actions,
+    });
+}
+export function cypressTools() {
+    return [
+        {
+            name: 'cypress_tap',
+            description: 'Drive a Cypress 15.21+ open-mode Chromium session in the configured project using JSON TAP. sessions discovers sessionId; run requests a spec and status guards stale startedAt verdicts and zero executed tests. reporter gives test IDs/Command Log, command gives snapshots, pin restores historical DOM, dom/aria/inspect read completed or pinned state. at is 1-based for pin, 0-based for element matches; attempt is 1-based. Run mode has no TAP; use inspect_cypress_browser for live paused state. Pins and run change the open session.',
+            inputSchema: cypressTapInput, outputSchema: toolOutputSchema,
+            execute: async (input, context) => report(`Cypress TAP ${input.action}`, await cypressRuntime(context).tapCommand(input)),
+        },
+        {
+            name: 'start_cypress_run',
+            description: 'Launch one project spec using its installed Cypress CLI on Windows or Linux. Returns runId immediately. mode run supports bounded repeats; mode open keeps the session alive after completion for TAP command logs and time travel (Cypress 15.21+). debug pauses before each test; resume through inspect_cypress_browser. repeats compares independent runs; retries records Cypress attempts. Uses existing project credentials, keeps diagnostics local, and does not publish runs.',
+            inputSchema: z.object({
+                spec: z.string().min(1), mode: z.enum(['run', 'open']).optional(), browser: z.enum(['chrome-for-testing', 'chrome', 'chromium', 'edge', 'yandex']).optional(),
+                repeats: z.number().int().min(1).max(20).optional(), retries: z.number().int().min(0).max(5).optional(),
+                timeoutSeconds: z.number().int().min(1).max(7200).optional(), debug: z.boolean().optional(),
+            }),
+            outputSchema: toolOutputSchema,
+            execute: async (input, context) => {
+                const run = await cypressRuntime(context).start(input);
+                return report(`Cypress run ${run.runId}: ${run.status}`, run, [run.mode === 'open' ? 'Poll get_cypress_run for tap.sessionId and requestId, then cypress_tap status for a fresh verdict. Stop the session when finished.' : 'Poll get_cypress_run; use inspect_cypress_browser for live debugging.']);
+            },
+        },
+        {
+            name: 'get_cypress_run',
+            description: 'Read managed run status, captured log, per-test errors/retry attempts, failure DOM evidence, artifact paths and observed flakiness. A completed process is not necessarily a passing test run; inspect results. No new run is started.',
+            inputSchema: z.object({ runId: z.string().uuid() }), outputSchema: toolOutputSchema,
+            execute: async ({ runId }, context) => {
+                const run = cypressRuntime(context).get(runId);
+                return report(`Cypress run ${runId}: ${run.status}; ${run.flakiness.completedRepeats} completed repeats, ${run.flakiness.failedRepeats} failed repeats`, run);
+            },
+        },
+        {
+            name: 'stop_cypress_run', description: 'Stop a managed Cypress run and its browser; keep diagnostic artifacts for analysis.',
+            inputSchema: z.object({ runId: z.string().uuid() }), outputSchema: toolOutputSchema,
+            execute: async ({ runId }, context) => report(`Stopped Cypress run ${runId}`, await cypressRuntime(context).stop(runId)),
+        },
+        {
+            name: 'inspect_cypress_browser',
+            description: 'Inspect the live browser of a managed run: snapshot DOM plus console/network, screenshot, evaluate JavaScript in AUT or runner, pause or resume. evaluate can change page state; use deliberately. The live DOM is current state; get_cypress_run contains captured failure state. For ambiguous frames pass contextId from diagnostics.',
+            inputSchema: z.object({
+                runId: z.string().uuid(), action: z.enum(['snapshot', 'evaluate', 'screenshot', 'pause', 'resume']),
+                target: z.enum(['aut', 'runner']).optional(), contextId: z.number().int().positive().optional(),
+                selector: z.string().max(2000).optional(), expression: z.string().max(20000).optional(),
+            }), outputSchema: toolOutputSchema,
+            execute: async ({ runId, ...input }, context) => {
+                const result = await cypressRuntime(context).inspect(runId, input);
+                if (input.action === 'screenshot')
+                    return {
+                        ...report(`Cypress browser screenshot for ${runId}`, { runId }),
+                        image: { type: 'image', data: result.data, mimeType: result.mimeType },
+                    };
+                return report(`Cypress browser ${input.action} for ${runId}`, result);
+            },
+        },
+    ];
+}

package/dist/src/mcp/registerTools.js

@@ -15,8 +15,10 @@ import { reviewTestDraft } from '../domain/reviewTestDraft.js';
 import { summarizeCiContext } from '../domain/summarizeCiContext.js';
 import { triageFailedRun } from '../domain/triageFailedRun.js';
 import { toolOutputSchema } from '../contracts/toolOutput.js';
+import { cypressTools } from './cypressTools.js';
 export function buildToolRegistry() {
     return [
+        ...cypressTools(),
         {
             name: 'find_existing_test_assets',
             description: 'Finds reusable specs, commands, helpers, and selectors in autotests2.',

package/dist/src/mcp/server.js

@@ -1,11 +1,17 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { ErrorCode, ListResourcesRequestSchema, ListResourceTemplatesRequestSchema, McpError, ReadResourceRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
 import { FramingAwareStdioServerTransport } from './framingAwareStdioTransport.js';
 import { buildToolRegistry } from './registerTools.js';
+import { closeCypressRuntime } from '../runtime/cypressRuntime.js';
 export async function createMcpServer(context) {
     const server = new McpServer({
         name: 'autotests-ultimate-testing-overkill',
-        version: '1.1.0',
+        version: '1.3.0',
+    }, {
+        instructions: 'For local Cypress work use start_cypress_run, then poll get_cypress_run. debug=true pauses before each test; inspect_cypress_browser action=resume continues. Use snapshot/evaluate/screenshot for browser evidence, and captured failures for pre-cleanup DOM. Use repeats/retries to measure observed flakiness. Use mode=open for completed Command Log and time travel through cypress_tap; poll its fresh verdict with sessionId/requestId and do not count no_tests as a pass. Reuse project assets before editing specs, then rerun the affected spec. Stop unused runs. A completed run may contain failed tests. Never expose credentials or weaken assertions just to make a test pass.',
     });
+    server.server.onclose = () => { void closeCypressRuntime(context); };
+    registerEmptyResourceHandlers(server);
     for (const tool of buildToolRegistry()) {
         server.registerTool(tool.name, {
             title: tool.name,
@@ -13,17 +19,45 @@ export async function createMcpServer(context) {
             inputSchema: tool.inputSchema,
             outputSchema: tool.outputSchema,
         }, async (args) => {
-            const structuredContent = await tool.execute(args, context);
+            const { image, ...structuredContent } = await tool.execute(args, context);
             return {
-                content: [{ type: 'text', text: structuredContent.summary }],
+                content: [{ type: 'text', text: structuredContent.summary }, ...(image ? [image] : [])],
                 structuredContent,
             };
         });
     }
     return server;
 }
+function registerEmptyResourceHandlers(server) {
+    server.server.registerCapabilities({
+        resources: {
+            listChanged: true,
+        },
+    });
+    server.server.setRequestHandler(ListResourcesRequestSchema, () => ({
+        resources: [],
+    }));
+    server.server.setRequestHandler(ListResourceTemplatesRequestSchema, () => ({
+        resourceTemplates: [],
+    }));
+    server.server.setRequestHandler(ReadResourceRequestSchema, (request) => {
+        throw new McpError(ErrorCode.InvalidParams, `Resource ${request.params.uri} not found`);
+    });
+}
 export async function runMcpServer(context) {
     const server = await createMcpServer(context);
     const transport = new FramingAwareStdioServerTransport();
     await server.connect(transport);
+    let closing = false;
+    const close = async () => {
+        if (closing)
+            return;
+        closing = true;
+        await closeCypressRuntime(context);
+        await server.close();
+        context.database.close();
+    };
+    process.stdin.once('end', () => { void close(); });
+    process.once('SIGTERM', () => { void close(); });
+    process.once('SIGINT', () => { void close(); });
 }

package/dist/src/runtime/cypressBrowser.d.ts

@@ -0,0 +1,32 @@
+export type BrowserInspection = {
+    action: 'snapshot' | 'evaluate' | 'screenshot' | 'pause' | 'resume';
+    expression?: string;
+    target?: 'aut' | 'runner';
+    contextId?: number;
+    selector?: string;
+};
+export declare function redactBrowserText(value: string): string;
+/** CDP access is limited to the Chrome instance owned by the managed Cypress run. */
+export declare class CypressBrowser {
+    private readonly port;
+    private readonly recordFailure?;
+    private socket?;
+    private connecting?;
+    private generation;
+    private nextId;
+    private pending;
+    private contexts;
+    private consoleEntries;
+    private networkEntries;
+    private paused;
+    private readonly sanitize;
+    constructor(port: number, sanitize?: (text: string) => string, recordFailure?: ((record: unknown) => void) | undefined);
+    connect(): Promise<void>;
+    private open;
+    private message;
+    private call;
+    private frameContexts;
+    inspect(input: BrowserInspection): Promise<any>;
+    private failPending;
+    close(): Promise<void>;
+}

package/dist/src/runtime/cypressBrowser.js

@@ -0,0 +1,280 @@
+function safeUrl(value) {
+    try {
+        const url = new URL(value);
+        return `${url.protocol}//${url.host}${url.pathname}`;
+    }
+    catch {
+        return '[unavailable URL]';
+    }
+}
+export function redactBrowserText(value) {
+    return value.replace(/\bBearer\s+[^\s"']+/gi, 'Bearer [REDACTED]')
+        .replace(/((?:password|passwd|secret|token|authorization|cookie|api[_-]?key)["']?\s*[:=]\s*["']?)[^\s"',;}]+/gi, '$1[REDACTED]')
+        .replace(/https?:\/\/[^\s<>"']+/gi, (url) => safeUrl(url));
+}
+/** CDP access is limited to the Chrome instance owned by the managed Cypress run. */
+export class CypressBrowser {
+    port;
+    recordFailure;
+    socket;
+    connecting;
+    generation = 0;
+    nextId = 0;
+    pending = new Map();
+    contexts = new Map();
+    consoleEntries = [];
+    networkEntries = [];
+    paused = false;
+    sanitize;
+    constructor(port, sanitize = (text) => text, recordFailure) {
+        this.port = port;
+        this.recordFailure = recordFailure;
+        if (!Number.isInteger(port) || port < 1 || port > 65535)
+            throw new Error('Invalid browser debugging port');
+        this.sanitize = (text) => redactBrowserText(sanitize(text));
+    }
+    async connect() {
+        if (this.socket?.readyState === 1)
+            return;
+        if (this.connecting)
+            return this.connecting;
+        this.connecting = this.open(this.generation);
+        try {
+            await this.connecting;
+        }
+        finally {
+            this.connecting = undefined;
+        }
+    }
+    async open(generation) {
+        if (typeof WebSocket === 'undefined')
+            throw new Error('Browser debugging requires Node.js 22.5+ with native WebSocket');
+        let targets;
+        try {
+            const response = await fetch(`http://127.0.0.1:${this.port}/json/list`, { signal: AbortSignal.timeout(3000), redirect: 'error' });
+            if (!response.ok)
+                throw new Error(`HTTP ${response.status}`);
+            targets = await response.json();
+        }
+        catch {
+            throw new Error('Cypress browser is not available yet. Poll the run, then retry browser inspection.');
+        }
+        if (generation !== this.generation)
+            throw new Error('Cypress browser inspection closed during connection');
+        const pages = targets.filter((target) => target.type === 'page' && target.webSocketDebuggerUrl);
+        const page = pages.find((target) => /\/__\/|\/__cypress\/|cypress\/runner/.test(target.url))
+            ?? (pages.length === 1 ? pages[0] : undefined);
+        if (!page?.webSocketDebuggerUrl)
+            throw new Error('No unique Cypress runner page is available on the managed browser port');
+        const endpoint = new URL(page.webSocketDebuggerUrl);
+        if (endpoint.protocol !== 'ws:' || !['127.0.0.1', 'localhost', '[::1]'].includes(endpoint.hostname)
+            || Number(endpoint.port) !== this.port || endpoint.username || endpoint.password) {
+            throw new Error('Browser debugger endpoint must remain on the managed loopback port');
+        }
+        const socket = new WebSocket(endpoint.href);
+        this.socket = socket;
+        socket.addEventListener('message', (event) => this.message(String(event.data)));
+        socket.addEventListener('close', () => {
+            this.contexts.clear();
+            this.failPending(new Error('Cypress browser connection closed; retry if the run launches another browser'));
+        });
+        try {
+            await new Promise((resolve, reject) => {
+                const timer = setTimeout(() => { socket.close(); reject(new Error('Browser connection timed out')); }, 5000);
+                socket.addEventListener('open', () => { clearTimeout(timer); resolve(); }, { once: true });
+                socket.addEventListener('error', () => { clearTimeout(timer); reject(new Error('Browser connection failed')); }, { once: true });
+                socket.addEventListener('close', () => { clearTimeout(timer); reject(new Error('Browser connection closed')); }, { once: true });
+            });
+            if (generation !== this.generation)
+                throw new Error('Cypress browser inspection closed during connection');
+            await Promise.all([
+                ...['Runtime.enable', 'Page.enable', 'Network.enable', 'Debugger.enable'].map((method) => this.call(method)),
+                this.call('Runtime.addBinding', { name: '__overkillRecord' }),
+            ]);
+        }
+        catch (error) {
+            await this.close();
+            throw error;
+        }
+    }
+    message(raw) {
+        let message;
+        try {
+            message = JSON.parse(raw);
+        }
+        catch {
+            return;
+        }
+        if (message.id) {
+            const pending = this.pending.get(message.id);
+            if (!pending)
+                return;
+            clearTimeout(pending.timer);
+            this.pending.delete(message.id);
+            if (message.error)
+                pending.reject(new Error(this.sanitize(message.error.message)));
+            else
+                pending.resolve(message.result);
+            return;
+        }
+        const params = message.params ?? {};
+        if (message.method === 'Runtime.bindingCalled' && params.name === '__overkillRecord'
+            && typeof params.payload === 'string' && Buffer.byteLength(params.payload, 'utf8') <= 250000) {
+            try {
+                const record = JSON.parse(params.payload);
+                if (record && record.type === 'failure')
+                    this.recordFailure?.(record);
+            }
+            catch {
+                // Malformed page telemetry or a failed evidence sink must not crash the MCP connection.
+            }
+        }
+        if (message.method === 'Runtime.executionContextCreated')
+            this.contexts.set(params.context.id, params.context);
+        if (message.method === 'Runtime.executionContextDestroyed')
+            this.contexts.delete(params.executionContextId);
+        if (message.method === 'Runtime.executionContextsCleared')
+            this.contexts.clear();
+        if (message.method === 'Debugger.paused')
+            this.paused = true;
+        if (message.method === 'Debugger.resumed')
+            this.paused = false;
+        if (message.method === 'Runtime.consoleAPICalled' || message.method === 'Runtime.exceptionThrown') {
+            const text = params.exceptionDetails?.exception?.description ?? params.exceptionDetails?.text
+                ?? (params.args ?? []).map((arg) => typeof arg.value === 'string' ? arg.value : arg.description ?? String(arg.value ?? arg.type)).join(' ');
+            this.consoleEntries.push({ type: params.type ?? 'exception', text: this.sanitize(text).slice(0, 2000), timestamp: new Date().toISOString() });
+            this.consoleEntries = this.consoleEntries.slice(-200);
+        }
+        if (message.method === 'Network.requestWillBeSent') {
+            this.networkEntries.push({ requestId: params.requestId, url: safeUrl(params.request.url), method: params.request.method });
+        }
+        if (message.method === 'Network.responseReceived') {
+            this.networkEntries.push({ requestId: params.requestId, url: safeUrl(params.response.url), status: params.response.status, type: params.type });
+        }
+        if (message.method === 'Network.loadingFailed') {
+            this.networkEntries.push({ requestId: params.requestId, error: this.sanitize(params.errorText ?? ''), canceled: params.canceled });
+        }
+        this.networkEntries = this.networkEntries.slice(-200);
+    }
+    call(method, params = {}, timeoutMs = 10000) {
+        if (this.socket?.readyState !== 1)
+            return Promise.reject(new Error('Cypress browser is disconnected'));
+        const id = ++this.nextId;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => { this.pending.delete(id); reject(new Error(`Browser command ${method} timed out`)); }, timeoutMs);
+            this.pending.set(id, { resolve, reject, timer });
+            try {
+                this.socket.send(JSON.stringify({ id, method, params }));
+            }
+            catch (error) {
+                clearTimeout(timer);
+                this.pending.delete(id);
+                reject(error);
+            }
+        });
+    }
+    async frameContexts() {
+        const frames = [];
+        const walk = (tree) => { frames.push(tree.frame); (tree.childFrames ?? []).forEach(walk); };
+        walk((await this.call('Page.getFrameTree')).frameTree);
+        return [...this.contexts.values()].filter((context) => context.auxData?.isDefault).map((context) => ({
+            contextId: context.id,
+            frame: frames.find((frame) => frame.id === context.auxData?.frameId),
+        }));
+    }
+    async inspect(input) {
+        await this.connect();
+        if (input.action === 'pause' || input.action === 'resume') {
+            if (input.action === 'pause') {
+                await this.call('Debugger.pause');
+                return { pauseRequested: true, paused: this.paused, note: 'Pauses at the next JavaScript execution. Cypress timeouts continue; resume promptly.' };
+            }
+            // Disabling also cancels a pause armed on an idle page; resume alone does not.
+            await this.call('Debugger.disable');
+            await this.call('Debugger.enable');
+            this.paused = false;
+            const contexts = await this.frameContexts();
+            const runner = contexts.find((item) => /your spec/i.test(item.frame?.name ?? ''))
+                ?? contexts.find((item) => item.frame && !item.frame.parentId);
+            if (runner)
+                await this.call('Runtime.evaluate', { expression: 'globalThis.__overkillResume?.()', contextId: runner.contextId, returnByValue: true, timeout: 5000 });
+            return { paused: false, resumed: true };
+        }
+        if (input.action === 'screenshot') {
+            const { data } = await this.call('Page.captureScreenshot', { format: 'png' });
+            return { data, mimeType: 'image/png' };
+        }
+        const contexts = await this.frameContexts();
+        const candidates = input.contextId !== undefined ? contexts.filter((item) => item.contextId === input.contextId)
+            : input.target === 'runner' ? contexts.filter((item) => item.frame && !item.frame.parentId)
+                : contexts.filter((item) => item.frame?.parentId && /^Your (?:App|project)(?::|$)/i.test(item.frame.name ?? ''));
+        const selected = candidates.length === 1 ? candidates[0] : undefined;
+        if (!selected)
+            throw new Error(`No unique ${input.target ?? 'aut'} execution context. Available contexts: ${JSON.stringify(contexts.map((item) => ({ contextId: item.contextId, name: item.frame?.name, url: safeUrl(item.frame?.url ?? '') })))}. Use contextId or target=runner.`);
+        if (input.action === 'evaluate' && !input.expression?.trim())
+            throw new Error('Browser evaluate requires an expression');
+        const expression = input.action === 'evaluate' ? input.expression : `(() => {
+      const root = document.querySelector(${JSON.stringify(input.selector ?? 'body')});
+      if (!root) return { url: location.origin + location.pathname, html: null, matched: false };
+      if (root.matches('script,style,noscript,input[type="hidden"],meta')) return { html: '[REDACTED]', matched: true };
+      const clone = root.cloneNode(true);
+      clone.querySelectorAll('script,style,noscript,input[type="hidden"],meta').forEach(node => node.remove());
+      for (const node of [clone, ...clone.querySelectorAll('*')]) {
+        for (const attr of [...node.attributes]) {
+          if (!['testguid','data-testid','id','class','role','aria-label','aria-expanded','aria-disabled','type','name','title','disabled','checked'].includes(attr.name)) node.removeAttribute(attr.name);
+        }
+        if (node.matches('input,textarea,[contenteditable], [autocomplete*="password"]')) { node.removeAttribute('value'); node.textContent = ''; }
+      }
+      return { url: location.origin + location.pathname, html: clone.outerHTML.slice(0, 40000), matched: true, truncated: clone.outerHTML.length > 40000,
+        debug: globalThis.__overkillDebug ?? null,
+        spec: globalThis.Cypress?.spec?.relative ?? null,
+        currentTest: globalThis.Cypress?.currentTest ?? null };
+    })()`;
+        const result = await this.call('Runtime.evaluate', { expression, contextId: selected.contextId, returnByValue: true, awaitPromise: input.action === 'evaluate' && !this.paused, timeout: 5000, disableBreaks: true });
+        if (result.exceptionDetails)
+            throw new Error(this.sanitize(result.exceptionDetails.exception?.description ?? result.exceptionDetails.text));
+        const value = result.result?.value ?? result.result?.description ?? null;
+        const clean = (entry) => typeof entry === 'string' ? this.sanitize(entry)
+            : Array.isArray(entry) ? entry.map(clean)
+                : entry && typeof entry === 'object' ? Object.fromEntries(Object.entries(entry).map(([key, item]) => [key, /password|passwd|secret|token|authorization|cookie|api[_-]?key/i.test(key) ? '[REDACTED]' : clean(item)])) : entry;
+        const cleaned = clean(value);
+        const serialized = JSON.stringify(cleaned);
+        const dom = serialized.length <= 50000 ? cleaned : { truncated: true, text: serialized.slice(0, 50000) };
+        let runnerState;
+        if (input.action === 'snapshot') {
+            const spec = contexts.find((item) => /your spec/i.test(item.frame?.name ?? ''))
+                ?? contexts.find((item) => item.frame && !item.frame.parentId);
+            if (spec) {
+                const state = await this.call('Runtime.evaluate', {
+                    expression: '({debug: globalThis.__overkillDebug ?? null, spec: globalThis.Cypress?.spec?.relative ?? null, currentTest: globalThis.Cypress?.currentTest ?? null})',
+                    contextId: spec.contextId, returnByValue: true, awaitPromise: false, timeout: 5000, disableBreaks: true,
+                });
+                const value = clean(state.result?.value ?? null);
+                const json = JSON.stringify(value);
+                runnerState = json.length <= 50000 ? value : { truncated: true, text: json.slice(0, 50000) };
+            }
+        }
+        return input.action === 'evaluate' ? { value: dom, contextId: selected.contextId } : {
+            dom, runnerState, contextId: selected.contextId, paused: this.paused,
+            contexts: contexts.map((item) => ({ contextId: item.contextId, name: item.frame?.name, url: safeUrl(item.frame?.url ?? '') })),
+            console: this.consoleEntries, network: this.networkEntries,
+        };
+    }
+    failPending(error) {
+        for (const pending of this.pending.values()) {
+            clearTimeout(pending.timer);
+            pending.reject(error);
+        }
+        this.pending.clear();
+    }
+    async close() {
+        this.generation++;
+        // Detaching must not leave the user's Cypress browser paused.
+        if (this.socket?.readyState === 1)
+            await this.call('Debugger.disable', {}, 1000).catch(() => { });
+        this.socket?.close();
+        this.socket = undefined;
+        this.contexts.clear();
+        this.failPending(new Error('Cypress browser inspection closed'));
+    }
+}

package/dist/src/runtime/cypressProcess.d.ts

@@ -0,0 +1,8 @@
+import { type ChildProcess } from 'node:child_process';
+export declare function cypressInstallation(repoRoot: string, requireTap?: boolean): {
+    cli: string;
+    version: string;
+};
+export declare function cypressEnvironment(env?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+export declare function cypressTapArguments(cli: string, args: string[], platform?: NodeJS.Platform): string[];
+export declare function stopProcessTree(child?: ChildProcess, platform?: NodeJS.Platform): Promise<void>;

package/dist/src/runtime/cypressProcess.js

@@ -0,0 +1,83 @@
+import { execFile } from 'node:child_process';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import path from 'node:path';
+export function cypressInstallation(repoRoot, requireTap = false) {
+    const require = createRequire(path.join(repoRoot, 'package.json'));
+    let manifest;
+    try {
+        manifest = require.resolve('cypress/package.json');
+    }
+    catch {
+        throw new Error('Install Cypress in the configured test project before using the runtime.');
+    }
+    const { version, bin } = JSON.parse(fs.readFileSync(manifest, 'utf8'));
+    const match = /^(\d+)\.(\d+)\.(\d+)(?:\+.*)?$/.exec(version);
+    if (requireTap && (!match || Number(match[1]) < 15 || (Number(match[1]) === 15 && Number(match[2]) < 21))) {
+        throw new Error(`Cypress TAP requires Cypress 15.21.0+ (installed: ${version}); use managed run mode with older versions.`);
+    }
+    const cli = path.resolve(path.dirname(manifest), typeof bin === 'string' ? bin : bin.cypress);
+    return { cli, version: String(version) };
+}
+export function cypressEnvironment(env = process.env) {
+    // Keep local diagnostics free of guest telemetry; TAP's local requests also require graceful exit below.
+    return {
+        ...Object.fromEntries(Object.entries(env).filter(([key]) => !['ELECTRON_RUN_AS_NODE', 'CYPRESS_DISABLE_GUEST_TELEMETRY'].includes(key.toUpperCase()))),
+        CYPRESS_DISABLE_GUEST_TELEMETRY: '1',
+    };
+}
+export function cypressTapArguments(cli, args, platform = process.platform) {
+    const command = [cli, 'tap', ...args];
+    // TAP exits after its async dispatch. Let pending fetch/CDP work drain on Windows (nodejs/node#56645).
+    // Only this short-lived TAP child is changed; exit codes and the caller's timeout still apply.
+    return platform === 'win32'
+        ? ['--input-type=commonjs', '--eval', 'process.exit = (code) => { if (code !== undefined) process.exitCode = code; }; require(process.argv[1]);', ...command]
+        : command;
+}
+export async function stopProcessTree(child, platform = process.platform) {
+    if (!child?.pid)
+        return;
+    const pid = child.pid;
+    if (platform === 'win32') {
+        if (child.exitCode !== null || child.signalCode !== null)
+            return;
+        await new Promise((resolve, reject) => {
+            execFile('taskkill.exe', ['/pid', String(pid), '/T', '/F'], { windowsHide: true }, (error) => {
+                if (error) {
+                    try {
+                        process.kill(pid, 0);
+                    }
+                    catch (gone) {
+                        if (gone.code === 'ESRCH') {
+                            resolve();
+                            return;
+                        }
+                    }
+                    reject(error);
+                }
+                else
+                    resolve();
+            });
+        });
+        return;
+    }
+    const signal = (value) => {
+        try {
+            process.kill(-pid, value);
+            return true;
+        }
+        catch (error) {
+            if (error.code === 'ESRCH')
+                return false;
+            throw error;
+        }
+    };
+    // A detached POSIX child's group can outlive its leader. Always signal the group.
+    if (!signal('SIGTERM'))
+        return;
+    const deadline = Date.now() + 4000;
+    while (signal(0) && Date.now() < deadline)
+        await new Promise((resolve) => setTimeout(resolve, 100));
+    if (signal(0))
+        signal('SIGKILL');
+}

package/dist/src/runtime/cypressRuns.d.ts

@@ -0,0 +1,36 @@
+export type CypressRunOptions = {
+    spec: string;
+    mode?: 'run' | 'open';
+    browser?: string;
+    repeats?: number;
+    retries?: number;
+    timeoutSeconds?: number;
+    debug?: boolean;
+};
+export declare class CypressRuns {
+    private readonly cacheDir;
+    private readonly sanitize;
+    private readonly runs;
+    private readonly root;
+    private readonly lock;
+    private ownsLock;
+    private starting;
+    private closed;
+    constructor(repoRoot: string, cacheDir: string, sanitize?: (text: string) => string);
+    active(): {
+        runId: string;
+        mode: "run" | "open";
+    } | undefined;
+    start(input: CypressRunOptions): Promise<any>;
+    get(runId: string): any;
+    recordCapture(runId: string, payload: unknown): boolean;
+    getDebugPort(runId: string): number;
+    stop(runId: string): Promise<any>;
+    close(): Promise<void>;
+    private terminate;
+    private requireRun;
+    private acquireLock;
+    private releaseLock;
+    private save;
+    private execute;
+}