@steipete/oracle 0.19.0 → 0.20.1

package/dist/src/browser/reattach.js

@@ -13,9 +13,21 @@ import { readDevToolsActivePortInfo } from "./detect.js";
 import { pickTarget, extractConversationIdFromUrl, buildConversationUrl, withTimeout, openConversationFromSidebar, openConversationFromSidebarWithRetry, waitForLocationChange, readConversationTurnIndex, buildPromptEchoMatcher, recoverPromptEcho, alignPromptEchoMarkdown, } from "./reattachHelpers.js";
 import { waitForDeepResearchCompletion } from "./actions/deepResearch.js";
 import { CHROME_COOKIE_SYNC_WARNING, shouldSyncBrowserCookies } from "./policies.js";
+import { BrowserCancellation, withoutBrowserCancellation } from "./cancellation.js";
+import { BrowserRunCancelledError } from "../oracle/errors.js";
 export async function resumeBrowserSession(runtime, config, logger, deps = {}) {
-    const recoverSession = deps.recoverSession ??
-        (async (runtimeMeta, configMeta) => resumeBrowserSessionViaNewChrome(runtimeMeta, configMeta, logger, deps));
+    const cancellation = new BrowserCancellation(deps.signal, logger);
+    try {
+        return await cancellation.run(() => resumeBrowserSessionInternal(runtime, config, logger, deps, cancellation));
+    }
+    finally {
+        cancellation.dispose();
+    }
+}
+async function resumeBrowserSessionInternal(runtime, config, logger, deps, cancellation) {
+    const recoverSession = deps.recoverSession
+        ? (runtimeMeta, configMeta) => cancellation.call(() => deps.recoverSession(runtimeMeta, configMeta))
+        : (runtimeMeta, configMeta) => resumeBrowserSessionViaNewChrome(runtimeMeta, configMeta, logger, deps, cancellation);
     let closeAttachedConnection = null;
     const closeAttached = async () => {
         const close = closeAttachedConnection;
@@ -39,17 +51,18 @@ export async function resumeBrowserSession(runtime, config, logger, deps = {}) {
                 browserWSEndpoint,
                 approvalWaitMs,
                 logger,
+                signal: deps.signal,
             })));
-        const targetList = (await listTargets());
+        const targetList = (await cancellation.call(listTargets));
         const target = pickTarget(targetList, liveRuntime);
-        const connection = browserWSEndpoint && !deps.connect
-            ? await connectToRemoteChromeTarget(host, port ?? 9222, logger, {
+        const connection = await cancellation.acquire(() => browserWSEndpoint && !deps.connect
+            ? connectToRemoteChromeTarget(host, port ?? 9222, logger, {
                 browserWSEndpoint,
                 targetId: target?.targetId ?? target?.id,
                 closeTargetOnDispose: false,
                 approvalWaitMs,
             })
-            : await (async () => {
+            : (async () => {
                 const client = (await (deps.connect ?? ((options) => CDP(options)))(browserWSEndpoint
                     ? {
                         target: browserWSEndpoint,
@@ -62,10 +75,23 @@ export async function resumeBrowserSession(runtime, config, logger, deps = {}) {
                         target: target?.targetId ?? target?.id,
                     }));
                 return { client, close: () => client.close() };
-            })();
+            })(), (lateConnection) => lateConnection.close());
         closeAttachedConnection = () => connection.close();
-        const client = connection.client;
+        const client = cancellation.client(connection.client);
         const { Runtime, DOM, Page } = client;
+        const captureIdentity = async () => {
+            const targetId = target?.targetId ?? target?.id;
+            if (!targetId || !port)
+                return undefined;
+            const { result } = await withTimeout(Runtime.evaluate({ expression: "location.href", returnByValue: true }), 2_000, "Recovery target identity unavailable");
+            return {
+                host,
+                port,
+                targetId,
+                browserWSEndpoint,
+                conversationId: extractConversationIdFromUrl(typeof result?.value === "string" ? result.value : ""),
+            };
+        };
         if (Runtime?.enable) {
             await Runtime.enable();
         }
@@ -105,34 +131,44 @@ export async function resumeBrowserSession(runtime, config, logger, deps = {}) {
         await ensureConversationOpen();
         const waitForHydration = deps.waitForConversationHydration ?? waitForResumedConversationHydration;
         const expectedConversationUrl = buildConversationUrl(runtime, resolveBrowserConfig(config ?? {}).url);
-        await waitForHydration(Runtime, timeoutMs, logger, {
+        await cancellation.call(() => waitForHydration(Runtime, timeoutMs, logger, {
             requirePriorTurns: true,
             requirePromptReady: false,
             expectedConversationUrl: expectedConversationUrl ?? undefined,
-        });
+        }));
         const minTurnIndex = (await readPromptPreviewTurnIndex(Runtime, deps.promptPreview)) ??
             (deps.promptPreview ? null : await readConversationTurnIndex(Runtime, logger));
         if (config?.researchMode === "deep") {
             const waitForDeepResearch = deps.waitForDeepResearchCompletion ?? waitForDeepResearchCompletion;
-            const researchResult = await withTimeout(waitForDeepResearch(Runtime, logger, timeoutMs, minTurnIndex ?? undefined, Page, client, {
+            const researchResult = await withTimeout(cancellation.call(() => waitForDeepResearch(Runtime, logger, timeoutMs, minTurnIndex ?? undefined, Page, client, {
                 requireScopedTargetOwner: true,
-            }), timeoutMs + 5_000, "Reattach Deep Research response timed out");
+            })), timeoutMs + 5_000, "Reattach Deep Research response timed out");
+            const captureTarget = await captureIdentity().catch(() => undefined);
             await closeAttached();
             return {
                 answerText: researchResult.text,
                 answerMarkdown: researchResult.text,
+                captureTarget,
             };
         }
         const promptEcho = buildPromptEchoMatcher(deps.promptPreview);
-        const answer = await withTimeout(waitForResponse(Runtime, timeoutMs, logger, minTurnIndex ?? undefined), timeoutMs + 5_000, "Reattach response timed out");
-        const recovered = await recoverPromptEcho(Runtime, answer, promptEcho, logger, minTurnIndex, timeoutMs);
-        const markdown = (await withTimeout(captureMarkdown(Runtime, recovered.meta, logger), 15_000, "Reattach markdown capture timed out")) ?? recovered.text;
+        const answer = await withTimeout(cancellation.call(() => waitForResponse(Runtime, timeoutMs, logger, minTurnIndex ?? undefined)), timeoutMs + 5_000, "Reattach response timed out");
+        const recovered = await cancellation.call(() => recoverPromptEcho(Runtime, answer, promptEcho, logger, minTurnIndex, timeoutMs));
+        const markdown = (await withTimeout(cancellation.call(() => captureMarkdown(Runtime, recovered.meta, logger)), 15_000, "Reattach markdown capture timed out")) ?? recovered.text;
         const aligned = alignPromptEchoMarkdown(recovered.text, markdown, promptEcho, logger);
+        const captureTarget = await captureIdentity().catch(() => undefined);
         await closeAttached();
-        return { answerText: aligned.answerText, answerMarkdown: aligned.answerMarkdown };
+        return {
+            answerText: aligned.answerText,
+            answerMarkdown: aligned.answerMarkdown,
+            captureTarget,
+        };
     }
     catch (error) {
         await closeAttached();
+        if (deps.signal?.aborted || error instanceof BrowserRunCancelledError) {
+            throw new BrowserRunCancelledError();
+        }
         const message = error instanceof Error ? error.message : String(error);
         logger(`Existing Chrome reattach failed (${message}); reopening browser to locate the session.`);
         return recoverSession(runtime, config);
@@ -172,26 +208,64 @@ function inferPortFromBrowserWSEndpoint(browserWSEndpoint) {
     }
     return undefined;
 }
-async function resumeBrowserSessionViaNewChrome(runtime, config, logger, deps) {
+async function resumeBrowserSessionViaNewChrome(runtime, config, logger, deps, cancellation) {
     const resolved = resolveBrowserConfig(config ?? {});
     const manualLogin = Boolean(resolved.manualLogin);
     const userDataDir = manualLogin
         ? (resolved.manualLoginProfileDir ?? path.join(os.homedir(), ".oracle", "browser-profile"))
-        : await mkdtemp(path.join(os.tmpdir(), "oracle-reattach-"));
+        : await (deps.createTemporaryProfile ?? (() => mkdtemp(path.join(os.tmpdir(), "oracle-reattach-"))))();
     if (manualLogin) {
         await mkdir(userDataDir, { recursive: true });
     }
+    const cleanupProfile = async () => {
+        if (manualLogin) {
+            await cleanupStaleProfileState(userDataDir, logger, { lockRemovalMode: "never" }).catch(() => undefined);
+        }
+        else {
+            await rm(userDataDir, { recursive: true, force: true }).catch(() => undefined);
+        }
+    };
+    if (deps.signal?.aborted) {
+        if (!manualLogin)
+            await cleanupProfile();
+        cancellation.check();
+    }
     const launch = deps.launchChrome ?? launchChrome;
     const connectToLaunchedChrome = deps.connectToChrome ?? connectToChrome;
-    const chrome = await launch(resolved, userDataDir, logger);
+    const chrome = await cancellation.acquire(() => launch(resolved, userDataDir, logger), async (lateChrome) => {
+        if (!resolved.keepBrowser) {
+            try {
+                await lateChrome.kill();
+            }
+            catch {
+                // best-effort cleanup for a browser that finished launching after cancellation
+            }
+            await cleanupProfile();
+        }
+    });
     const chromeHost = chrome && typeof chrome === "object" && "host" in chrome && typeof chrome.host === "string"
         ? chrome.host
         : "127.0.0.1";
-    const client = await connectToLaunchedChrome(chrome.port, logger, chromeHost);
+    let rawClient;
+    try {
+        rawClient = await cancellation.acquire(() => connectToLaunchedChrome(chrome.port, logger, chromeHost), (lateClient) => lateClient.close());
+    }
+    catch (error) {
+        if (!resolved.keepBrowser) {
+            try {
+                await withoutBrowserCancellation(() => chrome.kill());
+            }
+            catch {
+                // best-effort cleanup after a failed or cancelled CDP connection
+            }
+            await cleanupProfile();
+        }
+        throw error;
+    }
     const cleanup = async () => {
-        if (client && typeof client.close === "function") {
+        if (rawClient && typeof rawClient.close === "function") {
             try {
-                await client.close();
+                await rawClient.close();
             }
             catch {
                 // ignore
@@ -204,34 +278,30 @@ async function resumeBrowserSessionViaNewChrome(runtime, config, logger, deps) {
             catch {
                 // ignore
             }
-            if (manualLogin) {
-                await cleanupStaleProfileState(userDataDir, logger, { lockRemovalMode: "never" }).catch(() => undefined);
-            }
-            else {
-                await rm(userDataDir, { recursive: true, force: true }).catch(() => undefined);
-            }
+            await cleanupProfile();
         }
     };
+    const client = cancellation.client(rawClient);
     const { Network, Page, Runtime, DOM, Target } = client;
-    if (Runtime?.enable) {
-        await Runtime.enable();
-    }
-    if (DOM && typeof DOM.enable === "function") {
-        await DOM.enable();
-    }
-    if (!resolved.headless && resolved.hideWindow) {
-        await positionChromeWindowOffscreen(client, userDataDir, logger);
-    }
-    else if (!resolved.headless) {
-        await positionChromeWindowOnscreen(client, userDataDir, logger);
-    }
-    let appliedCookies = 0;
-    if (shouldSyncBrowserCookies(resolved, { manualLogin })) {
-        if (!resolved.inlineCookies) {
-            logger(CHROME_COOKIE_SYNC_WARNING);
+    try {
+        if (Runtime?.enable) {
+            await Runtime.enable();
         }
-        const sync = deps.syncCookies ?? syncCookies;
-        try {
+        if (DOM && typeof DOM.enable === "function") {
+            await DOM.enable();
+        }
+        if (!resolved.headless && resolved.hideWindow) {
+            await positionChromeWindowOffscreen(client, userDataDir, logger);
+        }
+        else if (!resolved.headless) {
+            await positionChromeWindowOnscreen(client, userDataDir, logger);
+        }
+        let appliedCookies = 0;
+        if (shouldSyncBrowserCookies(resolved, { manualLogin })) {
+            if (!resolved.inlineCookies) {
+                logger(CHROME_COOKIE_SYNC_WARNING);
+            }
+            const sync = deps.syncCookies ?? syncCookies;
             appliedCookies = await sync(Network, resolved.url, resolved.chromeProfile, logger, {
                 allowErrors: resolved.allowCookieErrors,
                 filterNames: resolved.cookieNames ?? undefined,
@@ -240,74 +310,73 @@ async function resumeBrowserSessionViaNewChrome(runtime, config, logger, deps) {
                 waitMs: resolved.cookieSyncWaitMs ?? 0,
             });
         }
-        catch (error) {
-            await cleanup();
-            throw error;
-        }
-    }
-    await clearStaleChatGptConversationCookies(Network, Target, logger, {
-        preserveConversationIds: [
-            runtime.conversationId,
-            extractConversationIdFromUrl(runtime.tabUrl ?? ""),
-            extractConversationIdFromUrl(resolved.url),
-        ],
-    });
-    await navigateToChatGPT(Page, Runtime, CHATGPT_URL, logger);
-    await ensureNotBlocked(Runtime, resolved.headless, logger);
-    await ensureLoggedIn(Runtime, logger, { appliedCookies });
-    if (resolved.url !== CHATGPT_URL) {
-        await navigateToChatGPT(Page, Runtime, resolved.url, logger);
-        await ensureNotBlocked(Runtime, resolved.headless, logger);
-    }
-    await ensurePromptReady(Runtime, resolved.inputTimeoutMs, logger);
-    const conversationUrl = buildConversationUrl(runtime, resolved.url);
-    if (conversationUrl) {
-        logger(`Reopening conversation at ${conversationUrl}`);
-        await navigateToChatGPT(Page, Runtime, conversationUrl, logger);
+        await clearStaleChatGptConversationCookies(Network, Target, logger, {
+            preserveConversationIds: [
+                runtime.conversationId,
+                extractConversationIdFromUrl(runtime.tabUrl ?? ""),
+                extractConversationIdFromUrl(resolved.url),
+            ],
+        });
+        await navigateToChatGPT(Page, Runtime, CHATGPT_URL, logger);
         await ensureNotBlocked(Runtime, resolved.headless, logger);
+        await ensureLoggedIn(Runtime, logger, { appliedCookies });
+        if (resolved.url !== CHATGPT_URL) {
+            await navigateToChatGPT(Page, Runtime, resolved.url, logger);
+            await ensureNotBlocked(Runtime, resolved.headless, logger);
+        }
         await ensurePromptReady(Runtime, resolved.inputTimeoutMs, logger);
-    }
-    else {
-        const opened = await openConversationFromSidebarWithRetry(Runtime, {
-            conversationId: runtime.conversationId ?? extractConversationIdFromUrl(runtime.tabUrl ?? ""),
-            preferProjects: resolved.url !== CHATGPT_URL ||
-                Boolean(runtime.tabUrl && (/\/g\//.test(runtime.tabUrl) || runtime.tabUrl.includes("/project"))),
-            promptPreview: deps.promptPreview,
-        }, 15_000);
-        if (!opened) {
-            throw new Error("Unable to locate prior ChatGPT conversation in sidebar.");
+        const conversationUrl = buildConversationUrl(runtime, resolved.url);
+        if (conversationUrl) {
+            logger(`Reopening conversation at ${conversationUrl}`);
+            await navigateToChatGPT(Page, Runtime, conversationUrl, logger);
+            await ensureNotBlocked(Runtime, resolved.headless, logger);
+            await ensurePromptReady(Runtime, resolved.inputTimeoutMs, logger);
+        }
+        else {
+            const opened = await openConversationFromSidebarWithRetry(Runtime, {
+                conversationId: runtime.conversationId ?? extractConversationIdFromUrl(runtime.tabUrl ?? ""),
+                preferProjects: resolved.url !== CHATGPT_URL ||
+                    Boolean(runtime.tabUrl &&
+                        (/\/g\//.test(runtime.tabUrl) || runtime.tabUrl.includes("/project"))),
+                promptPreview: deps.promptPreview,
+            }, 15_000);
+            if (!opened) {
+                throw new Error("Unable to locate prior ChatGPT conversation in sidebar.");
+            }
+            await waitForLocationChange(Runtime, 15_000);
+        }
+        const waitForHydration = deps.waitForConversationHydration ?? waitForResumedConversationHydration;
+        await cancellation.call(() => waitForHydration(Runtime, resolved.inputTimeoutMs, logger, {
+            requirePriorTurns: true,
+            requirePromptReady: false,
+            expectedConversationUrl: conversationUrl ?? undefined,
+        }));
+        const waitForResponse = deps.waitForAssistantResponse ?? waitForAssistantResponse;
+        const captureMarkdown = deps.captureAssistantMarkdown ?? captureAssistantMarkdown;
+        const timeoutMs = resolved.timeoutMs ?? 120_000;
+        const minTurnIndex = (await readPromptPreviewTurnIndex(Runtime, deps.promptPreview)) ??
+            (deps.promptPreview ? null : await readConversationTurnIndex(Runtime, logger));
+        if (resolved.researchMode === "deep") {
+            const waitForDeepResearch = deps.waitForDeepResearchCompletion ?? waitForDeepResearchCompletion;
+            const researchResult = await cancellation.call(() => waitForDeepResearch(Runtime, logger, timeoutMs, minTurnIndex ?? undefined, Page, client, {
+                requireScopedTargetOwner: true,
+            }));
+            return {
+                answerText: researchResult.text,
+                answerMarkdown: researchResult.text,
+            };
         }
-        await waitForLocationChange(Runtime, 15_000);
+        const promptEcho = buildPromptEchoMatcher(deps.promptPreview);
+        const answer = await cancellation.call(() => waitForResponse(Runtime, timeoutMs, logger, minTurnIndex ?? undefined));
+        const recovered = await cancellation.call(() => recoverPromptEcho(Runtime, answer, promptEcho, logger, minTurnIndex, timeoutMs));
+        const markdown = (await cancellation.call(() => captureMarkdown(Runtime, recovered.meta, logger))) ??
+            recovered.text;
+        const aligned = alignPromptEchoMarkdown(recovered.text, markdown, promptEcho, logger);
+        return { answerText: aligned.answerText, answerMarkdown: aligned.answerMarkdown };
     }
-    const waitForHydration = deps.waitForConversationHydration ?? waitForResumedConversationHydration;
-    await waitForHydration(Runtime, resolved.inputTimeoutMs, logger, {
-        requirePriorTurns: true,
-        requirePromptReady: false,
-        expectedConversationUrl: conversationUrl ?? undefined,
-    });
-    const waitForResponse = deps.waitForAssistantResponse ?? waitForAssistantResponse;
-    const captureMarkdown = deps.captureAssistantMarkdown ?? captureAssistantMarkdown;
-    const timeoutMs = resolved.timeoutMs ?? 120_000;
-    const minTurnIndex = (await readPromptPreviewTurnIndex(Runtime, deps.promptPreview)) ??
-        (deps.promptPreview ? null : await readConversationTurnIndex(Runtime, logger));
-    if (resolved.researchMode === "deep") {
-        const waitForDeepResearch = deps.waitForDeepResearchCompletion ?? waitForDeepResearchCompletion;
-        const researchResult = await waitForDeepResearch(Runtime, logger, timeoutMs, minTurnIndex ?? undefined, Page, client, {
-            requireScopedTargetOwner: true,
-        });
-        await cleanup();
-        return {
-            answerText: researchResult.text,
-            answerMarkdown: researchResult.text,
-        };
+    finally {
+        await withoutBrowserCancellation(cleanup);
     }
-    const promptEcho = buildPromptEchoMatcher(deps.promptPreview);
-    const answer = await waitForResponse(Runtime, timeoutMs, logger, minTurnIndex ?? undefined);
-    const recovered = await recoverPromptEcho(Runtime, answer, promptEcho, logger, minTurnIndex, timeoutMs);
-    const markdown = (await captureMarkdown(Runtime, recovered.meta, logger)) ?? recovered.text;
-    const aligned = alignPromptEchoMarkdown(recovered.text, markdown, promptEcho, logger);
-    await cleanup();
-    return { answerText: aligned.answerText, answerMarkdown: aligned.answerMarkdown };
 }
 async function readPromptPreviewTurnIndex(Runtime, promptPreview) {
     const preview = promptPreview?.trim();

package/dist/src/browser/recoveryTarget.js

@@ -0,0 +1,156 @@
+import { randomUUID } from "node:crypto";
+import { sessionStore } from "../sessionStore.js";
+import { connectToRemoteChromeTarget } from "./chromeLifecycle.js";
+import { resolveBrowserApprovalWait } from "./config.js";
+import { extractConversationIdFromUrl } from "./reattachHelpers.js";
+import { STOP_BUTTON_SELECTORS } from "./constants.js";
+import { hasActiveBrowserTargetLease } from "./tabLeaseRegistry.js";
+import { buildTargetRetirementExpression, buildTargetRetirementRollbackExpression, normalizeChromeHost, } from "./targetClaim.js";
+function processMayBeAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code !== "ESRCH";
+    }
+}
+export function hasOtherLiveBrowserController(metadata) {
+    for (const pid of [metadata.browser?.runtime?.controllerPid, metadata.lifecycle?.workerPid]) {
+        if (!pid || pid === process.pid)
+            continue;
+        if (processMayBeAlive(pid))
+            return true;
+    }
+    return false;
+}
+async function targetHasActiveController(metadata, capture) {
+    for (const other of await sessionStore.listSessions()) {
+        if (other.id === metadata.id)
+            continue;
+        const runtime = other.browser?.runtime;
+        if (runtime?.chromeTargetId !== capture.targetId ||
+            runtime.chromePort !== capture.port ||
+            normalizeChromeHost(runtime.chromeHost ?? "127.0.0.1") !== normalizeChromeHost(capture.host))
+            continue;
+        if ([runtime.controllerPid, other.lifecycle?.workerPid].some((pid) => pid && processMayBeAlive(pid)))
+            return true;
+    }
+    const runtime = metadata.browser?.runtime;
+    const profileDirs = new Set([
+        runtime?.userDataDir,
+        runtime?.chromeProfileRoot,
+        metadata.browser?.config?.manualLoginProfileDir,
+    ].filter((dir) => Boolean(dir)));
+    for (const dir of profileDirs) {
+        if (await hasActiveBrowserTargetLease(dir, capture))
+            return true;
+    }
+    return false;
+}
+export function matchesOwnedRecoveryTarget(metadata, capture) {
+    const runtime = metadata.browser?.runtime;
+    const owned = runtime?.ownedRecoveryTarget;
+    const conversationId = runtime?.conversationId ?? extractConversationIdFromUrl(runtime?.tabUrl ?? "");
+    return Boolean(owned &&
+        capture &&
+        conversationId &&
+        capture.conversationId === conversationId &&
+        owned.targetId === capture.targetId &&
+        normalizeChromeHost(owned.host) === normalizeChromeHost(capture.host) &&
+        owned.port === capture.port &&
+        owned.browserWSEndpoint === capture.browserWSEndpoint);
+}
+export function recoveryCaptureFromRuntime(runtime) {
+    const owned = runtime?.ownedRecoveryTarget;
+    const conversationId = runtime?.conversationId ?? extractConversationIdFromUrl(runtime?.tabUrl ?? "");
+    return owned && conversationId ? { ...owned, conversationId } : undefined;
+}
+/** Call only after the full recovered answer and completed session have been saved. */
+export async function retireRecoveredBrowserTarget(sessionId, capture, logger, deps = {}) {
+    await retireOwnedBrowserTarget(sessionId, capture, logger, {
+        ...deps,
+        terminalStatus: "completed",
+        requireIdle: true,
+    });
+}
+/** Call only after cancellation has been persisted for the owning session. */
+export async function retireCancelledBrowserTarget(sessionId, capture, logger, deps = {}) {
+    await retireOwnedBrowserTarget(sessionId, capture, logger, {
+        ...deps,
+        terminalStatus: "cancelled",
+        requireIdle: false,
+    });
+}
+async function retireOwnedBrowserTarget(sessionId, capture, logger, options) {
+    if (!capture)
+        return;
+    let connection;
+    let lockedClaim;
+    const reservationId = randomUUID();
+    let retired = false;
+    try {
+        const metadata = await sessionStore.readSession(sessionId);
+        if (!metadata ||
+            metadata.status !== options.terminalStatus ||
+            metadata.browser?.config?.keepBrowser === true ||
+            hasOtherLiveBrowserController(metadata) ||
+            !matchesOwnedRecoveryTarget(metadata, capture))
+            return;
+        const claimId = metadata.browser?.runtime?.ownedRecoveryTarget?.claimId;
+        if (!claimId)
+            return;
+        const connect = options.connect ?? connectToRemoteChromeTarget;
+        connection = await connect(capture.host, capture.port, logger, {
+            targetId: capture.targetId,
+            browserWSEndpoint: capture.browserWSEndpoint,
+            closeTargetOnDispose: false,
+            approvalWaitMs: resolveBrowserApprovalWait(metadata.browser?.config?.approvalWaitMs),
+        });
+        const { Runtime, Target } = connection.client;
+        const state = await Runtime.evaluate({
+            expression: `(() => ({ url: location.href, generating: Array.from(document.querySelectorAll(${JSON.stringify(STOP_BUTTON_SELECTORS.join(","))})).some(node => node.getBoundingClientRect().width > 0 && node.getBoundingClientRect().height > 0) }))()`,
+            returnByValue: true,
+        });
+        const value = state.result?.value;
+        if (!value ||
+            (options.requireIdle && value.generating !== false) ||
+            extractConversationIdFromUrl(value.url ?? "") !== capture.conversationId)
+            return;
+        const { targetInfos } = await Target.getTargets();
+        if (!targetInfos.some((target) => target.type === "page" && target.targetId !== capture.targetId)) {
+            const replacement = await Target.createTarget({ url: "about:blank" });
+            if (!replacement.targetId)
+                return;
+        }
+        if (await targetHasActiveController(metadata, capture))
+            return;
+        lockedClaim = claimId;
+        const locked = await Runtime.evaluate({
+            expression: buildTargetRetirementExpression(claimId, capture.conversationId, reservationId, {
+                allowGenerating: !options.requireIdle,
+            }),
+            returnByValue: true,
+        });
+        if (locked.exceptionDetails || locked.result?.value !== true)
+            return;
+        const result = await Target.closeTarget({ targetId: capture.targetId });
+        if (!result.success)
+            throw new Error("Chrome refused target retirement");
+        retired = true;
+        logger(options.terminalStatus === "completed"
+            ? "Retired Oracle-owned browser tab after saving the recovered answer."
+            : "Retired Oracle-owned browser tab after cancellation.");
+    }
+    catch (error) {
+        logger(`${options.terminalStatus === "completed" ? "Recovered answer is saved" : "Cancellation is saved"}; browser tab cleanup failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    finally {
+        if (connection && lockedClaim && !retired) {
+            await connection.client.Runtime.evaluate({
+                expression: buildTargetRetirementRollbackExpression(lockedClaim, reservationId),
+            }).catch(() => undefined);
+        }
+        await connection?.close().catch(() => undefined);
+    }
+}

package/dist/src/browser/sessionRunner.js

@@ -4,7 +4,7 @@ import { formatFinishLine } from "../oracle/finishLine.js";
 import { runBrowserMode } from "../browserMode.js";
 import { DEFAULT_BROWSER_CONFIG } from "./config.js";
 import { assembleBrowserPrompt, cleanupGeneratedBrowserBundles, materializeBrowserFallback, } from "./prompt.js";
-import { BrowserAutomationError } from "../oracle/errors.js";
+import { BrowserAutomationError, BrowserRunCancelledError } from "../oracle/errors.js";
 import { appendArtifacts, saveBrowserTranscriptArtifact, saveDeepResearchReportArtifact, } from "./artifacts.js";
 import { formatBrowserModelSelectionEvidence, formatBrowserThinkingSelectionEvidence, formatBrowserModelTarget, resolveBrowserModelDisplayName, } from "./modelDisplay.js";
 const LARGE_PRO_FAST_INPUT_TOKEN_THRESHOLD = 25_000;
@@ -55,24 +55,28 @@ function buildBrowserRunWarnings(args) {
         },
     ];
 }
-export async function runBrowserSessionExecution({ runOptions, browserConfig, cwd, log }, deps = {}) {
+export async function runBrowserSessionExecution({ runOptions, browserConfig, cwd, log, signal }, deps = {}) {
     const assemblePrompt = deps.assemblePrompt ?? assembleBrowserPrompt;
     const executeBrowser = deps.executeBrowser ?? runBrowserMode;
     const persistRuntimeHint = deps.persistRuntimeHint ?? (() => { });
     const inputTimeoutMs = browserConfig.inputTimeoutMs ?? DEFAULT_BROWSER_CONFIG.inputTimeoutMs;
-    let preparationTimedOut = false;
+    let preparationAbandoned = false;
     let preparationTimeout;
+    let removePreparationAbortListener;
     let promptArtifacts;
+    if (signal?.aborted) {
+        throw new BrowserRunCancelledError();
+    }
     try {
         promptArtifacts = await Promise.race([
             assemblePrompt(runOptions, { cwd }).then(async (artifacts) => {
-                if (preparationTimedOut)
+                if (preparationAbandoned)
                     await cleanupGeneratedBrowserBundles(artifacts);
                 return artifacts;
             }),
             new Promise((_, reject) => {
                 preparationTimeout = setTimeout(() => {
-                    preparationTimedOut = true;
+                    preparationAbandoned = true;
                     reject(new BrowserAutomationError(`Browser prompt preparation timed out after ${inputTimeoutMs}ms; increase --browser-input-timeout if local files need more time.`, {
                         stage: "prepare-prompt",
                         code: "prompt-preparation-timeout",
@@ -80,12 +84,27 @@ export async function runBrowserSessionExecution({ runOptions, browserConfig, cw
                     }));
                 }, inputTimeoutMs);
             }),
+            new Promise((_, reject) => {
+                if (!signal)
+                    return;
+                const abort = () => {
+                    preparationAbandoned = true;
+                    reject(new BrowserRunCancelledError());
+                };
+                if (signal.aborted) {
+                    abort();
+                    return;
+                }
+                signal.addEventListener("abort", abort, { once: true });
+                removePreparationAbortListener = () => signal.removeEventListener("abort", abort);
+            }),
         ]);
     }
     finally {
         if (preparationTimeout) {
             clearTimeout(preparationTimeout);
         }
+        removePreparationAbortListener?.();
     }
     try {
         return await executeAssembledBrowserSession({
@@ -95,13 +114,14 @@ export async function runBrowserSessionExecution({ runOptions, browserConfig, cw
             promptArtifacts,
             executeBrowser,
             persistRuntimeHint,
+            signal,
         });
     }
     finally {
         await cleanupGeneratedBrowserBundles(promptArtifacts);
     }
 }
-async function executeAssembledBrowserSession({ runOptions, browserConfig, log, promptArtifacts, executeBrowser, persistRuntimeHint, }) {
+async function executeAssembledBrowserSession({ runOptions, browserConfig, log, promptArtifacts, executeBrowser, persistRuntimeHint, signal, }) {
     if (runOptions.verbose) {
         log(chalk.dim(`[verbose] Browser config: ${JSON.stringify({
             ...browserConfig,
@@ -135,7 +155,7 @@ async function executeAssembledBrowserSession({ runOptions, browserConfig, log,
         if (typeof message !== "string")
             return;
         const shouldAlwaysPrint = message.startsWith("[browser] ") &&
-            /archive|fallback|follow-up|retry|thinking|waiting for chatgpt|remote debugging approval|browser slot|browser control|browser guidance|model selection|model picker/i.test(message);
+            /archive|fallback|follow-up|retry|thinking|research|waiting for chatgpt|remote debugging approval|browser slot|browser control|browser guidance|model selection|model picker/i.test(message);
         if (!runOptions.verbose && !shouldAlwaysPrint)
             return;
         log(message);
@@ -180,6 +200,8 @@ async function executeAssembledBrowserSession({ runOptions, browserConfig, log,
             generateImagePath: runOptions.generateImage,
             outputPath: runOptions.outputPath,
             followUpPrompts: runOptions.browserFollowUps,
+            signal,
+            closeOwnedTabOnCancel: !executionBrowserConfig.keepBrowser,
             runtimeHintCb: async (runtime, modelSelection) => {
                 const runtimeWithController = {
                     ...runtime,
@@ -195,7 +217,7 @@ async function executeAssembledBrowserSession({ runOptions, browserConfig, log,
         });
     }
     catch (error) {
-        if (error instanceof BrowserAutomationError) {
+        if (error instanceof BrowserAutomationError || error instanceof BrowserRunCancelledError) {
             throw error;
         }
         const message = error instanceof Error ? error.message : "Browser automation failed.";
@@ -278,9 +300,12 @@ async function executeAssembledBrowserSession({ runOptions, browserConfig, log,
             chromeProfileRoot: browserResult.chromeProfileRoot,
             userDataDir: browserResult.userDataDir,
             chromeTargetId: browserResult.chromeTargetId,
+            ownedRecoveryTarget: browserResult.ownedRecoveryTarget,
             tabUrl: browserResult.tabUrl,
             conversationId: browserResult.conversationId,
             promptSubmitted: browserResult.promptSubmitted,
+            submittedPromptHash: browserResult.submittedPromptHash,
+            researchPlan: browserResult.researchPlan,
             controllerPid: browserResult.controllerPid ?? process.pid,
         },
         archive: browserResult.archive,