@agentrhq/webcmd 0.1.2 → 0.2.0

package/dist/src/cli.test.js

@@ -100,10 +100,10 @@ describe('createProgram root help descriptions', () => {
         registry.clear();
         try {
             cli({
-                site: 'bilibili',
+                site: 'reddit',
                 name: 'hot',
                 access: 'read',
-                description: 'Bilibili hot videos',
+                description: 'Reddit hot posts',
                 strategy: Strategy.PUBLIC,
                 browser: false,
             });
@@ -118,9 +118,9 @@ describe('createProgram root help descriptions', () => {
             const program = createProgram('', '');
             const help = program.helpInformation();
             expect(help).toContain('Site adapters (2):');
-            expect(help).toContain('bilibili, youtube');
+            expect(help).toContain('reddit, youtube');
             expect(help).toContain("webcmd <site> --help -f yaml");
-            expect(help).not.toMatch(/\n  bilibili\s+hot/);
+            expect(help).not.toMatch(/\n  reddit\s+hot/);
             expect(help).not.toMatch(/\n  youtube\s+search/);
         }
         finally {
@@ -135,11 +135,11 @@ describe('createProgram root help descriptions', () => {
         registry.clear();
         try {
             cli({
-                site: 'bilibili',
-                name: 'hot',
+                site: 'youtube',
+                name: 'search',
                 access: 'read',
-                description: 'Bilibili hot videos',
-                domain: 'www.bilibili.com',
+                description: 'Search YouTube',
+                domain: 'www.youtube.com',
                 strategy: Strategy.PUBLIC,
                 browser: false,
             });
@@ -158,7 +158,7 @@ describe('createProgram root help descriptions', () => {
             expect(help).toContain('App adapters (1):');
             expect(help).toMatch(/App adapters \(1\):\n {2}chatwise/);
             expect(help).toContain('Site adapters (1):');
-            expect(help).toMatch(/Site adapters \(1\):\n {2}bilibili/);
+            expect(help).toMatch(/Site adapters \(1\):\n {2}youtube/);
             // App adapters appear before Site adapters (External CLIs are absent here)
             expect(help.indexOf('App adapters')).toBeLessThan(help.indexOf('Site adapters'));
         }
@@ -172,7 +172,7 @@ describe('createProgram root help descriptions', () => {
         expect(classifyAdapter('localhost')).toBe('app');
         expect(classifyAdapter('127.0.0.1')).toBe('app');
         expect(classifyAdapter('::1')).toBe('app');
-        expect(classifyAdapter('www.bilibili.com')).toBe('site');
+        expect(classifyAdapter('www.youtube.com')).toBe('site');
     });
     it('splits list table output into App and Site sections without changing per-site rows', async () => {
         const registry = getRegistry();
@@ -200,11 +200,11 @@ describe('createProgram root help descriptions', () => {
                 browser: true,
             });
             cli({
-                site: 'bilibili',
-                name: 'hot',
+                site: 'youtube',
+                name: 'search',
                 access: 'read',
-                description: 'Bilibili hot videos',
-                domain: 'www.bilibili.com',
+                description: 'Search YouTube',
+                domain: 'www.youtube.com',
                 strategy: Strategy.PUBLIC,
                 browser: false,
             });
@@ -216,7 +216,7 @@ describe('createProgram root help descriptions', () => {
             expect(output.indexOf('App adapters')).toBeLessThan(output.indexOf('Site adapters'));
             expect(output).toMatch(/App adapters[\s\S]*antigravity[\s\S]*history \[ui\] — Read Antigravity history/);
             expect(output).toMatch(/App adapters[\s\S]*chatwise[\s\S]*ask \[ui\] — Ask Chatwise desktop app/);
-            expect(output).toMatch(/Site adapters[\s\S]*bilibili[\s\S]*hot \[public\] — Bilibili hot videos/);
+            expect(output).toMatch(/Site adapters[\s\S]*youtube[\s\S]*search \[public\] — Search YouTube/);
             expect(output).toContain('3 built-in commands across 2 apps + 1 sites,');
         }
         finally {
@@ -235,11 +235,11 @@ describe('createProgram root help descriptions', () => {
         registry.clear();
         try {
             cli({
-                site: 'bilibili',
-                name: 'hot',
+                site: 'youtube',
+                name: 'search',
                 access: 'read',
-                description: 'Bilibili hot videos',
-                domain: 'www.bilibili.com',
+                description: 'Search YouTube',
+                domain: 'www.youtube.com',
                 strategy: Strategy.PUBLIC,
                 browser: false,
                 columns: ['title', 'url'],
@@ -257,9 +257,9 @@ describe('createProgram root help descriptions', () => {
             const rows = JSON.parse(jsonOutput);
             expect(rows).toMatchObject([
                 {
-                    site: 'bilibili',
-                    name: 'hot',
-                    domain: 'www.bilibili.com',
+                    site: 'youtube',
+                    name: 'search',
+                    domain: 'www.youtube.com',
                     columns: ['title', 'url'],
                 },
             ]);
@@ -281,11 +281,11 @@ describe('createProgram root help descriptions', () => {
         registry.clear();
         try {
             cli({
-                site: 'bilibili',
-                name: 'hot',
+                site: 'youtube',
+                name: 'search',
                 access: 'read',
-                description: 'Bilibili hot videos',
-                domain: 'www.bilibili.com',
+                description: 'Search YouTube',
+                domain: 'www.youtube.com',
                 strategy: Strategy.PUBLIC,
                 browser: false,
             });
@@ -304,13 +304,13 @@ describe('createProgram root help descriptions', () => {
             expect(data.app_adapters.count).toBe(1);
             expect(data.app_adapters.apps).toEqual(['chatwise']);
             expect(data.site_adapters.count).toBe(1);
-            expect(data.site_adapters.sites).toEqual(['bilibili']);
+            expect(data.site_adapters.sites).toEqual(['youtube']);
             expect(data.external_clis.count).toBeGreaterThanOrEqual(0);
             expect(Array.isArray(data.external_clis.clis)).toBe(true);
             expect(Array.isArray(data.external_clis.display)).toBe(true);
             // Adapters must NOT leak into the core commands list
             const commandNames = data.commands.map((cmd) => cmd.name);
-            expect(commandNames).not.toContain('bilibili');
+            expect(commandNames).not.toContain('youtube');
             expect(commandNames).not.toContain('chatwise');
         }
         finally {
@@ -327,10 +327,10 @@ describe('createProgram root help descriptions', () => {
         registry.clear();
         try {
             cli({
-                site: 'bilibili',
-                name: 'hot',
+                site: 'youtube',
+                name: 'search',
                 access: 'read',
-                description: 'Bilibili hot videos',
+                description: 'Search YouTube',
                 strategy: Strategy.PUBLIC,
                 browser: false,
             });
@@ -338,9 +338,9 @@ describe('createProgram root help descriptions', () => {
             process.argv = ['node', 'webcmd', '--help', '-f', 'yaml'];
             const data = yaml.load(program.helpInformation());
             expect(data.site_adapters.count).toBe(1);
-            expect(data.site_adapters.sites).toEqual(['bilibili']);
+            expect(data.site_adapters.sites).toEqual(['youtube']);
             expect(data.commands.map((cmd) => cmd.name)).toContain('list');
-            expect(data.commands.map((cmd) => cmd.name)).not.toContain('bilibili');
+            expect(data.commands.map((cmd) => cmd.name)).not.toContain('youtube');
         }
         finally {
             process.argv = argv;
@@ -356,28 +356,28 @@ describe('createProgram root help descriptions', () => {
         registry.clear();
         try {
             cli({
-                site: 'bilibili',
-                name: 'hot',
+                site: 'youtube',
+                name: 'search',
                 access: 'read',
-                description: 'Bilibili hot videos',
+                description: 'Search YouTube',
                 strategy: Strategy.PUBLIC,
                 browser: false,
                 args: [{ name: 'limit', type: 'int', default: 20, help: 'Number of videos' }],
                 columns: ['title', 'url'],
             });
             const program = createProgram('', '');
-            const site = program.commands.find(cmd => cmd.name() === 'bilibili');
+            const site = program.commands.find(cmd => cmd.name() === 'youtube');
             expect(site).toBeTruthy();
-            process.argv = ['node', 'webcmd', 'bilibili', '--help', '-f', 'yaml'];
+            process.argv = ['node', 'webcmd', 'youtube', '--help', '-f', 'yaml'];
             const data = yaml.load(site.helpInformation());
-            expect(data.site).toBe('bilibili');
+            expect(data.site).toBe('youtube');
             expect(data.commands).toMatchObject([
                 {
-                    name: 'hot',
+                    name: 'search',
                     access: 'read',
-                    description: 'Bilibili hot videos',
+                    description: 'Search YouTube',
                     browser: false,
-                    example: 'webcmd bilibili hot -f yaml',
+                    example: 'webcmd youtube search -f yaml',
                     command_options: [{ name: 'limit', type: 'int', default: 20 }],
                     columns: ['title', 'url'],
                 },
@@ -397,31 +397,31 @@ describe('createProgram root help descriptions', () => {
         registry.clear();
         try {
             cli({
-                site: 'bilibili',
-                name: 'hot',
+                site: 'youtube',
+                name: 'search',
                 access: 'read',
-                description: 'Bilibili hot videos',
+                description: 'Search YouTube',
                 strategy: Strategy.PUBLIC,
                 browser: false,
                 args: [{ name: 'limit', type: 'int', default: 20, help: 'Number of videos' }],
             });
             cli({
-                site: 'bilibili',
+                site: 'youtube',
                 name: 'video',
                 access: 'read',
                 description: 'Read one video',
-                domain: 'www.bilibili.com',
+                domain: 'www.youtube.com',
                 strategy: Strategy.PUBLIC,
                 browser: true,
                 args: [{ name: 'bvid', positional: true, required: true, help: 'Video id' }],
             });
             const program = createProgram('', '');
-            const site = program.commands.find(cmd => cmd.name() === 'bilibili');
+            const site = program.commands.find(cmd => cmd.name() === 'youtube');
             expect(site).toBeTruthy();
             const help = site.helpInformation();
-            expect(help).toContain('hot [options]  [read] Bilibili hot videos');
-            expect(help).toContain('video <bvid>   [read] Read one video');
-            expect(help).toContain('hot [options]');
+            expect(help).toContain('search [options]  [read] Search YouTube');
+            expect(help).toContain('video <bvid>      [read] Read one video');
+            expect(help).toContain('search [options]');
             expect(help).not.toContain('video <bvid> [options]');
             expect(help).not.toContain('\nOptions:');
             expect(help).toContain('Common options:');
@@ -442,12 +442,12 @@ describe('createProgram root help descriptions', () => {
         registry.clear();
         try {
             cli({
-                site: 'bilibili',
+                site: 'youtube',
                 name: 'video',
                 access: 'read',
                 description: 'Read one video',
                 strategy: Strategy.PUBLIC,
-                domain: 'www.bilibili.com',
+                domain: 'www.youtube.com',
                 browser: true,
                 args: [
                     { name: 'bvid', positional: true, required: true, help: 'Video id' },
@@ -456,14 +456,14 @@ describe('createProgram root help descriptions', () => {
                 columns: ['title', 'url'],
             });
             const program = createProgram('', '');
-            const site = program.commands.find(cmd => cmd.name() === 'bilibili');
+            const site = program.commands.find(cmd => cmd.name() === 'youtube');
             const command = site.commands.find(cmd => cmd.name() === 'video');
             expect(command).toBeTruthy();
-            process.argv = ['node', 'webcmd', 'bilibili', 'video', '--help', '-f', 'yaml'];
+            process.argv = ['node', 'webcmd', 'youtube', 'video', '--help', '-f', 'yaml'];
             const data = yaml.load(command.helpInformation());
-            expect(data.usage).toBe('webcmd bilibili video <bvid> [options]');
+            expect(data.usage).toBe('webcmd youtube video <bvid> [options]');
             expect(data.browser).toBe(true);
-            expect(data.domain).toBe('www.bilibili.com');
+            expect(data.domain).toBe('www.youtube.com');
             expect(data.positionals).toMatchObject([{ name: 'bvid', positional: true, required: true }]);
             expect(data.command_options).toMatchObject([{ name: 'with-comments', default: false }]);
             expect(data.common_options.map((option) => option.name)).toEqual(['format', 'trace', 'verbose', 'help']);

package/dist/src/commanderAdapter.test.js

@@ -251,12 +251,12 @@ describe('commanderAdapter default formats', () => {
 });
 describe('commanderAdapter error envelope output', () => {
     const cmd = {
-        site: 'xiaohongshu',
-        name: 'note', access: 'read',
-        description: 'Read one note',
+        site: 'github',
+        name: 'issue', access: 'read',
+        description: 'Read one issue',
         browser: false,
         args: [
-            { name: 'note-id', positional: true, required: true, help: 'Note ID' },
+            { name: 'issue-id', positional: true, required: true, help: 'Issue ID' },
         ],
         func: vi.fn(),
     };
@@ -268,26 +268,26 @@ describe('commanderAdapter error envelope output', () => {
     });
     it('outputs YAML error envelope with adapter hint to stderr', async () => {
         const program = new Command();
-        const siteCmd = program.command('xiaohongshu');
+        const siteCmd = program.command('github');
         registerCommandToProgram(siteCmd, cmd);
         const stderrSpy = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
-        mockExecuteCommand.mockRejectedValueOnce(new EmptyResultError('xiaohongshu/note', 'Pass the full search_result URL with xsec_token instead of a bare note ID.'));
-        await program.parseAsync(['node', 'webcmd', 'xiaohongshu', 'note', '69ca3927000000001a020fd5']);
+        mockExecuteCommand.mockRejectedValueOnce(new EmptyResultError('github/issue', 'Pass the full issue URL instead of a bare issue number.'));
+        await program.parseAsync(['node', 'webcmd', 'github', 'issue', '12345']);
         const output = stderrSpy.mock.calls.map(c => String(c[0])).join('');
         expect(output).toContain('ok: false');
         expect(output).toContain('code: EMPTY_RESULT');
-        expect(output).toContain('xsec_token');
+        expect(output).toContain('full issue URL');
         expect(output).toContain('--trace=retain-on-failure');
-        expect(output).toContain('webcmd xiaohongshu note --trace retain-on-failure');
+        expect(output).toContain('webcmd github issue --trace retain-on-failure');
         stderrSpy.mockRestore();
     });
     it('outputs YAML error envelope for selector errors', async () => {
         const program = new Command();
-        const siteCmd = program.command('xiaohongshu');
+        const siteCmd = program.command('github');
         registerCommandToProgram(siteCmd, cmd);
         const stderrSpy = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
         mockExecuteCommand.mockRejectedValueOnce(selectorError('.note-title', 'The note title selector no longer matches the current page.'));
-        await program.parseAsync(['node', 'webcmd', 'xiaohongshu', 'note', '69ca3927000000001a020fd5']);
+        await program.parseAsync(['node', 'webcmd', 'github', 'issue', '12345']);
         const output = stderrSpy.mock.calls.map(c => String(c[0])).join('');
         expect(output).toContain('ok: false');
         expect(output).toContain('code: SELECTOR');
@@ -297,16 +297,16 @@ describe('commanderAdapter error envelope output', () => {
     });
     it('does not add an AutoFix rerun hint when trace is already enabled', async () => {
         const program = new Command();
-        const siteCmd = program.command('xiaohongshu');
+        const siteCmd = program.command('github');
         registerCommandToProgram(siteCmd, cmd);
         const stderrSpy = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
         mockExecuteCommand.mockRejectedValueOnce(selectorError('.note-title'));
         await program.parseAsync([
             'node',
             'webcmd',
-            'xiaohongshu',
-            'note',
-            '69ca3927000000001a020fd5',
+            'github',
+            'issue',
+            '12345',
             '--trace',
             'retain-on-failure',
         ]);
@@ -317,7 +317,7 @@ describe('commanderAdapter error envelope output', () => {
     });
     it('includes trace metadata from the error envelope when execution attached it', async () => {
         const program = new Command();
-        const siteCmd = program.command('xiaohongshu');
+        const siteCmd = program.command('github');
         registerCommandToProgram(siteCmd, cmd);
         const stderrSpy = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
         const err = selectorError('.note-title');
@@ -336,9 +336,9 @@ describe('commanderAdapter error envelope output', () => {
         await program.parseAsync([
             'node',
             'webcmd',
-            'xiaohongshu',
-            'note',
-            '69ca3927000000001a020fd5',
+            'github',
+            'issue',
+            '12345',
             '--trace',
             'retain-on-failure',
         ]);

package/dist/src/convention-audit.js

@@ -244,7 +244,7 @@ function auditTypedErrorPatterns(command, source, sourcePath, projectRoot) {
                 details: { text: line.trim() },
             });
         }
-        const sentinel = /(?:\?\?|\|\|)\s*(['"])(unknown|Unknown|UNKNOWN|N\/A|n\/a|NA|未知|-)\1/.exec(line);
+        const sentinel = /(?:\?\?|\|\|)\s*(['"])(unknown|Unknown|UNKNOWN|N\/A|n\/a|NA|-)\1/.exec(line);
         if (sentinel) {
             if (!isThrowMessageLine(line)) {
                 violations.push({

package/dist/src/daemon/server.js

@@ -1,6 +1,6 @@
 import { createServer } from 'node:http';
 import { DAEMON_HEADER_NAME, DEFAULT_DAEMON_PORT } from '../constants.js';
-import { getResponseCorsHeaders } from '../daemon-utils.js';
+import { buildCommandTimeoutFailure, getResponseCorsHeaders } from '../daemon-utils.js';
 const MAX_BODY = 1024 * 1024;
 const LOG_BUFFER_SIZE = 200;
 function readBody(req) {
@@ -36,7 +36,7 @@ export function createDaemonServer(provider, opts) {
     const port = opts.port ?? DEFAULT_DAEMON_PORT;
     const host = opts.host ?? '127.0.0.1';
     const logBuffer = [];
-    const pending = new Set();
+    const pending = new Map();
     let shutdownStarted = false;
     function pushLog(level, msg) {
         logBuffer.push({ level, msg, ts: Date.now() });
@@ -115,35 +115,40 @@ export function createDaemonServer(provider, opts) {
                     jsonResponse(res, 400, { ok: false, error: 'Missing command id' });
                     return;
                 }
-                if (pending.has(body.id)) {
-                    jsonResponse(res, 409, { id: body.id, ok: false, error: 'Duplicate command id already pending; retry' });
+                const existing = pending.get(body.id);
+                if (existing) {
+                    const result = await existing;
+                    jsonResponse(res, result.ok ? 200 : result.errorCode === 'command_result_unknown' ? 408 : 400, result);
                     return;
                 }
-                pending.add(body.id);
-                const timeoutMs = typeof body.timeout === 'number' && body.timeout > 0 ? body.timeout * 1000 : 120_000;
+                const timeoutMs = typeof body.deadlineAt === 'number' && body.deadlineAt > 0
+                    ? Math.max(1000, body.deadlineAt - Date.now())
+                    : (typeof body.timeout === 'number' && body.timeout > 0 ? body.timeout * 1000 : 120_000);
                 let timeoutId;
-                try {
-                    const result = await Promise.race([
-                        provider.dispatch(body),
-                        new Promise((resolve) => {
-                            timeoutId = setTimeout(() => resolve({
+                const commandPromise = Promise.race([
+                    provider.dispatch(body),
+                    new Promise((resolve) => {
+                        timeoutId = setTimeout(() => {
+                            const failure = buildCommandTimeoutFailure(body.action, timeoutMs);
+                            resolve({
                                 id: body.id,
                                 ok: false,
-                                errorCode: 'command_result_unknown',
-                                error: `Command timeout (${timeoutMs / 1000}s)`,
-                                errorHint: 'Inspect the browser state before retrying non-idempotent commands.',
-                            }), timeoutMs);
-                        }),
-                    ]);
-                    if (!result.ok)
-                        pushLog('warn', `Command ${body.id} failed: ${result.error ?? result.errorCode ?? 'unknown error'}`);
-                    jsonResponse(res, result.ok ? 200 : result.errorCode === 'command_result_unknown' ? 408 : 400, result);
-                }
-                finally {
+                                errorCode: failure.errorCode,
+                                error: failure.message,
+                                errorHint: failure.errorHint,
+                            });
+                        }, timeoutMs);
+                    }),
+                ]).finally(() => {
                     if (timeoutId)
                         clearTimeout(timeoutId);
                     pending.delete(body.id);
-                }
+                });
+                pending.set(body.id, commandPromise);
+                const result = await commandPromise;
+                if (!result.ok)
+                    pushLog('warn', `Command ${body.id} failed: ${result.error ?? result.errorCode ?? 'unknown error'}`);
+                jsonResponse(res, result.ok ? 200 : result.errorCode === 'command_result_unknown' ? 408 : 400, result);
             }
             catch (err) {
                 jsonResponse(res, 400, { ok: false, error: err instanceof Error ? err.message : 'Invalid request' });

package/dist/src/daemon/server.test.js

@@ -93,6 +93,58 @@ describe('createDaemonServer', () => {
             clearTimeoutSpy.mockRestore();
         }
     });
+    it('uses deadlineAt as the command timeout budget when present', async () => {
+        const now = 1_763_000_000_000;
+        const dateSpy = vi.spyOn(Date, 'now').mockReturnValue(now);
+        const setTimeoutSpy = vi.spyOn(globalThis, 'setTimeout');
+        try {
+            const { baseUrl } = await start();
+            const res = await fetch(`${baseUrl}/command`, {
+                method: 'POST',
+                headers: { [DAEMON_HEADER_NAME]: '1', 'Content-Type': 'application/json' },
+                body: JSON.stringify({
+                    id: 'deadline-command',
+                    action: 'exec',
+                    session: 'work',
+                    timeout: 120,
+                    deadlineAt: now + 12_345,
+                }),
+            });
+            expect(res.status).toBe(200);
+            await expect(res.json()).resolves.toMatchObject({
+                id: 'deadline-command',
+                ok: true,
+            });
+            expect(setTimeoutSpy.mock.calls.some(([, delay]) => delay === 12_345)).toBe(true);
+        }
+        finally {
+            setTimeoutSpy.mockRestore();
+            dateSpy.mockRestore();
+        }
+    });
+    it('attaches duplicate command ids to the in-flight dispatch instead of re-dispatching', async () => {
+        const provider = new FakeProvider();
+        provider.delayMs = 50;
+        const { baseUrl } = await start(provider);
+        const body = JSON.stringify({ id: 'same-id', action: 'exec', session: 'work', code: '1' });
+        const [first, second] = await Promise.all([
+            fetch(`${baseUrl}/command`, {
+                method: 'POST',
+                headers: { [DAEMON_HEADER_NAME]: '1', 'Content-Type': 'application/json' },
+                body,
+            }),
+            fetch(`${baseUrl}/command`, {
+                method: 'POST',
+                headers: { [DAEMON_HEADER_NAME]: '1', 'Content-Type': 'application/json' },
+                body,
+            }),
+        ]);
+        expect(first.status).toBe(200);
+        expect(second.status).toBe(200);
+        await expect(first.json()).resolves.toMatchObject({ id: 'same-id', ok: true });
+        await expect(second.json()).resolves.toMatchObject({ id: 'same-id', ok: true });
+        expect(provider.commands).toHaveLength(1);
+    });
     it('requires X-Webcmd on non-ping endpoints', async () => {
         const { baseUrl } = await start();
         const res = await fetch(`${baseUrl}/status`);

package/dist/src/daemon-utils.d.ts

@@ -14,5 +14,6 @@ export declare function buildExtensionDisconnectFailure(input: {
     action: string;
     dispatched: boolean;
 }): DaemonFailureContract;
+export declare function buildCommandTimeoutFailure(action: string, timeoutMs: number): DaemonFailureContract;
 export declare function buildCommandDispatchFailure(contextId: string): DaemonFailureContract;
 export declare function getResponseCorsHeaders(pathname: string, origin?: string): Record<string, string> | undefined;

package/dist/src/daemon-utils.js

@@ -16,6 +16,15 @@ export function buildExtensionDisconnectFailure(input) {
     }
     return buildCommandDispatchFailure(input.contextId);
 }
+export function buildCommandTimeoutFailure(action, timeoutMs) {
+    return {
+        message: `Browser ${action} command timed out after ${Math.round(timeoutMs / 1000)}s; it may still complete in the browser.`,
+        errorCode: COMMAND_RESULT_UNKNOWN_CODE,
+        errorHint: COMMAND_RESULT_UNKNOWN_HINT,
+        status: 408,
+        countAsCommandResultUnknown: true,
+    };
+}
 export function buildCommandDispatchFailure(contextId) {
     return {
         message: `Browser profile "${contextId}" disconnected before command dispatch`,

package/dist/src/daemon.test.js

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import { COMMAND_RESULT_UNKNOWN_CODE, COMMAND_RESULT_UNKNOWN_HINT, buildCommandDispatchFailure, buildExtensionDisconnectFailure, commandResultUnknownMessage, getResponseCorsHeaders, } from './daemon-utils.js';
+import { COMMAND_RESULT_UNKNOWN_CODE, COMMAND_RESULT_UNKNOWN_HINT, buildCommandDispatchFailure, buildCommandTimeoutFailure, buildExtensionDisconnectFailure, commandResultUnknownMessage, getResponseCorsHeaders, } from './daemon-utils.js';
 describe('getResponseCorsHeaders', () => {
     it('allows the packaged runtime origin to read /ping', () => {
         expect(getResponseCorsHeaders('/ping', 'chrome-extension://abc123')).toEqual({
@@ -57,4 +57,13 @@ describe('daemon command dispatch', () => {
             countAsCommandResultUnknown: false,
         });
     });
+    it('classifies command timeouts as command_result_unknown', () => {
+        expect(buildCommandTimeoutFailure('exec', 12_345)).toEqual({
+            message: 'Browser exec command timed out after 12s; it may still complete in the browser.',
+            errorCode: 'command_result_unknown',
+            errorHint: COMMAND_RESULT_UNKNOWN_HINT,
+            status: 408,
+            countAsCommandResultUnknown: true,
+        });
+    });
 });

package/dist/src/doctor.js

@@ -5,6 +5,7 @@
  */
 import { DEFAULT_DAEMON_PORT } from './constants.js';
 import { BrowserBridge } from './browser/index.js';
+import { setDaemonCommandTimeoutSeconds } from './browser/daemon-client.js';
 import { getDaemonHealth } from './browser/daemon-transport.js';
 import { getErrorMessage } from './errors.js';
 import { getRuntimeLabel } from './runtime-detect.js';
@@ -18,10 +19,12 @@ const DOCTOR_SESSION = '__doctor__';
  */
 export async function checkConnectivity(opts) {
     const start = Date.now();
+    const timeoutSeconds = opts?.timeout ?? DOCTOR_LIVE_TIMEOUT_SECONDS;
+    setDaemonCommandTimeoutSeconds(timeoutSeconds);
     try {
         const bridge = new BrowserBridge();
         const page = await bridge.connect({
-            timeout: opts?.timeout ?? DOCTOR_LIVE_TIMEOUT_SECONDS,
+            timeout: timeoutSeconds,
             session: DOCTOR_SESSION,
             surface: 'browser',
         });
@@ -38,6 +41,9 @@ export async function checkConnectivity(opts) {
     catch (err) {
         return { ok: false, error: getErrorMessage(err), durationMs: Date.now() - start };
     }
+    finally {
+        setDaemonCommandTimeoutSeconds(null);
+    }
 }
 export async function runBrowserDoctor(opts = {}) {
     // Live connectivity check is the core of doctor — it doubles as auto-start

package/dist/src/doctor.test.js

@@ -1,9 +1,10 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest';
-const { mockGetDaemonHealth, mockConnect, mockClose, mockFindShadowedUserAdapters } = vi.hoisted(() => ({
+const { mockGetDaemonHealth, mockConnect, mockClose, mockFindShadowedUserAdapters, mockSetDaemonCommandTimeoutSeconds, } = vi.hoisted(() => ({
     mockGetDaemonHealth: vi.fn(),
     mockConnect: vi.fn(),
     mockClose: vi.fn(),
     mockFindShadowedUserAdapters: vi.fn(),
+    mockSetDaemonCommandTimeoutSeconds: vi.fn(),
 }));
 vi.mock('./browser/daemon-transport.js', () => ({
     getDaemonHealth: mockGetDaemonHealth,
@@ -14,6 +15,9 @@ vi.mock('./browser/index.js', () => ({
         close = mockClose;
     },
 }));
+vi.mock('./browser/daemon-client.js', () => ({
+    setDaemonCommandTimeoutSeconds: mockSetDaemonCommandTimeoutSeconds,
+}));
 vi.mock('./adapter-shadow.js', async () => {
     const actual = await vi.importActual('./adapter-shadow.js');
     return {
@@ -27,6 +31,7 @@ describe('doctor report rendering', () => {
     beforeEach(() => {
         vi.clearAllMocks();
         mockFindShadowedUserAdapters.mockReturnValue([]);
+        mockSetDaemonCommandTimeoutSeconds.mockClear();
         // Doctor always runs live connectivity. Tests that want connect to fail override.
         mockConnect.mockResolvedValue({
             evaluate: vi.fn().mockResolvedValue(2),
@@ -202,6 +207,8 @@ describe('doctor report rendering', () => {
         await runBrowserDoctor();
         expect(timeoutSeen).toBe(8);
         expect(closeWindow).toHaveBeenCalledTimes(1);
+        expect(mockSetDaemonCommandTimeoutSeconds).toHaveBeenNthCalledWith(1, 8);
+        expect(mockSetDaemonCommandTimeoutSeconds).toHaveBeenLastCalledWith(null);
     });
     it('does not report an issue when the connected Cloak runtime does not report a version', async () => {
         const status = {