@jackwener/opencli 1.7.8 → 1.7.10

package/dist/src/cli.test.js

@@ -2,10 +2,15 @@ import { beforeEach, describe, expect, it, vi } from 'vitest';
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
+import { BrowserCommandError } from './browser/daemon-client.js';
 import { TargetError } from './browser/target-errors.js';
-const { mockBrowserConnect, mockBrowserClose, browserState, } = vi.hoisted(() => ({
+import { PKG_VERSION } from './version.js';
+const { mockBrowserConnect, mockBrowserClose, mockBindTab, mockSendCommand, mockExecFileSync, browserState, } = vi.hoisted(() => ({
     mockBrowserConnect: vi.fn(),
     mockBrowserClose: vi.fn(),
+    mockBindTab: vi.fn(),
+    mockSendCommand: vi.fn(),
+    mockExecFileSync: vi.fn(),
     browserState: { page: null },
 }));
 vi.mock('./browser/index.js', () => {
@@ -17,7 +22,22 @@ vi.mock('./browser/index.js', () => {
         },
     };
 });
-import { createProgram, findPackageRoot, normalizeVerifyRows, renderVerifyPreview, resolveBrowserVerifyInvocation } from './cli.js';
+vi.mock('./browser/daemon-client.js', async () => {
+    const actual = await vi.importActual('./browser/daemon-client.js');
+    return {
+        ...actual,
+        bindTab: mockBindTab,
+        sendCommand: mockSendCommand,
+    };
+});
+vi.mock('node:child_process', async () => {
+    const actual = await vi.importActual('node:child_process');
+    return {
+        ...actual,
+        execFileSync: mockExecFileSync,
+    };
+});
+import { createProgram, findPackageRoot, normalizeVerifyRows, renderVerifyPreview, resolveBrowserVerifyInvocation, selectFreshByTimestamp } from './cli.js';
 describe('resolveBrowserVerifyInvocation', () => {
     it('prefers the built entry declared in package metadata', () => {
         const projectRoot = path.join('repo-root');
@@ -82,6 +102,107 @@ describe('resolveBrowserVerifyInvocation', () => {
         });
     });
 });
+describe('selectFreshByTimestamp', () => {
+    it('uses timestamp watermarks so rolled buffers still emit new messages', () => {
+        const first = selectFreshByTimestamp([
+            { timestamp: 1, text: 'a' },
+            { timestamp: 2, text: 'b' },
+        ], 0);
+        expect(first.fresh.map((item) => item.text)).toEqual(['a', 'b']);
+        expect(first.lastSeenTs).toBe(2);
+        const rolled = selectFreshByTimestamp([
+            { timestamp: 2, text: 'b' },
+            { timestamp: 3, text: 'c' },
+        ], first.lastSeenTs);
+        expect(rolled.fresh.map((item) => item.text)).toEqual(['c']);
+        expect(rolled.lastSeenTs).toBe(3);
+    });
+});
+describe('browser verify', () => {
+    beforeEach(() => {
+        process.exitCode = undefined;
+        mockExecFileSync.mockReset().mockReturnValue('[]');
+    });
+    it('passes --trace through to the adapter subprocess', async () => {
+        const originalHome = process.env.HOME;
+        const originalUserProfile = process.env.USERPROFILE;
+        const fakeHome = fs.mkdtempSync(path.join(os.tmpdir(), 'opencli-browser-verify-trace-'));
+        process.env.HOME = fakeHome;
+        process.env.USERPROFILE = fakeHome;
+        try {
+            const adapterDir = path.join(fakeHome, '.opencli', 'clis', 'hn');
+            fs.mkdirSync(adapterDir, { recursive: true });
+            fs.writeFileSync(path.join(adapterDir, 'top.js'), 'export default {};\n', 'utf-8');
+            const program = createProgram('', '');
+            await program.parseAsync(['node', 'opencli', 'browser', 'verify', 'hn/top', '--no-fixture', '--trace', 'retain-on-failure']);
+            expect(mockExecFileSync).toHaveBeenCalledTimes(1);
+            const [, execArgs] = mockExecFileSync.mock.calls[0];
+            expect(execArgs.slice(-6)).toEqual(['hn', 'top', '--trace', 'retain-on-failure', '--format', 'json']);
+        }
+        finally {
+            if (originalHome === undefined)
+                delete process.env.HOME;
+            else
+                process.env.HOME = originalHome;
+            if (originalUserProfile === undefined)
+                delete process.env.USERPROFILE;
+            else
+                process.env.USERPROFILE = originalUserProfile;
+            fs.rmSync(fakeHome, { recursive: true, force: true });
+        }
+    });
+});
+describe('profile list', () => {
+    const stdoutSpy = vi.spyOn(console, 'log').mockImplementation(() => { });
+    beforeEach(() => {
+        process.exitCode = undefined;
+        stdoutSpy.mockClear();
+        vi.stubGlobal('fetch', vi.fn());
+    });
+    it('reports stale daemon instead of no profiles when status lacks profile support', async () => {
+        vi.mocked(fetch).mockResolvedValue({
+            ok: true,
+            json: async () => ({
+                ok: true,
+                pid: 123,
+                uptime: 1,
+                daemonVersion: '1.7.6',
+                extensionConnected: true,
+                extensionVersion: '1.0.3',
+                pending: 0,
+                memoryMB: 20,
+                port: 19825,
+            }),
+        });
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'profile', 'list']);
+        const output = stdoutSpy.mock.calls.flat().join('\n');
+        expect(output).toContain('stale');
+        expect(output).toContain('opencli daemon restart');
+        expect(output).not.toContain('No Browser Bridge profiles connected');
+    });
+    it('keeps the empty profile message for current daemon status with no profiles', async () => {
+        vi.mocked(fetch).mockResolvedValue({
+            ok: true,
+            json: async () => ({
+                ok: true,
+                pid: 123,
+                uptime: 1,
+                daemonVersion: PKG_VERSION,
+                extensionConnected: false,
+                profiles: [],
+                pending: 0,
+                memoryMB: 20,
+                port: 19825,
+            }),
+        });
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'profile', 'list']);
+        const output = stdoutSpy.mock.calls.flat().join('\n');
+        expect(output).toContain('No Browser Bridge profiles connected');
+        expect(output).not.toContain('opencli daemon restart');
+    });
+});
 describe('browser tab targeting commands', () => {
     const consoleLogSpy = vi.spyOn(console, 'log').mockImplementation(() => { });
     const stderrSpy = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
@@ -95,6 +216,13 @@ describe('browser tab targeting commands', () => {
         stderrSpy.mockClear();
         mockBrowserConnect.mockClear();
         mockBrowserClose.mockReset().mockResolvedValue(undefined);
+        mockBindTab.mockReset().mockResolvedValue({
+            workspace: 'bound:default',
+            page: 'tab-2',
+            url: 'https://user.example/inbox',
+            title: 'Inbox',
+        });
+        mockSendCommand.mockReset().mockResolvedValue({ closed: true });
         browserState.page = {
             goto: vi.fn().mockResolvedValue(undefined),
             wait: vi.fn().mockResolvedValue(undefined),
@@ -104,6 +232,7 @@ describe('browser tab targeting commands', () => {
             startNetworkCapture: vi.fn().mockResolvedValue(true),
             getCookies: vi.fn().mockResolvedValue([]),
             evaluate: vi.fn().mockResolvedValue({ ok: true }),
+            snapshot: vi.fn().mockResolvedValue('snapshot'),
             tabs: vi.fn().mockResolvedValue([
                 { index: 0, page: 'tab-1', url: 'https://one.example', title: 'one', active: true },
                 { index: 1, page: 'tab-2', url: 'https://two.example', title: 'two', active: false },
@@ -127,6 +256,62 @@ describe('browser tab targeting commands', () => {
             throw new Error(`Expected string arg to console.log, got ${typeof last}`);
         return JSON.parse(last);
     }
+    it('binds the current Chrome tab into a bound workspace', async () => {
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'bind', '--domain', 'user.example', '--path-prefix', '/inbox']);
+        expect(mockBrowserConnect).toHaveBeenCalledWith({ timeout: 30, workspace: 'bound:default' });
+        expect(mockBindTab).toHaveBeenCalledWith('bound:default', {
+            matchDomain: 'user.example',
+            matchPathPrefix: '/inbox',
+        });
+        const out = lastJsonLog();
+        expect(out.workspace).toBe('bound:default');
+        expect(out.url).toBe('https://user.example/inbox');
+    });
+    it('rejects bind workspaces outside the bound namespace', async () => {
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'bind', '--workspace', 'browser:default']);
+        expect(mockBrowserConnect).not.toHaveBeenCalled();
+        expect(mockBindTab).not.toHaveBeenCalled();
+        const out = lastJsonLog();
+        expect(out.error.code).toBe('invalid_bind_workspace');
+        expect(process.exitCode).toBeDefined();
+    });
+    it('runs browser commands against an explicit bound workspace', async () => {
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', '--workspace', 'bound:default', 'state']);
+        expect(mockBrowserConnect).toHaveBeenCalledWith({ timeout: 30, workspace: 'bound:default' });
+        expect(browserState.page?.snapshot).toHaveBeenCalled();
+    });
+    it('blocks history navigation on bound workspaces unless explicitly allowed', async () => {
+        browserState.page = {
+            ...browserState.page,
+            workspace: 'bound:default',
+            evaluate: vi.fn(),
+            wait: vi.fn(),
+        };
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', '--workspace', 'bound:default', 'back']);
+        expect(browserState.page?.evaluate).not.toHaveBeenCalled();
+        const out = lastJsonLog();
+        expect(out.error.code).toBe('bound_navigation_blocked');
+    });
+    it('unbinds a bound workspace through the daemon close-window command', async () => {
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'unbind', '--workspace', 'bound:default']);
+        expect(mockBrowserConnect).toHaveBeenCalledWith({ timeout: 30, workspace: 'bound:default' });
+        expect(mockSendCommand).toHaveBeenCalledWith('close-window', { workspace: 'bound:default' });
+        const out = lastJsonLog();
+        expect(out).toEqual({ unbound: true, workspace: 'bound:default' });
+    });
+    it('does not print false success when unbind fails', async () => {
+        mockSendCommand.mockRejectedValueOnce(new BrowserCommandError('Workspace "bound:default" is not attached to a tab.', 'bound_session_missing', 'Run bind again, then retry the browser command.'));
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'unbind', '--workspace', 'bound:default']);
+        const out = lastJsonLog();
+        expect(out.error.code).toBe('bound_session_missing');
+        expect(process.exitCode).toBeDefined();
+    });
     it('binds browser commands to an explicit target tab via --tab', async () => {
         const program = createProgram('', '');
         await program.parseAsync(['node', 'opencli', 'browser', 'eval', '--tab', 'tab-2', 'document.title']);
@@ -446,6 +631,9 @@ describe('browser network command', () => {
     function getNetworkCachePath(cacheDir) {
         return path.join(cacheDir, 'browser-network', 'browser_default.json');
     }
+    function getBoundNetworkCachePath(cacheDir) {
+        return path.join(cacheDir, 'browser-network', 'bound_default.json');
+    }
     function lastJsonLog() {
         const calls = consoleLogSpy.mock.calls;
         if (calls.length === 0)
@@ -473,6 +661,7 @@ describe('browser network command', () => {
                     responseStatus: 200,
                     responseContentType: 'application/json',
                     responsePreview: JSON.stringify({ data: { user: { rest_id: '42' } } }),
+                    timestamp: Date.now(),
                 },
                 {
                     url: 'https://cdn.example.com/app.js',
@@ -496,6 +685,19 @@ describe('browser network command', () => {
         expect(out.entries[0]).not.toHaveProperty('body');
         expect(fs.existsSync(getNetworkCachePath(cacheDir))).toBe(true);
     });
+    it('uses the selected browser workspace for network cache scope', async () => {
+        const cacheDir = String(process.env.OPENCLI_CACHE_DIR);
+        browserState.page = {
+            ...browserState.page,
+            workspace: 'bound:default',
+        };
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', '--workspace', 'bound:default', 'network']);
+        const out = lastJsonLog();
+        expect(out.workspace).toBe('bound:default');
+        expect(fs.existsSync(getBoundNetworkCachePath(cacheDir))).toBe(true);
+        expect(fs.existsSync(getNetworkCachePath(cacheDir))).toBe(false);
+    });
     it('--all includes static resources that the default filter drops', async () => {
         const program = createProgram('', '');
         await program.parseAsync(['node', 'opencli', 'browser', 'network', '--all']);
@@ -504,11 +706,73 @@ describe('browser network command', () => {
         expect(out.entries.map((e) => e.key)).toContain('UserTweets');
         expect(out.entries.map((e) => e.key)).toContain('GET cdn.example.com/app.js');
     });
+    it('--failed and --since filter captured entries by status and time window', async () => {
+        const now = Date.now();
+        browserState.page.readNetworkCapture = vi.fn().mockResolvedValue([
+            {
+                url: 'https://api.example.com/new-fail',
+                method: 'GET',
+                responseStatus: 500,
+                responseContentType: 'application/json',
+                responsePreview: JSON.stringify({ error: true }),
+                timestamp: now,
+            },
+            {
+                url: 'https://api.example.com/old-fail',
+                method: 'GET',
+                responseStatus: 500,
+                responseContentType: 'application/json',
+                responsePreview: JSON.stringify({ error: true }),
+                timestamp: now - 180_000,
+            },
+            {
+                url: 'https://api.example.com/new-ok',
+                method: 'GET',
+                responseStatus: 200,
+                responseContentType: 'application/json',
+                responsePreview: JSON.stringify({ ok: true }),
+                timestamp: now,
+            },
+        ]);
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'network', '--since', '120s', '--failed']);
+        const out = lastJsonLog();
+        expect(out.count).toBe(1);
+        expect(out.entries[0].url).toBe('https://api.example.com/new-fail');
+        expect(out.entries[0].timestamp).toMatch(/T/);
+    });
+    it('default output keeps text/javascript API responses while dropping static JS files', async () => {
+        browserState.page.readNetworkCapture = vi.fn().mockResolvedValue([
+            {
+                url: 'https://hw.mail.163.com/js6/s?sid=abc&func=mbox:listMessages',
+                method: 'POST',
+                responseStatus: 200,
+                responseContentType: 'text/javascript',
+                responsePreview: JSON.stringify({ messages: [{ id: 'm1', subject: 'hello' }] }),
+            },
+            {
+                url: 'https://cdn.example.com/app.js',
+                method: 'GET',
+                responseStatus: 200,
+                responseContentType: 'application/javascript',
+                responsePreview: '// js',
+            },
+        ]);
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'network']);
+        const out = lastJsonLog();
+        expect(out.count).toBe(1);
+        expect(out.filtered_out).toBe(1);
+        expect(out.entries[0].key).toBe('POST hw.mail.163.com/js6/s');
+        expect(out.entries[0].ct).toBe('text/javascript');
+        expect(out.entries[0].shape['$.messages']).toBe('array(1)');
+    });
     it('--raw emits full bodies inline for every entry', async () => {
         const program = createProgram('', '');
         await program.parseAsync(['node', 'opencli', 'browser', 'network', '--raw']);
         const out = lastJsonLog();
         expect(out.entries[0].body).toEqual({ data: { user: { rest_id: '42' } } });
+        expect(out.entries[0].timestamp).toMatch(/T/);
     });
     it('--detail <key> returns the full body for the requested entry', async () => {
         const program = createProgram('', '');
@@ -519,6 +783,7 @@ describe('browser network command', () => {
         expect(out.key).toBe('UserTweets');
         expect(out.body).toEqual({ data: { user: { rest_id: '42' } } });
         expect(out.shape['$.data.user.rest_id']).toBe('string');
+        expect(out.timestamp).toMatch(/T/);
     });
     it('--detail reports key_not_found with the list of available keys', async () => {
         const program = createProgram('', '');
@@ -793,6 +1058,42 @@ describe('browser network command', () => {
         });
     });
 });
+describe('browser console command', () => {
+    const consoleLogSpy = vi.spyOn(console, 'log').mockImplementation(() => { });
+    beforeEach(() => {
+        process.exitCode = undefined;
+        consoleLogSpy.mockClear();
+        mockBrowserConnect.mockClear();
+        mockBrowserClose.mockReset().mockResolvedValue(undefined);
+        const now = Date.now();
+        browserState.page = {
+            setActivePage: vi.fn(),
+            getActivePage: vi.fn().mockReturnValue('tab-1'),
+            tabs: vi.fn().mockResolvedValue([{ page: 'tab-1', active: true }]),
+            consoleMessages: vi.fn().mockResolvedValue([
+                { type: 'error', text: 'boom', timestamp: now },
+                { type: 'log', text: 'ok', timestamp: now },
+                { type: 'warning', text: 'old warning', timestamp: now - 180_000 },
+            ]),
+        };
+    });
+    function lastJsonLog() {
+        const calls = consoleLogSpy.mock.calls;
+        if (calls.length === 0)
+            throw new Error('Expected at least one console.log call');
+        const last = calls[calls.length - 1][0];
+        if (typeof last !== 'string')
+            throw new Error(`Expected string arg to console.log, got ${typeof last}`);
+        return JSON.parse(last);
+    }
+    it('filters console messages by level and time window', async () => {
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'console', '--level', 'error', '--since', '120s']);
+        const out = lastJsonLog();
+        expect(out.count).toBe(1);
+        expect(out.messages[0]).toMatchObject({ type: 'error', text: 'boom' });
+    });
+});
 describe('browser get html command', () => {
     const consoleLogSpy = vi.spyOn(console, 'log').mockImplementation(() => { });
     function lastLogArg() {

package/dist/src/commanderAdapter.js

@@ -16,7 +16,6 @@ import { formatRegistryHelpText } from './serialization.js';
 import { render as renderOutput } from './output.js';
 import { executeCommand, prepareCommandArgs } from './execution.js';
 import { CliError, EXIT_CODES, toEnvelope, } from './errors.js';
-import { isDiagnosticEnabled } from './diagnostic.js';
 /**
  * Register a single CliCommand as a Commander subcommand.
  */
@@ -48,6 +47,7 @@ export function registerCommandToProgram(siteCmd, cmd) {
     }
     subCmd
         .option('-f, --format <fmt>', 'Output format: table, plain, json, yaml, md, csv', 'table')
+        .option('--trace <mode>', 'Trace capture: off, on, retain-on-failure', 'off')
         .option('-v, --verbose', 'Debug output', false);
     subCmd.addHelpText('after', formatRegistryHelpText(cmd));
     subCmd.action(async (...actionArgs) => {
@@ -94,7 +94,12 @@ export function registerCommandToProgram(siteCmd, cmd) {
                 const replacement = cmd.replacedBy ? ` Use ${cmd.replacedBy} instead.` : '';
                 log.warn(`Deprecated: ${message}${replacement}`);
             }
-            const result = await executeCommand(cmd, kwargs, verbose, { prepared: true });
+            const globals = typeof subCmd.optsWithGlobals === 'function' ? subCmd.optsWithGlobals() : {};
+            const result = await executeCommand(cmd, kwargs, verbose, {
+                prepared: true,
+                ...(typeof globals.profile === 'string' && globals.profile.trim() ? { profile: globals.profile.trim() } : {}),
+                ...(typeof optionsRecord.trace === 'string' && optionsRecord.trace !== 'off' ? { trace: optionsRecord.trace } : {}),
+            });
             if (result === null || result === undefined) {
                 return;
             }
@@ -116,7 +121,7 @@ export function registerCommandToProgram(siteCmd, cmd) {
             });
         }
         catch (err) {
-            renderError(err, fullName(cmd), optionsRecord.verbose === true);
+            renderError(err, fullName(cmd), optionsRecord.verbose === true, optionsRecord.trace);
             process.exitCode = resolveExitCode(err);
         }
     });
@@ -128,13 +133,16 @@ function resolveExitCode(err) {
     return EXIT_CODES.GENERIC_ERROR;
 }
 // ── Error rendering ─────────────────────────────────────────────────────────
-/** Emit AutoFix hint for repairable adapter errors (skipped if already in diagnostic mode). */
-function emitAutoFixHint(envelope, cmdName) {
-    if (isDiagnosticEnabled())
+/** Emit AutoFix hint for repairable adapter errors (skipped if trace already exported). */
+function emitAutoFixHint(envelope, cmdName, traceMode) {
+    if (traceMode === 'on' || traceMode === 'retain-on-failure')
         return envelope;
-    return envelope + `# AutoFix: re-run with OPENCLI_DIAGNOSTIC=1 for repair context\n# OPENCLI_DIAGNOSTIC=1 ${cmdName}\n`;
+    const runnable = cmdName.replace('/', ' ');
+    return envelope
+        + `# AutoFix: re-run with --trace=retain-on-failure for trace artifact\n`
+        + `# opencli ${runnable} --trace retain-on-failure\n`;
 }
-function renderError(err, cmdName, verbose) {
+function renderError(err, cmdName, verbose, traceMode) {
     const envelope = toEnvelope(err);
     // In verbose mode, include stack trace for debugging
     if (verbose && err instanceof Error && err.stack) {
@@ -144,7 +152,7 @@ function renderError(err, cmdName, verbose) {
     // Append AutoFix hint for repairable errors
     const code = envelope.error.code;
     if (code === 'SELECTOR' || code === 'EMPTY_RESULT' || code === 'ADAPTER_LOAD' || code === 'UNKNOWN') {
-        output = emitAutoFixHint(output, cmdName);
+        output = emitAutoFixHint(output, cmdName, traceMode);
     }
     process.stderr.write(output);
 }

package/dist/src/commanderAdapter.test.js

@@ -1,6 +1,6 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 import { Command } from 'commander';
-import { EmptyResultError, SelectorError } from './errors.js';
+import { attachTraceReceipt, EmptyResultError, selectorError } from './errors.js';
 const { mockExecuteCommand, mockRenderOutput } = vi.hoisted(() => ({
     mockExecuteCommand: vi.fn(),
     mockRenderOutput: vi.fn(),
@@ -67,6 +67,13 @@ describe('commanderAdapter arg passing', () => {
             'prepare-only': 'cli',
         });
     });
+    it('passes explicit trace mode to executeCommand', async () => {
+        const program = new Command();
+        const siteCmd = program.command('paperreview');
+        registerCommandToProgram(siteCmd, cmd);
+        await program.parseAsync(['node', 'opencli', 'paperreview', 'submit', './paper.pdf', '--trace', 'retain-on-failure']);
+        expect(mockExecuteCommand).toHaveBeenCalledWith(expect.objectContaining({ site: 'paperreview', name: 'submit' }), expect.objectContaining({ pdf: './paper.pdf' }), false, { prepared: true, trace: 'retain-on-failure' });
+    });
     it('rejects invalid bool values before calling executeCommand', async () => {
         const program = new Command();
         const siteCmd = program.command('paperreview');
@@ -269,6 +276,9 @@ describe('commanderAdapter error envelope output', () => {
         expect(output).toContain('ok: false');
         expect(output).toContain('code: EMPTY_RESULT');
         expect(output).toContain('xsec_token');
+        expect(output).toContain('--trace=retain-on-failure');
+        expect(output).toContain('opencli xiaohongshu note --trace retain-on-failure');
+        expect(output).not.toContain('OPENCLI_DIAGNOSTIC');
         stderrSpy.mockRestore();
     });
     it('outputs YAML error envelope for selector errors', async () => {
@@ -276,12 +286,67 @@ describe('commanderAdapter error envelope output', () => {
         const siteCmd = program.command('xiaohongshu');
         registerCommandToProgram(siteCmd, cmd);
         const stderrSpy = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
-        mockExecuteCommand.mockRejectedValueOnce(new SelectorError('.note-title', 'The note title selector no longer matches the current page.'));
+        mockExecuteCommand.mockRejectedValueOnce(selectorError('.note-title', 'The note title selector no longer matches the current page.'));
         await program.parseAsync(['node', 'opencli', 'xiaohongshu', 'note', '69ca3927000000001a020fd5']);
         const output = stderrSpy.mock.calls.map(c => String(c[0])).join('');
         expect(output).toContain('ok: false');
         expect(output).toContain('code: SELECTOR');
         expect(output).toContain('selector no longer matches');
+        expect(output).toContain('--trace=retain-on-failure');
+        stderrSpy.mockRestore();
+    });
+    it('does not add an AutoFix rerun hint when trace is already enabled', async () => {
+        const program = new Command();
+        const siteCmd = program.command('xiaohongshu');
+        registerCommandToProgram(siteCmd, cmd);
+        const stderrSpy = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+        mockExecuteCommand.mockRejectedValueOnce(selectorError('.note-title'));
+        await program.parseAsync([
+            'node',
+            'opencli',
+            'xiaohongshu',
+            'note',
+            '69ca3927000000001a020fd5',
+            '--trace',
+            'retain-on-failure',
+        ]);
+        const output = stderrSpy.mock.calls.map(c => String(c[0])).join('');
+        expect(output).toContain('code: SELECTOR');
+        expect(output).not.toContain('AutoFix: re-run');
+        stderrSpy.mockRestore();
+    });
+    it('includes trace metadata from the error envelope when execution attached it', async () => {
+        const program = new Command();
+        const siteCmd = program.command('xiaohongshu');
+        registerCommandToProgram(siteCmd, cmd);
+        const stderrSpy = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+        const err = selectorError('.note-title');
+        attachTraceReceipt(err, {
+            schemaVersion: 1,
+            opencliVersion: '1.7.8',
+            traceId: 'trace-1',
+            traceDir: '/tmp/opencli/profiles/default/traces/trace-1',
+            summaryPath: '/tmp/opencli/profiles/default/traces/trace-1/summary.md',
+            receiptPath: '/tmp/opencli/profiles/default/traces/trace-1/receipt.json',
+            status: 'failure',
+            createdAt: '2026-05-03T00:00:00.000Z',
+            error: { code: 'SELECTOR', message: 'Could not find element: .note-title' },
+        });
+        mockExecuteCommand.mockRejectedValueOnce(err);
+        await program.parseAsync([
+            'node',
+            'opencli',
+            'xiaohongshu',
+            'note',
+            '69ca3927000000001a020fd5',
+            '--trace',
+            'retain-on-failure',
+        ]);
+        const output = stderrSpy.mock.calls.map(c => String(c[0])).join('');
+        expect(output).toContain('trace:');
+        expect(output).toContain('dir: /tmp/opencli/profiles/default/traces/trace-1');
+        expect(output).toContain('summaryPath: /tmp/opencli/profiles/default/traces/trace-1/summary.md');
+        expect(output).toContain('receiptPath: /tmp/opencli/profiles/default/traces/trace-1/receipt.json');
         stderrSpy.mockRestore();
     });
 });

package/dist/src/commands/daemon.d.ts

@@ -2,6 +2,8 @@
  * CLI commands for daemon lifecycle:
  *   opencli daemon status — show daemon state
  *   opencli daemon stop   — graceful shutdown
+ *   opencli daemon restart — graceful shutdown, then start a fresh daemon
  */
 export declare function daemonStatus(): Promise<void>;
 export declare function daemonStop(): Promise<void>;
+export declare function daemonRestart(): Promise<void>;

package/dist/src/commands/daemon.js

@@ -2,11 +2,15 @@
  * CLI commands for daemon lifecycle:
  *   opencli daemon status — show daemon state
  *   opencli daemon stop   — graceful shutdown
+ *   opencli daemon restart — graceful shutdown, then start a fresh daemon
  */
 import { styleText } from 'node:util';
 import { fetchDaemonStatus, requestDaemonShutdown } from '../browser/daemon-client.js';
+import { restartDaemon } from '../browser/daemon-lifecycle.js';
 import { formatDuration } from '../download/progress.js';
 import { log } from '../logger.js';
+import { PKG_VERSION } from '../version.js';
+import { formatDaemonVersion, isDaemonStale } from '../browser/daemon-version.js';
 export async function daemonStatus() {
     const status = await fetchDaemonStatus();
     if (!status) {
@@ -18,9 +22,18 @@ export async function daemonStatus() {
         : status.extensionVersion
             ? `${styleText('green', 'connected')} ${styleText('dim', `(v${status.extensionVersion})`)}`
             : `${styleText('yellow', 'connected')} ${styleText('dim', '(version unknown)')}`;
-    console.log(`Daemon: ${styleText('green', 'running')} (PID ${status.pid})`);
+    const daemonVersion = formatDaemonVersion(status);
+    const stale = isDaemonStale(status, PKG_VERSION);
+    console.log(`Daemon: ${stale ? styleText('yellow', 'stale') : styleText('green', 'running')} (PID ${status.pid})`);
+    console.log(`Version: ${daemonVersion}${stale ? styleText('yellow', ` (CLI v${PKG_VERSION}; run: opencli daemon restart)`) : ''}`);
     console.log(`Uptime: ${formatDuration(Math.round(status.uptime * 1000))}`);
     console.log(`Extension: ${extensionLabel}`);
+    if (status.profiles && status.profiles.length > 0) {
+        console.log(`Profiles: ${status.profiles.map((profile) => {
+            const version = profile.extensionVersion ? ` v${profile.extensionVersion}` : '';
+            return `${profile.contextId}${version}`;
+        }).join(', ')}`);
+    }
     console.log(`Memory: ${status.memoryMB} MB`);
     console.log(`Port: ${status.port}`);
 }
@@ -39,3 +52,31 @@ export async function daemonStop() {
         process.exitCode = 1;
     }
 }
+export async function daemonRestart() {
+    const before = await fetchDaemonStatus();
+    if (before?.profiles && before.profiles.length > 0) {
+        log.warn(`Restarting daemon will disconnect ${before.profiles.length} browser profile(s); the extension should reconnect automatically.`);
+    }
+    const result = await restartDaemon();
+    if (!result.stopped) {
+        log.error('Failed to stop daemon before restart.');
+        process.exitCode = 1;
+        return;
+    }
+    if (!result.status) {
+        log.error('Daemon restart timed out before the new daemon reported status.');
+        process.exitCode = 1;
+        return;
+    }
+    const action = result.previousStatus ? 'restarted' : 'started';
+    const version = formatDaemonVersion(result.status);
+    log.success(`Daemon ${action} on port ${result.status.port} (${version}).`);
+    if (result.status.extensionConnected) {
+        const profiles = result.status.profiles?.length ?? 0;
+        const profileText = profiles > 0 ? `; profiles connected: ${profiles}` : '';
+        log.status(`Extension connected${profileText}.`);
+    }
+    else {
+        log.warn('Daemon is running, but the Browser Bridge extension has not connected yet.');
+    }
+}