pi-oracle 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## Unreleased
+
+## 0.6.0 - 2026-04-13
+
+### Added
+- `oracle_auth`, an agent-facing tool that mirrors `/oracle-auth` so oracle runs can refresh the shared ChatGPT auth seed profile before a single retry when stale auth blocks execution
+
+### Changed
+- `/oracle` and `/oracle-followup` now follow a stricter preflight-first flow, bias toward context-rich archive selection up to the 250 MB ceiling, and explicitly allow one `oracle_auth` refresh before retrying stale-auth/login-required failures
+- package metadata now follows the current pi package dependency guidance by publishing `@mariozechner/pi-coding-agent` and `@sinclair/typebox` as peer dependencies while keeping local typechecking/dev resolution intact
+
+### Fixed
+- `/oracle` no-session and missing-seed flows now stop before unnecessary repo exploration, and prompt-template guidance keeps relevant surrounding archive context instead of over-optimizing for minimal slices when extra context still fits
+- oracle model selection now recognizes ChatGPT family controls exposed as radios/menu items plus durable closed-chip states like `Extended thinking` and `Extended Pro`, so remembered new-chat defaults no longer derail preset configuration or ready-state detection
+- authenticated ready-state detection now accepts extended closed-chip model controls during auth/bootstrap verification, preventing false login/setup failures when ChatGPT remembers a non-default preset
+
+## 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 still prefer a context-rich relevant archive up to the 250 MB ceiling, including nearby tests, docs, config, and adjacent modules when that can improve answer quality. Reserve tightly minimal archives for an explicit user request for a tight archive, privacy-sensitive material, or size-constrained cases. 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,21 @@ 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. Archive README.md plus any nearby docs or implementation files that help answer accurately.
+```
+
+```text
+/oracle-followup <job-id> Tighten the migration plan around rollback risk, and include the most relevant surrounding files/docs as long as the archive stays comfortably within the limit.
+```
+
+After a job finishes, use `/oracle-followup <job-id> <request>` to continue the same ChatGPT thread without hand-writing the low-level `followUpJobId` tool parameter.
+
 ## High-level flow
 
 ```mermaid
 flowchart LR
-    A["/oracle request"] --> B["Agent gathers repo context"]
+    A["/oracle request"] --> B["Agent preflights, then gathers a context-rich relevant repo slice"]
     B --> C["oracle_submit builds archive"]
     C --> D["Detached worker starts isolated ChatGPT runtime"]
     D --> E["Archive + prompt sent to ChatGPT.com"]
@@ -79,12 +94,16 @@ If concurrency is full, the job is queued and starts automatically later.
 
 User-facing commands:
 - `/oracle <request>` — prompt template that tells the agent to gather context and dispatch an oracle job
+- `/oracle-followup <job-id> <request>` — prompt template that continues an earlier oracle job in the same ChatGPT thread
 - `/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-read [job-id]` — inspect job status plus the saved response preview
+- `/oracle-status [job-id]` — inspect job status and list recent job ids when no explicit id is given
+- `/oracle-cancel <job-id>` — cancel a queued or active job by id
+- `/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_auth`
 - `oracle_submit`
 - `oracle_read`
 - `oracle_cancel`
@@ -142,7 +161,11 @@ Project config should only override safe, non-privileged settings.
 - Jobs persist their response and any artifacts under `${PI_ORACLE_JOBS_DIR:-/tmp}/oracle-<job-id>/` by default.
 - 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`.
+- If you miss the wake-up, use `/oracle-read [job-id]` to inspect the saved response preview.
+- `/oracle-status [job-id]` still shows saved job metadata and lists recent job ids when you omit the id.
+- Agent callers can use `oracle_read({ jobId })`.
+- If a prior oracle run failed because ChatGPT login was required or the worker explicitly said to rerun `/oracle-auth`, agent callers can run `oracle_auth({})` once and then retry the submission once.
+- `/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
 
@@ -174,9 +197,17 @@ Project config should only override safe, non-privileged settings.
 
 ### A job finished but no wake-up arrived
 
-- Use `/oracle-status [job-id]` or `oracle_read(jobId)`.
+- Use `/oracle-read [job-id]` to inspect the saved response preview.
+- Use `/oracle-status [job-id]` when you want status metadata or need help finding a job id.
+- Agent callers can use `oracle_read({ jobId })` if they need tool output in the current turn.
 - 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

@@ -65,20 +65,31 @@ The extension now follows the current `pi` session lifecycle model:
   - implemented as a prompt template, not an extension command
   - asks the agent to gather context and dispatch an oracle job
   - intentionally uses native pi prompt/template queueing so submissions survive streaming and compaction
+- `/oracle-followup <job-id> <request>`
+  - implemented as a prompt template, not an extension command
+  - asks the agent to continue an earlier oracle job in the same ChatGPT thread via `followUpJobId`
+  - keeps same-thread continuation available to normal users without requiring raw tool-call syntax
 
 ### Commands
 
 - `/oracle-auth`
   - syncs ChatGPT cookies from the user’s real Chrome into the isolated oracle profile and verifies them there
+- `/oracle-read [job-id]`
+  - shows job status plus the saved response preview
 - `/oracle-status [job-id]`
-  - shows job status
-- `/oracle-cancel [job-id]`
-  - cancels a queued or active job
+  - shows job status and lists recent job ids when the caller omits an explicit id
+- `/oracle-cancel <job-id>`
+  - cancels a queued or active job by id; does not guess a default target
 - `/oracle-clean <job-id|all>`
   - removes temp files for terminal jobs only
 
 ### Tools
 
+- `oracle_preflight`
+  - lightweight agent-facing readiness check for persisted-session and local oracle prerequisites
+  - intended to run before expensive `/oracle` context gathering
+- `oracle_auth`
+  - agent-facing auth refresh tool that mirrors `/oracle-auth` for stale-auth recovery before a retry
 - `oracle_submit`
   - low-level agent-facing dispatch tool
   - creates archive and launches a detached worker
@@ -97,12 +108,16 @@ 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. if the immediately preceding oracle run failed because ChatGPT login is required or the worker explicitly said to rerun `/oracle-auth`, call `oracle_auth` once before retrying
+5. gather enough repo context to submit well and bias toward context-rich archives when they fit within the 250 MB ceiling
+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. craft the oracle prompt
+9. call `oracle_submit`
+10. 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 +148,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. It also biases toward context-rich archives up to the 250 MB ceiling, narrowing only when the user explicitly asks for a tight archive, privacy/sensitivity requires it, or size pressure forces it.
 
 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 +277,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
@@ -448,6 +463,7 @@ Same-thread continuity is persisted as data, not runtime browser state.
 
 Approach:
 
+- expose `/oracle-followup <job-id> <request>` as the user-facing way to continue the same ChatGPT thread later
 - store `chatUrl` only after the conversation URL stabilizes
 - derive and persist `conversationId` from that URL when possible
 - for a follow-up job, resolve `followUpJobId` to the prior `chatUrl`
@@ -467,10 +483,10 @@ The extension still uses the same general `pi`-native background completion patt
 - poller scans jobs on an interval
 - completed job durability lives in oracle job state plus saved response/artifact files, not in synthetic session-history assistant messages
 - when a matching job reaches `complete`, `failed`, or `cancelled`, the poller issues bounded best-effort wake-up reminders to whichever matching session is currently live
-- those wake-ups direct the receiver to `oracle_read(jobId)` as the canonical completion-consumption path, while still surfacing saved response/artifact paths as secondary context
-- manual `oracle_read` or `/oracle-status` inspection settles further reminder retries once the terminal job has been opened and persists provenance about which path/session settled the wake-up
+- those wake-ups direct the receiver to `/oracle-read [job-id]` as the primary completion-consumption path, while still surfacing saved response/artifact paths as secondary context; `/oracle-status` remains useful for metadata and job-id discovery, and agent callers can still use `oracle_read` when they need tool output in-turn
+- manual `oracle_read`, `/oracle-read`, or `/oracle-status` inspection settles further reminder retries once the terminal job has been opened and persists provenance about which path/session settled the wake-up
 - manual inspection before the first wake-up attempt is recorded separately as observation metadata and does not suppress the first reminder send
-- if no wake-up lands, the job remains available via `/oracle-status`, `oracle_read`, and the saved `${PI_ORACLE_JOBS_DIR:-/tmp}/oracle-<job-id>/` response/artifact files
+- if no wake-up lands, the job remains available via `/oracle-read`, `/oracle-status`, `oracle_read`, and the saved `${PI_ORACLE_JOBS_DIR:-/tmp}/oracle-<job-id>/` response/artifact files
 - because completion delivery is best-effort, pruning uses explicit terminal-job age policy instead of pretending a durable session notification happened
 - recently sent wake-ups keep response/artifact files retained briefly so follow-up turns do not point at deleted paths if cleanup or pruning races with delivery
 
@@ -512,8 +528,8 @@ Implemented in code for the pivot and concurrency redesign:
 
 Retained from the earlier MVP:
 
-- `/oracle`, `/oracle-status`, `/oracle-cancel`, `/oracle-clean`
-- `oracle_submit`, `oracle_read`, `oracle_cancel`
+- `/oracle`, `/oracle-followup`, `/oracle-read`, `/oracle-status`, `/oracle-cancel`, `/oracle-clean`
+- `oracle_auth`, `oracle_submit`, `oracle_read`, `oracle_cancel`
 - detached background worker model
 - `${PI_ORACLE_JOBS_DIR:-/tmp}/oracle-<job-id>/...` state layout
 - shell-safe archive creation using `tar` piped to `zstd`

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/index.ts

@@ -21,7 +21,7 @@ export default function oracleExtension(pi: ExtensionAPI) {
   const authWorkerPath = join(extensionDir, "worker", "auth-bootstrap.mjs");
 
   registerOracleCommands(pi, authWorkerPath, workerPath);
-  registerOracleTools(pi, workerPath);
+  registerOracleTools(pi, workerPath, authWorkerPath);
 
   async function runStartupMaintenance(ctx: ExtensionContext): Promise<void> {
     try {

package/extensions/oracle/lib/auth.ts

@@ -0,0 +1,50 @@
+// Purpose: Share oracle auth-bootstrap orchestration between slash commands and agent-facing tools.
+// Responsibilities: Load effective auth guidance, run reconcile maintenance, spawn the auth bootstrap worker, and return user-facing results.
+// Scope: Extension-side auth bootstrap orchestration only; browser cookie import and profile validation stay in worker/auth-bootstrap.mjs.
+// Usage: Imported by oracle commands and tools whenever the shared oracle auth seed profile must be refreshed.
+// Invariants/Assumptions: Auth bootstrap runs under the global reconcile lock when available, uses the effective oracle config for the current workspace root, and returns the worker's stdout/stderr message verbatim on success or failure.
+import { spawn } from "node:child_process";
+import { formatOracleAuthConfigRemediation, formatOracleAuthConfigSummary, getOracleConfigLoadDetails, loadOracleConfig } from "./config.js";
+import { pruneTerminalOracleJobs, reconcileStaleOracleJobs } from "./jobs.js";
+import { isLockTimeoutError, withGlobalReconcileLock } from "./locks.js";
+
+export async function runOracleAuthBootstrap(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();
+      await pruneTerminalOracleJobs();
+    });
+  } catch (error) {
+    if (!isLockTimeoutError(error, "reconcile", "global")) throw error;
+  }
+
+  return await new Promise<string>((resolve, reject) => {
+    const child = spawn(process.execPath, [authWorkerPath, JSON.stringify({ config, configLoad: authConfigGuidance })], {
+      cwd,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (data) => {
+      stdout += String(data);
+    });
+    child.stderr.on("data", (data) => {
+      stderr += String(data);
+    });
+    child.on("error", (error) => reject(error));
+    child.on("close", (code) => {
+      const message = stdout.trim() || stderr.trim() || "Oracle auth bootstrap finished with no output.";
+      if (code === 0) resolve(message);
+      else reject(new Error(message));
+    });
+  });
+}

package/extensions/oracle/lib/commands.ts

@@ -3,10 +3,11 @@
 // Scope: Command-facing orchestration only; durable lifecycle mutations live in jobs/runtime/tools modules and browser execution stays in worker scripts.
 // 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 { readFile } from "node:fs/promises";
 import type { ExtensionAPI, ExtensionCommandContext } from "@mariozechner/pi-coding-agent";
 import { formatOracleJobSummary } from "../shared/job-observability-helpers.mjs";
-import { loadOracleConfig } from "./config.js";
+import { runOracleAuthBootstrap } from "./auth.js";
 import {
   cancelOracleJob,
   getJobDir,
@@ -14,7 +15,6 @@ import {
   isTerminalOracleJob,
   listJobsForCwd,
   markWakeupSettled,
-  pruneTerminalOracleJobs,
   readJob,
   reconcileStaleOracleJobs,
   removeTerminalOracleJob,
@@ -25,13 +25,25 @@ import { refreshOracleStatus } from "./poller.js";
 import { isLockTimeoutError, withGlobalReconcileLock } from "./locks.js";
 import { getProjectId } from "./runtime.js";
 
-function summarizeJob(jobId: string): string {
+async function summarizeJob(jobId: string, options?: { responsePreview?: boolean }): Promise<string> {
   const job = readJob(jobId);
   if (!job) return `Oracle job ${jobId} not found.`;
 
+  const responseAvailable = Boolean(job.responsePath && existsSync(job.responsePath));
+  let responsePreview: string | undefined;
+  if (options?.responsePreview && responseAvailable && job.responsePath) {
+    try {
+      responsePreview = (await readFile(job.responsePath, "utf8")).slice(0, 4000);
+    } catch {
+      responsePreview = undefined;
+    }
+  }
+
   return formatOracleJobSummary(job, {
     queuePosition: job.status === "queued" ? getQueuePosition(job.id) : undefined,
     artifactsPath: `${getJobDir(job.id)}/artifacts`,
+    responseAvailable,
+    responsePreview,
   });
 }
 
@@ -39,53 +51,25 @@ function getLatestJobId(cwd: string): string | undefined {
   return listJobsForCwd(cwd)[0]?.id;
 }
 
+function listRecentJobIds(cwd: string, limit = 5): string | undefined {
+  const jobs = listJobsForCwd(cwd).slice(0, limit);
+  if (jobs.length === 0) return undefined;
+  return jobs.map((job) => `${job.id} (${job.status})`).join(", ");
+}
+
 function readScopedJob(jobId: string, cwd: string) {
   const job = readJob(jobId);
   if (!job || job.projectId !== getProjectId(cwd)) return undefined;
   return job;
 }
 
-async function runAuthBootstrap(authWorkerPath: string, cwd: string): Promise<string> {
-  const config = loadOracleConfig(cwd);
-  try {
-    await withGlobalReconcileLock({ processPid: process.pid, source: "oracle_auth", cwd }, async () => {
-      await reconcileStaleOracleJobs();
-      await pruneTerminalOracleJobs();
-    });
-  } catch (error) {
-    if (!isLockTimeoutError(error, "reconcile", "global")) throw error;
-  }
-
-  return await new Promise<string>((resolve, reject) => {
-    const child = spawn(process.execPath, [authWorkerPath, JSON.stringify(config)], {
-      cwd,
-      stdio: ["ignore", "pipe", "pipe"],
-    });
-
-    let stdout = "";
-    let stderr = "";
-    child.stdout.on("data", (data) => {
-      stdout += String(data);
-    });
-    child.stderr.on("data", (data) => {
-      stderr += String(data);
-    });
-    child.on("error", (error) => reject(error));
-    child.on("close", (code) => {
-      const message = stdout.trim() || stderr.trim() || "Oracle auth bootstrap finished with no output.";
-      if (code === 0) resolve(message);
-      else reject(new Error(message));
-    });
-  });
-}
-
 export function registerOracleCommands(pi: ExtensionAPI, authWorkerPath: string, workerPath: string): void {
   pi.registerCommand("oracle-auth", {
     description: "Sync ChatGPT cookies from real Chrome into the oracle auth seed profile",
     handler: async (_args, ctx) => {
       ctx.ui.notify("Syncing ChatGPT cookies from real Chrome into the oracle auth seed profile…", "info");
       try {
-        const result = await runAuthBootstrap(authWorkerPath, ctx.cwd);
+        const result = await runOracleAuthBootstrap(authWorkerPath, ctx.cwd);
         ctx.ui.notify(result, "info");
       } catch (error) {
         ctx.ui.notify(error instanceof Error ? error.message : String(error), "warning");
@@ -94,7 +78,7 @@ export function registerOracleCommands(pi: ExtensionAPI, authWorkerPath: string,
   });
 
   pi.registerCommand("oracle-status", {
-    description: "Show oracle job status",
+    description: "Show oracle job status and recent job ids",
     handler: async (args, ctx) => {
       const explicitJobId = args.trim();
       const jobId = explicitJobId || getLatestJobId(ctx.cwd);
@@ -114,12 +98,14 @@ export function registerOracleCommands(pi: ExtensionAPI, authWorkerPath: string,
           cwd: ctx.cwd,
         });
       }
-      ctx.ui.notify(summarizeJob(job.id), "info");
+      const summary = await summarizeJob(job.id);
+      const recentJobs = !explicitJobId ? listRecentJobIds(ctx.cwd) : undefined;
+      ctx.ui.notify([summary, recentJobs ? `Recent jobs: ${recentJobs}` : undefined].filter(Boolean).join("\n"), "info");
     },
   });
 
-  pi.registerCommand("oracle-cancel", {
-    description: "Cancel a queued or active oracle job",
+  pi.registerCommand("oracle-read", {
+    description: "Show oracle job status plus saved response preview",
     handler: async (args, ctx) => {
       const explicitJobId = args.trim();
       const jobId = explicitJobId || getLatestJobId(ctx.cwd);
@@ -127,8 +113,32 @@ export function registerOracleCommands(pi: ExtensionAPI, authWorkerPath: string,
         ctx.ui.notify("No oracle jobs found for this project", "info");
         return;
       }
+      const job = readScopedJob(jobId, ctx.cwd);
+      if (!job) {
+        ctx.ui.notify(`Oracle job ${jobId} was not found in this project`, "warning");
+        return;
+      }
+      if (isTerminalOracleJob(job)) {
+        await markWakeupSettled(job.id, {
+          source: "oracle_read_command",
+          sessionFile: ctx.sessionManager.getSessionFile?.(),
+          cwd: ctx.cwd,
+        });
+      }
+      ctx.ui.notify(await summarizeJob(job.id, { responsePreview: true }), "info");
+    },
+  });
 
-      const job = explicitJobId ? readScopedJob(jobId, ctx.cwd) : readJob(jobId);
+  pi.registerCommand("oracle-cancel", {
+    description: "Cancel a queued or active oracle job by id",
+    handler: async (args, ctx) => {
+      const jobId = args.trim();
+      if (!jobId) {
+        ctx.ui.notify("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) {
         ctx.ui.notify(`Oracle job ${jobId} not found in this project`, "warning");
         return;
@@ -151,7 +161,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 +206,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

@@ -8,6 +8,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { getAgentDir } from "@mariozechner/pi-coding-agent";
 import { isAbsolute, join, normalize } from "node:path";
+import { getProjectId } from "./runtime.js";
 
 export const MODEL_FAMILIES = ["instant", "thinking", "pro"] as const;
 export type OracleModelFamily = (typeof MODEL_FAMILIES)[number];
@@ -258,6 +259,55 @@ 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 projectRoot = getProjectId(cwd);
+  const agentConfigPath = join(agentDir, "extensions", "oracle.json");
+  const projectConfigPath = join(projectRoot, ".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 +564,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));
 }