pi-oracle 0.7.4 → 0.7.5

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 ## Unreleased
 
+## 0.7.5 - 2026-06-02
+
+### Added
+- added a Crabbox platform release smoke gate for macOS, Ubuntu, and Windows native with doctor-first validation, packed-install real-extension proof, stop evidence, and platform artifacts
+- added canonical workflow docs and scripts for everyday local validation, focused platform-sensitive runs, and full release/publish smoke coverage
+
+### Changed
+- made the default packed real smoke deterministic by installing the packed package into a clean pi project and invoking the installed `oracle_submit` tool path without waiting on a model-agent turn
+- made Windows native a supported package OS and moved reusable Windows smoke dependencies into the Parallels template/snapshot workflow
+
+### Fixed
+- hardened Windows archive/process/profile handling, including taskkill cleanup, executable resolution, tar/zstd archive behavior, path safety, and auth-bootstrap absolute-path checks
+- removed production `as unknown as` casts and switched Linux/Windows runtime profile copies to Node recursive copy instead of relying on POSIX `cp`
+
+### Validation
+- verified `npm run verify:oracle`, `git diff --check`, and `npm run smoke:platform:all` across macOS, Ubuntu, and Windows native before release
+
 ## 0.7.4 - 2026-05-28
 
 ### Changed
@@ -66,6 +83,7 @@
 
 ### Changed
 - made `/oracle-auth` success and failure output easier to scan, with compact source summaries and source-specific troubleshooting for configured Chromium cookie sources
+- expanded package support to Linux, using ordinary profile copies off macOS and documenting `@steipete/sweet-cookie`'s Linux keyring/password options for Chromium cookie import
 - 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`

package/README.md

@@ -2,7 +2,7 @@
 
 `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.
 
-> Status: experimental public beta. Validated primarily on macOS with Google Chrome/Chromium and the current pi package baseline. Pi-bundled runtime packages are optional wildcard peers so npm peer ranges do not block users from trying newer pi releases, though runtime behavior is only verified against the tested baseline until a follow-up package release confirms it. Normal oracle jobs run in an isolated browser profile, not your active browser window.
+> Status: experimental public beta. Validated on macOS, Linux, and Windows native with Chromium-family browsers and the current pi package baseline. Pi-bundled runtime packages are optional wildcard peers so npm peer ranges do not block users from trying newer pi releases, though runtime behavior is only verified against the tested baseline until a follow-up package release confirms it. Normal oracle jobs run in an isolated browser profile, not your active browser window.
 
 ## What a successful run looks like
 
@@ -37,7 +37,7 @@ 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
-- non-macOS environments or machines without the required local browser/tooling
+- machines outside the currently supported local browser/tooling setup
 
 ## Problem it solves
 
@@ -75,13 +75,15 @@ pi install https://github.com/fitchmultz/pi-oracle
 
 You need:
 
-- macOS
+- macOS, Linux, or Windows native
 - Node.js 22 or newer
 - `pi` 0.65.0 or newer
-- Google Chrome or another Chromium-family browser
+- 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`, `tar`, and `zstd` available on the machine
+- 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
 
 ### 3. Sync provider auth once
 
@@ -202,11 +204,23 @@ Notes:
 - 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` 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.
+
+Sweet Cookie's 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` 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; if you use an environment override for one `/oracle-auth` run, pi-oracle scrubs it before launching browser/helper subprocesses after cookie import.
+
 ### Custom Chromium cookie sources
 
-Use this only for a Chromium-family browser that the default cookie importer cannot read.
+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.
 
-Before running `/oracle-auth` with this path:
+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.
@@ -214,7 +228,7 @@ Before running `/oracle-auth` with this 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 Helium config:
+Example macOS Helium config:
 
 ```json
 {
@@ -233,7 +247,9 @@ Example Helium config:
 }
 ```
 
-`auth.chromeCookiePath` must be paired with `auth.chromiumKeychain`; partial config is rejected so oracle does not silently fall back to another browser source.
+`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
 
@@ -279,19 +295,19 @@ Review the code and design docs before using it with private or regulated materi
 
 ## Current limits
 
-- Experimental public beta, validated primarily on macOS.
+- 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, and environment diagnostics.
+- 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 and `auth.chromiumKeychain.services` names the browser's safe-storage Keychain service.
+- 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 the provider is half-logged-in or challenge flow state looks weird, finish the login/challenge in the headed auth browser and retry.
@@ -304,7 +320,7 @@ This usually means the cookie import worked but the source cookies are not the a
 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. Confirm `auth.chromiumKeychain.services` names the browser's safe-storage Keychain service for that 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
@@ -330,14 +346,14 @@ This usually means the cookie import worked but the source cookies are not the a
 - 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
+### A local dependency like `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. 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 and pair it with `auth.chromiumKeychain`.
+- 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
@@ -350,6 +366,7 @@ 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
@@ -358,9 +375,25 @@ npm test
 npm run verify:oracle
 ```
 
-`npm publish` is guarded by `prepublishOnly`, which runs `npm run verify:oracle`.
+`npm publish` is guarded by `prepublishOnly`, which runs `npm run release:check`. That release gate 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-sensitive changes | `npm run smoke:platform:doctor`, then a focused `node scripts/platform-smoke.mjs run --target <target> --suite <suite>` |
+| Publish/release proof | `npm run smoke:platform:all` |
+
+For macOS, Ubuntu, and Windows native package/build plus packed runtime validation, use [`docs/platform-smoke.md`](docs/platform-smoke.md). The full release proof is:
+
+```bash
+npm run smoke:platform:all
+```
+
+The real runtime suite defaults to deterministic installed-tool execution so platform proof stays bounded. Provider/model defaults remain `zai/glm-5.1` 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 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.
+For manual 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` coding-agent sessions against this checkout and uses `instant` or `thinking_light`, as required by the project validation policy.
 
 ## Project map
 
@@ -373,6 +406,7 @@ For end-to-end local-extension smoke testing, use [`docs/ORACLE_ISOLATED_PI_VALI
 | [`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 |
+| `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 |

package/docs/ORACLE_DESIGN.md

@@ -246,7 +246,7 @@ Browser/auth settings are global-only because they control local privileged brow
     "authSeedProfileDir": "<absolute path to oracle auth seed profile>",
     "runtimeProfilesDir": "<absolute path to oracle runtime profiles dir>",
     "maxConcurrentJobs": 2,
-    "cloneStrategy": "apfs-clone",
+    "cloneStrategy": "copy",
     "chatUrl": "https://chatgpt.com/",
     "authUrl": "https://chatgpt.com/auth/login",
     "runMode": "headless",
@@ -260,7 +260,7 @@ Browser/auth settings are global-only because they control local privileged brow
     "chromeProfile": "<optional Chrome/Chromium profile name>",
     "chromeCookiePath": "<optional absolute path to Chromium Cookies DB>",
     "chromiumKeychain": {
-      "account": "<macOS Keychain account for non-built-in Chromium browsers>",
+      "account": "<macOS-only Keychain account for non-built-in Chromium browsers>",
       "services": ["<safe-storage service name>"],
       "label": "<optional human-readable label>"
     }
@@ -282,9 +282,13 @@ Browser/auth settings are global-only because they control local privileged brow
 }
 ```
 
-`auth.chromiumKeychain` is an 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.
+`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`.
 
-When both `auth.chromeCookiePath` and `auth.chromiumKeychain` are present, auth bootstrap:
+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.
+
+`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.
+
+When both `auth.chromeCookiePath` and `auth.chromiumKeychain` are present on macOS, auth bootstrap:
 
 1. reads the configured macOS Keychain safe-storage password using `account` and the ordered `services` list
 2. snapshots the Chromium `Cookies` DB plus `Cookies-wal` / `Cookies-shm` sidecars, tolerating sidecars that disappear while the browser is closing
@@ -292,7 +296,7 @@ When both `auth.chromeCookiePath` and `auth.chromiumKeychain` are present, auth
 4. dedupes duplicate cookie rows by keeping the first row after newest-expiry ordering
 5. filters importable provider auth cookies and seeds the isolated oracle auth profile
 
-Operational requirements for this path:
+Operational requirements for this macOS-only path:
 
 - ChatGPT or Grok must already be logged in in the configured browser profile, depending on the provider being synced.
 - The target browser should be fully quit before `/oracle-auth` so the cookie DB snapshot is stable.
@@ -633,3 +637,6 @@ Recent proof points:
 - expired-auth drill post-repair success: `fa26a2a7-0057-4a21-b3e0-71c1d020facf`
 - successful multi-artifact completion: `b6b3599c-6b91-4315-adfa-8a83aa5eda9b`
 - repo-owned sanity harness: `npm run sanity:oracle`
+- real installed-extension smoke source of truth: `scripts/oracle-real-smoke.mjs`; required release proof runs packed-install mode (`npm run smoke:real:packed`) and executes installed-package `oracle_submit` deterministically, with optional slower model-agent debugging via `PI_ORACLE_REAL_TEST_MODEL_AGENT=1`; source mode (`npm run smoke:real:source`) is inner-loop/debug only
+- macOS, Ubuntu, and Windows native package/build/runtime smoke source of truth: `docs/platform-smoke.md`; use `npm run verify:oracle` for everyday local iteration, `npm run smoke:platform:doctor` plus a focused target/suite run for platform-sensitive changes, and `npm run smoke:platform:all` for doctor-first packed-install Crabbox release evidence
+- release gate: `npm run release:check`, also used by `prepublishOnly`, combines static verification and all required Crabbox platform smokes

package/docs/platform-smoke.md

@@ -0,0 +1,153 @@
+# pi-oracle Crabbox platform smoke
+
+`pi-oracle` uses Crabbox for the local release-blocking platform gate. The gate runs on macOS, Ubuntu Linux, and native Windows and is meant to catch broken package installs, platform assumptions, and real `pi` tool-call failures before push or publish.
+
+## Source of truth
+
+- Config: [`../platform-smoke.config.mjs`](../platform-smoke.config.mjs)
+- CLI: [`../scripts/platform-smoke.mjs`](../scripts/platform-smoke.mjs)
+- Target runner: [`../scripts/platform-smoke/targets.mjs`](../scripts/platform-smoke/targets.mjs)
+- Windows build script: [`../scripts/platform-smoke/platform-build-windows.ps1`](../scripts/platform-smoke/platform-build-windows.ps1)
+- Real runtime smoke: [`../scripts/oracle-real-smoke.mjs`](../scripts/oracle-real-smoke.mjs)
+- Artifact root: `.artifacts/platform-smoke/` (gitignored)
+
+Required targets: `macos`, `ubuntu`, `windows-native`.
+Required suites: `platform-build`, `real-extension`.
+Crabbox baseline: `0.24.0` or newer.
+
+## Required local setup
+
+Install Crabbox with Homebrew and keep it on `PATH`:
+
+```bash
+brew install openclaw/tap/crabbox
+crabbox --version
+crabbox providers
+```
+
+`PI_ORACLE_SMOKE_CRABBOX` is optional and only needed to override the binary path.
+
+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.
+- 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.
+
+Real runtime suite auth:
+
+- Default deterministic installed-tool smoke does not require provider API keys.
+- Provider/model defaults remain `zai/glm-5.1` for optional model-agent debugging.
+- Set `PI_ORACLE_REAL_TEST_MODEL_AGENT=1` to run the slower model-agent path; then the provider auth env is required (`ZAI_API_KEY` by default, reported only as present/redacted).
+- Override with `PI_ORACLE_REAL_TEST_PROVIDER` and `PI_ORACLE_REAL_TEST_MODEL`; auth variable names live in `platform-smoke.config.mjs`.
+
+## Canonical validation workflows
+
+Use the narrowest workflow that proves the change. Do not run the full platform matrix for ordinary edits when the local gate and cheap invariants prove the change.
+
+| 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. |
+| Publish/release proof | `npm run smoke:platform:all` | Doctor-first packed-install proof passes on every required target and suite. |
+
+Platform-sensitive changes include archive behavior, process cleanup, runtime/browser profile handling, package metadata, Crabbox harness code, or anything that may differ across macOS/Linux/Windows.
+
+## Commands
+
+Doctor is mandatory before the full release matrix. The canonical all-target release command enforces that:
+
+```bash
+npm run smoke:platform:all
+```
+
+Focused commands:
+
+```bash
+npm run smoke:platform:doctor
+npm run smoke:platform:macos
+npm run smoke:platform:ubuntu
+npm run smoke:platform:windows-native
+node scripts/platform-smoke.mjs run --target windows-native --suite real-extension
+```
+
+Release check:
+
+```bash
+npm run release:check
+```
+
+`prepublishOnly` runs `npm run release:check`.
+
+## What `platform-build` proves
+
+On each required target, `platform-build`:
+
+1. checks Node major version against `nodeValidationMajor`;
+2. runs `npm ci`;
+3. requires target tools (`zstd`, `agent-browser`) to already be available from target setup;
+4. runs `npm run verify:oracle:platform`, the platform-focused gate for syntax, platform-smoke invariants, real-smoke script syntax, platform-sensitive oracle sanity coverage, and package dry-run;
+5. runs `npm pack`;
+6. creates a fresh target-local pi project;
+7. runs `npm install --no-save <packed tarball>`;
+8. runs `pi install -l ./node_modules/pi-oracle`;
+9. runs `pi list`;
+10. asserts the installed package came from `node_modules/pi-oracle` and did not use `pi -e` / source-extension shortcuts.
+
+## What `real-extension` proves
+
+`real-extension` is required release proof. It runs `npm run smoke:real:packed` on each target, which:
+
+1. packs this checkout with `npm pack`;
+2. installs the tarball into a clean pi project;
+3. runs `pi install -l ./node_modules/pi-oracle`;
+4. asserts `pi list` 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.
+
+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.
+
+For inner-loop/debug only, use:
+
+```bash
+npm run smoke:real:source
+```
+
+That source-mode smoke loads `extensions/oracle/index.ts` with `pi --no-extensions -e`; it is useful while developing but is not release proof.
+
+## Artifacts
+
+Each suite writes reviewable evidence under:
+
+```text
+.artifacts/platform-smoke/<run-id>/<target>/<suite>/
+  summary.json
+  target.json
+  suite.json
+  command.txt
+  exit-code.txt
+  crabbox.stdout.txt
+  crabbox.stderr.txt
+  crabbox.timing.json
+  crabbox.stop.stdout.txt
+  crabbox.stop.stderr.txt
+  crabbox.stop.exit-code.txt
+  assertions.json
+  artifact-manifest.json
+  failures.md            # only on failure
+```
+
+`platform-build` also writes packed install extracts (`packed-tarball.txt`, `packed-node-install.*`, `pi-install.*`, `pi-list.*`). Passing suites require `summary.ok === true`, `assertions.ok === true`, and `artifact-manifest.missing.length === 0`.
+
+Artifacts are local evidence only. Do not commit or share them without redaction. Secret scans fail on bearer/API-key/cookie-like values.
+
+## Windows template maintenance
+
+When Windows lacks a reusable tool such as `zstd` or `agent-browser`, update `pi-extension-windows-template` rather than adding a per-run installer:
+
+1. boot `pi-extension-windows-template`;
+2. install/update the tool globally without secrets;
+3. verify from a fresh SSH session: `node --version`, `npm --version`, `git --version`, `tar --version`, `zstd --version`, `agent-browser --version`;
+4. remove downloads, caches, checkouts, `.pi`, `.artifacts`, `.debug`, and secrets;
+5. shut down cleanly;
+6. create/promote the configured power-off snapshot;
+7. clean stale clones/leases.

package/extensions/oracle/lib/config.ts

@@ -8,6 +8,15 @@ import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { isAbsolute, join, normalize } from "node:path";
+import {
+  assertNotKnownBrowserUserDataPath,
+  chromeUserAgentPlatformToken,
+  chromiumKeychainSupportedOnPlatform,
+  defaultCloneStrategyForPlatform,
+  detectDefaultBrowserProfileSource,
+  detectDefaultLinuxChromeExecutablePath,
+  sweetCookieSafeStoragePasswordScrubbedEnv,
+} from "../shared/browser-profile-helpers.mjs";
 import { getProjectId } from "./runtime.js";
 
 export const ORACLE_PROVIDERS = ["chatgpt", "grok"] as const;
@@ -225,7 +234,6 @@ export type OracleCloneStrategy = (typeof CLONE_STRATEGIES)[number];
 const ALLOWED_CHATGPT_ORIGINS = new Set(["https://chatgpt.com", "https://chat.openai.com"]);
 const PROJECT_OVERRIDE_KEYS = new Set(["defaults", "worker", "poller", "artifacts", "cleanup"]);
 const DEFAULT_MAC_CHROME_EXECUTABLE = "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome";
-const DEFAULT_MAC_CHROME_USER_DATA_DIR = join(homedir(), "Library", "Application Support", "Google", "Chrome");
 
 export interface OracleConfig {
   defaults: {
@@ -274,37 +282,36 @@ export interface OracleConfig {
 }
 
 function detectDefaultChromeExecutablePath(): string | undefined {
-  return existsSync(DEFAULT_MAC_CHROME_EXECUTABLE) ? DEFAULT_MAC_CHROME_EXECUTABLE : undefined;
+  if (process.platform === "darwin") {
+    return existsSync(DEFAULT_MAC_CHROME_EXECUTABLE) ? DEFAULT_MAC_CHROME_EXECUTABLE : undefined;
+  }
+  if (process.platform === "linux") {
+    return detectDefaultLinuxChromeExecutablePath();
+  }
+  return undefined;
 }
 
 function detectDefaultChromeUserAgent(executablePath: string | undefined): string | undefined {
   if (!executablePath) return undefined;
+  // Linux executable discovery is PATH-based, so avoid executing that discovered
+  // binary during config module initialization just to derive a user agent.
+  if (process.platform === "linux") return undefined;
+  const platformToken = chromeUserAgentPlatformToken(process.platform);
+  if (!platformToken) return undefined;
   try {
-    const versionOutput = execFileSync(executablePath, ["--version"], { encoding: "utf8" }).trim();
+    const versionOutput = execFileSync(executablePath, ["--version"], { encoding: "utf8", env: sweetCookieSafeStoragePasswordScrubbedEnv() }).trim();
     const versionMatch = versionOutput.match(/(\d+\.\d+\.\d+\.\d+)/);
     if (!versionMatch) return undefined;
-    return `Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/${versionMatch[1]} Safari/537.36`;
+    return `Mozilla/5.0 (${platformToken}) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/${versionMatch[1]} Safari/537.36`;
   } catch {
     return undefined;
   }
 }
 
-function detectDefaultChromeProfileName(): string {
-  const localStatePath = join(DEFAULT_MAC_CHROME_USER_DATA_DIR, "Local State");
-  if (!existsSync(localStatePath)) return "Default";
-  try {
-    const localState = JSON.parse(readFileSync(localStatePath, "utf8")) as { profile?: { last_used?: string } };
-    const lastUsed = localState?.profile?.last_used;
-    return typeof lastUsed === "string" && lastUsed.trim() ? lastUsed.trim() : "Default";
-  } catch {
-    return "Default";
-  }
-}
-
 const detectedChromeExecutablePath = detectDefaultChromeExecutablePath();
 const detectedChromeUserAgent = detectDefaultChromeUserAgent(detectedChromeExecutablePath);
 const agentExtensionsDir = join(getAgentDir(), "extensions");
-const detectedChromeProfileName = detectDefaultChromeProfileName();
+const detectedChromeProfileName = detectDefaultBrowserProfileSource(process.platform);
 
 export interface OracleConfigLoadDetails {
   agentDir: string;
@@ -367,7 +374,7 @@ export const DEFAULT_CONFIG: OracleConfig = {
     authSeedProfileDir: join(agentExtensionsDir, "oracle-auth-seed-profile"),
     runtimeProfilesDir: join(agentExtensionsDir, "oracle-runtime-profiles"),
     maxConcurrentJobs: 2,
-    cloneStrategy: "apfs-clone",
+    cloneStrategy: defaultCloneStrategyForPlatform(process.platform),
     chatUrl: "https://chatgpt.com/",
     authUrl: "https://chatgpt.com/auth/login",
     runMode: "headless",
@@ -452,18 +459,28 @@ function expectAbsoluteNormalizedPath(value: unknown, path: string): string {
   return normalize(expanded);
 }
 
-function expectSafeProfilePath(pathValue: string, path: string): string {
+function expectSafeProfilePath(
+  pathValue: string,
+  path: string,
+  cookieSources?: { chromeProfile?: string; chromeCookiePath?: string },
+): string {
   if (pathValue === "/" || pathValue === homedir()) {
     throw new Error(`Invalid oracle config: ${path} points to an unsafe directory`);
   }
-  if (pathValue === DEFAULT_MAC_CHROME_USER_DATA_DIR || pathValue.startsWith(`${DEFAULT_MAC_CHROME_USER_DATA_DIR}/`)) {
-    throw new Error(`Invalid oracle config: ${path} must not point into the real Chrome user-data directory`);
+  try {
+    assertNotKnownBrowserUserDataPath(pathValue, `Invalid oracle config: ${path}`, { cookieSources });
+  } catch (error) {
+    throw new Error(error instanceof Error ? error.message : String(error));
   }
   return pathValue;
 }
 
-function expectSafeProfileDir(value: unknown, path: string): string {
-  return expectSafeProfilePath(expectAbsoluteNormalizedPath(value, path), path);
+function expectSafeProfileDir(
+  value: unknown,
+  path: string,
+  cookieSources?: { chromeProfile?: string; chromeCookiePath?: string },
+): string {
+  return expectSafeProfilePath(expectAbsoluteNormalizedPath(value, path), path, cookieSources);
 }
 
 function expectBoolean(value: unknown, path: string): boolean {
@@ -584,17 +601,26 @@ function validateOracleConfig(value: unknown): OracleConfig {
   const artifacts = expectObject(root.artifacts, "artifacts");
   const cleanup = expectObject(root.cleanup, "cleanup");
 
-  const authSeedProfileDir = expectSafeProfileDir(browser.authSeedProfileDir, "browser.authSeedProfileDir");
-  const runtimeProfilesDir = expectSafeProfileDir(browser.runtimeProfilesDir, "browser.runtimeProfilesDir");
+  const chromeProfile = expectString(auth.chromeProfile, "auth.chromeProfile");
+  const chromeCookiePath = expectOptionalAbsoluteNormalizedPath(auth.chromeCookiePath, "auth.chromeCookiePath");
+  const cookieSources = { chromeProfile, chromeCookiePath };
+  const authSeedProfileDir = expectSafeProfileDir(browser.authSeedProfileDir, "browser.authSeedProfileDir", cookieSources);
+  const runtimeProfilesDir = expectSafeProfileDir(browser.runtimeProfilesDir, "browser.runtimeProfilesDir", cookieSources);
   if (runtimeProfilesDir === authSeedProfileDir || runtimeProfilesDir.startsWith(`${authSeedProfileDir}/`)) {
     throw new Error("Invalid oracle config: browser.runtimeProfilesDir must be separate from browser.authSeedProfileDir");
   }
 
-  const chromeCookiePath = expectOptionalAbsoluteNormalizedPath(auth.chromeCookiePath, "auth.chromeCookiePath");
   const chromiumKeychain = expectOptionalChromiumKeychain(auth.chromiumKeychain, "auth.chromiumKeychain");
   if (chromiumKeychain !== undefined && chromeCookiePath === undefined) {
     throw new Error("Invalid oracle config: auth.chromiumKeychain requires auth.chromeCookiePath");
   }
+  if (chromiumKeychain !== undefined && !chromiumKeychainSupportedOnPlatform(process.platform)) {
+    throw new Error(
+      "Invalid oracle config: auth.chromiumKeychain is macOS-only. " +
+        "On Linux, set auth.chromeCookiePath/auth.chromeProfile without auth.chromiumKeychain and use @steipete/sweet-cookie's " +
+        "SWEET_COOKIE_LINUX_KEYRING, SWEET_COOKIE_CHROME_SAFE_STORAGE_PASSWORD, or SWEET_COOKIE_BRAVE_SAFE_STORAGE_PASSWORD options for encrypted Chromium cookies.",
+    );
+  }
 
   return {
     defaults: {
@@ -618,7 +644,7 @@ function validateOracleConfig(value: unknown): OracleConfig {
     auth: {
       pollMs: expectInteger(auth.pollMs, "auth.pollMs", 100),
       bootstrapTimeoutMs: expectInteger(auth.bootstrapTimeoutMs, "auth.bootstrapTimeoutMs", 1000),
-      chromeProfile: expectString(auth.chromeProfile, "auth.chromeProfile"),
+      chromeProfile,
       chromeCookiePath,
       chromiumKeychain,
     },

package/extensions/oracle/lib/jobs.ts

@@ -197,9 +197,12 @@ export interface OracleRuntimeAllocation {
   seedGeneration?: string;
 }
 
+function hasSessionFileAccessor(value: unknown): value is { getSessionFile: () => string | undefined } {
+  return typeof value === "object" && value !== null && "getSessionFile" in value && typeof value.getSessionFile === "function";
+}
+
 export function getSessionFile(ctx: ExtensionContext): string | undefined {
-  const manager = ctx.sessionManager as unknown as { getSessionFile?: () => string | undefined };
-  return manager.getSessionFile?.();
+  return hasSessionFileAccessor(ctx.sessionManager) ? ctx.sessionManager.getSessionFile() : undefined;
 }
 
 export function getOracleJobsDir(): string {
@@ -989,13 +992,14 @@ export function resolveArchiveInputs(cwd: string, files: string[]): { absolute:
       throw new Error("Archive input must use '.' exactly for a whole-repo archive");
     }
     const absolute = resolve(cwd, file);
-    if (absolute === cwd && file !== ".") {
+    const relativeFromCwd = relativePath(cwd, absolute);
+    if (relativeFromCwd === "" && file !== ".") {
       throw new Error("Archive input must use '.' exactly for a whole-repo archive");
     }
-    const relative = absolute.startsWith(`${cwd}/`) ? absolute.slice(cwd.length + 1) : absolute === cwd ? "." : "";
-    if (!relative) {
+    if (relativeFromCwd && (relativeFromCwd === ".." || relativeFromCwd.startsWith(`..${sep}`) || isAbsolute(relativeFromCwd))) {
       throw new Error(`Archive input must be inside the project cwd: ${file}`);
     }
+    const relative = relativeFromCwd === "" ? "." : relativeFromCwd.split(sep).join("/");
     if (!existsSync(absolute)) {
       throw new Error(`Archive input does not exist: ${file}`);
     }