pi-oracle 0.7.21 → 0.7.22

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.7.22 - 2026-10-12
+
+### Documentation
+- rewrite the README around installation, first use, commands, and privacy; add an editable workflow diagram and move detailed setup and maintainer guidance into linked reference docs
+
+### Fixed
+- decrypt native Linux Chromium/Chromium Browser encrypted cookies with Chromium's safe-storage key, retaining GNOME/KWallet/basic controls and per-run password calibration without upgrading the unaffected Chrome/Brave importer
+- ignore custom-message agent starts in the `/oracle` user-command handler, so idle completion notifications can trigger a turn on newer Pi hosts without a missing-prompt error
+- wait for agent-browser's closing daemon to become launchable after its known pre-launch socket failure, retaining a bounded deadline and failing other launch errors immediately
+- wait for ChatGPT's Power slider to mount and focus its observed control rather than a brittle picker-container selector before selecting and verifying the requested tier
+
 ## 0.7.21 - 2026-09-26
 
 ### Fixed

package/README.md

@@ -1,450 +1,114 @@
 # pi-oracle
 
-`pi-oracle` lets a `pi` agent send hard, long-running work to ChatGPT.com or Grok 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.
+pi-oracle sends project files and questions from [Pi](https://github.com/earendil-works/pi) to ChatGPT or Grok through your web account. Each job uses an isolated browser and saves its answer locally.
 
-> Status: experimental public beta. Current source qualification baseline is official pi `0.86.1`; the platform-smoke harness covers macOS, Linux, and Windows native with Chromium-family browsers. Pi `0.80.9+` is the suggested tested floor for project-trust-aware package/runtime validation, but pi-bundled runtime packages remain optional wildcard peers so npm peer ranges do not block users from trying newer pi releases. Normal oracle jobs run in an isolated browser profile, not your active browser window.
+![Oracle workflow: Pi packages project files, an isolated browser sends them to ChatGPT or Grok, and Oracle saves the answer locally.](.github/readme/oracle-workflow.png)
 
-## What a successful run looks like
+## Install
 
-```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 provider archive (`.tar.zst` for ChatGPT, `.tar.gz` for Grok)
-  3. starts an isolated provider web runtime in the background
-  4. uploads the archive and prompt to the selected provider
-  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 the selected web provider 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 or Grok 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 provider 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, Grok, or another configured web provider
-- machines outside the currently supported local browser/tooling setup
-
-## Problem it solves
-
-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/Grok subscription, artifact downloads, or a durable result that arrives after the active turn ends.
-
-`pi-oracle` makes that workflow explicit and recoverable instead of asking the main agent to manually drive provider chat UIs in your real browser window.
+Use Node.js 22.19.0 or newer on macOS, Linux, or Windows native. Use a current Pi release and a Chromium-family browser.
 
-## What it does
+Install `agent-browser` and `tar`. Install `zstd` for ChatGPT jobs. Check the [platform requirements](docs/reference.md#requirements) for profile copies and encrypted cookies.
 
-| 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 the selected provider web app. | [`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` |
-| Provider auth can expire or drift. | `/oracle-auth [chatgpt|grok]` 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) |
-
-## Fastest way to see it work
-
-### 1. Install
-
-From npm:
+Install Oracle:
 
 ```bash
 pi install npm:pi-oracle
 ```
 
-Or from GitHub:
+Start a normal persisted `pi` session in your project directory:
 
 ```bash
-pi install https://github.com/fitchmultz/pi-oracle
+pi
 ```
 
-To update the package later, use `pi update --extensions`, `pi update --all`, or `pi update npm:pi-oracle`. Bare `pi update` updates pi itself only. Versioned npm/git refs stay pinned until you change the configured source.
-
-### 2. Check requirements
+Oracle cannot submit jobs from `pi --no-session`.
 
-You need:
+## First job
 
-- macOS, Linux, or Windows native
-- Node.js 22.19.0 or newer for package install/use; platform smoke/release validation currently expects Node 24+ per `platform-smoke.config.mjs`
-- Suggested tested floor: `pi` 0.80.9 or newer; older pi versions are not blocked by package metadata but are outside the current validation baseline
-- Google Chrome/Chromium or another Chromium-family browser
-- ChatGPT or Grok already signed in to the configured local browser profile for the provider you plan to use
-- `agent-browser` and `tar` available on the machine; `zstd` is also required when submitting ChatGPT `.tar.zst` archives
-- on macOS APFS clone mode, `cp` available on PATH or via `PI_ORACLE_CP_PATH`; Linux/Windows runtime profile copies use Node's recursive copy
-- a normal persisted `pi` session, not `pi --no-session`
-- on Linux, encrypted Chromium cookies may also require `secret-tool` (GNOME/libsecret) or `kwallet-query` + `dbus-send` (KDE), unless a Chrome/Brave safe-storage password override is set for the auth run
+Sign in to ChatGPT in your source browser profile. Your account must have access to the selected [preset](#settings).
 
-### 3. Sync provider auth once
+Import your login into Oracle:
 
 ```text
 /oracle-auth
 ```
 
-This reads cookies for the configured default provider from your local browser profile and writes an isolated oracle seed profile. Use `/oracle-auth grok` to force-refresh the Grok seed when your default provider is still ChatGPT. It should not automate your active browser window for normal jobs.
-
-### 4. Submit a tiny job
+Submit a small request:
 
 ```text
-/oracle Read README.md and package.json. Tell me in five bullets what this package does and who should not use it.
+/oracle Read README.md and package.json. Explain what this package does.
 ```
 
-Expected result:
+Oracle checks session and authentication readiness before gathering files. It returns a job id and response path after dispatch.
 
-- 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 selected provider's upload 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 the selected provider, capped at 250 MiB for ChatGPT or 200 MiB for Grok 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.
+Jobs can queue when browser capacity is full. Oracle sends a best-effort notification to the matching Pi session when a job finishes.
 
-If the wake-up does not arrive, run:
+If no notification arrives, find the job and read its answer:
 
 ```text
 /oracle-status
 /oracle-read <job-id>
 ```
 
-## Example requests
-
-```text
-/oracle Review the current pending changes. Include the whole repo unless a narrower archive is clearly better. Give me a prioritized code review with concrete fixes.
-```
-
-```text
-/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 250 MiB limit.
-```
-
-```text
-/oracle Continue existing ChatGPT conversation 6a28ab5c-e4d4-83e8-b8be-dd39f38a26d6. Review the current auth code and include enough surrounding context to propose concrete fixes.
-```
-
-## How it works
-
-```mermaid
-flowchart LR
-    A["/oracle request"] --> B["Agent preflights, then gathers a context-rich relevant repo slice"]
-    B --> C["Agent chooses context-rich archive inputs"]
-    C --> D["oracle_submit builds provider-specific archive"]
-    D --> E["Detached worker clones isolated auth seed profile"]
-    E --> F["Selected provider receives archive + prompt"]
-    F --> G["Response/artifacts saved under oracle job dir"]
-    G --> H["Best-effort wake-up to matching pi session"]
-```
-
-Key design choices:
-
-- **Extension-managed dispatch owns context gathering.** In the TUI, `/oracle` and `/oracle-followup` are intercepted before prompt-template expansion, re-added as compact user messages for prompt-history/up-arrow recall, and paired with detailed dispatch instructions as hidden context. The visible transcript stays compact while the agent still preflights, gathers context, chooses archive inputs, and stops 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 provider thread state.** `/oracle-followup <job-id> ...` resolves the prior job's saved provider URL and submits the next prompt with `followUpJobId`.
-- **Existing ChatGPT browser threads are opt-in.** Normal `/oracle` jobs still start a fresh provider thread. When the user explicitly provides a ChatGPT conversation id or `https://chatgpt.com/c/...` URL, the agent passes `chatGptConversationId` so `oracle_submit` opens that existing thread in the isolated runtime.
-- **Wake-up is best effort, storage is durable.** A missed wake-up does not lose the result.
-
-## Commands and tools
+## Commands
 
-User-facing commands:
-
-- `/oracle <request>` — prepare context and dispatch a ChatGPT or Grok web oracle job. If the request explicitly includes an existing ChatGPT conversation id/URL, the agent can continue that browser-created thread; otherwise `/oracle` starts a fresh thread as before.
-- `/oracle-followup <job-id> <request>` — continue an earlier oracle job in the same provider thread
-- `/oracle-auth [chatgpt|grok]` — sync provider 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:
+| Command | Purpose |
+| --- | --- |
+| `/oracle <request>` | Submit a question with project files. |
+| `/oracle-followup <job-id> <request>` | Continue the same provider thread. |
+| `/oracle-auth [chatgpt\|grok]` | Import a provider login from your source browser profile. |
+| `/oracle-read [job-id]` | Show status and a saved answer preview. |
+| `/oracle-status [job-id]` | Show status and recent job ids when no explicit id is given. |
+| `/oracle-cancel <job-id>` | Cancel a queued or active job. |
+| `/oracle-clean <job-id\|all>` | Delete finished-job files. A recent notification can delay cleanup; retry at the time shown. |
 
-- `oracle_preflight`
-- `oracle_auth`
-- `oracle_submit` (`chatGptConversationId` is optional and only for explicitly continuing an existing ChatGPT browser conversation id/URL; omit it for the default fresh thread)
-- `oracle_read`
-- `oracle_cancel`
+Normal `/oracle` jobs start a fresh provider thread. To continue an existing ChatGPT conversation, include its id or URL in your request.
 
-## Configuration
+Answers, logs and artifacts use `${PI_ORACLE_JOBS_DIR:-/tmp}/oracle-<job-id>/`.
 
-Most users can start with defaults. Set an agent-level config only when you need a non-default provider, mode, preset, or browser profile.
+By default, Oracle deletes completed and cancelled jobs after 14 days. It deletes failed jobs after 30 days. Copy files you need to keep. See [retention settings](docs/reference.md#job-retention) for details.
 
-Pi 0.79+ gates project-local inputs behind project trust. `pi-oracle` preserves its historical risk-on extension behavior for existing users: project-local `.pi/extensions/oracle.json` safe overrides still load by default for compatibility. They are ignored when you explicitly opt out of project-local inputs with `--no-approve` or save a “do not trust” decision for the project. Privileged browser/auth settings still come only from the agent-level config.
+## Settings
 
-`~/.pi/agent/extensions/oracle.json`
+Oracle uses ChatGPT and the `pro_extended` preset by default. Change the defaults in `~/.pi/agent/extensions/oracle.json`:
 
 ```json
 {
   "defaults": {
     "provider": "chatgpt",
-    "preset": "<preset id from ORACLE_SUBMIT_PRESETS>",
-    "grokMode": "heavy"
-  },
-  "auth": {
-    "chromeProfile": "Default"
+    "preset": "thinking_light"
   }
 }
 ```
 
-Notes:
+For Grok, run `/oracle-auth grok` first. Name Grok in your `/oracle` request. Grok supports Heavy only.
 
-- `defaults.provider` is the default web provider: `chatgpt` or `grok`.
-- `defaults.preset` is the default ChatGPT model preset for oracle jobs.
-- `defaults.grokMode` is the default Grok mode. Only `heavy` is supported today.
-- The canonical preset ids and provider modes live in [`extensions/oracle/lib/config.ts`](extensions/oracle/lib/config.ts).
-- If the packaged default is fine, omit `defaults`.
-- When an agent is unsure which oracle preset fits, it should omit `preset` and use the configured default model instead of asking by default. If the prompt says to use Grok, it should pass `provider: "grok"` to `oracle_submit`.
-- You usually do not need browser paths unless auto-detection fails.
+ChatGPT accepts archives up to 250 MiB; Grok accepts up to 200 MiB. See [providers and presets](docs/reference.md#available-providers-and-presets) for archive formats, preset ids and model-picker limits.
 
-### Linux cookie import notes
+Browser and authentication settings use the agent-level config. See [configuration](docs/reference.md#configuration) for project trust rules and custom cookie sources.
 
-`/oracle-auth` delegates the default cookie read to `@steipete/sweet-cookie`'s Linux Chrome/Chromium backend. The packaged default auto-detects existing Google Chrome, Chromium, Chromium Browser, or Brave profile roots under `${XDG_CONFIG_HOME:-~/.config}` and passes non-Google roots as absolute profile paths so the correct cookie DB is read. Set `auth.chromeProfile` to another profile name, a profile directory, or a `Cookies` DB path when needed, and leave `auth.chromiumKeychain` unset on Linux.
+To update Oracle, run `pi update npm:pi-oracle`. See [installation options](docs/reference.md#installation-options) for GitHub installs and other update commands.
 
-Sweet Cookie's Linux encrypted-cookie handling is controlled outside pi-oracle:
+## Limits and privacy
 
-- `SWEET_COOKIE_LINUX_KEYRING=gnome|kwallet|basic` selects GNOME/libsecret, KDE KWallet, or no keyring probing.
-- GNOME probing shells out to `secret-tool`; KDE probing shells out to `kwallet-query` and `dbus-send`.
-- `SWEET_COOKIE_CHROME_SAFE_STORAGE_PASSWORD` and `SWEET_COOKIE_BRAVE_SAFE_STORAGE_PASSWORD` bypass keyring probing when you already know the browser safe-storage password.
+**Experimental public beta.** Provider pages can change and cause jobs to fail. Check [troubleshooting](docs/reference.md#troubleshooting) if authentication or a job fails.
 
-Do not put safe-storage passwords in project config or persistent shell startup files. Prefer keyring helpers when possible; if you use an environment override for one `/oracle-auth` run, pi-oracle scrubs it before launching browser/helper subprocesses after cookie import.
+**Oracle uploads project files to ChatGPT or Grok.** The agent chooses the files. It adds nearby files for context and can send the whole repository for broad or unclear requests.
 
-### Custom Chromium cookie sources
+Default exclusions do not guarantee that an archive contains no sensitive data. Specify an exact file list for private material. Tell the agent to exclude all other files.
 
-Most Chrome/Chromium-compatible browsers should work through Sweet Cookie's default Chrome backend when `auth.chromeProfile` points at the right profile or cookie DB. pi-oracle does not currently select Sweet Cookie's Edge or Firefox backends. The `auth.chromiumKeychain` alternate path is macOS-only and is intended for a Chromium-family browser that is not one of Sweet Cookie's built-in Chrome/Brave/Arc/Chromium targets or otherwise cannot import cookies without dependency patching.
+Oracle reads provider cookies from your source browser profile. It copies the login into an isolated profile for each job.
 
-Before running `/oracle-auth` with this macOS path:
+Cookie imports do not preserve host-only or partitioned-cookie isolation metadata. Keep browser safe-storage passwords out of project config and shell startup files.
 
-1. Log into ChatGPT or Grok in the target browser profile, depending on `defaults.provider`.
-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 `~/.pi/agent/extensions/oracle.json`.
+## Details
 
-Example macOS Helium config:
-
-```json
-{
-  "browser": {
-    "executablePath": "/Applications/Helium.app/Contents/MacOS/Helium"
-  },
-  "auth": {
-    "chromeProfile": "Default",
-    "chromeCookiePath": "/Users/you/Library/Application Support/net.imput.helium/Default/Cookies",
-    "chromiumKeychain": {
-      "account": "Helium",
-      "services": ["Helium Storage Key"],
-      "label": "Helium Storage Key"
-    }
-  }
-}
-```
-
-`auth.chromeCookiePath` remains the cookie database path for backward compatibility. On macOS, `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 on macOS, `/oracle-auth` uses pi-oracle's repo-owned generic Chromium cookie reader instead of patching `@steipete/sweet-cookie` internals. On Linux, `auth.chromiumKeychain` is rejected; use Sweet Cookie's Linux keyring/password environment options instead.
-
-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`. On Linux, inspect `/oracle-auth` diagnostics for Sweet Cookie warnings about `secret-tool`, `kwallet-query`, or safe-storage password overrides.
-
-## Available providers and presets
-
-| Provider | Mode / preset | Archive format | Upload ceiling |
-| --- | --- | --- | --- |
-| ChatGPT | Presets below | `.tar.zst` | 250 MiB |
-| Grok | `heavy` only | `.tar.gz` | 200 MiB |
-
-Grok uploads now use `.tar.gz` archives. Grok may accept `.tar.zst` uploads, but its execution environment can lack `zstd` tooling to extract them; gzip-compressed tar keeps extraction on standard tools. Manual testing against `https://grok.com` found a 200 MiB upload is accepted and a 200 MiB + 1 byte upload is rejected, so pi-oracle caps Grok archives at 200 MiB.
-
-## Available ChatGPT presets
-
-| Preset id | Description |
-| --- | --- |
-| `pro_standard` | Pro - Standard |
-| `pro_extended` | Pro - Extended |
-| `thinking_light` | Thinking - Light |
-| `thinking_standard` | Thinking - Standard |
-| `thinking_extended` | Thinking - Extended |
-| `thinking_heavy` | Thinking - Heavy |
-| `instant` | Instant |
-| `instant_auto_switch` | Instant - Auto-switch to Thinking Enabled |
-
-For ChatGPT, `oracle_submit` accepts canonical preset ids or a matching human-readable preset label. Keep config values on canonical ids. For Grok, use `provider: "grok"`; only Heavy is supported today.
-
-ChatGPT's compact picker and current **Power** slider expose fewer choices than the legacy settings dialog: both Instant presets use Instant when no auto-switch toggle exists; Thinking Light/Standard use Medium, Extended uses High, and Heavy uses Extra High. Both Pro presets use the single Pro tier when separate effort choices are unavailable. Oracle verifies the visible selection rather than assuming the saved preference.
-
-## Outputs and cleanup
-
-- 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.
-
-## Privacy and local data
-
-This extension is local-first, but it handles sensitive local and project data:
-
-- `/oracle-auth` reads provider cookies from the configured local browser profile. Use `/oracle-auth grok` for Grok when ChatGPT remains the default provider.
-- `oracle_submit` uploads selected project archives to the selected provider web app.
-- Responses, logs, and artifacts are written to the configured oracle jobs directory.
-
-Review the code and design docs before using it with private or regulated material.
-
-## Current limits
-
-- Experimental public beta, validated on macOS, Linux, and Windows native with Chromium-family browsers.
-- Provider UI, auth, model controls, and artifact download behavior can drift.
-- Archive uploads are capped at 250 MiB for ChatGPT and 200 MiB for Grok after default exclusions and automatic whole-repo pruning.
-- A real ChatGPT or Grok web session is required for the provider you use.
-- 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, platform compatibility, and environment diagnostics.
-
-## Troubleshooting
-
-### `/oracle-auth` fails or says login is required
-
-- Make sure the selected provider works in the same local browser profile you configured.
-- For custom Chromium cookie sources, confirm `auth.chromeCookiePath` points at that profile's `Cookies` DB. On macOS, also confirm `auth.chromiumKeychain.services` names the browser's safe-storage Keychain service. On Linux, leave `auth.chromiumKeychain` unset and use Sweet Cookie's `SWEET_COOKIE_LINUX_KEYRING`, `SWEET_COOKIE_CHROME_SAFE_STORAGE_PASSWORD`, or `SWEET_COOKIE_BRAVE_SAFE_STORAGE_PASSWORD` options for encrypted Chrome/Chromium/Brave cookies.
-- Re-run `/oracle-auth`.
-- Agent callers can use `oracle_auth({})` once before retrying a stale-auth oracle submission.
-- If ChatGPT reports an anonymous visitor session, sign in in the configured **source browser profile**, quit that browser fully, and rerun `/oracle-auth`. This command imports an existing login; the isolated verification window is not a manual-login setup flow.
-- Navigation interruptions during verification are retried until the auth deadline. A closed browser or verification timeout does not by itself mean the source cookies are invalid; leave the isolated window open and inspect the printed diagnostics if retries fail.
-- If the provider presents a challenge and Oracle explicitly leaves the headed auth browser open, complete the challenge there and retry.
-
-### Custom Chromium auth says cookies synced but the session is rejected
-
-This usually means the cookie import worked but the source cookies are not the active provider session you expected.
-
-1. Open the configured browser profile.
-2. Confirm the selected provider works there without logging in again.
-3. Quit the browser fully so its `Cookies` DB is stable.
-4. Confirm `auth.chromeCookiePath` points at that exact profile's `Cookies` DB.
-5. On macOS, confirm `auth.chromiumKeychain.services` names the browser's safe-storage Keychain service for that DB. On Linux, confirm the relevant Sweet Cookie keyring helper or Chrome/Brave safe-storage password override is available.
-6. Re-run `/oracle-auth`.
-
-### You hit a challenge or verification page
-
-- Solve it in the auth/bootstrap browser if prompted.
-- Re-run `/oracle-auth` before submitting jobs again.
-
-### You see "Oracle requires a persisted pi session"
-
-- Do not run oracle from `pi --no-session`.
-- Start a normal persisted `pi` session, then use `/oracle` again.
-
-### A job finished but no wake-up arrived
-
-- Use `/oracle-read [job-id]` to inspect the saved response preview.
-- 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 returns a `Retry after ...` timestamp when that guard is active.
-- Wait until that time, then rerun `/oracle-clean <job-id|all>`.
-
-### A local dependency like `agent-browser`, `tar`, or `zstd` is missing
-
-Install the missing local dependency and rerun the command. `zstd` is only needed for ChatGPT `.tar.zst` archive submissions; Grok submissions use `.tar.gz`. On macOS APFS clone mode, `cp` must also be available on PATH or configured with `PI_ORACLE_CP_PATH`; Linux and Windows profile copies use Node's recursive copy.
-
-### Auto-detection picked the wrong browser profile
-
-- Set `auth.chromeProfile` in `~/.pi/agent/extensions/oracle.json`.
-- For custom Chromium cookie sources, set `auth.chromeCookiePath` to the exact profile `Cookies` DB. Pair it with `auth.chromiumKeychain` only on macOS; on Linux, rely on Sweet Cookie's keyring/password environment options.
-- Re-run `/oracle-auth`.
-
-### 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.
-
-## Verification
-
-For credential-free host qualification, run `npm ci --ignore-scripts` then `npm run check:compat` with an empty HOME/agent profile. It runs the existing syntax, type, isolated sanity, and pack checks plus native Pi `/oracle-status` dispatch, asserting that no browser job is created. Sanity uses fixture browser/keychain commands and private job/state directories; it needs local archive utilities (`tar` and `zstd`), not browser credentials. This is source/host proof, not authenticated ChatGPT/Grok or packed cross-platform release proof. The older suggested floor is historical support guidance, not requalified by a current-host run.
-
-Useful local checks:
-
-```bash
-npm run check:oracle-extension
-npm run check:platform-smoke
-npm run typecheck
-npm run typecheck:worker-helpers
-npm run sanity:oracle
-npm run pack:check
-npm test
-npm run verify:oracle
-```
-
-`npm test` runs `npm run verify:oracle`, so it is not a separate gate from the final line above.
-
-`npm publish` is guarded by `prepublishOnly`, which runs `npm run release:check`. That release gate now blocks unless fresh live ChatGPT preset proof exists for every canonical preset, then requires doctor-first macOS, Ubuntu, and Windows native Crabbox evidence. The required Crabbox runtime suite uses packed-install proof, not source-tree `pi -e` loading.
-
-Use the narrowest validation workflow that proves the change:
-
-| Situation | Command(s) |
-| --- | --- |
-| Everyday local iteration | `npm run verify:oracle` |
-| Platform-focused syntax/invariant sanity | `npm run check:platform-smoke`, `npm run sanity:oracle:platform` |
-| Platform-sensitive runtime changes | `npm run smoke:platform:doctor`, then a focused `node scripts/platform-smoke.mjs run --target <target> --suite <suite>` |
-| Platform matrix proof | `npm run smoke:platform:all` |
-| ChatGPT preset release proof | `npm run release:proof:chatgpt-presets` |
-| Publish/release gate | `npm run release:check` |
-
-For macOS, Ubuntu, and Windows native package/build plus packed runtime validation, use [`docs/platform-smoke.md`](docs/platform-smoke.md). The full release gate is:
-
-```bash
-npm run release:check
-```
-
-Before a release, run live jobs through the loaded extension for every ChatGPT preset in `ORACLE_SUBMIT_PRESETS`. Each prompt must make the saved response contain exact markers `PRESET <preset> OK` and `PACKAGE pi-oracle`. After every job has completed, save the job ids/job directories in `.artifacts/chatgpt-preset-proof/latest.json`; `validatedAt` must be later than the completed jobs. Start from the checked, intentionally non-valid template:
-
-```bash
-mkdir -p .artifacts/chatgpt-preset-proof
-node scripts/oracle-chatgpt-preset-proof.mjs template > .artifacts/chatgpt-preset-proof/latest.json
-npm run release:proof:chatgpt-presets
-```
-
-The proof checker is intentionally part of `release:check`; it fails if the proof is missing, stale, tied to a different package version/git head, references jobs that completed before the current commit, or lacks actual persisted ChatGPT `.tar.zst` job state and response text for any canonical preset.
-
-The real runtime suite defaults to deterministic installed-tool execution so platform proof stays bounded. Provider/model defaults remain `zai/glm-5.2` for doctor/config and for optional model-agent debugging; override with `PI_ORACLE_REAL_TEST_PROVIDER` and `PI_ORACLE_REAL_TEST_MODEL` when needed. For inner-loop source loading only, use `npm run smoke:real:source`; it is not release proof. Set `PI_ORACLE_REAL_TEST_MODEL_AGENT=1` only when debugging the slower model-agent path. The optional second real-agent negative symlink check is opt-in via `PI_ORACLE_REAL_TEST_NEGATIVE_SYMLINK=1`; `npm run sanity:oracle` covers archive/symlink rejection by default without adding another model-agent turn to the platform release gate.
-
-For manual end-to-end local-extension smoke testing, use [`docs/ORACLE_ISOLATED_PI_VALIDATION.md`](docs/ORACLE_ISOLATED_PI_VALIDATION.md). Ordinary pre-commit smoke runs can still use `instant` or `thinking_light`, but release proof must cover every canonical ChatGPT preset through the loaded extension.
-
-## Project map
-
-| 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 provider web worker and UI/auth helpers |
-| `extensions/oracle/shared/` | Shared process, state, job, and observability helpers |
-| [`prompts/oracle.md`](prompts/oracle.md) | Hidden `/oracle` command-dispatch workflow |
-| [`prompts/oracle-followup.md`](prompts/oracle-followup.md) | Hidden `/oracle-followup` command-dispatch workflow |
-| `scripts/oracle-sanity-*` | Local sanity and archive-safety checks |
-| `scripts/platform-smoke*` | Crabbox macOS, Ubuntu, and Windows release smoke gate |
-| [`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).
+- [Reference](docs/reference.md): examples, commands, presets, authentication setup and troubleshooting.
+- [Design](docs/ORACLE_DESIGN.md): archives, queue, job state and notifications.
+- [Development](docs/development.md): checks, host compatibility and release gates.
+- [Report a problem](https://github.com/fitchmultz/pi-oracle/issues). Remove sensitive data from job diagnostics before you share them.
 
 ## License
 
-MIT. See `LICENSE`.
+MIT. See [LICENSE](LICENSE).

package/docs/ORACLE_DESIGN.md

@@ -291,7 +291,7 @@ Project config remains restricted to safe overrides only. On Pi 0.79+, pi itself
 
 `browser.cloneStrategy` defaults to `apfs-clone` on macOS and `copy` on Linux/Windows. macOS APFS clone mode uses `cp -cR` and preflights `cp`; set `PI_ORACLE_CP_PATH` only when the default PATH lookup cannot find the intended copy executable. Linux and Windows runtime profile copies use Node's recursive copy instead of depending on POSIX `cp`.
 
-The default `/oracle-auth` cookie importer delegates to `@steipete/sweet-cookie`'s Chrome/Chromium backend. On Linux, pi-oracle auto-detects existing Google Chrome, Chromium, Chromium Browser, or Brave profile roots under `${XDG_CONFIG_HOME:-~/.config}` and passes non-Google roots as absolute profile paths so Sweet Cookie reads the intended cookie DB. pi-oracle does not currently select Sweet Cookie's Edge or Firefox backends. Encrypted Linux Chromium cookies are handled by Sweet Cookie via `secret-tool`, `kwallet-query`/`dbus-send`, `SWEET_COOKIE_LINUX_KEYRING=gnome|kwallet|basic`, or the `SWEET_COOKIE_CHROME_SAFE_STORAGE_PASSWORD` / `SWEET_COOKIE_BRAVE_SAFE_STORAGE_PASSWORD` overrides. Prefer keyring helpers over password environment variables; if a password override is used for `/oracle-auth`, pi-oracle scrubs it before launching browser/helper subprocesses after cookie import.
+The default `/oracle-auth` cookie importer uses `@steipete/sweet-cookie` 0.3's public Chrome backend. On Linux, pi-oracle auto-detects existing Google Chrome, Chromium, Chromium Browser, or Brave profile roots under `${XDG_CONFIG_HOME:-~/.config}` and passes non-Google roots as absolute profile paths. After confirming a native `chromium`/`chromium-browser` profile or explicit `Cookies` DB under those same roots needs key selection, the worker dynamically imports `linux-chromium-cookie-source.mjs` and passes its already-loaded public getter (without another runtime dependency import). Chrome/Brave and other platforms keep the existing dependency path; the macOS `chromium-cookie-source.mjs` contains no Linux key-selection code. It retains Sweet Cookie parsing/decryption, GNOME service/account then application lookup, KDE versioned KWallet network-wallet lookup with `kdewallet` fallback, `SWEET_COOKIE_LINUX_KEYRING=gnome|kwallet|basic`, 3-second helper deadlines, non-secret warnings, and `SWEET_COOKIE_CHROME_SAFE_STORAGE_PASSWORD` calibration (including Chromium). Oracle-owned keyring helpers receive password-scrubbed environments. The worker temporarily supplies the selected key through Sweet Cookie's supported Chrome and Brave password overrides: 0.3 classifies Brave by substrings anywhere in the DB path, including an unrelated XDG/HOME ancestor. Mirroring the key prevents that branch from probing a vendor keyring with the Chromium secret inherited. The Chrome override remains the Chromium calibration control. Before native qualification or loading the Linux module, a nonempty trimmed Chrome override bypasses native qualification and the environment transaction only for explicit paths whose Sweet Cookie-expanded candidate contains no case-insensitive Brave selector. Tilde and relative paths are expanded as Sweet Cookie does; absolute text is retained because a literal `Cookies` path can still contain a Brave selector before a `..` segment. Profile names and ambiguous candidates retain the normal source-selection path. Empty-key fallback suppresses both password overrides and selects `basic`; both prior passwords and the backend are restored in `finally`. Parent Pi/global config is not changed. Relocated, Snap, and Flatpak Chromium sources are outside automatic key selection; a per-run matching Chrome or Brave password override can calibrate a relocated source. For unqualified sources, Sweet Cookie 0.3 still selects Brave when the resolved DB path contains `bravesoftware`, `brave-browser`, or `brave browser` (case-insensitive), including an ancestor directory; such paths may require the Brave override. This narrow adapter retains Sweet Cookie 0.3's public parser/decryptor. Remove it once an upstream fix passes equivalent successful-path performance checks. pi-oracle does not select Sweet Cookie's Edge or Firefox backends. Browser/helper subprocesses launched by Oracle receive password-scrubbed environments; this guarantee does not cover upstream fallback helpers for unqualified sources. Cookie replay remains domain-based; host-only/partition isolation is not repaired by this key-selection fix.
 
 `auth.chromiumKeychain` is a macOS-only opt-in alternate cookie source for Chromium-family browsers that are not handled by the default `@steipete/sweet-cookie` Chrome-compatible importer. It must be configured with `auth.chromeCookiePath`; partial config is rejected so `/oracle-auth` cannot silently fall back to a different browser profile. On Linux, valid config should leave `auth.chromiumKeychain` unset and use Sweet Cookie's Linux keyring/password options instead.