@jackwener/opencli 1.7.8 → 1.7.9

package/dist/src/daemon.js

@@ -25,19 +25,96 @@ import { DEFAULT_DAEMON_PORT } from './constants.js';
 import { EXIT_CODES } from './errors.js';
 import { log } from './logger.js';
 import { PKG_VERSION } from './version.js';
+import { DEFAULT_CONTEXT_ID } from './browser/profile.js';
+import { recordExtensionVersion } from './update-check.js';
 const PORT = parseInt(process.env.OPENCLI_DAEMON_PORT ?? String(DEFAULT_DAEMON_PORT), 10);
-// ─── State ───────────────────────────────────────────────────────────
-let extensionWs = null;
-let extensionVersion = null;
-let extensionCompatRange = null;
+const extensionProfiles = new Map();
 const pending = new Map();
 const LOG_BUFFER_SIZE = 200;
 const logBuffer = [];
+class DaemonCommandFailure extends Error {
+    errorCode;
+    errorHint;
+    status;
+    constructor(message, errorCode, errorHint, status = 400) {
+        super(message);
+        this.errorCode = errorCode;
+        this.errorHint = errorHint;
+        this.status = status;
+        this.name = 'DaemonCommandFailure';
+    }
+}
 function pushLog(entry) {
     logBuffer.push(entry);
     if (logBuffer.length > LOG_BUFFER_SIZE)
         logBuffer.shift();
 }
+function activeProfiles() {
+    return [...extensionProfiles.values()].filter((entry) => entry.ws.readyState === WebSocket.OPEN);
+}
+function resolveExtensionConnection(contextId) {
+    const requestedContextId = typeof contextId === 'string' && contextId.trim() ? contextId.trim() : undefined;
+    if (requestedContextId) {
+        const connection = extensionProfiles.get(requestedContextId);
+        if (connection?.ws.readyState === WebSocket.OPEN)
+            return { connection };
+        return {
+            errorCode: 'profile_disconnected',
+            error: `Browser profile "${requestedContextId}" is not connected.`,
+            errorHint: 'Open that Chrome profile and make sure the OpenCLI extension is enabled, or choose another profile with opencli profile use <name>.',
+        };
+    }
+    const connected = activeProfiles();
+    if (connected.length === 1)
+        return { connection: connected[0] };
+    if (connected.length > 1) {
+        return {
+            errorCode: 'profile_required',
+            error: 'Multiple Browser Bridge profiles are connected; choose one with --profile.',
+            errorHint: 'Run opencli profile list, then use opencli --profile <name> ... or opencli profile use <name>.',
+        };
+    }
+    return {
+        errorCode: 'extension_not_connected',
+        error: 'Extension not connected. Please install the opencli Browser Bridge extension.',
+    };
+}
+function registerExtensionConnection(ws, rawContextId) {
+    const contextId = typeof rawContextId === 'string' && rawContextId.trim()
+        ? rawContextId.trim()
+        : DEFAULT_CONTEXT_ID;
+    const previous = extensionProfiles.get(contextId);
+    if (previous && previous.ws !== ws) {
+        previous.ws.close();
+    }
+    const existing = [...extensionProfiles.entries()].find(([, entry]) => entry.ws === ws);
+    if (existing && existing[0] !== contextId)
+        extensionProfiles.delete(existing[0]);
+    const current = extensionProfiles.get(contextId);
+    const connection = {
+        contextId,
+        ws,
+        extensionVersion: current?.ws === ws ? current.extensionVersion : null,
+        extensionCompatRange: current?.ws === ws ? current.extensionCompatRange : null,
+        lastSeenAt: Date.now(),
+    };
+    extensionProfiles.set(contextId, connection);
+    return connection;
+}
+function unregisterExtensionConnection(ws) {
+    for (const [contextId, connection] of extensionProfiles.entries()) {
+        if (connection.ws !== ws)
+            continue;
+        extensionProfiles.delete(contextId);
+        for (const [id, p] of pending) {
+            if (p.contextId !== contextId)
+                continue;
+            clearTimeout(p.timer);
+            p.reject(new DaemonCommandFailure(`Browser profile "${contextId}" disconnected`, 'profile_disconnected', 'Open that Chrome profile and make sure the OpenCLI extension is enabled, or choose another profile with opencli profile use <name>.', 503));
+            pending.delete(id);
+        }
+    }
+}
 // ─── HTTP Server ─────────────────────────────────────────────────────
 const MAX_BODY = 1024 * 1024; // 1 MB — commands are tiny; this prevents OOM
 function readBody(req) {
@@ -118,14 +195,29 @@ async function handleRequest(req, res) {
     if (req.method === 'GET' && pathname === '/status') {
         const uptime = process.uptime();
         const mem = process.memoryUsage();
+        const params = new URL(url, `http://localhost:${PORT}`).searchParams;
+        const requestedContextId = params.get('contextId')?.trim() || undefined;
+        const route = resolveExtensionConnection(requestedContextId);
+        const profiles = activeProfiles().map((profile) => ({
+            contextId: profile.contextId,
+            extensionConnected: true,
+            extensionVersion: profile.extensionVersion ?? undefined,
+            extensionCompatRange: profile.extensionCompatRange ?? undefined,
+            pending: [...pending.values()].filter((entry) => entry.contextId === profile.contextId).length,
+            lastSeenAt: profile.lastSeenAt,
+        }));
         jsonResponse(res, 200, {
             ok: true,
             pid: process.pid,
             uptime,
             daemonVersion: PKG_VERSION,
-            extensionConnected: extensionWs?.readyState === WebSocket.OPEN,
-            extensionVersion,
-            extensionCompatRange,
+            extensionConnected: !!route.connection,
+            extensionVersion: route.connection?.extensionVersion ?? undefined,
+            extensionCompatRange: route.connection?.extensionCompatRange ?? undefined,
+            contextId: route.connection?.contextId ?? requestedContextId,
+            profileRequired: route.errorCode === 'profile_required',
+            profileDisconnected: route.errorCode === 'profile_disconnected',
+            profiles,
             pending: pending.size,
             memoryMB: Math.round(mem.rss / 1024 / 1024 * 10) / 10,
             port: PORT,
@@ -158,8 +250,15 @@ async function handleRequest(req, res) {
                 jsonResponse(res, 400, { ok: false, error: 'Missing command id' });
                 return;
             }
-            if (!extensionWs || extensionWs.readyState !== WebSocket.OPEN) {
-                jsonResponse(res, 503, { id: body.id, ok: false, error: 'Extension not connected. Please install the opencli Browser Bridge extension.' });
+            const route = resolveExtensionConnection(typeof body.contextId === 'string' ? body.contextId : undefined);
+            if (!route.connection) {
+                jsonResponse(res, route.errorCode === 'profile_required' ? 409 : 503, {
+                    id: body.id,
+                    ok: false,
+                    errorCode: route.errorCode,
+                    error: route.error,
+                    ...(route.errorHint ? { errorHint: route.errorHint } : {}),
+                });
                 return;
             }
             const timeoutMs = typeof body.timeout === 'number' && body.timeout > 0
@@ -178,15 +277,18 @@ async function handleRequest(req, res) {
                     pending.delete(body.id);
                     reject(new Error(`Command timeout (${timeoutMs / 1000}s)`));
                 }, timeoutMs);
-                pending.set(body.id, { resolve, reject, timer });
-                extensionWs.send(JSON.stringify(body));
+                pending.set(body.id, { contextId: route.connection.contextId, resolve, reject, timer });
+                route.connection.ws.send(JSON.stringify(body));
             });
             jsonResponse(res, 200, result);
         }
         catch (err) {
-            jsonResponse(res, err instanceof Error && err.message.includes('timeout') ? 408 : 400, {
+            const commandFailure = err instanceof DaemonCommandFailure ? err : null;
+            jsonResponse(res, commandFailure?.status ?? (err instanceof Error && err.message.includes('timeout') ? 408 : 400), {
                 ok: false,
                 error: err instanceof Error ? err.message : 'Invalid request',
+                ...(commandFailure?.errorCode ? { errorCode: commandFailure.errorCode } : {}),
+                ...(commandFailure?.errorHint ? { errorHint: commandFailure.errorHint } : {}),
             });
         }
         return;
@@ -209,9 +311,6 @@ const wss = new WebSocketServer({
 });
 wss.on('connection', (ws) => {
     log.info('[daemon] Extension connected');
-    extensionWs = ws;
-    extensionVersion = null; // cleared until hello message arrives
-    extensionCompatRange = null;
     // ── Heartbeat: ping every 15s, close if 2 pongs missed ──
     let missedPongs = 0;
     const heartbeatInterval = setInterval(() => {
@@ -236,8 +335,13 @@ wss.on('connection', (ws) => {
             const msg = JSON.parse(data.toString());
             // Handle hello message from extension (version handshake)
             if (msg.type === 'hello') {
-                extensionVersion = typeof msg.version === 'string' ? msg.version : null;
-                extensionCompatRange = typeof msg.compatRange === 'string' ? msg.compatRange : null;
+                const connection = registerExtensionConnection(ws, msg.contextId);
+                connection.extensionVersion = typeof msg.version === 'string' ? msg.version : null;
+                connection.extensionCompatRange = typeof msg.compatRange === 'string' ? msg.compatRange : null;
+                connection.lastSeenAt = Date.now();
+                if (connection.extensionVersion)
+                    recordExtensionVersion(connection.extensionVersion);
+                log.info(`[daemon] Extension profile connected: ${connection.contextId}`);
                 return;
             }
             // Handle log messages from extension
@@ -266,31 +370,11 @@ wss.on('connection', (ws) => {
     ws.on('close', () => {
         log.info('[daemon] Extension disconnected');
         clearInterval(heartbeatInterval);
-        if (extensionWs === ws) {
-            extensionWs = null;
-            extensionVersion = null;
-            extensionCompatRange = null;
-            // Reject all pending requests since the extension is gone
-            for (const [id, p] of pending) {
-                clearTimeout(p.timer);
-                p.reject(new Error('Extension disconnected'));
-            }
-            pending.clear();
-        }
+        unregisterExtensionConnection(ws);
     });
     ws.on('error', () => {
         clearInterval(heartbeatInterval);
-        if (extensionWs === ws) {
-            extensionWs = null;
-            extensionVersion = null;
-            extensionCompatRange = null;
-            // Reject pending requests in case 'close' does not follow this 'error'
-            for (const [, p] of pending) {
-                clearTimeout(p.timer);
-                p.reject(new Error('Extension disconnected'));
-            }
-            pending.clear();
-        }
+        unregisterExtensionConnection(ws);
     });
 });
 // ─── Start ───────────────────────────────────────────────────────────
@@ -313,8 +397,8 @@ function shutdown() {
         p.reject(new Error('Daemon shutting down'));
     }
     pending.clear();
-    if (extensionWs)
-        extensionWs.close();
+    for (const profile of extensionProfiles.values())
+        profile.ws.close();
     httpServer.close();
     process.exit(EXIT_CODES.SUCCESS);
 }

package/dist/src/doctor.d.ts

@@ -3,6 +3,8 @@
  *
  * Simplified for the daemon-based architecture.
  */
+import type { BrowserSessionInfo } from './types.js';
+import type { BrowserProfileStatus } from './browser/daemon-client.js';
 export type DoctorOptions = {
     yes?: boolean;
     live?: boolean;
@@ -24,12 +26,8 @@ export type DoctorReport = {
     extensionVersion?: string;
     latestExtensionVersion?: string;
     connectivity?: ConnectivityResult;
-    sessions?: Array<{
-        workspace: string;
-        windowId: number;
-        tabCount: number;
-        idleMsRemaining: number;
-    }>;
+    sessions?: BrowserSessionInfo[];
+    profiles?: BrowserProfileStatus[];
     issues: string[];
 };
 /**

package/dist/src/doctor.js

@@ -10,6 +10,7 @@ import { getDaemonHealth, listSessions } from './browser/daemon-client.js';
 import { getErrorMessage } from './errors.js';
 import { getRuntimeLabel } from './runtime-detect.js';
 import { getCachedLatestExtensionVersion } from './update-check.js';
+import { aliasForContextId, loadProfileConfig } from './browser/profile.js';
 const DOCTOR_LIVE_TIMEOUT_SECONDS = 8;
 /** Parse a semver string into [major, minor, patch]. Returns null on invalid input. */
 function parseSemver(v) {
@@ -48,9 +49,14 @@ export async function checkConnectivity(opts) {
     try {
         const bridge = new BrowserBridge();
         const page = await bridge.connect({ timeout: opts?.timeout ?? DOCTOR_LIVE_TIMEOUT_SECONDS });
-        // Try a simple eval to verify end-to-end connectivity
-        await page.evaluate('1 + 1');
-        await bridge.close();
+        try {
+            // Try a simple eval to verify end-to-end connectivity.
+            await page.evaluate('1 + 1');
+            await page.closeWindow?.();
+        }
+        finally {
+            await bridge.close();
+        }
         return { ok: true, durationMs: Date.now() - start };
     }
     catch (err) {
@@ -84,9 +90,20 @@ export async function runBrowserDoctor(opts = {}) {
     const extensionConnected = health.state === 'ready';
     const daemonFlaky = !!(connectivity?.ok && !daemonRunning);
     const extensionFlaky = !!(connectivity?.ok && daemonRunning && !extensionConnected);
-    const sessions = opts.sessions && health.state === 'ready'
-        ? await listSessions()
-        : undefined;
+    const profiles = health.status?.profiles;
+    let sessions;
+    if (opts.sessions) {
+        if (profiles && profiles.length > 0) {
+            const grouped = await Promise.all(profiles.map(async (profile) => {
+                const rows = await listSessions({ contextId: profile.contextId }).catch(() => []);
+                return rows.map((row) => ({ ...row, contextId: row.contextId ?? profile.contextId }));
+            }));
+            sessions = grouped.flat();
+        }
+        else if (health.state === 'ready') {
+            sessions = await listSessions();
+        }
+    }
     const extensionVersion = health.status?.extensionVersion;
     const issues = [];
     if (daemonFlaky) {
@@ -101,23 +118,33 @@ export async function runBrowserDoctor(opts = {}) {
             'This usually means the Browser Bridge service worker is reconnecting slowly or Chrome suspended it.');
     }
     else if (daemonRunning && !extensionConnected) {
-        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');
+        if (health.state === 'profile-required') {
+            issues.push('Multiple Chrome profiles are connected to the daemon, but no default profile was selected.\n' +
+                '  Run opencli profile list, then opencli profile use <name>, or pass --profile <name>.');
+        }
+        else if (health.state === 'profile-disconnected') {
+            issues.push(`Selected browser profile is not connected: ${health.status?.contextId ?? 'unknown'}.\n` +
+                '  Open that Chrome profile and make sure the OpenCLI extension is enabled.');
         }
         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');
+            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');
+            }
         }
     }
     if (extensionConnected && !extensionVersion) {
@@ -162,6 +189,7 @@ export async function runBrowserDoctor(opts = {}) {
         latestExtensionVersion,
         connectivity,
         sessions,
+        profiles,
         issues,
     };
 }
@@ -191,6 +219,17 @@ export function renderBrowserDoctorReport(report) {
         ? 'unstable (connected during live check, then disconnected)'
         : report.extensionConnected ? 'connected' : 'not connected';
     lines.push(`${extIcon} Extension: ${extLabel}${extVersion}`);
+    if (report.profiles && report.profiles.length > 0) {
+        const config = loadProfileConfig();
+        lines.push('', styleText('bold', 'Profiles:'));
+        for (const profile of report.profiles) {
+            const alias = aliasForContextId(config, profile.contextId);
+            const aliasText = alias ? ` (${alias})` : '';
+            const defaultText = config.defaultContextId === profile.contextId ? ', default' : '';
+            const version = profile.extensionVersion ? `v${profile.extensionVersion}` : 'version unknown';
+            lines.push(styleText('dim', `  • ${profile.contextId}${aliasText}: connected ${version}${defaultText}`));
+        }
+    }
     // Connectivity
     if (report.connectivity) {
         const connIcon = report.connectivity.ok ? styleText('green', '[OK]') : styleText('red', '[FAIL]');
@@ -208,8 +247,27 @@ export function renderBrowserDoctorReport(report) {
             lines.push(styleText('dim', '  • no active automation sessions'));
         }
         else {
+            const byContext = new Map();
             for (const session of report.sessions) {
-                lines.push(styleText('dim', `  • ${session.workspace} → window ${session.windowId}, tabs=${session.tabCount}, idle=${Math.ceil(session.idleMsRemaining / 1000)}s`));
+                const contextId = typeof session.contextId === 'string' && session.contextId ? session.contextId : 'default';
+                const rows = byContext.get(contextId) ?? [];
+                rows.push(session);
+                byContext.set(contextId, rows);
+            }
+            for (const [contextId, rows] of byContext) {
+                if (byContext.size > 1)
+                    lines.push(styleText('dim', `  [profile: ${contextId}]`));
+                for (const session of rows) {
+                    const idle = session.idleMsRemaining == null
+                        ? 'none'
+                        : `${Math.ceil(session.idleMsRemaining / 1000)}s`;
+                    const target = session.preferredTabId != null
+                        ? `tab ${session.preferredTabId}`
+                        : `window ${session.windowId ?? 'unknown'}`;
+                    const mode = session.ownership ?? (session.owned === false ? 'borrowed' : 'owned');
+                    const surface = session.surface ? `, surface=${session.surface}` : '';
+                    lines.push(styleText('dim', `  • ${session.workspace ?? 'default'} → ${target}, mode=${mode}${surface}, tabs=${session.tabCount ?? 0}, idle=${idle}`));
+                }
             }
         }
     }

package/dist/src/doctor.test.js

@@ -78,6 +78,64 @@ describe('doctor report rendering', () => {
         }));
         expect(text).toContain('[SKIP] Connectivity: skipped (--no-live)');
     });
+    it('renders sessions with tab leases and no idle timer', () => {
+        const text = strip(renderBrowserDoctorReport({
+            daemonRunning: true,
+            extensionConnected: true,
+            issues: [],
+            sessions: [
+                {
+                    workspace: 'bound:default',
+                    windowId: 2,
+                    preferredTabId: 42,
+                    ownership: 'borrowed',
+                    surface: 'borrowed-user-tab',
+                    tabCount: 1,
+                    idleMsRemaining: null,
+                },
+            ],
+        }));
+        expect(text).toContain('bound:default → tab 42, mode=borrowed, surface=borrowed-user-tab, tabs=1, idle=none');
+    });
+    it('renders connected profiles and groups sessions by profile', () => {
+        const text = strip(renderBrowserDoctorReport({
+            daemonRunning: true,
+            extensionConnected: false,
+            profiles: [
+                { contextId: 'work', extensionConnected: true, extensionVersion: '1.2.3', pending: 0 },
+                { contextId: 'personal', extensionConnected: true, extensionVersion: '1.2.3', pending: 0 },
+            ],
+            issues: [],
+            sessions: [
+                {
+                    contextId: 'work',
+                    workspace: 'bound:default',
+                    windowId: 2,
+                    preferredTabId: 42,
+                    ownership: 'borrowed',
+                    surface: 'borrowed-user-tab',
+                    tabCount: 1,
+                    idleMsRemaining: null,
+                },
+                {
+                    contextId: 'personal',
+                    workspace: 'site:foo',
+                    windowId: 1,
+                    preferredTabId: 10,
+                    ownership: 'owned',
+                    surface: 'dedicated-container',
+                    tabCount: 1,
+                    idleMsRemaining: 1000,
+                },
+            ],
+        }));
+        expect(text).toContain('Profiles:');
+        expect(text).toContain('work: connected v1.2.3');
+        expect(text).toContain('[profile: work]');
+        expect(text).toContain('[profile: personal]');
+        expect(text).toContain('bound:default → tab 42');
+        expect(text).toContain('site:foo → tab 10');
+    });
     it('renders unstable extension state when live connectivity and status disagree', () => {
         const text = strip(renderBrowserDoctorReport({
             daemonRunning: true,
@@ -142,16 +200,19 @@ describe('doctor report rendering', () => {
     });
     it('uses the fast default timeout for live connectivity checks', async () => {
         let timeoutSeen;
+        const closeWindow = vi.fn().mockResolvedValue(undefined);
         mockConnect.mockImplementationOnce(async (opts) => {
             timeoutSeen = opts?.timeout;
             return {
                 evaluate: vi.fn().mockResolvedValue(2),
+                closeWindow,
             };
         });
         mockClose.mockResolvedValueOnce(undefined);
         mockGetDaemonHealth.mockResolvedValueOnce({ state: 'ready', status: { extensionConnected: true } });
         await runBrowserDoctor({ live: true });
         expect(timeoutSeen).toBe(8);
+        expect(closeWindow).toHaveBeenCalledTimes(1);
     });
     it('skips auto-start in no-live mode when daemon is already running', async () => {
         mockGetDaemonHealth.mockResolvedValueOnce({ state: 'no-extension', status: { extensionConnected: false } });
@@ -177,4 +238,25 @@ describe('doctor report rendering', () => {
             expect.stringContaining('did not report a version'),
         ]));
     });
+    it('reports profile-required when multiple profiles are connected without a selection', async () => {
+        const status = {
+            state: 'profile-required',
+            status: {
+                extensionConnected: false,
+                profileRequired: true,
+                profiles: [
+                    { contextId: 'work', extensionConnected: true, pending: 0 },
+                    { contextId: 'personal', extensionConnected: true, pending: 0 },
+                ],
+            },
+        };
+        mockGetDaemonHealth
+            .mockResolvedValueOnce(status)
+            .mockResolvedValueOnce(status);
+        const report = await runBrowserDoctor({ live: false });
+        expect(report.profiles).toHaveLength(2);
+        expect(report.issues).toEqual(expect.arrayContaining([
+            expect.stringContaining('Multiple Chrome profiles are connected'),
+        ]));
+    });
 });

package/dist/src/engine.test.js

@@ -137,6 +137,7 @@ describe('discoverPlugins', () => {
     const symlinkTargetDir = path.join(os.tmpdir(), '__test-plugin-symlink-target__');
     const symlinkPluginDir = path.join(PLUGINS_DIR, '__test-plugin-symlink__');
     const brokenSymlinkDir = path.join(PLUGINS_DIR, '__test-plugin-broken__');
+    const dirSymlinkType = process.platform === 'win32' ? 'junction' : 'dir';
     afterEach(async () => {
         try {
             await fs.promises.rm(testPluginDir, { recursive: true });
@@ -183,14 +184,14 @@ description: Test plugin greeting via symlink
 strategy: public
 browser: false
 `);
-        await fs.promises.symlink(symlinkTargetDir, symlinkPluginDir, 'dir');
+        await fs.promises.symlink(symlinkTargetDir, symlinkPluginDir, dirSymlinkType);
         await discoverPlugins();
         const cmd = getRegistry().get('__test-plugin-symlink__/hello');
         expect(cmd).toBeUndefined();
     });
     it('skips broken plugin symlinks without throwing', async () => {
         await fs.promises.mkdir(PLUGINS_DIR, { recursive: true });
-        await fs.promises.symlink(path.join(os.tmpdir(), '__missing-plugin-target__'), brokenSymlinkDir, 'dir');
+        await fs.promises.symlink(path.join(os.tmpdir(), '__missing-plugin-target__'), brokenSymlinkDir, dirSymlinkType);
         await expect(discoverPlugins()).resolves.not.toThrow();
         expect(getRegistry().get('__test-plugin-broken__/hello')).toBeUndefined();
     });
@@ -210,7 +211,7 @@ describe('executeCommand', () => {
             args: [
                 { name: 'note-id', required: true, help: 'Note ID' },
             ],
-            func: async (_page, kwargs) => [{ noteId: kwargs['note-id'] }],
+            func: async (kwargs) => [{ noteId: kwargs['note-id'] }],
         });
         const result = await executeCommand(cmd, { 'note-id': 'abc123' });
         expect(result).toEqual([{ noteId: 'abc123' }]);
@@ -222,7 +223,7 @@ describe('executeCommand', () => {
             description: 'test command with func',
             browser: false,
             strategy: Strategy.PUBLIC,
-            func: async (_page, kwargs) => {
+            func: async (kwargs) => {
                 return [{ title: kwargs.query ?? 'default' }];
             },
         });
@@ -260,7 +261,7 @@ describe('executeCommand', () => {
             name: 'debug-test',
             description: 'debug test',
             browser: false,
-            func: async (_page, _kwargs, debug) => {
+            func: async (_kwargs, debug) => {
                 receivedDebug = debug ?? false;
                 return [];
             },

package/dist/src/errors.d.ts

@@ -13,12 +13,13 @@
  *   1   Generic / unexpected error
  *   2   Argument / usage error          (ArgumentError)
  *  66   No input / empty result         (EmptyResultError)
- *  69   Service unavailable             (BrowserConnectError, AdapterLoadError)
+ *  69   Service unavailable             (BrowserConnectError, adapter load failures)
  *  75   Temporary failure, retry later  (TimeoutError)   EX_TEMPFAIL
  *  77   Permission denied / auth needed (AuthRequiredError)
  *  78   Configuration error             (ConfigError)
  * 130   Interrupted by Ctrl-C           (set by tui.ts SIGINT handler)
  */
+import type { ObservationTraceReceipt } from './observation/events.js';
 export declare const EXIT_CODES: {
     readonly SUCCESS: 0;
     readonly GENERIC_ERROR: 1;
@@ -40,14 +41,13 @@ export declare class CliError extends Error {
     readonly exitCode: ExitCode;
     constructor(code: string, message: string, hint?: string, exitCode?: ExitCode);
 }
-export type BrowserConnectKind = 'daemon-not-running' | 'extension-not-connected' | 'command-failed' | 'unknown';
+export declare function attachTraceReceipt(err: unknown, receipt: ObservationTraceReceipt): void;
+export declare function getTraceReceipt(err: unknown): ObservationTraceReceipt | undefined;
+export type BrowserConnectKind = 'daemon-not-running' | 'extension-not-connected' | 'profile-required' | 'profile-disconnected' | 'command-failed' | 'unknown';
 export declare class BrowserConnectError extends CliError {
     readonly kind: BrowserConnectKind;
     constructor(message: string, hint?: string, kind?: BrowserConnectKind);
 }
-export declare class AdapterLoadError extends CliError {
-    constructor(message: string, hint?: string);
-}
 export declare class CommandExecutionError extends CliError {
     constructor(message: string, hint?: string);
 }
@@ -67,9 +67,8 @@ export declare class ArgumentError extends CliError {
 export declare class EmptyResultError extends CliError {
     constructor(command: string, hint?: string);
 }
-export declare class SelectorError extends CliError {
-    constructor(selector: string, hint?: string);
-}
+export declare function adapterLoadError(message: string, hint?: string): CliError;
+export declare function selectorError(selector: string, hint?: string): CliError;
 export declare class PluginError extends CliError {
     constructor(message: string, hint?: string);
 }
@@ -84,6 +83,13 @@ export interface ErrorEnvelope {
         stack?: string;
         cause?: string;
     };
+    trace?: {
+        traceId: string;
+        dir: string;
+        summaryPath: string;
+        receiptPath: string;
+        status: ObservationTraceReceipt['status'];
+    };
 }
 /** Extract a human-readable message from an unknown caught value. */
 export declare function getErrorMessage(error: unknown): string;