@jackwener/opencli 1.7.17 → 1.7.19

package/dist/src/cli.test.js

@@ -349,18 +349,20 @@ describe('createProgram root help descriptions', () => {
             expect(data.command).toBe('opencli browser');
             expect(data.description).toBe('Browser control — navigate, click, type, extract, wait (no LLM needed)');
             expect(data.command_count).toBeGreaterThan(20);
+            // `--session` is now a hidden internal option; user-facing surface is the
+            // <session> positional declared via `.usage()`. Structured help drops
+            // hidden options, so namespace_options shouldn't expose it.
+            expect(data.namespace_options).not.toEqual(expect.arrayContaining([
+                expect.objectContaining({ name: 'session' }),
+            ]));
             expect(data.namespace_options).toEqual(expect.arrayContaining([
-                expect.objectContaining({
-                    name: 'session',
-                    flags: '--session <name>',
-                    takes_value: 'required',
-                }),
                 expect.objectContaining({
                     name: 'window',
                     flags: '--window <mode>',
                     takes_value: 'required',
                 }),
             ]));
+            expect(data.usage).toBe('opencli browser <session> <command> [options]');
             expect(data.global_options).toEqual(expect.arrayContaining([
                 expect.objectContaining({
                     name: 'version',
@@ -373,21 +375,24 @@ describe('createProgram root help descriptions', () => {
                 }),
             ]));
             const click = data.commands.find((cmd) => cmd.name === 'click');
+            // Structured help command/usage paths include the <session> positional so
+            // agents construct the correct full invocation. `name` is the leaf
+            // identifier (placeholder positionals are stripped).
             expect(click).toMatchObject({
-                command: 'opencli browser click',
-                usage: 'opencli browser click [target] [options]',
+                command: 'opencli browser <session> click',
+                usage: 'opencli browser <session> click [target] [options]',
                 positionals: [{ name: 'target' }],
             });
             expect(click.command_options.map((option) => option.name)).toEqual(['role', 'name', 'label', 'text', 'testid', 'nth', 'tab']);
             const tabList = data.commands.find((cmd) => cmd.name === 'tab list');
             expect(tabList).toMatchObject({
-                command: 'opencli browser tab list',
-                usage: 'opencli browser tab list [options]',
+                command: 'opencli browser <session> tab list',
+                usage: 'opencli browser <session> tab list [options]',
                 command_options: [],
             });
             const getText = data.commands.find((cmd) => cmd.name === 'get text');
             expect(getText).toMatchObject({
-                command: 'opencli browser get text',
+                command: 'opencli browser <session> get text',
                 positionals: [{ name: 'target' }],
             });
             expect(data.structured_help).toMatchObject({
@@ -411,8 +416,8 @@ describe('createProgram root help descriptions', () => {
             expect(data).toMatchObject({
                 namespace: 'browser',
                 group: 'tab',
-                command: 'opencli browser tab',
-                usage: 'opencli browser tab <command> [args] [options]',
+                command: 'opencli browser <session> tab',
+                usage: 'opencli browser <session> tab <command> [args] [options]',
                 command_count: 4,
             });
             expect(data.commands.map((cmd) => cmd.name)).toEqual([
@@ -422,13 +427,15 @@ describe('createProgram root help descriptions', () => {
                 'tab select',
             ]);
             expect(data.commands.find((cmd) => cmd.name === 'tab close')).toMatchObject({
-                command: 'opencli browser tab close',
-                usage: 'opencli browser tab close [targetId] [options]',
+                command: 'opencli browser <session> tab close',
+                usage: 'opencli browser <session> tab close [targetId] [options]',
                 positionals: [{ name: 'targetId', help: 'Target tab/page identity returned by "browser open", "browser tab new", or "browser tab list"' }],
             });
-            expect(data.namespace_options.map((option) => option.name)).toEqual(['session', 'window']);
+            // session is now a hidden internal option (consumed from the <session> positional).
+            // namespace_options should only list user-facing options.
+            expect(data.namespace_options.map((option) => option.name)).toEqual(['window']);
             expect(data.structured_help).toMatchObject({
-                usage: 'opencli browser tab --help -f yaml',
+                usage: 'opencli browser <session> tab --help -f yaml',
             });
         }
         finally {
@@ -447,15 +454,16 @@ describe('createProgram root help descriptions', () => {
             expect(data).toMatchObject({
                 namespace: 'browser',
                 name: 'click',
-                command: 'opencli browser click',
-                usage: 'opencli browser click [target] [options]',
+                command: 'opencli browser <session> click',
+                usage: 'opencli browser <session> click [target] [options]',
                 positionals: [{ name: 'target' }],
                 structured_help: {
-                    usage: 'opencli browser click --help -f yaml',
+                    usage: 'opencli browser <session> click --help -f yaml',
                 },
             });
             expect(data.command_options.map((option) => option.name)).toEqual(['role', 'name', 'label', 'text', 'testid', 'nth', 'tab']);
-            expect(data.namespace_options.map((option) => option.name)).toEqual(['session', 'window']);
+            // session is hidden; only `window` surfaces as a namespace option.
+            expect(data.namespace_options.map((option) => option.name)).toEqual(['window']);
             expect(data.global_options.map((option) => option.name)).toContain('profile');
         }
         finally {
@@ -896,10 +904,12 @@ describe('browser tab targeting commands', () => {
     });
     it('requires an explicit session for browser commands', async () => {
         const program = createProgram('', '');
+        // --session is now a hidden internal flag; commander no longer guards it.
+        // The action body throws via getBrowserSession(), surfacing the
+        // <session> positional in the error message.
         await program.parseAsync(['node', 'opencli', 'browser', 'state']);
         expect(mockBrowserConnect).not.toHaveBeenCalled();
-        expect(stderrSpy.mock.calls.flat().join('')).toContain('--session <name> is required');
-        expect(process.exitCode).toBeDefined();
+        expect(stderrSpy.mock.calls.flat().join('')).toContain('<session> is a required positional argument');
     });
     it('runs browser commands against an explicit session', async () => {
         const program = createProgram('', '');

package/dist/src/commands/daemon.js

@@ -4,7 +4,6 @@
  *   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';
@@ -14,18 +13,18 @@ import { formatDaemonVersion, isDaemonStale } from '../browser/daemon-version.js
 export async function daemonStatus() {
     const status = await fetchDaemonStatus();
     if (!status) {
-        console.log(`Daemon: ${styleText('dim', 'not running')}`);
+        console.log('Daemon: not running');
         return;
     }
     const extensionLabel = !status.extensionConnected
-        ? styleText('yellow', 'disconnected')
+        ? 'disconnected'
         : status.extensionVersion
-            ? `${styleText('green', 'connected')} ${styleText('dim', `(v${status.extensionVersion})`)}`
-            : `${styleText('yellow', 'connected')} ${styleText('dim', '(version unknown)')}`;
+            ? `connected (v${status.extensionVersion})`
+            : 'connected (version unknown)';
     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(`Daemon: ${stale ? 'stale' : 'running'} (PID ${status.pid})`);
+    console.log(`Version: ${daemonVersion}${stale ? ` (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) {

package/dist/src/doctor.js

@@ -3,7 +3,6 @@
  *
  * Simplified for the daemon-based architecture.
  */
-import { styleText } from 'node:util';
 import { DEFAULT_DAEMON_PORT } from './constants.js';
 import { BrowserBridge } from './browser/index.js';
 import { getDaemonHealth } from './browser/daemon-client.js';
@@ -14,6 +13,7 @@ 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;
+const DOCTOR_SESSION = '__doctor__';
 /** Parse a semver string into [major, minor, patch]. Returns null on invalid input. */
 function parseSemver(v) {
     const parts = v.replace(/^v/, '').split('-')[0].split('.').map(Number);
@@ -50,7 +50,11 @@ export async function checkConnectivity(opts) {
     const start = Date.now();
     try {
         const bridge = new BrowserBridge();
-        const page = await bridge.connect({ timeout: opts?.timeout ?? DOCTOR_LIVE_TIMEOUT_SECONDS });
+        const page = await bridge.connect({
+            timeout: opts?.timeout ?? DOCTOR_LIVE_TIMEOUT_SECONDS,
+            session: DOCTOR_SESSION,
+            surface: 'browser',
+        });
         try {
             // Try a simple eval to verify end-to-end connectivity.
             await page.evaluate('1 + 1');
@@ -163,13 +167,13 @@ export async function runBrowserDoctor(opts = {}) {
     };
 }
 export function renderBrowserDoctorReport(report) {
-    const lines = [styleText('bold', `opencli v${report.cliVersion ?? 'unknown'} doctor`) + styleText('dim', ` (${getRuntimeLabel()})`), ''];
+    const lines = [`opencli v${report.cliVersion ?? 'unknown'} doctor` + ` (${getRuntimeLabel()})`, ''];
     // Daemon status
     const daemonIcon = report.daemonFlaky
-        ? styleText('yellow', '[WARN]')
+        ? '[WARN]'
         : report.daemonStale
-            ? styleText('yellow', '[WARN]')
-            : report.daemonRunning ? styleText('green', '[OK]') : styleText('red', '[MISSING]');
+            ? '[WARN]'
+            : report.daemonRunning ? '[OK]' : '[MISSING]';
     const daemonLabel = report.daemonFlaky
         ? 'unstable (running during live check, then stopped)'
         : report.daemonRunning
@@ -180,47 +184,47 @@ export function renderBrowserDoctorReport(report) {
     lines.push(`${daemonIcon} Daemon: ${daemonLabel}`);
     // Extension status
     const extIcon = report.extensionFlaky || (report.extensionConnected && !report.extensionVersion)
-        ? styleText('yellow', '[WARN]')
-        : report.extensionConnected ? styleText('green', '[OK]') : styleText('yellow', '[MISSING]');
+        ? '[WARN]'
+        : report.extensionConnected ? '[OK]' : '[MISSING]';
     const extUpdateHint = report.extensionVersion && report.latestExtensionVersion && isNewerVersion(report.latestExtensionVersion, report.extensionVersion)
-        ? styleText('yellow', ` → v${report.latestExtensionVersion} available`)
+        ? ` → v${report.latestExtensionVersion} available`
         : '';
     const extVersion = !report.extensionConnected
         ? ''
         : report.extensionVersion
-            ? styleText('dim', ` (v${report.extensionVersion})`) + extUpdateHint
-            : styleText('dim', ' (version unknown)');
+            ? ` (v${report.extensionVersion})` + extUpdateHint
+            : ' (version unknown)';
     const extLabel = report.extensionFlaky
         ? '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:'));
+        lines.push('', '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}`));
+            lines.push(`  • ${profile.contextId}${aliasText}: connected ${version}${defaultText}`);
         }
     }
     // Connectivity
     if (report.connectivity) {
-        const connIcon = report.connectivity.ok ? styleText('green', '[OK]') : styleText('red', '[FAIL]');
+        const connIcon = report.connectivity.ok ? '[OK]' : '[FAIL]';
         const detail = report.connectivity.ok
             ? `connected in ${(report.connectivity.durationMs / 1000).toFixed(1)}s`
             : `failed (${report.connectivity.error ?? 'unknown'})`;
         lines.push(`${connIcon} Connectivity: ${detail}`);
     }
     if (report.issues.length) {
-        lines.push('', styleText('yellow', 'Issues:'));
+        lines.push('', 'Issues:');
         for (const issue of report.issues) {
-            lines.push(styleText('dim', `  • ${issue}`));
+            lines.push(`  • ${issue}`);
         }
     }
     else if (report.daemonRunning && report.extensionConnected) {
-        lines.push('', styleText('green', 'Everything looks good!'));
+        lines.push('', 'Everything looks good!');
     }
     return lines.join('\n');
 }

package/dist/src/doctor.test.js

@@ -173,6 +173,8 @@ describe('doctor report rendering', () => {
         const closeWindow = vi.fn().mockResolvedValue(undefined);
         mockConnect.mockImplementationOnce(async (opts) => {
             timeoutSeen = opts?.timeout;
+            expect(opts?.session).toBe('__doctor__');
+            expect(opts?.surface).toBe('browser');
             return {
                 evaluate: vi.fn().mockResolvedValue(2),
                 closeWindow,

package/dist/src/download/progress.js

@@ -1,7 +1,6 @@
 /**
  * Download progress display: terminal progress bars, status updates.
  */
-import { styleText } from 'node:util';
 /**
  * Format bytes as human-readable string (KB, MB, GB).
  */
@@ -35,33 +34,38 @@ export function formatDuration(ms) {
  * Create a simple progress bar for terminal display.
  */
 export function createProgressBar(filename, index, total) {
-    const prefix = styleText('dim', `[${index + 1}/${total}]`);
+    const prefix = `[${index + 1}/${total}]`;
     const truncatedName = filename.length > 40 ? filename.slice(0, 37) + '...' : filename;
     return {
         update(current, totalBytes, label) {
-            const percent = totalBytes > 0 ? Math.round((current / totalBytes) * 100) : 0;
+            const percent = clampPercent(totalBytes > 0 ? Math.round((current / totalBytes) * 100) : 0);
             const bar = createBar(percent);
             const size = totalBytes > 0 ? formatBytes(totalBytes) : '';
             const extra = label ? ` ${label}` : '';
             process.stderr.write(`\r${prefix} ${truncatedName} ${bar} ${percent}% ${size}${extra}`);
         },
         complete(success, message) {
-            const icon = success ? styleText('green', '✓') : styleText('red', '✗');
-            const msg = message ? ` ${styleText('dim', message)}` : '';
+            const icon = success ? '✓' : '✗';
+            const msg = message ? ` ${message}` : '';
             process.stderr.write(`\r${prefix} ${icon} ${truncatedName}${msg}\n`);
         },
         fail(error) {
-            process.stderr.write(`\r${prefix} ${styleText('red', '✗')} ${truncatedName} ${styleText('red', error)}\n`);
+            process.stderr.write(`\r${prefix} ✗ ${truncatedName} ${error}\n`);
         },
     };
 }
+function clampPercent(percent) {
+    if (!Number.isFinite(percent))
+        return 0;
+    return Math.max(0, Math.min(100, percent));
+}
 /**
  * Create a progress bar string.
  */
 function createBar(percent, width = 20) {
     const filled = Math.round((percent / 100) * width);
     const empty = width - filled;
-    return styleText('cyan', '█'.repeat(filled)) + styleText('dim', '░'.repeat(empty));
+    return '█'.repeat(filled) + '░'.repeat(empty);
 }
 /**
  * Multi-file download progress tracker.
@@ -98,19 +102,19 @@ export class DownloadProgressTracker {
         const elapsed = formatDuration(Date.now() - this.startTime);
         const parts = [];
         if (this.completed > 0) {
-            parts.push(styleText('green', `${this.completed} downloaded`));
+            parts.push(`${this.completed} downloaded`);
         }
         if (this.skipped > 0) {
-            parts.push(styleText('yellow', `${this.skipped} skipped`));
+            parts.push(`${this.skipped} skipped`);
         }
         if (this.failed > 0) {
-            parts.push(styleText('red', `${this.failed} failed`));
+            parts.push(`${this.failed} failed`);
         }
         return `${parts.join(', ')} in ${elapsed}`;
     }
     finish() {
         if (this.verbose) {
-            process.stderr.write(`\n${styleText('bold', 'Download complete:')} ${this.getSummary()}\n`);
+            process.stderr.write(`\nDownload complete: ${this.getSummary()}\n`);
         }
     }
 }

package/dist/src/download/progress.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/download/progress.test.js

@@ -0,0 +1,25 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { createProgressBar } from './progress.js';
+describe('download progress display', () => {
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+    it('clamps percentages above 100 to keep the progress bar renderable', () => {
+        const write = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+        const progress = createProgressBar('file.bin', 0, 1);
+        expect(() => progress.update(150, 100)).not.toThrow();
+        expect(write).toHaveBeenCalledWith(expect.stringContaining('100%'));
+    });
+    it('clamps negative percentages to zero', () => {
+        const write = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+        const progress = createProgressBar('file.bin', 0, 1);
+        expect(() => progress.update(-10, 100)).not.toThrow();
+        expect(write).toHaveBeenCalledWith(expect.stringContaining('0%'));
+    });
+    it('renders zero percent when the total size is unknown', () => {
+        const write = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+        const progress = createProgressBar('file.bin', 0, 1);
+        expect(() => progress.update(50, 0)).not.toThrow();
+        expect(write).toHaveBeenCalledWith(expect.stringContaining('0%'));
+    });
+});

package/dist/src/execution.js

@@ -467,9 +467,7 @@ function normalizeBooleanOption(name, raw) {
 function resolveKeepTab(siteSession, rawOption) {
     if (siteSession === 'persistent')
         return true;
-    return normalizeBooleanOption('--keep-tab', rawOption)
-        ?? normalizeBooleanOption('OPENCLI_KEEP_TAB', process.env.OPENCLI_KEEP_TAB)
-        ?? false;
+    return normalizeBooleanOption('--keep-tab', rawOption) ?? false;
 }
 function normalizeWindowMode(name, raw) {
     if (raw === undefined || raw === '')

package/dist/src/execution.test.js

@@ -370,13 +370,11 @@ describe('executeCommand — non-browser timeout', () => {
         expect(closeWindow).toHaveBeenCalledTimes(1);
         vi.restoreAllMocks();
     });
-    it('skips closeWindow when OPENCLI_KEEP_TAB=true (success path)', async () => {
+    it('skips closeWindow when --keep-tab=true (success path)', async () => {
         const closeWindow = vi.fn().mockResolvedValue(undefined);
         const mockPage = { closeWindow };
         vi.spyOn(capRouting, 'shouldUseBrowserSession').mockReturnValue(true);
         vi.spyOn(runtime, 'browserSession').mockImplementation(async (_Factory, fn) => fn(mockPage));
-        const prev = process.env.OPENCLI_KEEP_TAB;
-        process.env.OPENCLI_KEEP_TAB = 'true';
         try {
             const cmd = cli({
                 site: 'test-execution',
@@ -386,24 +384,18 @@ describe('executeCommand — non-browser timeout', () => {
                 strategy: Strategy.PUBLIC,
                 func: async () => [{ ok: true }],
             });
-            await executeCommand(cmd, {});
+            await executeCommand(cmd, {}, false, { keepTab: 'true' });
             expect(closeWindow).not.toHaveBeenCalled();
         }
         finally {
-            if (prev === undefined)
-                delete process.env.OPENCLI_KEEP_TAB;
-            else
-                process.env.OPENCLI_KEEP_TAB = prev;
             vi.restoreAllMocks();
         }
     });
-    it('skips closeWindow when OPENCLI_KEEP_TAB=true (failure path)', async () => {
+    it('skips closeWindow when --keep-tab=true (failure path)', async () => {
         const closeWindow = vi.fn().mockResolvedValue(undefined);
         const mockPage = { closeWindow };
         vi.spyOn(capRouting, 'shouldUseBrowserSession').mockReturnValue(true);
         vi.spyOn(runtime, 'browserSession').mockImplementation(async (_Factory, fn) => fn(mockPage));
-        const prev = process.env.OPENCLI_KEEP_TAB;
-        process.env.OPENCLI_KEEP_TAB = 'true';
         try {
             const cmd = cli({
                 site: 'test-execution',
@@ -413,14 +405,10 @@ describe('executeCommand — non-browser timeout', () => {
                 strategy: Strategy.PUBLIC,
                 func: async () => { throw new Error('adapter failure'); },
             });
-            await expect(executeCommand(cmd, {})).rejects.toThrow('adapter failure');
+            await expect(executeCommand(cmd, {}, false, { keepTab: 'true' })).rejects.toThrow('adapter failure');
             expect(closeWindow).not.toHaveBeenCalled();
         }
         finally {
-            if (prev === undefined)
-                delete process.env.OPENCLI_KEEP_TAB;
-            else
-                process.env.OPENCLI_KEEP_TAB = prev;
             vi.restoreAllMocks();
         }
     });

package/dist/src/help.d.ts

@@ -47,6 +47,17 @@ export interface RootAdapterGroups {
     sites: readonly string[];
 }
 export declare function formatRootAdapterHelpText(groups: RootAdapterGroups): string;
+/**
+ * Extracts a positional placeholder that should appear immediately after this
+ * command's name in user-facing path strings. Reads the leading positional
+ * (e.g. `<session>`) from a `.usage()` override; commands without a positional
+ * override return `null` so the path stays as-is.
+ *
+ * Example: `browser` declares `.usage('<session> <command> [options]')`,
+ * so `commanderPath(browserClickCmd)` becomes
+ * `['opencli', 'browser', '<session>', 'click']`.
+ */
+export declare function leadingPositionalFromUsage(command: Command): string | null;
 export declare function commanderNamespaceHelpData(namespaceRoot: Command, opts?: {
     globalCommand?: Command;
     description?: string;

package/dist/src/help.js

@@ -175,13 +175,42 @@ function compactCommanderOptions(options) {
         .map(compactCommanderOption)
         .filter((option) => option !== null);
 }
+/**
+ * Extracts a positional placeholder that should appear immediately after this
+ * command's name in user-facing path strings. Reads the leading positional
+ * (e.g. `<session>`) from a `.usage()` override; commands without a positional
+ * override return `null` so the path stays as-is.
+ *
+ * Example: `browser` declares `.usage('<session> <command> [options]')`,
+ * so `commanderPath(browserClickCmd)` becomes
+ * `['opencli', 'browser', '<session>', 'click']`.
+ */
+export function leadingPositionalFromUsage(command) {
+    const usage = command._usage;
+    if (!usage)
+        return null;
+    const match = usage.match(/^\s*(<[^>]+>)/);
+    return match ? match[1] : null;
+}
 function commanderPath(command) {
     const parts = [];
     let current = command;
     while (current) {
         const name = current.name();
-        if (name)
+        if (name) {
             parts.push(name);
+            // If this command declares a leading-positional usage override AND we
+            // have already collected a child name below it, the positional must
+            // appear between this command and the child (i.e. before the names
+            // already collected). parts is in reverse order, so push to the end.
+            const positional = leadingPositionalFromUsage(current);
+            if (positional && parts.length > 1) {
+                // We collected child names first (reverse order). Move them up by one
+                // and put the positional at index `parts.length - 2` so reverse()
+                // places it between this command and the first child name.
+                parts.splice(parts.length - 1, 0, positional);
+            }
+        }
         current = current.parent;
     }
     return parts.reverse();
@@ -189,7 +218,10 @@ function commanderPath(command) {
 function commandPathFromRoot(namespaceRoot, command) {
     const rootPath = commanderPath(namespaceRoot);
     const commandPath = commanderPath(command);
-    return commandPath.slice(rootPath.length);
+    // Strip placeholder positional segments (e.g. `<session>`) from the relative
+    // name so agents can still address subcommands by their leaf name. Display
+    // paths in `command` / `usage` still include the placeholders.
+    return commandPath.slice(rootPath.length).filter(part => !/^<.+>$/.test(part));
 }
 function collectLeafCommands(command) {
     if (command.commands.length === 0)
@@ -232,10 +264,19 @@ export function commanderNamespaceHelpData(namespaceRoot, opts = {}) {
     const leaves = collectLeafCommands(namespaceRoot)
         .filter(command => command !== namespaceRoot)
         .sort((a, b) => commandPathFromRoot(namespaceRoot, a).join(' ').localeCompare(commandPathFromRoot(namespaceRoot, b).join(' ')));
+    // Respect commander's `.usage()` override (e.g. `<session> <command> [options]`
+    // on `browser`); fall back to the generic `<command> [args] [options]` form.
+    // Read the private `_usage` field directly because `.usage()` returns the
+    // auto-generated form if no override was set.
+    const commandPath = commanderPath(namespaceRoot).join(' ');
+    const usageOverride = namespaceRoot._usage;
+    const usage = usageOverride
+        ? `${commandPath} ${usageOverride}`
+        : `${commandPath} <command> [args] [options]`;
     return {
         namespace: namespaceRoot.name(),
-        command: commanderPath(namespaceRoot).join(' '),
-        usage: `${commanderPath(namespaceRoot).join(' ')} <command> [args] [options]`,
+        command: commandPath,
+        usage,
         description: opts.description ?? namespaceRoot.description(),
         command_count: leaves.length,
         commands: leaves.map(command => compactCommanderCommand(namespaceRoot, command, opts)),
@@ -243,7 +284,7 @@ export function commanderNamespaceHelpData(namespaceRoot, opts = {}) {
         ...(opts.globalCommand ? { global_options: compactCommanderOptions(opts.globalCommand.options) } : {}),
         structured_help: {
             formats: ['yaml', 'json'],
-            usage: `${commanderPath(namespaceRoot).join(' ')} --help -f yaml`,
+            usage: `${commandPath} --help -f yaml`,
         },
     };
 }

package/dist/src/logger.js

@@ -4,35 +4,34 @@
  * All framework output (warnings, debug info, errors) should go through
  * this module so that verbosity levels are respected consistently.
  */
-import { styleText } from 'node:util';
 function isVerbose() {
     return !!process.env.OPENCLI_VERBOSE;
 }
 export const log = {
     /** Informational message (always shown) */
     info(msg) {
-        process.stderr.write(`${styleText('blue', 'ℹ')}  ${msg}\n`);
+        process.stderr.write(`ℹ  ${msg}\n`);
     },
     /** Lightweight status line for adapter progress updates */
     status(msg) {
-        process.stderr.write(`${styleText('dim', msg)}\n`);
+        process.stderr.write(`${msg}\n`);
     },
     /** Positive completion/status line without the heavier info prefix */
     success(msg) {
-        process.stderr.write(`${styleText('green', msg)}\n`);
+        process.stderr.write(`${msg}\n`);
     },
     /** Warning (always shown) */
     warn(msg) {
-        process.stderr.write(`${styleText('yellow', '⚠')}  ${msg}\n`);
+        process.stderr.write(`⚠  ${msg}\n`);
     },
     /** Error (always shown) */
     error(msg) {
-        process.stderr.write(`${styleText('red', '✖')}  ${msg}\n`);
+        process.stderr.write(`✖  ${msg}\n`);
     },
     /** Verbose output (shown when -v flag or OPENCLI_VERBOSE is set) */
     verbose(msg) {
         if (isVerbose()) {
-            process.stderr.write(`${styleText('dim', '[verbose]')} ${msg}\n`);
+            process.stderr.write(`[verbose] ${msg}\n`);
         }
     },
     /** Alias for verbose output. */
@@ -41,10 +40,10 @@ export const log = {
     },
     /** Step-style debug (for pipeline steps, etc.) */
     step(stepNum, total, op, preview = '') {
-        process.stderr.write(`  ${styleText('dim', `[${stepNum}/${total}]`)} ${styleText(['bold', 'cyan'], op)}${preview}\n`);
+        process.stderr.write(`  [${stepNum}/${total}] ${op}${preview}\n`);
     },
     /** Step result summary */
     stepResult(summary) {
-        process.stderr.write(`       ${styleText('dim', `→ ${summary}`)}\n`);
+        process.stderr.write(`       → ${summary}\n`);
     },
 };

package/dist/src/main.js

@@ -139,5 +139,21 @@ if (getCompIdx !== -1) {
     process.stdout.write(candidates.join('\n') + '\n');
     process.exit(EXIT_CODES.SUCCESS);
 }
+// Rewrite `opencli browser <session> <subcommand> ...` so commander (which
+// can't combine a parent positional with subcommand dispatch) sees the internal
+// `--session <name>` flag form. Also refuses the retired `opencli browser
+// --session foo ...` user form with a friendly usage error.
+const { rewriteBrowserArgv, BrowserSessionArgvError } = await import('./cli-argv-preprocess.js');
+try {
+    const rewritten = rewriteBrowserArgv(process.argv.slice(2));
+    process.argv.splice(2, process.argv.length - 2, ...rewritten);
+}
+catch (err) {
+    if (err instanceof BrowserSessionArgvError) {
+        process.stderr.write(`error: ${err.message}\n`);
+        process.exit(EXIT_CODES.GENERIC_ERROR);
+    }
+    throw err;
+}
 await emitHook('onStartup', { command: '__startup__', args: {} });
 runCli(BUILTIN_CLIS, USER_CLIS);