@steipete/oracle 0.11.1 → 0.12.0

package/dist/bin/oracle-cli.js

@@ -2,7 +2,6 @@
 import "dotenv/config";
 import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
-import { once } from "node:events";
 import { Command, Option } from "commander";
 // Allow `npx @steipete/oracle oracle-mcp` to resolve the MCP server even though npx runs the default binary.
 if (process.argv[2] === "oracle-mcp") {
@@ -15,41 +14,33 @@ import { shouldRequirePrompt } from "../src/cli/promptRequirement.js";
 import { resolveDashPrompt } from "../src/cli/stdin.js";
 import chalk from "chalk";
 import { sessionStore, pruneOldSessions } from "../src/sessionStore.js";
-import { DEFAULT_MODEL, MODEL_CONFIGS, readFiles, estimateRequestTokens, buildRequestBody, } from "../src/oracle.js";
+import { DEFAULT_MODEL, MODEL_CONFIGS } from "../src/oracle/config.js";
 import { isKnownModel } from "../src/oracle/modelResolver.js";
-import { CHATGPT_URL } from "../src/browserMode.js";
-import { createRemoteBrowserExecutor } from "../src/remote/client.js";
-import { createGeminiWebExecutor } from "../src/gemini-web/index.js";
+import { CHATGPT_URL } from "../src/browser/constants.js";
 import { applyHelpStyling } from "../src/cli/help.js";
 import { collectPaths, collectModelList, collectTextValues, parseFloatOption, parseIntOption, parseSearchOption, usesDefaultStatusFilters, resolvePreviewMode, normalizeModelOption, normalizeBaseUrl, resolveApiModel, inferModelFromLabel, parseHeartbeatOption, parseTimeoutOption, parseDurationOption, mergePathLikeOptions, dedupePathInputs, } from "../src/cli/options.js";
 import { copyToClipboard } from "../src/cli/clipboard.js";
 import { buildMarkdownBundle } from "../src/cli/markdownBundle.js";
 import { shouldDetachSession } from "../src/cli/detach.js";
 import { applyHiddenAliases } from "../src/cli/hiddenAliases.js";
-import { buildBrowserConfig, resolveBrowserModelLabel } from "../src/cli/browserConfig.js";
-import { performSessionRun } from "../src/cli/sessionRunner.js";
 import { isMediaFile } from "../src/browser/prompt.js";
-import { attachSession, showStatus, formatCompletionSummary } from "../src/cli/sessionDisplay.js";
 import { formatCompactNumber } from "../src/cli/format.js";
 import { formatIntroLine } from "../src/cli/tagline.js";
 import { warnIfOversizeBundle } from "../src/cli/bundleWarnings.js";
 import { formatRenderedMarkdown } from "../src/cli/renderOutput.js";
 import { resolveRenderFlag, resolveRenderPlain } from "../src/cli/renderFlags.js";
-import { resolveGeminiModelId } from "../src/oracle/gemini.js";
-import { handleSessionCommand, formatSessionCleanupMessage, } from "../src/cli/sessionCommand.js";
+import { resolveGeminiModelId } from "../src/oracle/geminiModels.js";
 import { isErrorLogged } from "../src/cli/errorUtils.js";
-import { handleSessionAlias, handleStatusFlag } from "../src/cli/rootAlias.js";
 import { resolveOutputPath } from "../src/cli/writeOutputPath.js";
-import { showBrowserTabsStatus } from "../src/cli/browserTabs.js";
 import { getCliVersion } from "../src/version.js";
-import { runDryRunSummary, runBrowserPreview } from "../src/cli/dryRun.js";
-import { launchTui } from "../src/cli/tui/index.js";
 import { resolveNotificationSettings, deriveNotificationSettingsFromMetadata, } from "../src/cli/notifier.js";
 import { loadUserConfig } from "../src/config.js";
-import { applyBrowserDefaultsFromConfig } from "../src/cli/browserDefaults.js";
 import { shouldBlockDuplicatePrompt } from "../src/cli/duplicatePromptGuard.js";
 import { resolveRemoteServiceConfig } from "../src/remote/remoteServiceConfig.js";
 import { resolveConfiguredMaxFileSizeBytes } from "../src/cli/fileSize.js";
+import { isAzureOpenAICandidateModel, validateProviderRouting, } from "../src/oracle/providerRouting.js";
+import { buildSessionLifecycle, formatSessionLifecycleBlock } from "../src/cli/sessionLifecycle.js";
+import { buildDetachedPerfTraceEnv, createPerfTrace, isTraceValueFlag, } from "../src/cli/perfTrace.js";
 const VERSION = getCliVersion();
 const CLI_ENTRYPOINT = fileURLToPath(import.meta.url);
 const LEGACY_FLAG_ALIASES = new Map([
@@ -57,19 +48,117 @@ const LEGACY_FLAG_ALIASES = new Map([
     ["--[no-]notify-sound", "--notify-sound"],
     ["--[no-]background", "--background"],
 ]);
-const normalizedArgv = process.argv.map((arg, index) => {
+const legacyNormalizedArgv = process.argv.map((arg, index) => {
     if (index < 2)
         return arg;
     return LEGACY_FLAG_ALIASES.get(arg) ?? arg;
 });
-const rawCliArgs = normalizedArgv.slice(2);
-const userCliArgs = rawCliArgs[0] === CLI_ENTRYPOINT ? rawCliArgs.slice(1) : rawCliArgs;
+const rawCliArgs = legacyNormalizedArgv.slice(2);
+const hasCliEntrypointArg = rawCliArgs[0] === CLI_ENTRYPOINT;
+const originalUserCliArgs = hasCliEntrypointArg ? rawCliArgs.slice(1) : rawCliArgs;
+const perfTraceArgs = normalizePerfTraceArgs(originalUserCliArgs);
+const userCliArgs = perfTraceArgs.args;
+const normalizedArgv = [
+    ...legacyNormalizedArgv.slice(0, 2),
+    ...(hasCliEntrypointArg ? [CLI_ENTRYPOINT] : []),
+    ...userCliArgs,
+];
+const routingCliArgs = stripPerfTraceArgs(userCliArgs);
 const isTty = process.stdout.isTTY;
-const suppressIntro = userCliArgs[0] === "bridge" &&
-    (userCliArgs[1] === "codex-config" || userCliArgs[1] === "claude-config");
+const perfTrace = createPerfTrace({
+    value: perfTraceArgs.value,
+    argv: userCliArgs,
+    version: VERSION,
+});
+process.once("exit", (code) => {
+    try {
+        perfTrace.flush(code);
+    }
+    catch (error) {
+        console.error(`Failed to write perf trace: ${error instanceof Error ? error.message : error}`);
+    }
+});
+function stripPerfTraceArgs(args) {
+    const stripped = [];
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === "--perf-trace")
+            continue;
+        if (arg === "--perf-trace-path") {
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith("--perf-trace-path="))
+            continue;
+        stripped.push(arg);
+    }
+    return stripped;
+}
+function normalizePerfTraceArgs(args) {
+    const normalized = [];
+    let skipNextValue = false;
+    let value;
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (skipNextValue) {
+            normalized.push(arg);
+            skipNextValue = false;
+            continue;
+        }
+        if (arg === "--") {
+            normalized.push(...args.slice(index));
+            break;
+        }
+        if (arg.startsWith("--perf-trace=")) {
+            const tracePath = arg.slice("--perf-trace=".length);
+            if (tracePath) {
+                normalized.push("--perf-trace", "--perf-trace-path", tracePath);
+                value = tracePath;
+            }
+            else {
+                normalized.push("--perf-trace");
+                value = true;
+            }
+            continue;
+        }
+        if (arg === "--perf-trace-path") {
+            const tracePath = args[index + 1];
+            if (!tracePath || tracePath.startsWith("-")) {
+                return { args: normalized, error: "option '--perf-trace-path <path>' argument missing" };
+            }
+            normalized.push(arg, tracePath);
+            value = tracePath;
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith("--perf-trace-path=") && !arg.slice("--perf-trace-path=".length)) {
+            return { args: normalized, error: "option '--perf-trace-path <path>' argument missing" };
+        }
+        if (arg.startsWith("--perf-trace-path=")) {
+            value = arg.slice("--perf-trace-path=".length);
+        }
+        else if (arg === "--perf-trace") {
+            value ??= true;
+        }
+        normalized.push(arg);
+        const equalsIndex = arg.indexOf("=");
+        const flag = equalsIndex >= 0 ? arg.slice(0, equalsIndex) : arg;
+        skipNextValue = equalsIndex < 0 && isTraceValueFlag(flag);
+    }
+    return { args: normalized, value };
+}
+const doctorArgIndex = routingCliArgs.indexOf("doctor");
+const doctorJsonRequested = doctorArgIndex >= 0 && routingCliArgs.slice(doctorArgIndex).includes("--json");
+const docsArgIndex = routingCliArgs.indexOf("docs");
+const docsCheckRequested = docsArgIndex >= 0 && routingCliArgs[docsArgIndex + 1] === "check";
+const suppressIntro = doctorJsonRequested ||
+    docsCheckRequested ||
+    (routingCliArgs[0] === "bridge" &&
+        (routingCliArgs[1] === "codex-config" || routingCliArgs[1] === "claude-config"));
 const program = new Command();
 let introPrinted = false;
-program.hook("preAction", () => {
+program.hook("preAction", (_thisCommand, actionCommand) => {
+    perfTrace.mark("pre-action", { command: actionCommand.name() || "root" });
     if (suppressIntro)
         return;
     if (introPrinted)
@@ -82,10 +171,10 @@ program.hook("preAction", async (thisCommand) => {
     if (thisCommand !== program) {
         return;
     }
-    if (userCliArgs.some((arg) => arg === "--help" || arg === "-h")) {
+    if (routingCliArgs.some((arg) => arg === "--help" || arg === "-h")) {
         return;
     }
-    if (userCliArgs.length === 0) {
+    if (routingCliArgs.length === 0) {
         // Let the root action handle zero-arg entry (help + hint to `oracle tui`).
         return;
     }
@@ -101,10 +190,9 @@ program.hook("preAction", async (thisCommand) => {
         opts.prompt = resolvedPrompt;
         thisCommand.setOptionValue("prompt", resolvedPrompt);
     }
-    if (shouldRequirePrompt(userCliArgs, opts)) {
+    if (shouldRequirePrompt(routingCliArgs, opts)) {
         console.log(chalk.yellow('Prompt is required. Provide it via --prompt "<text>" or positional [prompt].'));
-        thisCommand.help({ error: false });
-        process.exitCode = 1;
+        thisCommand.help({ error: true });
         return;
     }
 });
@@ -118,6 +206,7 @@ program
     .option("--followup <sessionId|responseId>", "Continue an OpenAI/Azure Responses API run from a stored response id (resp_...) or from a stored oracle session id.")
     .option("--followup-model <model>", "When following up a multi-model session, choose which model response to continue from.")
     .option("-f, --file <paths...>", "Files/directories or glob patterns to attach (prefix with !pattern to exclude). Oversized files are rejected automatically (default cap: 1 MB; configurable via ORACLE_MAX_FILE_SIZE_BYTES or config.maxFileSizeBytes).", collectPaths, [])
+    .option("--max-file-size-bytes <bytes>", "Reject files larger than this many bytes.", parseIntOption)
     .addOption(new Option("--include <paths...>", "Alias for --file.")
     .argParser(collectPaths)
     .default([])
@@ -151,7 +240,7 @@ program
     .addOption(new Option("--no-notify", "Disable desktop notifications.").default(undefined))
     .addOption(new Option("--notify-sound", "Play a notification sound on completion (default off).").default(undefined))
     .addOption(new Option("--no-notify-sound", "Disable notification sounds.").default(undefined))
-    .addOption(new Option("--timeout <seconds|auto>", "Overall timeout before aborting the API call (auto = 60m for Pro models, 120s otherwise).")
+    .addOption(new Option("--timeout <seconds|duration|auto>", "Overall timeout before aborting the API call (auto = 60m for Pro models, 120s otherwise).")
     .argParser(parseTimeoutOption)
     .default("auto"))
     .addOption(new Option("--background", "Use Responses API background mode (create + retrieve) for API runs.").default(undefined))
@@ -171,6 +260,10 @@ program
     .choices(["summary", "json", "full"])
     .preset("summary")
     .default(false))
+    .option("--route", "Print API provider route plan and exit.", false)
+    .option("--preflight", "Check API provider readiness for the requested model(s) and exit.", false)
+    .addOption(new Option("--perf-trace", "Write CLI performance timing trace JSON (or set ORACLE_PERF_TRACE=1/path).").default(false))
+    .addOption(new Option("--perf-trace-path <path>", "Write CLI performance timing trace JSON to an explicit path.").default(undefined))
     .addOption(new Option("--exec-session <id>").hideHelp())
     .addOption(new Option("--session <id>").hideHelp())
     .addOption(new Option("--status", "Show stored sessions (alias for `oracle status`).")
@@ -180,6 +273,10 @@ program
     .option("--render", "Alias for --render-markdown.", false)
     .option("--render-plain", "Render markdown without ANSI/highlighting (use plain text even in a TTY).", false)
     .option("--write-output <path>", "Write only the final assistant message to this file (overwrites; multi-model appends .<model> before the extension).")
+    .option("--allow-partial", "Exit 0 for multi-model runs when at least one model succeeds.", false)
+    .addOption(new Option("--partial <mode>", "Multi-model failure policy (fail | ok).")
+    .choices(["fail", "ok"])
+    .default(undefined))
     .option("--verbose-render", "Show render/TTY diagnostics when replaying sessions.", false)
     .addOption(new Option("--search <mode>", "Set server-side search behavior (on/off).")
     .argParser(parseSearchOption)
@@ -191,6 +288,10 @@ program
     .argParser(parseIntOption)
     .hideHelp())
     .option("--base-url <url>", "Override the OpenAI-compatible base URL for API runs (e.g. LiteLLM proxy endpoint).")
+    .addOption(new Option("--provider <provider>", "Choose API provider routing: auto, openai, or azure. Use openai to ignore Azure env/config.")
+    .choices(["auto", "openai", "azure"])
+    .default("auto"))
+    .option("--no-azure", "Disable Azure OpenAI routing for this run (same as --provider openai).")
     .option("--azure-endpoint <url>", "Azure OpenAI Endpoint (e.g. https://resource.openai.azure.com/).")
     .option("--azure-deployment <name>", "Azure OpenAI Deployment Name.")
     .option("--azure-api-version <version>", "Azure OpenAI API Version.")
@@ -221,6 +322,7 @@ program
     .addOption(new Option("--browser-inline-cookies-file <path>", "Load inline cookies from file (JSON or base64 JSON).").hideHelp())
     .addOption(new Option("--browser-no-cookie-sync", "Skip copying cookies from Chrome.").hideHelp())
     .addOption(new Option("--browser-manual-login", "Skip cookie copy; reuse a persistent automation profile and wait for manual ChatGPT login.").hideHelp())
+    .addOption(new Option("--browser-manual-login-profile-dir <path>", "Persistent Chrome profile directory for manual-login browser runs.").hideHelp())
     .addOption(new Option("--browser-headless", "Launch Chrome in headless mode.").hideHelp())
     .addOption(new Option("--browser-hide-window", "Hide the Chrome window after launch (macOS headful only).").hideHelp())
     .addOption(new Option("--browser-keep-browser", "Keep Chrome running after completion.").hideHelp())
@@ -243,6 +345,9 @@ program
     .addOption(new Option("--remote-token <token>", "Access token for the remote `oracle serve` instance."))
     .addOption(new Option("--browser-inline-files", "Alias for --browser-attachments never (force pasting file contents inline).").default(false))
     .addOption(new Option("--browser-bundle-files", "Bundle all attachments into a single archive before uploading.").default(false))
+    .addOption(new Option("--browser-bundle-format <format>", "Bundle format for browser uploads when files are bundled: text (default) or zip.")
+    .choices(["text", "zip"])
+    .default("text"))
     .addOption(new Option("--youtube <url>", "YouTube video URL to analyze (Gemini web/cookie mode only; uses your signed-in Chrome cookies for gemini.google.com)."))
     .addOption(new Option("--generate-image <file>", "Generate image and save to file (Gemini browser mode; ChatGPT browser mode saves downloadable image artifacts when present)."))
     .addOption(new Option("--edit-image <file>", "Edit existing image (Gemini browser mode; for ChatGPT attach source images with --file and use --generate-image for output)."))
@@ -391,9 +496,46 @@ program
     .command("tui")
     .description("Launch the interactive terminal UI for humans (no automation).")
     .action(async () => {
+    const { launchTui } = await import("../src/cli/tui/index.js");
     await sessionStore.ensureStorage();
     await launchTui({ version: VERSION, printIntro: false });
 });
+program
+    .command("doctor")
+    .description("Diagnose Oracle API provider readiness and routing.")
+    .option("--providers", "Inspect API provider keys and route choices.", false)
+    .option("--models <models>", "Comma-separated API model list to inspect.")
+    .option("-m, --model <model>", "Single API model to inspect.")
+    .addOption(new Option("--provider <provider>", "Choose API provider routing: auto, openai, or azure.")
+    .choices(["auto", "openai", "azure"])
+    .default("auto"))
+    .option("--no-azure", "Disable Azure OpenAI routing for this inspection.")
+    .option("--azure-endpoint <url>", "Azure OpenAI Endpoint.")
+    .option("--azure-deployment <name>", "Azure OpenAI Deployment Name.")
+    .option("--azure-api-version <version>", "Azure OpenAI API Version.")
+    .option("--base-url <url>", "Override OpenAI-compatible base URL.")
+    .option("--json", "Print structured JSON.", false)
+    .action(async function () {
+    const { runProviderDoctor } = await import("../src/cli/providerDoctor.js");
+    await runProviderDoctor(this.optsWithGlobals());
+});
+const docsCommand = program.command("docs").description("Documentation maintenance utilities.");
+docsCommand
+    .command("check")
+    .description("Check documented CLI flags against Commander help metadata.")
+    .option("--docs-path <file...>", "Markdown files to check (default core shipped docs).")
+    .option("--json", "Print structured JSON.", false)
+    .action(async (options) => {
+    const { checkDocsFlags, printDocsCheckResult } = await import("../src/cli/docsCheck.js");
+    const result = await checkDocsFlags({ command: program, paths: options.docsPath });
+    if (options.json) {
+        console.log(JSON.stringify(result, null, 2));
+    }
+    else {
+        printDocsCheckResult(result);
+    }
+    process.exitCode = result.issues.length > 0 ? 1 : 0;
+});
 program
     .command("session [id]")
     .description("Attach to a stored session or list recent sessions when no ID is provided.")
@@ -412,6 +554,7 @@ program
     .option("--browser-tab <ref>", "Override the browser tab ref used for harvesting/live tail (current, target id, URL, or title substring).")
     .addOption(new Option("--clean", "Deprecated alias for --clear.").default(false).hideHelp())
     .action(async (sessionId, _options, cmd) => {
+    const { handleSessionCommand } = await import("../src/cli/sessionCommand.js");
     await handleSessionCommand(sessionId, cmd);
 });
 program
@@ -435,6 +578,7 @@ program
             process.exitCode = 1;
             return;
         }
+        const { showBrowserTabsStatus } = await import("../src/cli/browserTabs.js");
         await showBrowserTabsStatus();
         return;
     }
@@ -449,6 +593,7 @@ program
         const includeAll = statusOptions.all;
         const result = await sessionStore.deleteOlderThan({ hours, includeAll });
         const scope = includeAll ? "all stored sessions" : `sessions older than ${hours}h`;
+        const { formatSessionCleanupMessage } = await import("../src/cli/sessionCommand.js");
         console.log(formatSessionCleanupMessage(result, scope));
         return;
     }
@@ -463,10 +608,12 @@ program
             ? process.stdout.isTTY
             : false;
         const renderMarkdown = Boolean(statusOptions.render || statusOptions.renderMarkdown || autoRender);
+        const { attachSession } = await import("../src/cli/sessionDisplay.js");
         await attachSession(sessionId, { renderMarkdown, renderPrompt: !statusOptions.hidePrompt });
         return;
     }
     const showExamples = usesDefaultStatusFilters(command);
+    const { showStatus } = await import("../src/cli/sessionDisplay.js");
     await showStatus({
         hours: statusOptions.all ? Infinity : statusOptions.hours,
         includeAll: statusOptions.all,
@@ -490,6 +637,13 @@ function buildRunOptions(options, overrides = {}) {
         throw new Error("Prompt is required.");
     }
     const normalizedBaseUrl = normalizeBaseUrl(overrides.baseUrl ?? options.baseUrl);
+    const timeoutSeconds = overrides.timeoutSeconds ?? options.timeout;
+    const resolvedTimeoutMs = typeof timeoutSeconds === "number" && Number.isFinite(timeoutSeconds) && timeoutSeconds > 0
+        ? timeoutSeconds * 1000
+        : undefined;
+    const httpTimeoutMs = overrides.httpTimeoutMs ?? options.httpTimeout ?? resolvedTimeoutMs;
+    const zombieTimeoutMs = overrides.zombieTimeoutMs ?? options.zombieTimeout ?? resolvedTimeoutMs;
+    const partialMode = options.allowPartial ? "ok" : options.partial;
     const azure = options.azureEndpoint || overrides.azure?.endpoint
         ? {
             endpoint: overrides.azure?.endpoint ?? options.azureEndpoint,
@@ -510,15 +664,17 @@ function buildRunOptions(options, overrides = {}) {
         maxInput: overrides.maxInput ?? options.maxInput,
         maxOutput: overrides.maxOutput ?? options.maxOutput,
         system: overrides.system ?? options.system,
-        timeoutSeconds: overrides.timeoutSeconds ?? options.timeout,
-        httpTimeoutMs: overrides.httpTimeoutMs ?? options.httpTimeout,
-        zombieTimeoutMs: overrides.zombieTimeoutMs ?? options.zombieTimeout,
+        timeoutSeconds,
+        httpTimeoutMs,
+        zombieTimeoutMs,
         zombieUseLastActivity: overrides.zombieUseLastActivity ?? options.zombieLastActivity,
+        partialMode,
         silent: overrides.silent ?? options.silent,
         search: overrides.search ?? options.search,
         preview: overrides.preview ?? undefined,
         previewMode: overrides.previewMode ?? options.previewMode,
         apiKey: overrides.apiKey ?? options.apiKey,
+        provider: overrides.provider ?? options.provider,
         baseUrl: normalizedBaseUrl,
         azure,
         sessionId: overrides.sessionId ?? options.sessionId,
@@ -529,6 +685,7 @@ function buildRunOptions(options, overrides = {}) {
             "auto",
         browserInlineFiles: overrides.browserInlineFiles ?? options.browserInlineFiles ?? false,
         browserBundleFiles: overrides.browserBundleFiles ?? options.browserBundleFiles ?? false,
+        browserBundleFormat: overrides.browserBundleFormat ?? options.browserBundleFormat ?? "text",
         generateImage: overrides.generateImage ?? options.generateImage,
         outputPath: overrides.outputPath ?? options.output,
         browserFollowUps: overrides.browserFollowUps ?? options.browserFollowUp ?? [],
@@ -537,6 +694,59 @@ function buildRunOptions(options, overrides = {}) {
         writeOutputPath: overrides.writeOutputPath ?? options.writeOutputPath,
     };
 }
+function resolveApiProviderMode(options) {
+    const provider = options.provider ?? "auto";
+    if (provider === "azure" && options.azure === false) {
+        throw new Error("--provider azure cannot be combined with --no-azure.");
+    }
+    if (options.azure === false) {
+        return "openai";
+    }
+    return provider;
+}
+function hasExplicitAzureOption(optionUsesDefault) {
+    return (!optionUsesDefault("azureEndpoint") ||
+        !optionUsesDefault("azureDeployment") ||
+        !optionUsesDefault("azureApiVersion"));
+}
+function firstNonEmpty(...values) {
+    return values.find((value) => value?.trim());
+}
+function formatRouteTargetForLog(raw) {
+    if (!raw)
+        return "";
+    try {
+        const parsed = new URL(raw);
+        const segments = parsed.pathname.split("/").filter(Boolean);
+        let routePath = "";
+        if (segments.length > 0) {
+            routePath = `/${segments[0]}`;
+            if (segments.length > 1) {
+                routePath += "/...";
+            }
+        }
+        return `${parsed.host}${routePath}`;
+    }
+    catch {
+        return raw.replace(/^https?:\/\//u, "").replace(/\/+$/u, "");
+    }
+}
+function validateApiProviderRoutingForCli(runOptions) {
+    const models = Array.isArray(runOptions.models) && runOptions.models.length > 0
+        ? runOptions.models
+        : [runOptions.model];
+    for (const model of models) {
+        validateProviderRouting({
+            model,
+            providerMode: runOptions.provider,
+            azure: runOptions.azure,
+        }, {
+            onAzureDeploymentMissing: (state) => {
+                console.log(chalk.dim(`Provider: Azure OpenAI | endpoint: ${formatRouteTargetForLog(state.azureEndpoint)} | deployment: none | key: ${runOptions.apiKey ? "apiKey option" : "AZURE_OPENAI_API_KEY|OPENAI_API_KEY"}`));
+            },
+        });
+    }
+}
 export function enforceBrowserSearchFlag(runOptions, sessionMode, logFn = console.log) {
     if (sessionMode === "browser" && runOptions.search === false) {
         logFn(chalk.dim("Note: search is not available in browser engine; ignoring search=false."));
@@ -696,18 +906,21 @@ function buildRunOptionsFromMetadata(metadata) {
         preview: false,
         previewMode: undefined,
         apiKey: undefined,
+        provider: stored.provider,
         baseUrl: normalizeBaseUrl(stored.baseUrl),
         azure: stored.azure,
         timeoutSeconds: stored.timeoutSeconds,
         httpTimeoutMs: stored.httpTimeoutMs,
         zombieTimeoutMs: stored.zombieTimeoutMs,
         zombieUseLastActivity: stored.zombieUseLastActivity,
+        partialMode: stored.partialMode,
         sessionId: metadata.id,
         verbose: stored.verbose,
         heartbeatIntervalMs: stored.heartbeatIntervalMs,
         browserAttachments: stored.browserAttachments,
         browserInlineFiles: stored.browserInlineFiles,
         browserBundleFiles: stored.browserBundleFiles,
+        browserBundleFormat: stored.browserBundleFormat,
         browserFollowUps: stored.browserFollowUps,
         background: stored.background,
         renderPlain: stored.renderPlain,
@@ -721,7 +934,9 @@ function getBrowserConfigFromMetadata(metadata) {
     return metadata.options?.browserConfig ?? metadata.browser?.config;
 }
 async function runRootCommand(options) {
+    perfTrace.mark("root-command-start");
     if (process.env.ORACLE_FORCE_TUI === "1") {
+        const { launchTui } = await import("../src/cli/tui/index.js");
         await sessionStore.ensureStorage();
         await launchTui({ version: VERSION, printIntro: false });
         return;
@@ -729,17 +944,14 @@ async function runRootCommand(options) {
     const userConfig = (await loadUserConfig()).config;
     const helpRequested = rawCliArgs.some((arg) => arg === "--help" || arg === "-h");
     const multiModelProvided = Array.isArray(options.models) && options.models.length > 0;
-    if (multiModelProvided) {
-        const modelFromConfigOrCli = normalizeModelOption(options.model ?? userConfig.model ?? "");
-        if (modelFromConfigOrCli) {
-            throw new Error("--models cannot be combined with --model.");
-        }
-    }
     const optionUsesDefault = (name) => {
         // Commander reports undefined for untouched options, so treat undefined/default the same
         const source = program.getOptionValueSource?.(name);
         return source == null || source === "default";
     };
+    if (multiModelProvided && !optionUsesDefault("model") && normalizeModelOption(options.model)) {
+        throw new Error("--models cannot be combined with --model.");
+    }
     if (helpRequested) {
         if (options.verbose) {
             console.log("");
@@ -787,31 +999,19 @@ async function runRootCommand(options) {
     if (remoteHost) {
         console.log(chalk.dim(`Remote browser host detected: ${remoteHost}`));
     }
-    if (userCliArgs.length === 0) {
+    if (routingCliArgs.length === 0) {
         console.log(chalk.yellow("No prompt or subcommand supplied. Run `oracle --help` or `oracle tui` for the TUI."));
         program.outputHelp();
         return;
     }
-    const retentionHours = typeof options.retainHours === "number" ? options.retainHours : undefined;
-    await sessionStore.ensureStorage();
-    await pruneOldSessions(retentionHours, (message) => console.log(chalk.dim(message)));
     if (options.debugHelp) {
         printDebugHelp(program.name());
         return;
     }
-    if (options.dryRun && options.renderMarkdown) {
+    if (options.dryRun && renderMarkdown) {
         throw new Error("--dry-run cannot be combined with --render-markdown.");
     }
-    const preferredEngine = options.engine ?? userConfig.engine;
-    let engine = resolveEngine({
-        engine: preferredEngine,
-        browserFlag: options.browser,
-        env: process.env,
-    });
-    if (options.browser) {
-        console.log(chalk.yellow("`--browser` is deprecated; use `--engine browser` instead."));
-    }
-    if (optionUsesDefault("model") && userConfig.model) {
+    if (!multiModelProvided && optionUsesDefault("model") && userConfig.model) {
         options.model = userConfig.model;
     }
     if (optionUsesDefault("search") && userConfig.search) {
@@ -826,6 +1026,95 @@ async function runRootCommand(options) {
     if (optionUsesDefault("baseUrl") && userConfig.apiBaseUrl) {
         options.baseUrl = userConfig.apiBaseUrl;
     }
+    const providerMode = resolveApiProviderMode(options);
+    const engineModels = multiModelProvided
+        ? Array.from(new Set(options.models.map((entry) => resolveApiModel(entry))))
+        : [resolveApiModel(normalizeModelOption(options.model) || DEFAULT_MODEL)];
+    if (options.route || options.preflight) {
+        const routeAzureEndpoint = firstNonEmpty(options.azureEndpoint, process.env.AZURE_OPENAI_ENDPOINT, userConfig.azure?.endpoint);
+        const configuredAzureForRoute = routeAzureEndpoint
+            ? {
+                endpoint: routeAzureEndpoint,
+                deployment: firstNonEmpty(options.azureDeployment, process.env.AZURE_OPENAI_DEPLOYMENT, userConfig.azure?.deployment),
+                apiVersion: firstNonEmpty(options.azureApiVersion, process.env.AZURE_OPENAI_API_VERSION, userConfig.azure?.apiVersion),
+            }
+            : undefined;
+        const { buildProviderRoutePlan } = await import("../src/oracle/providerRoutePlan.js");
+        const plans = engineModels.map((model) => buildProviderRoutePlan({
+            model,
+            providerMode,
+            azure: configuredAzureForRoute,
+            baseUrl: options.baseUrl,
+            env: process.env,
+        }));
+        const { printProviderPlans } = await import("../src/cli/providerDoctor.js");
+        printProviderPlans(plans, { title: options.preflight ? "Provider preflight" : "Route plan" });
+        process.exitCode = plans.some((plan) => !plan.ok) ? 1 : 0;
+        return;
+    }
+    const retentionHours = typeof options.retainHours === "number" ? options.retainHours : undefined;
+    await sessionStore.ensureStorage();
+    await pruneOldSessions(retentionHours, (message) => console.log(chalk.dim(message)));
+    if (providerMode === "openai") {
+        if (hasExplicitAzureOption(optionUsesDefault)) {
+            throw new Error("--provider openai/--no-azure cannot be combined with Azure options.");
+        }
+        options.azureEndpoint = undefined;
+        options.azureDeployment = undefined;
+        options.azureApiVersion = undefined;
+    }
+    else {
+        if (optionUsesDefault("azureEndpoint")) {
+            if (process.env.AZURE_OPENAI_ENDPOINT) {
+                options.azureEndpoint = process.env.AZURE_OPENAI_ENDPOINT;
+            }
+            else if (userConfig.azure?.endpoint) {
+                options.azureEndpoint = userConfig.azure.endpoint;
+            }
+        }
+        if (optionUsesDefault("azureDeployment")) {
+            if (process.env.AZURE_OPENAI_DEPLOYMENT) {
+                options.azureDeployment = process.env.AZURE_OPENAI_DEPLOYMENT;
+            }
+            else if (userConfig.azure?.deployment) {
+                options.azureDeployment = userConfig.azure.deployment;
+            }
+        }
+        if (optionUsesDefault("azureApiVersion")) {
+            if (process.env.AZURE_OPENAI_API_VERSION) {
+                options.azureApiVersion = process.env.AZURE_OPENAI_API_VERSION;
+            }
+            else if (userConfig.azure?.apiVersion) {
+                options.azureApiVersion = userConfig.azure.apiVersion;
+            }
+        }
+        if (providerMode === "azure" && !options.azureEndpoint?.trim()) {
+            throw new Error("--provider azure requires --azure-endpoint or AZURE_OPENAI_ENDPOINT.");
+        }
+    }
+    const azureAutoApiRequested = providerMode !== "openai" &&
+        Boolean(options.azureEndpoint?.trim()) &&
+        engineModels.some((model) => isAzureOpenAICandidateModel(model));
+    const explicitApiProviderRequested = providerMode !== "auto" || hasExplicitAzureOption(optionUsesDefault);
+    const preferredEngine = options.engine ?? (explicitApiProviderRequested ? undefined : userConfig.engine);
+    let engine = resolveEngine({
+        engine: preferredEngine,
+        browserFlag: options.browser,
+        apiProviderRequested: explicitApiProviderRequested,
+        env: process.env,
+    });
+    const envEnginePreference = (process.env.ORACLE_ENGINE ?? "").trim().toLowerCase();
+    const browserEngineRequested = options.browser ||
+        options.engine === "browser" ||
+        Boolean(remoteHost) ||
+        (!explicitApiProviderRequested &&
+            (userConfig.engine === "browser" || envEnginePreference === "browser"));
+    if (azureAutoApiRequested && engine === "browser" && !browserEngineRequested) {
+        engine = "api";
+    }
+    if (options.browser) {
+        console.log(chalk.yellow("`--browser` is deprecated; use `--engine browser` instead."));
+    }
     if (remoteHost && engine !== "browser") {
         throw new Error("--remote-host requires --engine browser.");
     }
@@ -835,30 +1124,6 @@ async function runRootCommand(options) {
     if (options.browserTab && engine !== "browser") {
         throw new Error("--browser-tab requires --engine browser.");
     }
-    if (optionUsesDefault("azureEndpoint")) {
-        if (process.env.AZURE_OPENAI_ENDPOINT) {
-            options.azureEndpoint = process.env.AZURE_OPENAI_ENDPOINT;
-        }
-        else if (userConfig.azure?.endpoint) {
-            options.azureEndpoint = userConfig.azure.endpoint;
-        }
-    }
-    if (optionUsesDefault("azureDeployment")) {
-        if (process.env.AZURE_OPENAI_DEPLOYMENT) {
-            options.azureDeployment = process.env.AZURE_OPENAI_DEPLOYMENT;
-        }
-        else if (userConfig.azure?.deployment) {
-            options.azureDeployment = userConfig.azure.deployment;
-        }
-    }
-    if (optionUsesDefault("azureApiVersion")) {
-        if (process.env.AZURE_OPENAI_API_VERSION) {
-            options.azureApiVersion = process.env.AZURE_OPENAI_API_VERSION;
-        }
-        else if (userConfig.azure?.apiVersion) {
-            options.azureApiVersion = userConfig.azure.apiVersion;
-        }
-    }
     const normalizedMultiModels = multiModelProvided
         ? Array.from(new Set(options.models.map((entry) => resolveApiModel(entry))))
         : [];
@@ -873,14 +1138,17 @@ async function runRootCommand(options) {
     const isCodex = primaryModelCandidate.startsWith("gpt-5.1-codex");
     const isClaude = primaryModelCandidate.startsWith("claude");
     const userForcedBrowser = options.browser || options.engine === "browser";
+    const browserExplicitlyRequested = browserEngineRequested;
     const isBrowserCompatible = (model) => model.startsWith("gpt-") || model.startsWith("gemini");
-    const hasNonBrowserCompatibleTarget = (engine === "browser" || userForcedBrowser) &&
-        (normalizedMultiModels.length > 0
-            ? normalizedMultiModels.some((model) => !isBrowserCompatible(model))
-            : !isBrowserCompatible(resolvedModelCandidate));
-    if (hasNonBrowserCompatibleTarget) {
+    const hasNonBrowserCompatibleTarget = normalizedMultiModels.length > 0
+        ? normalizedMultiModels.some((model) => !isBrowserCompatible(model))
+        : !isBrowserCompatible(resolvedModelCandidate);
+    if (browserExplicitlyRequested && hasNonBrowserCompatibleTarget) {
         throw new Error("Browser engine only supports GPT and Gemini models. Re-run with --engine api for Grok, Claude, or other models.");
     }
+    if (engine === "browser" && hasNonBrowserCompatibleTarget) {
+        engine = "api";
+    }
     if (isClaude && engine === "browser") {
         console.log(chalk.dim("Browser engine is not supported for Claude models; switching to API."));
         engine = "api";
@@ -916,12 +1184,14 @@ async function runRootCommand(options) {
     const resolvedBaseUrl = normalizeBaseUrl(options.baseUrl ?? (isClaude ? process.env.ANTHROPIC_BASE_URL : process.env.OPENAI_BASE_URL));
     const { models: _rawModels, ...optionsWithoutModels } = options;
     const resolvedOptions = { ...optionsWithoutModels, model: resolvedModel };
-    resolvedOptions.maxFileSizeBytes = resolveConfiguredMaxFileSizeBytes(userConfig, process.env);
+    resolvedOptions.maxFileSizeBytes =
+        options.maxFileSizeBytes ?? resolveConfiguredMaxFileSizeBytes(userConfig, process.env);
     if (normalizedMultiModels.length > 0) {
         resolvedOptions.models = normalizedMultiModels;
     }
     resolvedOptions.baseUrl = resolvedBaseUrl;
     resolvedOptions.effectiveModelId = effectiveModelId;
+    resolvedOptions.provider = providerMode;
     resolvedOptions.writeOutputPath = resolveOutputPath(options.writeOutput, process.cwd());
     // Decide whether to block until completion:
     // - explicit --wait / --no-wait wins
@@ -935,10 +1205,19 @@ async function runRootCommand(options) {
         console.log(chalk.dim("Remote browser runs require --wait; ignoring --no-wait."));
         waitPreference = true;
     }
-    if (await handleStatusFlag(options, { attachSession, showStatus })) {
+    if (options.status) {
+        const { attachSession, showStatus } = await import("../src/cli/sessionDisplay.js");
+        if (options.session) {
+            await attachSession(options.session);
+        }
+        else {
+            await showStatus({ hours: 24, includeAll: false, limit: 100, showExamples: true });
+        }
         return;
     }
-    if (await handleSessionAlias(options, { attachSession })) {
+    if (options.session) {
+        const { attachSession } = await import("../src/cli/sessionDisplay.js");
+        await attachSession(options.session);
         return;
     }
     if (options.execSession) {
@@ -953,6 +1232,8 @@ async function runRootCommand(options) {
         const modelConfig = isKnownModel(resolvedModel)
             ? MODEL_CONFIGS[resolvedModel]
             : MODEL_CONFIGS["gpt-5.1"];
+        const { buildRequestBody } = await import("../src/oracle/request.js");
+        const { estimateRequestTokens } = await import("../src/oracle/tokenEstimate.js");
         const requestBody = buildRequestBody({
             modelConfig,
             systemPrompt: bundle.systemPrompt,
@@ -988,16 +1269,19 @@ async function runRootCommand(options) {
         return;
     }
     const getSource = (key) => program.getOptionValueSource?.(key) ?? undefined;
+    const { applyBrowserDefaultsFromConfig } = await import("../src/cli/browserDefaults.js");
     applyBrowserDefaultsFromConfig(options, userConfig, getSource);
     const sessionMode = engine === "browser" ? "browser" : "api";
-    const browserModelLabelOverride = sessionMode === "browser" ? resolveBrowserModelLabel(cliModelArg, resolvedModel) : undefined;
-    const browserConfig = sessionMode === "browser"
-        ? await buildBrowserConfig({
+    const browserConfig = await (async () => {
+        if (sessionMode !== "browser")
+            return undefined;
+        const { buildBrowserConfig, resolveBrowserModelLabel } = await import("../src/cli/browserConfig.js");
+        return buildBrowserConfig({
             ...options,
             model: resolvedModel,
-            browserModelLabel: browserModelLabelOverride,
-        })
-        : undefined;
+            browserModelLabel: resolveBrowserModelLabel(cliModelArg, resolvedModel),
+        });
+    })();
     if (previewMode) {
         if (!options.prompt) {
             throw new Error("Prompt is required when using --dry-run/preview.");
@@ -1027,6 +1311,7 @@ async function runRootCommand(options) {
             baseUrl: resolvedBaseUrl,
         });
         if (engine === "browser") {
+            const { runBrowserPreview } = await import("../src/cli/dryRun.js");
             await runBrowserPreview({
                 runOptions,
                 cwd: process.cwd(),
@@ -1038,6 +1323,8 @@ async function runRootCommand(options) {
             return;
         }
         // API dry-run/preview path
+        validateApiProviderRoutingForCli(runOptions);
+        const { runDryRunSummary } = await import("../src/cli/dryRun.js");
         if (previewMode === "summary") {
             await runDryRunSummary({
                 engine,
@@ -1096,6 +1383,7 @@ async function runRootCommand(options) {
             ? options.file.filter((f) => !isMediaFile(f))
             : options.file;
         if (filesToValidate.length > 0) {
+            const { readFiles } = await import("../src/oracle/files.js");
             await readFiles(filesToValidate, {
                 cwd: process.cwd(),
                 maxFileSizeBytes: resolvedOptions.maxFileSizeBytes,
@@ -1110,12 +1398,14 @@ async function runRootCommand(options) {
     });
     let browserDeps;
     if (browserConfig && remoteHost) {
+        const { createRemoteBrowserExecutor } = await import("../src/remote/client.js");
         browserDeps = {
             executeBrowser: createRemoteBrowserExecutor({ host: remoteHost, token: remoteToken }),
         };
         console.log(chalk.dim(`Routing browser automation to remote host ${remoteHost}`));
     }
     else if (browserConfig && resolvedModel.startsWith("gemini")) {
+        const { createGeminiWebExecutor } = await import("../src/gemini-web/index.js");
         browserDeps = {
             executeBrowser: createGeminiWebExecutor({
                 youtube: options.youtube,
@@ -1138,6 +1428,7 @@ async function runRootCommand(options) {
             previewMode: undefined,
             baseUrl: resolvedBaseUrl,
         });
+        const { runDryRunSummary } = await import("../src/cli/dryRun.js");
         await runDryRunSummary({
             engine,
             runOptions: baseRunOptions,
@@ -1155,6 +1446,9 @@ async function runRootCommand(options) {
         background: resolvedOptions.background ?? userConfig.background,
         baseUrl: resolvedBaseUrl,
     });
+    if (sessionMode === "api") {
+        validateApiProviderRoutingForCli(baseRunOptions);
+    }
     enforceBrowserSearchFlag(baseRunOptions, sessionMode, console.log);
     if (sessionMode === "browser" && baseRunOptions.search === false) {
         console.log(chalk.dim("Note: search is not available in browser engine; ignoring search=false."));
@@ -1195,22 +1489,32 @@ async function runRootCommand(options) {
             console.log(chalk.yellow(`Unable to detach session runner (${message}). Running inline...`));
             return false;
         });
+    const lifecycle = buildSessionLifecycle({
+        engine,
+        detached,
+        reattachCommand: `oracle session ${sessionMeta.id}`,
+    });
+    await sessionStore.updateSession(sessionMeta.id, { lifecycle });
+    const sessionWithLifecycle = { ...sessionMeta, lifecycle };
     if (!waitPreference) {
         if (!detached) {
             console.log(chalk.red("Unable to start in background; use --wait to run inline."));
             process.exitCode = 1;
             return;
         }
-        console.log(chalk.blue(`Session running in background. Reattach via: oracle session ${sessionMeta.id}`));
+        for (const line of formatSessionLifecycleBlock(sessionWithLifecycle)) {
+            console.log(line);
+        }
         console.log(chalk.dim("Pro runs can take up to 60 minutes (usually 10-15). Add --wait to stay attached."));
         return;
     }
     if (detached === false) {
-        await runInteractiveSession(sessionMeta, liveRunOptions, sessionMode, browserConfig, false, notifications, userConfig, true, browserDeps);
+        await runInteractiveSession(sessionWithLifecycle, liveRunOptions, sessionMode, browserConfig, false, notifications, userConfig, true, browserDeps);
         return;
     }
     if (detached) {
         console.log(chalk.blue(`Reattach via: oracle session ${sessionMeta.id}`));
+        const { attachSession } = await import("../src/cli/sessionDisplay.js");
         await attachSession(sessionMeta.id, { suppressMetadata: true });
     }
 }
@@ -1237,7 +1541,12 @@ async function runInteractiveSession(sessionMeta, runOptions, mode, browserConfi
         writeChunk(chunk);
         return true;
     };
+    for (const line of formatSessionLifecycleBlock(sessionMeta)) {
+        console.log(line);
+        logLine(line);
+    }
     try {
+        const { performSessionRun } = await import("../src/cli/sessionRunner.js");
         await performSessionRun({
             sessionMeta,
             runOptions,
@@ -1253,6 +1562,7 @@ async function runInteractiveSession(sessionMeta, runOptions, mode, browserConfi
         });
         const latest = await sessionStore.readSession(sessionMeta.id);
         if (!suppressSummary) {
+            const { formatCompletionSummary } = await import("../src/cli/sessionDisplay.js");
             const summary = latest ? formatCompletionSummary(latest, { includeSlug: true }) : null;
             if (summary) {
                 console.log("\n" + chalk.green.bold(summary));
@@ -1268,10 +1578,11 @@ async function launchDetachedSession(sessionId) {
     return new Promise((resolve, reject) => {
         try {
             const args = ["--", CLI_ENTRYPOINT, "--exec-session", sessionId];
+            const env = buildDetachedPerfTraceEnv(process.env, perfTraceArgs.value, sessionId);
             const child = spawn(process.execPath, args, {
                 detached: true,
                 stdio: "ignore",
-                env: process.env,
+                env,
             });
             child.once("error", reject);
             child.once("spawn", () => {
@@ -1314,6 +1625,7 @@ async function restartSession(sessionId, options) {
             ? runOptions.file.filter((f) => !isMediaFile(f))
             : runOptions.file;
         if (filesToValidate.length > 0) {
+            const { readFiles } = await import("../src/oracle/files.js");
             await readFiles(filesToValidate, {
                 cwd,
                 maxFileSizeBytes: runOptions.maxFileSizeBytes,
@@ -1347,12 +1659,14 @@ async function restartSession(sessionId, options) {
     }
     let browserDeps;
     if (browserConfig && remoteHost) {
+        const { createRemoteBrowserExecutor } = await import("../src/remote/client.js");
         browserDeps = {
             executeBrowser: createRemoteBrowserExecutor({ host: remoteHost, token: remoteToken }),
         };
         console.log(chalk.dim(`Routing browser automation to remote host ${remoteHost}`));
     }
     else if (browserConfig && runOptions.model.startsWith("gemini")) {
+        const { createGeminiWebExecutor } = await import("../src/gemini-web/index.js");
         browserDeps = {
             executeBrowser: createGeminiWebExecutor({
                 youtube: storedOptions.youtube,
@@ -1369,6 +1683,9 @@ async function restartSession(sessionId, options) {
         }
     }
     const remoteExecutionActive = Boolean(browserDeps);
+    if (sessionMode === "api") {
+        validateApiProviderRoutingForCli(runOptions);
+    }
     await sessionStore.ensureStorage();
     const notifications = deriveNotificationSettingsFromMetadata(metadata, process.env, userConfig.notify);
     const sessionMeta = await sessionStore.createSession({
@@ -1406,22 +1723,32 @@ async function restartSession(sessionId, options) {
             console.log(chalk.yellow(`Unable to detach session runner (${message}). Running inline...`));
             return false;
         });
+    const lifecycle = buildSessionLifecycle({
+        engine,
+        detached,
+        reattachCommand: `oracle session ${sessionMeta.id}`,
+    });
+    await sessionStore.updateSession(sessionMeta.id, { lifecycle });
+    const sessionWithLifecycle = { ...sessionMeta, lifecycle };
     if (!waitPreference) {
         if (!detached) {
             console.log(chalk.red("Unable to start in background; use --wait to run inline."));
             process.exitCode = 1;
             return;
         }
-        console.log(chalk.blue(`Session running in background. Reattach via: oracle session ${sessionMeta.id}`));
+        for (const line of formatSessionLifecycleBlock(sessionWithLifecycle)) {
+            console.log(line);
+        }
         console.log(chalk.dim("Pro runs can take up to 60 minutes (usually 10-15). Add --wait to stay attached."));
         return;
     }
     if (detached === false) {
-        await runInteractiveSession(sessionMeta, liveRunOptions, sessionMode, browserConfig, false, notifications, userConfig, true, browserDeps, cwd);
+        await runInteractiveSession(sessionWithLifecycle, liveRunOptions, sessionMode, browserConfig, false, notifications, userConfig, true, browserDeps, cwd);
         return;
     }
     if (detached) {
         console.log(chalk.blue(`Reattach via: oracle session ${sessionMeta.id}`));
+        const { attachSession } = await import("../src/cli/sessionDisplay.js");
         await attachSession(sessionMeta.id, { suppressMetadata: true });
     }
 }
@@ -1439,6 +1766,7 @@ async function executeSession(sessionId) {
     const userConfig = (await loadUserConfig()).config;
     const notifications = deriveNotificationSettingsFromMetadata(metadata, process.env, userConfig.notify);
     try {
+        const { performSessionRun } = await import("../src/cli/sessionRunner.js");
         await performSessionRun({
             sessionMeta: metadata,
             runOptions,
@@ -1553,12 +1881,26 @@ program.action(async function () {
     await runRootCommand(options);
 });
 async function main() {
-    const parsePromise = program.parseAsync(normalizedArgv);
-    const sigintPromise = once(process, "SIGINT").then(() => "sigint");
-    const result = await Promise.race([parsePromise.then(() => "parsed"), sigintPromise]);
-    if (result === "sigint") {
+    if (perfTraceArgs.error) {
+        console.error(`error: ${perfTraceArgs.error}`);
+        console.error("(use --help for usage)");
+        process.exitCode = 1;
+        return;
+    }
+    const handleSigint = () => {
         console.log(chalk.yellow("\nCancelled."));
         process.exitCode = 130;
+        // Browser/serve modes install their own SIGINT cleanup after this top-level handler.
+        if (process.listenerCount("SIGINT") <= 1) {
+            process.exit(130);
+        }
+    };
+    process.once("SIGINT", handleSigint);
+    try {
+        await program.parseAsync(normalizedArgv);
+    }
+    finally {
+        process.off("SIGINT", handleSigint);
     }
 }
 void main().catch((error) => {