@steipete/oracle 0.17.2 → 0.17.3

package/dist/docs-site/quickstart.html

@@ -270,7 +270,7 @@ body:not(.home) .doc>h1:first-child{display:none}
 <p><code>--browser-manual-login</code> skips Keychain cookie copy (no permission popups) and reuses a persistent automation profile under <code>~/.oracle/browser/</code>.</p>
 <h3 id="render-and-copy"><a class="anchor" href="#render-and-copy" aria-label="Anchor link">#</a>Render and copy</h3>
 <pre class="shiki github-dark-dimmed" style="background-color:var(--code-bg);color:var(--code-fg)" tabindex="0"><code class="language-bash"><span class="line"><span style="color:#F69D50">oracle</span><span style="color:#6CB6FF"> --render</span><span style="color:#6CB6FF"> --copy</span><span style="color:#6CB6FF"> -p</span><span style="color:#96D0FF"> "Architecture review"</span><span style="color:#6CB6FF"> --file</span><span style="color:#96D0FF"> "src/**/*.ts"</span></span></code></pre>
-<p>The bundle is on your clipboard. Paste it into ChatGPT, Claude, Gemini, AI Studio, or wherever you want the answer. Generated text context includes stable <code>Lines:</code> ranges and <code>N |</code> prefixes for <code>path:line</code> citations. Direct browser file uploads and ZIP bundles keep the original file contents.</p>
+<p>The bundle is on your clipboard. Paste it into ChatGPT, Claude, Gemini, AI Studio, or wherever you want the answer.</p>
 <h2 id="3-preview-before-you-spend"><a class="anchor" href="#3-preview-before-you-spend" aria-label="Anchor link">#</a>3. Preview before you spend</h2>
 <pre class="shiki github-dark-dimmed" style="background-color:var(--code-bg);color:var(--code-fg)" tabindex="0"><code class="language-bash"><span class="line"><span style="color:#F69D50">oracle</span><span style="color:#6CB6FF"> --dry-run</span><span style="color:#96D0FF"> summary</span><span style="color:#6CB6FF"> --files-report</span><span style="color:#F47067"> \</span></span>
 <span class="line"><span style="color:#6CB6FF">  -p</span><span style="color:#96D0FF"> "Audit the storage layer for race conditions"</span><span style="color:#F47067"> \</span></span>

package/dist/docs-site/sessions.html

@@ -251,7 +251,7 @@ body:not(.home) .doc>h1:first-child{display:none}
 <span class="line"><span>├── prompt.md                # assembled bundle (what was sent)</span></span>
 <span class="line"><span>├── response.md              # the model's answer (when complete)</span></span>
 <span class="line"><span>├── log.jsonl                # per-event log</span></span>
-<span class="line"><span>└── artifacts/               # browser-only: transcript, generated images/files, deep-research-report.md</span></span></code></pre>
+<span class="line"><span>└── artifacts/               # browser-only: transcript, generated images, deep-research-report.md</span></span></code></pre>
 <p>Override the root with <code>ORACLE_HOME_DIR=/some/path</code>.</p>
 <h2 id="listing"><a class="anchor" href="#listing" aria-label="Anchor link">#</a>Listing</h2>
 <pre class="shiki github-dark-dimmed" style="background-color:var(--code-bg);color:var(--code-fg)" tabindex="0"><code class="language-bash"><span class="line"><span style="color:#F69D50">oracle</span><span style="color:#96D0FF"> status</span><span style="color:#768390">                  # last 20 sessions</span></span>
@@ -277,10 +277,9 @@ body:not(.home) .doc>h1:first-child{display:none}
 <span class="line"><span>Models: 3 parallel</span></span>
 <span class="line"><span>Detach: yes, polling</span></span>
 <span class="line"><span>Reattach: oracle session 20260515-name-panel</span></span></code></pre>
-<p><code>oracle status</code> uses compact mode labels such as <code>api/fg</code>, <code>api/bg</code>, <code>br/fg</code>, and <code>br/bg</code>; <code>oracle session &lt;id&gt;</code> shows the persisted execution state.</p>
-<p>To keep the original CLI attached until completion, pass <code>--wait</code>:</p>
+<p><code>oracle status</code> uses compact mode labels such as <code>api/fg</code>, <code>api/bg</code>, and <code>br/fg</code>; <code>oracle session &lt;id&gt;</code> shows the persisted execution state.</p>
+<p>To block in the original command, pass <code>--wait</code>:</p>
 <pre class="shiki github-dark-dimmed" style="background-color:var(--code-bg);color:var(--code-fg)" tabindex="0"><code class="language-bash"><span class="line"><span style="color:#F69D50">oracle</span><span style="color:#6CB6FF"> --wait</span><span style="color:#6CB6FF"> --model</span><span style="color:#96D0FF"> gpt-5.5-pro</span><span style="color:#6CB6FF"> -p</span><span style="color:#96D0FF"> "Long architecture review"</span><span style="color:#6CB6FF"> --file</span><span style="color:#96D0FF"> "src/**"</span></span></code></pre>
-<p>For API runs, <code>--wait</code> executes the request in the foreground. Local Pro browser runs use a detached worker even with <code>--wait</code>, while the original CLI stays attached to the session log. This lets the browser worker capture and save the answer if the foreground CLI exits unexpectedly. Pressing Ctrl-C still cancels the worker and exits with code 130.</p>
 <p>For browser runs, ChatGPT sometimes redirects mid-page-load. The auto-reattach flags poll the existing tab without manual intervention:</p>
 <pre class="shiki github-dark-dimmed" style="background-color:var(--code-bg);color:var(--code-fg)" tabindex="0"><code class="language-bash"><span class="line"><span style="color:#F69D50">oracle</span><span style="color:#6CB6FF"> --engine</span><span style="color:#96D0FF"> browser</span><span style="color:#F47067"> \</span></span>
 <span class="line"><span style="color:#6CB6FF">  --browser-timeout</span><span style="color:#96D0FF"> 6m</span><span style="color:#F47067"> \</span></span>
@@ -293,10 +292,10 @@ body:not(.home) .doc>h1:first-child{display:none}
 <pre class="shiki github-dark-dimmed" style="background-color:var(--code-bg);color:var(--code-fg)" tabindex="0"><code class="language-bash"><span class="line"><span style="color:#F69D50">oracle</span><span style="color:#96D0FF"> restart</span><span style="color:#F47067"> &#x3C;</span><span style="color:#96D0FF">i</span><span style="color:#ADBAC7">d</span><span style="color:#F47067">></span><span style="color:#768390">            # re-run with the same prompt + files</span></span></code></pre>
 <p>Useful when a transient browser/API error truncated the answer. Restart copies the bundle, opens a new session, and links lineage back.</p>
 <h2 id="follow-up"><a class="anchor" href="#follow-up" aria-label="Anchor link">#</a>Follow up</h2>
-<p>Continue a saved ChatGPT browser conversation or an OpenAI / Azure Responses API session with new context:</p>
+<p>Continue an OpenAI / Azure Responses API session with new context:</p>
 <pre class="shiki github-dark-dimmed" style="background-color:var(--code-bg);color:var(--code-fg)" tabindex="0"><code class="language-bash"><span class="line"><span style="color:#F69D50">oracle</span><span style="color:#6CB6FF"> --followup</span><span style="color:#F47067"> &#x3C;</span><span style="color:#96D0FF">i</span><span style="color:#ADBAC7">d</span><span style="color:#F47067">></span><span style="color:#6CB6FF"> -p</span><span style="color:#96D0FF"> "Re-evaluate with these files"</span><span style="color:#F47067"> \</span></span>
 <span class="line"><span style="color:#6CB6FF">  --file</span><span style="color:#96D0FF"> "src/migrations/**"</span></span></code></pre>
-<p>Browser followup reopens the exact saved conversation and inherits its browser configuration and model. For multi-model API parents, pick the lineage with <code>--followup-model</code>. See <a href="followup.html">Followup</a> for the full flow and the formats <code>--followup</code> accepts (session ids, slugs, or <code>resp_…</code> response ids).</p>
+<p>For multi-model parents, pick the lineage with <code>--followup-model</code>. See <a href="followup.html">Followup</a> for the full flow and the formats <code>--followup</code> accepts (session ids, slugs, or <code>resp_…</code> response ids).</p>
 <h2 id="background-mode"><a class="anchor" href="#background-mode" aria-label="Anchor link">#</a>Background mode</h2>
 <p>Force a Responses API run into background mode (create + retrieve) regardless of model defaults:</p>
 <pre class="shiki github-dark-dimmed" style="background-color:var(--code-bg);color:var(--code-fg)" tabindex="0"><code class="language-bash"><span class="line"><span style="color:#F69D50">oracle</span><span style="color:#6CB6FF"> --background</span><span style="color:#6CB6FF"> --model</span><span style="color:#96D0FF"> gpt-5.5-pro</span><span style="color:#6CB6FF"> -p</span><span style="color:#96D0FF"> "..."</span><span style="color:#6CB6FF"> --file</span><span style="color:#96D0FF"> "src/**"</span></span>

package/dist/docs-site/spec.html

@@ -275,7 +275,7 @@ body:not(.home) .doc>h1:first-child{display:none}
 <p>Auto-pick rules:</p>
 <ol>
 <li>If <code>--engine</code> is set, use it.</li>
-<li>Else if <code>engine</code> is set in the effective config, use it. The effective config starts with <code>~/.oracle/config.json</code>, then layers project <code>.oracle/config.json</code> files from parent folders to the current directory.</li>
+<li>Else if <code>engine</code> is set in <code>~/.oracle/config.json</code>, use it.</li>
 <li>Else if <code>OPENAI_API_KEY</code> (or another supported API key) is set, use API.</li>
 <li>Else use browser.</li>
 </ol>

package/dist/docs-site/windows-work.html

@@ -249,10 +249,9 @@ body:not(.home) .doc>h1:first-child{display:none}
 <ul>
 <li>Browser engine now allowed on Windows; expect more flakiness. If automation fails, rerun with <code>--engine api --wait</code> or point <code>--remote-chrome</code> to a running Chrome with remote debugging.</li>
 <li>Chrome DevTools via mcporter: <code>chrome-devtools</code> server needs <code>CHROME_DEVTOOLS_URL</code> from a live session; without it <code>mcporter call chrome-devtools.*</code> fails. Expect this to be unset on Windows unless you bring your own Chrome session/URL.</li>
-<li>The agent-scripts <code>runner</code> helper can fail under PowerShell/CMD because of CRLF and bash expectations. If it explodes, run commands directly (<code>pnpm ...</code>, <code>git add/commit</code>) instead.</li>
+<li>agent-scripts bash helpers: <code>runner</code>/<code>scripts/committer</code> can fail under PowerShell/CMD because of CRLF and bash expectations. If they explode, run commands directly (<code>pnpm ...</code>, <code>git add/commit</code>) instead.</li>
 <li>browser-tools binary: not built in <code>agent-scripts/bin</code> on Windows; <code>pnpm tsx scripts/browser-tools.ts</code> also fails there (no package manifest). Use a macOS-built binary or run from macOS if you need it.</li>
 <li>Prefer PowerShell + pnpm directly; watch for CRLF warnings when touching tracked files.</li>
-<li>WSL browser launch host detection: a systemd-resolved stub such as <code>nameserver 127.0.0.53</code> is guest loopback, not the Windows host. Keep resolver-derived non-loopback hosts for Windows Chrome compatibility, but route resolver-derived <code>127/8</code> values to the standard local Chrome launcher.</li>
 </ul>
 <p>Future Windows gotchas belong here. Update this doc when you learn something new.</p>
 <ul>

package/dist/docs-site/windows.html

@@ -252,7 +252,7 @@ body:not(.home) .doc>h1:first-child{display:none}
 <li>Manual login flow: run with <code>--browser-manual-login</code> and sign into chatgpt.com in the opened Chrome; Oracle waits until the session is active. For initial login/setup or debugging, add <code>--browser-keep-browser</code> to keep the window open after the run; otherwise Oracle closes Chrome but preserves the profile at <code>~/.oracle/browser-profile</code> (override with <code>ORACLE_BROWSER_PROFILE_DIR</code> or <code>browser.manualLoginProfileDir</code> in <code>~/.oracle/config.json</code>). If that automation Chrome is already running with remote debugging enabled (DevToolsActivePort present), reuse it instead of relaunching by pointing Oracle at it via <code>--remote-chrome &lt;host:port&gt;</code>.</li>
 <li>Cookie paths: preferred path is <code>%LOCALAPPDATA%\\Google\\Chrome\\User Data\\&lt;Profile&gt;\\Network\\Cookies</code>. If that errors, try the top-level <code>Cookies</code> file or supply the exact path via <code>--browser-cookie-path</code>.</li>
 <li>mcporter chrome-devtools: requires a valid <code>CHROME_DEVTOOLS_URL</code> from a live session; otherwise calls will fail.</li>
-<li>The agent-scripts <code>runner</code> helper is bash-based and may fail under PowerShell/CMD; run commands directly if it misbehaves.</li>
+<li>agent-scripts helpers (<code>runner</code>, <code>scripts/committer</code>) are bash-based and may fail under PowerShell/CMD; run commands directly if they misbehave.</li>
 </ul><nav class="page-nav" aria-label="Pager"><a class="page-nav-prev" href="linux.html"><small>Previous</small><span>Linux Notes</span></a><a class="page-nav-next" href="windows-work.html"><small>Next</small><span>Windows Work</span></a></nav></article>
         
       </div>

package/dist/markdansi/types/index.js

@@ -0,0 +1,4 @@
+// Public API typings for Markdansi.
+// Hand-authored source for `pnpm types` (tsc --emitDeclarationOnly)
+// to produce dist/index.d.ts. Keep in sync with src/ changes.
+export {};

package/dist/oracle/bin/oracle-cli.js

@@ -0,0 +1,472 @@
+#!/usr/bin/env node
+import 'dotenv/config';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { Command, Option } from 'commander';
+import { resolveEngine } from '../src/cli/engine.js';
+import { shouldRequirePrompt } from '../src/cli/promptRequirement.js';
+import chalk from 'chalk';
+import { ensureSessionStorage, initializeSession, readSessionMetadata, createSessionLogWriter, deleteSessionsOlderThan, } from '../src/sessionManager.js';
+import { runOracle, renderPromptMarkdown, readFiles } from '../src/oracle.js';
+import { CHATGPT_URL } from '../src/browserMode.js';
+import { applyHelpStyling } from '../src/cli/help.js';
+import { collectPaths, parseFloatOption, parseIntOption, parseSearchOption, usesDefaultStatusFilters, resolvePreviewMode, normalizeModelOption, resolveApiModel, inferModelFromLabel, parseHeartbeatOption, } from '../src/cli/options.js';
+import { buildBrowserConfig, resolveBrowserModelLabel } from '../src/cli/browserConfig.js';
+import { performSessionRun } from '../src/cli/sessionRunner.js';
+import { attachSession, showStatus } from '../src/cli/sessionDisplay.js';
+import { handleSessionCommand, formatSessionCleanupMessage } from '../src/cli/sessionCommand.js';
+import { isErrorLogged } from '../src/cli/errorUtils.js';
+import { handleSessionAlias, handleStatusFlag } from '../src/cli/rootAlias.js';
+import { getCliVersion } from '../src/version.js';
+import { runDryRunSummary } from '../src/cli/dryRun.js';
+const VERSION = getCliVersion();
+const CLI_ENTRYPOINT = fileURLToPath(import.meta.url);
+const rawCliArgs = process.argv.slice(2);
+const isTty = process.stdout.isTTY;
+const program = new Command();
+applyHelpStyling(program, VERSION, isTty);
+program.hook('preAction', (thisCommand) => {
+    if (thisCommand !== program) {
+        return;
+    }
+    if (rawCliArgs.some((arg) => arg === '--help' || arg === '-h')) {
+        return;
+    }
+    const opts = thisCommand.optsWithGlobals();
+    const positional = thisCommand.args?.[0];
+    if (!opts.prompt && positional) {
+        opts.prompt = positional;
+        thisCommand.setOptionValue('prompt', positional);
+    }
+    if (shouldRequirePrompt(rawCliArgs, opts)) {
+        console.log(chalk.yellow('Prompt is required. Provide it via --prompt "<text>" or positional [prompt].'));
+        thisCommand.help({ error: false });
+        process.exitCode = 1;
+        return;
+    }
+});
+program
+    .name('oracle')
+    .description('One-shot GPT-5 Pro / GPT-5.1 tool for hard questions that benefit from large file context and server-side search.')
+    .version(VERSION)
+    .argument('[prompt]', 'Prompt text (shorthand for --prompt).')
+    .option('-p, --prompt <text>', 'User prompt to send to the model.')
+    .option('-f, --file <paths...>', 'Files/directories or glob patterns to attach (prefix with !pattern to exclude). Files larger than 1 MB are rejected automatically.', collectPaths, [])
+    .option('-s, --slug <words>', 'Custom session slug (3-5 words).')
+    .option('-m, --model <model>', 'Model to target (gpt-5-pro | gpt-5.1, or ChatGPT labels like "5.1 Instant" for browser runs).', normalizeModelOption, 'gpt-5-pro')
+    .addOption(new Option('-e, --engine <mode>', 'Execution engine (api | browser). If omitted, Oracle picks api when OPENAI_API_KEY is set, otherwise browser.').choices(['api', 'browser']))
+    .option('--files-report', 'Show token usage per attached file (also prints automatically when files exceed the token budget).', false)
+    .option('-v, --verbose', 'Enable verbose logging for all operations.', false)
+    .option('--dry-run', 'Validate inputs and show token estimates without calling the model.', false)
+    .addOption(new Option('--preview [mode]', 'Preview the request without calling the API (summary | json | full).')
+    .choices(['summary', 'json', 'full'])
+    .preset('summary'))
+    .addOption(new Option('--exec-session <id>').hideHelp())
+    .addOption(new Option('--session <id>').hideHelp())
+    .addOption(new Option('--status', 'Show stored sessions (alias for `oracle status`).').default(false).hideHelp())
+    .option('--render-markdown', 'Emit the assembled markdown bundle for prompt + files and exit.', false)
+    .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)
+    .hideHelp())
+    .addOption(new Option('--max-input <tokens>', 'Override the input token budget for the selected model.')
+    .argParser(parseIntOption)
+    .hideHelp())
+    .addOption(new Option('--max-output <tokens>', 'Override the max output tokens for the selected model.')
+    .argParser(parseIntOption)
+    .hideHelp())
+    .addOption(new Option('--browser', '(deprecated) Use --engine browser instead.').default(false).hideHelp())
+    .addOption(new Option('--browser-chrome-profile <name>', 'Chrome profile name/path for cookie reuse.').hideHelp())
+    .addOption(new Option('--browser-chrome-path <path>', 'Explicit Chrome or Chromium executable path.').hideHelp())
+    .addOption(new Option('--browser-url <url>', `Override the ChatGPT URL (default ${CHATGPT_URL}).`).hideHelp())
+    .addOption(new Option('--browser-timeout <ms|s|m>', 'Maximum time to wait for an answer (default 900s).').hideHelp())
+    .addOption(new Option('--browser-input-timeout <ms|s|m>', 'Maximum time to wait for the prompt textarea (default 30s).').hideHelp())
+    .addOption(new Option('--browser-no-cookie-sync', 'Skip copying cookies from Chrome.').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())
+    .addOption(new Option('--browser-allow-cookie-errors', 'Continue even if Chrome cookies cannot be copied.').hideHelp())
+    .addOption(new Option('--browser-inline-files', 'Paste files directly into the ChatGPT composer instead of uploading attachments.').default(false))
+    .option('--debug-help', 'Show the advanced/debug option set and exit.', false)
+    .option('--heartbeat <seconds>', 'Emit periodic in-progress updates (0 to disable).', parseHeartbeatOption, 30)
+    .showHelpAfterError('(use --help for usage)');
+program.addHelpText('after', `
+Examples:
+  # Quick API run with two files
+  oracle --prompt "Summarize the risk register" --file docs/risk-register.md docs/risk-matrix.md
+
+  # Browser run (no API key) + globbed TypeScript sources, excluding tests
+  oracle --engine browser --prompt "Review the TS data layer" \\
+    --file "src/**/*.ts" --file "!src/**/*.test.ts"
+`);
+const sessionCommand = program
+    .command('session [id]')
+    .description('Attach to a stored session or list recent sessions when no ID is provided.')
+    .option('--hours <hours>', 'Look back this many hours when listing sessions (default 24).', parseFloatOption, 24)
+    .option('--limit <count>', 'Maximum sessions to show when listing (max 1000).', parseIntOption, 100)
+    .option('--all', 'Include all stored sessions regardless of age.', false)
+    .option('--clear', 'Delete stored sessions older than the provided window (24h default).', false)
+    .option('--render', 'Render completed session output as markdown (rich TTY only).', false)
+    .option('--render-markdown', 'Alias for --render.', false)
+    .addOption(new Option('--clean', 'Deprecated alias for --clear.').default(false).hideHelp())
+    .action(async (sessionId, _options, cmd) => {
+    await handleSessionCommand(sessionId, cmd);
+});
+const statusCommand = program
+    .command('status [id]')
+    .description('List recent sessions (24h window by default) or attach to a session when an ID is provided.')
+    .option('--hours <hours>', 'Look back this many hours (default 24).', parseFloatOption, 24)
+    .option('--limit <count>', 'Maximum sessions to show (max 1000).', parseIntOption, 100)
+    .option('--all', 'Include all stored sessions regardless of age.', false)
+    .option('--clear', 'Delete stored sessions older than the provided window (24h default).', false)
+    .option('--render', 'Render completed session output as markdown (rich TTY only).', false)
+    .option('--render-markdown', 'Alias for --render.', false)
+    .addOption(new Option('--clean', 'Deprecated alias for --clear.').default(false).hideHelp())
+    .action(async (sessionId, _options, command) => {
+    const statusOptions = command.opts();
+    const clearRequested = Boolean(statusOptions.clear || statusOptions.clean);
+    if (clearRequested) {
+        if (sessionId) {
+            console.error('Cannot combine a session ID with --clear. Remove the ID to delete cached sessions.');
+            process.exitCode = 1;
+            return;
+        }
+        const hours = statusOptions.hours;
+        const includeAll = statusOptions.all;
+        const result = await deleteSessionsOlderThan({ hours, includeAll });
+        const scope = includeAll ? 'all stored sessions' : `sessions older than ${hours}h`;
+        console.log(formatSessionCleanupMessage(result, scope));
+        return;
+    }
+    if (sessionId === 'clear' || sessionId === 'clean') {
+        console.error('Session cleanup now uses --clear. Run "oracle status --clear --hours <n>" instead.');
+        process.exitCode = 1;
+        return;
+    }
+    if (sessionId) {
+        await attachSession(sessionId);
+        return;
+    }
+    const showExamples = usesDefaultStatusFilters(command);
+    await showStatus({
+        hours: statusOptions.all ? Infinity : statusOptions.hours,
+        includeAll: statusOptions.all,
+        limit: statusOptions.limit,
+        showExamples,
+    });
+});
+function buildRunOptions(options, overrides = {}) {
+    if (!options.prompt) {
+        throw new Error('Prompt is required.');
+    }
+    return {
+        prompt: options.prompt,
+        model: options.model,
+        file: overrides.file ?? options.file ?? [],
+        slug: overrides.slug ?? options.slug,
+        filesReport: overrides.filesReport ?? options.filesReport,
+        maxInput: overrides.maxInput ?? options.maxInput,
+        maxOutput: overrides.maxOutput ?? options.maxOutput,
+        system: overrides.system ?? options.system,
+        silent: overrides.silent ?? options.silent,
+        search: overrides.search ?? options.search,
+        preview: overrides.preview ?? undefined,
+        previewMode: overrides.previewMode ?? options.previewMode,
+        apiKey: overrides.apiKey ?? options.apiKey,
+        sessionId: overrides.sessionId ?? options.sessionId,
+        verbose: overrides.verbose ?? options.verbose,
+        heartbeatIntervalMs: overrides.heartbeatIntervalMs ?? resolveHeartbeatIntervalMs(options.heartbeat),
+        browserInlineFiles: overrides.browserInlineFiles ?? options.browserInlineFiles ?? false,
+        background: overrides.background ?? undefined,
+    };
+}
+function resolveHeartbeatIntervalMs(seconds) {
+    if (typeof seconds !== 'number' || seconds <= 0) {
+        return undefined;
+    }
+    return Math.round(seconds * 1000);
+}
+function buildRunOptionsFromMetadata(metadata) {
+    const stored = metadata.options ?? {};
+    return {
+        prompt: stored.prompt ?? '',
+        model: stored.model ?? 'gpt-5-pro',
+        file: stored.file ?? [],
+        slug: stored.slug,
+        filesReport: stored.filesReport,
+        maxInput: stored.maxInput,
+        maxOutput: stored.maxOutput,
+        system: stored.system,
+        silent: stored.silent,
+        search: undefined,
+        preview: false,
+        previewMode: undefined,
+        apiKey: undefined,
+        sessionId: metadata.id,
+        verbose: stored.verbose,
+        heartbeatIntervalMs: stored.heartbeatIntervalMs,
+        browserInlineFiles: stored.browserInlineFiles,
+        background: stored.background,
+    };
+}
+function getSessionMode(metadata) {
+    return metadata.mode ?? metadata.options?.mode ?? 'api';
+}
+function getBrowserConfigFromMetadata(metadata) {
+    return metadata.options?.browserConfig ?? metadata.browser?.config;
+}
+async function runRootCommand(options) {
+    const helpRequested = rawCliArgs.some((arg) => arg === '--help' || arg === '-h');
+    if (helpRequested) {
+        if (options.verbose) {
+            console.log('');
+            printDebugHelp(program.name());
+            console.log('');
+        }
+        program.help({ error: false });
+        return;
+    }
+    const previewMode = resolvePreviewMode(options.preview);
+    if (rawCliArgs.length === 0) {
+        console.log(chalk.yellow('No prompt or subcommand supplied. See `oracle --help` for usage.'));
+        program.help({ error: false });
+        return;
+    }
+    if (options.debugHelp) {
+        printDebugHelp(program.name());
+        return;
+    }
+    if (options.dryRun && previewMode) {
+        throw new Error('--dry-run cannot be combined with --preview.');
+    }
+    if (options.dryRun && options.renderMarkdown) {
+        throw new Error('--dry-run cannot be combined with --render-markdown.');
+    }
+    const engine = resolveEngine({ engine: options.engine, browserFlag: options.browser, env: process.env });
+    if (options.browser) {
+        console.log(chalk.yellow('`--browser` is deprecated; use `--engine browser` instead.'));
+    }
+    const cliModelArg = normalizeModelOption(options.model) || 'gpt-5-pro';
+    const resolvedModel = engine === 'browser' ? inferModelFromLabel(cliModelArg) : resolveApiModel(cliModelArg);
+    const resolvedOptions = { ...options, model: resolvedModel };
+    if (await handleStatusFlag(options, { attachSession, showStatus })) {
+        return;
+    }
+    if (await handleSessionAlias(options, { attachSession })) {
+        return;
+    }
+    if (options.execSession) {
+        await executeSession(options.execSession);
+        return;
+    }
+    if (options.renderMarkdown) {
+        if (!options.prompt) {
+            throw new Error('Prompt is required when using --render-markdown.');
+        }
+        const markdown = await renderPromptMarkdown({ prompt: options.prompt, file: options.file, system: options.system }, { cwd: process.cwd() });
+        console.log(markdown);
+        return;
+    }
+    if (previewMode) {
+        if (engine === 'browser') {
+            throw new Error('--engine browser cannot be combined with --preview.');
+        }
+        if (!options.prompt) {
+            throw new Error('Prompt is required when using --preview.');
+        }
+        const runOptions = buildRunOptions(resolvedOptions, { preview: true, previewMode });
+        await runOracle(runOptions, { log: console.log, write: (chunk) => process.stdout.write(chunk) });
+        return;
+    }
+    if (!options.prompt) {
+        throw new Error('Prompt is required when starting a new session.');
+    }
+    if (options.dryRun) {
+        const baseRunOptions = buildRunOptions(resolvedOptions, { preview: false, previewMode: undefined });
+        await runDryRunSummary({
+            engine,
+            runOptions: baseRunOptions,
+            cwd: process.cwd(),
+            version: VERSION,
+            log: console.log,
+        }, {});
+        return;
+    }
+    if (options.file && options.file.length > 0) {
+        await readFiles(options.file, { cwd: process.cwd() });
+    }
+    const sessionMode = engine === 'browser' ? 'browser' : 'api';
+    const browserModelLabelOverride = sessionMode === 'browser' ? resolveBrowserModelLabel(cliModelArg, resolvedModel) : undefined;
+    const browserConfig = sessionMode === 'browser'
+        ? buildBrowserConfig({
+            ...options,
+            model: resolvedModel,
+            browserModelLabel: browserModelLabelOverride,
+        })
+        : undefined;
+    await ensureSessionStorage();
+    const baseRunOptions = buildRunOptions(resolvedOptions, { preview: false, previewMode: undefined });
+    const sessionMeta = await initializeSession({
+        ...baseRunOptions,
+        mode: sessionMode,
+        browserConfig,
+    }, process.cwd());
+    const reattachCommand = `pnpm oracle session ${sessionMeta.id}`;
+    console.log(chalk.bold(`Reattach later with: ${chalk.cyan(reattachCommand)}`));
+    console.log('');
+    const liveRunOptions = { ...baseRunOptions, sessionId: sessionMeta.id };
+    const disableDetach = process.env.ORACLE_NO_DETACH === '1';
+    const detached = disableDetach
+        ? false
+        : await launchDetachedSession(sessionMeta.id).catch((error) => {
+            const message = error instanceof Error ? error.message : String(error);
+            console.log(chalk.yellow(`Unable to detach session runner (${message}). Running inline...`));
+            return false;
+        });
+    if (detached === false) {
+        await runInteractiveSession(sessionMeta, liveRunOptions, sessionMode, browserConfig, true);
+        console.log(chalk.bold(`Session ${sessionMeta.id} completed`));
+        return;
+    }
+    if (detached) {
+        console.log(chalk.blue(`Reattach via: oracle session ${sessionMeta.id}`));
+        await attachSession(sessionMeta.id, { suppressMetadata: true });
+        console.log(chalk.bold(`Session ${sessionMeta.id} completed`));
+    }
+}
+async function runInteractiveSession(sessionMeta, runOptions, mode, browserConfig, showReattachHint = true) {
+    const { logLine, writeChunk, stream } = createSessionLogWriter(sessionMeta.id);
+    let headerAugmented = false;
+    const combinedLog = (message = '') => {
+        if (!headerAugmented && message.startsWith('Oracle (')) {
+            headerAugmented = true;
+            if (showReattachHint) {
+                console.log(`${message}\n${chalk.blue(`Reattach via: oracle session ${sessionMeta.id}`)}`);
+            }
+            else {
+                console.log(message);
+            }
+            logLine(message);
+            return;
+        }
+        console.log(message);
+        logLine(message);
+    };
+    const combinedWrite = (chunk) => {
+        writeChunk(chunk);
+        return process.stdout.write(chunk);
+    };
+    try {
+        await performSessionRun({
+            sessionMeta,
+            runOptions,
+            mode,
+            browserConfig,
+            cwd: process.cwd(),
+            log: combinedLog,
+            write: combinedWrite,
+            version: VERSION,
+        });
+    }
+    catch (error) {
+        throw error;
+    }
+    finally {
+        stream.end();
+    }
+}
+async function launchDetachedSession(sessionId) {
+    return new Promise((resolve, reject) => {
+        try {
+            const args = ['--', CLI_ENTRYPOINT, '--exec-session', sessionId];
+            const child = spawn(process.execPath, args, {
+                detached: true,
+                stdio: 'ignore',
+                env: process.env,
+            });
+            child.once('error', reject);
+            child.once('spawn', () => {
+                child.unref();
+                resolve(true);
+            });
+        }
+        catch (error) {
+            reject(error);
+        }
+    });
+}
+async function executeSession(sessionId) {
+    const metadata = await readSessionMetadata(sessionId);
+    if (!metadata) {
+        console.error(chalk.red(`No session found with ID ${sessionId}`));
+        process.exitCode = 1;
+        return;
+    }
+    const runOptions = buildRunOptionsFromMetadata(metadata);
+    const sessionMode = getSessionMode(metadata);
+    const browserConfig = getBrowserConfigFromMetadata(metadata);
+    const { logLine, writeChunk, stream } = createSessionLogWriter(sessionId);
+    try {
+        await performSessionRun({
+            sessionMeta: metadata,
+            runOptions,
+            mode: sessionMode,
+            browserConfig,
+            cwd: metadata.cwd ?? process.cwd(),
+            log: logLine,
+            write: writeChunk,
+            version: VERSION,
+        });
+    }
+    catch {
+        // Errors are already logged to the session log; keep quiet to mirror stored-session behavior.
+    }
+    finally {
+        stream.end();
+    }
+}
+function printDebugHelp(cliName) {
+    console.log(chalk.bold('Advanced Options'));
+    printDebugOptionGroup([
+        ['--search <on|off>', 'Enable or disable the server-side search tool (default on).'],
+        ['--max-input <tokens>', 'Override the input token budget.'],
+        ['--max-output <tokens>', 'Override the max output tokens (model default otherwise).'],
+    ]);
+    console.log('');
+    console.log(chalk.bold('Browser Options'));
+    printDebugOptionGroup([
+        ['--browser-chrome-profile <name>', 'Reuse cookies from a specific Chrome profile.'],
+        ['--browser-chrome-path <path>', 'Point to a custom Chrome/Chromium binary.'],
+        ['--browser-url <url>', 'Hit an alternate ChatGPT host.'],
+        ['--browser-timeout <ms|s|m>', 'Cap total wait time for the assistant response.'],
+        ['--browser-input-timeout <ms|s|m>', 'Cap how long we wait for the composer textarea.'],
+        ['--browser-no-cookie-sync', 'Skip copying cookies from your main profile.'],
+        ['--browser-headless', 'Launch Chrome in headless mode.'],
+        ['--browser-hide-window', 'Hide the Chrome window (macOS headful only).'],
+        ['--browser-keep-browser', 'Leave Chrome running after completion.'],
+    ]);
+    console.log('');
+    console.log(chalk.dim(`Tip: run \`${cliName} --help\` to see the primary option set.`));
+}
+function printDebugOptionGroup(entries) {
+    const flagWidth = Math.max(...entries.map(([flag]) => flag.length));
+    entries.forEach(([flag, description]) => {
+        const label = chalk.cyan(flag.padEnd(flagWidth + 2));
+        console.log(`  ${label}${description}`);
+    });
+}
+program.action(async function () {
+    const options = this.optsWithGlobals();
+    await runRootCommand(options);
+});
+await program.parseAsync(process.argv).catch((error) => {
+    if (error instanceof Error) {
+        if (!isErrorLogged(error)) {
+            console.error(chalk.red('✖'), error.message);
+        }
+    }
+    else {
+        console.error(chalk.red('✖'), error);
+    }
+    process.exitCode = 1;
+});