pi-oracle 0.6.16 → 0.6.17

package/CHANGELOG.md

@@ -2,8 +2,18 @@
 
 ## Unreleased
 
+## 0.6.17 - 2026-05-10
+
 ### Changed
 - made `/oracle-auth` success and failure output easier to scan, with compact source summaries and source-specific troubleshooting for configured Chromium cookie sources
+- tightened README quickstart/command wording around preflight-first `/oracle` behavior, context-rich archive selection, cleanup retention, and preset defaults
+- added the resolved oracle model preset snapshot to `oracle_submit` queued/dispatched output so agents can see what preset will run
+- clarified `oracle_preflight` output so users can see that it validates the persisted pi session, local config, and ChatGPT auth seed created by `oracle_auth`
+- made direct `scripts/oracle-sanity.ts` execution fail fast unless isolated oracle state/jobs dirs are provided, preventing accidental sanity-job leakage into live oracle pollers
+
+### Fixed
+- stopped worker/auth readiness checks from treating ChatGPT's public logged-out composer shell as an authenticated ready state, and made stale-auth failures name the visible login controls instead of reporting a misleading partial-login state
+- made plain `instant` model selection robust against the current ChatGPT model menu by recognizing closed Instant chips and falling back to the top-level model menu when the configure sheet is unavailable
 
 ## 0.6.16 - 2026-05-07
 

package/README.md

@@ -1,62 +1,118 @@
 # pi-oracle
 
-`pi-oracle` is a `pi` package that lets the agent hand off difficult, long-running tasks to ChatGPT.com through the web app instead of the API.
+`pi-oracle` lets a `pi` agent send hard, long-running work to ChatGPT.com through the web app, with repo archives, background execution, saved results, and a best-effort wake-up back into `pi` when the answer is ready.
 
-Use it when you want:
-- your real ChatGPT account
-- web-model behavior instead of API usage
-- large repo/context uploads
-- async background execution
-- durable saved responses/artifacts plus best-effort wake-ups back into `pi`
+> Status: experimental public beta. Validated primarily on macOS with Google Chrome/Chromium and `pi` 0.65.0+. Normal oracle jobs run in an isolated browser profile, not your active browser window.
 
-Normal oracle jobs run in an isolated browser profile, not your active browser window.
+## What a successful run looks like
 
-> Status: experimental public beta. Validated primarily on macOS with Google Chrome and `pi` 0.65.0+.
+```text
+You: /oracle Review the pending changes. Include the whole repo unless a narrower archive is clearly better.
+
+pi-oracle:
+  1. preflights local session/auth readiness
+  2. builds a context-rich `.tar.zst` repo archive
+  3. starts an isolated ChatGPT web runtime in the background
+  4. uploads the archive and prompt to ChatGPT.com
+  5. saves the response/artifacts under /tmp/oracle-<job-id>/
+  6. sends a best-effort wake-up back to the matching pi session
+
+Later: /oracle-read <job-id>
+```
+
+What you are seeing: the local `pi` agent keeps control of context selection and safety checks, while ChatGPT web handles the expensive second-opinion work asynchronously. If the wake-up is missed, the result still lives on disk and can be read by job id.
+
+## Who this is for
+
+Use `pi-oracle` if you use `pi` and want a larger asynchronous reviewer, planner, or analyst that can use your real ChatGPT web account instead of an API model.
+
+It is most useful for:
+
+- maintainers reviewing broad repo changes before shipping
+- agents that need a slower second opinion without blocking the main `pi` turn
+- migration, architecture, or failure-mode analysis that benefits from a large archive
+- follow-up questions that should continue the same ChatGPT thread later
+
+Do not use it for:
+
+- short local coding tasks that `pi` can handle directly
+- projects that must never be uploaded to ChatGPT.com
+- non-macOS environments or machines without the required local browser/tooling
+
+## Problem it solves
 
-## When to use it
+A normal coding-agent turn is the wrong shape for some work: the task may need a large repo snapshot, a slower web model, a real ChatGPT subscription, artifact downloads, or a durable result that arrives after the active turn ends.
 
-Use `pi-oracle` for:
-- big code reviews of a repo or pending changes
-- architectural or migration analysis that benefits from a large uploaded archive
-- long-running prompts that may take minutes to finish
-- follow-up questions in the same ChatGPT thread later
+`pi-oracle` makes that workflow explicit and recoverable instead of asking the main agent to manually drive ChatGPT in your real browser window.
 
-Do not reach for it first for:
-- normal short coding tasks that `pi` can handle directly
-- workflows that must never upload project archives to ChatGPT.com
-- environments outside the current supported setup
+## What it does
 
-## Install
+| Problem | Capability | Proof in this repo |
+| --- | --- | --- |
+| Hard tasks need more context than a quick turn should gather. | `/oracle` prompts the agent to preflight, choose a context-rich archive, and submit it to ChatGPT web. | [`prompts/oracle.md`](prompts/oracle.md), `oracle_submit`, archive tests in `scripts/oracle-sanity-*` |
+| Browser automation should not steal focus or mutate your active profile. | Jobs clone an authenticated seed profile into per-job isolated runtime profiles. | [`docs/ORACLE_DESIGN.md`](docs/ORACLE_DESIGN.md), [`extensions/oracle/lib/runtime.ts`](extensions/oracle/lib/runtime.ts) |
+| Long jobs need durability. | Job state, responses, logs, and artifacts persist under `${PI_ORACLE_JOBS_DIR:-/tmp}/oracle-<job-id>/`. | [`extensions/oracle/lib/jobs.ts`](extensions/oracle/lib/jobs.ts), `/oracle-read`, `/oracle-status` |
+| ChatGPT auth can expire or drift. | `/oracle-auth` refreshes the isolated auth seed from a configured local Chromium profile, with recovery guidance. | [`extensions/oracle/lib/auth.ts`](extensions/oracle/lib/auth.ts), [`docs/ORACLE_RECOVERY_DRILL.md`](docs/ORACLE_RECOVERY_DRILL.md) |
+| Agents need a simple API, not UI-driving instructions. | The package exposes agent-facing tools: `oracle_preflight`, `oracle_submit`, `oracle_read`, `oracle_auth`, and `oracle_cancel`. | [`extensions/oracle/lib/tools.ts`](extensions/oracle/lib/tools.ts) |
 
-npm:
+## Fastest way to see it work
+
+### 1. Install
+
+From npm:
 
 ```bash
 pi install npm:pi-oracle
 ```
 
-GitHub:
+Or from GitHub:
 
 ```bash
 pi install https://github.com/fitchmultz/pi-oracle
 ```
 
-## Quickstart
+### 2. Check requirements
+
+You need:
+
+- macOS
+- Node.js 22 or newer
+- `pi` 0.65.0 or newer
+- Google Chrome or another Chromium-family browser
+- ChatGPT already signed in to the configured local browser profile
+- `agent-browser`, `tar`, and `zstd` available on the machine
+- a normal persisted `pi` session, not `pi --no-session`
+
+### 3. Sync ChatGPT auth once
+
+```text
+/oracle-auth
+```
+
+This reads ChatGPT cookies from your configured local browser profile and writes an isolated oracle seed profile. It should not automate your active browser window for normal jobs.
 
-1. Start a normal persisted `pi` session. Do not use `pi --no-session` for oracle.
-2. Make sure ChatGPT already works in your configured local browser 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 the one-time best-effort wake-up, or check `/oracle-status`.
+### 4. Submit a tiny job
 
-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.
+```text
+/oracle Read README.md and package.json. Tell me in five bullets what this package does and who should not use it.
+```
+
+Expected result:
 
-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.
+- The `/oracle` prompt now runs an early oracle preflight before expensive repo reading or archive creation.
+- The agent chooses a context-rich relevant archive up to the 250 MB ceiling, not the smallest possible one-file slice when nearby context helps.
+- `oracle_submit` creates or queues a job.
+- If local packing is too large, the prompt treats that as a retryable archive-selection failure and narrows automatically before surfacing the problem.
+- The job uploads a repo archive to ChatGPT.com, capped at 250 MiB after default exclusions/pruning.
+- The response is saved under `/tmp/oracle-<job-id>/response.md` by default.
+- The matching `pi` session gets one best-effort wake-up when the job finishes.
 
-If a local archive still exceeds the 250 MB limit after default exclusions and automatic whole-repo pruning, the agent should treat that as a retryable archive-selection failure: shrink the archive automatically, retry with a smaller relevant slice, and explain what it cut only if it still cannot fit after the allowed retry budget.
+If the wake-up does not arrive, run:
 
-If you miss the one-time wake-up, the result is still saved durably in the oracle job directory and can be read later.
+```text
+/oracle-status
+/oracle-read <job-id>
+```
 
 ## Example requests
 
@@ -73,46 +129,53 @@ If you miss the one-time wake-up, the result is still saved durably in the oracl
 ```
 
 ```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.
+/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 250 MiB 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
+## How it works
 
 ```mermaid
 flowchart LR
     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"]
-    E --> F["Response/artifacts saved under oracle job dir"]
-    F --> G["One-time best-effort wake-up to matching pi session"]
+    B --> C["Agent chooses context-rich archive inputs"]
+    C --> D["oracle_submit builds .tar.zst archive"]
+    D --> E["Detached worker clones isolated auth seed profile"]
+    E --> F["ChatGPT web receives archive + prompt"]
+    F --> G["Response/artifacts saved under oracle job dir"]
+    G --> H["Best-effort wake-up to matching pi session"]
 ```
 
-If concurrency is full, the job is queued and starts automatically later.
+Key design choices:
 
-## What the package adds
+- **Prompt templates own context gathering.** `/oracle` and `/oracle-followup` tell the agent how to preflight, gather context, choose archive inputs, and then stop after dispatch.
+- **Tools own execution.** `oracle_submit` builds the archive, admits or queues the job, starts the worker, and returns immediately.
+- **Auth uses a seed profile.** `/oracle-auth` imports cookies into an isolated seed profile; each job clones that seed into its own temporary runtime profile.
+- **Follow-ups preserve ChatGPT thread state.** `/oracle-followup <job-id> ...` resolves the prior job's saved ChatGPT URL and submits the next prompt with `followUpJobId`.
+- **Wake-up is best effort, storage is durable.** A missed wake-up does not lose the result.
+
+## Commands and tools
 
 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 configured local browser profile into the isolated oracle auth profile
-- `/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
+
+- `/oracle <request>` — prepare context and dispatch a ChatGPT web oracle job
+- `/oracle-followup <job-id> <request>` — continue an earlier oracle job in the same ChatGPT thread
+- `/oracle-auth` — sync ChatGPT cookies into the isolated oracle auth seed profile
+- `/oracle-read [job-id]` — inspect job status and saved response preview
+- `/oracle-status [job-id]` — inspect a job or list recent job ids when no explicit id is given
+- `/oracle-cancel <job-id>` — cancel a queued or active job
+- `/oracle-clean <job-id|all>` — remove temp files for terminal jobs; recently woken terminal jobs may stay retained briefly, and a blocked cleanup returns the next eligible cleanup time
 
 Agent-facing tools:
+
 - `oracle_preflight`
 - `oracle_auth`
 - `oracle_submit`
 - `oracle_read`
 - `oracle_cancel`
 
-## Minimal config
+## Configuration
 
-Most users can start with the packaged defaults and only set the browser profile if needed.
+Most users can start with defaults. Set an agent-level config only when you need a non-default preset or browser profile.
 
 `~/.pi/agent/extensions/oracle.json`
 
@@ -128,14 +191,16 @@ Most users can start with the packaged defaults and only set the browser profile
 ```
 
 Notes:
+
 - `defaults.preset` is the default ChatGPT model preset for oracle jobs.
-- The canonical preset ids live in `extensions/oracle/lib/config.ts`.
-- If the packaged default is fine, you can omit `defaults.preset` entirely.
-- You usually do not need to set browser paths unless auto-detection fails.
+- The canonical preset ids live in [`extensions/oracle/lib/config.ts`](extensions/oracle/lib/config.ts).
+- If the packaged default is fine, omit `defaults.preset`.
+- When an agent is unsure which oracle preset fits, it should omit `preset` and use the configured default model instead of asking by default.
+- You usually do not need browser paths unless auto-detection fails.
 
 ### Custom Chromium cookie sources
 
-Most Chrome-compatible browsers should work through the default cookie importer. Use this alternate path only for a Chromium-family browser that is not one of `@steipete/sweet-cookie`'s built-in Chrome/Brave/Arc/Chromium targets or otherwise cannot import cookies without dependency patching.
+Use this only for a Chromium-family browser that the default cookie importer cannot read.
 
 Before running `/oracle-auth` with this path:
 
@@ -143,7 +208,7 @@ Before running `/oracle-auth` with this path:
 2. Fully quit the browser so its `Cookies` database is stable.
 3. Find the profile `Cookies` SQLite DB path.
 4. Find the browser's macOS Keychain safe-storage item account and service name.
-5. Configure all of `browser.executablePath`, `auth.chromeCookiePath`, and `auth.chromiumKeychain` in the agent-level config at `~/.pi/agent/extensions/oracle.json`.
+5. Configure all of `browser.executablePath`, `auth.chromeCookiePath`, and `auth.chromiumKeychain` in `~/.pi/agent/extensions/oracle.json`.
 
 Example Helium config:
 
@@ -164,9 +229,7 @@ Example Helium config:
 }
 ```
 
-`auth.chromeCookiePath` remains the cookie database path for backward compatibility. `auth.chromiumKeychain` must be paired with `auth.chromeCookiePath`; partial config is rejected so oracle does not silently fall back to a different browser source. When both are present, `/oracle-auth` uses pi-oracle's repo-owned generic Chromium cookie reader instead of patching `@steipete/sweet-cookie` internals.
-
-If macOS prompts for Keychain access during `/oracle-auth`, allow access for the configured browser safe-storage item. If auth still fails after cookies are synced, the cookie DB may be stale, from the wrong profile, or for an account that is logged out; reopen the configured browser profile, confirm ChatGPT works there, quit the browser, and rerun `/oracle-auth`.
+`auth.chromeCookiePath` must be paired with `auth.chromiumKeychain`; partial config is rejected so oracle does not silently fall back to another browser source.
 
 ## Available presets
 
@@ -181,38 +244,34 @@ If macOS prompts for Keychain access during `/oracle-auth`, allow access for the
 | `instant` | Instant |
 | `instant_auto_switch` | Instant - Auto-switch to Thinking Enabled |
 
-`oracle_submit` accepts either the canonical preset id or the matching human-readable preset label; common space/hyphen variants are normalized automatically at submit time. Keep `defaults.preset` in config on the canonical preset id.
+`oracle_submit` accepts canonical preset ids or a matching human-readable preset label. Keep config values on canonical ids.
 
-Other useful settings:
-- `browser.runMode`
-- `browser.args`
-- `browser.authSeedProfileDir`
-- `browser.runtimeProfilesDir`
-- `cleanup.completeJobRetentionMs`
-- `cleanup.failedJobRetentionMs`
+## Outputs and cleanup
 
-Project config should only override safe, non-privileged settings.
+- Jobs persist response text, metadata, logs, and artifacts under `${PI_ORACLE_JOBS_DIR:-/tmp}/oracle-<job-id>/` by default.
+- Jobs can queue automatically when runtime capacity is full.
+- Completion delivery into `pi` is one-time best-effort wake-up based.
+- `/oracle-read [job-id]` and `oracle_read({ jobId })` inspect saved output later.
+- `/oracle-clean` removes terminal job temp files, but can briefly refuse cleanup after a wake-up so the follow-up turn can still read the saved paths.
 
-## What happens to outputs
+## Privacy and local data
 
-- 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 one-time best-effort wake-up based; duplicate poller scans are deduped in job state.
-- 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.
+This extension is local-first, but it handles sensitive local and project data:
 
-## Requirements
+- `/oracle-auth` reads ChatGPT cookies from the configured local browser profile.
+- `oracle_submit` uploads selected project archives to ChatGPT.com.
+- Responses, logs, and artifacts are written to the configured oracle jobs directory.
 
-- macOS
-- Node.js 22 or newer
-- Google Chrome or another Chromium-family browser installed
-- ChatGPT already signed into the configured local browser profile
-- `pi` 0.65.0 or newer
-- `agent-browser` available on the machine
-- `tar` and `zstd` available
+Review the code and design docs before using it with private or regulated material.
+
+## Current limits
+
+- Experimental public beta, validated primarily on macOS.
+- ChatGPT UI, auth, model controls, and artifact download behavior can drift.
+- Archive uploads are capped at 250 MiB after default exclusions and automatic whole-repo pruning.
+- A real ChatGPT web session is required.
+- The README currently uses command-level proof and design docs; no public screenshot or demo GIF is checked into the repo.
+- Production hardening should keep focusing on UI drift detection, auth recovery, artifact capture, and environment diagnostics.
 
 ## Troubleshooting
 
@@ -221,6 +280,7 @@ Project config should only override safe, non-privileged settings.
 - Make sure ChatGPT works in the same local browser profile you configured.
 - For custom Chromium cookie sources, confirm `auth.chromeCookiePath` points at that profile's `Cookies` DB and `auth.chromiumKeychain.services` names the browser's safe-storage Keychain service.
 - Re-run `/oracle-auth`.
+- Agent callers can use `oracle_auth({})` once before retrying a stale-auth oracle submission.
 - If ChatGPT is half-logged-in or challenge flow state looks weird, finish the login/challenge in the headed auth browser and retry.
 
 ### Custom Chromium auth says cookies synced but the session is rejected
@@ -234,10 +294,10 @@ This usually means the cookie import worked but the source cookies are not the a
 5. Confirm `auth.chromiumKeychain.services` names the browser's safe-storage Keychain service for that DB.
 6. Re-run `/oracle-auth`.
 
-### You hit a challenge / verification page
+### You hit a challenge or verification page
 
 - Solve it in the auth/bootstrap browser if prompted.
-- Then re-run `/oracle-auth` before submitting jobs again.
+- Re-run `/oracle-auth` before submitting jobs again.
 
 ### You see "Oracle requires a persisted pi session"
 
@@ -247,19 +307,19 @@ This usually means the cookie import worked but the source cookies are not the a
 ### A job finished but no wake-up arrived
 
 - 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.
+- Use `/oracle-status` if you need help finding a recent job id.
+- Agent callers can use `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]`.
+- The command 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.
+Install the missing local dependency and rerun the command.
 
 ### Auto-detection picked the wrong browser profile
 
@@ -269,25 +329,11 @@ This usually means the cookie import worked but the source cookies are not the a
 
 ### You want more details about a failed run
 
-- Inspect the job directory under `${PI_ORACLE_JOBS_DIR:-/tmp}/oracle-<job-id>/`.
-- The worker log and captured diagnostics are stored there.
+Inspect the job directory under `${PI_ORACLE_JOBS_DIR:-/tmp}/oracle-<job-id>/`. The worker log and captured diagnostics are stored there.
 
-## Detailed docs
+## Verification
 
-- `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
-
-This extension is local-first, but it does read and persist local data:
-- `/oracle-auth` reads ChatGPT cookies from the configured local browser profile
-- job archives are uploaded to ChatGPT.com
-- responses and artifacts are written under the configured oracle jobs dir
-
-Review the code and design docs before using it with sensitive material.
-
-## Validation helpers
+Useful local checks:
 
 ```bash
 npm run check:oracle-extension
@@ -295,21 +341,32 @@ npm run typecheck
 npm run typecheck:worker-helpers
 npm run sanity:oracle
 npm run pack:check
-# conventional local gate
 npm test
-# or all at once
 npm run verify:oracle
 ```
 
-`npm publish` is also guarded locally via `prepublishOnly` and will run `npm run verify:oracle` before publishing.
+`npm publish` is guarded by `prepublishOnly`, which runs `npm run verify:oracle`.
+
+For end-to-end local-extension smoke testing, use [`docs/ORACLE_ISOLATED_PI_VALIDATION.md`](docs/ORACLE_ISOLATED_PI_VALIDATION.md). That workflow launches isolated `pi` sessions against this checkout and uses `instant` or `thinking_light`, as required by the project validation policy.
 
-## Beta caveats
+## Project map
 
-The highest-risk areas to monitor are:
-- ChatGPT UI drift
-- auth/bootstrap drift
-- artifact download behavior
-- local environment assumptions
+| Path | Purpose |
+| --- | --- |
+| [`extensions/oracle/index.ts`](extensions/oracle/index.ts) | Extension entrypoint |
+| `extensions/oracle/lib/` | Commands, tools, config, jobs, queueing, runtime, poller |
+| `extensions/oracle/worker/` | Detached ChatGPT web worker and UI/auth helpers |
+| `extensions/oracle/shared/` | Shared process, state, job, and observability helpers |
+| [`prompts/oracle.md`](prompts/oracle.md) | `/oracle` prompt-template workflow |
+| [`prompts/oracle-followup.md`](prompts/oracle-followup.md) | `/oracle-followup` prompt-template workflow |
+| `scripts/oracle-sanity-*` | Local sanity and archive-safety checks |
+| [`docs/ORACLE_DESIGN.md`](docs/ORACLE_DESIGN.md) | Architecture, lifecycle, queueing, persistence, recovery behavior |
+| [`docs/ORACLE_ISOLATED_PI_VALIDATION.md`](docs/ORACLE_ISOLATED_PI_VALIDATION.md) | Repeatable isolated `pi` validation workflow |
+| [`docs/ORACLE_RECOVERY_DRILL.md`](docs/ORACLE_RECOVERY_DRILL.md) | Safe expired-auth recovery drill |
+
+## Next action
+
+Install the package, run `/oracle-auth`, then submit the tiny README/package review job above. If you are evaluating the design before running it, start with [`docs/ORACLE_DESIGN.md`](docs/ORACLE_DESIGN.md).
 
 ## License
 

package/extensions/oracle/lib/tools.ts

@@ -957,12 +957,14 @@ function formatOraclePreflightResponse(details: OraclePreflightDetails): string
       "Oracle preflight ready.",
       details.session.sessionFile ? `Persisted session: ${details.session.sessionFile}` : undefined,
       details.auth.seedProfileDir ? `Auth seed profile: ${details.auth.seedProfileDir}` : undefined,
+      "Preflight validates the persisted pi session, local oracle config, and ChatGPT auth seed created by oracle_auth.",
       "You can continue with oracle context gathering and submission.",
     ].filter(Boolean).join("\n");
   }
 
   return [
     `Oracle preflight blocked: ${details.error?.message ?? "unknown blocker"}`,
+    "Preflight checks the persisted pi session, local oracle config, and ChatGPT auth seed before any archive work starts.",
     details.error?.suggestedNextStep ? `Suggested next step: ${details.error.suggestedNextStep}` : undefined,
   ].filter(Boolean).join("\n");
 }

package/extensions/oracle/shared/job-observability-helpers.d.mts

@@ -12,6 +12,12 @@ export interface OracleJobSummaryLike {
   heartbeatAt?: string;
   projectId: string;
   sessionId: string;
+  selection?: {
+    preset?: string;
+    modelFamily?: string;
+    effort?: string;
+    autoSwitchToThinking?: boolean;
+  };
   followUpToJobId?: string;
   chatUrl?: string;
   conversationId?: string;

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

@@ -46,6 +46,20 @@ function formatAutoPrunedArchiveMessage(autoPrunedPrefixes) {
   return `Archive auto-pruned generic generated-output-name dirs to fit size limit: ${autoPrunedPrefixes.map((entry) => `${entry.relativePath}/ (${formatBytes(entry.bytes)})`).join(", ")}`;
 }
 
+/**
+ * @param {OracleJobSummaryLike["selection"]} selection
+ * @returns {string | undefined}
+ */
+function formatOracleSelection(selection) {
+  if (!selection?.preset || !selection.modelFamily) return undefined;
+  const details = [
+    `family=${selection.modelFamily}`,
+    selection.effort ? `effort=${selection.effort}` : undefined,
+    selection.autoSwitchToThinking === true ? "auto-switch-to-thinking=true" : undefined,
+  ].filter(Boolean).join(", ");
+  return `Model preset: ${selection.preset}${details ? ` (${details})` : ""}`;
+}
+
 const ACTIVE_SUMMARY_STATUSES = new Set(["preparing", "submitted", "waiting"]);
 const DEFAULT_ORACLE_HEARTBEAT_STALE_MS = 3 * 60 * 1000;
 const DEFAULT_ACTIVE_JOB_POLL_HINT_SECONDS = 15;
@@ -221,6 +235,7 @@ export function formatOracleSubmitResponse(job, options) {
     `${options.queued ? "Oracle job queued" : "Oracle job dispatched"}: ${job.id}`,
     options.queued && options.queuePosition && options.queueDepth ? `Queue position: ${options.queuePosition} of ${options.queueDepth}` : undefined,
     job.followUpToJobId ? `Follow-up to: ${job.followUpToJobId}` : undefined,
+    formatOracleSelection(job.selection),
     `Prompt: ${job.promptPath}`,
     `Archive: ${job.archivePath}`,
     formatAutoPrunedArchiveMessage(options.autoPrunedPrefixes),

package/extensions/oracle/worker/auth-flow-helpers.mjs

@@ -109,7 +109,9 @@ export function classifyChatAuthPage(args) {
     return { state: "transient_outage_error", message: `ChatGPT is showing a transient outage/error page. Logs: ${args.logPath}` };
   }
 
-  if (args.probe?.status === 401 || (args.probe?.status === 403 && (!onAllowedOrigin || !hasUsableComposer || args.probe?.domLoginCta))) {
+  const probeHasAccountIdentity = args.probe?.bodyHasId === true || args.probe?.bodyHasEmail === true;
+
+  if (args.probe?.status === 401 || (args.probe?.status === 403 && (!onAllowedOrigin || !hasUsableComposer))) {
     return {
       state: "login_required",
       message:
@@ -120,7 +122,7 @@ export function classifyChatAuthPage(args) {
   }
 
   if (args.probe?.onAuthPage) {
-    if (args.probe?.bodyHasId || args.probe?.bodyHasEmail) {
+    if (probeHasAccountIdentity) {
       return {
         state: "auth_transitioning",
         message:
@@ -137,6 +139,16 @@ export function classifyChatAuthPage(args) {
     };
   }
 
+  if (onAllowedOrigin && hasUsableComposer && args.probe?.domLoginCta && !probeHasAccountIdentity) {
+    return {
+      state: "login_required",
+      message:
+        `ChatGPT still shows public login controls after syncing cookies from ${args.cookieSourceLabel}. ` +
+        `The cookie DB may be stale, from the wrong browser profile, or for an account that is logged out. ` +
+        `Check auth.chromeProfile/auth.chromeCookiePath/auth.chromiumKeychain and inspect ${args.logPath}.`,
+    };
+  }
+
   if (onAllowedOrigin && (args.probe?.status === 200 || args.probe?.status === 403) && hasUsableComposer) {
     if (!args.probe?.domLoginCta) {
       return {
@@ -145,12 +157,12 @@ export function classifyChatAuthPage(args) {
       };
     }
 
+    // The public logged-out composer case returned above, so a remaining visible login CTA here still has account-like probe data.
     return {
       state: "auth_transitioning",
       message:
-        args.probe?.bodyHasId || args.probe?.bodyHasEmail
-          ? `ChatGPT backend session is authenticated but the shell still shows public CTA chrome. Logs: ${args.logPath}`
-          : `ChatGPT accepted cookies but is still hydrating/auth-selecting. Logs: ${args.logPath}`,
+        `ChatGPT backend probe returned account-like fields, but the shell still shows public login controls. ` +
+        `Trying to resolve the account shell. Logs: ${args.logPath}`,
     };
   }
 

package/extensions/oracle/worker/chatgpt-ui-helpers.mjs

@@ -30,6 +30,7 @@ const THINKING_EFFORT_COMBOBOX_LABEL = "Thinking effort";
 const PRO_THINKING_EFFORT_COMBOBOX_LABEL = "Pro thinking effort";
 const EFFORT_LABELS = new Set(["Light", "Standard", "Extended", "Heavy"]);
 const BARE_EFFORT_PATTERN = /^(light|standard|extended|heavy)(?:, click to remove)?$/i;
+const INSTANT_CHIP_PATTERN = /^instant(?:, click to remove)?$/i;
 const THINKING_CHIP_PATTERN = /^(?:(light|standard|extended|heavy)\s+)?thinking(?:, click to remove)?$/i;
 const PRO_CHIP_PATTERN = /^(?:(light|standard|extended|heavy)\s+)?pro(?:, click to remove)?$/i;
 const MODEL_FAMILY_CONTROL_KINDS = new Set(["button", "radio", "menuitemradio"]);
@@ -125,6 +126,12 @@ function parseComposerChipSelection(label) {
     };
   }
 
+  if (INSTANT_CHIP_PATTERN.test(normalized)) {
+    return {
+      modelFamily: /** @type {OracleUiModelFamily} */ ("instant"),
+    };
+  }
+
   const thinkingMatch = normalized.match(THINKING_CHIP_PATTERN);
   if (thinkingMatch) {
     return {
@@ -240,11 +247,20 @@ export function snapshotHasModelConfigurationUi(snapshot) {
           .filter((family) => matchesModelFamilyLabel(entry.label, family)),
       ),
   );
+  const visibleRadioFamilies = new Set(
+    entries
+      .filter((entry) => entry.kind === "radio" && typeof entry.label === "string")
+      .flatMap((entry) =>
+        /** @type {OracleUiModelFamily[]} */ (["instant", "thinking", "pro"])
+          .filter((family) => matchesModelFamilyLabel(entry.label, family)),
+      ),
+  );
   const hasCloseButton = entries.some((entry) => entry.kind === "button" && entry.label === "Close" && !entry.disabled);
+  const hasIntelligenceHeading = entries.some((entry) => entry.kind === "heading" && normalizeText(entry.label) === "Intelligence" && !entry.disabled);
   const hasEffortCombobox = entries.some(
     (entry) => entry.kind === "combobox" && EFFORT_LABELS.has(entry.value || "") && !entry.disabled,
   );
-  return visibleFamilies.size >= 2 || hasCloseButton || hasEffortCombobox;
+  return visibleFamilies.size >= 2 || visibleRadioFamilies.size >= 2 || hasCloseButton || hasIntelligenceHeading || hasEffortCombobox;
 }
 
 /**

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

@@ -705,6 +705,14 @@ function matchesModelConfigurationOpener(candidate) {
     || /^(?:(?:Light|Standard|Extended|Heavy) )?Pro(?:, click to remove)?$/i.test(label);
 }
 
+function canUseOpenModelMenuForSelection(snapshot, selection) {
+  if (selection.modelFamily !== "instant" || selection.autoSwitchToThinking === true) return false;
+  return Boolean(findEntry(
+    snapshot,
+    (candidate) => candidate.kind === "menuitemradio" && matchesModelFamilyControl(candidate, selection.modelFamily),
+  ));
+}
+
 function composerControlsVisible(snapshot) {
   const entries = parseSnapshotEntries(snapshot);
   const hasComposer = entries.some(
@@ -802,25 +810,35 @@ function classifyChatPage({ job, url, snapshot, body, probe }) {
   const onAuthPath = typeof url === "string" && url.includes("/auth/");
   const hasUsableComposer = snapshotHasUsableComposerControls(snapshot);
 
-  if (probe?.status === 401 || (probe?.status === 403 && (!onAllowedOrigin || !hasUsableComposer || probe?.domLoginCta))) {
+  const probeHasAccountIdentity = probe?.bodyHasId === true || probe?.bodyHasEmail === true;
+
+  if (probe?.status === 401 || (probe?.status === 403 && (!onAllowedOrigin || !hasUsableComposer))) {
     return { state: "login_required", message: "ChatGPT login is required. Run /oracle-auth." };
   }
 
   if (onAuthPath || probe?.onAuthPage) {
-    if (probe?.bodyHasId || probe?.bodyHasEmail) {
+    if (probeHasAccountIdentity) {
       return {
         state: "auth_transitioning",
-        message: "ChatGPT is on an auth page even though the backend session is partially authenticated. Rerun /oracle-auth.",
+        message: "ChatGPT is on an auth page even though the backend probe returned account-like fields. Rerun /oracle-auth.",
       };
     }
     return { state: "login_required", message: "ChatGPT login is required. Run /oracle-auth." };
   }
 
+  if (onAllowedOrigin && hasUsableComposer && probe?.domLoginCta && !probeHasAccountIdentity) {
+    return {
+      state: "login_required",
+      message: "ChatGPT login is required: the chat shell still shows public Log in/Sign up controls. Run /oracle-auth.",
+    };
+  }
+
   if (onAllowedOrigin && (probe?.status === 200 || probe?.status === 403) && hasUsableComposer) {
-    if (probe?.domLoginCta && (probe?.bodyHasId || probe?.bodyHasEmail)) {
+    if (probe?.domLoginCta) {
+      // The public logged-out composer case returned above, so a remaining visible login CTA here still has account-like probe data.
       return {
         state: "auth_transitioning",
-        message: "ChatGPT backend session is authenticated, but the web shell still shows public login CTA chrome. Rerun /oracle-auth.",
+        message: "ChatGPT backend probe returned account-like fields, but the web shell still shows public login controls. Rerun /oracle-auth.",
       };
     }
     return { state: "authenticated_and_ready", message: "ChatGPT is authenticated and ready." };
@@ -875,7 +893,7 @@ async function waitForOracleReady(job) {
       }
       if (elapsedMs >= 15_000) {
         await captureDiagnostics(job, "preflight-auth-transition");
-        throw new Error("ChatGPT backend session is authenticated, but the web shell stayed in a partially logged-in state. Rerun /oracle-auth.");
+        throw new Error(classification.message || "ChatGPT auth did not settle into a ready chat shell. Rerun /oracle-auth.");
       }
       await sleep(1000);
       continue;
@@ -1009,6 +1027,7 @@ async function openModelConfiguration(job) {
     await agentBrowser(job, "wait", "800");
     const after = await snapshotText(job);
     if (snapshotHasModelConfigurationUi(after)) return after;
+    if (canUseOpenModelMenuForSelection(after, job.selection)) return after;
 
     const configureEntry = findEntry(
       after,
@@ -1020,6 +1039,7 @@ async function openModelConfiguration(job) {
       await agentBrowser(job, "wait", "1200");
       const postConfigure = await snapshotText(job);
       if (snapshotHasModelConfigurationUi(postConfigure)) return postConfigure;
+      if (canUseOpenModelMenuForSelection(postConfigure, job.selection)) return postConfigure;
     }
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-oracle",
-  "version": "0.6.16",
+  "version": "0.6.17",
   "description": "ChatGPT web-oracle extension for pi with isolated browser auth, async jobs, and project-context archives.",
   "private": false,
   "license": "MIT",