pi-oracle 0.7.16 → 0.7.17

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 ## 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

package/README.md

@@ -78,7 +78,7 @@ To update the package later, use `pi update --extensions`, `pi update --all`, or
 You need:
 
 - macOS, Linux, or Windows native
-- Node.js 22 or newer
+- 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
@@ -391,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

@@ -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

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,17 +68,13 @@ 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(pi: ExtensionAPI, ctx: ExtensionCommandContext, message: string, level: "info" | "warning" | "error" = "info"): void {
   if (ctx.mode === "print") {
     process.stdout.write(`${message}\n`);
@@ -100,7 +92,7 @@ function emitCommandOutput(pi: ExtensionAPI, ctx: ExtensionCommandContext, messa
   });
 }
 
-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) => {
@@ -108,7 +100,7 @@ export function registerOracleCommands(pi: ExtensionAPI, authWorkerPath: string,
         const provider = parseOracleAuthProvider(args);
         const providerLabel = provider === "grok" ? "Grok" : provider === "chatgpt" ? "ChatGPT" : "configured provider";
         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: isProjectTrusted(ctx) });
+        const result = await runOracleAuthBootstrap(authWorkerPath, ctx.cwd, provider, { projectConfigTrusted: isOracleProjectTrusted(ctx) });
         emitCommandOutput(pi, ctx, result, "info");
       } catch (error) {
         emitCommandOutput(pi, ctx, error instanceof Error ? error.message : String(error), "warning");

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";
 

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

@@ -17,6 +17,7 @@ import { isLockTimeoutError, withGlobalReconcileLock, withLock } from "./locks.j
 import {
   coerceOracleSubmitPresetId,
   loadOracleConfig,
+  normalizeOracleProvider,
   GROK_MODES,
   ORACLE_PROVIDERS,
   ORACLE_SUBMIT_PRESET_IDS,
@@ -49,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";
@@ -126,15 +128,6 @@ const ORACLE_CANCEL_PARAMS = Type.Object({
 
 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;
@@ -712,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)) {
@@ -743,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) {
@@ -835,9 +824,9 @@ export function registerOracleTools(pi: ExtensionAPI, workerPath: string, authWo
     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: {
@@ -874,7 +863,7 @@ export function registerOracleTools(pi: ExtensionAPI, workerPath: string, authWo
     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);

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.16",
+  "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",
@@ -48,7 +48,7 @@
     ]
   },
   "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",
@@ -66,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",

package/prompts/oracle-followup.md

@@ -6,6 +6,12 @@ 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.`
@@ -14,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.
@@ -35,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

@@ -17,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.
@@ -40,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);