@jackwener/opencli 1.7.16 → 1.7.17

package/dist/src/commanderAdapter.js

@@ -51,6 +51,7 @@ export function registerCommandToProgram(siteCmd, cmd) {
     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);
@@ -108,6 +109,7 @@ export function registerCommandToProgram(siteCmd, cmd) {
                 ...(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) {

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 windowRole = session.windowRole ? `, window=${session.windowRole}` : '';
-                    lines.push(styleText('dim', `  • ${session.workspace ?? 'default'} → ${target}, mode=${mode}${windowRole}, 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',
-                    windowRole: 'borrowed-user',
-                    tabCount: 1,
-                    idleMsRemaining: null,
-                },
-            ],
-        }));
-        expect(text).toContain('bound:default → tab 42, mode=borrowed, window=borrowed-user, 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',
-                    windowRole: 'borrowed-user',
-                    tabCount: 1,
-                    idleMsRemaining: null,
-                },
-                {
-                    contextId: 'personal',
-                    workspace: 'site:foo',
-                    windowId: 1,
-                    preferredTabId: 10,
-                    ownership: 'owned',
-                    windowRole: 'automation',
-                    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

@@ -18,6 +18,7 @@ export declare function executeCommand(cmd: CliCommand, rawKwargs: CommandArgs,
     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,10 +211,9 @@ 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 keepTab = resolveKeepTab(browserReuse, opts.keepTab);
+            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'
@@ -223,7 +221,7 @@ export async function executeCommand(cmd, rawKwargs, debug = false, opts = {}) {
                     : new ObservationSession({
                         scope: {
                             contextId,
-                            workspace,
+                            session,
                             target: page.getActivePage?.(),
                             site: cmd.site,
                             command: fullName(cmd),
@@ -240,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',
@@ -332,7 +330,7 @@ export async function executeCommand(cmd, rawKwargs, debug = false, opts = {}) {
                         await page.closeWindow?.().catch(() => { });
                     throw err;
                 }
-            }, { workspace, cdpEndpoint, contextId, idleTimeout, windowMode });
+            }, { session, cdpEndpoint, contextId, windowMode, surface: 'adapter', siteSession });
         }
         else {
             // Non-browser commands: enforce a timeout only when the command exposes
@@ -442,19 +440,18 @@ 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()}`;
 }
@@ -467,10 +464,12 @@ function normalizeBooleanOption(name, raw) {
         return false;
     throw new ArgumentError(`${name} must be one of: true, false. Received: "${String(raw)}"`);
 }
-function resolveKeepTab(reuse, rawOption) {
+function resolveKeepTab(siteSession, rawOption) {
+    if (siteSession === 'persistent')
+        return true;
     return normalizeBooleanOption('--keep-tab', rawOption)
         ?? normalizeBooleanOption('OPENCLI_KEEP_TAB', process.env.OPENCLI_KEEP_TAB)
-        ?? reuse !== 'none';
+        ?? false;
 }
 function normalizeWindowMode(name, raw) {
     if (raw === undefined || raw === '')

package/dist/src/execution.test.js

@@ -136,7 +136,7 @@ describe('executeCommand — non-browser timeout', () => {
         });
         vi.restoreAllMocks();
     });
-    it('reuses a site-scoped browser workspace and keeps the tab lease open', async () => {
+    it('reuses a persistent site browser session and keeps the tab lease open', async () => {
         const closeWindow = vi.fn().mockResolvedValue(undefined);
         const mockPage = { closeWindow };
         const sessionOpts = [];
@@ -147,22 +147,24 @@ describe('executeCommand — non-browser timeout', () => {
         });
         const cmd = cli({
             site: 'test-execution',
-            name: 'browser-reuse-site', access: 'read',
-            description: 'test site-scoped browser reuse',
+            name: 'site-session-persistent', access: 'read',
+            description: 'test persistent site session',
             browser: true,
             strategy: Strategy.PUBLIC,
-            browserSession: { reuse: 'site' },
+            siteSession: 'persistent',
             func: async () => [{ ok: true }],
         });
         await executeCommand(cmd, {});
-        await executeCommand(cmd, {});
+        await executeCommand(cmd, {}, false, { keepTab: 'false' });
         expect(sessionOpts).toHaveLength(2);
-        expect(sessionOpts[0]).toMatchObject({ workspace: 'site:test-execution', idleTimeout: 600, windowMode: 'background' });
-        expect(sessionOpts[1]).toMatchObject({ workspace: 'site:test-execution', idleTimeout: 600, windowMode: 'background' });
+        expect(sessionOpts[0]).toMatchObject({ session: 'site:test-execution', windowMode: 'background', siteSession: 'persistent' });
+        expect(sessionOpts[1]).toMatchObject({ session: 'site:test-execution', windowMode: 'background', siteSession: 'persistent' });
+        expect(sessionOpts[0]?.idleTimeout).toBeUndefined();
+        expect(sessionOpts[1]?.idleTimeout).toBeUndefined();
         expect(closeWindow).not.toHaveBeenCalled();
         vi.restoreAllMocks();
     });
-    it('keeps default browser commands on one-shot workspaces', async () => {
+    it('keeps default browser commands on one-shot adapter sessions', async () => {
         const closeWindow = vi.fn().mockResolvedValue(undefined);
         const mockPage = { closeWindow };
         const sessionOpts = [];
@@ -173,8 +175,8 @@ describe('executeCommand — non-browser timeout', () => {
         });
         const cmd = cli({
             site: 'test-execution',
-            name: 'browser-reuse-default', access: 'read',
-            description: 'test default one-shot browser workspace',
+            name: 'site-session-default', access: 'read',
+            description: 'test default one-shot browser session',
             browser: true,
             strategy: Strategy.PUBLIC,
             func: async () => [{ ok: true }],
@@ -182,9 +184,9 @@ describe('executeCommand — non-browser timeout', () => {
         await executeCommand(cmd, {});
         await executeCommand(cmd, {});
         expect(sessionOpts).toHaveLength(2);
-        expect(sessionOpts[0]?.workspace).toMatch(/^site:test-execution:/);
-        expect(sessionOpts[1]?.workspace).toMatch(/^site:test-execution:/);
-        expect(sessionOpts[0]?.workspace).not.toBe(sessionOpts[1]?.workspace);
+        expect(sessionOpts[0]?.session).toMatch(/^site:test-execution:/);
+        expect(sessionOpts[1]?.session).toMatch(/^site:test-execution:/);
+        expect(sessionOpts[0]?.session).not.toBe(sessionOpts[1]?.session);
         expect(sessionOpts[0]?.idleTimeout).toBeUndefined();
         expect(sessionOpts[1]?.idleTimeout).toBeUndefined();
         expect(sessionOpts[0]?.windowMode).toBe('background');
@@ -192,7 +194,7 @@ describe('executeCommand — non-browser timeout', () => {
         expect(closeWindow).toHaveBeenCalledTimes(2);
         vi.restoreAllMocks();
     });
-    it('lets user --reuse none override adapter reuse metadata', async () => {
+    it('lets user --site-session ephemeral override adapter persistent metadata', async () => {
         const closeWindow = vi.fn().mockResolvedValue(undefined);
         const mockPage = { closeWindow };
         const sessionOpts = [];
@@ -201,33 +203,27 @@ describe('executeCommand — non-browser timeout', () => {
             sessionOpts.push(opts ?? {});
             return fn(mockPage);
         });
-        const prev = process.env.OPENCLI_BROWSER_REUSE;
-        process.env.OPENCLI_BROWSER_REUSE = 'none';
         try {
             const cmd = cli({
                 site: 'test-execution',
-                name: 'browser-reuse-override-none', access: 'read',
-                description: 'test user reuse override',
+                name: 'site-session-override-ephemeral', access: 'read',
+                description: 'test user site-session override',
                 browser: true,
                 strategy: Strategy.PUBLIC,
-                browserSession: { reuse: 'site' },
+                siteSession: 'persistent',
                 func: async () => [{ ok: true }],
             });
-            await executeCommand(cmd, {});
+            await executeCommand(cmd, {}, false, { siteSession: 'ephemeral' });
             expect(sessionOpts).toHaveLength(1);
-            expect(sessionOpts[0]?.workspace).toMatch(/^site:test-execution:/);
+            expect(sessionOpts[0]?.session).toMatch(/^site:test-execution:/);
             expect(sessionOpts[0]?.idleTimeout).toBeUndefined();
             expect(closeWindow).toHaveBeenCalledTimes(1);
         }
         finally {
-            if (prev === undefined)
-                delete process.env.OPENCLI_BROWSER_REUSE;
-            else
-                process.env.OPENCLI_BROWSER_REUSE = prev;
             vi.restoreAllMocks();
         }
     });
-    it('skips repeated domain pre-navigation for site-reused browser sessions', async () => {
+    it('skips repeated domain pre-navigation for persistent site sessions', async () => {
         const closeWindow = vi.fn().mockResolvedValue(undefined);
         const goto = vi.fn().mockResolvedValue(undefined);
         const mockPage = {
@@ -239,12 +235,12 @@ describe('executeCommand — non-browser timeout', () => {
         vi.spyOn(runtime, 'browserSession').mockImplementation(async (_Factory, fn) => fn(mockPage));
         const cmd = cli({
             site: 'test-execution',
-            name: 'browser-reuse-skip-prenav', access: 'read',
+            name: 'site-session-skip-prenav', access: 'read',
             description: 'test reused same-domain tabs do not reset conversation state',
             browser: true,
             strategy: Strategy.COOKIE,
             domain: 'grok.com',
-            browserSession: { reuse: 'site' },
+            siteSession: 'persistent',
             func: async () => [{ ok: true }],
         });
         await executeCommand(cmd, {});
@@ -252,7 +248,7 @@ describe('executeCommand — non-browser timeout', () => {
         expect(closeWindow).not.toHaveBeenCalled();
         vi.restoreAllMocks();
     });
-    it('keeps explicit path pre-navigation for site-reused browser sessions', async () => {
+    it('keeps explicit path pre-navigation for persistent site sessions', async () => {
         const closeWindow = vi.fn().mockResolvedValue(undefined);
         const goto = vi.fn().mockResolvedValue(undefined);
         const mockPage = {
@@ -264,13 +260,13 @@ describe('executeCommand — non-browser timeout', () => {
         vi.spyOn(runtime, 'browserSession').mockImplementation(async (_Factory, fn) => fn(mockPage));
         const cmd = cli({
             site: 'test-execution',
-            name: 'browser-reuse-path-prenav', access: 'read',
+            name: 'site-session-path-prenav', access: 'read',
             description: 'test explicit path pre-navigation still runs',
             browser: true,
             strategy: Strategy.COOKIE,
             domain: 'example.com',
             navigateBefore: 'https://example.com/dashboard',
-            browserSession: { reuse: 'site' },
+            siteSession: 'persistent',
             func: async () => [{ ok: true }],
         });
         await executeCommand(cmd, {});