@jackwener/opencli 1.7.15 → 1.7.17

package/dist/src/commanderAdapter.js

@@ -48,6 +48,12 @@ export function registerCommandToProgram(siteCmd, cmd) {
         .option('-f, --format <fmt>', 'Output format: table, plain, json, yaml, md, csv', 'table')
         .option('--trace <mode>', 'Trace capture: off, on, retain-on-failure', 'off')
         .option('-v, --verbose', 'Debug output', false);
+    if (cmd.browser) {
+        subCmd
+            .option('--window <mode>', 'Browser window mode: foreground or background')
+            .option('--site-session <mode>', 'Adapter site session lifecycle: ephemeral or persistent')
+            .option('--keep-tab <bool>', 'Keep the browser tab lease after the command finishes');
+    }
     const originalHelpInformation = subCmd.helpInformation.bind(subCmd);
     subCmd.helpInformation = ((contextOptions) => {
         const format = getRequestedHelpFormat();
@@ -102,6 +108,9 @@ export function registerCommandToProgram(siteCmd, cmd) {
                 prepared: true,
                 ...(typeof globals.profile === 'string' && globals.profile.trim() ? { profile: globals.profile.trim() } : {}),
                 ...(typeof optionsRecord.trace === 'string' && optionsRecord.trace !== 'off' ? { trace: optionsRecord.trace } : {}),
+                ...(cmd.browser && typeof optionsRecord.window === 'string' ? { windowMode: optionsRecord.window } : {}),
+                ...(cmd.browser && typeof optionsRecord.siteSession === 'string' ? { siteSession: optionsRecord.siteSession } : {}),
+                ...(cmd.browser && typeof optionsRecord.keepTab === 'string' ? { keepTab: optionsRecord.keepTab } : {}),
             });
             if (result === null || result === undefined) {
                 return;

package/dist/src/discovery.js

@@ -135,7 +135,7 @@ async function loadFromManifest(manifestPath, clisDir) {
                 pipeline: entry.pipeline,
                 source: entry.sourceFile ? path.resolve(clisDir, entry.sourceFile) : modulePath,
                 navigateBefore: entry.navigateBefore,
-                browserSession: entry.browserSession,
+                siteSession: entry.siteSession,
                 _lazy: true,
                 _modulePath: modulePath,
             };

package/dist/src/doctor.d.ts

@@ -3,13 +3,10 @@
  *
  * Simplified for the daemon-based architecture.
  */
-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;
-    sessions?: boolean;
     cliVersion?: string;
 };
 export type ConnectivityResult = {
@@ -28,7 +25,6 @@ export type DoctorReport = {
     extensionVersion?: string;
     latestExtensionVersion?: string;
     connectivity?: ConnectivityResult;
-    sessions?: BrowserSessionInfo[];
     profiles?: BrowserProfileStatus[];
     adapterShadows?: AdapterShadow[];
     issues: string[];

package/dist/src/doctor.js

@@ -6,7 +6,7 @@
 import { styleText } from 'node:util';
 import { DEFAULT_DAEMON_PORT } from './constants.js';
 import { BrowserBridge } from './browser/index.js';
-import { getDaemonHealth, listSessions } from './browser/daemon-client.js';
+import { getDaemonHealth } from './browser/daemon-client.js';
 import { getErrorMessage } from './errors.js';
 import { getRuntimeLabel } from './runtime-detect.js';
 import { getCachedLatestExtensionVersion } from './update-check.js';
@@ -66,47 +66,17 @@ export async function checkConnectivity(opts) {
     }
 }
 export async function runBrowserDoctor(opts = {}) {
-    // Live connectivity check doubles as auto-start (bridge.connect spawns daemon).
-    let connectivity;
-    if (opts.live) {
-        connectivity = await checkConnectivity();
-    }
-    else {
-        // No live probe — daemon may have idle-exited. Do a minimal auto-start
-        // so we don't misreport a lazy-lifecycle stop as a real failure.
-        const initialHealth = await getDaemonHealth();
-        if (initialHealth.state === 'stopped') {
-            try {
-                const bridge = new BrowserBridge();
-                await bridge.connect({ timeout: 5 });
-                await bridge.close();
-            }
-            catch {
-                // Auto-start failed; we'll report it below.
-            }
-        }
-    }
-    // Single status read *after* all side-effects (live check / auto-start) settle.
+    // Live connectivity check is the core of doctor — it doubles as auto-start
+    // (bridge.connect spawns daemon) and validates end-to-end browser bridge health.
+    const connectivity = await checkConnectivity();
+    // Single status read *after* connectivity side-effects settle.
     const health = await getDaemonHealth();
     const daemonRunning = health.state !== 'stopped';
     const extensionConnected = health.state === 'ready';
-    const daemonFlaky = !!(connectivity?.ok && !daemonRunning);
-    const extensionFlaky = !!(connectivity?.ok && daemonRunning && !extensionConnected);
+    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) {
-        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 adapterShadows = findShadowedUserAdapters();
     const issues = [];
@@ -147,7 +117,7 @@ export async function runBrowserDoctor(opts = {}) {
             '  This usually means an outdated Browser Bridge extension.\n' +
             '  Reload or reinstall the extension from: https://github.com/jackwener/opencli/releases');
     }
-    if (connectivity && !connectivity.ok) {
+    if (!connectivity.ok) {
         issues.push(`Browser connectivity test failed: ${connectivity.error ?? 'unknown'}`);
     }
     const extensionCompatRange = health.status?.extensionCompatRange;
@@ -187,7 +157,6 @@ export async function runBrowserDoctor(opts = {}) {
         extensionVersion,
         latestExtensionVersion,
         connectivity,
-        sessions,
         profiles,
         adapterShadows,
         issues,
@@ -244,39 +213,6 @@ export function renderBrowserDoctorReport(report) {
             : `failed (${report.connectivity.error ?? 'unknown'})`;
         lines.push(`${connIcon} Connectivity: ${detail}`);
     }
-    else {
-        lines.push(`${styleText('dim', '[SKIP]')} Connectivity: skipped (--no-live)`);
-    }
-    if (report.sessions) {
-        lines.push('', styleText('bold', 'Sessions:'));
-        if (report.sessions.length === 0) {
-            lines.push(styleText('dim', '  • no active automation sessions'));
-        }
-        else {
-            const byContext = new Map();
-            for (const session of report.sessions) {
-                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}`));
-                }
-            }
-        }
-    }
     if (report.issues.length) {
         lines.push('', styleText('yellow', 'Issues:'));
         for (const issue of report.issues) {

package/dist/src/doctor.test.js

@@ -1,14 +1,12 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest';
-const { mockGetDaemonHealth, mockListSessions, mockConnect, mockClose, mockFindShadowedUserAdapters } = vi.hoisted(() => ({
+const { mockGetDaemonHealth, 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,
-    listSessions: mockListSessions,
 }));
 vi.mock('./browser/index.js', () => ({
     BrowserBridge: class {
@@ -29,6 +27,12 @@ describe('doctor report rendering', () => {
     beforeEach(() => {
         vi.clearAllMocks();
         mockFindShadowedUserAdapters.mockReturnValue([]);
+        // Doctor always runs live connectivity. Tests that want connect to fail override.
+        mockConnect.mockResolvedValue({
+            evaluate: vi.fn().mockResolvedValue(2),
+            closeWindow: vi.fn().mockResolvedValue(undefined),
+        });
+        mockClose.mockResolvedValue(undefined);
     });
     it('renders OK-style report when daemon and extension connected', () => {
         const text = strip(renderBrowserDoctorReport({
@@ -97,34 +101,7 @@ describe('doctor report rendering', () => {
         }));
         expect(text).toContain('[OK] Connectivity: connected in 1.2s');
     });
-    it('renders connectivity SKIP when not tested', () => {
-        const text = strip(renderBrowserDoctorReport({
-            daemonRunning: true,
-            extensionConnected: true,
-            issues: [],
-        }));
-        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', () => {
+    it('renders connected profiles when multiple are present', () => {
         const text = strip(renderBrowserDoctorReport({
             daemonRunning: true,
             extensionConnected: false,
@@ -133,35 +110,10 @@ describe('doctor report rendering', () => {
                 { 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');
+        expect(text).toContain('personal: connected v1.2.3');
     });
     it('renders unstable extension state when live connectivity and status disagree', () => {
         const text = strip(renderBrowserDoctorReport({
@@ -185,25 +137,20 @@ describe('doctor report rendering', () => {
         expect(text).toContain('[WARN] Daemon: unstable');
         expect(text).toContain('Daemon connectivity is unstable.');
     });
-    it('reports daemon not running when no-live and auto-start fails', async () => {
-        mockGetDaemonHealth.mockResolvedValueOnce({ state: 'stopped', status: null });
+    it('reports daemon not running when connectivity fails and daemon stays stopped', async () => {
         mockConnect.mockRejectedValueOnce(new Error('Could not start daemon'));
         mockGetDaemonHealth.mockResolvedValueOnce({ state: 'stopped', status: null });
-        const report = await runBrowserDoctor({ live: false });
+        const report = await runBrowserDoctor();
         expect(report.daemonRunning).toBe(false);
         expect(report.extensionConnected).toBe(false);
-        expect(mockGetDaemonHealth).toHaveBeenCalledTimes(2);
+        expect(report.connectivity?.ok).toBe(false);
         expect(report.issues).toEqual(expect.arrayContaining([
             expect.stringContaining('Daemon is not running'),
         ]));
     });
     it('reports flapping when live check succeeds but final status shows extension disconnected', async () => {
-        mockConnect.mockResolvedValueOnce({
-            evaluate: vi.fn().mockResolvedValue(2),
-        });
-        mockClose.mockResolvedValueOnce(undefined);
         mockGetDaemonHealth.mockResolvedValueOnce({ state: 'no-extension', status: { extensionConnected: false } });
-        const report = await runBrowserDoctor({ live: true });
+        const report = await runBrowserDoctor();
         expect(report.daemonRunning).toBe(true);
         expect(report.extensionConnected).toBe(false);
         expect(report.extensionFlaky).toBe(true);
@@ -212,12 +159,8 @@ describe('doctor report rendering', () => {
         ]));
     });
     it('reports daemon flapping when live check succeeds but daemon disappears afterward', async () => {
-        mockConnect.mockResolvedValueOnce({
-            evaluate: vi.fn().mockResolvedValue(2),
-        });
-        mockClose.mockResolvedValueOnce(undefined);
         mockGetDaemonHealth.mockResolvedValueOnce({ state: 'stopped', status: null });
-        const report = await runBrowserDoctor({ live: true });
+        const report = await runBrowserDoctor();
         expect(report.daemonRunning).toBe(false);
         expect(report.daemonFlaky).toBe(true);
         expect(report.extensionConnected).toBe(false);
@@ -235,20 +178,11 @@ describe('doctor report rendering', () => {
                 closeWindow,
             };
         });
-        mockClose.mockResolvedValueOnce(undefined);
         mockGetDaemonHealth.mockResolvedValueOnce({ state: 'ready', status: { extensionConnected: true } });
-        await runBrowserDoctor({ live: true });
+        await runBrowserDoctor();
         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 } });
-        mockGetDaemonHealth.mockResolvedValueOnce({ state: 'no-extension', status: { extensionConnected: false } });
-        const report = await runBrowserDoctor({ live: false });
-        expect(mockConnect).not.toHaveBeenCalled();
-        expect(report.daemonRunning).toBe(true);
-        expect(report.extensionConnected).toBe(false);
-    });
     it('reports an issue when the extension is connected but does not report a version', async () => {
         const status = {
             state: 'ready',
@@ -257,10 +191,8 @@ describe('doctor report rendering', () => {
                 extensionVersion: undefined,
             },
         };
-        mockGetDaemonHealth
-            .mockResolvedValueOnce(status)
-            .mockResolvedValueOnce(status);
-        const report = await runBrowserDoctor({ live: false });
+        mockGetDaemonHealth.mockResolvedValue(status);
+        const report = await runBrowserDoctor();
         expect(report.issues).toEqual(expect.arrayContaining([
             expect.stringContaining('did not report a version'),
         ]));
@@ -274,10 +206,8 @@ describe('doctor report rendering', () => {
                 extensionVersion: '1.0.3',
             },
         };
-        mockGetDaemonHealth
-            .mockResolvedValueOnce(status)
-            .mockResolvedValueOnce(status);
-        const report = await runBrowserDoctor({ live: false, cliVersion: '1.7.9' });
+        mockGetDaemonHealth.mockResolvedValue(status);
+        const report = await runBrowserDoctor({ 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'),
@@ -292,9 +222,7 @@ describe('doctor report rendering', () => {
                 extensionVersion: '1.0.3',
             },
         };
-        mockGetDaemonHealth
-            .mockResolvedValueOnce(status)
-            .mockResolvedValueOnce(status);
+        mockGetDaemonHealth.mockResolvedValue(status);
         mockFindShadowedUserAdapters.mockReturnValueOnce([
             {
                 name: 'instagram/saved',
@@ -302,7 +230,7 @@ describe('doctor report rendering', () => {
                 builtinPath: '/pkg/clis/instagram/saved.js',
             },
         ]);
-        const report = await runBrowserDoctor({ live: false, cliVersion: '1.7.9' });
+        const report = await runBrowserDoctor({ cliVersion: '1.7.9' });
         expect(report.adapterShadows).toHaveLength(1);
         expect(report.issues).toEqual(expect.arrayContaining([
             expect.stringContaining('Local adapter overrides shadow packaged adapters'),
@@ -320,10 +248,11 @@ describe('doctor report rendering', () => {
                 ],
             },
         };
-        mockGetDaemonHealth
-            .mockResolvedValueOnce(status)
-            .mockResolvedValueOnce(status);
-        const report = await runBrowserDoctor({ live: false });
+        mockGetDaemonHealth.mockResolvedValue(status);
+        // Real connectivity would fail in profile-required state; force it here so
+        // the test exercises the profile-required issue path, not the flaky path.
+        mockConnect.mockRejectedValueOnce(new Error('profile required'));
+        const report = await runBrowserDoctor();
         expect(report.profiles).toHaveLength(2);
         expect(report.issues).toEqual(expect.arrayContaining([
             expect.stringContaining('Multiple Chrome profiles are connected'),

package/dist/src/execution.d.ts

@@ -16,6 +16,9 @@ export declare function executeCommand(cmd: CliCommand, rawKwargs: CommandArgs,
     prepared?: boolean;
     profile?: string;
     trace?: string;
+    keepTab?: string;
+    windowMode?: string;
+    siteSession?: string;
     onTraceExport?: (trace: ObservationExportResult) => void;
 }): Promise<unknown>;
 export declare function prepareCommandArgs(cmd: CliCommand, rawKwargs: CommandArgs): CommandArgs;

package/dist/src/execution.js

@@ -29,7 +29,6 @@ const _loadedModules = new Map();
 /** Track mtime of loaded user adapter files for hot-reload in daemon mode. */
 const _moduleMtimes = new Map();
 const _userClisDir = `${os.homedir()}/.opencli/clis/`;
-const INTERACTIVE_BROWSER_IDLE_TIMEOUT_SECONDS = 600;
 function normalizeTraceMode(raw) {
     if (raw === undefined || raw === null || raw === '' || raw === 'off')
         return 'off';
@@ -164,8 +163,8 @@ function isDomainRootPreNav(preNavUrl, domain) {
         return false;
     }
 }
-async function shouldRunPreNav(cmd, page, reuse, preNavUrl) {
-    if (reuse !== 'site' || !cmd.domain)
+async function shouldRunPreNav(cmd, page, siteSession, preNavUrl) {
+    if (siteSession !== 'persistent' || !cmd.domain)
         return true;
     if (!isDomainRootPreNav(preNavUrl, cmd.domain))
         return true;
@@ -212,16 +211,17 @@ export async function executeCommand(cmd, rawKwargs, debug = false, opts = {}) {
             const BrowserFactory = getBrowserFactory(cmd.site);
             const contextId = resolveProfileContextId(opts.profile);
             const internal = cmd;
-            const browserReuse = resolveBrowserSessionReuse(cmd);
-            const workspace = resolveBrowserWorkspace(cmd, browserReuse);
-            const idleTimeout = browserReuse === 'site' ? INTERACTIVE_BROWSER_IDLE_TIMEOUT_SECONDS : undefined;
+            const siteSession = resolveSiteSession(cmd, opts.siteSession);
+            const session = resolveAdapterBrowserSession(cmd, siteSession);
+            const keepTab = resolveKeepTab(siteSession, opts.keepTab);
+            const windowMode = resolveBrowserWindowMode('background', opts.windowMode);
             result = await browserSession(BrowserFactory, async (page) => {
                 const observation = traceMode === 'off'
                     ? null
                     : new ObservationSession({
                         scope: {
                             contextId,
-                            workspace,
+                            session,
                             target: page.getActivePage?.(),
                             site: cmd.site,
                             command: fullName(cmd),
@@ -238,7 +238,7 @@ export async function executeCommand(cmd, rawKwargs, debug = false, opts = {}) {
                     await page.startNetworkCapture?.().catch(() => false);
                 }
                 const preNavUrl = resolvePreNav(cmd);
-                if (preNavUrl && await shouldRunPreNav(cmd, page, browserReuse, preNavUrl)) {
+                if (preNavUrl && await shouldRunPreNav(cmd, page, siteSession, preNavUrl)) {
                     observation?.record({
                         stream: 'action',
                         name: 'pre_navigate',
@@ -281,9 +281,6 @@ export async function executeCommand(cmd, rawKwargs, debug = false, opts = {}) {
                         throw wrapped;
                     }
                 }
-                // --live / OPENCLI_LIVE=1 keeps the current automation tab lease after
-                // the command finishes, so agents (or humans) can inspect the page state.
-                const keepOpen = browserReuse !== 'none' || process.env.OPENCLI_LIVE === '1' || process.env.OPENCLI_LIVE === 'true';
                 try {
                     const browserTimeout = userTimeoutSec !== null
                         ? userTimeoutSec + RUNTIME_TIMEOUT_PADDING_SECONDS
@@ -304,7 +301,7 @@ export async function executeCommand(cmd, rawKwargs, debug = false, opts = {}) {
                     // Adapter commands are one-shot — release the current tab lease immediately
                     // instead of waiting for the 30s idle timeout. The automation container
                     // window stays open for reuse.
-                    if (!keepOpen)
+                    if (!keepTab)
                         await page.closeWindow?.().catch(() => { });
                     return result;
                 }
@@ -329,11 +326,11 @@ export async function executeCommand(cmd, rawKwargs, debug = false, opts = {}) {
                     // Release the tab lease on failure too — without this, the lease lingers
                     // until the extension's idle timer fires (unreliable on Windows where
                     // MV3 service workers may be suspended before setTimeout triggers).
-                    if (!keepOpen)
+                    if (!keepTab)
                         await page.closeWindow?.().catch(() => { });
                     throw err;
                 }
-            }, { workspace, cdpEndpoint, contextId, idleTimeout });
+            }, { session, cdpEndpoint, contextId, windowMode, surface: 'adapter', siteSession });
         }
         else {
             // Non-browser commands: enforce a timeout only when the command exposes
@@ -443,22 +440,49 @@ export function prepareCommandArgs(cmd, rawKwargs) {
  * the runtime kills the Promise.
  */
 const RUNTIME_TIMEOUT_PADDING_SECONDS = 30;
-function readEnvBrowserSessionReuse() {
-    const raw = process.env.OPENCLI_BROWSER_REUSE;
-    if (raw === undefined || raw === '')
+function normalizeSiteSession(raw) {
+    if (raw === undefined || raw === null || raw === '')
         return null;
-    if (raw === 'none' || raw === 'site')
+    if (raw === 'ephemeral' || raw === 'persistent')
         return raw;
-    throw new ArgumentError(`--reuse must be one of: none, site. Received: "${raw}"`);
+    throw new ArgumentError(`--site-session must be one of: ephemeral, persistent. Received: "${String(raw)}"`);
 }
-function resolveBrowserSessionReuse(cmd) {
-    return readEnvBrowserSessionReuse() ?? cmd.browserSession?.reuse ?? 'none';
+function resolveSiteSession(cmd, rawOption) {
+    return normalizeSiteSession(rawOption) ?? cmd.siteSession ?? 'ephemeral';
 }
-function resolveBrowserWorkspace(cmd, reuse) {
-    if (reuse === 'site')
+function resolveAdapterBrowserSession(cmd, siteSession) {
+    if (siteSession === 'persistent')
         return `site:${cmd.site}`;
     return `site:${cmd.site}:${crypto.randomUUID()}`;
 }
+function normalizeBooleanOption(name, raw) {
+    if (raw === undefined || raw === '')
+        return null;
+    if (raw === 'true')
+        return true;
+    if (raw === 'false')
+        return false;
+    throw new ArgumentError(`${name} must be one of: true, false. Received: "${String(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;
+}
+function normalizeWindowMode(name, raw) {
+    if (raw === undefined || raw === '')
+        return null;
+    if (raw === 'foreground' || raw === 'background')
+        return raw;
+    throw new ArgumentError(`${name} must be one of: foreground, background. Received: "${String(raw)}"`);
+}
+function resolveBrowserWindowMode(defaultMode = 'background', rawOption) {
+    return normalizeWindowMode('--window', rawOption)
+        ?? normalizeWindowMode('OPENCLI_WINDOW', process.env.OPENCLI_WINDOW)
+        ?? defaultMode;
+}
 /**
  * Resolve the user-controllable `--timeout` arg, in seconds.
  *