pi-oracle 0.3.4 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # 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
+- repeatable isolated local-extension `pi` validation guidance for oracle release verification, including smoke workflows that load the in-repo extension source directly
+- persisted oracle lifecycle-event breadcrumbs plus richer detached-job observability in `oracle_submit`, `oracle_read`, poller wake-ups, and `/oracle-status`, including worker-log paths and last-event context
+- shared worker/auth validation helpers, shared concurrency primitives, shared lifecycle reducers, and shared observability formatters to keep extension and worker behavior aligned
+- extracted sanity-harness support and poller suites with typed helper scaffolding and repeated-run stability coverage
+
+### Changed
+- oracle whole-repo archiving now excludes local tool state like `.pi/`, `.oracle-context/`, `.cursor/`, and `.scratchpad.md` by default while preserving explicitly requested paths
+- lock/lease recovery, queue promotion, process identity handling, and lifecycle transitions now flow through shared helper modules instead of duplicated inline implementations
+- worker/auth verification now leans on behaviorally tested helper modules plus dedicated `typecheck:worker-helpers` coverage instead of syntax checks and brittle source-string assertions alone
+- release validation now expects isolated local-extension `pi` smoke tests and a stronger local oracle verification gate before shipping
+
+### Fixed
+- archive input resolution now rejects symlink escapes outside the repo root and preserves safer repo-boundary handling for targeted archives
+- hung `tar`, `zstd`, `cp`, and auth `agent-browser` subprocesses now time out and fail clearly instead of wedging archive, runtime-clone, or auth flows indefinitely
+- cleanup warnings without a live worker no longer consume runtime/conversation capacity forever, while teardown still attempts lease release and preserves warnings for later triage
+- detached oracle workers and poller flows now report clearer lifecycle breadcrumbs, wake-up settlement state, and failure context during fast-fail auth/bootstrap scenarios
+- sanity-runner cleanup now retries transient temp-directory removal races, and the extracted harness is less timing-fragile and less `any`-driven than the previous monolithic runner
+
 ## 0.3.4 - 2026-04-11
 
 ### Changed

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.
@@ -195,6 +212,7 @@ Project config should only override safe, non-privileged settings.
 
 - `docs/ORACLE_DESIGN.md` — architecture, lifecycle, queueing, persistence, presets, and recovery behavior
 - `docs/ORACLE_RECOVERY_DRILL.md` — safe expired-auth recovery validation drill
+- `docs/ORACLE_ISOLATED_PI_VALIDATION.md` — repeatable isolated `pi` session smoke test for local-extension validation
 
 ## Privacy / local data
 
@@ -210,6 +228,7 @@ Review the code and design docs before using it with sensitive material.
 ```bash
 npm run check:oracle-extension
 npm run typecheck
+npm run typecheck:worker-helpers
 npm run sanity:oracle
 npm run pack:check
 # conventional local gate

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

@@ -0,0 +1,276 @@
+# Oracle isolated `pi` validation
+
+This document describes the repeatable pre-commit smoke test for validating `pi-oracle` through isolated `pi` agent sessions that load the local extension source.
+
+Use this workflow for code changes when you need end-to-end evidence beyond `npm test`.
+
+## What this validates
+
+- the local extension can be loaded directly by isolated `pi` sessions
+- whole-repo `oracle_submit` archive creation excludes local tool state by default
+- targeted archive inputs cannot escape the repo through symlinked paths
+- the exercised `pi` agents can provide candid feedback about tool clarity or clunkiness
+
+## Why this workflow is isolated
+
+The test intentionally uses separate directories for:
+
+- `PI_CODING_AGENT_DIR`
+- `--session-dir`
+- `PI_ORACLE_JOBS_DIR`
+
+That keeps the validation run from reusing your normal `pi` agent state.
+
+The extension is loaded from the local checkout with:
+
+```bash
+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:
+
+- `instant`
+- `thinking_light`
+
+The examples below use `instant` because it is the fastest smoke-test preset.
+
+## Prerequisites
+
+- `pi` installed locally
+- `tmux` installed locally
+- run from the repository root
+
+## Repeatable smoke test
+
+```bash
+set -euo pipefail
+
+REPO="$PWD"
+TEST_ROOT="/tmp/pi-oracle-isolated-tests-$$"
+
+TEST1_AGENT="$TEST_ROOT/agent1"
+TEST1_SESSIONS="$TEST_ROOT/sessions1"
+TEST1_JOBS="$TEST_ROOT/jobs1"
+TEST2_AGENT="$TEST_ROOT/agent2"
+TEST2_SESSIONS="$TEST_ROOT/sessions2"
+TEST2_JOBS="$TEST_ROOT/jobs2"
+
+FIXTURE="$TEST_ROOT/symlink-fixture"
+OUTSIDE="$TEST_ROOT/outside"
+
+SESSION1="pi-oracle-test1"
+SESSION2="pi-oracle-test2"
+
+mkdir -p \
+  "$TEST1_AGENT" "$TEST1_SESSIONS" "$TEST1_JOBS" \
+  "$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"
+
+PROMPT1='Call oracle_submit directly with prompt "Sanity test for archive exclusions. Reply with OK." files ["."] and preset "instant". Do not use bash. After the tool returns, summarize the outcome in 3 bullets including the job id/status, and give one sentence of candid feedback on whether the oracle tool behavior feels clear or clunky.'
+PROMPT2='Call oracle_submit directly with prompt "Sanity test for symlink escape rejection." files ["linked-outside/secret.txt"] and preset "instant". Do not use bash. After the tool returns, summarize the outcome in 3 bullets and give one sentence of candid feedback on whether the oracle tool behavior feels clear or clunky.'
+
+cleanup() {
+  tmux kill-session -t "$SESSION1" 2>/dev/null || true
+  tmux kill-session -t "$SESSION2" 2>/dev/null || true
+}
+trap cleanup EXIT
+cleanup
+
+TMUX_CMD1="cd '$REPO' && env PI_CODING_AGENT_DIR='$TEST1_AGENT' PI_ORACLE_JOBS_DIR='$TEST1_JOBS' PATH='$PATH' pi --session-dir '$TEST1_SESSIONS' --no-extensions -e '$REPO/extensions/oracle/index.ts'"
+tmux new-session -d -s "$SESSION1" "$TMUX_CMD1"
+sleep 8
+tmux send-keys -t "$SESSION1":0.0 "$PROMPT1" Enter
+sleep 35
+
+echo '--- pane:test1'
+tmux capture-pane -p -S -220 -t "$SESSION1":0.0 | tail -n 160
+
+JOB_DIR1="$(find "$TEST1_JOBS" -maxdepth 1 -type d -name 'oracle-*' | sort | tail -n 1 || true)"
+echo "--- latest job dir:test1 ${JOB_DIR1:-<none>}"
+
+if [ -n "${JOB_DIR1:-}" ] && [ -f "$JOB_DIR1/job.json" ]; then
+  ARCHIVE1="$(python3 - <<'PY' "$JOB_DIR1/job.json"
+import json,sys
+with open(sys.argv[1]) as f:
+    print(json.load(f)['archivePath'])
+PY
+)"
+  echo "--- archive:test1 $ARCHIVE1"
+  tar --zstd -tf "$ARCHIVE1" | head -n 80
+  LIST="$(mktemp)"
+  tar --zstd -tf "$ARCHIVE1" > "$LIST"
+  for path in .pi/settings.json .oracle-context .cursor .scratchpad.md README.md; do
+    if grep -E -q "^${path}$|^${path}/" "$LIST"; then
+      echo "FOUND $path"
+    else
+      echo "MISSING $path"
+    fi
+  done
+  rm -f "$LIST"
+fi
+
+TMUX_CMD2="cd '$FIXTURE' && env PI_CODING_AGENT_DIR='$TEST2_AGENT' PI_ORACLE_JOBS_DIR='$TEST2_JOBS' PATH='$PATH' pi --session-dir '$TEST2_SESSIONS' --no-extensions -e '$REPO/extensions/oracle/index.ts'"
+tmux new-session -d -s "$SESSION2" "$TMUX_CMD2"
+sleep 8
+tmux send-keys -t "$SESSION2":0.0 "$PROMPT2" Enter
+sleep 25
+
+echo '--- pane:test2'
+tmux capture-pane -p -S -220 -t "$SESSION2":0.0 | tail -n 160
+
+echo '--- jobs created:test2'
+find "$TEST2_JOBS" -maxdepth 1 -type d -name 'oracle-*' | sort || true
+
+echo "TEST_ROOT=$TEST_ROOT"
+```
+
+## Expected results
+
+### Test 1: whole-repo archive exclusions
+
+Expected behavior:
+
+- the isolated `pi` session loads the local extension successfully
+- `oracle_submit` creates a job and an archive path under the isolated jobs dir
+- the archive should exclude:
+  - `.pi/`
+  - `.oracle-context/`
+  - `.cursor/`
+  - `.scratchpad.md`
+- the archive should still include normal repo files such as `README.md`
+
+Notes:
+
+- this smoke test does not require `/oracle-auth`
+- 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
+
+Expected behavior:
+
+- `oracle_submit` rejects `linked-outside/secret.txt`
+- 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
+
+Use this when validating timeout hardening around auth/bootstrap browser commands.
+
+```bash
+set -euo pipefail
+
+REPO="$PWD"
+TEST_ROOT="/tmp/pi-oracle-auth-timeout-$$"
+AGENT_DIR="$TEST_ROOT/agent"
+SESSION_DIR="$TEST_ROOT/sessions"
+JOBS_DIR="$TEST_ROOT/jobs"
+FAKE_BROWSER="$TEST_ROOT/agent-browser"
+SESSION_NAME="pi-oracle-auth-timeout"
+
+mkdir -p "$AGENT_DIR/extensions" "$SESSION_DIR" "$JOBS_DIR"
+
+cat > "$AGENT_DIR/extensions/oracle.json" <<JSON
+{
+  "auth": {
+    "chromeCookiePath": "$TEST_ROOT/missing-cookies.sqlite"
+  }
+}
+JSON
+
+cat > "$FAKE_BROWSER" <<'SH'
+#!/bin/sh
+trap 'exit 0' TERM INT
+while :; do sleep 1; done
+SH
+chmod +x "$FAKE_BROWSER"
+
+cleanup() {
+  tmux kill-session -t "$SESSION_NAME" 2>/dev/null || true
+}
+trap 'cleanup; rm -rf "$TEST_ROOT"' EXIT
+cleanup
+
+TMUX_CMD="cd '$REPO' && env PI_CODING_AGENT_DIR='$AGENT_DIR' PI_ORACLE_JOBS_DIR='$JOBS_DIR' AGENT_BROWSER_PATH='$FAKE_BROWSER' PI_ORACLE_AUTH_AGENT_BROWSER_TIMEOUT_MS='250' PI_ORACLE_AUTH_CLOSE_TIMEOUT_MS='250' PI_ORACLE_AUTH_KILL_GRACE_MS='100' PATH='$PATH' pi --session-dir '$SESSION_DIR' --no-extensions -e '$REPO/extensions/oracle/index.ts'"
+
+tmux new-session -d -s "$SESSION_NAME" "$TMUX_CMD"
+sleep 8
+tmux send-keys -t "$SESSION_NAME":0.0 '/oracle-auth' Enter
+sleep 12
+
+tmux capture-pane -p -S -220 -t "$SESSION_NAME":0.0 | tail -n 140
+```
+
+Expected behavior:
+
+- the isolated `pi` session loads the local extension successfully
+- `/oracle-auth` returns with an error instead of hanging indefinitely
+- the output should mention the missing ChatGPT session-token cookies or the configured cookie source problem
+- the session should remain usable after the command failure
+
+## Switching to `thinking_light`
+
+To run the same smoke test with `thinking_light`, change both prompts from:
+
+```text
+preset "instant"
+```
+
+to:
+
+```text
+preset "thinking_light"
+```
+
+## Cleanup
+
+The snippet already kills the temporary `tmux` sessions on exit.
+
+To remove the temporary files after inspection:
+
+```bash
+rm -rf "$TEST_ROOT"
+```
+
+## Minimum pre-commit evidence
+
+Before committing code changes, keep evidence for:
+
+- `npm test` passing
+- isolated `pi` session validation using this workflow
+- any agent feedback gathered during the isolated run if it exposed clunky or unclear behavior

package/extensions/oracle/index.ts

@@ -1,3 +1,8 @@
+// Purpose: Register the oracle extension, wire commands/tools/workers, and manage per-session background maintenance.
+// Responsibilities: Bootstrap oracle commands and tools, start or stop polling, and surface startup/config availability in the pi session UI.
+// Scope: Extension entrypoint only; lifecycle mutation lives in lib modules and browser execution lives in worker scripts.
+// Usage: Loaded by pi as the extension module declared in package.json.
+// Invariants/Assumptions: Oracle only runs against persisted sessions, and startup maintenance should be best-effort without breaking session initialization.
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
 import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
@@ -42,7 +47,9 @@ export default function oracleExtension(pi: ExtensionAPI) {
 
       const config = loadOracleConfig(ctx.cwd);
       void runStartupMaintenance(ctx).catch((error) => {
-        console.error("Oracle startup maintenance failed:", error);
+        const message = `Oracle startup maintenance failed: ${error instanceof Error ? error.message : String(error)}`;
+        console.error(message);
+        ctx.ui.notify(message, "warning");
       });
       startPoller(pi, ctx, config.poller.intervalMs, workerPath);
       refreshOracleStatus(ctx);

package/extensions/oracle/lib/commands.ts

@@ -1,8 +1,16 @@
+// Purpose: Register slash commands for oracle auth/bootstrap, status inspection, cancellation, and cleanup.
+// Responsibilities: Bridge command handlers to shared oracle lifecycle helpers, surface consistent summaries, and coordinate follow-up queue advancement.
+// 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 type { ExtensionAPI, ExtensionCommandContext } from "@mariozechner/pi-coding-agent";
-import { loadOracleConfig } from "./config.js";
+import { formatOracleJobSummary } from "../shared/job-observability-helpers.mjs";
+import { formatOracleAuthConfigRemediation, formatOracleAuthConfigSummary, getOracleConfigLoadDetails, loadOracleConfig } from "./config.js";
 import {
   cancelOracleJob,
+  getJobDir,
   isOpenOracleJob,
   isTerminalOracleJob,
   listJobsForCwd,
@@ -22,30 +30,12 @@ function summarizeJob(jobId: string): string {
   const job = readJob(jobId);
   if (!job) return `Oracle job ${jobId} not found.`;
 
-  const queuePosition = job.status === "queued" ? getQueuePosition(job.id) : undefined;
-  return [
-    `job: ${job.id}`,
-    `status: ${job.status}`,
-    `phase: ${job.phase}`,
-    `created: ${job.createdAt}`,
-    job.queuedAt ? `queued: ${job.queuedAt}` : undefined,
-    job.submittedAt ? `submitted: ${job.submittedAt}` : undefined,
-    queuePosition ? `queue-position: ${queuePosition.position} of ${queuePosition.depth} global` : undefined,
-    `project: ${job.projectId}`,
-    `session: ${job.sessionId}`,
-    job.completedAt ? `completed: ${job.completedAt}` : undefined,
-    job.followUpToJobId ? `follow-up-to: ${job.followUpToJobId}` : undefined,
-    job.chatUrl ? `chat: ${job.chatUrl}` : undefined,
-    job.conversationId ? `conversation: ${job.conversationId}` : undefined,
-    job.responsePath ? `response: ${job.responsePath}` : undefined,
-    job.responseFormat ? `response-format: ${job.responseFormat}` : undefined,
-    typeof job.artifactFailureCount === "number" ? `artifact-failures: ${job.artifactFailureCount}` : undefined,
-    job.lastCleanupAt ? `last-cleanup: ${job.lastCleanupAt}` : undefined,
-    job.cleanupWarnings?.length ? `cleanup-warnings: ${job.cleanupWarnings.join(" | ")}` : undefined,
-    job.error ? `error: ${job.error}` : undefined,
-  ]
-    .filter(Boolean)
-    .join("\n");
+  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,
+  });
 }
 
 function getLatestJobId(cwd: string): string | undefined {
@@ -60,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();
@@ -70,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"],
     });
@@ -164,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) {
@@ -209,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

@@ -1,3 +1,8 @@
+// Purpose: Define oracle configuration schema, defaults, preset selection, and local config loading behavior.
+// Responsibilities: Normalize preset ids, load extension config from disk, expose default browser/auth/runtime settings, and validate config shape.
+// Scope: Configuration and preset resolution only; runtime/job execution stays in sibling oracle modules.
+// Usage: Imported by oracle tools, commands, runtime helpers, and sanity tests when config or preset resolution is required.
+// Invariants/Assumptions: Preset ids remain the canonical model-selection contract and config loading must fail clearly on invalid user overrides.
 import { execFileSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
@@ -253,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",
@@ -509,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));
 }