pi-oracle 0.7.21 → 0.7.23

package/docs/development.md

@@ -0,0 +1,99 @@
+# Development and release reference
+
+The [README](../README.md) is the user entry point. Architecture and lifecycle details live in [ORACLE_DESIGN.md](ORACLE_DESIGN.md).
+
+## Host qualification
+
+Required offline qualification targets are the latest stable official Pi and latest maintained fork `main`, resolving version/commit once per workflow run and retaining exact SDK/CLI evidence. Locked development dependencies are reproducible snapshots, not validation targets; 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.
+
+Package install/use requires Node.js 22.19.0 or newer; platform smoke/release validation expects Node 24+ per `platform-smoke.config.mjs`.
+
+Production hardening should keep focusing on UI drift detection, auth recovery, artifact capture, platform compatibility, and environment diagnostics.
+
+## Automatic npm releases (maintainers)
+
+The [shared release procedure](https://github.com/fitchmultz/.github#automatic-npm-releases) creates a reviewed patch-version PR after changes merge to `main`, then qualifies one retained candidate tarball across compatibility checks and hosted macOS, Ubuntu, and native Windows Crabbox suites before publishing the same version on npm and GitHub.
+
+Before releasing runtime or prompt changes, verify [the `release:check` requirements](#verification) and [packed platform proof](platform-smoke.md). Fresh all-preset ChatGPT proof must match `HEAD` or an ancestor commit whose `extensions/` and `prompts/` trees are byte-identical to `HEAD`, satisfy the proof checker's 72-hour timing and saved-response requirements, and accompany the required doctor-first macOS/Ubuntu/native-Windows evidence. Authenticated and paid checks remain outside CI. Automated publication disables npm hooks to publish the checked bytes; manual `npm publish` still runs its existing `prepublishOnly` gate.
+
+Set repository variable `NPM_RELEASE_ENABLED` to anything other than `true` to stop new version and release plans; cancel pending runs separately when needed. Follow the shared procedure to retry an unpublished candidate. Workflow validation is not evidence of a completed real OIDC publication.
+
+## Verification
+
+For credential-free latest-host qualification, use the shared qualifier with `--host official --target latest` and separately with the packed latest maintained fork revision. It selects a consistent host graph before running `npm run check:compat` with an empty HOME/agent profile. A plain `npm ci --ignore-scripts` uses only the locked development snapshot, not latest qualification. 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.
+
+Known development dependency warning: the official Pi 1.0.0 npm package's `npm-shrinkwrap.json` still pins `brace-expansion` `5.0.9`, which has brace-expansion denial-of-service advisories. npm 11 preserves that vendor-pinned subtree even with a root override; dropping the shrinkwrap to obtain a clean audit is not a fix. The warning predates the Pi 1.0 baseline upgrade and needs an upstream host dependency fix. Dependencies embedded in a prebuilt Pi CLI bundle likewise require a fixed host distribution.
+
+`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`](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 commit whose `extensions/` or `prompts/` differ from `HEAD`, references jobs that completed before the proven 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`](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.
+
+## Implementation entry points
+
+| 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`](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`](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) |
+
+## 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`](ORACLE_DESIGN.md) | Architecture, lifecycle, queueing, persistence, recovery behavior |
+| [`docs/ORACLE_ISOLATED_PI_VALIDATION.md`](ORACLE_ISOLATED_PI_VALIDATION.md) | Repeatable isolated `pi` validation workflow |
+| [`docs/ORACLE_RECOVERY_DRILL.md`](ORACLE_RECOVERY_DRILL.md) | Safe expired-auth recovery drill |

package/docs/platform-smoke.md

@@ -29,9 +29,10 @@ crabbox providers
 
 Target setup:
 
-- macOS: Remote Login enabled; noninteractive `ssh $USER@localhost` works; `node`, `npm`, `git`, `tar`, `rsync`, `zstd`, and `agent-browser` are on the SSH PATH.
+- macOS: Remote Login enabled; noninteractive `ssh $USER@localhost` works; `node`, `npm`, `git`, `tar`, `rsync`, `zstd`, and `agent-browser` are on the SSH PATH. Use `PI_ORACLE_SMOKE_MAC_PORT` or `PLATFORM_SMOKE_MAC_PORT` for a non-default SSH port.
 - Ubuntu: Docker is running and the configured image (`PI_ORACLE_SMOKE_UBUNTU_IMAGE`, default `pi-oracle-platform-smoke:node24`) has `node`, `npm`, `git`, `tar`, `rsync`, `zstd`, and `agent-browser` on PATH. Build the local image when needed with `docker build -t pi-oracle-platform-smoke:node24 -f scripts/platform-smoke/Dockerfile.ubuntu .`.
-- Windows native: Parallels has stopped source VM `pi-extension-windows-template` and the configured power-off snapshot (`crabbox-ready` by default for this repo). The template must have OpenSSH, PowerShell, Git, Node/npm, `tar`, `zstd`, and `agent-browser` on PATH. Do not bake API keys, browser sessions, project checkouts, `.pi` state, artifacts, or secrets into the template.
+- Windows native: by default, Parallels has stopped source VM `pi-extension-windows-template` and the configured power-off snapshot (`crabbox-ready` by default for this repo). The template must have OpenSSH, PowerShell, Git, Node/npm, `tar`, `zstd`, and `agent-browser` on PATH. Do not bake API keys, browser sessions, project checkouts, `.pi` state, artifacts, or secrets into the template.
+- Alternatively, set `PI_ORACLE_SMOKE_WINDOWS_HOST` to a native Windows SSH host, and set `PI_ORACLE_SMOKE_WINDOWS_USER`, `PI_ORACLE_SMOKE_WINDOWS_PORT` (default 22), and `PI_ORACLE_SMOKE_WINDOWS_NATIVE_WORK_ROOT` for that target as needed. Crabbox uses its SSH provider instead of Parallels; the target needs the same tools on its SSH PATH. The `PLATFORM_SMOKE_WINDOWS_*` aliases also work.
 
 Real runtime suite auth:
 
@@ -47,7 +48,7 @@ Use the narrowest workflow that proves the change. Do not run the full platform
 | Situation | Canonical command(s) | What it proves |
 | --- | --- | --- |
 | Everyday local iteration | `npm run verify:oracle` | Syntax, bundle, platform-smoke invariants, type checks, oracle sanity, and package dry-run pass locally. |
-| Platform-sensitive change | `npm run smoke:platform:doctor`, then `node scripts/platform-smoke.mjs run --target <target> --suite <suite>` | Target setup is ready and the affected platform/suite works without paying for unrelated targets. |
+| Platform-sensitive change | `node scripts/platform-smoke.mjs doctor --target <target>`, then `node scripts/platform-smoke.mjs run --target <target> --suite <suite>` | Target setup is ready and the affected platform/suite works without paying for unrelated targets. |
 | Platform matrix proof | `npm run smoke:platform:all` | Doctor-first packed-install proof passes on every required target and suite. |
 | ChatGPT preset release proof | `npm run release:proof:chatgpt-presets` | Fresh loaded-extension proof exists for every canonical ChatGPT preset. |
 | Publish/release gate | `npm run release:check` | Local verification (`verify:oracle`) passes, fresh ChatGPT preset proof exists, then the doctor-first platform matrix passes. |
@@ -65,13 +66,19 @@ npm run smoke:platform:all
 Focused commands:
 
 ```bash
-npm run smoke:platform:doctor
+node scripts/platform-smoke.mjs doctor --target macos
 npm run smoke:platform:macos
+node scripts/platform-smoke.mjs doctor --target ubuntu
 npm run smoke:platform:ubuntu
+node scripts/platform-smoke.mjs doctor --target windows-native
 npm run smoke:platform:windows-native
 node scripts/platform-smoke.mjs run --target windows-native --suite real-extension
 ```
 
+`doctor --target` checks the selected targets' providers and tools; without it,
+doctor still checks every required target. In split hosted jobs, run a scoped
+doctor on each target before its suites.
+
 Full release gate:
 
 ```bash
@@ -80,6 +87,10 @@ npm run release:check
 
 `release:check` runs `verify:oracle`, then `release:proof:chatgpt-presets`, then `smoke:platform:all`, matching the release order: cheap harness checks, fresh live ChatGPT preset proof, doctor, full matrix, then artifact review. `prepublishOnly` runs `npm run release:check`.
 
+For an already prepared release candidate, set `PI_ORACLE_RELEASE_TARBALL` to its local tarball before running the matrix. Set `PI_ORACLE_RELEASE_SHA256` to the prepared candidate's SHA-256 when one is available; the runner checks it before transfer. Each suite still checks that the source packs, but installs the retained candidate. Crabbox transfers a temporary copy and each target verifies its SHA-256 before use; the suite evidence records the verified hash.
+
+The reusable [hosted platform qualification](../.github/workflows/release-platform.yml) runs each target on its native GitHub-hosted OS. It verifies the shared candidate receipt and source before and after both suites, and retains the per-target evidence. This is the platform portion of release qualification; the live ChatGPT preset proof is a separate required gate.
+
 ## What `platform-build` proves
 
 On each required target, `platform-build`:
@@ -103,10 +114,10 @@ On each required target, `platform-build`:
 2. installs the tarball into a clean pi project;
 3. runs `pi install -l ./node_modules/pi-oracle --approve`;
 4. asserts `pi list --approve` shows the packed install path;
-5. executes `oracle_submit` from the installed package path, not source `pi -e`;
-6. asserts whole-project archive creation and default exclusions.
+5. executes the deterministic `/oracle-status` command through the installed extension's Pi loader;
+6. asserts the command output came from the loaded packed extension and that the safe default path created no oracle job.
 
-The default runtime suite executes the installed tool directly so platform proof is deterministic and bounded instead of waiting on a model turn. Set `PI_ORACLE_REAL_TEST_MODEL_AGENT=1` only when you specifically need to debug the slower model-agent path. Symlink escape rejection and other negative archive cases are covered by `npm run sanity:oracle`; the optional second-agent negative check is available with `PI_ORACLE_REAL_TEST_NEGATIVE_SYMLINK=1` when debugging that path.
+The default runtime suite executes a deterministic command through the installed extension's Pi loader so platform proof is bounded instead of waiting on a model turn. Set `PI_ORACLE_REAL_TEST_MODEL_AGENT=1` only when you specifically need to debug the slower model-agent path. Symlink escape rejection and other negative archive cases are covered by `npm run sanity:oracle`; the optional second-agent negative check is available with `PI_ORACLE_REAL_TEST_NEGATIVE_SYMLINK=1` when debugging that path.
 
 For inner-loop/debug only, use:
 

package/docs/reference.md

@@ -0,0 +1,338 @@
+# Oracle reference
+
+Start with the [README](../README.md) for installation and your first job. This page covers command details, browser configuration, provider controls, and troubleshooting.
+
+## Installation options
+
+Install from GitHub:
+
+```bash
+pi install https://github.com/fitchmultz/pi-oracle
+```
+
+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.
+
+## Requirements
+
+You need:
+
+- 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
+
+`agent-browser` has its own Node.js requirements, which may be newer than Oracle's package minimum.
+If npm blocks `agent-browser`'s install script, allow it when installing the global package:
+
+```bash
+npm install -g --allow-scripts=agent-browser agent-browser
+```
+
+## What a successful run looks like
+
+```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.
+
+## Dispatch details
+
+After you submit an `/oracle` request:
+
+- 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.
+
+If the wake-up does not arrive, run:
+
+```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 Oracle reference guidance for /oracle-clean retention grace. Archive docs/reference.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
+
+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:
+
+- `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`
+
+## Configuration
+
+Most users can start with defaults. Set an agent-level config only when you need a non-default provider, mode, preset, or browser profile.
+
+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.
+
+`~/.pi/agent/extensions/oracle.json`
+
+```json
+{
+  "defaults": {
+    "provider": "chatgpt",
+    "preset": "pro_extended",
+    "grokMode": "heavy"
+  },
+  "auth": {
+    "chromeProfile": "Default"
+  }
+}
+```
+
+Notes:
+
+- `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.
+
+### Linux cookie import notes
+
+`/oracle-auth` uses `@steipete/sweet-cookie`'s public Chrome backend to parse and decrypt Linux cookies. 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. For native `chromium` and `chromium-browser` profiles or `Cookies` DBs under those roots, Oracle selects **Chromium Safe Storage** rather than Chrome's key, including GNOME application lookup fallback and KDE KWallet. The Linux key-selection module loads only when needed and reuses the worker's existing public cookie getter; ordinary calibrated Chrome-password paths bypass it. Set `auth.chromeProfile` to another profile name, a profile directory, or a `Cookies` DB path when needed, and leave `auth.chromiumKeychain` unset on Linux. Profile names alone still select Google Chrome; relocated, Snap, and Flatpak Chromium sources are outside this automatic key-selection boundary.
+
+Linux encrypted-cookie handling is controlled outside pi-oracle:
+
+- `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` (also for a selected Chromium source) and `SWEET_COOKIE_BRAVE_SAFE_STORAGE_PASSWORD` bypass keyring probing when you already know the browser safe-storage password.
+
+Do not put safe-storage passwords in project config or persistent shell startup files. Prefer keyring helpers when possible. Oracle's native Chromium adapter scrubs password overrides from keyring subprocesses, uses the obtained password only around the public cookie read in the short-lived auth worker, and restores its prior environment in `finally`. Browser/helper subprocesses launched by Oracle receive a scrubbed environment; this guarantee does not cover upstream fallback helpers for unqualified sources. The parent Pi environment and persistent config are not changed.
+
+### Custom Chromium cookie sources
+
+Chrome-compatible browsers can use Sweet Cookie's default Chrome backend when `auth.chromeProfile` points at the right profile or cookie DB and the matching safe-storage key is available. On Linux, automatic Chromium-specific key selection is limited to the native roots described above; for relocated Chromium profiles use the matching Chrome or Brave password override for that auth run. Outside the confirmed native roots, Sweet Cookie 0.3 still selects Brave when the resolved cookie DB path contains `bravesoftware`, `brave-browser`, or `brave browser` (case-insensitive), even in an ancestor directory; such paths may require the Brave override. 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.
+
+Before running `/oracle-auth` with this macOS path:
+
+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`.
+
+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.
+
+### Job retention
+
+Oracle automatically deletes completed and cancelled jobs after 14 days, and failed jobs after 30 days, by default. Retention starts at completion, or creation when no completion timestamp exists. Cleanup runs at session start, on submission, and during `/oracle-auth`; it can be delayed by active notification or cleanup guards.
+
+Set these keys in `~/.pi/agent/extensions/oracle.json` to change retention for new jobs. Values use milliseconds. Each job keeps the settings from its submission.
+
+| Key | Default |
+| --- | --- |
+| `cleanup.completeJobRetentionMs` | `1209600000` — 14 days, for completed and cancelled jobs |
+| `cleanup.failedJobRetentionMs` | `2592000000` — 30 days, for failed jobs |
+
+Copy answers and artifacts you need to keep. Temporary storage can be cleared before the retention period ends.
+
+## 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.
+- Cookie replay uses domain-based browser commands and does not preserve host-only or partitioned-cookie isolation metadata.
+
+## 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.

package/extensions/oracle/index.ts

@@ -118,6 +118,7 @@ export default function oracleExtension(pi: ExtensionAPI) {
   });
 
   pi.on("before_agent_start", async (event) => {
+    if (!("prompt" in event)) return;
     const parsed = parseOracleInput(event.prompt);
     if (!parsed?.args || (parsed.command === "oracle-followup" && !/^\S+\s+\S/.test(parsed.args))) return;
     const template = parsed.command === "oracle" ? oraclePrompt : oracleFollowupPrompt;

package/extensions/oracle/lib/poller.ts

@@ -67,12 +67,9 @@ interface OracleWakeupTargetLeaseMetadata {
 type OraclePollerJob = NonNullable<ReturnType<typeof readJob>>;
 
 export interface OraclePollerHooks {
-  collectLiveWakeupTargets?: (now?: number) => Promise<Set<string>>;
   beforeNotificationClaim?: (jobId: string) => Promise<void> | void;
   afterNotificationClaim?: (job: OraclePollerJob) => Promise<void> | void;
   beforeNotificationPersist?: (job: OraclePollerJob) => Promise<void> | void;
-  afterNotificationPersisted?: (job: OraclePollerJob) => Promise<void> | void;
-  beforeMarkJobNotified?: (job: OraclePollerJob) => Promise<void> | void;
 }
 
 export interface OraclePollerOptions {
@@ -228,7 +225,6 @@ async function scan(
   const sessionId = getSessionId(currentSessionFile, projectId);
   const processStartedAt = readProcessStartedAt(process.pid);
   const wakeupTargetLeaseKey = getWakeupTargetLeaseKey(pollerKey, process.pid, processStartedAt || "unknown");
-  const resolveLiveWakeupTargets = hooks.collectLiveWakeupTargets ?? collectLiveWakeupTargets;
   await writeLeaseMetadata(WAKEUP_TARGET_LEASE_KIND, wakeupTargetLeaseKey, {
     leaseKey: wakeupTargetLeaseKey,
     projectId,
@@ -239,7 +235,7 @@ async function scan(
   }).catch(() => undefined);
   if (await releaseWakeupLeaseIfInactive(wakeupTargetLeaseKey, lifecycle)) return;
 
-  const liveWakeupTargets = await resolveLiveWakeupTargets();
+  const liveWakeupTargets = await collectLiveWakeupTargets();
   if (await releaseWakeupLeaseIfInactive(wakeupTargetLeaseKey, lifecycle)) return;
 
   try {
@@ -294,7 +290,7 @@ async function scan(
         await releaseNotificationClaim(jobId, notificationClaimant).catch(() => undefined);
         return;
       }
-      const preNotifyLiveWakeupTargets = await resolveLiveWakeupTargets();
+      const preNotifyLiveWakeupTargets = await collectLiveWakeupTargets();
       if (await releaseWakeupLeaseIfInactive(wakeupTargetLeaseKey, lifecycle)) {
         await releaseNotificationClaim(jobId, notificationClaimant).catch(() => undefined);
         return;
@@ -319,7 +315,7 @@ async function scan(
         await releaseNotificationClaim(jobId, notificationClaimant).catch(() => undefined);
         return;
       }
-      const preWakeupLiveWakeupTargets = await resolveLiveWakeupTargets();
+      const preWakeupLiveWakeupTargets = await collectLiveWakeupTargets();
       if (await releaseWakeupLeaseIfInactive(wakeupTargetLeaseKey, lifecycle)) {
         await releaseNotificationClaim(jobId, notificationClaimant).catch(() => undefined);
         return;
@@ -347,7 +343,6 @@ async function scan(
         await releaseNotificationClaim(jobId, notificationClaimant).catch(() => undefined);
         return;
       }
-      await hooks.beforeMarkJobNotified?.(deliverable);
       await markJobNotified(jobId, notificationClaimant, {
         notificationSessionKey: pollerKey,
         notificationSessionFile: currentSessionFile,

package/extensions/oracle/lib/queue.ts

@@ -27,7 +27,6 @@ export interface PromoteQueuedJobsOptions {
   source: string;
   lockTimeoutMs?: number;
   spawnWorkerFn?: typeof spawnWorker;
-  loadConfigFn?: typeof loadOracleConfig;
 }
 
 function isQueuedJob(job: OracleJob | undefined): job is OracleJob {
@@ -70,7 +69,6 @@ async function failQueuedPromotion(job: OracleJob, message: string, at: string):
 
 export async function promoteQueuedJobsWithinAdmissionLock(options: PromoteQueuedJobsOptions): Promise<{ promotedJobIds: string[] }> {
   const spawnWorkerFn = options.spawnWorkerFn ?? spawnWorker;
-  const loadConfigFn = options.loadConfigFn ?? loadOracleConfig;
 
   return runQueuedJobPromotionPass<OracleJob, Awaited<ReturnType<typeof spawnWorkerFn>>>({
     listQueuedJobs,
@@ -78,7 +76,7 @@ export async function promoteQueuedJobsWithinAdmissionLock(options: PromoteQueue
     readLatestJob: (jobId) => readJob(jobId),
     isQueuedJob,
     acquireRuntimeLease: async (job, at) => {
-      const config = job.config ?? loadConfigFn(job.cwd);
+      const config = job.config ?? loadOracleConfig(job.cwd);
       const attempt = await tryAcquireRuntimeLease(config, buildRuntimeLeaseMetadata(job, at));
       return attempt.acquired;
     },
@@ -92,7 +90,7 @@ export async function promoteQueuedJobsWithinAdmissionLock(options: PromoteQueue
       await releaseRuntimeLease(job.runtimeId);
     },
     markSubmitted: async (job, at) => {
-      const config = job.config ?? loadConfigFn(job.cwd);
+      const config = job.config ?? loadOracleConfig(job.cwd);
       await updateJob(job.id, (latest) => {
         if (latest.status !== "queued") {
           throw new Error(`Queued job ${latest.id} changed state during promotion (${latest.status})`);

package/extensions/oracle/shared/browser-profile-helpers.d.mts

@@ -26,6 +26,7 @@ export function expandHomePath(value: string, homeDir?: string): string;
 export function normalizedAbsolutePath(value: string, options?: BrowserPathOptions): string;
 export function linuxConfigHome(options?: BrowserPathOptions): string;
 export function linuxChromiumCookieImportUserDataDirs(options?: BrowserPathOptions): string[];
+export function isNativeLinuxChromiumCookieSource(source: string, options?: BrowserPathOptions): boolean;
 export function linuxBrowserSafetyUserDataDirs(options?: BrowserPathOptions): string[];
 export function browserUserDataDirsForPlatform(
   platform?: OraclePlatform,