pi-oracle 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 0.5.0 - 2026-04-12
+
+### Added
+- `oracle_preflight`, a lightweight readiness tool that lets `/oracle` fail fast on missing persisted-session or local auth/config blockers before archive/context work begins
+
+### Changed
+- `/oracle` now follows a stricter preflight-first flow, biases toward minimal context gathering for explicitly narrow requests, and prefers the configured default model unless a different preset is clearly needed
+- `oracle_read`, `/oracle-status`, and wake-up messaging now keep the true terminal event prominent, separate wake-up bookkeeping from failure state, and stop implying that a missing `response.md` is ready
+- `/oracle-auth` failure guidance now reports the effective agent config path for the active agent dir and explains when a project config was also read but could not override `auth.*`
+- `/oracle-clean` now documents the short post-send retention grace window and returns a retry-after timestamp when a terminal job is still intentionally retained
+
+### Fixed
+- `oracle_submit` now rejects locally knowable auth-seed blockers before archive creation or job persistence while still preserving direct archive-input validation errors like symlink escapes
+- oracle tool results now use consistent structured `details.job` / `details.error` payloads and preserve `isError` for structured failures through the tool-result hook
+- `/oracle` no-session and missing-seed flows now stop before unnecessary repo exploration, and narrow prompt-template runs dispatch more quickly with smaller archives when the user scope is explicit
+- repeated oracle sanity runs now quiesce background pollers before isolated-state teardown so release verification no longer emits a noisy temp-lock ENOENT race
+
 ## 0.4.0 - 2026-04-12
 
 ### Added

package/README.md

@@ -42,12 +42,17 @@ pi install https://github.com/fitchmultz/pi-oracle
 
 ## Quickstart
 
-1. Make sure ChatGPT already works in your local Chrome profile.
-2. Make sure these are installed: Google Chrome, `agent-browser`, `tar`, and `zstd`.
-3. Optional: create `~/.pi/agent/extensions/oracle.json` if you want non-default settings.
-4. Run `/oracle-auth`.
-5. Run `/oracle Review the current pending changes. Include the whole repo unless a narrower archive is clearly better.`
-6. Wait for a best-effort wake-up, or check `/oracle-status`.
+1. Start a normal persisted `pi` session. Do not use `pi --no-session` for oracle.
+2. Make sure ChatGPT already works in your local Chrome profile.
+3. Make sure these are installed: Google Chrome, `agent-browser`, `tar`, and `zstd`.
+4. Optional: create `~/.pi/agent/extensions/oracle.json` if you want non-default settings.
+5. Run `/oracle-auth`.
+6. Run `/oracle Review the current pending changes. Include the whole repo unless a narrower archive is clearly better.`
+7. Wait for a best-effort wake-up, or check `/oracle-status`.
+
+The `/oracle` prompt now runs an early oracle preflight before it gathers repo context, so missing persisted-session or local auth/config blockers fail before the agent spends time reading files.
+
+For explicitly narrow requests, `/oracle` should gather only minimal context and prefer a minimal archive instead of broad repo exploration. It should also omit `preset` and use the configured default model unless the task clearly needs a different one.
 
 If you miss the wake-up, the result is still saved durably in the oracle job directory and can be read later.
 
@@ -61,11 +66,15 @@ If you miss the wake-up, the result is still saved durably in the oracle job dir
 /oracle Read the codebase and explain the highest-risk auth/session failure modes, including what to test before shipping.
 ```
 
+```text
+/oracle Explain the README guidance for /oracle-clean retention grace. Only archive README.md unless another file is clearly necessary.
+```
+
 ## High-level flow
 
 ```mermaid
 flowchart LR
-    A["/oracle request"] --> B["Agent gathers repo context"]
+    A["/oracle request"] --> B["Agent preflights, then gathers only the needed repo context"]
     B --> C["oracle_submit builds archive"]
     C --> D["Detached worker starts isolated ChatGPT runtime"]
     D --> E["Archive + prompt sent to ChatGPT.com"]
@@ -82,9 +91,10 @@ User-facing commands:
 - `/oracle-auth` — sync ChatGPT cookies from your real Chrome profile into the isolated oracle auth profile
 - `/oracle-status [job-id]` — inspect job status
 - `/oracle-cancel [job-id]` — cancel queued or active job
-- `/oracle-clean <job-id|all>` — remove temp files for terminal jobs
+- `/oracle-clean <job-id|all>` — remove temp files for terminal jobs; recently woken terminal jobs may stay retained briefly and return a retry-after hint
 
 Agent-facing tools:
+- `oracle_preflight`
 - `oracle_submit`
 - `oracle_read`
 - `oracle_cancel`
@@ -143,6 +153,7 @@ Project config should only override safe, non-privileged settings.
 - Jobs can queue automatically if runtime capacity is full.
 - Completion delivery into `pi` is best-effort wake-up based.
 - If you miss the wake-up, use `oracle_read(jobId)` or `/oracle-status`.
+- `/oracle-clean` can still refuse a terminal job briefly after a wake-up send so saved response/artifact paths survive the follow-up turn; when that guard applies, it returns the next eligible cleanup time.
 
 ## Requirements
 
@@ -177,6 +188,12 @@ Project config should only override safe, non-privileged settings.
 - Use `/oracle-status [job-id]` or `oracle_read(jobId)`.
 - Results are still saved on disk even if the reminder turn does not land.
 
+### `/oracle-clean` refuses a terminal job right after completion
+
+- This can happen during the short post-send retention grace window after a wake-up was sent.
+- The command now returns a `Retry after ...` timestamp when that guard is active.
+- Wait until that time, then rerun `/oracle-clean [job-id|all]`.
+
 ### `agent-browser`, `tar`, or `zstd` is missing
 
 - Install the missing local dependency and rerun the command.

package/docs/ORACLE_DESIGN.md

@@ -79,6 +79,9 @@ The extension now follows the current `pi` session lifecycle model:
 
 ### Tools
 
+- `oracle_preflight`
+  - lightweight agent-facing readiness check for persisted-session and local oracle prerequisites
+  - intended to run before expensive `/oracle` context gathering
 - `oracle_submit`
   - low-level agent-facing dispatch tool
   - creates archive and launches a detached worker
@@ -97,12 +100,15 @@ It expands through the prompt-template path so pi can apply its native queueing
 
 Instead it instructs the agent to:
 
-1. understand the task
-2. gather repo context
-3. choose exact archive inputs
-4. craft the oracle prompt
-5. call `oracle_submit`
-6. stop and wait for the completion wake-up (best-effort; durable oracle response/artifact state is already persisted outside session history)
+1. call `oracle_preflight` immediately
+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. gather only the smallest repo context needed to submit well
+5. if the request is narrow, prefer a minimal targeted archive and dispatch as soon as enough context is in hand
+6. if the request is broad/repo-wide, gather broader context and usually archive `.`
+7. craft the oracle prompt
+8. call `oracle_submit`
+9. stop and wait for the completion wake-up (best-effort; durable oracle response/artifact state is already persisted outside session history)
 
 ### `/oracle-auth`
 
@@ -133,7 +139,7 @@ The authenticated seed profile remains the source of truth for future oracle run
 
 ### `oracle_submit`
 
-Agent-facing submissions use **`preset`**; the canonical registry is `ORACLE_SUBMIT_PRESETS` in `extensions/oracle/lib/config.ts`. **`preset` is the only model-selection parameter** on `oracle_submit`. There are no `modelFamily`, `effort`, or `autoSwitchToThinking` fields. Submit-time inputs accept canonical preset ids plus matching human-readable labels/common hyphen-space variants, and the tool normalizes them back to the canonical id before persisting job state.
+Agent-facing submissions use **`preset`**; the canonical registry is `ORACLE_SUBMIT_PRESETS` in `extensions/oracle/lib/config.ts`. **`preset` is the only model-selection parameter** on `oracle_submit`. There are no `modelFamily`, `effort`, or `autoSwitchToThinking` fields. Submit-time inputs accept canonical preset ids plus matching human-readable labels/common hyphen-space variants, and the tool normalizes them back to the canonical id before persisting job state. Prompt-template guidance biases toward omitting `preset` and using the configured default unless the task clearly needs a different model or the user explicitly asked for one.
 
 1. resolve the preset (submit-time or config default) into an execution snapshot
 2. resolve optional `followUpJobId` into a prior `chatUrl` and `conversationId`
@@ -262,7 +268,7 @@ Long-run hygiene is intentionally conservative:
 
 - runtime profiles, runtime leases, and conversation leases are cleaned immediately as part of worker/command cleanup paths
 - browser close is time-bounded so cleanup can continue even if `agent-browser close` wedges
-- `/oracle-clean` performs runtime cleanup before removing the persisted job directory, but refuses terminal jobs whose worker is still live or whose wake-up was just sent inside a short post-send retention grace window
+- `/oracle-clean` performs runtime cleanup before removing the persisted job directory, but refuses terminal jobs whose worker is still live or whose wake-up was just sent inside a short post-send retention grace window; when blocked by that grace it returns a retry-after timestamp
 - stale lock directories are swept before reconcile maintenance
 - old auth `.staging-*` profiles are swept during `/oracle-auth` startup when the auth browser session is not still active
 - terminal job directories are retained for inspection, then pruned later based on configurable retention windows

package/docs/ORACLE_ISOLATED_PI_VALIDATION.md

@@ -29,6 +29,17 @@ pi --no-extensions -e "$REPO/extensions/oracle/index.ts"
 
 That ensures the session is exercising the in-repo code, not a globally installed package.
 
+If you also need the in-repo `/oracle` prompt template, load it explicitly instead of installing this repository as a project-local package:
+
+```bash
+pi --no-extensions -e "$REPO/extensions/oracle/index.ts" \
+  --no-prompt-templates --prompt-template "$REPO/prompts/oracle.md"
+```
+
+Do not add `https://github.com/fitchmultz/pi-oracle` to this repository's `.pi/settings.json` just to test local oracle changes. If you already keep `npm:pi-oracle` installed globally, mixing the global npm package with a project-local git package creates two distinct package identities and can trigger prompt/tool conflicts. Use the explicit CLI resource flags above instead.
+
+`oracle_submit` now preflights a missing or unreadable auth seed profile before it creates an archive or persists a job. For archive-inspection smoke tests that intentionally run without real auth, create an empty isolated seed-profile directory under the temporary agent dir so submission can proceed far enough to write the archive while still staying isolated from your normal Chrome state.
+
 ## Preset requirement
 
 Use either:
@@ -70,6 +81,8 @@ mkdir -p \
   "$TEST2_AGENT" "$TEST2_SESSIONS" "$TEST2_JOBS" \
   "$FIXTURE" "$OUTSIDE"
 
+mkdir -p "$TEST1_AGENT/extensions/oracle-auth-seed-profile"
+
 echo 'secret' > "$OUTSIDE/secret.txt"
 ln -s "$OUTSIDE" "$FIXTURE/linked-outside"
 
@@ -149,7 +162,8 @@ Expected behavior:
 Notes:
 
 - this smoke test does not require `/oracle-auth`
-- without an auth seed profile, the worker fails after archive creation, which is useful because the archive remains on disk for inspection
+- the snippet creates an empty isolated auth seed profile for `TEST1_AGENT` because `oracle_submit` now rejects a missing seed profile before archiving
+- with that empty seed profile, the worker still fails later due to missing real auth, which is useful because the archive remains on disk for inspection
 
 ### Test 2: symlink escape rejection
 
@@ -159,6 +173,19 @@ Expected behavior:
 - the error should say the archive input must resolve inside the project cwd without symlink escapes
 - no oracle job directory should be created for the rejected submit
 
+## Testing local `/oracle` prompt changes too
+
+The main smoke test above calls `oracle_submit` directly, so it only needs the local extension entrypoint. If you also changed `prompts/oracle.md`, start the isolated session with the local prompt template explicitly loaded:
+
+```bash
+LOCAL_ORACLE_PI_CMD="pi --session-dir '$TEST1_SESSIONS' --no-extensions -e '$REPO/extensions/oracle/index.ts' --no-prompt-templates --prompt-template '$REPO/prompts/oracle.md'"
+TMUX_CMD1="cd '$REPO' && env PI_CODING_AGENT_DIR='$TEST1_AGENT' PI_ORACLE_JOBS_DIR='$TEST1_JOBS' PATH='$PATH' $LOCAL_ORACLE_PI_CMD"
+```
+
+Use the same pattern for additional sessions, swapping the session/job directories as needed. This keeps the test on the in-repo extension and in-repo prompt template without depending on `.pi/settings.json` package entries.
+
+`/oracle` now starts by calling `oracle_preflight`. If you want the prompt flow to proceed past that early guard in an isolated test without using your normal auth state, create an empty isolated auth seed profile first (for example `mkdir -p "$TEST1_AGENT/extensions/oracle-auth-seed-profile"`) or run `/oracle-auth` in the isolated agent dir.
+
 ## Additional failure-mode smoke tests
 
 ### `/oracle-auth` should fail fast when `agent-browser` hangs

package/extensions/oracle/lib/commands.ts

@@ -4,9 +4,10 @@
 // Usage: Imported by the oracle extension entrypoint to register /oracle-* commands with pi.
 // Invariants/Assumptions: Commands operate on persisted project-scoped jobs and rely on shared observability formatting for detached-state clarity.
 import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
 import type { ExtensionAPI, ExtensionCommandContext } from "@mariozechner/pi-coding-agent";
 import { formatOracleJobSummary } from "../shared/job-observability-helpers.mjs";
-import { loadOracleConfig } from "./config.js";
+import { formatOracleAuthConfigRemediation, formatOracleAuthConfigSummary, getOracleConfigLoadDetails, loadOracleConfig } from "./config.js";
 import {
   cancelOracleJob,
   getJobDir,
@@ -29,9 +30,11 @@ function summarizeJob(jobId: string): string {
   const job = readJob(jobId);
   if (!job) return `Oracle job ${jobId} not found.`;
 
+  const responseAvailable = Boolean(job.responsePath && existsSync(job.responsePath));
   return formatOracleJobSummary(job, {
     queuePosition: job.status === "queued" ? getQueuePosition(job.id) : undefined,
     artifactsPath: `${getJobDir(job.id)}/artifacts`,
+    responseAvailable,
   });
 }
 
@@ -47,6 +50,12 @@ function readScopedJob(jobId: string, cwd: string) {
 
 async function runAuthBootstrap(authWorkerPath: string, cwd: string): Promise<string> {
   const config = loadOracleConfig(cwd);
+  const configLoad = getOracleConfigLoadDetails(cwd);
+  const authConfigGuidance = {
+    ...configLoad,
+    remediation: formatOracleAuthConfigRemediation(configLoad),
+    summary: formatOracleAuthConfigSummary(configLoad),
+  };
   try {
     await withGlobalReconcileLock({ processPid: process.pid, source: "oracle_auth", cwd }, async () => {
       await reconcileStaleOracleJobs();
@@ -57,7 +66,7 @@ async function runAuthBootstrap(authWorkerPath: string, cwd: string): Promise<st
   }
 
   return await new Promise<string>((resolve, reject) => {
-    const child = spawn(process.execPath, [authWorkerPath, JSON.stringify(config)], {
+    const child = spawn(process.execPath, [authWorkerPath, JSON.stringify({ config, configLoad: authConfigGuidance })], {
       cwd,
       stdio: ["ignore", "pipe", "pipe"],
     });
@@ -151,7 +160,7 @@ export function registerOracleCommands(pi: ExtensionAPI, authWorkerPath: string,
   });
 
   pi.registerCommand("oracle-clean", {
-    description: "Remove oracle temp files for a job or all project jobs",
+    description: "Remove oracle temp files for terminal jobs; recently woken jobs may stay retained briefly",
     handler: async (args, ctx: ExtensionCommandContext) => {
       const target = args.trim();
       if (!target) {
@@ -196,10 +205,10 @@ export function registerOracleCommands(pi: ExtensionAPI, authWorkerPath: string,
       }
 
       refreshOracleStatus(ctx);
-      const warningSuffix = cleanupWarnings.length > 0 ? ` Cleanup warnings:\n${cleanupWarnings.join("\n")}` : "";
+      const warningSuffix = cleanupWarnings.length > 0 ? ` Cleanup blockers/warnings:\n${cleanupWarnings.join("\n")}` : "";
       const removalSummary = 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} with cleanup warnings.`;
+        : `Removed ${removedCount} of ${jobs.length} oracle job director${jobs.length === 1 ? "y" : "ies"}; retained ${jobs.length - removedCount} due to cleanup blockers or warnings.`;
       ctx.ui.notify(`${removalSummary}${warningSuffix}`, cleanupWarnings.length > 0 ? "warning" : "info");
     },
   });

package/extensions/oracle/lib/config.ts

@@ -258,6 +258,54 @@ const detectedChromeUserAgent = detectDefaultChromeUserAgent(detectedChromeExecu
 const agentExtensionsDir = join(getAgentDir(), "extensions");
 const detectedChromeProfileName = detectDefaultChromeProfileName();
 
+export interface OracleConfigLoadDetails {
+  agentDir: string;
+  agentConfigPath: string;
+  agentConfigExists: boolean;
+  projectConfigPath: string;
+  projectConfigExists: boolean;
+  effectiveAuthConfigPath: string;
+  effectiveAuthScope: "agent";
+}
+
+export function getOracleConfigLoadDetails(cwd: string): OracleConfigLoadDetails {
+  const agentDir = getAgentDir();
+  const agentConfigPath = join(agentDir, "extensions", "oracle.json");
+  const projectConfigPath = join(cwd, ".pi", "extensions", "oracle.json");
+  return {
+    agentDir,
+    agentConfigPath,
+    agentConfigExists: existsSync(agentConfigPath),
+    projectConfigPath,
+    projectConfigExists: existsSync(projectConfigPath),
+    effectiveAuthConfigPath: agentConfigPath,
+    effectiveAuthScope: "agent",
+  };
+}
+
+export function formatOracleAuthConfigRemediation(details: OracleConfigLoadDetails): string {
+  if (!details.projectConfigExists) {
+    return `Set auth.chromeProfile / auth.chromeCookiePath in ${details.effectiveAuthConfigPath}.`;
+  }
+  return (
+    `Set auth.chromeProfile / auth.chromeCookiePath in ${details.effectiveAuthConfigPath}. ` +
+    `Project overrides are also read from ${details.projectConfigPath}, but auth.* is loaded from ${details.effectiveAuthConfigPath}.`
+  );
+}
+
+export function formatOracleAuthConfigSummary(details: OracleConfigLoadDetails): string {
+  const lines = [
+    `Effective oracle auth config: ${details.effectiveAuthConfigPath} (agent dir: ${details.agentDir}${details.agentConfigExists ? "" : "; create this file to override auth.*"})`,
+  ];
+  if (details.projectConfigExists) {
+    lines.push(
+      `Project oracle config also loaded: ${details.projectConfigPath} ` +
+        `(project scope can override ${[...PROJECT_OVERRIDE_KEYS].join("/")} only; auth.* still comes from ${details.effectiveAuthConfigPath}).`,
+    );
+  }
+  return lines.join("\n");
+}
+
 export const DEFAULT_CONFIG: OracleConfig = {
   defaults: {
     preset: "pro_extended",
@@ -514,7 +562,8 @@ function validateOracleConfig(value: unknown): OracleConfig {
 }
 
 export function loadOracleConfig(cwd: string): OracleConfig {
-  const globalConfig = readJson(join(getAgentDir(), "extensions", "oracle.json"));
-  const projectConfig = filterProjectConfig(readJson(join(cwd, ".pi", "extensions", "oracle.json")));
+  const details = getOracleConfigLoadDetails(cwd);
+  const globalConfig = readJson(details.agentConfigPath);
+  const projectConfig = filterProjectConfig(readJson(details.projectConfigPath));
   return validateOracleConfig(deepMerge(deepMerge(DEFAULT_CONFIG, globalConfig), projectConfig));
 }

package/extensions/oracle/lib/jobs.ts

@@ -285,6 +285,16 @@ function notificationClaimIsLive(job: Pick<OracleJob, "notifyClaimedAt" | "notif
   return now - claimedAtMs < ORACLE_NOTIFICATION_CLAIM_TTL_MS;
 }
 
+function getWakeupRetentionGraceDeadline(job: Pick<OracleJob, "wakeupLastRequestedAt">, now = Date.now()): { retryAt: string; remainingMs: number } | undefined {
+  const lastRequestedAtMs = parseTimestamp(job.wakeupLastRequestedAt);
+  if (lastRequestedAtMs === undefined) return undefined;
+  const retryAtMs = lastRequestedAtMs + ORACLE_WAKEUP_POST_SEND_RETENTION_MS;
+  return {
+    retryAt: new Date(retryAtMs).toISOString(),
+    remainingMs: Math.max(0, retryAtMs - now),
+  };
+}
+
 function wakeupRetentionGraceIsActive(job: Pick<OracleJob, "wakeupLastRequestedAt">, now = Date.now()): boolean {
   const lastRequestedAtMs = parseTimestamp(job.wakeupLastRequestedAt);
   if (lastRequestedAtMs === undefined) return false;
@@ -464,12 +474,17 @@ export async function removeTerminalOracleJob(job: OracleJob): Promise<{ removed
         },
       };
     }
-    if (wakeupRetentionGraceIsActive(current)) {
+    const nowMs = Date.now();
+    if (wakeupRetentionGraceIsActive(current, nowMs)) {
+      const graceDeadline = getWakeupRetentionGraceDeadline(current, nowMs);
+      const retryHint = graceDeadline
+        ? ` Retry after ${graceDeadline.retryAt} (${Math.ceil(graceDeadline.remainingMs / 1000)}s remaining).`
+        : "";
       return {
         removed: false,
         cleanupReport: {
           attempted: [],
-          warnings: [`Refusing to remove terminal oracle job ${current.id} because its wake-up delivery is still within the post-send retention grace window.`],
+          warnings: [`Refusing to remove terminal oracle job ${current.id} because its wake-up delivery is still within the post-send retention grace window.${retryHint}`],
         },
       };
     }

package/extensions/oracle/lib/poller.ts

@@ -3,6 +3,7 @@
 // Scope: Poller/orchestration only; durable lifecycle mutations live in jobs.ts and shared observability formatting lives in extensions/oracle/shared.
 // Usage: Imported by the oracle extension entrypoint to start or stop per-session oracle polling.
 // Invariants/Assumptions: Poller scans are serialized per session key, wake-up delivery is best-effort, and terminal-job notifications always re-read durable job state before send.
+import { existsSync } from "node:fs";
 import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
 import { buildOracleStatusText, buildOracleWakeupNotificationContent } from "../shared/job-observability-helpers.mjs";
 import { isProcessAlive, readProcessStartedAt } from "../shared/process-helpers.mjs";
@@ -154,7 +155,8 @@ function requestWakeupTurn(pi: ExtensionAPI, job: OraclePollerJob): void {
       customType: ORACLE_WAKEUP_REMINDER_CUSTOM_TYPE,
       display: false,
       content: buildOracleWakeupNotificationContent(job, {
-        responsePath: job.responsePath || `${getJobDir(job.id)}/response.md`,
+        responsePath: job.responsePath,
+        responseAvailable: Boolean(job.responsePath && existsSync(job.responsePath)),
         artifactsPath: `${getJobDir(job.id)}/artifacts`,
       }),
       details: { jobId: job.id, status: job.status },
@@ -292,12 +294,33 @@ export function stopPollerForSession(sessionFile: string | undefined, cwd: strin
   if (timer) {
     clearInterval(timer);
     activePollers.delete(sessionKey);
-    scansInFlight.delete(sessionKey);
   }
   const wakeupTargetLeaseKey = getWakeupTargetLeaseKey(sessionKey);
   void releaseLease(WAKEUP_TARGET_LEASE_KIND, wakeupTargetLeaseKey).catch(() => undefined);
 }
 
+export async function stopAllPollers(): Promise<void> {
+  const sessionKeys = [...activePollers.keys()];
+  for (const timer of activePollers.values()) {
+    clearInterval(timer);
+  }
+  activePollers.clear();
+  await Promise.all(sessionKeys.map(async (sessionKey) => {
+    const wakeupTargetLeaseKey = getWakeupTargetLeaseKey(sessionKey);
+    await releaseLease(WAKEUP_TARGET_LEASE_KIND, wakeupTargetLeaseKey).catch(() => undefined);
+  }));
+}
+
+export async function waitForAllPollersToQuiesce(timeoutMs = 2_000): Promise<void> {
+  const startedAt = Date.now();
+  while (scansInFlight.size > 0) {
+    if (Date.now() - startedAt >= timeoutMs) {
+      throw new Error(`Timed out waiting for oracle pollers to quiesce after ${timeoutMs}ms`);
+    }
+    await new Promise((resolve) => setTimeout(resolve, 25));
+  }
+}
+
 export function stopPoller(ctx: ExtensionContext): void {
   const sessionFile = getSessionFile(ctx);
   if (!sessionFile) return;

package/extensions/oracle/lib/runtime.ts

@@ -5,8 +5,8 @@
 // Invariants/Assumptions: Lease metadata is the admission source of truth, tracked worker identity checks defend against PID reuse, and runtime cleanup always attempts lease release.
 import { randomUUID } from "node:crypto";
 import { spawn } from "node:child_process";
-import { existsSync, realpathSync, readFileSync } from "node:fs";
-import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { constants as fsConstants, existsSync, realpathSync, readFileSync } from "node:fs";
+import { access, mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { jobBlocksAdmission } from "../shared/job-coordination-helpers.mjs";
 import { isTrackedProcessAlive } from "../shared/process-helpers.mjs";
@@ -98,6 +98,45 @@ export function authSessionName(config: OracleConfig): string {
   return `${config.browser.sessionPrefix}-auth`;
 }
 
+function missingAuthSeedProfileMessage(seedDir: string): string {
+  return `Oracle auth seed profile not found: ${seedDir}. Run /oracle-auth first.`;
+}
+
+function invalidAuthSeedProfileTypeMessage(seedDir: string): string {
+  return `Oracle auth seed profile is not a directory: ${seedDir}. Remove the invalid path or rerun /oracle-auth.`;
+}
+
+function unreadableAuthSeedProfileMessage(seedDir: string): string {
+  return `Oracle auth seed profile is not readable: ${seedDir}. Fix its permissions or rerun /oracle-auth.`;
+}
+
+export async function assertOracleAuthSeedProfileReady(config: OracleConfig): Promise<void> {
+  const seedDir = config.browser.authSeedProfileDir;
+  let seedStats;
+  try {
+    seedStats = await stat(seedDir);
+  } catch (error) {
+    const code = error && typeof error === "object" && "code" in error ? String(error.code) : "";
+    if (code === "ENOENT") throw new Error(missingAuthSeedProfileMessage(seedDir));
+    if (code === "EACCES" || code === "EPERM") throw new Error(unreadableAuthSeedProfileMessage(seedDir));
+    throw new Error(`Failed to inspect oracle auth seed profile ${seedDir}: ${error instanceof Error ? error.message : String(error)}`);
+  }
+
+  if (!seedStats.isDirectory()) {
+    throw new Error(invalidAuthSeedProfileTypeMessage(seedDir));
+  }
+
+  try {
+    await access(seedDir, fsConstants.R_OK | fsConstants.X_OK);
+  } catch {
+    throw new Error(unreadableAuthSeedProfileMessage(seedDir));
+  }
+}
+
+export async function assertOracleSubmitPrerequisites(config: OracleConfig): Promise<void> {
+  await assertOracleAuthSeedProfileReady(config);
+}
+
 export function getSeedGeneration(config: OracleConfig): string | undefined {
   const path = join(config.browser.authSeedProfileDir, SEED_GENERATION_FILE);
   if (!existsSync(path)) return undefined;
@@ -267,9 +306,7 @@ export async function cloneSeedProfileToRuntime(
   options?: { cpTimeoutMs?: number },
 ): Promise<string | undefined> {
   const seedDir = config.browser.authSeedProfileDir;
-  if (!existsSync(seedDir)) {
-    throw new Error(`Oracle auth seed profile not found: ${seedDir}. Run /oracle-auth first.`);
-  }
+  await assertOracleAuthSeedProfileReady(config);
 
   await withAuthLock({ runtimeProfileDir, seedDir }, async () => {
     await rm(runtimeProfileDir, { recursive: true, force: true }).catch(() => undefined);