@jackwener/opencli 1.7.11 → 1.7.13

package/dist/src/convention-audit.test.js

@@ -0,0 +1,226 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { renderConventionAuditText, runConventionAudit } from './convention-audit.js';
+describe('convention audit', () => {
+    const tempDirs = [];
+    afterEach(() => {
+        for (const dir of tempDirs.splice(0)) {
+            fs.rmSync(dir, { recursive: true, force: true });
+        }
+    });
+    function makeProject(manifest, files) {
+        const root = fs.mkdtempSync(path.join(os.tmpdir(), 'opencli-convention-audit-'));
+        tempDirs.push(root);
+        fs.mkdirSync(path.join(root, 'clis'), { recursive: true });
+        fs.writeFileSync(path.join(root, 'cli-manifest.json'), JSON.stringify(manifest, null, 2));
+        for (const [relative, content] of Object.entries(files)) {
+            const file = path.join(root, 'clis', relative);
+            fs.mkdirSync(path.dirname(file), { recursive: true });
+            fs.writeFileSync(file, content);
+        }
+        return root;
+    }
+    it('reports column, metadata, typed-error, and write-pair violations', () => {
+        const root = makeProject([
+            {
+                site: 'demo',
+                name: 'search',
+                access: 'read',
+                columns: ['id', 'title', 'authorName'],
+                sourceFile: 'demo/search.js',
+            },
+            {
+                site: 'demo',
+                name: 'like',
+                access: 'write',
+                sourceFile: 'demo/like.js',
+            },
+            {
+                site: 'demo',
+                name: 'missing',
+                columns: [],
+                sourceFile: 'demo/missing.js',
+            },
+            {
+                site: 'clean',
+                name: 'search',
+                access: 'read',
+                columns: ['id', 'title'],
+                sourceFile: 'clean/search.js',
+            },
+        ], {
+            'demo/search.js': `
+        export async function run(kwargs) {
+          const limit = Math.min(kwargs.limit, 100);
+          try {
+            await fetch('/items');
+          } catch {
+            return [];
+          }
+          rows.push({
+            id: item.id,
+            title: item.title ?? 'unknown',
+            url: item.url,
+            authorName: item.authorName,
+          });
+          return limit;
+        }
+      `,
+            'demo/like.js': 'export async function run() { return { ok: true }; }',
+            'demo/missing.js': 'export async function run() { return { ok: true }; }',
+            'clean/search.js': 'export async function run() { rows.push({ id: item.id, title: item.title }); }',
+        });
+        const report = runConventionAudit({ projectRoot: root });
+        const category = (rule) => report.categories.find((item) => item.rule === rule);
+        expect(report.ok).toBe(false);
+        expect(category('silent-column-drop').violations[0]).toMatchObject({
+            command: 'demo/search',
+            details: expect.objectContaining({ missing: ['url'] }),
+        });
+        expect(category('camelCase-in-columns').violations[0]).toMatchObject({
+            command: 'demo/search',
+            details: { column: 'authorName' },
+        });
+        expect(category('missing-access-metadata').violations[0]).toMatchObject({ command: 'demo/missing' });
+        expect(category('silent-clamp').violations[0]).toMatchObject({ command: 'demo/search' });
+        expect(category('silent-empty-fallback').violations[0]).toMatchObject({ command: 'demo/search' });
+        expect(category('silent-sentinel').violations[0]).toMatchObject({ command: 'demo/search' });
+        expect(category('write-without-delete-pair').violations[0]).toMatchObject({
+            command: 'demo/like',
+            details: { expected_any_of: ['unlike'] },
+        });
+    });
+    it('supports site and command target filters', () => {
+        const root = makeProject([
+            { site: 'demo', name: 'search', access: 'read', columns: ['id'], sourceFile: 'demo/search.js' },
+            { site: 'other', name: 'search', access: 'read', columns: ['id'], sourceFile: 'other/search.js' },
+        ], {
+            'demo/search.js': 'export async function run() { rows.push({ id: 1, hidden: true }); }',
+            'other/search.js': 'export async function run() { rows.push({ id: 1, hidden: true }); }',
+        });
+        expect(runConventionAudit({ projectRoot: root, site: 'demo' }).summary.commands).toBe(1);
+        expect(runConventionAudit({ projectRoot: root, target: 'other/search' }).summary.commands).toBe(1);
+        expect(runConventionAudit({ projectRoot: root, target: 'missing' }).summary.commands).toBe(0);
+    });
+    it('renders a compact text report', () => {
+        const root = makeProject([
+            { site: 'demo', name: 'search', access: 'read', columns: ['id'], sourceFile: 'demo/search.js' },
+        ], {
+            'demo/search.js': 'export async function run() { rows.push({ id: 1 }); }',
+        });
+        const text = renderConventionAuditText(runConventionAudit({ projectRoot: root }));
+        expect(text).toContain('Convention Audit Report');
+        expect(text).toContain('OK - no convention violations found.');
+    });
+    it('scans pipeline map blocks for silent column drops', () => {
+        const root = makeProject([
+            { site: 'demo', name: 'feed', access: 'read', columns: ['id', 'title'], sourceFile: 'demo/feed.js' },
+        ], {
+            'demo/feed.js': `
+        cli({
+          site: 'demo',
+          name: 'feed',
+          access: 'read',
+          columns: ['id', 'title'],
+          pipeline: [
+            { map: {
+              id: '\${{ item.id }}',
+              title: '\${{ item.title }}',
+              url: '\${{ item.url }}',
+            } },
+          ],
+        });
+      `,
+        });
+        const report = runConventionAudit({ projectRoot: root });
+        const violations = report.categories.find((item) => item.rule === 'silent-column-drop').violations;
+        expect(violations[0]).toMatchObject({
+            command: 'demo/feed',
+            details: expect.objectContaining({ missing: ['url'] }),
+        });
+    });
+    it('ignores ok:false diagnostic objects when checking emitted rows', () => {
+        const root = makeProject([
+            { site: 'demo', name: 'search', access: 'read', columns: ['id', 'url'], sourceFile: 'demo/search.js' },
+        ], {
+            'demo/search.js': `
+        export async function run() {
+          if (!document.querySelector('.items')) {
+            return { ok: false, bodyLen: document.body.innerText.length, sample: document.body.innerText.slice(0, 800), url: location.href };
+          }
+          return rows.map((row) => ({ id: row.id, url: row.url }));
+        }
+      `,
+        });
+        const report = runConventionAudit({ projectRoot: root });
+        const violations = report.categories.find((item) => item.rule === 'silent-column-drop').violations;
+        expect(violations).toEqual([]);
+    });
+    it('ignores raw intermediate keys when a final mapper converts them into columns', () => {
+        const root = makeProject([
+            {
+                site: 'demo',
+                name: 'search',
+                access: 'read',
+                columns: ['id', 'rating', 'reviews', 'price'],
+                sourceFile: 'demo/search.js',
+            },
+        ], {
+            'demo/search.js': `
+        export async function run() {
+          rows.push({
+            id: item.id,
+            starClass: item.starClass,
+            reviewsRaw: item.reviewsRaw,
+            priceRaw: item.priceRaw,
+          });
+          return rows.map((r) => ({
+            id: r.id,
+            rating: r.starClass ? Number(r.starClass) / 10 : null,
+            reviews: parseReviewCount(r.reviewsRaw),
+            price: parsePrice(r.priceRaw),
+          }));
+        }
+      `,
+        });
+        const report = runConventionAudit({ projectRoot: root });
+        const violations = report.categories.find((item) => item.rule === 'silent-column-drop').violations;
+        expect(violations).toEqual([]);
+    });
+    it('still reports raw keys emitted directly without a final mapper', () => {
+        const root = makeProject([
+            { site: 'demo', name: 'search', access: 'read', columns: ['id', 'title'], sourceFile: 'demo/search.js' },
+        ], {
+            'demo/search.js': `
+        export async function run() {
+          rows.push({
+            id: item.id,
+            title: titleRaw,
+            titleRaw,
+          });
+          return rows;
+        }
+      `,
+        });
+        const report = runConventionAudit({ projectRoot: root });
+        const violations = report.categories.find((item) => item.rule === 'silent-column-drop').violations;
+        expect(violations[0]).toMatchObject({
+            command: 'demo/search',
+            details: expect.objectContaining({ missing: ['titleRaw'] }),
+        });
+    });
+    it('only reports empty array fallbacks inside catch blocks', () => {
+        const root = makeProject([
+            { site: 'demo', name: 'guard', access: 'read', columns: ['id'], sourceFile: 'demo/guard.js' },
+            { site: 'demo', name: 'catch', access: 'read', columns: ['id'], sourceFile: 'demo/catch.js' },
+        ], {
+            'demo/guard.js': 'export async function run() { if (!store) return []; rows.push({ id: 1 }); }',
+            'demo/catch.js': 'export async function run() { try { await fetch("/"); } catch (err) { return []; } rows.push({ id: 1 }); }',
+        });
+        const report = runConventionAudit({ projectRoot: root });
+        const violations = report.categories.find((item) => item.rule === 'silent-empty-fallback').violations;
+        expect(violations.map((violation) => violation.command)).toEqual(['demo/catch']);
+    });
+});

package/dist/src/discovery.js

@@ -124,17 +124,18 @@ async function loadFromManifest(manifestPath, clisDir) {
                 name: entry.name,
                 aliases: entry.aliases,
                 description: entry.description ?? '',
+                access: entry.access,
+                example: entry.example,
                 domain: entry.domain,
                 strategy: parseStrategy(entry.strategy),
                 browser: entry.browser,
                 args: entry.args ?? [],
                 columns: entry.columns,
+                defaultFormat: entry.defaultFormat,
                 pipeline: entry.pipeline,
-                timeoutSeconds: entry.timeout,
                 source: entry.sourceFile ? path.resolve(clisDir, entry.sourceFile) : modulePath,
-                deprecated: entry.deprecated,
-                replacedBy: entry.replacedBy,
                 navigateBefore: entry.navigateBefore,
+                browserSession: entry.browserSession,
                 _lazy: true,
                 _modulePath: modulePath,
             };
@@ -168,7 +169,6 @@ async function discoverClisFromFs(dir) {
         await Promise.all(files.map(async (file) => {
             const filePath = path.join(siteDir, file);
             if (file.endsWith('.yaml') || file.endsWith('.yml')) {
-                log.warn(`Ignoring YAML adapter ${filePath} — YAML format is no longer supported. Convert to JavaScript using cli() from '@jackwener/opencli/registry'.`);
                 return;
             }
             if (file.endsWith('.ts') && !file.endsWith('.d.ts') && !file.endsWith('.test.ts')) {
@@ -216,7 +216,6 @@ async function discoverPluginDir(dir, site) {
     await Promise.all(files.map(async (file) => {
         const filePath = path.join(dir, file);
         if (file.endsWith('.yaml') || file.endsWith('.yml')) {
-            log.warn(`Ignoring YAML plugin ${filePath} — YAML format is no longer supported. Convert to JavaScript using cli() from '@jackwener/opencli/registry'.`);
             return;
         }
         if (file.endsWith('.js') && !file.endsWith('.d.js')) {

package/dist/src/doctor.js

@@ -285,7 +285,6 @@ export function renderBrowserDoctorReport(report) {
     }
     else if (report.daemonRunning && report.extensionConnected) {
         lines.push('', styleText('green', 'Everything looks good!'));
-        lines.push(styleText('dim', 'Tip: writing a new adapter? Run `opencli browser analyze <url>` for one-shot site recon.'));
     }
     return lines.join('\n');
 }

package/dist/src/doctor.test.js

@@ -43,7 +43,7 @@ describe('doctor report rendering', () => {
         expect(text).toContain('(v1.7.9)');
         expect(text).toContain('[OK] Extension: connected (v1.6.8)');
         expect(text).toContain('Everything looks good!');
-        expect(text).toContain('opencli browser analyze <url>');
+        expect(text).not.toContain('opencli browser analyze <url>');
     });
     it('renders a warning when daemon version is stale', () => {
         const text = strip(renderBrowserDoctorReport({

package/dist/src/engine.test.js

@@ -27,7 +27,7 @@ export const helper = true;
 import { cli, Strategy } from '${pathToFileURL(path.join(process.cwd(), 'src', 'registry.ts')).href}';
 cli({
   site: 'temp-site',
-  name: 'hello',
+  name: 'hello', access: 'read',
   description: 'hello command',
   strategy: Strategy.PUBLIC,
   browser: false,
@@ -57,7 +57,7 @@ cli({
 import { cli, Strategy } from '${pathToFileURL(path.join(process.cwd(), 'src', 'registry.ts')).href}';
 cli({
   site: 'fallback-site',
-  name: 'hello',
+  name: 'hello', access: 'read',
   description: 'hello command',
   strategy: Strategy.PUBLIC,
   browser: false,
@@ -86,7 +86,7 @@ import { htmlToMarkdown } from '@jackwener/opencli/utils';
 
 cli({
   site: 'legacy-site',
-  name: 'hello',
+  name: 'hello', access: 'read',
   description: 'hello command',
   strategy: Strategy.PUBLIC,
   browser: false,
@@ -204,7 +204,7 @@ describe('executeCommand', () => {
     it('accepts kebab-case option names after Commander camelCases them', async () => {
         const cmd = cli({
             site: 'test-engine',
-            name: 'kebab-arg-test',
+            name: 'kebab-arg-test', access: 'read',
             description: 'test command with kebab-case arg',
             browser: false,
             strategy: Strategy.PUBLIC,
@@ -219,7 +219,7 @@ describe('executeCommand', () => {
     it('executes a command with func', async () => {
         const cmd = cli({
             site: 'test-engine',
-            name: 'func-test',
+            name: 'func-test', access: 'read',
             description: 'test command with func',
             browser: false,
             strategy: Strategy.PUBLIC,
@@ -233,7 +233,7 @@ describe('executeCommand', () => {
     it('executes a command with pipeline', async () => {
         const cmd = cli({
             site: 'test-engine',
-            name: 'pipe-test',
+            name: 'pipe-test', access: 'read',
             description: 'test command with pipeline',
             browser: false,
             strategy: Strategy.PUBLIC,
@@ -248,7 +248,7 @@ describe('executeCommand', () => {
     it('throws for command with no func or pipeline', async () => {
         const cmd = cli({
             site: 'test-engine',
-            name: 'empty-test',
+            name: 'empty-test', access: 'read',
             description: 'empty command',
             browser: false,
         });
@@ -258,7 +258,7 @@ describe('executeCommand', () => {
         let receivedDebug = false;
         const cmd = cli({
             site: 'test-engine',
-            name: 'debug-test',
+            name: 'debug-test', access: 'read',
             description: 'debug test',
             browser: false,
             func: async (_kwargs, debug) => {
@@ -276,7 +276,7 @@ describe('executeCommand', () => {
         });
         const cmd = cli({
             site: 'test-engine',
-            name: 'failing-test',
+            name: 'failing-test', access: 'read',
             description: 'failing command',
             browser: false,
             strategy: Strategy.PUBLIC,
@@ -297,7 +297,7 @@ describe('executeCommand', () => {
             .mockResolvedValue('http://127.0.0.1:9228');
         const cmd = cli({
             site: 'chatwise',
-            name: 'status',
+            name: 'status', access: 'read',
             description: 'chatwise status',
             browser: true,
             strategy: Strategy.PUBLIC,

package/dist/src/errors.js

@@ -73,7 +73,7 @@ export class AuthRequiredError extends CliError {
 }
 export class TimeoutError extends CliError {
     constructor(label, seconds, hint) {
-        super('TIMEOUT', `${label} timed out after ${seconds}s`, hint ?? 'Try again, or increase timeout with OPENCLI_BROWSER_COMMAND_TIMEOUT env var', EXIT_CODES.TEMPFAIL);
+        super('TIMEOUT', `${label} timed out after ${seconds}s`, hint ?? 'Try again, or increase timeout with --timeout <seconds> (or OPENCLI_BROWSER_COMMAND_TIMEOUT for the global default)', EXIT_CODES.TEMPFAIL);
     }
 }
 export class ArgumentError extends CliError {

package/dist/src/execution.d.ts

@@ -4,7 +4,7 @@
  * This is the single entry point for executing any CLI command. It handles:
  * 1. Argument validation and coercion
  * 2. Browser session lifecycle (if needed)
- * 3. Domain pre-navigation for cookie/header strategies
+ * 3. Domain pre-navigation for cookie strategies
  * 4. Timeout enforcement
  * 5. Lazy-loading of TS modules from manifest
  * 6. Lifecycle hooks (onBeforeExecute / onAfterExecute)

package/dist/src/execution.js

@@ -4,13 +4,14 @@
  * This is the single entry point for executing any CLI command. It handles:
  * 1. Argument validation and coercion
  * 2. Browser session lifecycle (if needed)
- * 3. Domain pre-navigation for cookie/header strategies
+ * 3. Domain pre-navigation for cookie strategies
  * 4. Timeout enforcement
  * 5. Lazy-loading of TS modules from manifest
  * 6. Lifecycle hooks (onBeforeExecute / onAfterExecute)
  */
 import { getRegistry, fullName, } from './registry.js';
 import { pathToFileURL } from 'node:url';
+import * as crypto from 'node:crypto';
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import { executePipeline } from './pipeline/index.js';
@@ -28,6 +29,7 @@ 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';
@@ -138,14 +140,37 @@ function resolvePreNav(cmd) {
     // strategy → navigateBefore expansion already happened in normalizeCommand().
     return null;
 }
-function ensureRequiredEnv(cmd) {
-    const missing = (cmd.requiredEnv ?? []).find(({ name }) => {
-        const value = process.env[name];
-        return value === undefined || value === null || value === '';
-    });
-    if (!missing)
-        return;
-    throw new CommandExecutionError(`Command ${fullName(cmd)} requires environment variable ${missing.name}.`, missing.help ?? `Set ${missing.name} before running ${fullName(cmd)}.`);
+function urlMatchesDomain(url, domain) {
+    if (!url || !domain)
+        return false;
+    try {
+        const hostname = new URL(url).hostname;
+        return hostname === domain || hostname.endsWith(`.${domain}`);
+    }
+    catch {
+        return false;
+    }
+}
+function isDomainRootPreNav(preNavUrl, domain) {
+    if (!domain)
+        return false;
+    try {
+        const parsed = new URL(preNavUrl);
+        const hostnameMatches = parsed.hostname === domain || parsed.hostname.endsWith(`.${domain}`);
+        const rootPath = parsed.pathname === '' || parsed.pathname === '/';
+        return hostnameMatches && rootPath && parsed.search === '' && parsed.hash === '';
+    }
+    catch {
+        return false;
+    }
+}
+async function shouldRunPreNav(cmd, page, reuse, preNavUrl) {
+    if (reuse !== 'site' || !cmd.domain)
+        return true;
+    if (!isDomainRootPreNav(preNavUrl, cmd.domain))
+        return true;
+    const currentUrl = await page.getCurrentUrl?.().catch(() => null);
+    return !urlMatchesDomain(currentUrl, cmd.domain);
 }
 export async function executeCommand(cmd, rawKwargs, debug = false, opts = {}) {
     let kwargs;
@@ -157,6 +182,7 @@ export async function executeCommand(cmd, rawKwargs, debug = false, opts = {}) {
             throw err;
         throw new ArgumentError(getErrorMessage(err));
     }
+    const userTimeoutSec = readUserTimeoutSeconds(cmd, kwargs);
     const traceMode = normalizeTraceMode(opts.trace);
     const hookCtx = {
         command: fullName(cmd),
@@ -183,17 +209,19 @@ export async function executeCommand(cmd, rawKwargs, debug = false, opts = {}) {
                     cdpEndpoint = await resolveElectronEndpoint(cmd.site);
                 }
             }
-            ensureRequiredEnv(cmd);
             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;
             result = await browserSession(BrowserFactory, async (page) => {
                 const observation = traceMode === 'off'
                     ? null
                     : new ObservationSession({
                         scope: {
                             contextId,
-                            workspace: `site:${cmd.site}`,
+                            workspace,
                             target: page.getActivePage?.(),
                             site: cmd.site,
                             command: fullName(cmd),
@@ -210,7 +238,7 @@ export async function executeCommand(cmd, rawKwargs, debug = false, opts = {}) {
                     await page.startNetworkCapture?.().catch(() => false);
                 }
                 const preNavUrl = resolvePreNav(cmd);
-                if (preNavUrl) {
+                if (preNavUrl && await shouldRunPreNav(cmd, page, browserReuse, preNavUrl)) {
                     observation?.record({
                         stream: 'action',
                         name: 'pre_navigate',
@@ -253,12 +281,15 @@ export async function executeCommand(cmd, rawKwargs, debug = false, opts = {}) {
                         throw wrapped;
                     }
                 }
-                // --live / OPENCLI_LIVE=1 keeps the automation window open after the
-                // command finishes, so agents (or humans) can inspect the page state.
-                const keepOpen = process.env.OPENCLI_LIVE === '1' || process.env.OPENCLI_LIVE === 'true';
+                // --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
+                        : DEFAULT_BROWSER_COMMAND_TIMEOUT;
                     const result = await runWithTimeout(runCommand(cmd, page, kwargs, debug), {
-                        timeout: cmd.timeoutSeconds ?? DEFAULT_BROWSER_COMMAND_TIMEOUT,
+                        timeout: browserTimeout,
                         label: fullName(cmd),
                     });
                     observation?.record({
@@ -270,8 +301,9 @@ export async function executeCommand(cmd, rawKwargs, debug = false, opts = {}) {
                         await collectObservationEvidence(observation, page).catch(() => { });
                         exportTraceArtifact(observation, 'success', undefined, opts.onTraceExport);
                     }
-                    // Adapter commands are one-shot — close the automation window immediately
-                    // instead of waiting for the 30s idle timeout.
+                    // 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)
                         await page.closeWindow?.().catch(() => { });
                     return result;
@@ -294,23 +326,26 @@ export async function executeCommand(cmd, rawKwargs, debug = false, opts = {}) {
                             exportTraceArtifact(observation, 'failure', err, opts.onTraceExport);
                         }
                     }
-                    // Close the automation window on failure too — without this, the window
-                    // lingers until the extension's idle timer fires (unreliable on Windows
-                    // where MV3 service workers may be suspended before setTimeout triggers).
+                    // 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)
                         await page.closeWindow?.().catch(() => { });
                     throw err;
                 }
-            }, { workspace: `site:${cmd.site}`, cdpEndpoint, contextId });
+            }, { workspace, cdpEndpoint, contextId, idleTimeout });
         }
         else {
-            // Non-browser commands: apply timeout only when explicitly configured.
-            const timeout = cmd.timeoutSeconds;
-            if (timeout !== undefined && timeout > 0) {
+            // Non-browser commands: enforce a timeout only when the command exposes
+            // a `--timeout` arg (and the resolved value is positive). Without that
+            // arg there is no meaningful default — non-browser cmds are diverse
+            // enough that a hard cap would do more harm than good.
+            if (userTimeoutSec !== null) {
+                const ceiling = userTimeoutSec + RUNTIME_TIMEOUT_PADDING_SECONDS;
                 result = await runWithTimeout(runCommand(cmd, null, kwargs, debug), {
-                    timeout,
+                    timeout: ceiling,
                     label: fullName(cmd),
-                    hint: `Increase the adapter's timeoutSeconds setting (currently ${timeout}s)`,
+                    hint: `Pass a higher --timeout value (currently ${userTimeoutSec}s)`,
                 });
             }
             else {
@@ -401,3 +436,52 @@ export function prepareCommandArgs(cmd, rawKwargs) {
     cmd.validateArgs?.(kwargs);
     return kwargs;
 }
+/**
+ * Runtime ceiling padding (seconds) added on top of the user's `--timeout`.
+ * The adapter's polling loop typically uses the full user value; the padding
+ * gives us room for the adapter to return + closeWindow + trace export before
+ * the runtime kills the Promise.
+ */
+const RUNTIME_TIMEOUT_PADDING_SECONDS = 30;
+function readEnvBrowserSessionReuse() {
+    const raw = process.env.OPENCLI_BROWSER_REUSE;
+    if (raw === undefined || raw === '')
+        return null;
+    if (raw === 'none' || raw === 'site')
+        return raw;
+    throw new ArgumentError(`--reuse must be one of: none, site. Received: "${raw}"`);
+}
+function resolveBrowserSessionReuse(cmd) {
+    return readEnvBrowserSessionReuse() ?? cmd.browserSession?.reuse ?? 'none';
+}
+function resolveBrowserWorkspace(cmd, reuse) {
+    if (reuse === 'site')
+        return `site:${cmd.site}`;
+    return `site:${cmd.site}:${crypto.randomUUID()}`;
+}
+/**
+ * Resolve the user-controllable `--timeout` arg, in seconds.
+ *
+ * Convention: a command opts into runtime-enforced timeouts by declaring an
+ * arg named `timeout`. The arg's `default` flows through `prepareCommandArgs`
+ * into `kwargs.timeout`, so by the time runtime enforcement runs, the value
+ * is the merged user-supplied-or-default seconds.
+ *
+ * Returns the parsed positive integer (seconds), or null if the command does
+ * not expose a `timeout` arg. Declaring `timeout` opts into runtime timeout
+ * enforcement, so invalid values must fail upfront instead of silently
+ * disabling the runtime ceiling.
+ */
+function readUserTimeoutSeconds(cmd, kwargs) {
+    if (!cmd.args.some(a => a.name === 'timeout'))
+        return null;
+    const raw = kwargs.timeout;
+    if (raw === undefined || raw === null || raw === '') {
+        throw new ArgumentError(`Argument "timeout" must be a positive integer. Received: "${String(raw)}"`);
+    }
+    const parsed = Number(raw);
+    if (!Number.isInteger(parsed) || parsed <= 0) {
+        throw new ArgumentError(`Argument "timeout" must be a positive integer. Received: "${String(raw)}"`);
+    }
+    return parsed;
+}