@sovovs/bycli 2.1.40 → 2.1.42

package/dist/src/daemon.js

@@ -39,6 +39,7 @@ import { recordExtensionVersion } from './update-check.js';
 import { EXTENSION_CAPABILITY_MISSING_ERROR_CODE, EXTENSION_CAPABILITY_MISSING_HTTP_STATUS, extensionCapabilityHint, missingRequiredExtensionCapability, normalizeExtensionCapabilities, } from './browser/extension-capabilities.js';
 import { buildCommandDispatchFailure, buildExtensionDisconnectFailure, getResponseCorsHeaders, } from './daemon-utils.js';
 import { resolveDaemonHost } from './daemon-config.js';
+import { AdapterScheduler, AdapterSchedulerError, } from './adapter-scheduler.js';
 const PORT = parseInt(process.env.BYCLI_DAEMON_PORT ?? String(DEFAULT_DAEMON_PORT), 10);
 const HOST = resolveDaemonHost();
 const BROWSER_RECOVERY_COMMAND = process.env.BYCLI_BROWSER_RECOVERY_COMMAND?.trim();
@@ -60,6 +61,9 @@ const logger = createRecorderLogger(LOG_LEVELS.includes(envLogLevel) ? envLogLev
 // runner counters surface on GET /metrics and runner logs share the daemon's level.
 setDefaultRunnerObservability(metrics, logger);
 const extensionProfiles = new Map();
+const adapterScheduler = new AdapterScheduler();
+const adapterSchedulerSweep = setInterval(() => adapterScheduler.sweepExpired(), 5_000);
+adapterSchedulerSweep.unref?.();
 const pending = new Map();
 let commandResultUnknownCount = 0;
 const LOG_BUFFER_SIZE = 200;
@@ -386,6 +390,92 @@ async function handleRequest(req, res) {
         }
         return;
     }
+    if (req.method === 'POST' && pathname.startsWith('/v1/adapter-leases/')) {
+        try {
+            const body = JSON.parse(await readBody(req));
+            if (pathname === '/v1/adapter-leases/acquire') {
+                const request = body;
+                let clientGone = false;
+                const onClose = () => {
+                    if (res.writableEnded)
+                        return;
+                    clientGone = true;
+                    adapterScheduler.cancel(request.requestId);
+                };
+                res.once('close', onClose);
+                const lease = await adapterScheduler.acquire(request);
+                res.off('close', onClose);
+                if (clientGone || res.destroyed) {
+                    adapterScheduler.release({ ...lease, reason: 'cancelled' });
+                    return;
+                }
+                jsonResponse(res, 200, { ok: true, data: lease });
+                return;
+            }
+            if (pathname === '/v1/adapter-leases/heartbeat') {
+                const lease = adapterScheduler.heartbeat(body);
+                jsonResponse(res, 200, { ok: true, data: lease });
+                return;
+            }
+            if (pathname === '/v1/adapter-leases/release') {
+                const released = adapterScheduler.release(body);
+                jsonResponse(res, 200, { ok: true, data: { released } });
+                return;
+            }
+            if (pathname === '/v1/adapter-leases/cancel') {
+                const requestId = typeof body.requestId === 'string' ? body.requestId : '';
+                const cancelled = requestId ? adapterScheduler.cancel(requestId) : false;
+                jsonResponse(res, 200, { ok: true, data: { cancelled } });
+                return;
+            }
+            jsonResponse(res, 404, { ok: false, errorCode: 'ADAPTER_QUEUE_RESET', error: 'Unknown Adapter lease operation' });
+        }
+        catch (error) {
+            if (res.destroyed)
+                return;
+            const schedulerError = error instanceof AdapterSchedulerError ? error : null;
+            const status = schedulerError?.code === 'ADAPTER_QUEUE_TIMEOUT' ? 408
+                : schedulerError?.code === 'ADAPTER_LEASE_LOST' ? 409
+                    : schedulerError?.code === 'ADAPTER_POOL_AUTH_GATE' || schedulerError?.code === 'ADAPTER_POOL_RATE_LIMITED' ? 409
+                        : 400;
+            jsonResponse(res, status, {
+                ok: false,
+                errorCode: schedulerError?.code ?? 'ADAPTER_QUEUE_RESET',
+                error: error instanceof Error ? error.message : 'Adapter scheduler request failed',
+            });
+        }
+        return;
+    }
+    if (req.method === 'POST' && pathname.startsWith('/v1/adapter-resources/')) {
+        try {
+            const body = JSON.parse(await readBody(req));
+            const lease = body.lease;
+            if (pathname === '/v1/adapter-resources/acquire') {
+                const keys = Array.isArray(body.keys) ? body.keys.filter((key) => typeof key === 'string') : [];
+                const timeoutMs = typeof body.timeoutMs === 'number' ? body.timeoutMs : 0;
+                const grant = await adapterScheduler.acquireResources(lease, keys, timeoutMs);
+                jsonResponse(res, 200, { ok: true, data: grant });
+                return;
+            }
+            if (pathname === '/v1/adapter-resources/release') {
+                const grantId = typeof body.grantId === 'string' ? body.grantId : '';
+                const released = adapterScheduler.releaseResources(lease, grantId);
+                jsonResponse(res, 200, { ok: true, data: { released } });
+                return;
+            }
+            jsonResponse(res, 404, { ok: false, errorCode: 'ADAPTER_QUEUE_RESET', error: 'Unknown Adapter resource operation' });
+        }
+        catch (error) {
+            const schedulerError = error instanceof AdapterSchedulerError ? error : null;
+            const status = schedulerError?.code === 'ADAPTER_RESOURCE_TIMEOUT' ? 408 : 409;
+            jsonResponse(res, status, {
+                ok: false,
+                errorCode: schedulerError?.code ?? 'ADAPTER_LEASE_LOST',
+                error: error instanceof Error ? error.message : 'Adapter resource request failed',
+            });
+        }
+        return;
+    }
     if (req.method === 'GET' && pathname === '/status') {
         const uptime = process.uptime();
         const mem = process.memoryUsage();
@@ -415,6 +505,8 @@ async function handleRequest(req, res) {
             profileDisconnected: route.errorCode === 'profile_disconnected',
             profiles,
             pending: pending.size,
+            adapterLeases: adapterScheduler.snapshot(),
+            adapterResources: adapterScheduler.resourceSnapshot(),
             commandResultUnknown: commandResultUnknownCount,
             memoryMB: Math.round(mem.rss / 1024 / 1024 * 10) / 10,
             port: PORT,
@@ -454,6 +546,30 @@ async function handleRequest(req, res) {
                 jsonResponse(res, 400, { ok: false, error: 'Missing command id' });
                 return;
             }
+            const namedAdapterSession = body.surface === 'adapter'
+                && body.siteSession === 'persistent'
+                && typeof body.session === 'string'
+                && /^site:[^:\s]+:[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/.test(body.session);
+            if (namedAdapterSession && !body.adapterLease) {
+                throw new DaemonCommandFailure('Named Adapter browser commands require an active lease', 'ADAPTER_LEASE_LOST', undefined, 409);
+            }
+            if (body.adapterLease) {
+                try {
+                    const lease = adapterScheduler.assertLease(body.adapterLease);
+                    if (body.contextId !== lease.contextId
+                        || body.surface !== 'adapter'
+                        || body.siteSession !== 'persistent'
+                        || body.session !== lease.sessionKey) {
+                        throw new AdapterSchedulerError('ADAPTER_LEASE_LOST', 'Adapter browser command does not match its lease scope');
+                    }
+                }
+                catch (error) {
+                    if (error instanceof AdapterSchedulerError) {
+                        throw new DaemonCommandFailure(error.message, error.code, undefined, 409);
+                    }
+                    throw error;
+                }
+            }
             const route = resolveExtensionConnection(typeof body.contextId === 'string' ? body.contextId : undefined);
             if (!route.connection) {
                 jsonResponse(res, route.errorCode === 'profile_required' ? 409 : 503, {
@@ -722,6 +838,8 @@ function shutdown() {
         p.reject(new Error('Daemon shutting down'));
     }
     pending.clear();
+    clearInterval(adapterSchedulerSweep);
+    adapterScheduler.reset();
     for (const profile of extensionProfiles.values())
         profile.ws.close();
     httpServer.close();

package/dist/src/discovery.js

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

package/dist/src/download/article-download.d.ts

@@ -53,6 +53,8 @@ export interface ArticleDownloadOptions {
     stdout?: boolean;
     /** Opt-in hardened Markdown rules used by HTML-focused adapters. */
     secureMarkdown?: boolean;
+    /** Lease fencing check invoked immediately before the final Markdown write. */
+    beforePublish?: () => Promise<void>;
 }
 export interface ArticleDownloadResult {
     title: string;

package/dist/src/download/article-download.js

@@ -325,7 +325,7 @@ async function downloadImages(imgUrls, imgDir, headers, detectExt) {
  * 6. File write
  */
 export async function downloadArticle(data, options) {
-    const { output, downloadImages: shouldDownloadImages = true, imageHeaders, maxTitleLength = 80, configureTurndown, detectImageExt, frontmatterLabels, cleanSelectors, stdout = false, secureMarkdown = false, } = options;
+    const { output, downloadImages: shouldDownloadImages = true, imageHeaders, maxTitleLength = 80, configureTurndown, detectImageExt, frontmatterLabels, cleanSelectors, stdout = false, secureMarkdown = false, beforePublish, } = options;
     const labels = { ...DEFAULT_LABELS, ...frontmatterLabels };
     if (!data.title) {
         return [{
@@ -350,12 +350,14 @@ export async function downloadArticle(data, options) {
     // Convert HTML to Markdown
     let markdown = convertToMarkdown(data.contentHtml, data.codeBlocks || [], configureTurndown, cleanSelectors, secureMarkdown);
     const safeTitle = sanitizeFilename(data.title, maxTitleLength);
+    const stagingDir = !stdout && beforePublish
+        ? path.join(output, `.bycli-article-${crypto.randomUUID()}.tmp`)
+        : undefined;
     // Download images only when writing to disk. In stdout mode remote URLs
     // stay intact so the piped output is self-contained.
     if (!stdout && shouldDownloadImages && data.imageUrls && data.imageUrls.length > 0) {
         const articleDir = path.join(output, safeTitle);
-        fs.mkdirSync(articleDir, { recursive: true });
-        const imagesDir = path.join(articleDir, 'images');
+        const imagesDir = path.join(stagingDir ?? articleDir, 'images');
         fs.mkdirSync(imagesDir, { recursive: true });
         const urlMap = await downloadImages(data.imageUrls, imagesDir, imageHeaders, detectImageExt);
         markdown = replaceImageUrls(markdown, urlMap);
@@ -396,7 +398,31 @@ export async function downloadArticle(data, options) {
     fs.mkdirSync(articleDir, { recursive: true });
     const filename = `${safeTitle}.md`;
     const filePath = path.join(articleDir, filename);
-    fs.writeFileSync(filePath, fullContent, 'utf-8');
+    if (stagingDir) {
+        fs.mkdirSync(stagingDir, { recursive: true });
+        const stagedMarkdown = path.join(stagingDir, filename);
+        fs.writeFileSync(stagedMarkdown, fullContent, { encoding: 'utf-8', flag: 'wx' });
+        try {
+            await beforePublish?.();
+            const stagedImages = path.join(stagingDir, 'images');
+            if (fs.existsSync(stagedImages)) {
+                const finalImages = path.join(articleDir, 'images');
+                fs.mkdirSync(finalImages, { recursive: true });
+                for (const image of fs.readdirSync(stagedImages)) {
+                    fs.linkSync(path.join(stagedImages, image), path.join(finalImages, image));
+                }
+            }
+            // Same-filesystem rename makes the Markdown replacement atomic.
+            fs.renameSync(stagedMarkdown, filePath);
+        }
+        finally {
+            fs.rmSync(stagingDir, { recursive: true, force: true });
+        }
+    }
+    else {
+        await beforePublish?.();
+        fs.writeFileSync(filePath, fullContent, 'utf-8');
+    }
     return [{
             title: data.title,
             author: data.author || '-',

package/dist/src/errors.d.ts

@@ -67,6 +67,9 @@ export declare class TimeoutError extends CliError {
 export declare class ArgumentError extends CliError {
     constructor(message: string, hint?: string);
 }
+export declare class AdapterCoordinationError extends CliError {
+    constructor(code: string, message: string, temporary?: boolean, hint?: string);
+}
 export declare class EmptyResultError extends CliError {
     constructor(command: string, hint?: string);
 }

package/dist/src/errors.js

@@ -86,6 +86,11 @@ export class ArgumentError extends CliError {
         super('ARGUMENT', message, hint, EXIT_CODES.USAGE_ERROR);
     }
 }
+export class AdapterCoordinationError extends CliError {
+    constructor(code, message, temporary = false, hint) {
+        super(code, message, hint, temporary ? EXIT_CODES.TEMPFAIL : EXIT_CODES.USAGE_ERROR);
+    }
+}
 export class EmptyResultError extends CliError {
     constructor(command, hint) {
         super('EMPTY_RESULT', `${command} returned no data`, hint ?? 'The page structure may have changed, or you may need to log in', EXIT_CODES.EMPTY_RESULT);

package/dist/src/execution.d.ts

@@ -22,6 +22,8 @@ export declare function executeCommand(cmd: CliCommand, rawKwargs: CommandArgs,
     keepTab?: string;
     windowMode?: string;
     siteSession?: string;
+    adapterSession?: string;
+    adapterQueueTimeout?: string;
     onTraceExport?: (trace: ObservationExportResult) => void;
 }): Promise<unknown>;
 export declare function prepareCommandArgs(cmd: CliCommand, rawKwargs: CommandArgs): CommandArgs;

package/dist/src/execution.js

@@ -16,10 +16,11 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { getUserClisDir } from './config-paths.js';
 import { executePipeline } from './pipeline/index.js';
-import { adapterLoadError, ArgumentError, CliError, CommandExecutionError, attachTraceReceipt, getErrorMessage } from './errors.js';
+import { AdapterCoordinationError, adapterLoadError, ArgumentError, CliError, CommandExecutionError, TimeoutError, attachTraceReceipt, getErrorMessage } from './errors.js';
 import { shouldUseBrowserSession } from './capabilityRouting.js';
 import { getBrowserFactory, browserSession, runWithTimeout, DEFAULT_BROWSER_COMMAND_TIMEOUT } from './runtime.js';
 import { resolveProfileContextId } from './browser/profile.js';
+import { resolveAdapterLeaseContextId } from './browser/daemon-client.js';
 import { emitHook } from './hooks.js';
 import { log } from './logger.js';
 import { isElectronApp } from './electron-apps.js';
@@ -27,6 +28,7 @@ import { probeCDP, resolveElectronEndpoint } from './launcher.js';
 import { ObservationSession, exportObservationSession } from './observation/index.js';
 import { resolveAdapterSourcePath } from './adapter-source.js';
 import { canonicalizeManifestArgSchema, ManifestSchemaError } from './manifest-schema.js';
+import { settleAdapterOperationAfterTimeout, withAdapterCommandLease } from './adapter-coordination.js';
 import { capturedRegistryValues, closeRegistryTransaction, createRegistryTransaction, finalizeRegistryTransaction, resetRegistryTransactionStateForTests, rollbackRegistryTransaction, runRegistryTransaction, transactionGroupsForKey, } from './registry-transaction.js';
 const _loadedModules = new Map();
 /** Independent cache-busting generation; retained when an import promise is discarded. */
@@ -402,6 +404,8 @@ export async function executeCommand(cmd, rawKwargs, debug = false, opts = {}) {
     let result;
     try {
         const resolvedBrowser = resolveBrowserRequirement(cmd, kwargs);
+        const adapterSession = normalizeAdapterSession(cmd, resolvedBrowser, opts.adapterSession);
+        const adapterQueueTimeoutSeconds = normalizeAdapterQueueTimeout(opts.adapterQueueTimeout, adapterSession);
         const userTimeoutSec = readUserTimeoutSeconds(cmd, kwargs);
         if (shouldUseBrowserSession(cmd, resolvedBrowser)) {
             const electron = isElectronApp(cmd.site);
@@ -424,126 +428,154 @@ export async function executeCommand(cmd, rawKwargs, debug = false, opts = {}) {
             const contextId = resolveProfileContextId(opts.profile);
             const internal = cmd;
             const siteSession = resolveSiteSession(cmd, opts.siteSession);
-            const session = resolveAdapterBrowserSession(cmd, siteSession);
+            assertAdapterSessionLifecycle(siteSession, adapterSession);
+            const session = resolveAdapterBrowserSession(cmd, siteSession, adapterSession);
             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,
-                            session,
-                            target: page.getActivePage?.(),
-                            site: cmd.site,
-                            command: fullName(cmd),
-                            adapterSourcePath: resolveAdapterSourcePath(internal)
-                                ?? resolveAdapterSourcePath(initialTraceCommand),
-                        },
-                    });
-                if (observation) {
-                    observation.record({
-                        stream: 'action',
-                        name: 'command',
-                        phase: 'start',
-                        data: { args: kwargs },
-                    });
-                    await page.startNetworkCapture?.().catch(() => false);
-                }
-                const preNavUrl = resolvePreNav(cmd);
-                if (preNavUrl && await shouldRunPreNav(cmd, page, siteSession, preNavUrl)) {
-                    observation?.record({
-                        stream: 'action',
-                        name: 'pre_navigate',
-                        phase: 'start',
-                        data: { url: preNavUrl },
-                    });
-                    // Navigate directly — the extension's handleNavigate already has a fast-path
-                    // that skips navigation if the tab is already at the target URL.
-                    // This avoids an extra exec round-trip (getCurrentUrl) on first command and
-                    // lets the extension create the automation window with the target URL directly
-                    // instead of about:blank.
-                    try {
-                        await page.goto(preNavUrl);
-                        observation?.record({
+            const executeInBrowser = () => browserSession(BrowserFactory, async (page) => {
+                // BrowserBridge.connect() has started/probed the daemon by this point. Resolve
+                // the daemon's canonical profile before acquiring a profile-scoped lease.
+                const leaseContextId = adapterSession
+                    ? await resolveAdapterLeaseContextId(contextId)
+                    : undefined;
+                if (leaseContextId)
+                    page.setContextId?.(leaseContextId);
+                const executeOnPage = async () => {
+                    const observation = traceMode === 'off'
+                        ? null
+                        : new ObservationSession({
+                            scope: {
+                                contextId,
+                                session: adapterSession ? adapterSessionDiagnosticKey(cmd.site, adapterSession) : session,
+                                target: page.getActivePage?.(),
+                                site: cmd.site,
+                                command: fullName(cmd),
+                                adapterSourcePath: resolveAdapterSourcePath(internal)
+                                    ?? resolveAdapterSourcePath(initialTraceCommand),
+                            },
+                        });
+                    if (observation) {
+                        observation.record({
                             stream: 'action',
-                            name: 'pre_navigate',
-                            phase: 'end',
-                            data: { url: preNavUrl },
+                            name: 'command',
+                            phase: 'start',
+                            data: { args: kwargs },
                         });
+                        await page.startNetworkCapture?.().catch(() => false);
                     }
-                    catch (err) {
+                    const preNavUrl = resolvePreNav(cmd);
+                    if (preNavUrl && await shouldRunPreNav(cmd, page, siteSession, preNavUrl)) {
                         observation?.record({
                             stream: 'action',
                             name: 'pre_navigate',
-                            phase: 'error',
-                            data: { url: preNavUrl, error: err instanceof Error ? err.message : String(err) },
+                            phase: 'start',
+                            data: { url: preNavUrl },
                         });
-                        const wrapped = new CommandExecutionError(`Pre-navigation to ${preNavUrl} failed: ${err instanceof Error ? err.message : err}`, 'Check that the site is reachable and the browser extension is running.');
-                        if (observation && (traceMode === 'on' || traceMode === 'retain-on-failure')) {
-                            observation.record({
-                                stream: 'error',
-                                message: wrapped.message,
-                                stack: wrapped.stack,
-                                code: wrapped.code,
-                                hint: wrapped.hint,
+                        // Navigate directly — the extension's handleNavigate already has a fast-path
+                        // that skips navigation if the tab is already at the target URL.
+                        // This avoids an extra exec round-trip (getCurrentUrl) on first command and
+                        // lets the extension create the automation window with the target URL directly
+                        // instead of about:blank.
+                        try {
+                            await page.goto(preNavUrl);
+                            observation?.record({
+                                stream: 'action',
+                                name: 'pre_navigate',
+                                phase: 'end',
+                                data: { url: preNavUrl },
                             });
-                            await collectObservationEvidence(observation, page).catch(() => { });
-                            exportTraceArtifact(observation, 'failure', wrapped, opts.onTraceExport);
                         }
-                        throw wrapped;
-                    }
-                }
-                try {
-                    const browserTimeout = userTimeoutSec !== null
-                        ? userTimeoutSec + RUNTIME_TIMEOUT_PADDING_SECONDS
-                        : DEFAULT_BROWSER_COMMAND_TIMEOUT;
-                    const result = await runWithTimeout(runCommand(cmd, page, kwargs, debug), {
-                        timeout: browserTimeout,
-                        label: fullName(cmd),
-                    });
-                    observation?.record({
-                        stream: 'action',
-                        name: 'command',
-                        phase: 'end',
-                    });
-                    if (observation && traceMode === 'on') {
-                        await collectObservationEvidence(observation, page).catch(() => { });
-                        exportTraceArtifact(observation, 'success', undefined, opts.onTraceExport);
+                        catch (err) {
+                            observation?.record({
+                                stream: 'action',
+                                name: 'pre_navigate',
+                                phase: 'error',
+                                data: { url: preNavUrl, error: err instanceof Error ? err.message : String(err) },
+                            });
+                            const wrapped = new CommandExecutionError(`Pre-navigation to ${preNavUrl} failed: ${err instanceof Error ? err.message : err}`, 'Check that the site is reachable and the browser extension is running.');
+                            if (observation && (traceMode === 'on' || traceMode === 'retain-on-failure')) {
+                                observation.record({
+                                    stream: 'error',
+                                    message: wrapped.message,
+                                    stack: wrapped.stack,
+                                    code: wrapped.code,
+                                    hint: wrapped.hint,
+                                });
+                                await collectObservationEvidence(observation, page).catch(() => { });
+                                exportTraceArtifact(observation, 'failure', wrapped, opts.onTraceExport);
+                            }
+                            throw wrapped;
+                        }
                     }
-                    // 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 (!keepTab)
-                        await page.closeWindow?.().catch(() => { });
-                    return result;
-                }
-                catch (err) {
-                    if (observation) {
-                        observation.record({
+                    try {
+                        const browserTimeout = userTimeoutSec !== null
+                            ? userTimeoutSec + RUNTIME_TIMEOUT_PADDING_SECONDS
+                            : DEFAULT_BROWSER_COMMAND_TIMEOUT;
+                        const commandOperation = runCommand(cmd, page, kwargs, debug);
+                        const result = adapterSession
+                            ? await settleAdapterOperationAfterTimeout(commandOperation, browserTimeout * 1_000, new TimeoutError(fullName(cmd), browserTimeout), async () => { await page.closeWindow?.().catch(() => { }); })
+                            : await runWithTimeout(commandOperation, {
+                                timeout: browserTimeout,
+                                label: fullName(cmd),
+                            });
+                        observation?.record({
                             stream: 'action',
                             name: 'command',
-                            phase: 'error',
-                            data: { error: err instanceof Error ? err.message : String(err) },
-                        });
-                        observation.record({
-                            stream: 'error',
-                            message: err instanceof Error ? err.message : String(err),
-                            stack: err instanceof Error ? err.stack : undefined,
+                            phase: 'end',
                         });
-                        if (traceMode === 'on' || traceMode === 'retain-on-failure') {
+                        if (observation && traceMode === 'on') {
                             await collectObservationEvidence(observation, page).catch(() => { });
-                            exportTraceArtifact(observation, 'failure', err, opts.onTraceExport);
+                            exportTraceArtifact(observation, 'success', undefined, opts.onTraceExport);
                         }
+                        // 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 (!keepTab)
+                            await page.closeWindow?.().catch(() => { });
+                        return result;
                     }
-                    // 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 (!keepTab)
-                        await page.closeWindow?.().catch(() => { });
-                    throw err;
-                }
+                    catch (err) {
+                        if (observation) {
+                            observation.record({
+                                stream: 'action',
+                                name: 'command',
+                                phase: 'error',
+                                data: { error: err instanceof Error ? err.message : String(err) },
+                            });
+                            observation.record({
+                                stream: 'error',
+                                message: err instanceof Error ? err.message : String(err),
+                                stack: err instanceof Error ? err.stack : undefined,
+                            });
+                            if (traceMode === 'on' || traceMode === 'retain-on-failure') {
+                                await collectObservationEvidence(observation, page).catch(() => { });
+                                exportTraceArtifact(observation, 'failure', err, opts.onTraceExport);
+                            }
+                        }
+                        // 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 (!keepTab)
+                            await page.closeWindow?.().catch(() => { });
+                        throw err;
+                    }
+                };
+                if (!adapterSession)
+                    return executeOnPage();
+                return withAdapterCommandLease({
+                    requestId: crypto.randomUUID(),
+                    contextId: leaseContextId,
+                    surface: 'adapter',
+                    site: cmd.site,
+                    adapterSession,
+                    sessionKey: session,
+                    queueTimeoutMs: (adapterQueueTimeoutSeconds ?? 300) * 1_000,
+                    maxParallel: cmd.adapterConcurrency?.maxParallel ?? 1,
+                }, executeOnPage, {
+                    onLeaseLost: async () => { await page.closeWindow?.().catch(() => { }); },
+                });
             }, { session, cdpEndpoint, contextId, windowMode, surface: 'adapter', siteSession });
+            result = await executeInBrowser();
         }
         else {
             // Non-browser commands: enforce a timeout only when the command exposes
@@ -674,11 +706,46 @@ function normalizeSiteSession(raw) {
 function resolveSiteSession(cmd, rawOption) {
     return normalizeSiteSession(rawOption) ?? cmd.siteSession ?? 'ephemeral';
 }
-function resolveAdapterBrowserSession(cmd, siteSession) {
-    if (siteSession === 'persistent')
-        return `site:${cmd.site}`;
+function normalizeAdapterSession(cmd, resolvedBrowser, rawOption) {
+    if (rawOption === undefined || rawOption === null || rawOption === '')
+        return undefined;
+    if (!resolvedBrowser || cmd.adapterConcurrency?.isolatedTabs !== true) {
+        throw new AdapterCoordinationError('ADAPTER_SESSION_NOT_SUPPORTED', `${fullName(cmd)} does not support named Adapter sessions`);
+    }
+    const value = String(rawOption);
+    if (!/^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/.test(value)) {
+        throw new AdapterCoordinationError('INVALID_ADAPTER_SESSION', '--adapter-session must match [A-Za-z0-9][A-Za-z0-9_-]{0,63}');
+    }
+    return value;
+}
+function normalizeAdapterQueueTimeout(rawOption, adapterSession) {
+    if (rawOption === undefined || rawOption === null || rawOption === '') {
+        return adapterSession ? 300 : undefined;
+    }
+    if (!adapterSession) {
+        throw new AdapterCoordinationError('INVALID_ADAPTER_QUEUE_TIMEOUT', '--adapter-queue-timeout requires --adapter-session');
+    }
+    const value = typeof rawOption === 'string' && /^\d+$/.test(rawOption) ? Number(rawOption) : NaN;
+    if (!Number.isInteger(value) || value < 1 || value > 3600) {
+        throw new AdapterCoordinationError('INVALID_ADAPTER_QUEUE_TIMEOUT', '--adapter-queue-timeout must be an integer between 1 and 3600 seconds');
+    }
+    return value;
+}
+function assertAdapterSessionLifecycle(siteSession, adapterSession) {
+    if (adapterSession && siteSession !== 'persistent') {
+        throw new AdapterCoordinationError('ADAPTER_SESSION_REQUIRES_PERSISTENT', '--adapter-session requires --site-session persistent');
+    }
+}
+function resolveAdapterBrowserSession(cmd, siteSession, adapterSession) {
+    if (siteSession === 'persistent') {
+        return adapterSession ? `site:${cmd.site}:${adapterSession}` : `site:${cmd.site}`;
+    }
     return `site:${cmd.site}:${crypto.randomUUID()}`;
 }
+function adapterSessionDiagnosticKey(site, adapterSession) {
+    const digest = crypto.createHash('sha256').update(adapterSession).digest('hex').slice(0, 12);
+    return `site:${site}:adapter-${digest}`;
+}
 function normalizeBooleanOption(name, raw) {
     if (raw === undefined || raw === '')
         return null;

package/dist/src/help.d.ts

@@ -82,6 +82,7 @@ export declare function siteHelpData(site: string, commands: readonly CliCommand
 export declare function commandHelpData(cmd: CliCommand): Record<string, unknown>;
 export declare function formatCommonOptionsHelpText(): string;
 export declare function formatBrowserCommonOptionsHelpText(): string;
+export declare function formatAdapterSessionOptionsHelpText(): string;
 export declare function formatSiteHelpText(site: string, commands: readonly CliCommand[]): string;
 export declare function formatCommandHelpText(cmd: CliCommand): string;
 export declare function installStructuredHelp(command: Command, data: () => unknown, textSuffix?: string | (() => string)): void;