@agentrhq/webcmd 0.1.1 → 0.2.0

package/dist/src/browser/verify-fixture.test.js

@@ -0,0 +1,219 @@
+import { describe, expect, it } from 'vitest';
+import { deriveFixture, expandFixtureArgs, parseSeedArgs, validateRows, validateRowShape } from './verify-fixture.js';
+describe('validateRows', () => {
+    it('passes when rows meet all expectations', () => {
+        const fixture = {
+            expect: {
+                rowCount: { min: 1, max: 3 },
+                columns: ['id', 'title', 'url'],
+                types: { id: 'number', title: 'string', url: 'string' },
+                patterns: { url: '^https://' },
+                notEmpty: ['title', 'url'],
+            },
+        };
+        const rows = [
+            { id: 1, title: 'a', url: 'https://x.com/a' },
+            { id: 2, title: 'b', url: 'https://x.com/b' },
+        ];
+        expect(validateRows(rows, fixture)).toEqual([]);
+    });
+    it('reports rowCount below min', () => {
+        const failures = validateRows([], { expect: { rowCount: { min: 1 } } });
+        expect(failures).toHaveLength(1);
+        expect(failures[0]).toMatchObject({ rule: 'rowCount' });
+        expect(failures[0].detail).toContain('at least 1');
+    });
+    it('reports rowCount above max', () => {
+        const failures = validateRows([{}, {}, {}, {}], { expect: { rowCount: { max: 3 } } });
+        expect(failures).toHaveLength(1);
+        expect(failures[0].detail).toContain('at most 3');
+    });
+    it('reports missing columns per row', () => {
+        const failures = validateRows([{ a: 1 }, { a: 2, b: 3 }], { expect: { columns: ['a', 'b'] } });
+        // row 0 missing 'b', row 1 complete
+        expect(failures).toEqual([
+            { rule: 'column', detail: 'missing column "b"', rowIndex: 0 },
+        ]);
+    });
+    it('reports type mismatch including null', () => {
+        const failures = validateRows([{ a: 'abc' }, { a: null }, { a: 42 }], { expect: { types: { a: 'string' } } });
+        // row 0 string ok, row 1 null fail, row 2 number fail
+        expect(failures).toHaveLength(2);
+        expect(failures[0].rowIndex).toBe(1);
+        expect(failures[0].detail).toContain('null');
+        expect(failures[1].rowIndex).toBe(2);
+        expect(failures[1].detail).toContain('number');
+    });
+    it('accepts union types like "number|string"', () => {
+        const failures = validateRows([{ id: 1 }, { id: 'abc' }], { expect: { types: { id: 'number|string' } } });
+        expect(failures).toEqual([]);
+    });
+    it('accepts "any" as wildcard type', () => {
+        const failures = validateRows([{ v: 1 }, { v: 'x' }, { v: null }, { v: [1, 2] }], { expect: { types: { v: 'any' } } });
+        expect(failures).toEqual([]);
+    });
+    it('reports pattern mismatch with row index and truncated value', () => {
+        const failures = validateRows([{ url: 'https://ok.com' }, { url: 'not-a-url' }], { expect: { patterns: { url: '^https?://' } } });
+        expect(failures).toHaveLength(1);
+        expect(failures[0]).toMatchObject({ rule: 'pattern', rowIndex: 1 });
+        expect(failures[0].detail).toContain('not-a-url');
+    });
+    it('skips pattern check for null/undefined values', () => {
+        const failures = validateRows([{ url: null }, { url: undefined }], { expect: { patterns: { url: '^x' } } });
+        expect(failures).toEqual([]);
+    });
+    it('reports invalid regex without crashing', () => {
+        const failures = validateRows([{ a: 'x' }], { expect: { patterns: { a: '[unclosed' } } });
+        expect(failures.some((f) => f.rule === 'pattern' && f.detail.includes('invalid'))).toBe(true);
+    });
+    it('treats empty/whitespace/null as failing notEmpty', () => {
+        const failures = validateRows([{ t: '' }, { t: '   ' }, { t: null }, { t: 'ok' }], { expect: { notEmpty: ['t'] } });
+        expect(failures).toHaveLength(3);
+        expect(failures.map((f) => f.rowIndex)).toEqual([0, 1, 2]);
+    });
+    it('no failures when fixture has no expect block', () => {
+        expect(validateRows([{ anything: 1 }], {})).toEqual([]);
+    });
+    it('mustNotContain flags substring bleed in columns', () => {
+        const failures = validateRows([
+            { description: 'Lead engineer, 5 years exp. address: Shanghai. category: IT' },
+            { description: 'Clean text.' },
+        ], {
+            expect: {
+                mustNotContain: { description: ['address:', 'category:'] },
+            },
+        });
+        expect(failures).toHaveLength(2);
+        expect(failures.every((f) => f.rule === 'mustNotContain')).toBe(true);
+        expect(failures.every((f) => f.rowIndex === 0)).toBe(true);
+    });
+    it('mustNotContain skips null/undefined values', () => {
+        const failures = validateRows([{ description: null }, { description: undefined }], { expect: { mustNotContain: { description: ['x'] } } });
+        expect(failures).toEqual([]);
+    });
+    it('mustBeTruthy catches silent 0 / false / "" fallbacks', () => {
+        const failures = validateRows([{ count: 10 }, { count: 0 }, { count: false }, { count: '' }, { count: null }], { expect: { mustBeTruthy: ['count'] } });
+        expect(failures).toHaveLength(4);
+        expect(failures.every((f) => f.rule === 'mustBeTruthy')).toBe(true);
+        expect(failures.map((f) => f.rowIndex)).toEqual([1, 2, 3, 4]);
+    });
+});
+describe('validateRowShape', () => {
+    it('passes flat rows with a compact key set', () => {
+        const failures = validateRowShape([
+            { id: '1', title: 'A', author: { name: 'Ada' }, tags: ['ai', 'web'] },
+        ]);
+        expect(failures).toEqual([]);
+    });
+    it('reports rows with too many top-level keys', () => {
+        const row = Object.fromEntries(Array.from({ length: 13 }, (_, i) => [`k${i}`, i]));
+        const failures = validateRowShape([row]);
+        expect(failures).toEqual([
+            {
+                rule: 'shapeKeyCount',
+                detail: 'row has 13 top-level keys, expected at most 12',
+                rowIndex: 0,
+            },
+        ]);
+    });
+    it('reports nesting deeper than one level', () => {
+        const failures = validateRowShape([
+            { title: 'A', stats: { author: { name: 'Ada' } } },
+        ]);
+        expect(failures).toEqual([
+            {
+                rule: 'shapeDepth',
+                detail: '"stats" nesting depth is 2, expected at most 1',
+                rowIndex: 0,
+            },
+        ]);
+    });
+    it('reports nested id-shaped fields even when one-level nesting is otherwise allowed', () => {
+        const failures = validateRowShape([
+            { title: 'A', author: { user_id: 'u1', name: 'Ada' } },
+        ]);
+        expect(failures).toEqual([
+            {
+                rule: 'shapeNestedId',
+                detail: 'id-shaped field "author.user_id" must be a top-level row key',
+                rowIndex: 0,
+            },
+        ]);
+    });
+});
+describe('deriveFixture', () => {
+    it('returns rowCount.min=0 when rows are empty', () => {
+        expect(deriveFixture([])).toEqual({ expect: { rowCount: { min: 0 } } });
+    });
+    it('extracts columns from first row and infers types per column', () => {
+        const fixture = deriveFixture([
+            { id: 1, title: 'a', url: 'https://x' },
+            { id: 2, title: 'b', url: 'https://y' },
+        ]);
+        expect(fixture.expect?.columns).toEqual(['id', 'title', 'url']);
+        expect(fixture.expect?.types).toEqual({
+            id: 'number',
+            title: 'string',
+            url: 'string',
+        });
+        expect(fixture.expect?.rowCount).toEqual({ min: 1 });
+    });
+    it('unions mixed types across rows as "a|b"', () => {
+        const fixture = deriveFixture([
+            { v: 1 },
+            { v: 'two' },
+            { v: null },
+        ]);
+        expect(fixture.expect?.types?.v).toBe('null|number|string');
+    });
+    it('embeds args when provided', () => {
+        const fixture = deriveFixture([{ x: 1 }], { limit: 5 });
+        expect(fixture.args).toEqual({ limit: 5 });
+    });
+    it('embeds positional argv array when provided', () => {
+        const fixture = deriveFixture([{ x: 1 }], ['123', '--limit', '3']);
+        expect(fixture.args).toEqual(['123', '--limit', '3']);
+    });
+    it('does not add patterns or notEmpty automatically', () => {
+        const fixture = deriveFixture([{ a: 'x' }]);
+        expect(fixture.expect?.patterns).toBeUndefined();
+        expect(fixture.expect?.notEmpty).toBeUndefined();
+    });
+});
+describe('expandFixtureArgs', () => {
+    it('returns [] for undefined', () => {
+        expect(expandFixtureArgs(undefined)).toEqual([]);
+    });
+    it('expands object form as --key value pairs', () => {
+        expect(expandFixtureArgs({ limit: 3, sort: 'hot' })).toEqual(['--limit', '3', '--sort', 'hot']);
+    });
+    it('passes array form verbatim, stringifying values', () => {
+        expect(expandFixtureArgs(['123456', '--limit', 3])).toEqual(['123456', '--limit', '3']);
+    });
+    it('handles empty object and empty array', () => {
+        expect(expandFixtureArgs({})).toEqual([]);
+        expect(expandFixtureArgs([])).toEqual([]);
+    });
+    it('preserves positional + flag mix (e.g. <tid> --limit 3)', () => {
+        expect(expandFixtureArgs(['https://example.com/thread-1', '--comments', '5'])).toEqual([
+            'https://example.com/thread-1',
+            '--comments',
+            '5',
+        ]);
+    });
+});
+describe('parseSeedArgs', () => {
+    it('treats plain text as one positional arg', () => {
+        expect(parseSeedArgs('webcmd-verify')).toEqual(['webcmd-verify']);
+    });
+    it('accepts JSON array seed args', () => {
+        expect(parseSeedArgs('["subject", "--limit", 3]')).toEqual(['subject', '--limit', 3]);
+    });
+    it('accepts JSON object seed args', () => {
+        expect(parseSeedArgs('{"limit":3,"sort":"hot"}')).toEqual({ limit: 3, sort: 'hot' });
+    });
+    it('ignores empty input', () => {
+        expect(parseSeedArgs(undefined)).toBeUndefined();
+        expect(parseSeedArgs('   ')).toBeUndefined();
+    });
+});

package/dist/src/browser/visual-refs.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Visual ref overlay for annotated screenshots.
+ *
+ * The overlay is intentionally DOM-side and temporary. It reuses the same
+ * `data-webcmd-ref` attributes produced by the DOM snapshot path so the
+ * screenshot labels map back to normal `browser click <ref>` targets.
+ */
+export declare function installVisualRefOverlayJs(opts?: {
+    maxRefs?: number;
+}): string;
+export declare function removeVisualRefOverlayJs(): string;

package/dist/src/browser/visual-refs.js

@@ -0,0 +1,108 @@
+/**
+ * Visual ref overlay for annotated screenshots.
+ *
+ * The overlay is intentionally DOM-side and temporary. It reuses the same
+ * `data-webcmd-ref` attributes produced by the DOM snapshot path so the
+ * screenshot labels map back to normal `browser click <ref>` targets.
+ */
+const OVERLAY_ID = '__webcmd_visual_ref_overlay';
+export function installVisualRefOverlayJs(opts = {}) {
+    const maxRefs = Math.max(1, Math.min(opts.maxRefs ?? 120, 500));
+    return `
+    (() => {
+      const OVERLAY_ID = ${JSON.stringify(OVERLAY_ID)};
+      const MAX_REFS = ${maxRefs};
+      document.getElementById(OVERLAY_ID)?.remove();
+
+      const overlay = document.createElement('div');
+      overlay.id = OVERLAY_ID;
+      overlay.setAttribute('aria-hidden', 'true');
+      Object.assign(overlay.style, {
+        position: 'fixed',
+        inset: '0',
+        zIndex: '2147483647',
+        pointerEvents: 'none',
+        fontFamily: 'ui-monospace, SFMono-Regular, Menlo, Consolas, monospace',
+      });
+
+      const refs = Array.from(document.querySelectorAll('[data-webcmd-ref]'))
+        .map((el) => {
+          const rawRef = el.getAttribute('data-webcmd-ref') || '';
+          const ref = Number(rawRef);
+          const rect = el.getBoundingClientRect();
+          const visible = Number.isFinite(ref)
+            && rect.width >= 2
+            && rect.height >= 2
+            && rect.bottom >= 0
+            && rect.right >= 0
+            && rect.top <= window.innerHeight
+            && rect.left <= window.innerWidth;
+          return { el, rawRef, ref, rect, visible };
+        })
+        .filter((entry) => entry.visible)
+        .sort((a, b) => a.ref - b.ref)
+        .slice(0, MAX_REFS);
+
+      for (const entry of refs) {
+        const left = Math.max(0, Math.min(window.innerWidth - 1, entry.rect.left));
+        const top = Math.max(0, Math.min(window.innerHeight - 1, entry.rect.top));
+        const right = Math.max(0, Math.min(window.innerWidth, entry.rect.right));
+        const bottom = Math.max(0, Math.min(window.innerHeight, entry.rect.bottom));
+        const width = Math.max(2, right - left);
+        const height = Math.max(2, bottom - top);
+
+        const box = document.createElement('div');
+        Object.assign(box.style, {
+          position: 'fixed',
+          left: left + 'px',
+          top: top + 'px',
+          width: width + 'px',
+          height: height + 'px',
+          border: '2px solid #ff3b30',
+          borderRadius: '4px',
+          boxSizing: 'border-box',
+          boxShadow: '0 0 0 1px rgba(255,255,255,.9), 0 4px 16px rgba(0,0,0,.25)',
+          background: 'rgba(255,59,48,.08)',
+        });
+
+        const badge = document.createElement('div');
+        badge.textContent = entry.rawRef;
+        Object.assign(badge.style, {
+          position: 'fixed',
+          left: left + 'px',
+          top: Math.max(0, top - 20) + 'px',
+          minWidth: '18px',
+          height: '18px',
+          padding: '0 5px',
+          borderRadius: '999px',
+          border: '1px solid rgba(255,255,255,.95)',
+          background: '#ff3b30',
+          color: '#fff',
+          fontSize: '12px',
+          fontWeight: '700',
+          lineHeight: '18px',
+          textAlign: 'center',
+          textShadow: '0 1px 1px rgba(0,0,0,.25)',
+          boxShadow: '0 2px 8px rgba(0,0,0,.35)',
+        });
+
+        overlay.appendChild(box);
+        overlay.appendChild(badge);
+      }
+
+      document.documentElement.appendChild(overlay);
+      return {
+        annotated: refs.length,
+        truncated: refs.length >= MAX_REFS,
+      };
+    })()
+  `.trim();
+}
+export function removeVisualRefOverlayJs() {
+    return `
+    (() => {
+      document.getElementById(${JSON.stringify(OVERLAY_ID)})?.remove();
+      return true;
+    })()
+  `.trim();
+}

package/dist/src/browser.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/browser.test.js

@@ -0,0 +1,297 @@
+import { afterEach, describe, it, expect, vi } from 'vitest';
+import { BrowserBridge, generateStealthJs } from './browser/index.js';
+import { extractTabEntries, diffTabIndexes, appendLimited } from './browser/tabs.js';
+import { withTimeoutMs } from './runtime.js';
+import { __test__ as cdpTest } from './browser/cdp.js';
+import { classifyBrowserError } from './browser/errors.js';
+import * as daemonTransport from './browser/daemon-transport.js';
+import * as daemonLifecycle from './browser/daemon-lifecycle.js';
+afterEach(() => {
+    vi.restoreAllMocks();
+});
+describe('browser helpers', () => {
+    it('extracts tab entries from string snapshots', () => {
+        const entries = extractTabEntries('Tab 0 https://example.com\nTab 1 Chrome Extension');
+        expect(entries).toEqual([
+            { index: 0, identity: 'https://example.com' },
+            { index: 1, identity: 'Chrome Extension' },
+        ]);
+    });
+    it('extracts tab entries from MCP markdown format', () => {
+        const entries = extractTabEntries('- 0: (current) [Playwright MCP extension](chrome-extension://abc/connect.html)\n- 1: [Example - Home](https://example.com/)');
+        expect(entries).toEqual([
+            { index: 0, identity: '(current) [Playwright MCP extension](chrome-extension://abc/connect.html)' },
+            { index: 1, identity: '[Example - Home](https://example.com/)' },
+        ]);
+    });
+    it('closes only tabs that were opened during the session', () => {
+        const tabsToClose = diffTabIndexes(['https://example.com', 'Chrome Extension'], [
+            { index: 0, identity: 'https://example.com' },
+            { index: 1, identity: 'Chrome Extension' },
+            { index: 2, identity: 'https://target.example/page' },
+            { index: 3, identity: 'chrome-extension://bridge' },
+        ]);
+        expect(tabsToClose).toEqual([3, 2]);
+    });
+    it('keeps only the tail of stderr buffers', () => {
+        expect(appendLimited('12345', '67890', 8)).toBe('34567890');
+    });
+    it('times out slow promises', async () => {
+        await expect(withTimeoutMs(new Promise(() => { }), 10, 'timeout')).rejects.toThrow('timeout');
+    });
+    it('classifies browser errors with correct kind and retry advice', () => {
+        // CDP target navigation — page-level settle retry
+        const nav = classifyBrowserError(new Error('{"code":-32000,"message":"Inspected target navigated or closed"}'));
+        expect(nav.kind).toBe('target-navigation');
+        expect(nav.delayMs).toBe(200);
+        // Extension transient — daemon-client retry only, NOT page-level
+        const ext = classifyBrowserError(new Error('Extension disconnected'));
+        expect(ext.kind).toBe('extension-transient');
+        expect(ext.delayMs).toBe(1500);
+        // Non-transient errors — not retryable
+        expect(classifyBrowserError(new Error('malformed exec payload')).kind).toBe('non-retryable');
+        expect(classifyBrowserError(new Error('Permission denied')).kind).toBe('non-retryable');
+    });
+    it('prefers the real Electron app target over DevTools and blank pages', () => {
+        const target = cdpTest.selectCDPTarget([
+            {
+                type: 'page',
+                title: 'DevTools - localhost:9224',
+                url: 'devtools://devtools/bundled/inspector.html',
+                webSocketDebuggerUrl: 'ws://127.0.0.1:9224/devtools',
+            },
+            {
+                type: 'page',
+                title: '',
+                url: 'about:blank',
+                webSocketDebuggerUrl: 'ws://127.0.0.1:9224/blank',
+            },
+            {
+                type: 'app',
+                title: 'Antigravity',
+                url: 'http://localhost:3000/',
+                webSocketDebuggerUrl: 'ws://127.0.0.1:9224/app',
+            },
+        ]);
+        expect(target?.webSocketDebuggerUrl).toBe('ws://127.0.0.1:9224/app');
+    });
+    it('honors WEBCMD_CDP_TARGET when multiple inspectable targets exist', () => {
+        vi.stubEnv('WEBCMD_CDP_TARGET', 'codex');
+        const target = cdpTest.selectCDPTarget([
+            {
+                type: 'app',
+                title: 'Cursor',
+                url: 'http://localhost:3000/cursor',
+                webSocketDebuggerUrl: 'ws://127.0.0.1:9226/cursor',
+            },
+            {
+                type: 'app',
+                title: 'OpenAI Codex',
+                url: 'http://localhost:3000/codex',
+                webSocketDebuggerUrl: 'ws://127.0.0.1:9226/codex',
+            },
+        ]);
+        expect(target?.webSocketDebuggerUrl).toBe('ws://127.0.0.1:9226/codex');
+    });
+});
+describe('BrowserBridge state', () => {
+    it('transitions to closed after close()', async () => {
+        const bridge = new BrowserBridge();
+        expect(bridge.state).toBe('idle');
+        await bridge.close();
+        expect(bridge.state).toBe('closed');
+    });
+    it('rejects connect() after the session has been closed', async () => {
+        const bridge = new BrowserBridge();
+        await bridge.close();
+        await expect(bridge.connect()).rejects.toThrow('Session is closed');
+    });
+    it('rejects connect() while already connecting', async () => {
+        const bridge = new BrowserBridge();
+        bridge._state = 'connecting';
+        await expect(bridge.connect()).rejects.toThrow('Already connecting');
+    });
+    it('rejects connect() while closing', async () => {
+        const bridge = new BrowserBridge();
+        bridge._state = 'closing';
+        await expect(bridge.connect()).rejects.toThrow('Session is closing');
+    });
+    it('fails fast when daemon is running but runtime is disconnected (same version)', async () => {
+        const { PKG_VERSION } = await import('./version.js');
+        vi.spyOn(daemonTransport, 'getDaemonHealth').mockResolvedValue({
+            state: 'no-runtime',
+            status: {
+                ok: true,
+                pid: 999999,
+                uptime: 0,
+                daemonVersion: PKG_VERSION,
+                runtimeConnected: false,
+                runtimeName: 'fake',
+                pending: 0,
+                memoryMB: 0,
+                port: 0,
+            },
+        });
+        const bridge = new BrowserBridge();
+        await expect(bridge.connect({ timeout: 0.1 })).rejects.toThrow('Browser runtime is not ready');
+    });
+    it('attempts stale daemon replacement when daemonVersion is missing', async () => {
+        vi.spyOn(daemonTransport, 'getDaemonHealth').mockResolvedValue({
+            state: 'no-runtime',
+            status: {
+                ok: true,
+                pid: 999999,
+                uptime: 0,
+                runtimeConnected: false,
+                runtimeName: 'fake',
+                pending: 0,
+                memoryMB: 0,
+                port: 0,
+            },
+        });
+        vi.spyOn(daemonLifecycle.daemonLifecycleHooks, 'requestDaemonShutdown').mockResolvedValue(false);
+        // Keep the SIGKILL fallback's poll short — neither pid 999999 nor the test
+        // daemon exists, so we'd otherwise spin for 2s on every test in the block.
+        vi.spyOn(daemonLifecycle.daemonLifecycleHooks, 'waitForDaemonStop').mockResolvedValue(false);
+        const bridge = new BrowserBridge();
+        await expect(bridge.connect({ timeout: 0.1 })).rejects.toThrow('Stale daemon could not be replaced');
+    });
+    it('attempts stale daemon replacement when daemonVersion mismatches', async () => {
+        vi.spyOn(daemonTransport, 'getDaemonHealth').mockResolvedValue({
+            state: 'no-runtime',
+            status: {
+                ok: true,
+                pid: 999999,
+                uptime: 0,
+                daemonVersion: '0.0.1',
+                runtimeConnected: false,
+                runtimeName: 'fake',
+                pending: 0,
+                memoryMB: 0,
+                port: 0,
+            },
+        });
+        vi.spyOn(daemonLifecycle.daemonLifecycleHooks, 'requestDaemonShutdown').mockResolvedValue(false);
+        vi.spyOn(daemonLifecycle.daemonLifecycleHooks, 'waitForDaemonStop').mockResolvedValue(false);
+        const bridge = new BrowserBridge();
+        await expect(bridge.connect({ timeout: 0.1 })).rejects.toThrow('Stale daemon could not be replaced');
+    });
+    it('attempts stale daemon replacement even when runtime is connected', async () => {
+        vi.spyOn(daemonTransport, 'getDaemonHealth').mockResolvedValue({
+            state: 'ready',
+            status: {
+                ok: true,
+                pid: 999999,
+                uptime: 0,
+                daemonVersion: '0.0.1',
+                runtimeConnected: true,
+                runtimeName: 'fake',
+                pending: 0,
+                memoryMB: 0,
+                port: 0,
+            },
+        });
+        vi.spyOn(daemonLifecycle.daemonLifecycleHooks, 'requestDaemonShutdown').mockResolvedValue(false);
+        vi.spyOn(daemonLifecycle.daemonLifecycleHooks, 'waitForDaemonStop').mockResolvedValue(false);
+        const bridge = new BrowserBridge();
+        await expect(bridge.connect({ timeout: 0.1 })).rejects.toThrow('Stale daemon could not be replaced');
+    });
+    it('falls back to SIGKILL when stale daemon refuses graceful shutdown', async () => {
+        vi.spyOn(daemonTransport, 'getDaemonHealth').mockResolvedValue({
+            state: 'no-runtime',
+            status: {
+                ok: true,
+                pid: 99999,
+                uptime: 0,
+                daemonVersion: '0.0.1',
+                runtimeConnected: false,
+                runtimeName: 'fake',
+                pending: 0,
+                memoryMB: 0,
+                port: 0,
+            },
+        });
+        vi.spyOn(daemonLifecycle.daemonLifecycleHooks, 'requestDaemonShutdown').mockResolvedValue(false);
+        // Graceful shutdown short-circuits to false (requestDaemonShutdown -> false).
+        // After SIGKILL the port is released, so the second waitForDaemonStop returns true.
+        vi.spyOn(daemonLifecycle.daemonLifecycleHooks, 'waitForDaemonStop').mockResolvedValue(true);
+        vi.spyOn(daemonLifecycle.daemonLifecycleHooks, 'spawnDaemonProcess').mockReturnValue(null);
+        const killSpy = vi.spyOn(process, 'kill').mockImplementation(() => true);
+        const bridge = new BrowserBridge();
+        // We expect the stale-daemon path to succeed and then continue into the
+        // no-runtime wait (which times out with `timeout: 0.1`), producing the
+        // runtime-not-ready error rather than the stale-daemon error.
+        await expect(bridge.connect({ timeout: 0.1 })).rejects.toThrow('Browser runtime is not ready');
+        expect(killSpy).toHaveBeenCalledWith(99999, 'SIGKILL');
+    });
+    it('reports stale daemon error when SIGKILL fails to release the port', async () => {
+        vi.spyOn(daemonTransport, 'getDaemonHealth').mockResolvedValue({
+            state: 'no-runtime',
+            status: {
+                ok: true,
+                pid: 99999,
+                uptime: 0,
+                daemonVersion: '0.0.1',
+                runtimeConnected: false,
+                runtimeName: 'fake',
+                pending: 0,
+                memoryMB: 0,
+                port: 0,
+            },
+        });
+        vi.spyOn(daemonLifecycle.daemonLifecycleHooks, 'requestDaemonShutdown').mockResolvedValue(false);
+        // Graceful + SIGKILL both fail to release the port.
+        vi.spyOn(daemonLifecycle.daemonLifecycleHooks, 'waitForDaemonStop').mockResolvedValue(false);
+        vi.spyOn(process, 'kill').mockImplementation(() => {
+            throw Object.assign(new Error('EPERM'), { code: 'EPERM' });
+        });
+        const bridge = new BrowserBridge();
+        await expect(bridge.connect({ timeout: 0.1 })).rejects.toThrow('Stale daemon could not be replaced');
+    });
+});
+describe('stealth anti-detection', () => {
+    it('generates non-empty JS string', () => {
+        const js = generateStealthJs();
+        expect(typeof js).toBe('string');
+        expect(js.length).toBeGreaterThan(100);
+    });
+    it('contains all 7 anti-detection patches', () => {
+        const js = generateStealthJs();
+        // 1. webdriver
+        expect(js).toContain('navigator');
+        expect(js).toContain('webdriver');
+        // 2. chrome stub
+        expect(js).toContain('window.chrome');
+        // 3. plugins
+        expect(js).toContain('plugins');
+        expect(js).toContain('PDF Viewer');
+        // 4. languages
+        expect(js).toContain('languages');
+        // 5. permissions
+        expect(js).toContain('Permissions');
+        expect(js).toContain('notifications');
+        // 6. automation artifacts (dynamic cdc_ scan)
+        expect(js).toContain('__playwright');
+        expect(js).toContain('__puppeteer');
+        expect(js).toContain('getOwnPropertyNames');
+        expect(js).toContain('cdc_');
+        // 7. CDP stack trace cleanup
+        expect(js).toContain('Error.prototype');
+        expect(js).toContain('puppeteer_evaluation_script');
+        expect(js).toContain('getOwnPropertyDescriptor');
+    });
+    it('includes guard flag to prevent double-injection', () => {
+        const js = generateStealthJs();
+        // Guard uses a non-enumerable property on a built-in prototype
+        expect(js).toContain("EventTarget.prototype");
+        // Guard should check early and return 'skipped'
+        expect(js).toContain("return 'skipped'");
+        // Normal path returns 'applied'
+        expect(js).toContain("return 'applied'");
+    });
+    it('generates syntactically valid JS', () => {
+        const js = generateStealthJs();
+        // Should not throw when parsed
+        expect(() => new Function(js)).not.toThrow();
+    });
+});