pi-oracle 0.7.15 → 0.7.17

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 ## Unreleased
 
+## 0.7.17 - 2026-07-01
+
+### Changed
+- clarified oracle prompt/docs validation around provider upload ceilings, Node release-gate requirements, and follow-up dispatch rules
+- centralized provider normalization, project-trust probing, oracle jobs-dir defaults, and timestamp parsing in narrow source-of-truth modules
+
+### Fixed
+- made sanity-runner mode and real-smoke timeout validation fail through tested behavior paths instead of brittle source-string contracts
+- removed duplicate worker/auth helper logic for snapshot parsing, URL normalization, conversation ids, and login-probe normalization
+
+### Validation
+- ran the full `npm run verify:oracle` local gate before release
+
+## 0.7.16 - 2026-06-24
+
+### Changed
+- updated the local pi development and validation baseline to `@earendil-works/*` `0.80.2`
+- exposed packaged `/oracle` and `/oracle-followup` prompt templates through the package manifest so TUI slash completion can discover them
+- reduced always-on `oracle_submit` prompt metadata while keeping detailed dispatch rules in the prompt templates
+
+### Fixed
+- made `/oracle-*` command output visible in JSON mode through a displayed custom message instead of UI notifications only
+- deferred Chrome user-agent probing until oracle config is loaded, with a timeout on the Chrome version probe
+
 ## 0.7.15 - 2026-06-23
 
 ### Changed

package/README.md

@@ -2,7 +2,7 @@
 
 `pi-oracle` lets a `pi` agent send hard, long-running work to ChatGPT.com or Grok through the web app, with repo archives, background execution, saved results, and a best-effort wake-up back into `pi` when the answer is ready.
 
-> Status: experimental public beta. Validated on macOS, Linux, and Windows native with Chromium-family browsers and pi `0.80.1`. Pi `0.80.1+` is the suggested tested floor for project-trust-aware package/runtime validation, but pi-bundled runtime packages remain optional wildcard peers so npm peer ranges do not block users from trying newer pi releases. Normal oracle jobs run in an isolated browser profile, not your active browser window.
+> Status: experimental public beta. Current local validation baseline is pi `0.80.2`; the platform-smoke harness covers macOS, Linux, and Windows native with Chromium-family browsers. Pi `0.80.2+` is the suggested tested floor for project-trust-aware package/runtime validation, but pi-bundled runtime packages remain optional wildcard peers so npm peer ranges do not block users from trying newer pi releases. Normal oracle jobs run in an isolated browser profile, not your active browser window.
 
 ## What a successful run looks like
 
@@ -71,13 +71,15 @@ Or from GitHub:
 pi install https://github.com/fitchmultz/pi-oracle
 ```
 
+To update the package later, use `pi update --extensions`, `pi update --all`, or `pi update npm:pi-oracle`. Bare `pi update` updates pi itself only. Versioned npm/git refs stay pinned until you change the configured source.
+
 ### 2. Check requirements
 
 You need:
 
 - macOS, Linux, or Windows native
-- Node.js 22 or newer
-- Suggested tested floor: `pi` 0.80.1 or newer; older pi versions are not blocked by package metadata but are outside the current validation baseline
+- Node.js 22.19.0 or newer for package install/use; platform smoke/release validation currently expects Node 24+ per `platform-smoke.config.mjs`
+- Suggested tested floor: `pi` 0.80.2 or newer; older pi versions are not blocked by package metadata but are outside the current validation baseline
 - Google Chrome/Chromium or another Chromium-family browser
 - ChatGPT or Grok already signed in to the configured local browser profile for the provider you plan to use
 - `agent-browser` and `tar` available on the machine; `zstd` is also required when submitting ChatGPT `.tar.zst` archives
@@ -389,7 +391,8 @@ Use the narrowest validation workflow that proves the change:
 | Situation | Command(s) |
 | --- | --- |
 | Everyday local iteration | `npm run verify:oracle` |
-| Platform-sensitive changes | `npm run smoke:platform:doctor`, then a focused `node scripts/platform-smoke.mjs run --target <target> --suite <suite>` |
+| Platform-focused syntax/invariant sanity | `npm run check:platform-smoke`, `npm run sanity:oracle:platform` |
+| Platform-sensitive runtime changes | `npm run smoke:platform:doctor`, then a focused `node scripts/platform-smoke.mjs run --target <target> --suite <suite>` |
 | Platform matrix proof | `npm run smoke:platform:all` |
 | ChatGPT preset release proof | `npm run release:proof:chatgpt-presets` |
 | Publish/release gate | `npm run release:check` |

package/docs/ORACLE_DESIGN.md

@@ -7,7 +7,7 @@ Companion doc:
 - `docs/ORACLE_RECOVERY_DRILL.md` — safe expired-auth recovery validation drill
 
 Compatibility target:
-- `pi` 0.80.1+ is the suggested tested floor for current project-trust-aware package/runtime validation
+- `pi` 0.80.2+ is the suggested tested floor for current project-trust-aware package/runtime validation
 - package metadata keeps pi runtime packages as optional wildcard peers, so this suggested floor is not enforced as a hard npm install requirement
 - current extension lifecycle only; no backward-compatibility shims for removed `session_switch` / `session_fork` events
 
@@ -115,7 +115,7 @@ It instructs the agent to:
 2. stop right away if preflight reports the session or local oracle setup is not ready
 3. understand whether the request is explicitly narrow or genuinely broad
 4. if auth is missing, stale, or the worker explicitly said to rerun `/oracle-auth`, stop and tell the user to run `/oracle-auth` rather than launching auth automatically
-5. gather enough repo context to submit well and bias toward context-rich archives when they fit within the provider ceiling: 250 MB for ChatGPT and 200 MiB for Grok
+5. gather enough repo context to submit well and bias toward context-rich archives when they fit within the provider ceiling: 250 MiB for ChatGPT and 200 MiB for Grok
 6. if the request is narrow, start from the directly relevant area but still include nearby tests, docs, config, and adjacent modules when they may improve answer quality
 7. if the request is broad/repo-wide, gather broader context and usually archive `.`
 8. if `oracle_submit` fails before dispatch with an `archive_too_large` / upload-limit error, treat that as retryable: use the reported size summary plus any auto-pruned paths to cut scope and retry automatically with a smaller archive
@@ -639,6 +639,9 @@ Remaining non-blocking hardening work:
 - keep hardening model-selection verification against future ChatGPT UI variation
 
 Recent proof points:
+- Pi 0.80.2 local gate: `npm run verify:oracle` passed on 2026-06-24 after the JSON command output, prompt-manifest, schema, and lazy Chrome-probe audit fixes
+- Pi 0.80.2 isolated extension smokes: `.artifacts/real-smoke/run-1782321054924-jnq0x3` passed source proof, and `.artifacts/real-smoke/run-1782321056224-yuq5a2` passed packed-install proof
+- Pi 0.80.2 JSON command smoke: `pi --no-extensions -e ./extensions/oracle/index.ts --mode json --no-session --no-approve "/oracle-status"` emitted displayed `oracle-command-output` JSON events
 - Pi 0.79.10 local gate: `npm run verify:oracle` passed on 2026-06-22 after the 0.79.10 baseline refresh and `CONFIG_DIR_NAME` cleanup
 - Pi 0.79.10 isolated extension smokes: `.artifacts/real-smoke/run-1782137209549-0xe67z` passed packed-install proof, and `.artifacts/real-smoke/run-1782137217821-95a1po` passed source model-agent proof
 - Pi 0.79.10 platform artifacts: `.artifacts/platform-smoke/run-1782137574391-7lay68` (macOS platform-build), `.artifacts/platform-smoke/run-1782137619352-gku7jz` (macOS real-extension), `.artifacts/platform-smoke/run-1782137587082-d7kg4p` (Ubuntu platform-build), `.artifacts/platform-smoke/run-1782137619176-lgxezy` (Ubuntu real-extension), `.artifacts/platform-smoke/run-1782137625964-66z0oc` (Windows native platform-build), `.artifacts/platform-smoke/run-1782137752969-pbmdj1` (Windows native real-extension)

package/docs/ORACLE_RECOVERY_DRILL.md

@@ -43,7 +43,7 @@ mkdir -p "$SEED"
 chmod 700 "$SEED"
 ```
 
-This simulates a seed profile with no usable ChatGPT session.
+This simulates a seed profile with no usable provider session.
 
 ## Validation steps
 
@@ -72,7 +72,7 @@ Run:
 ```
 
 Expected result:
-- ChatGPT cookies are re-synced into the seed profile
+- provider cookies are re-synced into the seed profile
 - no real Chrome profile is mutated
 - command reports success
 

package/extensions/oracle/index.ts

@@ -11,6 +11,7 @@ import { loadOracleConfig } from "./lib/config.js";
 import { registerOracleCommands } from "./lib/commands.js";
 import { getSessionFile, pruneTerminalOracleJobs, reconcileStaleOracleJobs } from "./lib/jobs.js";
 import { isLockTimeoutError, withGlobalReconcileLock } from "./lib/locks.js";
+import { isOracleProjectTrusted } from "./lib/trust.js";
 import { refreshOracleStatus, setOracleReadiness, startPoller, stopPoller } from "./lib/poller.js";
 import { promoteQueuedJobs } from "./lib/queue.js";
 import { assertOracleSubmitPrerequisites, hasPersistedSessionFile } from "./lib/runtime.js";
@@ -29,10 +30,6 @@ function oracleReadinessFromError(error: unknown): "auth_needed" | "config_error
   return /auth seed profile/i.test(message) ? "auth_needed" : "config_error";
 }
 
-function isProjectTrusted(ctx: ExtensionContext): boolean {
-  return (ctx as { isProjectTrusted?: () => boolean }).isProjectTrusted?.() ?? true;
-}
-
 function expandOraclePromptTemplate(source: string, args: string): string {
   return source.replaceAll("$@", args).replaceAll("$ARGUMENTS", args);
 }
@@ -94,7 +91,7 @@ export default function oracleExtension(pi: ExtensionAPI) {
         return;
       }
 
-      const config = loadOracleConfig(ctx.cwd, { projectConfigTrusted: isProjectTrusted(ctx) });
+      const config = loadOracleConfig(ctx.cwd, { projectConfigTrusted: isOracleProjectTrusted(ctx) });
       setOracleReadiness(ctx, "loaded");
       void assertOracleSubmitPrerequisites(config)
         .then(() => setOracleReadiness(ctx, "ready"))

package/extensions/oracle/lib/commands.ts

@@ -8,7 +8,8 @@ import { readFile } from "node:fs/promises";
 import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import { formatOracleCancelOutcome, formatOracleJobSummary } from "../shared/job-observability-helpers.mjs";
 import { runOracleAuthBootstrap } from "./auth.js";
-import type { OracleProvider } from "./config.js";
+import { normalizeOracleProviderAlias, type OracleProvider } from "./config.js";
+import { isOracleProjectTrusted } from "./trust.js";
 import {
   cancelOracleJob,
   getJobDir,
@@ -27,11 +28,6 @@ import { refreshOracleStatus } from "./poller.js";
 import { isLockTimeoutError, withGlobalReconcileLock } from "./locks.js";
 import { getProjectId } from "./runtime.js";
 
-export interface OracleCommandPromptTemplates {
-  oracle?: string;
-  oracleFollowup?: string;
-}
-
 async function summarizeJob(jobId: string, options?: { responsePreview?: boolean }): Promise<string> {
   const job = readJob(jobId);
   if (!job) return `Oracle job ${jobId} not found.`;
@@ -72,37 +68,42 @@ function readScopedJob(jobId: string, cwd: string) {
 }
 
 function parseOracleAuthProvider(args: string): OracleProvider | undefined {
-  const value = args.trim().toLowerCase();
+  const value = args.trim();
   if (!value) return undefined;
-  if (value === "chatgpt" || value === "chat-gpt" || value === "openai") return "chatgpt";
-  if (value === "grok" || value === "xai" || value === "x.ai") return "grok";
+  const provider = normalizeOracleProviderAlias(value);
+  if (provider) return provider;
   throw new Error("Usage: /oracle-auth [chatgpt|grok]");
 }
 
-function isProjectTrusted(ctx: ExtensionCommandContext): boolean {
-  return (ctx as { isProjectTrusted?: () => boolean }).isProjectTrusted?.() ?? true;
-}
-
-function emitCommandOutput(ctx: ExtensionCommandContext, message: string, level: "info" | "warning" | "error" = "info"): void {
+function emitCommandOutput(pi: ExtensionAPI, ctx: ExtensionCommandContext, message: string, level: "info" | "warning" | "error" = "info"): void {
   if (ctx.mode === "print") {
     process.stdout.write(`${message}\n`);
     return;
   }
-  ctx.ui.notify(message, level);
+  if (ctx.hasUI) {
+    ctx.ui.notify(message, level);
+    return;
+  }
+  pi.sendMessage({
+    customType: "oracle-command-output",
+    content: message,
+    display: true,
+    details: { level },
+  });
 }
 
-export function registerOracleCommands(pi: ExtensionAPI, authWorkerPath: string, workerPath: string, _promptTemplates: OracleCommandPromptTemplates = {}): void {
+export function registerOracleCommands(pi: ExtensionAPI, authWorkerPath: string, workerPath: string): void {
   pi.registerCommand("oracle-auth", {
     description: "Sync ChatGPT or Grok cookies from the configured local browser profile into the provider auth seed profile",
     handler: async (args, ctx) => {
       try {
         const provider = parseOracleAuthProvider(args);
         const providerLabel = provider === "grok" ? "Grok" : provider === "chatgpt" ? "ChatGPT" : "configured provider";
-        emitCommandOutput(ctx, `Syncing ${providerLabel} cookies from the configured local browser profile into the oracle auth seed profile…`, "info");
-        const result = await runOracleAuthBootstrap(authWorkerPath, ctx.cwd, provider, { projectConfigTrusted: isProjectTrusted(ctx) });
-        emitCommandOutput(ctx, result, "info");
+        emitCommandOutput(pi, ctx, `Syncing ${providerLabel} cookies from the configured local browser profile into the oracle auth seed profile…`, "info");
+        const result = await runOracleAuthBootstrap(authWorkerPath, ctx.cwd, provider, { projectConfigTrusted: isOracleProjectTrusted(ctx) });
+        emitCommandOutput(pi, ctx, result, "info");
       } catch (error) {
-        emitCommandOutput(ctx, error instanceof Error ? error.message : String(error), "warning");
+        emitCommandOutput(pi, ctx, error instanceof Error ? error.message : String(error), "warning");
       }
     },
   });
@@ -113,12 +114,12 @@ export function registerOracleCommands(pi: ExtensionAPI, authWorkerPath: string,
       const explicitJobId = args.trim();
       const jobId = explicitJobId || getLatestJobId(ctx.cwd);
       if (!jobId) {
-        emitCommandOutput(ctx, "No oracle jobs found for this project", "info");
+        emitCommandOutput(pi, ctx, "No oracle jobs found for this project", "info");
         return;
       }
       const job = readScopedJob(jobId, ctx.cwd);
       if (!job) {
-        emitCommandOutput(ctx, `Oracle job ${jobId} was not found in this project`, "warning");
+        emitCommandOutput(pi, ctx, `Oracle job ${jobId} was not found in this project`, "warning");
         return;
       }
       if (isTerminalOracleJob(job)) {
@@ -130,7 +131,7 @@ export function registerOracleCommands(pi: ExtensionAPI, authWorkerPath: string,
       }
       const summary = await summarizeJob(job.id);
       const recentJobs = !explicitJobId ? listRecentJobIds(ctx.cwd) : undefined;
-      emitCommandOutput(ctx, [summary, recentJobs ? `Recent jobs: ${recentJobs}` : undefined].filter(Boolean).join("\n"), "info");
+      emitCommandOutput(pi, ctx, [summary, recentJobs ? `Recent jobs: ${recentJobs}` : undefined].filter(Boolean).join("\n"), "info");
     },
   });
 
@@ -140,12 +141,12 @@ export function registerOracleCommands(pi: ExtensionAPI, authWorkerPath: string,
       const explicitJobId = args.trim();
       const jobId = explicitJobId || getLatestJobId(ctx.cwd);
       if (!jobId) {
-        emitCommandOutput(ctx, "No oracle jobs found for this project", "info");
+        emitCommandOutput(pi, ctx, "No oracle jobs found for this project", "info");
         return;
       }
       const job = readScopedJob(jobId, ctx.cwd);
       if (!job) {
-        emitCommandOutput(ctx, `Oracle job ${jobId} was not found in this project`, "warning");
+        emitCommandOutput(pi, ctx, `Oracle job ${jobId} was not found in this project`, "warning");
         return;
       }
       if (isTerminalOracleJob(job)) {
@@ -155,7 +156,7 @@ export function registerOracleCommands(pi: ExtensionAPI, authWorkerPath: string,
           cwd: ctx.cwd,
         });
       }
-      emitCommandOutput(ctx, await summarizeJob(job.id, { responsePreview: true }), "info");
+      emitCommandOutput(pi, ctx, await summarizeJob(job.id, { responsePreview: true }), "info");
     },
   });
 
@@ -164,20 +165,20 @@ export function registerOracleCommands(pi: ExtensionAPI, authWorkerPath: string,
     handler: async (args, ctx) => {
       const jobId = args.trim();
       if (!jobId) {
-        emitCommandOutput(ctx, "Usage: /oracle-cancel <job-id>\nUse /oracle-status to find the job id you want to cancel.", "warning");
+        emitCommandOutput(pi, ctx, "Usage: /oracle-cancel <job-id>\nUse /oracle-status to find the job id you want to cancel.", "warning");
         return;
       }
 
       const job = readScopedJob(jobId, ctx.cwd);
       if (!job) {
-        emitCommandOutput(ctx, `Oracle job ${jobId} not found in this project`, "warning");
+        emitCommandOutput(pi, ctx, `Oracle job ${jobId} not found in this project`, "warning");
         return;
       }
       if (!isOpenOracleJob(job)) {
         if (isTerminalOracleJob(job)) {
-          emitCommandOutput(ctx, `Job is already terminal: ${job.status}. Use /oracle-read ${job.id} for details or /oracle-clean ${job.id} to remove it.`, "info");
+          emitCommandOutput(pi, ctx, `Job is already terminal: ${job.status}. Use /oracle-read ${job.id} for details or /oracle-clean ${job.id} to remove it.`, "info");
         } else {
-          emitCommandOutput(ctx, `Oracle job ${jobId} is not cancellable (${job.status})`, "info");
+          emitCommandOutput(pi, ctx, `Oracle job ${jobId} is not cancellable (${job.status})`, "info");
         }
         return;
       }
@@ -187,7 +188,7 @@ export function registerOracleCommands(pi: ExtensionAPI, authWorkerPath: string,
         await promoteQueuedJobs({ workerPath, source: "oracle_cancel_command" });
       }
       refreshOracleStatus(ctx);
-      emitCommandOutput(ctx, formatOracleCancelOutcome(cancelled), "info");
+      emitCommandOutput(pi, ctx, formatOracleCancelOutcome(cancelled), "info");
     },
   });
 
@@ -196,19 +197,20 @@ export function registerOracleCommands(pi: ExtensionAPI, authWorkerPath: string,
     handler: async (args, ctx: ExtensionCommandContext) => {
       const target = args.trim();
       if (!target) {
-        emitCommandOutput(ctx, "Usage: /oracle-clean <job-id|all>", "warning");
+        emitCommandOutput(pi, ctx, "Usage: /oracle-clean <job-id|all>", "warning");
         return;
       }
 
       const jobs = target === "all" ? listJobsForCwd(ctx.cwd) : [readScopedJob(target, ctx.cwd)].filter(Boolean);
       if (jobs.length === 0) {
-        emitCommandOutput(ctx, "No matching oracle jobs found", "warning");
+        emitCommandOutput(pi, ctx, "No matching oracle jobs found", "warning");
         return;
       }
 
       const nonTerminalJobs = jobs.filter((job): job is NonNullable<typeof job> => Boolean(job && !isTerminalOracleJob(job)));
       if (nonTerminalJobs.length > 0) {
         emitCommandOutput(
+          pi,
           ctx,
           `Refusing to remove non-terminal oracle job${nonTerminalJobs.length === 1 ? "" : "s"}: ${nonTerminalJobs.map((job) => job.id).join(", ")}`,
           "warning",
@@ -246,7 +248,7 @@ export function registerOracleCommands(pi: ExtensionAPI, authWorkerPath: string,
         : removedCount === jobs.length
           ? `Removed ${removedCount} oracle job director${removedCount === 1 ? "y" : "ies"}.`
           : `Removed ${removedCount} of ${jobs.length} oracle job director${jobs.length === 1 ? "y" : "ies"}; retained ${jobs.length - removedCount} due to cleanup blockers or warnings.`;
-      emitCommandOutput(ctx, `${removalSummary}${warningSuffix}`, cleanupWarnings.length > 0 ? "warning" : "info");
+      emitCommandOutput(pi, ctx, `${removalSummary}${warningSuffix}`, cleanupWarnings.length > 0 ? "warning" : "info");
     },
   });
 }

package/extensions/oracle/lib/config.ts

@@ -22,6 +22,21 @@ import { getProjectId } from "./runtime.js";
 export const ORACLE_PROVIDERS = ["chatgpt", "grok"] as const;
 export type OracleProvider = (typeof ORACLE_PROVIDERS)[number];
 
+export function normalizeOracleProviderAlias(value: string): OracleProvider | undefined {
+  const normalized = value.trim().toLowerCase();
+  if (normalized === "chatgpt" || normalized === "chat-gpt" || normalized === "openai") return "chatgpt";
+  if (normalized === "grok" || normalized === "xai" || normalized === "x.ai") return "grok";
+  return undefined;
+}
+
+export function normalizeOracleProvider(value: unknown, fallback: OracleProvider, toolName = "oracle_submit"): OracleProvider {
+  if (value === undefined) return fallback;
+  if (typeof value !== "string") throw new Error(`${toolName} provider must be a string`);
+  const provider = normalizeOracleProviderAlias(value);
+  if (provider) return provider;
+  throw new Error(`Unknown ${toolName} provider: ${value}. Use chatgpt or grok.`);
+}
+
 export { resolveOracleArchiveFormat, resolveOracleProviderArchivePlan } from "./provider-capabilities.js";
 export type { OracleArchiveFormat, OracleProviderArchivePlan } from "./provider-capabilities.js";
 
@@ -308,7 +323,7 @@ function detectDefaultChromeUserAgent(executablePath: string | undefined): strin
   const platformToken = chromeUserAgentPlatformToken(process.platform);
   if (!platformToken) return undefined;
   try {
-    const versionOutput = execFileSync(executablePath, ["--version"], { encoding: "utf8", env: sweetCookieSafeStoragePasswordScrubbedEnv() }).trim();
+    const versionOutput = execFileSync(executablePath, ["--version"], { encoding: "utf8", env: sweetCookieSafeStoragePasswordScrubbedEnv(), timeout: 1000 }).trim();
     const versionMatch = versionOutput.match(/(\d+\.\d+\.\d+\.\d+)/);
     if (!versionMatch) return undefined;
     return `Mozilla/5.0 (${platformToken}) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/${versionMatch[1]} Safari/537.36`;
@@ -318,8 +333,17 @@ function detectDefaultChromeUserAgent(executablePath: string | undefined): strin
 }
 
 const detectedChromeExecutablePath = detectDefaultChromeExecutablePath();
-const detectedChromeUserAgent = detectDefaultChromeUserAgent(detectedChromeExecutablePath);
+let detectedChromeUserAgent: string | undefined;
+let detectedChromeUserAgentResolved = false;
 const agentExtensionsDir = join(getAgentDir(), "extensions");
+
+function getDetectedChromeUserAgent(): string | undefined {
+  if (!detectedChromeUserAgentResolved) {
+    detectedChromeUserAgent = detectDefaultChromeUserAgent(detectedChromeExecutablePath);
+    detectedChromeUserAgentResolved = true;
+  }
+  return detectedChromeUserAgent;
+}
 const detectedChromeProfileName = detectDefaultBrowserProfileSource(process.platform);
 
 export interface OracleConfigLoadOptions {
@@ -442,7 +466,7 @@ export const DEFAULT_CONFIG: OracleConfig = {
     authUrl: "https://chatgpt.com/auth/login",
     runMode: "headless",
     executablePath: detectedChromeExecutablePath,
-    userAgent: detectedChromeUserAgent,
+    userAgent: undefined,
     args: ["--disable-blink-features=AutomationControlled"],
   },
   auth: {
@@ -732,5 +756,14 @@ export function loadOracleConfig(cwd: string, options?: OracleConfigLoadOptions)
   const details = getOracleConfigLoadDetails(cwd, options);
   const globalConfig = readJson(details.agentConfigPath);
   const projectConfig = details.projectConfigLoaded ? filterProjectConfig(readJson(details.projectConfigPath)) : undefined;
-  return validateOracleConfig(deepMerge(deepMerge(DEFAULT_CONFIG, globalConfig), projectConfig));
+  const globalBrowser = isObject(globalConfig) ? globalConfig.browser : undefined;
+  const hasConfiguredUserAgent = isObject(globalBrowser) && globalBrowser.userAgent !== undefined;
+  const defaults = {
+    ...DEFAULT_CONFIG,
+    browser: {
+      ...DEFAULT_CONFIG.browser,
+      userAgent: hasConfiguredUserAgent ? undefined : getDetectedChromeUserAgent(),
+    },
+  };
+  return validateOracleConfig(deepMerge(deepMerge(defaults, globalConfig), projectConfig));
 }

package/extensions/oracle/lib/jobs.ts

@@ -30,6 +30,8 @@ import type { OracleJobLifecycleEvent as SharedOracleJobLifecycleEvent, OracleJo
 import { hasDurableWorkerHandoff as sharedHasDurableWorkerHandoff } from "../shared/job-coordination-helpers.mjs";
 import { isTrackedProcessAlive, readProcessStartedAt, spawnDetachedNodeProcess, terminateTrackedProcess } from "../shared/process-helpers.mjs";
 import type { OracleConfig, OracleResolvedSelection } from "./config.js";
+import { getOracleJobsDir } from "../shared/state-path-helpers.mjs";
+import { parseTimestamp } from "../shared/time-helpers.mjs";
 import { resolveOracleProviderArchivePlan } from "./provider-capabilities.js";
 import { withJobLock, withLock } from "./locks.js";
 import { cleanupRuntimeArtifacts, getProjectId, getSessionId, parseConversationId, requirePersistedSessionFile, type OracleCleanupReport } from "./runtime.js";
@@ -50,9 +52,8 @@ const ORACLE_JOB_DIR_RM_MAX_RETRIES = 5;
 const ORACLE_JOB_DIR_RM_RETRY_DELAY_MS = 50;
 const ORACLE_COMPLETE_JOB_RETENTION_MS = 14 * 24 * 60 * 60 * 1000;
 const ORACLE_FAILED_JOB_RETENTION_MS = 30 * 24 * 60 * 60 * 1000;
-export const DEFAULT_ORACLE_JOBS_DIR = "/tmp";
-export const ORACLE_JOBS_DIR_ENV = "PI_ORACLE_JOBS_DIR";
-const ORACLE_JOBS_DIR = process.env[ORACLE_JOBS_DIR_ENV]?.trim() || DEFAULT_ORACLE_JOBS_DIR;
+export { DEFAULT_ORACLE_JOBS_DIR, ORACLE_JOBS_DIR_ENV, getOracleJobsDir } from "../shared/state-path-helpers.mjs";
+const ORACLE_JOBS_DIR = getOracleJobsDir();
 
 export function isActiveOracleJob(job: Pick<OracleJob, "status">): boolean {
   return ACTIVE_ORACLE_JOB_STATUSES.includes(job.status);
@@ -217,10 +218,6 @@ export function getSessionFile(ctx: ExtensionContext): string | undefined {
   return hasSessionFileAccessor(ctx.sessionManager) ? ctx.sessionManager.getSessionFile() : undefined;
 }
 
-export function getOracleJobsDir(): string {
-  return ORACLE_JOBS_DIR;
-}
-
 export function getJobDir(id: string): string {
   return join(ORACLE_JOBS_DIR, `oracle-${id}`);
 }
@@ -297,12 +294,6 @@ export async function clearCleanupPending(jobId: string, at = new Date().toISOSt
   }
 }
 
-function parseTimestamp(value: string | undefined): number | undefined {
-  if (!value) return undefined;
-  const parsed = Date.parse(value);
-  return Number.isFinite(parsed) ? parsed : undefined;
-}
-
 function notificationClaimIsOwnedBy(job: Pick<OracleJob, "notifyClaimedAt" | "notifyClaimedBy">, claimedBy: string, now = Date.now()): boolean {
   if (job.notifyClaimedBy !== claimedBy) return false;
   const claimedAtMs = parseTimestamp(job.notifyClaimedAt);

package/extensions/oracle/lib/locks.ts

@@ -100,14 +100,6 @@ export async function withGlobalReconcileLock<T>(
   return withLock("reconcile", "global", metadata, fn, { timeoutMs: options?.timeoutMs ?? 30_000 });
 }
 
-export async function withGlobalScanLock<T>(
-  metadata: unknown,
-  fn: () => Promise<T>,
-  options?: { timeoutMs?: number },
-): Promise<T> {
-  return withLock("scan", "global", metadata, fn, { timeoutMs: options?.timeoutMs ?? 5_000 });
-}
-
 export async function withJobLock<T>(jobId: string, metadata: unknown, fn: () => Promise<T>): Promise<T> {
   return withLock("job", jobId, metadata, fn, { timeoutMs: 10_000 });
 }

package/extensions/oracle/lib/poller.ts

@@ -7,6 +7,7 @@ import { existsSync } from "node:fs";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { buildOracleStatusText, buildOracleWakeupNotificationContent, type OracleReadinessStatus } from "../shared/job-observability-helpers.mjs";
 import { isProcessAlive, readProcessStartedAt } from "../shared/process-helpers.mjs";
+import { parseTimestamp } from "../shared/time-helpers.mjs";
 import { isLockTimeoutError, listLeaseMetadata, releaseLease, withGlobalReconcileLock, writeLeaseMetadata } from "./locks.js";
 import {
   getJobDir,
@@ -90,12 +91,6 @@ function jobMatchesContext(job: { projectId: string; sessionId: string }, sessio
   return job.projectId === projectId && job.sessionId === sessionId;
 }
 
-function parseTimestamp(value: string | undefined): number | undefined {
-  if (!value) return undefined;
-  const parsed = Date.parse(value);
-  return Number.isFinite(parsed) ? parsed : undefined;
-}
-
 function getWakeupTargetLeaseKey(sessionKey: string, processPid = process.pid, processStartedAt = readProcessStartedAt(process.pid) || "unknown"): string {
   return `${sessionKey}::${processPid}::${processStartedAt}`;
 }

package/extensions/oracle/lib/queue.ts

@@ -14,7 +14,7 @@ import {
 import { transitionOracleJobPhase } from "../shared/job-lifecycle-helpers.mjs";
 import { loadOracleConfig } from "./config.js";
 import { withLock } from "./locks.js";
-import { appendCleanupWarnings, createJob, isTerminalOracleJob, listOracleJobDirs, readJob, spawnWorker, terminateWorkerPid, updateJob, type OracleJob } from "./jobs.js";
+import { appendCleanupWarnings, isTerminalOracleJob, listOracleJobDirs, readJob, spawnWorker, terminateWorkerPid, updateJob, type OracleJob } from "./jobs.js";
 import { cleanupRuntimeArtifacts, releaseRuntimeLease, tryAcquireConversationLease, tryAcquireRuntimeLease } from "./runtime.js";
 
 export interface OracleQueuePosition {
@@ -144,14 +144,3 @@ export async function promoteQueuedJobs(options: PromoteQueuedJobsOptions): Prom
     return promoteQueuedJobsWithinAdmissionLock(options);
   }, { timeoutMs: options.lockTimeoutMs });
 }
-
-export async function createQueuedJob(
-  id: string,
-  input: Parameters<typeof createJob>[1],
-  cwd: string,
-  originSessionFile: string | undefined,
-  config: Parameters<typeof createJob>[4],
-  runtime: Parameters<typeof createJob>[5],
-): Promise<OracleJob> {
-  return createJob(id, input, cwd, originSessionFile, config, runtime, { initialState: "queued" });
-}

package/extensions/oracle/lib/runtime.ts

@@ -13,12 +13,11 @@ import { assertNotKnownBrowserUserDataPath, sweetCookieSafeStoragePasswordScrubb
 import { jobBlocksAdmission } from "../shared/job-coordination-helpers.mjs";
 import { isTrackedProcessAlive } from "../shared/process-helpers.mjs";
 import type { OracleConfig, OracleProvider } from "./config.js";
+import { getOracleJobsDir } from "../shared/state-path-helpers.mjs";
 import { resolveOracleProviderArchivePlan } from "./provider-capabilities.js";
 import { createLease, listLeaseMetadata, readLeaseMetadata, releaseLease, withAuthLock } from "./locks.js";
 
 const SEED_GENERATION_FILE = ".oracle-seed-generation";
-const DEFAULT_ORACLE_JOBS_DIR = "/tmp";
-const ORACLE_JOBS_DIR = process.env.PI_ORACLE_JOBS_DIR?.trim() || DEFAULT_ORACLE_JOBS_DIR;
 const AGENT_BROWSER_BIN = [process.env.AGENT_BROWSER_PATH, "/opt/homebrew/bin/agent-browser", "/usr/local/bin/agent-browser"].find(
   (candidate) => typeof candidate === "string" && candidate && existsSync(candidate),
 ) || "agent-browser";
@@ -338,7 +337,7 @@ export async function assertOracleSubmitPrerequisites(config: OracleConfig, prov
     await assertRequiredLocalDependencyReady(dependency.name, dependency.command);
   }
   await assertWritableDirectory(config.browser.runtimeProfilesDir, "runtime profiles");
-  await assertWritableDirectory(ORACLE_JOBS_DIR, "jobs");
+  await assertWritableDirectory(getOracleJobsDir(), "jobs");
 }
 
 export function getSeedGeneration(config: OracleConfig): string | undefined {
@@ -359,7 +358,7 @@ export async function writeSeedGeneration(config: OracleConfig, value = new Date
 }
 
 function activeJobExists(jobId: string): boolean {
-  const path = join(ORACLE_JOBS_DIR, `oracle-${jobId}`, "job.json");
+  const path = join(getOracleJobsDir(), `oracle-${jobId}`, "job.json");
   if (!existsSync(path)) return false;
   try {
     const job = JSON.parse(readFileSync(path, "utf8")) as {

package/extensions/oracle/lib/tools.ts

@@ -10,13 +10,15 @@ import { join } from "node:path";
 import { createArchive, type ArchiveCreationResult, type ArchiveSizeBreakdownRow } from "./archive.js";
 import { runOracleAuthBootstrap } from "./auth.js";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { Type } from "typebox";
+import { Type, type Static } from "typebox";
 import { formatOracleCancelOutcome, formatOracleJobSummary, formatOracleSubmitResponse } from "../shared/job-observability-helpers.mjs";
 import { getLatestOracleJobLifecycleEvent, getLatestOracleTerminalLifecycleEvent, transitionOracleJobPhase } from "../shared/job-lifecycle-helpers.mjs";
 import { isLockTimeoutError, withGlobalReconcileLock, withLock } from "./locks.js";
 import {
   coerceOracleSubmitPresetId,
   loadOracleConfig,
+  normalizeOracleProvider,
+  GROK_MODES,
   ORACLE_PROVIDERS,
   ORACLE_SUBMIT_PRESET_IDS,
   resolveOracleConfigForProvider,
@@ -48,6 +50,7 @@ import {
   updateJob,
   type OracleJob,
 } from "./jobs.js";
+import { isOracleProjectTrusted } from "./trust.js";
 import { getQueuePosition, promoteQueuedJobs, promoteQueuedJobsWithinAdmissionLock } from "./queue.js";
 import { resolveOracleProviderArchivePlan } from "./provider-capabilities.js";
 import { refreshOracleStatus } from "./poller.js";
@@ -64,6 +67,16 @@ import {
   tryAcquireRuntimeLease,
 } from "./runtime.js";
 
+const ORACLE_PROVIDER_PARAM_DESCRIPTION = `Oracle web provider. Omit to use the configured default provider. Supported providers: ${ORACLE_PROVIDERS.join(", ")}.`;
+const ORACLE_PROVIDER_PARAM = Type.Optional(Type.String({
+  description: ORACLE_PROVIDER_PARAM_DESCRIPTION,
+  enum: [...ORACLE_PROVIDERS],
+}));
+const ORACLE_GROK_MODE_PARAM = Type.Optional(Type.String({
+  description: "Provider mode. For Grok, only heavy is currently supported. Omit to use the configured default mode.",
+  enum: [...GROK_MODES],
+}));
+
 const ORACLE_SUBMIT_PARAMS = Type.Object({
   prompt: Type.String({ description: "Prompt text to send to ChatGPT or Grok web." }),
   files: Type.Array(Type.String({
@@ -74,11 +87,7 @@ const ORACLE_SUBMIT_PARAMS = Type.Object({
     description: "Exact project-relative files/directories to include in the oracle archive.",
     minItems: 1,
   }),
-  provider: Type.Optional(
-    Type.String({
-      description: `Oracle web provider. Omit to use the configured default provider. Supported providers: ${ORACLE_PROVIDERS.join(", ")}. Use grok when the user asks to oracle to Grok. Grok archives are capped at 200 MiB.`,
-    }),
-  ),
+  provider: ORACLE_PROVIDER_PARAM,
   preset: Type.Optional(
     Type.String({
       description:
@@ -86,50 +95,55 @@ const ORACLE_SUBMIT_PARAMS = Type.Object({
         "Matching human-readable preset labels and common hyphen/space variants are normalized automatically. Do not pass preset when provider is grok.",
     }),
   ),
-  mode: Type.Optional(
-    Type.String({
-      description: "Provider mode. For Grok, only heavy is currently supported. Omit to use the configured default mode.",
-    }),
-  ),
+  mode: ORACLE_GROK_MODE_PARAM,
   followUpJobId: Type.Optional(Type.String({ description: "Earlier oracle job id whose chat thread should be continued." })),
   chatGptConversationId: Type.Optional(Type.String({
     description: "Existing ChatGPT conversation id, or full https://chatgpt.com/c/... URL, to continue. Omit for default behavior: starting a fresh oracle thread. Do not combine with followUpJobId.",
     minLength: 1,
     pattern: "^.*\\S.*$",
   })),
-});
+}, { additionalProperties: false });
 
 const ORACLE_PREFLIGHT_PARAMS = Type.Object({
-  provider: Type.Optional(Type.String({ description: `Provider readiness to check. Omit to use the configured default provider. Supported providers: ${ORACLE_PROVIDERS.join(", ")}.` })),
+  provider: ORACLE_PROVIDER_PARAM,
   followUpJobId: Type.Optional(Type.String({ description: "Earlier oracle job id whose provider/thread readiness should be checked." })),
   chatGptConversationId: Type.Optional(Type.String({
     description: "Existing ChatGPT conversation id, or full https://chatgpt.com/c/... URL, whose provider/thread readiness should be checked. Do not combine with followUpJobId.",
     minLength: 1,
     pattern: "^.*\\S.*$",
   })),
-});
+}, { additionalProperties: false });
 
 const ORACLE_AUTH_PARAMS = Type.Object({
-  provider: Type.Optional(Type.String({ description: `Provider auth seed to refresh. Omit to use the configured default provider. Supported providers: ${ORACLE_PROVIDERS.join(", ")}.` })),
-});
+  provider: ORACLE_PROVIDER_PARAM,
+}, { additionalProperties: false });
 
 const ORACLE_READ_PARAMS = Type.Object({
   jobId: Type.String({ description: "Oracle job id." }),
-});
+}, { additionalProperties: false });
 
 const ORACLE_CANCEL_PARAMS = Type.Object({
   jobId: Type.String({ description: "Oracle job id." }),
-});
+}, { additionalProperties: false });
 
 const MAX_QUEUED_JOBS_PER_ACTIVE_RUNTIME = 1;
 const MAX_QUEUED_ARCHIVE_BYTES_PER_ACTIVE_RUNTIME = resolveOracleProviderArchivePlan("chatgpt").maxArchiveBytes;
-function normalizeOracleProvider(value: unknown, fallback: OracleProvider, toolName = "oracle_submit"): OracleProvider {
-  if (value === undefined) return fallback;
-  if (typeof value !== "string") throw new Error(`${toolName} provider must be a string`);
-  const normalized = value.trim().toLowerCase();
-  if (normalized === "chatgpt" || normalized === "chat-gpt" || normalized === "openai") return "chatgpt";
-  if (normalized === "grok" || normalized === "xai" || normalized === "x.ai") return "grok";
-  throw new Error(`Unknown ${toolName} provider: ${value}. Use chatgpt or grok.`);
+function prepareOracleProviderAliases<T>(args: unknown, toolName: string): T {
+  const record = asRecord(args);
+  if (!record) return args as T;
+  return {
+    ...record,
+    provider: typeof record.provider === "string" ? normalizeOracleProvider(record.provider, "chatgpt", toolName) : record.provider,
+  } as T;
+}
+
+function prepareOracleSubmitArguments(args: unknown): Static<typeof ORACLE_SUBMIT_PARAMS> {
+  const record = asRecord(args);
+  if (!record) return args as Static<typeof ORACLE_SUBMIT_PARAMS>;
+  return {
+    ...prepareOracleProviderAliases<Record<string, unknown>>(record, "oracle_submit"),
+    mode: typeof record.mode === "string" ? normalizeGrokMode(record.mode, "heavy") : record.mode,
+  } as Static<typeof ORACLE_SUBMIT_PARAMS>;
 }
 
 function normalizeGrokMode(value: unknown, fallback: "heavy"): "heavy" {
@@ -691,10 +705,6 @@ function formatOraclePreflightResponse(details: OraclePreflightDetails): string
   ].filter(Boolean).join("\n");
 }
 
-function isProjectTrusted(ctx: ExtensionContext): boolean {
-  return (ctx as { isProjectTrusted?: () => boolean }).isProjectTrusted?.() ?? true;
-}
-
 async function runOraclePreflight(ctx: ExtensionContext, params: { provider?: unknown; followUpJobId?: unknown; chatGptConversationId?: unknown } = {}): Promise<OraclePreflightDetails> {
   const sessionFile = getSessionFile(ctx);
   if (!hasPersistedSessionFile(sessionFile)) {
@@ -722,7 +732,7 @@ async function runOraclePreflight(ctx: ExtensionContext, params: { provider?: un
     if (chatGptConversationId !== undefined && typeof chatGptConversationId !== "string") {
       throw new Error("oracle_preflight chatGptConversationId must be a string");
     }
-    const baseConfig = loadOracleConfig(ctx.cwd, { projectConfigTrusted: isProjectTrusted(ctx) });
+    const baseConfig = loadOracleConfig(ctx.cwd, { projectConfigTrusted: isOracleProjectTrusted(ctx) });
     const target = resolveConversationTarget({ followUpJobId, chatGptConversationId, cwd: ctx.cwd, config: baseConfig });
     provider = normalizeOracleProvider(params.provider, target.provider ?? baseConfig.defaults.provider, "oracle_preflight");
     if (target.provider && provider !== target.provider) {
@@ -789,6 +799,7 @@ export function registerOracleTools(pi: ExtensionAPI, workerPath: string, authWo
       "Call oracle_preflight before doing expensive /oracle preparation. Pass provider='grok' when the user explicitly asks for Grok, followUpJobId for same-thread follow-ups from oracle-created jobs, or chatGptConversationId when the user explicitly provides an existing ChatGPT browser conversation id/URL. If ready is false, stop immediately and report the suggested next step instead of reading files or crafting archive inputs.",
     ],
     parameters: ORACLE_PREFLIGHT_PARAMS,
+    prepareArguments: (args) => prepareOracleProviderAliases(args, "oracle_preflight"),
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
       const details = await runOraclePreflight(ctx, params);
       return {
@@ -809,12 +820,13 @@ export function registerOracleTools(pi: ExtensionAPI, workerPath: string, authWo
       "If oracle_auth itself fails, stop and report the failure instead of looping.",
     ],
     parameters: ORACLE_AUTH_PARAMS,
+    prepareArguments: (args) => prepareOracleProviderAliases(args, "oracle_auth"),
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
       try {
         const projectCwd = getProjectId(ctx.cwd);
-        const baseConfig = loadOracleConfig(projectCwd, { projectConfigTrustCwd: ctx.cwd, projectConfigTrusted: isProjectTrusted(ctx) });
+        const baseConfig = loadOracleConfig(projectCwd, { projectConfigTrustCwd: ctx.cwd, projectConfigTrusted: isOracleProjectTrusted(ctx) });
         const provider = normalizeOracleProvider(params.provider, baseConfig.defaults.provider, "oracle_auth");
-        const message = await runOracleAuthBootstrap(authWorkerPath, projectCwd, provider, { projectConfigTrustCwd: ctx.cwd, projectConfigTrusted: isProjectTrusted(ctx) });
+        const message = await runOracleAuthBootstrap(authWorkerPath, projectCwd, provider, { projectConfigTrustCwd: ctx.cwd, projectConfigTrusted: isOracleProjectTrusted(ctx) });
         return {
           content: [{ type: "text" as const, text: message }],
           details: {
@@ -838,30 +850,20 @@ export function registerOracleTools(pi: ExtensionAPI, workerPath: string, authWo
       "Optional thread target: pass `chatGptConversationId` only when the user explicitly provides an existing ChatGPT browser conversation id/URL to continue; omit it for the default fresh oracle thread.",
     promptSnippet: "Dispatch a background ChatGPT or Grok web oracle job after gathering repo context.",
     promptGuidelines: [
-      "Gather context before calling oracle_submit.",
-      "If the user explicitly provides an existing ChatGPT browser conversation id or https://chatgpt.com/c/... URL, pass it as chatGptConversationId and force provider='chatgpt'; otherwise omit chatGptConversationId so oracle_submit starts a fresh thread by default.",
-      "If the immediately preceding oracle run failed because ChatGPT or Grok login is required or the worker explicitly said to rerun /oracle-auth, call oracle_auth once before retrying the submission; pass provider='grok' for Grok retries. Do not loop auth refreshes.",
-      "Prefer context-rich archives up to the provider ceiling because more relevant surrounding context is usually better than less: 250 MB for ChatGPT and 200 MiB for Grok.",
-      "By default, archive the whole repo by passing '.' for broad or unclear requests; default archive exclusions apply automatically, including common bulky outputs and obvious credentials/private data like .env files, key material, credential dotfiles, local database files, and nested secrets directories anywhere in the repo.",
-      "For narrower asks, still include nearby tests, docs, configs, and adjacent modules when they may improve answer quality. Only narrow aggressively when the user explicitly asks, privacy/sensitivity requires it, or size pressure forces it.",
-      "Do not default to a one-file archive for a single function, file, or stack trace if the relevant surrounding context still fits comfortably within the limit.",
-      "When files='.' and the post-exclusion archive is still too large, submit automatically prunes the largest nested directories matching generic generated-output names like build/, dist/, out/, coverage/, and tmp/ outside obvious source roots like src/ and lib/ until the archive fits or no candidate remains; successful submissions report what was pruned.",
-      "If a submitted oracle job later fails because upload is rejected, retry smaller: remove the largest obviously irrelevant/generated content first, then narrow to modified files plus adjacent files plus directly relevant subtrees, then explain the cut or ask the user if still needed.",
-      "If oracle_submit fails before dispatch with details.error.code === 'archive_too_large' or an upload-limit message, treat that as retryable and retry automatically with a smaller archive.",
-      "For archive_too_large retries, use the reported top-level size summary and any auto-pruned paths to decide what to cut: first remove the largest obviously irrelevant/generated/history/export content, then if needed narrow to the directly relevant subtrees plus adjacent docs/tests/config.",
-      "Do not loop forever: stop after at most two total oracle_submit attempts for the same request, and if it still does not fit explain what was cut and why.",
-      "For any other submit-time error, stop and report the error instead of retrying automatically.",
-      "If oracle_submit returns a queued job instead of an immediately dispatched one, treat that as success and stop exactly the same way.",
-      "After a successful or queued oracle_submit, stop; do not continue the task while the oracle job is running. If oracle_submit failed with retryable archive_too_large, narrow the archive and retry first.",
-      "For ChatGPT, use `preset` as the only model-selection parameter on oracle_submit. " +
-      `Canonical ids: ${ORACLE_SUBMIT_PRESET_IDS.join(", ")}. ` +
-      "matching human-readable preset labels are normalized automatically. Omit preset to use the configured default. For Grok, pass provider='grok' and omit preset; only Heavy is supported today.",
+      "Call oracle_preflight first, then gather enough context to choose archive inputs before oracle_submit.",
+      "Use context-rich archives when they fit; use files='.' for broad repo-wide asks. Default exclusions already skip common bulky outputs and obvious credentials/private data.",
+      "Pass chatGptConversationId only when the user explicitly provides an existing ChatGPT conversation id/URL; otherwise omit it for a fresh thread.",
+      "If auth is stale, call oracle_auth at most once before retrying. If oracle_auth fails, stop and report it.",
+      "If details.error.code is 'archive_too_large', retry once with a smaller archive using the reported size/pruning details; do not loop.",
+      "After a successful or queued oracle_submit, stop and report only the dispatch summary. Do not keep working while the oracle job runs.",
+      "For ChatGPT, use preset only when the user requests model control; otherwise omit it. For Grok, pass provider='grok' and omit preset.",
     ],
     parameters: ORACLE_SUBMIT_PARAMS,
+    prepareArguments: prepareOracleSubmitArguments,
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
       try {
         const projectCwd = getProjectId(ctx.cwd);
-        const baseConfig = loadOracleConfig(projectCwd, { projectConfigTrustCwd: ctx.cwd, projectConfigTrusted: isProjectTrusted(ctx) });
+        const baseConfig = loadOracleConfig(projectCwd, { projectConfigTrustCwd: ctx.cwd, projectConfigTrusted: isOracleProjectTrusted(ctx) });
         const originSessionFile = requirePersistedSessionFile(getSessionFile(ctx), "submit oracle jobs");
         const projectId = getProjectId(projectCwd);
         const sessionId = getSessionId(originSessionFile, projectId);
@@ -878,6 +880,9 @@ export function registerOracleTools(pi: ExtensionAPI, workerPath: string, authWo
         if (provider === "grok" && typeof params.preset === "string") {
           throw new Error("oracle_submit preset is only valid for ChatGPT. For Grok, use provider='grok' and mode='heavy'.");
         }
+        if (provider === "chatgpt" && typeof params.mode === "string") {
+          throw new Error("oracle_submit mode is only valid for Grok. For ChatGPT, omit mode and use preset for model selection.");
+        }
         const selection = provider === "grok"
           ? resolveOracleGrokMode(normalizeGrokMode(params.mode, baseConfig.defaults.grokMode))
           : resolveOracleSubmitPreset(typeof params.preset === "string" ? coerceOracleSubmitPresetId(params.preset) : baseConfig.defaults.preset);

package/extensions/oracle/lib/trust.ts

@@ -0,0 +1,5 @@
+// Purpose: Keep pi project-trust probing behind one typed extension-side helper.
+
+export function isOracleProjectTrusted(ctx: { isProjectTrusted?: () => boolean }): boolean {
+  return ctx.isProjectTrusted?.() ?? true;
+}

package/extensions/oracle/shared/job-observability-helpers.mjs

@@ -5,6 +5,7 @@
 // Invariants/Assumptions: Job summaries read from durable job state, and lifecycle event trails are bounded and already normalized by shared lifecycle helpers.
 
 import { getLatestOracleJobLifecycleEvent, getLatestOracleTerminalLifecycleEvent } from "./job-lifecycle-helpers.mjs";
+import { parseTimestamp } from "./time-helpers.mjs";
 
 /** @typedef {import("./job-observability-helpers.d.mts").OracleJobSummaryLike} OracleJobSummaryLike */
 /** @typedef {import("./job-observability-helpers.d.mts").OracleJobSummaryOptions} OracleJobSummaryOptions */
@@ -68,16 +69,6 @@ const ACTIVE_SUMMARY_STATUSES = new Set(["preparing", "submitted", "waiting"]);
 const DEFAULT_ORACLE_HEARTBEAT_STALE_MS = 3 * 60 * 1000;
 const DEFAULT_ACTIVE_JOB_POLL_HINT_SECONDS = 15;
 
-/**
- * @param {string | undefined} value
- * @returns {number | undefined}
- */
-function parseTimestamp(value) {
-  if (!value) return undefined;
-  const ms = Date.parse(value);
-  return Number.isNaN(ms) ? undefined : ms;
-}
-
 /**
  * @param {number} elapsedMs
  * @returns {string}

package/extensions/oracle/shared/state-path-helpers.d.mts

@@ -0,0 +1,3 @@
+export declare const DEFAULT_ORACLE_JOBS_DIR = "/tmp";
+export declare const ORACLE_JOBS_DIR_ENV = "PI_ORACLE_JOBS_DIR";
+export declare function getOracleJobsDir(env?: Record<string, string | undefined>): string;

package/extensions/oracle/shared/state-path-helpers.mjs

@@ -0,0 +1,9 @@
+// Purpose: Share oracle state path defaults across extension and detached workers.
+// Scope: Path/env defaults only; no filesystem mutation.
+
+export const DEFAULT_ORACLE_JOBS_DIR = "/tmp";
+export const ORACLE_JOBS_DIR_ENV = "PI_ORACLE_JOBS_DIR";
+
+export function getOracleJobsDir(env = process.env) {
+  return env[ORACLE_JOBS_DIR_ENV]?.trim() || DEFAULT_ORACLE_JOBS_DIR;
+}

package/extensions/oracle/shared/time-helpers.d.mts

@@ -0,0 +1 @@
+export declare function parseTimestamp(value: string | undefined): number | undefined;

package/extensions/oracle/shared/time-helpers.mjs

@@ -0,0 +1,7 @@
+// Purpose: Tiny shared time parsing helper for job timestamps.
+
+export function parseTimestamp(value) {
+  if (!value) return undefined;
+  const parsed = Date.parse(value);
+  return Number.isFinite(parsed) ? parsed : undefined;
+}

package/extensions/oracle/worker/auth-bootstrap.mjs

@@ -16,7 +16,9 @@ import {
 } from "../shared/browser-profile-helpers.mjs";
 import { ensureAccountCookie, filterImportableAuthCookies } from "./auth-cookie-policy.mjs";
 import { getCookiesFromConfiguredChromiumSource } from "./chromium-cookie-source.mjs";
+import { parseSnapshotEntries } from "./artifact-heuristics.mjs";
 import { buildAllowedChatGptOrigins } from "./chatgpt-ui-helpers.mjs";
+import { stripUrlQueryAndHash } from "./chatgpt-flow-helpers.mjs";
 import { buildAccountChooserCandidateLabels, classifyChatAuthPage, normalizeLoginProbeResult } from "./auth-flow-helpers.mjs";
 
 const rawConfig = process.argv[2];
@@ -429,27 +431,6 @@ async function pageText() {
   return stdout || "";
 }
 
-function parseSnapshotEntries(snapshot) {
-  return snapshot
-    .split("\n")
-    .map((line) => {
-      const refMatch = line.match(/\bref=(e\d+)\b/);
-      if (!refMatch) return undefined;
-      const kindMatch = line.match(/^\s*-\s*([^\s]+)/);
-      const quotedMatch = line.match(/"([^"]*)"/);
-      const valueMatch = line.match(/:\s*(.+)$/);
-      return {
-        line,
-        ref: `@${refMatch[1]}`,
-        kind: kindMatch ? kindMatch[1] : undefined,
-        label: quotedMatch ? quotedMatch[1] : undefined,
-        value: valueMatch ? valueMatch[1].trim() : undefined,
-        disabled: /\bdisabled\b/.test(line),
-      };
-    })
-    .filter(Boolean);
-}
-
 function findEntry(snapshot, predicate) {
   return parseSnapshotEntries(snapshot).find(predicate);
 }
@@ -466,17 +447,6 @@ async function clickRef(ref, logLabel = `click ${ref}`) {
   await targetCommand("click", ref, { logLabel });
 }
 
-function stripQuery(url) {
-  try {
-    const parsed = new URL(url);
-    parsed.hash = "";
-    parsed.search = "";
-    return parsed.toString();
-  } catch {
-    return url;
-  }
-}
-
 function preferredProvider() {
   return config?.defaults?.provider === "grok" ? "grok" : "chatgpt";
 }
@@ -491,7 +461,7 @@ function providerName() {
 
 function cookieOrigins() {
   const providerOrigins = preferredProvider() === "grok" ? GROK_COOKIE_ORIGINS : CHATGPT_COOKIE_ORIGINS;
-  return Array.from(new Set([stripQuery(providerChatUrl()), ...providerOrigins]));
+  return Array.from(new Set([stripUrlQueryAndHash(providerChatUrl()), ...providerOrigins]));
 }
 
 function cookieSource() {

package/extensions/oracle/worker/run-job.mjs

@@ -19,6 +19,7 @@ import {
 } from "../shared/job-coordination-helpers.mjs";
 import { applyOracleJobCleanupWarnings, clearOracleJobCleanupState, transitionOracleJobPhase } from "../shared/job-lifecycle-helpers.mjs";
 import { spawnDetachedNodeProcess, terminateTrackedProcess } from "../shared/process-helpers.mjs";
+import { getOracleJobsDir } from "../shared/state-path-helpers.mjs";
 import { extractArtifactLabels, FILE_LABEL_PATTERN_SOURCE, GENERIC_ARTIFACT_LABELS, parseSnapshotEntries, partitionStructuralArtifactCandidates } from "./artifact-heuristics.mjs";
 import {
   buildAllowedChatGptOrigins,
@@ -39,7 +40,8 @@ import {
   autoSwitchToThinkingSelectionVisible,
   stripChatGptResponseChrome,
 } from "./chatgpt-ui-helpers.mjs";
-import { assistantSnapshotSlice, nextStableValueState, providerSendAccepted, resolveStableConversationUrlCandidate, stripUrlQueryAndHash } from "./chatgpt-flow-helpers.mjs";
+import { assistantSnapshotSlice, conversationIdFromUrl, nextStableValueState, providerSendAccepted, resolveStableConversationUrlCandidate, stripUrlQueryAndHash } from "./chatgpt-flow-helpers.mjs";
+import { normalizeLoginProbeResult } from "./auth-flow-helpers.mjs";
 import { assertNotKnownBrowserUserDataPath, scrubSweetCookieSafeStoragePasswordEnv, sweetCookieSafeStoragePasswordScrubbedEnv } from "../shared/browser-profile-helpers.mjs";
 import { createLease, listLeaseMetadata, readLeaseMetadata, releaseLease, withLock } from "./state-locks.mjs";
 
@@ -49,9 +51,7 @@ if (!jobId) {
   process.exit(1);
 }
 
-const DEFAULT_ORACLE_JOBS_DIR = "/tmp";
-const ORACLE_JOBS_DIR = process.env.PI_ORACLE_JOBS_DIR?.trim() || DEFAULT_ORACLE_JOBS_DIR;
-const jobDir = join(ORACLE_JOBS_DIR, `oracle-${jobId}`);
+const jobDir = join(getOracleJobsDir(), `oracle-${jobId}`);
 const jobPath = `${jobDir}/job.json`;
 const CHATGPT_LABELS = {
   composer: "Chat with ChatGPT",
@@ -294,17 +294,6 @@ async function cpSupportsApfsClone() {
   return cpSupportsApfsCloneFlag;
 }
 
-function parseConversationId(chatUrl) {
-  if (!chatUrl) return undefined;
-  try {
-    const parsed = new URL(chatUrl);
-    const match = parsed.pathname.match(/\/(?:c|chat)\/([^/?#]+)/i);
-    return match?.[1];
-  } catch {
-    return undefined;
-  }
-}
-
 async function removeChromiumProcessSingletonArtifacts(profileDir) {
   await Promise.all([
     rm(join(profileDir, "SingletonLock"), { force: true }),
@@ -763,21 +752,7 @@ async function evalPage(job, script) {
 }
 
 async function loginProbe(job) {
-  const result = await evalPage(job, buildLoginProbeScript(5_000));
-  if (!result || typeof result !== "object") {
-    return { ok: false, status: 0, error: "invalid-probe-result" };
-  }
-  return {
-    ok: result.ok === true,
-    status: typeof result.status === "number" ? result.status : 0,
-    pageUrl: typeof result.pageUrl === "string" ? result.pageUrl : undefined,
-    domLoginCta: result.domLoginCta === true,
-    onAuthPage: result.onAuthPage === true,
-    error: typeof result.error === "string" ? result.error : undefined,
-    bodyKeys: Array.isArray(result.bodyKeys) ? result.bodyKeys : [],
-    bodyHasId: result.bodyHasId === true,
-    bodyHasEmail: result.bodyHasEmail === true,
-  };
+  return normalizeLoginProbeResult(await evalPage(job, buildLoginProbeScript(5_000)));
 }
 
 async function currentUrl(job) {
@@ -785,10 +760,6 @@ async function currentUrl(job) {
   return stdout;
 }
 
-function stripQuery(url) {
-  return stripUrlQueryAndHash(url);
-}
-
 async function snapshotText(job) {
   const { stdout } = await agentBrowser(job, "snapshot", "-i");
   return stdout;
@@ -1829,7 +1800,7 @@ async function waitForStableChatUrl(job, previousChatUrl) {
     await sleep(1000);
   }
 
-  return previousChatUrl || stripQuery(await currentUrl(job));
+  return previousChatUrl || stripUrlQueryAndHash(await currentUrl(job));
 }
 
 async function waitForChatCompletion(job, baselineAssistantCount) {
@@ -2198,7 +2169,7 @@ async function waitForStableArtifactCandidates(job, responseIndex, responseText
 }
 
 async function reopenConversationForArtifacts(job, responseIndex, responseText, reason) {
-  const targetUrl = job.chatUrl || stripQuery(await currentUrl(job));
+  const targetUrl = job.chatUrl || stripUrlQueryAndHash(await currentUrl(job));
   await log(`Reopening conversation before artifact capture (${reason}): ${targetUrl}`);
   await agentBrowser(job, "open", targetUrl);
   await agentBrowser(job, "wait", "1500");
@@ -2397,9 +2368,9 @@ async function run() {
     await sleep(POST_SEND_SETTLE_MS);
 
     const observedChatUrl = isGrokJob(currentJob)
-      ? stripQuery(await currentUrl(currentJob))
+      ? stripUrlQueryAndHash(await currentUrl(currentJob))
       : await waitForStableChatUrl(currentJob, currentJob.chatUrl);
-    const observedConversationId = parseConversationId(observedChatUrl) || currentJob.conversationId;
+    const observedConversationId = conversationIdFromUrl(observedChatUrl) || currentJob.conversationId;
     const awaitingResponsePatch = {
       heartbeatAt: new Date().toISOString(),
       ...(observedConversationId ? { chatUrl: observedChatUrl, conversationId: observedConversationId } : {}),
@@ -2414,7 +2385,7 @@ async function run() {
     const completion = await waitForChatCompletion(currentJob, baselineAssistantCount);
     if (isGrokJob(currentJob) && !currentJob.conversationId) {
       const stableGrokChatUrl = await waitForStableChatUrl(currentJob, undefined);
-      const stableGrokConversationId = parseConversationId(stableGrokChatUrl);
+      const stableGrokConversationId = conversationIdFromUrl(stableGrokChatUrl);
       if (!stableGrokConversationId) {
         throw new Error(`Grok response completed but the conversation URL did not stabilize; current URL: ${stableGrokChatUrl || "(unknown)"}`);
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-oracle",
-  "version": "0.7.15",
+  "version": "0.7.17",
   "description": "ChatGPT and Grok web-oracle extension for pi with isolated browser auth, async jobs, and project-context archives.",
   "private": false,
   "license": "MIT",
@@ -42,10 +42,13 @@
   "pi": {
     "extensions": [
       "./extensions/oracle/index.ts"
+    ],
+    "prompts": [
+      "./prompts"
     ]
   },
   "scripts": {
-    "check:oracle-extension": "node --check extensions/oracle/shared/browser-profile-helpers.mjs && node --check extensions/oracle/shared/process-helpers.mjs && node --check extensions/oracle/shared/state-coordination-helpers.mjs && node --check extensions/oracle/shared/job-coordination-helpers.mjs && node --check extensions/oracle/shared/job-lifecycle-helpers.mjs && node --check extensions/oracle/shared/job-observability-helpers.mjs && node --check extensions/oracle/worker/run-job.mjs && node --check extensions/oracle/worker/state-locks.mjs && node --check extensions/oracle/worker/artifact-heuristics.mjs && node --check extensions/oracle/worker/chatgpt-ui-helpers.mjs && node --check extensions/oracle/worker/chatgpt-flow-helpers.mjs && node --check extensions/oracle/worker/auth-flow-helpers.mjs && node --check extensions/oracle/worker/auth-cookie-policy.mjs && node --check extensions/oracle/worker/chromium-cookie-source.mjs && node --check extensions/oracle/worker/auth-bootstrap.mjs && esbuild extensions/oracle/index.ts --bundle --platform=node --format=esm --external:@earendil-works/pi-coding-agent --external:typebox --outfile=/tmp/pi-oracle-extension-check.js",
+    "check:oracle-extension": "node --check extensions/oracle/shared/browser-profile-helpers.mjs && node --check extensions/oracle/shared/process-helpers.mjs && node --check extensions/oracle/shared/state-path-helpers.mjs && node --check extensions/oracle/shared/time-helpers.mjs && node --check extensions/oracle/shared/state-coordination-helpers.mjs && node --check extensions/oracle/shared/job-coordination-helpers.mjs && node --check extensions/oracle/shared/job-lifecycle-helpers.mjs && node --check extensions/oracle/shared/job-observability-helpers.mjs && node --check extensions/oracle/worker/run-job.mjs && node --check extensions/oracle/worker/state-locks.mjs && node --check extensions/oracle/worker/artifact-heuristics.mjs && node --check extensions/oracle/worker/chatgpt-ui-helpers.mjs && node --check extensions/oracle/worker/chatgpt-flow-helpers.mjs && node --check extensions/oracle/worker/auth-flow-helpers.mjs && node --check extensions/oracle/worker/auth-cookie-policy.mjs && node --check extensions/oracle/worker/chromium-cookie-source.mjs && node --check extensions/oracle/worker/auth-bootstrap.mjs && esbuild extensions/oracle/index.ts --bundle --platform=node --format=esm --external:@earendil-works/pi-coding-agent --external:typebox --outfile=/tmp/pi-oracle-extension-check.js",
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "typecheck:worker-helpers": "tsc --noEmit -p tsconfig.worker-helpers.json",
     "sanity:oracle": "node scripts/oracle-sanity-runner.mjs",
@@ -63,7 +66,7 @@
     "smoke:real": "npm run smoke:real:packed",
     "smoke:real:doctor": "node scripts/oracle-real-smoke.mjs doctor",
     "release:check": "npm run verify:oracle && npm run release:proof:chatgpt-presets && npm run smoke:platform:all",
-    "check:oracle-real-smoke": "node --check scripts/oracle-real-smoke.mjs",
+    "check:oracle-real-smoke": "node --check scripts/oracle-real-smoke.mjs && node --check scripts/oracle-sanity-runner.mjs",
     "check:oracle-release-proof": "node --check scripts/oracle-chatgpt-preset-proof.mjs",
     "release:proof:chatgpt-presets": "node scripts/oracle-chatgpt-preset-proof.mjs check",
     "smoke:real:packed": "node scripts/oracle-real-smoke.mjs run --mode packed",
@@ -83,8 +86,8 @@
     "protobufjs": "7.6.1"
   },
   "devDependencies": {
-    "@earendil-works/pi-ai": "^0.80.1",
-    "@earendil-works/pi-coding-agent": "^0.80.1",
+    "@earendil-works/pi-ai": "^0.80.2",
+    "@earendil-works/pi-coding-agent": "^0.80.2",
     "@types/node": "^22.19.19",
     "esbuild": "^0.28.0",
     "tsx": "^4.22.3",

package/prompts/oracle-followup.md

@@ -1,10 +1,17 @@
 ---
 description: Continue an earlier oracle job in the same provider thread
+argument-hint: <job-id> <request>
 ---
 You are preparing an `/oracle-followup` job.
 
 Do not answer the user's request directly yet.
 
+Hard requirements:
+- Do not plan instead of submitting. The point of `/oracle-followup` is dispatch.
+- Do not claim preflight, auth, archive prep, or submission happened unless the matching tool call actually happened in this turn.
+- If a required tool call is unavailable or fails, stop and report that exact blocker instead of fabricating progress.
+- After a successful or queued `oracle_submit`, your final answer must be only a terse dispatch summary with the job id and response path. Do not ask questions, offer to watch/poll/read, list next steps, or continue working.
+
 Required workflow:
 1. Parse the user request as `<job-id> <follow-up request>`.
 2. If the request does not include both a prior oracle job id and a follow-up request, stop and report: `Usage: /oracle-followup <job-id> <request>. Find the job id in the earlier oracle response or via /oracle-status.`
@@ -13,7 +20,7 @@ Required workflow:
 5. If `oracle_preflight` reports `ready: false`, stop before any expensive prep. Do not read files, search the codebase, prepare archive inputs, or call `oracle_auth` automatically. Report the blocking issue plus the suggested next step.
 6. Treat the parsed job id as `followUpJobId` for `oracle_submit`.
 7. Understand whether the follow-up request is explicitly narrow or genuinely broad.
-8. Gather enough repo context to choose archive inputs and write a strong oracle prompt. Bias toward context-rich submissions when they fit within the provider archive ceiling: 250 MB for ChatGPT, 200 MiB for Grok.
+8. Gather enough repo context to choose archive inputs and write a strong oracle prompt. Bias toward context-rich submissions when they fit within the provider archive ceiling: 250 MiB for ChatGPT, 200 MiB for Grok.
 9. If the follow-up request is explicit and narrow, start from the directly relevant area but still include nearby files, tests, docs, configs, and adjacent modules when they may improve answer quality. Keep the archive tightly minimal only when the user explicitly asks for that, privacy/sensitivity requires it, or size pressure forces it.
 10. If the follow-up request is broad, architectural, release-oriented, or otherwise repo-wide, gather broader context and usually archive `.`.
 11. Choose archive inputs for the follow-up oracle job.
@@ -34,7 +41,7 @@ Rules:
 - If the immediately preceding oracle run for this follow-up failed because ChatGPT/Grok login is required, the worker said to rerun `/oracle-auth`, or stale auth clearly blocked execution, stop and tell the user to run `/oracle-auth` (or `/oracle-auth grok` for Grok). Do not call `oracle_auth` automatically from `/oracle-followup`.
 - This prompt exists so normal users can continue the same provider thread without manually constructing `followUpJobId` tool calls.
 - Always include an archive. Do not submit without context files.
-- By default, prefer context-rich archives up to the provider ceiling because more relevant context is usually better than less. The ceiling is 250 MB for ChatGPT and 200 MiB for Grok. For broad or unclear follow-up requests, include the whole repository by passing `.`. Default archive exclusions apply automatically, including common bulky outputs and obvious credentials/private data like `.env` files, key material, credential dotfiles, local database files, and nested `secrets/` directories anywhere in the repo.
+- By default, prefer context-rich archives up to the provider ceiling because more relevant context is usually better than less. The ceiling is 250 MiB for ChatGPT and 200 MiB for Grok. For broad or unclear follow-up requests, include the whole repository by passing `.`. Default archive exclusions apply automatically, including common bulky outputs and obvious credentials/private data like `.env` files, key material, credential dotfiles, local database files, and nested `secrets/` directories anywhere in the repo.
 - Only limit file selection if the user explicitly requests a tight archive, if privacy/sensitivity requires it, or if the archive would otherwise exceed the size limit after exclusions/pruning.
 - For targeted follow-ups, still include directly related surrounding files, tests, docs, configs, and adjacent modules when they may improve answer quality. Do not default to a one-file archive just because the user mentioned one file, one function, or one stack trace.
 - Do not keep exploring once you already have enough context to submit well.

package/prompts/oracle.md

@@ -1,5 +1,6 @@
 ---
 description: Prepare and dispatch a ChatGPT or Grok web oracle job
+argument-hint: <request>
 ---
 You are preparing an /oracle job.
 
@@ -16,7 +17,7 @@ Required workflow:
 1. Call `oracle_preflight` immediately. If the user says to use Grok, pass `provider: "grok"` to `oracle_preflight`. If the user says to use ChatGPT, pass `provider: "chatgpt"`. If the user says to use ChatGPT Instant, pass `provider: "chatgpt"` and later call `oracle_submit` with `preset: "instant"`. If the user explicitly provides an existing ChatGPT conversation id or `https://chatgpt.com/c/...` URL, pass it as `chatGptConversationId` to `oracle_preflight` and force `provider: "chatgpt"`. Omit `chatGptConversationId` unless the user explicitly asks to continue an existing browser-created ChatGPT thread.
 2. If `oracle_preflight` reports `ready: false`, stop before any expensive prep. Do not read files, search the codebase, prepare archive inputs, or call `oracle_auth` automatically. Report the blocking issue plus the suggested next step.
 3. Understand the request and decide whether it is explicitly narrow or genuinely broad.
-4. Gather enough repo context to choose archive inputs and write a strong oracle prompt. Bias toward context-rich submissions when they fit within the provider archive ceiling: 250 MB for ChatGPT, 200 MiB for Grok.
+4. Gather enough repo context to choose archive inputs and write a strong oracle prompt. Bias toward context-rich submissions when they fit within the provider archive ceiling: 250 MiB for ChatGPT, 200 MiB for Grok.
 5. If the user scope is explicit and narrow, start from the directly relevant area but still include nearby files, tests, docs, configs, and adjacent modules when they may improve answer quality. Keep the archive tightly minimal only when the user explicitly asks for that, privacy/sensitivity requires it, or size pressure forces it.
 6. If the request is broad, architectural, release-oriented, or otherwise repo-wide, gather broader context and usually archive `.`.
 7. Choose archive inputs for the oracle job.
@@ -39,7 +40,7 @@ Rules:
 - Use `oracle_preflight` before any expensive `/oracle` preparation so missing persisted-session or local auth/config blockers fail fast.
 - If ChatGPT/Grok login is required, the worker said to rerun `/oracle-auth`, or stale auth clearly blocked execution, stop and tell the user to run `/oracle-auth` (or `/oracle-auth grok` for Grok). Do not call `oracle_auth` automatically from `/oracle`.
 - Always include an archive. Do not submit without context files.
-- By default, prefer context-rich archives up to the provider ceiling because more relevant context is usually better than less. The ceiling is 250 MB for ChatGPT and 200 MiB for Grok. For broad or unclear requests, include the whole repository by passing `.`. Default archive exclusions apply automatically, including common bulky outputs and obvious credentials/private data like `.env` files, key material, credential dotfiles, local database files, and nested `secrets/` directories anywhere in the repo.
+- By default, prefer context-rich archives up to the provider ceiling because more relevant context is usually better than less. The ceiling is 250 MiB for ChatGPT and 200 MiB for Grok. For broad or unclear requests, include the whole repository by passing `.`. Default archive exclusions apply automatically, including common bulky outputs and obvious credentials/private data like `.env` files, key material, credential dotfiles, local database files, and nested `secrets/` directories anywhere in the repo.
 - Only limit file selection if the user explicitly requests a tight archive, if privacy/sensitivity requires it, or if the archive would otherwise exceed the size limit after exclusions/pruning.
 - For targeted asks, still include directly related surrounding files, tests, docs, configs, and adjacent modules when they may improve answer quality. Do not default to a one-file archive just because the user mentioned one file, one function, or one stack trace.
 - Do not keep exploring once you already have enough context to submit well.

package/scripts/oracle-real-smoke.mjs

@@ -61,6 +61,12 @@ function truthy(value) {
   return ["1", "true", "yes", "on"].includes(String(value ?? "").toLowerCase());
 }
 
+function positiveTimeoutMs(value, label) {
+  const timeoutMs = Number(value ?? DEFAULT_TIMEOUT_MS);
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) throw new Error(`${label} must be a finite positive millisecond value`);
+  return timeoutMs;
+}
+
 function commandExists(command, args = ["--version"]) {
   return new Promise((resolvePromise) => {
     const child = spawn(command, args, { stdio: "ignore", shell: process.platform === "win32" });
@@ -130,7 +136,7 @@ async function doctor() {
 }
 
 function runCommand(command, args, options) {
-  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const timeoutMs = positiveTimeoutMs(options.timeoutMs, "command timeout");
   return new Promise((resolvePromise) => {
     const child = spawn(command, args, {
       cwd: options.cwd,
@@ -375,7 +381,7 @@ async function runPiAgent({ prepared, agentDir, sessionDir, jobsDir, prompt, out
 async function run(mode = "packed") {
   const provider = env("PI_ORACLE_REAL_TEST_PROVIDER") ?? DEFAULT_PROVIDER;
   const model = env("PI_ORACLE_REAL_TEST_MODEL") ?? DEFAULT_MODEL;
-  const timeoutMs = Number(env("PI_ORACLE_REAL_TEST_TIMEOUT_MS") ?? DEFAULT_TIMEOUT_MS);
+  const timeoutMs = positiveTimeoutMs(env("PI_ORACLE_REAL_TEST_TIMEOUT_MS"), "PI_ORACLE_REAL_TEST_TIMEOUT_MS");
   const artifactRoot = resolve(env("PI_ORACLE_REAL_TEST_ARTIFACT_ROOT") ?? ".artifacts/real-smoke");
   const runId = `run-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
   const runDir = join(artifactRoot, runId);