@steipete/oracle 0.12.1 → 0.14.0

package/dist/src/browser/pageActions.js

@@ -1,4 +1,4 @@
-export { navigateToChatGPT, navigateToPromptReadyWithFallback, ensureNotBlocked, ensureLoggedIn, ensurePromptReady, installJavaScriptDialogAutoDismissal, } from "./actions/navigation.js";
+export { navigateToChatGPT, navigateToPromptReadyWithFallback, ensureNotBlocked, ensureLoggedIn, ensurePromptReady, waitForResumedConversationHydration, installJavaScriptDialogAutoDismissal, } from "./actions/navigation.js";
 export { ensureModelSelection } from "./actions/modelSelection.js";
 export { submitPrompt, clearPromptComposer } from "./actions/promptComposer.js";
 export { clearComposerAttachments, uploadAttachmentFile, waitForAttachmentCompletion, waitForUserTurnAttachments, buildUserTurnAttachmentExpressionForTest, } from "./actions/attachments.js";

package/dist/src/browser/policies.js

@@ -1,11 +1,7 @@
-import { formatFileSection } from "../oracle/markdown.js";
+import { formatFileSections } from "../oracle/markdown.js";
 export function buildAttachmentPlan(sections, { inlineFiles, bundleRequested, maxAttachments = 10, }) {
     if (inlineFiles) {
-        const inlineLines = [];
-        sections.forEach((section) => {
-            inlineLines.push(formatFileSection(section.displayPath, section.content).trimEnd(), "");
-        });
-        const inlineBlock = inlineLines.join("\n").trim();
+        const inlineBlock = formatFileSections(sections);
         return {
             mode: "inline",
             inlineBlock,

package/dist/src/browser/projectSourcesRunner.js

@@ -347,11 +347,20 @@ async function maybeReuseProjectSourcesChrome(userDataDir, logger, options = {})
     if (!port) {
         const discovered = await findRunningChromeDebugTargetForProfile(userDataDir);
         if (!discovered) {
+            if (pid) {
+                logger(`No reachable Chrome DevTools target found for ${userDataDir}; clearing stale profile state before launching new Chrome.`);
+                await cleanupStaleProfileState(userDataDir, logger, {
+                    lockRemovalMode: "if_oracle_pid_dead",
+                });
+            }
             return null;
         }
-        const probe = await verifyDevToolsReachable({ port: discovered.port });
+        const probe = await (options.probe ?? verifyDevToolsReachable)({ port: discovered.port });
         if (!probe.ok) {
             logger(`Discovered Chrome for ${userDataDir} on port ${discovered.port} but it was unreachable (${probe.error}); launching new Chrome.`);
+            await cleanupStaleProfileState(userDataDir, logger, {
+                lockRemovalMode: "if_oracle_pid_dead",
+            });
             return null;
         }
         await writeDevToolsActivePort(userDataDir, discovered.port);
@@ -361,7 +370,7 @@ async function maybeReuseProjectSourcesChrome(userDataDir, logger, options = {})
         logger(`Discovered running Chrome for ${userDataDir}; reusing (DevTools port ${port}, pid ${pid})`);
         return { port, pid, kill: async () => { }, process: undefined };
     }
-    const probe = await verifyDevToolsReachable({ port });
+    const probe = await (options.probe ?? verifyDevToolsReachable)({ port });
     if (!probe.ok) {
         logger(`Recorded Chrome DevTools port ${port} is stale (${probe.error}); launching new Chrome.`);
         await cleanupStaleProfileState(userDataDir, logger, { lockRemovalMode: "if_oracle_pid_dead" });
@@ -375,3 +384,6 @@ async function maybeReuseProjectSourcesChrome(userDataDir, logger, options = {})
         process: undefined,
     };
 }
+export async function maybeReuseProjectSourcesChromeForTest(userDataDir, logger, options = {}) {
+    return maybeReuseProjectSourcesChrome(userDataDir, logger, options);
+}

package/dist/src/browser/prompt.js

@@ -1,7 +1,7 @@
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
-import { readFiles, createFileSections, MODEL_CONFIGS, TOKENIZER_OPTIONS, formatFileSection, } from "../oracle.js";
+import { readFiles, createFileSections, MODEL_CONFIGS, TOKENIZER_OPTIONS, formatFileSections, } from "../oracle.js";
 import { isKnownModel } from "../oracle/modelResolver.js";
 import { buildPromptMarkdown } from "../oracle/promptAssembly.js";
 import { buildAttachmentPlan } from "./policies.js";
@@ -35,20 +35,17 @@ export function isMediaFile(filePath) {
     const ext = path.extname(filePath).toLowerCase();
     return MEDIA_EXTENSIONS.has(ext);
 }
-function formatSectionsForBundle(sections) {
-    const bundleLines = [];
-    sections.forEach((section) => {
-        bundleLines.push(formatFileSection(section.displayPath, section.content).trimEnd());
-        bundleLines.push("");
+function formatSectionsForBundle(sections, options = {}) {
+    return formatFileSections(sections, {
+        lineNumbers: options.lineNumbers ?? true,
+        trailingNewline: true,
     });
-    return `${bundleLines
-        .join("\n")
-        .replace(/\n{3,}/g, "\n\n")
-        .trimEnd()}\n`;
 }
 async function writeBrowserBundle(sections, format) {
     const bundleDir = await fs.mkdtemp(path.join(os.tmpdir(), "oracle-browser-bundle-"));
-    const tokenEstimateText = formatSectionsForBundle(sections);
+    const tokenEstimateText = formatSectionsForBundle(sections, {
+        lineNumbers: format === "text",
+    });
     if (format === "zip") {
         const bundlePath = path.join(bundleDir, "attachments-bundle.zip");
         const buffer = createStoredZip(sections.map((section) => ({
@@ -61,6 +58,7 @@ async function writeBrowserBundle(sections, format) {
                 path: bundlePath,
                 displayPath: bundlePath,
                 sizeBytes: buffer.length,
+                generatedBundle: true,
             },
             metadata: { originalCount: sections.length, bundlePath, format },
             tokenEstimateText,
@@ -73,6 +71,7 @@ async function writeBrowserBundle(sections, format) {
             path: bundlePath,
             displayPath: bundlePath,
             sizeBytes: Buffer.byteLength(tokenEstimateText, "utf8"),
+            generatedBundle: true,
         },
         metadata: { originalCount: sections.length, bundlePath, format },
         tokenEstimateText,
@@ -161,10 +160,7 @@ export async function assembleBrowserPrompt(runOptions, deps = {}) {
     let estimatedInputTokens = tokenizer(tokenizerMessages.length > 0 ? tokenizerMessages : [{ role: "user", content: "" }], TOKENIZER_OPTIONS);
     const tokenEstimateIncludesInlineFiles = inlineFileCount > 0 && Boolean(selectedPlan.inlineBlock);
     if (!tokenEstimateIncludesInlineFiles && sections.length > 0) {
-        const attachmentText = bundleText ??
-            sections
-                .map((section) => formatFileSection(section.displayPath, section.content).trimEnd())
-                .join("\n\n");
+        const attachmentText = bundleText ?? formatFileSections(sections, { lineNumbers: false });
         const attachmentTokens = tokenizer([{ role: "user", content: attachmentText }], TOKENIZER_OPTIONS);
         estimatedInputTokens += attachmentTokens;
     }

package/dist/src/browser/providers/chatgptDomProvider.js

@@ -23,6 +23,7 @@ async function submitPromptViaAdapter(ctx) {
         attachmentNames: state.attachmentNames ?? [],
         baselineTurns: state.baselineTurns ?? undefined,
         inputTimeoutMs: state.inputTimeoutMs ?? undefined,
+        attachmentTimeoutMs: state.attachmentTimeoutMs ?? undefined,
         onPromptSubmitted: state.onPromptSubmitted,
     }, ctx.prompt, state.logger);
     state.committedTurns =

package/dist/src/browser/reattach.js

@@ -94,7 +94,9 @@ export async function resumeBrowserSession(runtime, config, logger, deps = {}) {
             (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), timeoutMs + 5_000, "Reattach Deep Research response timed out");
+            const researchResult = await withTimeout(waitForDeepResearch(Runtime, logger, timeoutMs, minTurnIndex ?? undefined, Page, client, {
+                requireScopedTargetOwner: true,
+            }), timeoutMs + 5_000, "Reattach Deep Research response timed out");
             await connection.close().catch(() => undefined);
             return {
                 answerText: researchResult.text,
@@ -239,7 +241,9 @@ async function resumeBrowserSessionViaNewChrome(runtime, config, logger, deps) {
         (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);
+        const researchResult = await waitForDeepResearch(Runtime, logger, timeoutMs, minTurnIndex ?? undefined, Page, client, {
+            requireScopedTargetOwner: true,
+        });
         await cleanup();
         return {
             answerText: researchResult.text,

package/dist/src/browser/reattachability.js

@@ -1,16 +1,19 @@
-export function hasRecoverableChatGptConversation(runtime) {
-    if (!runtime) {
-        return false;
-    }
-    if (runtime.conversationId?.trim()) {
-        return true;
-    }
-    const tabUrl = runtime.tabUrl?.trim();
-    if (!tabUrl) {
+/**
+ * True when the URL points at a specific ChatGPT conversation (`/c/<id>`) on
+ * chatgpt.com or chat.openai.com. Rejects home, project shell, and external
+ * URLs — anything else would be unsafe to auto-reopen in a persistent
+ * signed-in browser profile.
+ */
+export function isRecoverableChatGptConversationUrl(candidate) {
+    const trimmed = candidate?.trim();
+    if (!trimmed) {
         return false;
     }
     try {
-        const url = new URL(tabUrl);
+        const url = new URL(trimmed);
+        if (url.protocol !== "https:" || url.port) {
+            return false;
+        }
         if (url.hostname !== "chatgpt.com" && url.hostname !== "chat.openai.com") {
             return false;
         }
@@ -20,3 +23,12 @@ export function hasRecoverableChatGptConversation(runtime) {
         return false;
     }
 }
+export function hasRecoverableChatGptConversation(runtime) {
+    if (!runtime) {
+        return false;
+    }
+    if (runtime.conversationId?.trim()) {
+        return true;
+    }
+    return isRecoverableChatGptConversationUrl(runtime.tabUrl);
+}

package/dist/src/browser/recoverConversation.js

@@ -0,0 +1,73 @@
+import { launch } from "chrome-launcher";
+import { defaultManualLoginProfileDir } from "./manualLoginProfile.js";
+import { isRecoverableChatGptConversationUrl } from "./reattachability.js";
+const DEFAULT_HYDRATION_DELAY_MS = 3_000;
+/**
+ * Picks the URL to navigate the recovered Chrome tab to.
+ *
+ * Preference order matches `resolveSessionTabRef`: `harvest.url` (post-harvest,
+ * always a ChatGPT conversation URL when present) wins over `runtime.tabUrl`
+ * (the URL the original run last navigated to, which can be stale).
+ *
+ * Both candidates are gated by `isRecoverableChatGptConversationUrl` so a stale
+ * home / project shell URL or an unrelated external URL stored in metadata
+ * cannot navigate the persistent signed-in profile to the wrong page.
+ */
+export function resolveRecoveryUrl(meta) {
+    const harvest = meta?.browser?.harvest ?? {};
+    const runtime = meta?.browser?.runtime ?? {};
+    for (const candidate of [harvest.url, runtime.tabUrl]) {
+        if (isRecoverableChatGptConversationUrl(candidate)) {
+            return candidate;
+        }
+    }
+    return null;
+}
+function resolveProfileDir(meta) {
+    const fromMeta = meta?.browser?.config?.manualLoginProfileDir;
+    if (typeof fromMeta === "string" && fromMeta.length > 0) {
+        return fromMeta;
+    }
+    return defaultManualLoginProfileDir();
+}
+/**
+ * Re-open a previously-harvested ChatGPT conversation by relaunching Chrome
+ * with the session's persistent profile and navigating to the saved tab URL.
+ *
+ * Used as a fallback when `harvestChatGptTab` can find no live tab matching the
+ * stored target (common after the original CLI run exits and closes its
+ * browser). ChatGPT preserves attachments + history at the conversation URL,
+ * so harvesting against the relaunched tab returns the original message + any
+ * assistant response that completed after the original run gave up.
+ */
+export async function recoverConversationTab(meta, logger, options = {}) {
+    const url = resolveRecoveryUrl(meta);
+    if (!url) {
+        throw new Error("Cannot recover conversation: session metadata has no recoverable ChatGPT conversation URL " +
+            "(expected browser.harvest.url or browser.runtime.tabUrl to be a chatgpt.com/c/<id> URL).");
+    }
+    const userDataDir = resolveProfileDir(meta);
+    logger(`[browser] Recovery: relaunching Chrome with profile ${userDataDir} and navigating to ${url}`);
+    const chrome = await launch({
+        chromeFlags: [
+            "--no-first-run",
+            "--no-default-browser-check",
+            "--disable-features=AutomationControlled,TranslateUI",
+            "--disable-sync",
+            "--password-store=basic",
+            "--use-mock-keychain",
+            "--lang=en-US",
+            url,
+        ],
+        userDataDir,
+        handleSIGINT: false,
+    });
+    const host = "127.0.0.1";
+    const port = chrome.port;
+    const hydrationDelayMs = options.hydrationDelayMs ?? DEFAULT_HYDRATION_DELAY_MS;
+    if (hydrationDelayMs > 0) {
+        await new Promise((resolve) => setTimeout(resolve, hydrationDelayMs));
+    }
+    logger(`[browser] Recovery: Chrome listening on ${host}:${port}; tab loaded.`);
+    return { host, port, url, chrome };
+}

package/dist/src/browser/sessionRunner.js

@@ -105,6 +105,9 @@ export async function runBrowserSessionExecution({ runOptions, browserConfig, cw
         log(chalk.dim("Chrome automation does not stream output; this may take a minute..."));
     }
     const persistRuntimeHint = deps.persistRuntimeHint ?? (() => { });
+    const executionBrowserConfig = runOptions.browserResumeConversationUrl
+        ? { ...browserConfig, resumeConversationUrl: runOptions.browserResumeConversationUrl }
+        : browserConfig;
     let browserResult;
     try {
         browserResult = await executeBrowser({
@@ -116,7 +119,7 @@ export async function runBrowserSessionExecution({ runOptions, browserConfig, cw
                     attachments: promptArtifacts.fallback.attachments,
                 }
                 : undefined,
-            config: browserConfig,
+            config: executionBrowserConfig,
             log: automationLogger,
             heartbeatIntervalMs: runOptions.heartbeatIntervalMs,
             verbose: runOptions.verbose,

package/dist/src/cli/bridge/doctor.js

@@ -7,8 +7,9 @@ import { checkTcpConnection, checkRemoteHealth } from "../../remote/health.js";
 import { detectChromeBinary, detectChromeCookieDb } from "../../browser/detect.js";
 import { formatCodexMcpSnippet } from "./codexConfig.js";
 export async function runBridgeDoctor(_options) {
-    const { config: userConfig, path: configPath, loaded } = await loadUserConfig();
+    const { config: userConfig, path: configPath, paths: configPaths, loaded: userConfigLoaded, } = await loadUserConfig();
     const version = getCliVersion();
+    const projectConfigPaths = configPaths.filter((entry) => entry !== configPath);
     const resolvedRemote = resolveRemoteServiceConfig({
         cliHost: undefined,
         cliToken: undefined,
@@ -22,7 +23,11 @@ export async function runBridgeDoctor(_options) {
     lines.push(chalk.dim(`OS: ${process.platform} ${os.release()} (${process.arch})`));
     lines.push(chalk.dim(`Node: ${process.version}`));
     lines.push(chalk.dim(`Oracle: ${version}`));
-    lines.push(chalk.dim(`Config: ${loaded ? configPath : "(missing)"}`));
+    lines.push(chalk.dim(`Config: ${userConfigLoaded ? configPath : `${configPath} (missing)`}`));
+    if (projectConfigPaths.length > 0) {
+        const label = projectConfigPaths.length === 1 ? "Project config" : "Project configs";
+        lines.push(chalk.dim(`${label}: ${projectConfigPaths.join(", ")}`));
+    }
     if (userConfig.engine) {
         lines.push(chalk.dim(`Default engine: ${userConfig.engine}`));
     }

package/dist/src/cli/browserConfig.js

@@ -7,6 +7,7 @@ import { normalizeBrowserModelStrategy } from "../browser/modelStrategy.js";
 import { getOracleHomeDir } from "../oracleHome.js";
 const DEFAULT_BROWSER_TIMEOUT_MS = 1_200_000;
 const DEFAULT_BROWSER_INPUT_TIMEOUT_MS = 60_000;
+const DEFAULT_BROWSER_ATTACHMENT_TIMEOUT_MS = 45_000;
 const DEFAULT_BROWSER_RECHECK_TIMEOUT_MS = 120_000;
 const DEFAULT_BROWSER_AUTO_REATTACH_TIMEOUT_MS = 120_000;
 const DEFAULT_CHROME_PROFILE = "Default";
@@ -15,6 +16,7 @@ const DEFAULT_CHROME_PROFILE = "Default";
 const BROWSER_MODEL_LABELS = [
     // Most specific first (e.g., "gpt-5.2-thinking" before "gpt-5.2")
     ["gpt-5.5-pro", "Pro"],
+    ["gpt-5.5-instant", "GPT-5.5 Instant"],
     ["gpt-5.5", "Thinking 5.5"],
     ["gpt-5.4-pro", "Pro"],
     ["gpt-5.2-thinking", "GPT-5.2 Thinking"],
@@ -26,7 +28,10 @@ const BROWSER_MODEL_LABELS = [
     ["gpt-5.4", "Thinking 5.4"],
     ["gpt-5.2", "GPT-5.2"], // Selects "Auto" in ChatGPT UI
     ["gpt-5.1", "GPT-5.2"], // Legacy alias → Auto
-    ["gemini-3-pro", "Gemini 3 Pro"],
+    ["gemini-3.1-flash-lite", "Gemini 3.1 Flash-Lite"],
+    ["gemini-3.5-flash", "Gemini 3.5 Flash"],
+    ["gemini-3.1-pro", "Gemini 3.1 Pro"],
+    ["gemini-3-pro", "Gemini 3.1 Pro"],
     ["gemini-3-pro-deep-think", "gemini-3-deep-think"],
 ];
 export function normalizeChatGptModelForBrowser(model) {
@@ -34,7 +39,10 @@ export function normalizeChatGptModelForBrowser(model) {
     if (!normalized.startsWith("gpt-") || normalized.includes("codex")) {
         return model;
     }
-    if (normalized === "gpt-5.5-pro" || normalized === "gpt-5.5" || normalized === "gpt-5.4") {
+    if (normalized === "gpt-5.5-pro" ||
+        normalized === "gpt-5.5-instant" ||
+        normalized === "gpt-5.5" ||
+        normalized === "gpt-5.4") {
         return normalized;
     }
     // Pro variants: resolve to the latest Pro model in ChatGPT.
@@ -101,6 +109,9 @@ export async function buildBrowserConfig(options) {
         inputTimeoutMs: options.browserInputTimeout
             ? parseDuration(options.browserInputTimeout, DEFAULT_BROWSER_INPUT_TIMEOUT_MS)
             : undefined,
+        attachmentTimeoutMs: options.browserAttachmentTimeout
+            ? parseDuration(options.browserAttachmentTimeout, DEFAULT_BROWSER_ATTACHMENT_TIMEOUT_MS)
+            : undefined,
         assistantRecheckDelayMs: options.browserRecheckDelay
             ? parseDuration(options.browserRecheckDelay, 0)
             : undefined,

package/dist/src/cli/browserDefaults.js

@@ -43,6 +43,9 @@ export function applyBrowserDefaultsFromConfig(options, config, getSource) {
     if (isUnset("browserInputTimeout") && typeof browser.inputTimeoutMs === "number") {
         options.browserInputTimeout = String(browser.inputTimeoutMs);
     }
+    if (isUnset("browserAttachmentTimeout") && typeof browser.attachmentTimeoutMs === "number") {
+        options.browserAttachmentTimeout = String(browser.attachmentTimeoutMs);
+    }
     if (isUnset("browserRecheckDelay") && typeof browser.assistantRecheckDelayMs === "number") {
         options.browserRecheckDelay = String(browser.assistantRecheckDelayMs);
     }

package/dist/src/cli/browserTabs.js

@@ -3,6 +3,7 @@ import { createHash } from "node:crypto";
 import chalk from "chalk";
 import { sessionStore } from "../sessionStore.js";
 import { collectChatGptTabs, DEFAULT_REMOTE_CHROME_HOST, DEFAULT_REMOTE_CHROME_PORT, extractConversationIdFromUrl, formatBrowserTabState, harvestChatGptTab, sessionMatchesTab, } from "../browser/liveTabs.js";
+import { recoverConversationTab } from "../browser/recoverConversation.js";
 import { resolveOutputPath } from "./writeOutputPath.js";
 const LIVE_POLL_MS = 2000;
 const DEFAULT_STALL_THRESHOLD_MS = 60_000;
@@ -149,80 +150,154 @@ export async function harvestSessionBrowserOutput(sessionId, options = {}) {
     if (!meta) {
         throw new Error(`No session found with ID ${sessionId}.`);
     }
-    const endpoint = sessionBrowserEndpoint(meta) ?? {
+    const initialEndpoint = sessionBrowserEndpoint(meta) ?? {
         host: DEFAULT_REMOTE_CHROME_HOST,
         port: DEFAULT_REMOTE_CHROME_PORT,
     };
-    const harvested = await harvestChatGptTab({
-        host: endpoint.host,
-        port: endpoint.port,
-        ref: options.browserTabRef ?? resolveSessionTabRef(meta),
-        stallWindowMs: options.stallWindowMs,
-    });
-    await persistHarvest(sessionId, meta, harvested);
-    printHarvestSummary(sessionId, harvested);
-    const output = harvested.lastAssistantMarkdown ?? harvested.lastAssistantText ?? "";
-    if (options.writeOutputPath) {
-        await maybeWriteHarvestOutput(options.writeOutputPath, meta.cwd ?? process.cwd(), output);
+    const ref = options.browserTabRef ?? resolveSessionTabRef(meta);
+    const recoverIfMissing = options.recoverIfMissing !== false;
+    let recoveredChrome = null;
+    try {
+        let harvested;
+        try {
+            harvested = await harvestChatGptTab({
+                host: initialEndpoint.host,
+                port: initialEndpoint.port,
+                ref,
+                stallWindowMs: options.stallWindowMs,
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            const isMissingTabError = message.includes("No ChatGPT tab matched") ||
+                message.includes("ECONNREFUSED") ||
+                message.includes("Could not connect");
+            if (!isMissingTabError || !recoverIfMissing) {
+                throw error;
+            }
+            console.log(chalk.yellow(`No live ChatGPT tab matched session "${sessionId}". Attempting recovery by reopening the saved conversation URL.`));
+            const recovered = await recoverConversationTab(meta, (line) => console.log(line));
+            recoveredChrome = recovered.chrome;
+            harvested = await harvestChatGptTab({
+                host: recovered.host,
+                port: recovered.port,
+                ref: recovered.url,
+                stallWindowMs: options.stallWindowMs,
+            });
+        }
+        await persistHarvest(sessionId, meta, harvested);
+        printHarvestSummary(sessionId, harvested);
+        const output = harvested.lastAssistantMarkdown ?? harvested.lastAssistantText ?? "";
+        if (options.writeOutputPath) {
+            await maybeWriteHarvestOutput(options.writeOutputPath, meta.cwd ?? process.cwd(), output);
+        }
+        if (!options.quietOutput && output) {
+            process.stdout.write(`${output}${output.endsWith("\n") ? "" : "\n"}`);
+        }
+        return harvested;
     }
-    if (!options.quietOutput && output) {
-        process.stdout.write(`${output}${output.endsWith("\n") ? "" : "\n"}`);
+    finally {
+        if (recoveredChrome && options.closeAfterRecover) {
+            try {
+                recoveredChrome.kill();
+            }
+            catch {
+                // best-effort cleanup
+            }
+        }
     }
-    return harvested;
 }
 export async function liveTailSessionBrowserOutput(sessionId, options = {}) {
     const meta = await sessionStore.readSession(sessionId);
     if (!meta) {
         throw new Error(`No session found with ID ${sessionId}.`);
     }
-    const endpoint = sessionBrowserEndpoint(meta) ?? {
+    let endpoint = sessionBrowserEndpoint(meta) ?? {
         host: DEFAULT_REMOTE_CHROME_HOST,
         port: DEFAULT_REMOTE_CHROME_PORT,
     };
-    const browserTabRef = options.browserTabRef ?? resolveSessionTabRef(meta);
+    let browserTabRef = options.browserTabRef ?? resolveSessionTabRef(meta);
+    const recoverIfMissing = options.recoverIfMissing !== false;
+    let recoveredChrome = null;
     const stallThresholdMs = options.stallThresholdMs ?? DEFAULT_STALL_THRESHOLD_MS;
     let lastHash = null;
     let unchangedSince = Date.now();
-    while (true) {
-        const harvested = await harvestChatGptTab({
-            host: endpoint.host,
-            port: endpoint.port,
-            ref: browserTabRef,
-        });
-        const fullText = harvested.lastAssistantMarkdown ?? harvested.lastAssistantText ?? "";
-        const hash = createHash("sha1").update(fullText).digest("hex");
-        if (hash !== lastHash) {
-            lastHash = hash;
-            unchangedSince = Date.now();
-            const statusLine = `[${new Date().toISOString()}] state=${harvested.state} stop=${harvested.stopExists ? "yes" : "no"} ` +
-                `send=${harvested.sendExists ? "yes" : "no"} model=${harvested.currentModelLabel || "(unknown)"} ` +
-                `snippet=${snippet(harvested.lastAssistantSnippet || fullText, 160)}`;
-            console.log(statusLine);
-            await persistHarvest(sessionId, meta, harvested);
+    try {
+        // Probe once to see if the live tab is still alive; recover if not.
+        try {
+            await harvestChatGptTab({
+                host: endpoint.host,
+                port: endpoint.port,
+                ref: browserTabRef,
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            const isMissingTabError = message.includes("No ChatGPT tab matched") ||
+                message.includes("ECONNREFUSED") ||
+                message.includes("Could not connect");
+            if (!isMissingTabError || !recoverIfMissing) {
+                throw error;
+            }
+            console.log(chalk.yellow(`No live ChatGPT tab matched session "${sessionId}". Attempting recovery by reopening the saved conversation URL.`));
+            const recovered = await recoverConversationTab(meta, (line) => console.log(line));
+            recoveredChrome = recovered.chrome;
+            endpoint = { host: recovered.host, port: recovered.port };
+            browserTabRef = recovered.url;
         }
-        const derivedState = harvested.stopExists
-            ? Date.now() - unchangedSince >= stallThresholdMs
-                ? "stalled"
-                : "running"
-            : harvested.authenticated
-                ? "completed"
-                : "detached";
-        if (derivedState === "completed" || derivedState === "stalled" || derivedState === "detached") {
-            const finalHarvest = {
-                ...harvested,
-                state: derivedState,
-            };
-            await persistHarvest(sessionId, meta, finalHarvest);
-            printHarvestSummary(sessionId, finalHarvest);
-            const output = finalHarvest.lastAssistantMarkdown ?? finalHarvest.lastAssistantText ?? "";
-            if (options.writeOutputPath) {
-                await maybeWriteHarvestOutput(options.writeOutputPath, meta.cwd ?? process.cwd(), output);
+        while (true) {
+            const harvested = await harvestChatGptTab({
+                host: endpoint.host,
+                port: endpoint.port,
+                ref: browserTabRef,
+            });
+            const fullText = harvested.lastAssistantMarkdown ?? harvested.lastAssistantText ?? "";
+            const hash = createHash("sha1").update(fullText).digest("hex");
+            if (hash !== lastHash) {
+                lastHash = hash;
+                unchangedSince = Date.now();
+                const statusLine = `[${new Date().toISOString()}] state=${harvested.state} stop=${harvested.stopExists ? "yes" : "no"} ` +
+                    `send=${harvested.sendExists ? "yes" : "no"} model=${harvested.currentModelLabel || "(unknown)"} ` +
+                    `snippet=${snippet(harvested.lastAssistantSnippet || fullText, 160)}`;
+                console.log(statusLine);
+                await persistHarvest(sessionId, meta, harvested);
+            }
+            const derivedState = harvested.stopExists
+                ? Date.now() - unchangedSince >= stallThresholdMs
+                    ? "stalled"
+                    : "running"
+                : harvested.authenticated
+                    ? "completed"
+                    : "detached";
+            if (derivedState === "completed" ||
+                derivedState === "stalled" ||
+                derivedState === "detached") {
+                const finalHarvest = {
+                    ...harvested,
+                    state: derivedState,
+                };
+                await persistHarvest(sessionId, meta, finalHarvest);
+                printHarvestSummary(sessionId, finalHarvest);
+                const output = finalHarvest.lastAssistantMarkdown ?? finalHarvest.lastAssistantText ?? "";
+                if (options.writeOutputPath) {
+                    await maybeWriteHarvestOutput(options.writeOutputPath, meta.cwd ?? process.cwd(), output);
+                }
+                if (output) {
+                    process.stdout.write(`${output}${output.endsWith("\n") ? "" : "\n"}`);
+                }
+                return finalHarvest;
+            }
+            await new Promise((resolve) => setTimeout(resolve, LIVE_POLL_MS));
+        }
+    }
+    finally {
+        if (recoveredChrome && options.closeAfterRecover) {
+            try {
+                recoveredChrome.kill();
             }
-            if (output) {
-                process.stdout.write(`${output}${output.endsWith("\n") ? "" : "\n"}`);
+            catch {
+                // best-effort cleanup
             }
-            return finalHarvest;
         }
-        await new Promise((resolve) => setTimeout(resolve, LIVE_POLL_MS));
     }
 }

package/dist/src/cli/engine.js

@@ -14,9 +14,10 @@ export function defaultWaitPreference(model, engine) {
  * 2) Explicit --engine value.
  * 3) Explicit API provider routing flags force API.
  * 4) ORACLE_ENGINE environment override (api|browser).
- * 5) API environment decides: api when set, otherwise browser.
+ * 5) Config engine value.
+ * 6) API environment decides: api when set, otherwise browser.
  */
-export function resolveEngine({ engine, browserFlag, apiProviderRequested, env, }) {
+export function resolveEngine({ engine, configEngine, browserFlag, apiProviderRequested, env, }) {
     if (browserFlag) {
         return "browser";
     }
@@ -30,6 +31,9 @@ export function resolveEngine({ engine, browserFlag, apiProviderRequested, env,
     if (envEngine) {
         return envEngine;
     }
+    if (configEngine) {
+        return configEngine;
+    }
     return hasApiEnvironment(env) ? "api" : "browser";
 }
 function hasApiEnvironment(env) {