@jackwener/opencli 1.7.9 → 1.7.11

package/dist/src/cli.test.js

@@ -4,11 +4,13 @@ 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, mockBindTab, mockSendCommand, 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', () => {
@@ -28,6 +30,13 @@ vi.mock('./browser/daemon-client.js', async () => {
         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', () => {
@@ -109,6 +118,149 @@ describe('selectFreshByTimestamp', () => {
         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 });
+        }
+    });
+    it('uses --seed-args when no fixture args exist', async () => {
+        const originalHome = process.env.HOME;
+        const originalUserProfile = process.env.USERPROFILE;
+        const fakeHome = fs.mkdtempSync(path.join(os.tmpdir(), 'opencli-browser-verify-seed-'));
+        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', '--seed-args', 'opencli-verify']);
+            expect(mockExecFileSync).toHaveBeenCalledTimes(1);
+            const [, execArgs] = mockExecFileSync.mock.calls[0];
+            expect(execArgs.slice(-5)).toEqual(['hn', 'top', 'opencli-verify', '--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 });
+        }
+    });
+    it('writes --seed-args into a starter fixture', async () => {
+        const originalHome = process.env.HOME;
+        const originalUserProfile = process.env.USERPROFILE;
+        const fakeHome = fs.mkdtempSync(path.join(os.tmpdir(), 'opencli-browser-verify-write-seed-'));
+        process.env.HOME = fakeHome;
+        process.env.USERPROFILE = fakeHome;
+        mockExecFileSync.mockReturnValue(JSON.stringify([{ title: 'ok' }]));
+        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', '--write-fixture', '--seed-args', 'opencli-verify']);
+            const fixtureFile = path.join(fakeHome, '.opencli', 'sites', 'hn', 'verify', 'top.json');
+            const fixture = JSON.parse(fs.readFileSync(fixtureFile, 'utf-8'));
+            expect(fixture.args).toEqual(['opencli-verify']);
+            expect(fixture.expect.columns).toEqual(['title']);
+        }
+        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);

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,7 +22,10 @@ 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) {
@@ -45,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.');
+    }
+}

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

@@ -1,13 +1,18 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-const { fetchDaemonStatusMock, requestDaemonShutdownMock, } = vi.hoisted(() => ({
+const { fetchDaemonStatusMock, requestDaemonShutdownMock, restartDaemonMock, } = vi.hoisted(() => ({
     fetchDaemonStatusMock: vi.fn(),
     requestDaemonShutdownMock: vi.fn(),
+    restartDaemonMock: vi.fn(),
 }));
 vi.mock('../browser/daemon-client.js', () => ({
     fetchDaemonStatus: fetchDaemonStatusMock,
     requestDaemonShutdown: requestDaemonShutdownMock,
 }));
-import { daemonStatus, daemonStop } from './daemon.js';
+vi.mock('../browser/daemon-lifecycle.js', () => ({
+    restartDaemon: restartDaemonMock,
+}));
+import { daemonRestart, daemonStatus, daemonStop } from './daemon.js';
+import { PKG_VERSION } from '../version.js';
 describe('daemonStatus', () => {
     let stdoutSpy;
     beforeEach(() => {
@@ -28,6 +33,7 @@ describe('daemonStatus', () => {
             ok: true,
             pid: 12345,
             uptime: 3661,
+            daemonVersion: PKG_VERSION,
             extensionConnected: true,
             extensionVersion: '1.6.8',
             pending: 0,
@@ -37,6 +43,7 @@ describe('daemonStatus', () => {
         await daemonStatus();
         expect(stdoutSpy).toHaveBeenCalledWith(expect.stringContaining('running'));
         expect(stdoutSpy).toHaveBeenCalledWith(expect.stringContaining('PID 12345'));
+        expect(stdoutSpy).toHaveBeenCalledWith(expect.stringContaining(`v${PKG_VERSION}`));
         expect(stdoutSpy).toHaveBeenCalledWith(expect.stringContaining('1h 1m'));
         expect(stdoutSpy).toHaveBeenCalledWith(expect.stringContaining('connected'));
         expect(stdoutSpy).toHaveBeenCalledWith(expect.stringContaining('v1.6.8'));
@@ -48,6 +55,7 @@ describe('daemonStatus', () => {
             ok: true,
             pid: 99,
             uptime: 120,
+            daemonVersion: PKG_VERSION,
             extensionConnected: false,
             pending: 0,
             memoryMB: 32,
@@ -61,6 +69,7 @@ describe('daemonStatus', () => {
             ok: true,
             pid: 99,
             uptime: 120,
+            daemonVersion: PKG_VERSION,
             extensionConnected: true,
             extensionVersion: undefined,
             pending: 0,
@@ -91,6 +100,7 @@ describe('daemonStop', () => {
             ok: true,
             pid: 12345,
             uptime: 100,
+            daemonVersion: PKG_VERSION,
             extensionConnected: true,
             pending: 0,
             memoryMB: 50,
@@ -106,6 +116,7 @@ describe('daemonStop', () => {
             ok: true,
             pid: 12345,
             uptime: 100,
+            daemonVersion: PKG_VERSION,
             extensionConnected: true,
             pending: 0,
             memoryMB: 50,
@@ -116,3 +127,93 @@ describe('daemonStop', () => {
         expect(stderrSpy).toHaveBeenCalledWith(expect.stringContaining('Failed to stop daemon'));
     });
 });
+describe('daemonRestart', () => {
+    let stderrSpy;
+    beforeEach(() => {
+        stderrSpy = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+        fetchDaemonStatusMock.mockReset();
+        requestDaemonShutdownMock.mockReset();
+        restartDaemonMock.mockReset();
+        process.exitCode = undefined;
+    });
+    afterEach(() => {
+        vi.restoreAllMocks();
+        process.exitCode = undefined;
+    });
+    it('restarts a running daemon and reports the new version', async () => {
+        fetchDaemonStatusMock.mockResolvedValue({
+            ok: true,
+            pid: 12345,
+            uptime: 100,
+            daemonVersion: '1.7.6',
+            extensionConnected: true,
+            profiles: [{ contextId: 'work', extensionConnected: true, pending: 0 }],
+            pending: 0,
+            memoryMB: 50,
+            port: 19825,
+        });
+        restartDaemonMock.mockResolvedValue({
+            previousStatus: { daemonVersion: '1.7.6' },
+            stopped: true,
+            spawned: true,
+            status: {
+                ok: true,
+                pid: 12346,
+                uptime: 1,
+                daemonVersion: PKG_VERSION,
+                extensionConnected: true,
+                profiles: [{ contextId: 'work', extensionConnected: true, pending: 0 }],
+                pending: 0,
+                memoryMB: 51,
+                port: 19825,
+            },
+        });
+        await daemonRestart();
+        expect(restartDaemonMock).toHaveBeenCalledTimes(1);
+        expect(stderrSpy).toHaveBeenCalledWith(expect.stringContaining('will disconnect 1 browser profile'));
+        expect(stderrSpy).toHaveBeenCalledWith(expect.stringContaining(`Daemon restarted on port 19825 (v${PKG_VERSION})`));
+        expect(stderrSpy).toHaveBeenCalledWith(expect.stringContaining('Extension connected; profiles connected: 1'));
+    });
+    it('starts a new daemon when none was running', async () => {
+        fetchDaemonStatusMock.mockResolvedValue(null);
+        restartDaemonMock.mockResolvedValue({
+            previousStatus: null,
+            stopped: true,
+            spawned: true,
+            status: {
+                ok: true,
+                pid: 12346,
+                uptime: 1,
+                daemonVersion: PKG_VERSION,
+                extensionConnected: false,
+                pending: 0,
+                memoryMB: 51,
+                port: 19825,
+            },
+        });
+        await daemonRestart();
+        expect(stderrSpy).toHaveBeenCalledWith(expect.stringContaining(`Daemon started on port 19825 (v${PKG_VERSION})`));
+        expect(stderrSpy).toHaveBeenCalledWith(expect.stringContaining('extension has not connected yet'));
+    });
+    it('reports failure when the daemon cannot stop', async () => {
+        fetchDaemonStatusMock.mockResolvedValue({
+            ok: true,
+            pid: 12345,
+            uptime: 100,
+            daemonVersion: '1.7.6',
+            extensionConnected: true,
+            pending: 0,
+            memoryMB: 50,
+            port: 19825,
+        });
+        restartDaemonMock.mockResolvedValue({
+            previousStatus: { daemonVersion: '1.7.6' },
+            status: { daemonVersion: '1.7.6' },
+            stopped: false,
+            spawned: false,
+        });
+        await daemonRestart();
+        expect(stderrSpy).toHaveBeenCalledWith(expect.stringContaining('Failed to stop daemon before restart'));
+        expect(process.exitCode).toBe(1);
+    });
+});

package/dist/src/doctor.d.ts

@@ -5,6 +5,7 @@
  */
 import type { BrowserSessionInfo } from './types.js';
 import type { BrowserProfileStatus } from './browser/daemon-client.js';
+import { type AdapterShadow } from './adapter-shadow.js';
 export type DoctorOptions = {
     yes?: boolean;
     live?: boolean;
@@ -20,6 +21,7 @@ export type DoctorReport = {
     cliVersion?: string;
     daemonRunning: boolean;
     daemonFlaky?: boolean;
+    daemonStale?: boolean;
     daemonVersion?: string;
     extensionConnected: boolean;
     extensionFlaky?: boolean;
@@ -28,6 +30,7 @@ export type DoctorReport = {
     connectivity?: ConnectivityResult;
     sessions?: BrowserSessionInfo[];
     profiles?: BrowserProfileStatus[];
+    adapterShadows?: AdapterShadow[];
     issues: string[];
 };
 /**

package/dist/src/doctor.js

@@ -11,6 +11,8 @@ import { getErrorMessage } from './errors.js';
 import { getRuntimeLabel } from './runtime-detect.js';
 import { getCachedLatestExtensionVersion } from './update-check.js';
 import { aliasForContextId, loadProfileConfig } from './browser/profile.js';
+import { formatDaemonVersion, isDaemonStale, staleDaemonIssue } from './browser/daemon-version.js';
+import { findShadowedUserAdapters, formatAdapterShadowIssue } from './adapter-shadow.js';
 const DOCTOR_LIVE_TIMEOUT_SECONDS = 8;
 /** Parse a semver string into [major, minor, patch]. Returns null on invalid input. */
 function parseSemver(v) {
@@ -90,6 +92,7 @@ export async function runBrowserDoctor(opts = {}) {
     const extensionConnected = health.state === 'ready';
     const daemonFlaky = !!(connectivity?.ok && !daemonRunning);
     const extensionFlaky = !!(connectivity?.ok && daemonRunning && !extensionConnected);
+    const daemonStale = isDaemonStale(health.status, opts.cliVersion);
     const profiles = health.status?.profiles;
     let sessions;
     if (opts.sessions) {
@@ -105,6 +108,7 @@ export async function runBrowserDoctor(opts = {}) {
         }
     }
     const extensionVersion = health.status?.extensionVersion;
+    const adapterShadows = findShadowedUserAdapters();
     const issues = [];
     if (daemonFlaky) {
         issues.push('Daemon connectivity is unstable. The live browser test succeeded, but the daemon was no longer running immediately afterward.\n' +
@@ -113,6 +117,9 @@ export async function runBrowserDoctor(opts = {}) {
     else if (!daemonRunning) {
         issues.push('Daemon is not running. It should start automatically when you run an opencli browser command.');
     }
+    if (daemonStale && opts.cliVersion) {
+        issues.push(staleDaemonIssue(health.status, opts.cliVersion));
+    }
     if (extensionFlaky) {
         issues.push('Extension connection is unstable. The live browser test succeeded, but the daemon reported the extension disconnected immediately afterward.\n' +
             'This usually means the Browser Bridge service worker is reconnecting slowly or Chrome suspended it.');
@@ -127,24 +134,12 @@ export async function runBrowserDoctor(opts = {}) {
                 '  Open that Chrome profile and make sure the OpenCLI extension is enabled.');
         }
         else {
-            const daemonVersion = health.status?.daemonVersion;
-            const isStale = opts.cliVersion && (!daemonVersion || daemonVersion !== opts.cliVersion);
-            if (isStale) {
-                const reason = daemonVersion
-                    ? `daemon v${daemonVersion} ≠ CLI v${opts.cliVersion}`
-                    : `daemon predates version reporting, CLI is v${opts.cliVersion}`;
-                issues.push(`Stale daemon detected: ${reason}.\n` +
-                    'The daemon was started by an older CLI version and may have missed the extension registration.\n' +
-                    '  Quick fix: opencli daemon stop && opencli doctor');
-            }
-            else {
-                issues.push('Daemon is running but the Chrome/Chromium extension is not connected.\n' +
-                    'If the extension is already installed, try: opencli daemon stop && opencli doctor\n' +
-                    'If the extension is not installed:\n' +
-                    '  1. Download from https://github.com/jackwener/opencli/releases\n' +
-                    '  2. Open chrome://extensions/ → Enable Developer Mode\n' +
-                    '  3. Click "Load unpacked" → select the extension folder');
-            }
+            issues.push('Daemon is running but the Chrome/Chromium extension is not connected.\n' +
+                'If the extension is already installed, try: opencli daemon restart\n' +
+                'If the extension is not installed:\n' +
+                '  1. Download from https://github.com/jackwener/opencli/releases\n' +
+                '  2. Open chrome://extensions/ → Enable Developer Mode\n' +
+                '  3. Click "Load unpacked" → select the extension folder');
         }
     }
     if (extensionConnected && !extensionVersion) {
@@ -178,10 +173,14 @@ export async function runBrowserDoctor(opts = {}) {
         issues.push(`Extension update available: v${extensionVersion} → v${latestExtensionVersion}\n` +
             '  Download from: https://github.com/jackwener/opencli/releases');
     }
+    if (adapterShadows.length > 0) {
+        issues.push(formatAdapterShadowIssue(adapterShadows));
+    }
     return {
         cliVersion: opts.cliVersion,
         daemonRunning,
         daemonFlaky,
+        daemonStale,
         daemonVersion: health.status?.daemonVersion,
         extensionConnected,
         extensionFlaky,
@@ -190,6 +189,7 @@ export async function runBrowserDoctor(opts = {}) {
         connectivity,
         sessions,
         profiles,
+        adapterShadows,
         issues,
     };
 }
@@ -198,10 +198,16 @@ export function renderBrowserDoctorReport(report) {
     // Daemon status
     const daemonIcon = report.daemonFlaky
         ? styleText('yellow', '[WARN]')
-        : report.daemonRunning ? styleText('green', '[OK]') : styleText('red', '[MISSING]');
+        : report.daemonStale
+            ? styleText('yellow', '[WARN]')
+            : report.daemonRunning ? styleText('green', '[OK]') : styleText('red', '[MISSING]');
     const daemonLabel = report.daemonFlaky
         ? 'unstable (running during live check, then stopped)'
-        : report.daemonRunning ? `running on port ${DEFAULT_DAEMON_PORT}` + (report.daemonVersion ? ` (v${report.daemonVersion})` : '') : 'not running';
+        : report.daemonRunning
+            ? `running on port ${DEFAULT_DAEMON_PORT} (${report.daemonStale
+                ? `${formatDaemonVersion(report)}, stale; CLI v${report.cliVersion ?? 'unknown'}`
+                : formatDaemonVersion(report)})`
+            : 'not running';
     lines.push(`${daemonIcon} Daemon: ${daemonLabel}`);
     // Extension status
     const extIcon = report.extensionFlaky || (report.extensionConnected && !report.extensionVersion)
@@ -279,6 +285,7 @@ export function renderBrowserDoctorReport(report) {
     }
     else if (report.daemonRunning && report.extensionConnected) {
         lines.push('', styleText('green', 'Everything looks good!'));
+        lines.push(styleText('dim', 'Tip: writing a new adapter? Run `opencli browser analyze <url>` for one-shot site recon.'));
     }
     return lines.join('\n');
 }

package/dist/src/doctor.test.js

@@ -1,9 +1,10 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest';
-const { mockGetDaemonHealth, mockListSessions, mockConnect, mockClose } = vi.hoisted(() => ({
+const { mockGetDaemonHealth, mockListSessions, mockConnect, mockClose, mockFindShadowedUserAdapters } = vi.hoisted(() => ({
     mockGetDaemonHealth: vi.fn(),
     mockListSessions: vi.fn(),
     mockConnect: vi.fn(),
     mockClose: vi.fn(),
+    mockFindShadowedUserAdapters: vi.fn(),
 }));
 vi.mock('./browser/daemon-client.js', () => ({
     getDaemonHealth: mockGetDaemonHealth,
@@ -15,22 +16,48 @@ vi.mock('./browser/index.js', () => ({
         close = mockClose;
     },
 }));
+vi.mock('./adapter-shadow.js', async () => {
+    const actual = await vi.importActual('./adapter-shadow.js');
+    return {
+        ...actual,
+        findShadowedUserAdapters: mockFindShadowedUserAdapters,
+    };
+});
 import { renderBrowserDoctorReport, runBrowserDoctor } from './doctor.js';
 describe('doctor report rendering', () => {
     const strip = (s) => s.replace(/\x1b\[[0-9;]*m/g, '');
     beforeEach(() => {
         vi.clearAllMocks();
+        mockFindShadowedUserAdapters.mockReturnValue([]);
     });
     it('renders OK-style report when daemon and extension connected', () => {
         const text = strip(renderBrowserDoctorReport({
+            cliVersion: '1.7.9',
             daemonRunning: true,
+            daemonVersion: '1.7.9',
             extensionConnected: true,
             extensionVersion: '1.6.8',
             issues: [],
         }));
         expect(text).toContain('[OK] Daemon: running on port 19825');
+        expect(text).toContain('(v1.7.9)');
         expect(text).toContain('[OK] Extension: connected (v1.6.8)');
         expect(text).toContain('Everything looks good!');
+        expect(text).toContain('opencli browser analyze <url>');
+    });
+    it('renders a warning when daemon version is stale', () => {
+        const text = strip(renderBrowserDoctorReport({
+            cliVersion: '1.7.9',
+            daemonRunning: true,
+            daemonVersion: '1.7.6',
+            daemonStale: true,
+            extensionConnected: true,
+            extensionVersion: '1.0.3',
+            issues: ['Stale daemon detected: daemon v1.7.6 != CLI v1.7.9.\n  Run: opencli daemon restart'],
+        }));
+        expect(text).toContain('[WARN] Daemon: running on port 19825 (v1.7.6, stale; CLI v1.7.9)');
+        expect(text).toContain('Run: opencli daemon restart');
+        expect(text).not.toContain('Everything looks good!');
     });
     it('renders MISSING when daemon not running', () => {
         const text = strip(renderBrowserDoctorReport({
@@ -238,6 +265,49 @@ describe('doctor report rendering', () => {
             expect.stringContaining('did not report a version'),
         ]));
     });
+    it('reports an issue when daemon version differs from CLI version', async () => {
+        const status = {
+            state: 'ready',
+            status: {
+                daemonVersion: '1.7.6',
+                extensionConnected: true,
+                extensionVersion: '1.0.3',
+            },
+        };
+        mockGetDaemonHealth
+            .mockResolvedValueOnce(status)
+            .mockResolvedValueOnce(status);
+        const report = await runBrowserDoctor({ live: false, cliVersion: '1.7.9' });
+        expect(report.daemonStale).toBe(true);
+        expect(report.issues).toEqual(expect.arrayContaining([
+            expect.stringContaining('Stale daemon detected: daemon v1.7.6 != CLI v1.7.9'),
+        ]));
+    });
+    it('reports local adapter shadows as a warning issue', async () => {
+        const status = {
+            state: 'ready',
+            status: {
+                daemonVersion: '1.7.9',
+                extensionConnected: true,
+                extensionVersion: '1.0.3',
+            },
+        };
+        mockGetDaemonHealth
+            .mockResolvedValueOnce(status)
+            .mockResolvedValueOnce(status);
+        mockFindShadowedUserAdapters.mockReturnValueOnce([
+            {
+                name: 'instagram/saved',
+                userPath: '/home/me/.opencli/clis/instagram/saved.js',
+                builtinPath: '/pkg/clis/instagram/saved.js',
+            },
+        ]);
+        const report = await runBrowserDoctor({ live: false, cliVersion: '1.7.9' });
+        expect(report.adapterShadows).toHaveLength(1);
+        expect(report.issues).toEqual(expect.arrayContaining([
+            expect.stringContaining('Local adapter overrides shadow packaged adapters'),
+        ]));
+    });
     it('reports profile-required when multiple profiles are connected without a selection', async () => {
         const status = {
             state: 'profile-required',