@jackwener/opencli 1.7.15 → 1.7.17

package/dist/src/cli.js

@@ -36,8 +36,6 @@ import { bindTab, BrowserCommandError, fetchDaemonStatus, sendCommand } from './
 import { aliasForContextId, loadProfileConfig, renameProfile, resolveProfileContextId, setDefaultProfile } from './browser/profile.js';
 import { formatDaemonVersion, isDaemonStale } from './browser/daemon-version.js';
 const CLI_FILE = fileURLToPath(import.meta.url);
-const DEFAULT_BROWSER_WORKSPACE = 'browser:default';
-const DEFAULT_BOUND_WORKSPACE = 'bound:default';
 const BROWSER_TAB_OPTION_DESCRIPTION = 'Target tab/page identity returned by "browser open", "browser tab new", or "browser tab list"';
 const FOLLOW_POLL_MS = 1_000;
 function parseDurationMs(raw, flagName) {
@@ -245,11 +243,11 @@ export function renderVerifyPreview(rows, opts = {}) {
 function getBrowserCacheDir() {
     return process.env.OPENCLI_CACHE_DIR || path.join(os.homedir(), '.opencli', 'cache');
 }
-function getBrowserTargetStatePath(scope = DEFAULT_BROWSER_WORKSPACE) {
-    const safeWorkspace = scope.replace(/[^a-zA-Z0-9_-]+/g, '_');
-    return path.join(getBrowserCacheDir(), 'browser-state', `${safeWorkspace}.json`);
+function getBrowserTargetStatePath(scope) {
+    const safeSession = scope.replace(/[^a-zA-Z0-9_-]+/g, '_');
+    return path.join(getBrowserCacheDir(), 'browser-state', `${safeSession}.json`);
 }
-function loadBrowserTargetState(scope = DEFAULT_BROWSER_WORKSPACE) {
+function loadBrowserTargetState(scope) {
     try {
         const raw = fs.readFileSync(getBrowserTargetStatePath(scope), 'utf-8');
         const parsed = JSON.parse(raw);
@@ -259,7 +257,7 @@ function loadBrowserTargetState(scope = DEFAULT_BROWSER_WORKSPACE) {
         return null;
     }
 }
-function saveBrowserTargetState(defaultPage, scope = DEFAULT_BROWSER_WORKSPACE) {
+function saveBrowserTargetState(defaultPage, scope) {
     const target = getBrowserTargetStatePath(scope);
     if (!defaultPage) {
         fs.rmSync(target, { force: true });
@@ -291,7 +289,7 @@ async function resolveBrowserTargetInSession(page, targetPage, opts) {
             return undefined;
         }
         throw new Error(`Target tab ${candidate} could not be validated in the current browser session. ` +
-            'The Browser Bridge workspace may have restarted; re-run "opencli browser tab list" and choose a current target.', { cause: err });
+            'The Browser Bridge session may have restarted; re-run "opencli browser tab list" and choose a current target.', { cause: err });
     }
     if (Array.isArray(tabs) && hasBrowserTabTarget(tabs, candidate)) {
         return candidate;
@@ -301,32 +299,33 @@ async function resolveBrowserTargetInSession(page, targetPage, opts) {
         return undefined;
     }
     throw new Error(`Target tab ${candidate} is not part of the current browser session. ` +
-        'The Browser Bridge workspace may have restarted; re-run "opencli browser tab list" and choose a current target.');
+        'The Browser Bridge session may have restarted; re-run "opencli browser tab list" and choose a current target.');
 }
-function getBrowserScope(workspace, contextId) {
-    return contextId ? `${contextId}:${workspace}` : workspace;
+function getBrowserScope(session, contextId) {
+    return contextId ? `${contextId}:${session}` : session;
 }
-async function resolveStoredBrowserTarget(page, scope = DEFAULT_BROWSER_WORKSPACE) {
+async function resolveStoredBrowserTarget(page, scope) {
     const defaultPage = loadBrowserTargetState(scope)?.defaultPage?.trim();
     if (!defaultPage)
         return undefined;
     return resolveBrowserTargetInSession(page, defaultPage, { scope, source: 'saved' });
 }
-/** Create a browser page for browser commands. Uses a dedicated browser workspace for session persistence. */
-async function getBrowserPage(targetPage, workspace = DEFAULT_BROWSER_WORKSPACE, contextId) {
+/** Create a browser page for browser commands. Uses a named browser session for continuity. */
+async function getBrowserPage(session, targetPage, contextId, opts = {}) {
     const { BrowserBridge } = await import('./browser/index.js');
     const bridge = new BrowserBridge();
-    // Idle timeout: how long the browser workspace lease stays alive between commands
-    // (controls when the automation tab is released). Not the per-command runtime timeout.
+    // Internal GC timeout for browser sessions. Not the per-command runtime timeout.
     const envTimeout = process.env.OPENCLI_BROWSER_IDLE_TIMEOUT;
     const idleTimeout = envTimeout ? parseInt(envTimeout, 10) : undefined;
     const page = await bridge.connect({
         timeout: 30,
-        workspace,
+        session,
+        surface: 'browser',
         ...(contextId && { contextId }),
         ...(idleTimeout && idleTimeout > 0 && { idleTimeout }),
+        windowMode: opts.windowMode ?? getBrowserWindowMode(undefined, 'foreground'),
     });
-    const targetScope = getBrowserScope(workspace, contextId);
+    const targetScope = getBrowserScope(session, contextId);
     const resolvedTargetPage = targetPage
         ? await resolveBrowserTargetInSession(page, targetPage, { scope: targetScope, source: 'explicit' })
         : await resolveStoredBrowserTarget(page, targetScope);
@@ -338,6 +337,21 @@ async function getBrowserPage(targetPage, workspace = DEFAULT_BROWSER_WORKSPACE,
     }
     return page;
 }
+function getBrowserWindowMode(command, defaultMode) {
+    const optionRaw = getCommandOption(command, 'window');
+    if (optionRaw !== undefined && optionRaw !== '') {
+        if (optionRaw === 'foreground' || optionRaw === 'background')
+            return optionRaw;
+        throw new Error(`--window must be one of: foreground, background. Received: "${String(optionRaw)}"`);
+    }
+    const envRaw = process.env.OPENCLI_WINDOW;
+    if (envRaw !== undefined && envRaw !== '') {
+        if (envRaw === 'foreground' || envRaw === 'background')
+            return envRaw;
+        throw new Error(`OPENCLI_WINDOW must be one of: foreground, background. Received: "${envRaw}"`);
+    }
+    return defaultMode;
+}
 function addBrowserTabOption(command) {
     return command.option('--tab <targetId>', BROWSER_TAB_OPTION_DESCRIPTION);
 }
@@ -357,21 +371,25 @@ function getCommandOption(command, option) {
     }
     return undefined;
 }
-function getBrowserWorkspace(command) {
-    const raw = getCommandOption(command, 'workspace');
-    return typeof raw === 'string' && raw.trim() ? raw.trim() : DEFAULT_BROWSER_WORKSPACE;
+function getBrowserSession(command) {
+    const raw = getCommandOption(command, 'session');
+    if (typeof raw === 'string' && raw.trim())
+        return raw.trim();
+    throw new Error('--session <name> is required for opencli browser commands');
 }
 function getBrowserContextId(command) {
     const raw = getCommandOption(command, 'profile');
     return resolveProfileContextId(typeof raw === 'string' && raw.trim() ? raw.trim() : undefined);
 }
-function getPageWorkspace(page) {
-    const workspace = page.workspace;
-    return typeof workspace === 'string' && workspace.trim() ? workspace.trim() : DEFAULT_BROWSER_WORKSPACE;
+function getPageSession(page) {
+    const session = page.session;
+    if (typeof session === 'string' && session.trim())
+        return session.trim();
+    throw new Error('Browser page is missing a session');
 }
 function getPageScope(page) {
     const contextId = page.contextId;
-    return getBrowserScope(getPageWorkspace(page), typeof contextId === 'string' && contextId.trim() ? contextId.trim() : undefined);
+    return getBrowserScope(getPageSession(page), typeof contextId === 'string' && contextId.trim() ? contextId.trim() : undefined);
 }
 function snapshotMetricText(snapshot) {
     return typeof snapshot === 'string' ? snapshot : JSON.stringify(snapshot, null, 2);
@@ -582,7 +600,8 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
     // All commands wrapped in browserAction() for consistent error handling.
     const browser = program
         .command('browser')
-        .option('--workspace <name>', 'Browser workspace to use (default: browser:default; bound tabs use bound:<name>)')
+        .option('--session <name>', 'Browser session to use')
+        .option('--window <mode>', 'Browser window mode: foreground or background')
         .description('Browser control — navigate, click, type, extract, wait (no LLM needed)');
     const originalBrowserDescription = browser.description();
     /**
@@ -646,12 +665,14 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
     /** Wrap browser actions with error handling and optional --json output */
     function browserAction(fn) {
         return async (...args) => {
+            let page = null;
             try {
                 const command = args.at(-1) instanceof Command ? args.at(-1) : undefined;
                 const targetPage = getBrowserTargetId(command);
-                const workspace = getBrowserWorkspace(command);
+                const session = getBrowserSession(command);
                 const contextId = getBrowserContextId(command);
-                const page = await getBrowserPage(targetPage, workspace, contextId);
+                const windowMode = getBrowserWindowMode(command, 'foreground');
+                page = await getBrowserPage(session, targetPage, contextId, { windowMode });
                 await fn(page, ...args);
             }
             catch (err) {
@@ -702,40 +723,19 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
         };
     }
     browser.command('bind')
-        .option('--domain <host>', 'Only bind a current/visible tab whose hostname matches this domain')
-        .option('--path-prefix <path>', 'Only bind a current/visible tab whose pathname starts with this prefix')
-        .option('--workspace <name>', 'Bound workspace name (must start with bound:)')
-        .description('Bind a bound:* workspace to the current Chrome tab/window')
+        .option('--session <name>', 'Browser session name to bind')
+        .description('Bind the current Chrome tab/window to a browser session')
         .action(async (optsOrCommand, maybeCommand) => {
         const command = optsOrCommand instanceof Command ? optsOrCommand : maybeCommand;
-        const opts = command?.opts() ?? optsOrCommand ?? {};
-        const rawWorkspace = getCommandOption(command, 'workspace');
-        const workspace = typeof rawWorkspace === 'string' && rawWorkspace.trim()
-            ? rawWorkspace.trim()
-            : DEFAULT_BOUND_WORKSPACE;
-        if (!workspace.startsWith('bound:')) {
-            console.log(JSON.stringify({
-                error: {
-                    code: 'invalid_bind_workspace',
-                    message: `--workspace must start with "bound:", got "${workspace}"`,
-                    hint: 'Use the default bound:default or pass --workspace bound:<name>.',
-                },
-            }, null, 2));
-            process.exitCode = EXIT_CODES.USAGE_ERROR;
-            return;
-        }
+        const session = getBrowserSession(command);
         try {
             const { BrowserBridge } = await import('./browser/index.js');
             const bridge = new BrowserBridge();
             const contextId = getBrowserContextId(command);
-            await bridge.connect({ timeout: 30, workspace, ...(contextId && { contextId }) });
-            const data = await bindTab(workspace, {
-                ...(contextId && { contextId }),
-                ...(typeof opts.domain === 'string' && opts.domain.trim() ? { matchDomain: opts.domain.trim() } : {}),
-                ...(typeof opts.pathPrefix === 'string' && opts.pathPrefix.trim() ? { matchPathPrefix: opts.pathPrefix.trim() } : {}),
-            });
-            saveBrowserTargetState(undefined, getBrowserScope(workspace, contextId));
-            console.log(JSON.stringify({ workspace, ...((data && typeof data === 'object') ? data : { data }) }, null, 2));
+            await bridge.connect({ timeout: 30, session, surface: 'browser', ...(contextId && { contextId }) });
+            const data = await bindTab(session, { ...(contextId && { contextId }) });
+            saveBrowserTargetState(undefined, getBrowserScope(session, contextId));
+            console.log(JSON.stringify({ session, ...((data && typeof data === 'object') ? data : { data }) }, null, 2));
         }
         catch (err) {
             if (err instanceof BrowserCommandError && err.code) {
@@ -750,39 +750,23 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
             log.error(err instanceof Error ? err.message : String(err));
             if (err instanceof BrowserCommandError && err.hint)
                 log.error(`Hint: ${err.hint}`);
-            process.exitCode = err instanceof BrowserCommandError && err.code === 'invalid_bind_workspace'
-                ? EXIT_CODES.USAGE_ERROR
-                : EXIT_CODES.GENERIC_ERROR;
+            process.exitCode = EXIT_CODES.GENERIC_ERROR;
         }
     });
     browser.command('unbind')
-        .option('--workspace <name>', 'Bound workspace name to detach')
-        .description('Detach a bound:* workspace without closing the user tab/window')
+        .option('--session <name>', 'Browser session name to detach')
+        .description('Detach a bound browser session without closing the user tab/window')
         .action(async (optsOrCommand, maybeCommand) => {
         const command = optsOrCommand instanceof Command ? optsOrCommand : maybeCommand;
-        const rawWorkspace = getCommandOption(command, 'workspace');
-        const workspace = typeof rawWorkspace === 'string' && rawWorkspace.trim()
-            ? rawWorkspace.trim()
-            : DEFAULT_BOUND_WORKSPACE;
-        if (!workspace.startsWith('bound:')) {
-            console.log(JSON.stringify({
-                error: {
-                    code: 'invalid_bind_workspace',
-                    message: `--workspace must start with "bound:", got "${workspace}"`,
-                    hint: 'Use the default bound:default or pass --workspace bound:<name>.',
-                },
-            }, null, 2));
-            process.exitCode = EXIT_CODES.USAGE_ERROR;
-            return;
-        }
+        const session = getBrowserSession(command);
         try {
             const { BrowserBridge } = await import('./browser/index.js');
             const bridge = new BrowserBridge();
             const contextId = getBrowserContextId(command);
-            await bridge.connect({ timeout: 30, workspace, ...(contextId && { contextId }) });
-            await sendCommand('close-window', { workspace, ...(contextId && { contextId }) });
-            saveBrowserTargetState(undefined, getBrowserScope(workspace, contextId));
-            console.log(JSON.stringify({ unbound: true, workspace }, null, 2));
+            await bridge.connect({ timeout: 30, session, surface: 'browser', ...(contextId && { contextId }) });
+            await sendCommand('close-window', { session, surface: 'browser', ...(contextId && { contextId }) });
+            saveBrowserTargetState(undefined, getBrowserScope(session, contextId));
+            console.log(JSON.stringify({ unbound: true, session }, null, 2));
         }
         catch (err) {
             if (err instanceof BrowserCommandError && err.code) {
@@ -802,9 +786,9 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
     });
     const browserTab = browser
         .command('tab')
-        .description('Tab management — list, create, and close tabs in the automation window');
+        .description('Tab management — list, create, and close tabs in the browser session');
     browserTab.command('list')
-        .description('List tabs in the automation window with target IDs')
+        .description('List tabs in the browser session with target IDs')
         .action(browserAction(async (page) => {
         const tabs = await page.tabs();
         console.log(JSON.stringify(tabs, null, 2));
@@ -871,16 +855,11 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
      * capped at 200 entries, bounding worst-case in-page memory.
      */
     const NETWORK_INTERCEPTOR_JS = `(function(){if(window.__opencli_net)return;window.__opencli_net=[];var M=200,B=1048576,F=window.fetch;function capture(url,method,status,text,ct){if(window.__opencli_net.length>=M)return;var full=text?text.length:0,trunc=full>B,stored=trunc?text.slice(0,B):text,body=null;if(stored){if(trunc){body=stored}else{try{body=JSON.parse(stored)}catch(e){body=stored}}}var e={url:url,method:method||'GET',status:status,size:full,ct:ct,body:body,timestamp:Date.now()};if(trunc){e.bodyTruncated=true;e.bodyFullSize=full}window.__opencli_net.push(e)}window.fetch=async function(){var r=await F.apply(this,arguments);try{var ct=r.headers.get('content-type')||'';if(ct.includes('json')||ct.includes('text')){var c=r.clone(),t=await c.text();capture(r.url||(arguments[0]&&arguments[0].url)||String(arguments[0]),(arguments[1]&&arguments[1].method)||'GET',r.status,t,ct)}}catch(e){}return r};var X=XMLHttpRequest.prototype,O=X.open,S=X.send;X.open=function(m,u){this._om=m;this._ou=u;return O.apply(this,arguments)};X.send=function(){var x=this;x.addEventListener('load',function(){try{var ct=x.getResponseHeader('content-type')||'';if(ct.includes('json')||ct.includes('text')){capture(x._ou,x._om||'GET',x.status,x.responseText||'',ct)}}catch(e){}});return S.apply(this,arguments)}})()`;
-    addBrowserTabOption(browser.command('open').argument('<url>').option('--allow-navigate-bound', 'Allow navigating a bound user tab', false).description('Open URL in automation window'))
+    addBrowserTabOption(browser.command('open').argument('<url>').description('Open URL in the browser session'))
         .action(browserAction(async (page, url, opts) => {
         // Start session-level capture before navigation (catches initial requests)
         const hasSessionCapture = await page.startNetworkCapture?.() ?? false;
-        if (opts.allowNavigateBound === true) {
-            await page.goto(url, { allowBoundNavigation: true });
-        }
-        else {
-            await page.goto(url);
-        }
+        await page.goto(url);
         await page.wait(2);
         // Fallback: inject JS interceptor when session capture is unavailable
         if (!hasSessionCapture) {
@@ -894,19 +873,8 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
             ...(page.getActivePage?.() ? { page: page.getActivePage?.() } : {}),
         }, null, 2));
     }));
-    addBrowserTabOption(browser.command('back').option('--allow-navigate-bound', 'Allow history navigation in a bound user tab', false).description('Go back in browser history'))
+    addBrowserTabOption(browser.command('back').description('Go back in browser history'))
         .action(browserAction(async (page, opts) => {
-        if (getPageWorkspace(page).startsWith('bound:') && opts.allowNavigateBound !== true) {
-            console.log(JSON.stringify({
-                error: {
-                    code: 'bound_navigation_blocked',
-                    message: `Workspace "${getPageWorkspace(page)}" is bound to a user tab; history navigation is blocked by default.`,
-                    hint: 'Pass --allow-navigate-bound only if you intentionally want to navigate the bound tab.',
-                },
-            }, null, 2));
-            process.exitCode = EXIT_CODES.GENERIC_ERROR;
-            return;
-        }
         await page.evaluate('history.back()');
         await page.wait(2);
         console.log('Navigated back');
@@ -1037,7 +1005,7 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
         }
         const messages = filter(normalize(await page.consoleMessages(opts.level)));
         console.log(JSON.stringify({
-            workspace: getPageWorkspace(page),
+            session: getPageSession(page),
             captured_at: new Date().toISOString(),
             count: messages.length,
             messages: messages.map((message) => ({
@@ -2129,7 +2097,7 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
     // Default output is JSON (agent-native). Each entry carries a stable `key`
     // (GraphQL operationName or `METHOD host+pathname`) so agents can fetch
     // full bodies with `--detail <key>` even after subsequent commands.
-    // Captures are persisted per workspace under ~/.opencli/cache/browser-network/.
+    // Captures are persisted per browser session under ~/.opencli/cache/browser-network/.
     addBrowserTabOption(browser.command('network'))
         .option('--detail <key>', 'Emit full body for the entry with this key')
         .option('--all', 'Include static resources (js/css/images/telemetry)')
@@ -2144,7 +2112,7 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
         .description('Capture network requests as shape previews; retrieve full bodies by key')
         .action(browserAction(async (page, opts) => {
         const ttlMs = parsePositiveIntOption(opts.ttl, 'ttl', DEFAULT_TTL_MS);
-        const workspace = getPageWorkspace(page);
+        const session = getPageSession(page);
         const hasDetail = typeof opts.detail === 'string' && opts.detail.length > 0;
         const hasFilter = typeof opts.filter === 'string';
         const sinceMs = parseDurationMs(opts.since, 'since');
@@ -2180,9 +2148,9 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
         }
         // --detail short-circuits: read from cache only, no live capture needed.
         if (hasDetail) {
-            const res = loadNetworkCache(workspace, { ttlMs });
+            const res = loadNetworkCache(session, { ttlMs });
             if (res.status === 'missing') {
-                emitNetworkError('cache_missing', `No cached capture. Run "browser network" first (in workspace "${workspace}").`);
+                emitNetworkError('cache_missing', `No cached capture. Run "browser network" first (in session "${session}").`);
                 return;
             }
             if (res.status === 'expired') {
@@ -2303,7 +2271,7 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
         // via the output envelope rather than erroring out the whole command.
         let cacheWarning = null;
         try {
-            saveNetworkCache(workspace, cacheEntries);
+            saveNetworkCache(session, cacheEntries);
         }
         catch (err) {
             cacheWarning = `Could not persist capture cache: ${err.message}. --detail lookups may miss this capture.`;
@@ -2319,7 +2287,7 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
             : shaped;
         const filterDropped = filterFields ? shaped.length - visible.length : 0;
         const envelope = {
-            workspace,
+            session,
             captured_at: new Date().toISOString(),
             count: visible.length,
             filtered_out: filteredOut,
@@ -2384,19 +2352,7 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
                 console.log(`Adapter already exists: ${filePath}`);
                 return;
             }
-            // Try to detect domain from the last browser session
             let domain = site;
-            try {
-                const page = await getBrowserPage();
-                const url = await page.getCurrentUrl?.();
-                if (url) {
-                    try {
-                        domain = new URL(url).hostname;
-                    }
-                    catch { }
-                }
-            }
-            catch { /* no active session */ }
             const template = `import { cli, Strategy } from '@jackwener/opencli/registry';
 
 cli({
@@ -2584,22 +2540,20 @@ cli({
         }
     });
     // ── Session ──
-    browser.command('close').description('Release the current automation tab lease')
+    browser.command('close').description('Release the current browser session tab lease')
         .action(browserAction(async (page) => {
         await page.closeWindow?.();
-        console.log('Automation tab lease released');
+        console.log('Browser session tab lease released');
     }));
     // ── Built-in: doctor / completion ──────────────────────────────────────────
     program
         .command('doctor')
         .description('Diagnose opencli browser bridge connectivity')
-        .option('--no-live', 'Skip live browser connectivity test')
-        .option('--sessions', 'Show active automation sessions', false)
         .option('-v, --verbose', 'Debug output')
         .action(async (opts) => {
         applyVerbose(opts);
         const { runBrowserDoctor, renderBrowserDoctorReport } = await import('./doctor.js');
-        const report = await runBrowserDoctor({ live: opts.live, sessions: opts.sessions, cliVersion: PKG_VERSION });
+        const report = await runBrowserDoctor({ cliVersion: PKG_VERSION });
         console.log(renderBrowserDoctorReport(report));
     });
     program
@@ -2611,6 +2565,8 @@ cli({
     });
     // ── Plugin management ──────────────────────────────────────────────────────
     const pluginCmd = program.command('plugin').description('Manage opencli plugins');
+    // Snapshot before applyRootSubcommandSummaries() rewrites .description() to a child-name listing.
+    const originalPluginDescription = pluginCmd.description();
     pluginCmd
         .command('install')
         .description('Install a plugin from a git repository')
@@ -2797,6 +2753,8 @@ cli({
     });
     // ── Built-in: adapter management ─────────────────────────────────────────
     const adapterCmd = program.command('adapter').description('Manage CLI adapters');
+    // Snapshot before applyRootSubcommandSummaries() rewrites .description() to a child-name listing.
+    const originalAdapterDescription = adapterCmd.description();
     adapterCmd
         .command('status')
         .description('Show which sites have local overrides vs using official baseline')
@@ -2905,6 +2863,8 @@ cli({
     });
     // ── Built-in: browser profile selection ──────────────────────────────────
     const profileCmd = program.command('profile').description('Manage Browser Bridge Chrome profiles');
+    // Snapshot before applyRootSubcommandSummaries() rewrites .description() to a child-name listing.
+    const originalProfileDescription = profileCmd.description();
     profileCmd
         .command('list')
         .description('List Chrome profiles connected through the Browser Bridge extension')
@@ -2982,6 +2942,8 @@ cli({
     });
     // ── Built-in: daemon ──────────────────────────────────────────────────────
     const daemonCmd = program.command('daemon').description('Manage the opencli daemon');
+    // Snapshot before applyRootSubcommandSummaries() rewrites .description() to a child-name listing.
+    const originalDaemonDescription = daemonCmd.description();
     daemonCmd
         .command('status')
         .description('Show daemon status')
@@ -3107,6 +3069,10 @@ cli({
     const adapterGroups = { external: externalNames, apps, sites };
     const adapterNameSet = new Set([...externalNames, ...siteNames]);
     installCommanderNamespaceStructuredHelp(browser, { globalCommand: program, description: originalBrowserDescription });
+    installCommanderNamespaceStructuredHelp(daemonCmd, { globalCommand: program, description: originalDaemonDescription });
+    installCommanderNamespaceStructuredHelp(pluginCmd, { globalCommand: program, description: originalPluginDescription });
+    installCommanderNamespaceStructuredHelp(adapterCmd, { globalCommand: program, description: originalAdapterDescription });
+    installCommanderNamespaceStructuredHelp(profileCmd, { globalCommand: program, description: originalProfileDescription });
     program.configureHelp({
         visibleCommands: (command) => command.commands.filter(child => command !== program || !adapterNameSet.has(child.name())),
     });