pi-oracle 0.7.5 → 0.7.6

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 ## Unreleased
 
+## 0.7.6 - 2026-06-04
+
+### Changed
+- updated the local pi development baseline to `@earendil-works/pi-coding-agent` / `@earendil-works/pi-ai` `0.78.1` and regenerated the npm lockfile
+- documented `pi` `0.78.1+` as the suggested tested floor while keeping pi runtime packages as optional wildcard peers so newer pi releases are not blocked by npm peer ranges
+- added Ant Ling, NVIDIA NIM, and MiniMax China provider env mappings to the oracle real-smoke/platform-smoke provider metadata
+
+### Fixed
+- made startup poller and wake-up routing mode-aware with Pi 0.78.1 `ctx.mode`, so print and JSON one-shot runs do not start background pollers or publish oracle UI status
+- guarded oracle startup status and warning notifications with `ctx.hasUI` for non-UI modes
+
+### Compatibility
+- reviewed the pi `0.78.1` changelog, extension docs, package docs, prompt-template docs, and matching examples; the oracle extension remains compatible with current extension lifecycle and package install/update behavior
+
 ## 0.7.5 - 2026-06-02
 
 ### Added

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 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.
+> Status: experimental public beta. Validated on macOS, Linux, and Windows native with Chromium-family browsers and pi `0.78.1`. Pi `0.78.1+` is the suggested tested floor for mode-aware background polling, 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.
 
 ## What a successful run looks like
 
@@ -77,7 +77,7 @@ You need:
 
 - macOS, Linux, or Windows native
 - Node.js 22 or newer
-- `pi` 0.65.0 or newer
+- Suggested tested floor: `pi` 0.78.1 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`, `tar`, and `zstd` available on the machine
@@ -383,12 +383,13 @@ Use the narrowest validation workflow that proves the change:
 | --- | --- |
 | 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` |
+| Platform matrix proof | `npm run smoke:platform:all` |
+| 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 proof is:
+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 smoke:platform:all
+npm run release:check
 ```
 
 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.

package/docs/ORACLE_DESIGN.md

@@ -1,13 +1,14 @@
 # pi-oracle design
 
-Status: isolated-profile concurrency architecture implemented in code; major live validation now passes, but a few non-blocking hardening items remain.
-Date: 2026-04-03
+Status: isolated-profile concurrency architecture implemented in code and validated against the current pi baseline.
+Date: 2026-06-04
 
 Companion doc:
 - `docs/ORACLE_RECOVERY_DRILL.md` — safe expired-auth recovery validation drill
 
 Compatibility target:
-- `pi` 0.65.0+
+- `pi` 0.78.1+ is the suggested tested floor for current mode-aware poller behavior
+- package metadata keeps pi runtime packages as optional wildcard peers, so this suggested floor is not enforced as a hard npm install requirement
 - current extension lifecycle only; no backward-compatibility shims for removed `session_switch` / `session_fork` events
 
 ## Goal
@@ -638,5 +639,5 @@ Recent proof points:
 - 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
+- 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, `npm run smoke:platform:all` for doctor-first platform matrix evidence, and `npm run release:check` for the full local-plus-platform release gate
 - release gate: `npm run release:check`, also used by `prepublishOnly`, combines static verification and all required Crabbox platform smokes

package/docs/platform-smoke.md

@@ -13,7 +13,7 @@
 
 Required targets: `macos`, `ubuntu`, `windows-native`.
 Required suites: `platform-build`, `real-extension`.
-Crabbox baseline: `0.24.0` or newer.
+Crabbox baseline: `0.26.0` or newer.
 
 ## Required local setup
 
@@ -25,7 +25,7 @@ crabbox --version
 crabbox providers
 ```
 
-`PI_ORACLE_SMOKE_CRABBOX` is optional and only needed to override the binary path.
+`PLATFORM_SMOKE_CRABBOX` is the reusable binary override. `PI_ORACLE_SMOKE_CRABBOX` is a project-specific alias and wins when both are set.
 
 Target setup:
 
@@ -48,13 +48,14 @@ Use the narrowest workflow that proves the change. Do not run the full platform
 | --- | --- | --- |
 | 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 matrix proof | `npm run smoke:platform:all` | Doctor-first packed-install proof passes on every required target and suite. |
+| Publish/release gate | `npm run release:check` | Local verification (`verify:oracle`) passes, then the doctor-first platform matrix passes. |
 
 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:
+Doctor is mandatory before the full platform matrix. The canonical all-target platform command enforces that:
 
 ```bash
 npm run smoke:platform:all
@@ -70,13 +71,13 @@ npm run smoke:platform:windows-native
 node scripts/platform-smoke.mjs run --target windows-native --suite real-extension
 ```
 
-Release check:
+Full release gate:
 
 ```bash
 npm run release:check
 ```
 
-`prepublishOnly` runs `npm run release:check`.
+`release:check` runs `verify:oracle` before `smoke:platform:all`, matching the Crabbox doctor-first release order: cheap harness checks, doctor, full matrix, then artifact review. `prepublishOnly` runs `npm run release:check`.
 
 ## What `platform-build` proves
 
@@ -142,12 +143,14 @@ Artifacts are local evidence only. Do not commit or share them without redaction
 
 ## 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.
+When Windows lacks a reusable tool such as `zstd` or `agent-browser`, update the shared `pi-extension-windows-template` infrastructure rather than adding a per-run installer:
+
+1. revert/switch `pi-extension-windows-template` to the current canonical `crabbox-ready` snapshot;
+2. boot the template;
+3. install/update the reusable tool globally without secrets;
+4. verify from a fresh SSH session: `node --version`, `npm --version`, `git --version`, `tar --version`, `zstd --version`, `agent-browser --version`, and `agent-browser install`;
+5. remove downloads, caches, checkouts, `.pi`, `.artifacts`, `.debug`, browser auth/session state, and secrets;
+6. shut down cleanly;
+7. create/promote the configured power-off `crabbox-ready` snapshot;
+8. run `npm run smoke:platform:doctor` and `npm run smoke:platform:windows-native` against the promoted snapshot;
+9. clean stale clones/leases.

package/extensions/oracle/index.ts

@@ -39,9 +39,13 @@ export default function oracleExtension(pi: ExtensionAPI) {
   function startPollerForContext(ctx: ExtensionContext) {
     try {
       const sessionFile = getSessionFile(ctx);
+      if (ctx.mode === "print" || ctx.mode === "json") {
+        stopPoller(ctx);
+        return;
+      }
       if (!hasPersistedSessionFile(sessionFile)) {
         stopPoller(ctx);
-        ctx.ui.setStatus("oracle", ctx.ui.theme.fg("accent", "oracle: unavailable"));
+        if (ctx.hasUI) ctx.ui.setStatus("oracle", ctx.ui.theme.fg("accent", "oracle: unavailable"));
         return;
       }
 
@@ -49,15 +53,17 @@ export default function oracleExtension(pi: ExtensionAPI) {
       void runStartupMaintenance(ctx).catch((error) => {
         const message = `Oracle startup maintenance failed: ${error instanceof Error ? error.message : String(error)}`;
         console.error(message);
-        ctx.ui.notify(message, "warning");
+        if (ctx.hasUI) ctx.ui.notify(message, "warning");
       });
       startPoller(pi, ctx, config.poller.intervalMs, workerPath);
       refreshOracleStatus(ctx);
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
       stopPoller(ctx);
-      ctx.ui.setStatus("oracle", ctx.ui.theme.fg("error", "oracle: config error"));
-      ctx.ui.notify(message, "warning");
+      if (ctx.hasUI) {
+        ctx.ui.setStatus("oracle", ctx.ui.theme.fg("error", "oracle: config error"));
+        ctx.ui.notify(message, "warning");
+      }
     }
   }
 

package/extensions/oracle/lib/poller.ts

@@ -165,6 +165,7 @@ function getJobCountsForSession(sessionFile: string | undefined, cwd: string): {
 }
 
 function refreshOracleStatusSnapshot(snapshot: OraclePollerContextSnapshot): void {
+  if (!snapshot.hasUI) return;
   if (!snapshot.sessionFile) {
     snapshot.ui.setStatus("oracle", snapshot.ui.theme.fg("accent", "oracle: unavailable"));
     return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-oracle",
-  "version": "0.7.5",
+  "version": "0.7.6",
   "description": "ChatGPT and Grok web-oracle extension for pi with isolated browser auth, async jobs, and project-context archives.",
   "private": false,
   "license": "MIT",
@@ -47,7 +47,7 @@
     ]
   },
   "scripts": {
-    "check:oracle-extension": "node --check extensions/oracle/shared/browser-profile-helpers.mjs && node --check extensions/oracle/shared/process-helpers.mjs && node --check extensions/oracle/shared/state-coordination-helpers.mjs && node --check extensions/oracle/shared/job-coordination-helpers.mjs && node --check extensions/oracle/shared/job-lifecycle-helpers.mjs && node --check extensions/oracle/shared/job-observability-helpers.mjs && node --check extensions/oracle/worker/run-job.mjs && node --check extensions/oracle/worker/state-locks.mjs && node --check extensions/oracle/worker/artifact-heuristics.mjs && node --check extensions/oracle/worker/chatgpt-ui-helpers.mjs && node --check extensions/oracle/worker/chatgpt-flow-helpers.mjs && node --check extensions/oracle/worker/auth-flow-helpers.mjs && node --check extensions/oracle/worker/auth-cookie-policy.mjs && node --check extensions/oracle/worker/chromium-cookie-source.mjs && node --check extensions/oracle/worker/auth-bootstrap.mjs && esbuild extensions/oracle/index.ts --bundle --platform=node --format=esm --external:@earendil-works/pi-coding-agent --external:@earendil-works/pi-ai --external:typebox --outfile=/tmp/pi-oracle-extension-check.js",
+    "check:oracle-extension": "node --check extensions/oracle/shared/browser-profile-helpers.mjs && node --check extensions/oracle/shared/process-helpers.mjs && node --check extensions/oracle/shared/state-coordination-helpers.mjs && node --check extensions/oracle/shared/job-coordination-helpers.mjs && node --check extensions/oracle/shared/job-lifecycle-helpers.mjs && node --check extensions/oracle/shared/job-observability-helpers.mjs && node --check extensions/oracle/worker/run-job.mjs && node --check extensions/oracle/worker/state-locks.mjs && node --check extensions/oracle/worker/artifact-heuristics.mjs && node --check extensions/oracle/worker/chatgpt-ui-helpers.mjs && node --check extensions/oracle/worker/chatgpt-flow-helpers.mjs && node --check extensions/oracle/worker/auth-flow-helpers.mjs && node --check extensions/oracle/worker/auth-cookie-policy.mjs && node --check extensions/oracle/worker/chromium-cookie-source.mjs && node --check extensions/oracle/worker/auth-bootstrap.mjs && esbuild extensions/oracle/index.ts --bundle --platform=node --format=esm --external:@earendil-works/pi-coding-agent --external:typebox --outfile=/tmp/pi-oracle-extension-check.js",
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "typecheck:worker-helpers": "tsc --noEmit -p tsconfig.worker-helpers.json",
     "sanity:oracle": "node scripts/oracle-sanity-runner.mjs",
@@ -83,9 +83,9 @@
     "protobufjs": "7.6.1"
   },
   "devDependencies": {
-    "@earendil-works/pi-ai": "^0.77.0",
-    "@earendil-works/pi-coding-agent": "^0.77.0",
-    "@types/node": "^25.9.1",
+    "@earendil-works/pi-ai": "^0.78.1",
+    "@earendil-works/pi-coding-agent": "^0.78.1",
+    "@types/node": "^22.19.19",
     "esbuild": "^0.28.0",
     "tsx": "^4.22.3",
     "typebox": "^1.1.39",

package/platform-smoke.config.mjs

@@ -18,14 +18,18 @@ export default {
         "node scripts/platform-smoke.mjs run --target <target> --suite <suite>",
       ],
     },
-    release: {
-      description: "Doctor-first packed-install macOS/Ubuntu/Windows release proof.",
+    platformMatrix: {
+      description: "Doctor-first packed-install macOS/Ubuntu/Windows platform proof.",
       commands: ["npm run smoke:platform:all"],
     },
+    release: {
+      description: "Full release gate: local verification plus the doctor-first platform matrix.",
+      commands: ["npm run release:check"],
+    },
   },
   requiredCrabbox: {
     source: "https://github.com/openclaw/crabbox",
-    minVersion: "0.24.0",
+    minVersion: "0.26.0",
   },
   ubuntuContainerImage: "pi-oracle-platform-smoke:node24",
   ubuntuContainerBaseImage: "cimg/node:24.16",
@@ -52,6 +56,9 @@ export default {
       ai_gateway: ["AI_GATEWAY_API_KEY"],
       mistral: ["MISTRAL_API_KEY"],
       minimax: ["MINIMAX_API_KEY"],
+      "minimax-cn": ["MINIMAX_CN_API_KEY"],
+      "ant-ling": ["ANT_LING_API_KEY"],
+      nvidia: ["NVIDIA_API_KEY"],
       moonshot: ["MOONSHOT_API_KEY"],
       kimi: ["KIMI_API_KEY"],
     },

package/scripts/oracle-real-smoke.mjs

@@ -85,6 +85,9 @@ function apiKeyNameForProvider(provider) {
     ai_gateway: "AI_GATEWAY_API_KEY",
     mistral: "MISTRAL_API_KEY",
     minimax: "MINIMAX_API_KEY",
+    "minimax-cn": "MINIMAX_CN_API_KEY",
+    "ant-ling": "ANT_LING_API_KEY",
+    nvidia: "NVIDIA_API_KEY",
     moonshot: "MOONSHOT_API_KEY",
     opencode: "OPENCODE_API_KEY",
     kimi: "KIMI_API_KEY",

package/scripts/platform-smoke/crabbox-runner.mjs

@@ -1,10 +1,10 @@
 /**
- * Thin Crabbox CLI wrapper for pi-oracle's Ubuntu platform smoke target.
+ * Thin Crabbox CLI wrapper for pi-oracle's local platform smoke targets.
  */
 
 import { spawn } from "node:child_process";
 
-const CRABBOX_BIN = process.env.PI_ORACLE_SMOKE_CRABBOX || "crabbox";
+const CRABBOX_BIN = process.env.PI_ORACLE_SMOKE_CRABBOX || process.env.PLATFORM_SMOKE_CRABBOX || "crabbox";
 
 function env(name) {
   return process.env[name] ?? "";
@@ -58,9 +58,9 @@ export function execCrabbox(args, opts = {}) {
 export function buildTargetBaseArgs(targetName, config = {}) {
   switch (targetName) {
     case "macos": {
-      const host = env("PI_ORACLE_SMOKE_MAC_HOST") || "localhost";
-      const user = env("PI_ORACLE_SMOKE_MAC_USER") || env("USER");
-      const workRoot = env("PI_ORACLE_SMOKE_MAC_WORK_ROOT") || `/Users/${env("USER")}/crabbox/pi-oracle`;
+      const host = env("PI_ORACLE_SMOKE_MAC_HOST") || env("PLATFORM_SMOKE_MAC_HOST") || "localhost";
+      const user = env("PI_ORACLE_SMOKE_MAC_USER") || env("PLATFORM_SMOKE_MAC_USER") || env("USER");
+      const workRoot = env("PI_ORACLE_SMOKE_MAC_WORK_ROOT") || env("PLATFORM_SMOKE_MAC_WORK_ROOT") || `/Users/${env("USER")}/crabbox/${config.packageName ?? "pi-oracle"}`;
       return [
         "--provider", "ssh",
         "--target", "macos",
@@ -81,7 +81,7 @@ export function buildTargetBaseArgs(targetName, config = {}) {
     case "windows-native": {
       const vm = env("PI_ORACLE_SMOKE_WINDOWS_VM") || env("PLATFORM_SMOKE_WINDOWS_VM") || config.windowsParallels?.sourceVm || "pi-extension-windows-template";
       const snapshot = env("PI_ORACLE_SMOKE_WINDOWS_SNAPSHOT") || env("PLATFORM_SMOKE_WINDOWS_SNAPSHOT") || config.windowsParallels?.snapshot || "crabbox-ready";
-      const user = env("PI_ORACLE_SMOKE_WINDOWS_USER") || env("USER");
+      const user = env("PI_ORACLE_SMOKE_WINDOWS_USER") || env("PLATFORM_SMOKE_WINDOWS_USER") || env("USER");
       const workRoot = env("PI_ORACLE_SMOKE_WINDOWS_NATIVE_WORK_ROOT") || env("PLATFORM_SMOKE_WINDOWS_WORK_ROOT") || `C:\\crabbox\\${config.packageName ?? "pi-oracle"}`;
       return [
         "--provider", "parallels",

package/scripts/platform-smoke/invariants.mjs

@@ -17,6 +17,15 @@ function runNode(args) {
   return spawnSync(process.execPath, args, { cwd: repoRoot, encoding: "utf8" });
 }
 
+function testHelpTextIncludesTargetsAndExamples() {
+  const result = runNode(["scripts/platform-smoke.mjs", "--help"]);
+  assert.equal(result.status, 0, `help should exit cleanly: ${result.stderr}`);
+  assert.match(result.stdout, /Supported: macos,ubuntu,windows-native/, "help should list supported targets");
+  assert.match(result.stdout, /--suite\s+Suite name\. Supported: platform-build,real-extension/, "help should list supported suites");
+  assert.match(result.stdout, /npm run release:check/, "help should name the full release gate");
+  assert.match(result.stdout, /PLATFORM_SMOKE_CRABBOX/, "help should document reusable platform-smoke env knobs");
+}
+
 function testTargetSelection() {
   const result = runNode(["scripts/platform-smoke.mjs", "run", "--target", "not-a-target", "--suite", "platform-build"]);
   assert.notEqual(result.status, 0, "unsupported targets should fail before Crabbox runs");
@@ -79,9 +88,15 @@ function testCanonicalWorkflowConfig() {
   assert.deepEqual(config.workflows?.everyday?.commands, ["npm run verify:oracle"], "everyday workflow should use the local verification gate");
   assert(config.workflows?.platformSensitive?.commands?.includes("npm run smoke:platform:doctor"), "platform-sensitive workflow should start with doctor");
   assert(config.workflows?.platformSensitive?.commands?.some((command) => command.includes("--target <target> --suite <suite>")), "platform-sensitive workflow should document focused target/suite runs");
-  assert.deepEqual(config.workflows?.release?.commands, ["npm run smoke:platform:all"], "release workflow should use the full platform matrix");
+  assert.deepEqual(config.workflows?.platformMatrix?.commands, ["npm run smoke:platform:all"], "platform matrix workflow should use the full target matrix");
+  assert.deepEqual(config.workflows?.release?.commands, ["npm run release:check"], "release workflow should use the full local-plus-platform release gate");
+  assert.equal(config.requiredCrabbox?.minVersion, "0.26.0", "Crabbox baseline should match the documented provider contract");
   assert.equal(pkg.scripts["smoke:platform:all"], "npm run smoke:platform:doctor && node scripts/platform-smoke.mjs run --target macos,ubuntu,windows-native", "full platform smoke should remain doctor-first and cover all required targets");
   assert.match(pkg.scripts["release:check"], /npm run verify:oracle && npm run smoke:platform:all/, "release check should combine local verification and full platform smoke");
+  const runnerSource = readFileSync(new URL("./crabbox-runner.mjs", import.meta.url), "utf8");
+  assert.match(runnerSource, /PLATFORM_SMOKE_CRABBOX/, "runner should honor reusable Crabbox binary override");
+  assert.match(runnerSource, /PLATFORM_SMOKE_MAC_WORK_ROOT/, "runner should honor reusable macOS work-root override");
+  assert.match(runnerSource, /PLATFORM_SMOKE_WINDOWS_WORK_ROOT/, "runner should honor reusable Windows work-root override");
 }
 
 function testRealSmokeExpensiveAgentPathsAreOptIn() {
@@ -96,6 +111,7 @@ function testRealSmokeExpensiveAgentPathsAreOptIn() {
   assert.match(source, /truthy\(env\("PI_ORACLE_REAL_TEST_NEGATIVE_SYMLINK"\)\)/, "negative symlink real-agent check should be opt-in");
 }
 
+testHelpTextIncludesTargetsAndExamples();
 testTargetSelection();
 testPackedInstallCommandRendering();
 testRealExtensionPackedInstallRendering();

package/scripts/platform-smoke/targets.mjs

@@ -1,6 +1,6 @@
 /**
- * Ubuntu platform-build suite for pi-oracle.
- * The suite proves the PR's package builds/tests on Linux and installs through pi's package path.
+ * Cross-platform smoke suites for pi-oracle.
+ * The suites prove the package builds, packs, installs, loads, and runs through pi's package path.
  */
 
 import { readFileSync, writeFileSync } from "node:fs";

package/scripts/platform-smoke.mjs

@@ -41,21 +41,24 @@ Examples:
 Canonical workflows:
   Everyday local iteration: npm run verify:oracle
   Platform-sensitive changes: npm run smoke:platform:doctor, then focused run --target <target> --suite <suite>
-  Publish/release proof: npm run smoke:platform:all
+  Platform matrix proof: npm run smoke:platform:all
+  Full release gate: npm run release:check
 
 Environment:
-  PI_ORACLE_SMOKE_CRABBOX        Optional Crabbox binary override (defaults to PATH)
-  PI_ORACLE_SMOKE_MAC_HOST       macOS SSH host (default: localhost)
-  PI_ORACLE_SMOKE_MAC_USER       macOS SSH user (default: $USER)
-  PI_ORACLE_SMOKE_MAC_WORK_ROOT  macOS Crabbox work root
-  PI_ORACLE_SMOKE_UBUNTU_IMAGE   Optional local-container image override
-  PI_ORACLE_SMOKE_WINDOWS_VM      Parallels source VM (default from config)
-  PI_ORACLE_SMOKE_WINDOWS_SNAPSHOT Parallels snapshot (default from config)
-  PI_ORACLE_SMOKE_WINDOWS_USER    Windows SSH user (default: $USER)
-  PI_ORACLE_SMOKE_WINDOWS_NATIVE_WORK_ROOT Windows work root
+  PLATFORM_SMOKE_CRABBOX         Reusable Crabbox binary override (defaults to PATH)
+  PI_ORACLE_SMOKE_CRABBOX        Project-specific Crabbox binary override (wins over PLATFORM_SMOKE_CRABBOX)
+  PLATFORM_SMOKE_MAC_HOST        macOS SSH host (default: localhost)
+  PLATFORM_SMOKE_MAC_USER        macOS SSH user (default: $USER)
+  PLATFORM_SMOKE_MAC_WORK_ROOT   macOS Crabbox work root
+  PLATFORM_SMOKE_UBUNTU_IMAGE    Optional local-container image override
+  PLATFORM_SMOKE_WINDOWS_VM      Parallels source VM (default from config)
+  PLATFORM_SMOKE_WINDOWS_SNAPSHOT Parallels snapshot (default from config)
+  PLATFORM_SMOKE_WINDOWS_USER    Windows SSH user (default: $USER)
+  PLATFORM_SMOKE_WINDOWS_WORK_ROOT Windows work root
+  PI_ORACLE_SMOKE_*              Project-specific aliases for the PLATFORM_SMOKE_* knobs above
   PI_ORACLE_REAL_TEST_PROVIDER   Real smoke provider (default: zai)
   PI_ORACLE_REAL_TEST_MODEL      Real smoke model (default: glm-5.1)
-  ZAI_API_KEY                    Default real-smoke provider API key
+  ZAI_API_KEY                    Default real-smoke provider API key for optional model-agent debugging
 `);
 }