pi-agent-browser-native 0.2.43 → 0.2.44

package/CHANGELOG.md

@@ -4,6 +4,17 @@
 
 No changes yet.
 
+## 0.2.44 - 2026-06-04
+
+### Changed
+
+- Updated the local Pi development baseline to `@earendil-works/*` `0.78.1` after reviewing the installed Pi 0.78.1 changelog, docs, examples, and extension source. The audit found no runtime migration needed for `ctx.mode` or command-only `ctx.getSystemPromptOptions()`, and kept the public peer dependency ranges non-pinning.
+- Extended the read-only package doctor with a warning-only `pi --version` check so release validation can catch a Pi CLI older than the audited 0.78.1 floor without making Pi 0.78.1 a hard runtime requirement.
+
+### Validation
+
+- Ran checkout-based interactive `tmux` Pi dogfood with `pi --no-extensions --no-skills -e .` on Pi 0.78.1: `agent_browser` opened and snapshotted `https://example.com`, ran a QA preset against `https://react.dev` expecting `React`, saved and verified a screenshot, reported no console/network/page errors, closed the browser session, and cleaned the temp artifact directory.
+
 ## 0.2.43 - 2026-06-04
 
 ### Added

package/README.md

@@ -74,6 +74,8 @@ The result is optimized for agent work:
 
 ## Fastest way to try it
 
+Use Pi 0.78.1 or newer when possible. This package does not hard-pin Pi 0.78.1 as a runtime requirement, but the current release is audited and validated against that extension/package baseline.
+
 Install upstream `agent-browser` first and make sure it is on `PATH`:
 
 - https://agent-browser.dev/
@@ -142,6 +144,7 @@ The doctor checks:
 
 - upstream `agent-browser` exists on `PATH`
 - the installed upstream version matches this wrapper's command-reference baseline
+- `pi --version` meets the recommended Pi floor for this release, as a warning rather than a hard failure
 - Pi settings do not point at multiple active `pi-agent-browser-native` sources
 
 It does **not** edit Pi settings and does **not** run upstream `agent-browser doctor --fix`.
@@ -575,10 +578,11 @@ Cross-platform release coverage uses Crabbox to run macOS, Ubuntu Linux, and nat
 ```bash
 npm run check:platform-smoke
 npm run smoke:platform:ubuntu-image
+npm run smoke:platform:doctor
 npm run smoke:platform:all
 ```
 
-The required matrix is documented in [`docs/platform-smoke.md`](docs/platform-smoke.md). It runs `platform-build` (fast target-local verify, pack, clean packed Pi install, `pi list`) and `browser-dogfood-smoke` (real `agent-browser`/browser wrapper smoke) on every target.
+The required matrix is documented in [`docs/platform-smoke.md`](docs/platform-smoke.md). It runs `platform-build` (fast target-local verify, pack, clean packed Pi install, `pi list`) and `browser-dogfood-smoke` (real `agent-browser`/browser wrapper smoke) on every target. Inspect `.artifacts/platform-smoke/` and check `crabbox list --provider local-container` plus `crabbox list --provider parallels` after release runs so cleanup proof is not chat-only.
 
 For package release confidence, follow [`docs/RELEASE.md`](docs/RELEASE.md). The release gate is:
 
@@ -586,6 +590,7 @@ For package release confidence, follow [`docs/RELEASE.md`](docs/RELEASE.md). The
 npm run doctor
 npm run check:platform-smoke
 npm run smoke:platform:ubuntu-image
+npm run smoke:platform:doctor
 npm run verify -- release
 ```
 

package/docs/RELEASE.md

@@ -26,10 +26,11 @@ npm install
 npm run doctor
 npm run check:platform-smoke
 npm run smoke:platform:ubuntu-image
+npm run smoke:platform:doctor
 npm run verify -- release
 ```
 
-`npm run doctor` is a read-only first-run diagnostic for PATH, targeted upstream version, and duplicate package/checkout source conflicts. It does not replace upstream `agent-browser doctor` for browser runtime health and does not edit Pi settings.
+`npm run doctor` is a read-only first-run diagnostic for PATH, targeted upstream version, the recommended Pi release floor, and duplicate package/checkout source conflicts. The Pi version check is a warning, not a hard runtime requirement. It does not replace upstream `agent-browser doctor` for browser runtime health and does not edit Pi settings.
 
 `npm run verify -- release` runs:
 
@@ -50,12 +51,17 @@ npm run verify -- dogfood
 For direct Crabbox diagnostics outside the full release compose, run:
 
 ```bash
-npm run smoke:platform:doctor
+npm run check:platform-smoke
 npm run smoke:platform:ubuntu-image
+npm run smoke:platform:doctor
 npm run smoke:platform:all
+crabbox list --provider local-container
+crabbox list --provider parallels
 ```
 
-This mode uses the extension harness and the real `agent-browser` on `PATH` against a deterministic local file fixture, then verifies top-level `qa`, `semanticAction`, constrained `job`, screenshot artifact verification, and session close. Use `npm run verify -- dogfood --keep-artifacts` or `--artifact-dir <path>` only while debugging, then delete retained screenshots. This smoke complements, but does not replace, human-readable interactive transcript evidence.
+The Crabbox gate is only green when suite assertions and artifact manifests under `.artifacts/platform-smoke/` are green and no unexpected lease/clone remains.
+
+The deterministic dogfood mode uses the extension harness and the real `agent-browser` on `PATH` against a deterministic local file fixture, then verifies top-level `qa`, `semanticAction`, constrained `job`, screenshot artifact verification, and session close. Use `npm run verify -- dogfood --keep-artifacts` or `--artifact-dir <path>` only while debugging, then delete retained screenshots. This smoke complements, but does not replace, human-readable interactive transcript evidence.
 
 Every release also requires interactive `tmux`-driven Pi dogfood with the native `agent_browser` tool against real sites. For extension-focused release smokes, use `pi --no-extensions --no-skills -e .` from the checkout before publish so auto-loaded dogfood/QA skills cannot replace the bounded smoke workflow; run separate skill-enabled dogfood only when validating skill routing or report-generation behavior. Drive prompts with `tmux send-keys`, exercise at least one simple static site and one real documentation/product site, include the higher-level `qa` or `job`/`batch` surfaces when they changed, close every opened browser session, remove screenshots/temp artifacts, and record the outcome in the release notes or support-matrix evidence. Automated localhost, fake-upstream, and deterministic dogfood gates do not replace this human-readable live-site transcript evidence. When `agent_browser_web_search` or package config changed, add one key-free smoke proving the optional tool is absent without config, one fake/unit-backed smoke in the default suite, and one opt-in live Exa or Brave Search check with a real key while confirming the key does not appear in transcripts, stdout/stderr, config status, PR text, or artifacts. When `electron.*` surfaces, attached-session diagnostics, or `qa.attached` changed, add a local Electron pass: `electron.list` → `electron.launch` (expect isolated profile behavior) → `snapshot -i` or `electron.probe` / `qa.attached` → `electron.cleanup` with the returned `launchId`, verifying status/mismatch guidance if you simulate a dead renderer or stale refs. For dense-dashboard stress coverage, use the [public Grafana stress checklist](#public-grafana-stress-checklist) below; it is a maintainer workflow, not bundled product skill or recipe runtime.
 
@@ -227,7 +233,7 @@ These show up often in cloud dev boxes and scripted smokes; they are maintainer
 
 | Topic | What to watch for | Mitigation |
 | --- | --- | --- |
-| **Pi CLI vs repo devDependencies** | Global `pi` older than the `@earendil-works/pi-coding-agent` range in `package.json` can change TUI behavior, `/reload`, and tool routing during lifecycle or checkout smokes. | Align `pi` with the repo’s pinned coding-agent release before release gates (`pi update` or install the matching version). |
+| **Pi CLI vs repo devDependencies** | Global `pi` older than the recommended Pi floor for the release can change TUI behavior, `/reload`, package installs, and tool routing during lifecycle or checkout smokes. | Run `npm run doctor` and align `pi` with the current audited baseline before release gates (`pi update` or install the matching version). The published peer range stays non-pinning; the local release gate should use the audited Pi version. |
 | **npm lockfile (`packageManager`)** | `package.json` pins **npm@11**. npm 10 may only strip optional `libc` metadata on `@esbuild/*` platform entries in `package-lock.json` (no dependency version change). | Prefer `npx -y npm@11.14.0 install` when refreshing the lockfile; do not commit npm-10-only lockfile churn. |
 | **`pi -p` / print mode** | Non-interactive `pi -p` may hang or emit no stdout for long real-browser smokes without a TTY. | Use **tmux**-driven interactive `pi` for release evidence and checkout smokes; reserve `-p` for short, non-browser checks. |
 | **Real-browser cleanup** | `real-upstream`, Sauce Demo, and live-site runs can leave defunct Chrome/`agent-browser` children if a session aborts mid-flow. | Close via `agent_browser` / `agent-browser` `close`, kill stray tmux sessions, and remove temp screenshots/HARs under `/tmp` or your chosen artifact dirs. |

package/docs/SUPPORT_MATRIX.md

@@ -64,7 +64,7 @@ Re-run the gates below before each release; this table records what the closure
 | Packaged Pi smoke | `npm run verify -- package-pi` validates package contents, loads the packaged `agent_browser` tool without requiring optional Brave config, and executes fake-upstream `--version`. | Pass on 2026-06-03 as part of `npm run verify -- release` (`npm run verify -- package-pi` slice). |
 | Deterministic dogfood smoke | `npm run verify -- dogfood` (`scripts/verify-agent-browser-dogfood.ts`) drives the native wrapper against a local file fixture through top-level `qa`, `semanticAction`, constrained `job`, screenshot artifact verification, and session close with the real `agent-browser` on `PATH`. | Pass on 2026-06-03 (`npm run verify -- dogfood`, `agent-browser 0.27.1`; artifacts cleaned by the harness). |
 | Efficiency benchmark | `npm run verify -- benchmark` runs deterministic browser workflow accounting plus focused benchmark tests, including JSONL sampling fixtures and job/qa/sourceLookup/networkSourceLookup/Electron scenario coverage. | Pass on 2026-05-29 (`npm run verify -- benchmark`). |
-| Crabbox platform smoke | `npm run check:platform-smoke` syntax-checks the harness and cheap invariants. `npm run smoke:platform:all` runs doctor first, then fast target-local `platform-build` (`npm run verify -- platform-target`, pack, clean Pi install) plus `browser-dogfood-smoke` on Crabbox `macos`, `ubuntu`, and `windows-native`; see [`platform-smoke.md`](platform-smoke.md). | Pass on 2026-06-03 (`npm run check:platform-smoke`, `npm run smoke:platform:ubuntu-image`, and `npm run verify -- release`, whose platform slice ran the macOS/Ubuntu/native-Windows Crabbox matrix; artifacts cleaned after evidence capture). |
+| Crabbox platform smoke | `npm run check:platform-smoke` syntax-checks the harness and cheap invariants. `npm run smoke:platform:ubuntu-image` builds the project-owned Linux image, `npm run smoke:platform:doctor` checks Crabbox 0.26.0+ and local target readiness, and `npm run smoke:platform:all` runs doctor first, then fast target-local `platform-build` (`npm run verify -- platform-target`, pack, clean Pi install) plus `browser-dogfood-smoke` on Crabbox `macos`, `ubuntu`, and `windows-native`; see [`platform-smoke.md`](platform-smoke.md). Target artifacts include Crabbox/provider/work-root metadata, and release review also checks provider-specific `crabbox list` commands for leftover leases/clones. | Pass on 2026-06-03 (`npm run check:platform-smoke`, `npm run smoke:platform:ubuntu-image`, and `npm run verify -- release`, whose platform slice ran the macOS/Ubuntu/native-Windows Crabbox matrix; artifacts cleaned after evidence capture). |
 | `verify -- release` / `prepublishOnly` | `npm run verify -- release` chains the default gate with packaged Pi smoke and the release-blocking Crabbox platform matrix (`verifySteps` `release` in [`scripts/project.mjs`](../scripts/project.mjs)). `package.json` `prepublishOnly` runs that compose before `npm pack --dry-run` during `npm publish`. It intentionally omits standalone lifecycle, real-upstream, host-only dogfood, and benchmark modes—see [`RELEASE.md`](RELEASE.md#pre-release-checks). | Pass on 2026-06-03 (`npm run verify -- release`, including macOS/Ubuntu/native-Windows Crabbox matrix). |
 | Configured-source lifecycle | `npm run verify -- lifecycle` (`scripts/verify-lifecycle.mjs`) drives `/reload`, closes and relaunches Pi with the same exact `--session-id`, checks the JSONL session header id, session continuity, slash-command sentinel tokens (`v1` then `v2` after rewriting the packaged extension to simulate pickup), persisted spill reachability, and real Pi `tool_result` failure-patch semantics for a QA reclassification with a fake upstream on `PATH`. Default Pi model is `zai/glm-5.1`; default per-step wait is **180000 ms** (`DEFAULT_TIMEOUT_MS`); override model with `--model <id>` and waits with `--timeout-ms <ms>`. Passthrough flags in [`scripts/project.mjs`](../scripts/project.mjs): `--keep-artifacts`, `--model`, `--verbose`, and `--timeout-ms` plus a value (for example `npm run verify -- lifecycle --model openai-codex/gpt-5.5:minimal --keep-artifacts --verbose --timeout-ms 600000`). | Pass on 2026-06-03 (`npm run verify -- lifecycle`). Treat any future unexplained red lifecycle gate as a release blocker. |
 | Quick isolated Pi smoke | `pi --no-extensions --no-skills -e . --tools agent_browser` from repo root; native `agent_browser` only. | Last interactive tmux checkout smoke pass on 2026-05-29 (`agent-browser 0.27.0` at the time). The 2026-06-03 Crabbox matrix now covers clean packed Pi install plus deterministic wrapper dogfood on all required platforms for `agent-browser 0.27.1`; run a new manual tmux smoke before publish when human-readable transcript evidence is required. Broader historical coverage also includes version/help/skills, open/snapshot/click, eval stdin, batch stdin, screenshot, explicit session, `sessionMode: "fresh"`, network requests, console/errors, diff snapshot, stream status/disable, dashboard start/stop, and chat credential-failure pass-through during RQ-0055. |

package/docs/platform-smoke.md

@@ -6,15 +6,18 @@ This is a release-blocking gate. Missing Crabbox setup, Docker, macOS SSH, the n
 
 ## Required release gate
 
-Run the cheap harness checks first, then the full matrix:
+Run the cheap harness checks first, build the project-owned Ubuntu image, run doctor explicitly, then run the full matrix and inspect the evidence:
 
 ```sh
 npm run check:platform-smoke
 npm run smoke:platform:ubuntu-image
+npm run smoke:platform:doctor
 npm run smoke:platform:all
+crabbox list --provider local-container
+crabbox list --provider parallels
 ```
 
-`smoke:platform:all` runs `smoke:platform:doctor` before any target suite starts. The canonical `npm run verify -- release` gate also runs the same platform doctor and full `macos,ubuntu,windows-native` matrix after default verification and packaged Pi smoke, so `npm publish` cannot pass `prepublishOnly` without the platform gate.
+`smoke:platform:all` also runs `smoke:platform:doctor` before any target suite starts, so the explicit doctor step is a readable release checklist step rather than a hidden precondition. The canonical `npm run verify -- release` gate also runs the same platform doctor and full `macos,ubuntu,windows-native` matrix after default verification and packaged Pi smoke, so `npm publish` cannot pass `prepublishOnly` without the platform gate. After the matrix, inspect `.artifacts/platform-smoke/<run-id>/...` summaries and manifests; a green Crabbox exit without matching suite assertions is not release proof. Use provider-specific `crabbox list` commands for cleanup review because this host may have unrelated Crabbox providers configured that require credentials.
 
 Per-target commands are for diagnosis:
 
@@ -43,7 +46,7 @@ crabbox --version
 crabbox providers
 ```
 
-Use `PLATFORM_SMOKE_CRABBOX=/path/to/crabbox` only when testing a non-default Crabbox binary.
+Use Crabbox `0.26.0` or newer. Use `PLATFORM_SMOKE_CRABBOX=/path/to/crabbox` only when testing a non-default Crabbox binary.
 
 Standard configuration knobs:
 
@@ -51,6 +54,8 @@ Standard configuration knobs:
 PLATFORM_SMOKE_MAC_HOST=localhost
 PLATFORM_SMOKE_MAC_USER="$USER"
 PLATFORM_SMOKE_MAC_WORK_ROOT="/Users/$USER/crabbox/pi-agent-browser-native"
+# Optional only when localhost SSH does not use port 22.
+PLATFORM_SMOKE_MAC_PORT=22
 
 # Default local image built by npm run smoke:platform:ubuntu-image.
 PLATFORM_SMOKE_UBUNTU_IMAGE="pi-agent-browser-native-platform:node24-agent-browser0.27.1"
@@ -64,7 +69,7 @@ PLATFORM_SMOKE_WINDOWS_WORK_ROOT="C:\\crabbox\\pi-agent-browser-native"
 PLATFORM_SMOKE_AUTH_ENV=""
 ```
 
-The Ubuntu target image is derived from `node:24-bookworm`, installs `agent-browser@0.27.1`, installs Debian Chromium through apt, creates a non-root `circleci` user, and sets `AGENT_BROWSER_EXECUTABLE_PATH=/usr/bin/chromium`. Rebuild it after upstream rebaselining, or override `PLATFORM_SMOKE_UBUNTU_IMAGE` with an equivalent prepared local image. Do not install `agent-browser` ad hoc inside the Ubuntu smoke command.
+The Ubuntu target image is derived from `node:24-bookworm`, installs `agent-browser@0.27.1`, installs Debian Chromium through apt, creates a non-root `circleci` user, and sets `AGENT_BROWSER_EXECUTABLE_PATH=/usr/bin/chromium`. Rebuild it after upstream rebaselining, or override `PLATFORM_SMOKE_UBUNTU_IMAGE` with an equivalent prepared local image. Do not install `agent-browser` ad hoc inside the Ubuntu smoke command; a missing tool is image/template drift.
 
 The configured upstream `agent-browser` baseline is imported from [`scripts/agent-browser-capability-baseline.mjs`](../scripts/agent-browser-capability-baseline.mjs). Target-local browser suites verify that exact `agent-browser` version before running. Bake the exact upstream CLI and browser runtime into the Windows template/snapshot for speed and reproducibility; missing or stale Windows `agent-browser` / browser readiness is a blocked setup, not something the smoke command repairs. The Windows browser suite checks the preinstalled browser cache and prewarms one short local file URL before the extension harness runs.
 
@@ -78,7 +83,7 @@ Crabbox does not install project runtime tools. The macOS host, Ubuntu image, an
 - Browser/runtime dependencies needed by upstream `agent-browser`.
 - Native PowerShell and OpenSSH Server on Windows.
 
-For Windows, reuse `pi-extension-windows-template` with the shared canonical `crabbox-ready` power-off snapshot. Do not create one-off project VMs. If a reusable tool is missing, update the shared template, verify from a fresh SSH session, remove caches/secrets/checkouts, shut down cleanly, and promote a known-good power-off snapshot.
+For Windows, reuse `pi-extension-windows-template` with the shared canonical `crabbox-ready` power-off snapshot configured in [`platform-smoke.config.mjs`](../platform-smoke.config.mjs). Do not create one-off project VMs or run tests directly on the source VM. If a reusable tool is missing, update the shared template, verify from a fresh SSH session, remove caches/secrets/checkouts, shut down cleanly, and promote a known-good power-off snapshot.
 
 ## What the suites prove
 
@@ -108,7 +113,7 @@ The dogfood suite intentionally uses the checkout harness while `platform-build`
 
 ## Artifact contract
 
-Every target suite writes host-side evidence under:
+Every target run writes host-side evidence under one run id shared by that target’s suites:
 
 ```text
 .artifacts/platform-smoke/<run-id>/<target>/<suite>/
@@ -117,9 +122,9 @@ Every target suite writes host-side evidence under:
 Required files include:
 
 ```text
-summary.json
+summary.json           # includes ok, target, suite, exit code, elapsed time, writtenAt
 artifact-manifest.json
-target.json
+target.json            # package, package version, Crabbox binary/version, provider, work root/image/template
 suite.json
 command.txt
 exit-code.txt

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-agent-browser-native",
-  "version": "0.2.43",
+  "version": "0.2.44",
   "description": "pi extension that exposes agent-browser as a native tool for browser automation",
   "type": "module",
   "author": "Mitch Fultz (https://github.com/fitchmultz)",
@@ -62,9 +62,9 @@
     "typebox": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-ai": "^0.78.0",
-    "@earendil-works/pi-coding-agent": "^0.78.0",
-    "@earendil-works/pi-tui": "^0.78.0",
+    "@earendil-works/pi-ai": "^0.78.1",
+    "@earendil-works/pi-coding-agent": "^0.78.1",
+    "@earendil-works/pi-tui": "^0.78.1",
     "@types/node": "^25.6.1",
     "tsx": "^4.21.0",
     "typebox": "^1.1.38",

package/platform-smoke.config.mjs

@@ -8,11 +8,20 @@ export default {
 	artifactRoot: ".artifacts/platform-smoke",
 	requiredTargets: ["macos", "ubuntu", "windows-native"],
 	requiredSuites: ["platform-build", "browser-dogfood-smoke"],
+	supportedTargets: ["macos", "ubuntu", "windows-native"],
 	requiredCrabbox: {
 		install: "Homebrew package or PLATFORM_SMOKE_CRABBOX override",
-		minVersion: "0.24.0",
+		minVersion: "0.26.0",
+	},
+	macos: {
+		host: "localhost",
+		port: 22,
 	},
 	ubuntuContainerImage: "pi-agent-browser-native-platform:node24-agent-browser0.27.1",
+	windowsParallels: {
+		sourceVm: "pi-extension-windows-template",
+		snapshot: "crabbox-ready",
+	},
 	nodeValidationMajor: 22,
 	agentBrowserVersion: CAPABILITY_BASELINE.targetVersion,
 };

package/scripts/doctor.mjs

@@ -22,6 +22,7 @@ const PACKAGE_NAME = "pi-agent-browser-native";
 const REPO_URL_FRAGMENT = "github.com/fitchmultz/pi-agent-browser-native";
 const EXTENSION_ENTRYPOINT = "extensions/agent-browser/index.ts";
 const EXPECTED_VERSION = CAPABILITY_BASELINE.targetVersion;
+const RECOMMENDED_PI_VERSION = "0.78.1";
 const DEFAULT_AGENT_DIR = resolve(homedir(), ".pi/agent");
 const THIS_PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 
@@ -29,6 +30,27 @@ export function normalizeAgentBrowserVersion(output) {
 	return String(output ?? "").trim().replace(/^agent-browser\s+/, "");
 }
 
+export function normalizePiVersion(output) {
+	return String(output ?? "").trim().replace(/^pi\s+/, "");
+}
+
+function parseVersionParts(version) {
+	const match = String(version ?? "").match(/^(\d+)\.(\d+)\.(\d+)(?:\b|[-+])/);
+	if (!match) return undefined;
+	return match.slice(1).map((part) => Number.parseInt(part, 10));
+}
+
+function versionAtLeast(actual, minimum) {
+	const actualParts = parseVersionParts(actual);
+	const minimumParts = parseVersionParts(minimum);
+	if (!actualParts || !minimumParts) return undefined;
+	for (let index = 0; index < minimumParts.length; index += 1) {
+		if (actualParts[index] > minimumParts[index]) return true;
+		if (actualParts[index] < minimumParts[index]) return false;
+	}
+	return true;
+}
+
 function printHelp() {
 	console.log(`pi-agent-browser-doctor
 
@@ -45,7 +67,8 @@ Options:
 Checks:
   1. agent-browser is installed on PATH.
   2. agent-browser --version matches the package capability baseline.
-  3. Pi settings and repo-local autoload locations do not point at multiple active pi-agent-browser-native sources.
+  3. pi --version is at least the recommended Pi floor for this release.
+  4. Pi settings and repo-local autoload locations do not point at multiple active pi-agent-browser-native sources.
 
 Examples:
   pi-agent-browser-doctor
@@ -101,6 +124,11 @@ async function defaultRunAgentBrowser(args) {
 	return `${stdout}${stderr}`;
 }
 
+async function defaultRunPi(args) {
+	const { stdout, stderr } = await execFile("pi", args, { maxBuffer: 1024 * 1024 });
+	return `${stdout}${stderr}`;
+}
+
 async function defaultPathExists(path) {
 	try {
 		await access(path);
@@ -270,6 +298,43 @@ async function collectRepoLocalSources({ cwd, pathExists }) {
 	return sources;
 }
 
+async function checkPiVersion({ runPi }) {
+	try {
+		const rawOutput = await runPi(["--version"]);
+		const version = normalizePiVersion(rawOutput);
+		const supported = versionAtLeast(version, RECOMMENDED_PI_VERSION);
+		if (supported === false) {
+			return {
+				status: "warn",
+				title: `Pi ${RECOMMENDED_PI_VERSION} or newer is recommended; found ${version || "<empty>"}.`,
+				lines: [
+					"This package does not hard-pin Pi 0.78.1, but this release was audited against Pi 0.78.1 extension/package behavior.",
+					"Update Pi before release validation or lifecycle debugging if you see tool routing, /reload, exact-session, or package-install differences.",
+				],
+			};
+		}
+		if (supported === undefined) {
+			return {
+				status: "warn",
+				title: `Could not parse pi --version output: ${version || "<empty>"}.`,
+				lines: [`Pi ${RECOMMENDED_PI_VERSION} or newer is recommended for this release's validation baseline.`],
+			};
+		}
+		return { status: "pass", title: `Pi version is within the recommended baseline: ${version}`, lines: [] };
+	} catch (error) {
+		const code = error && typeof error === "object" ? error.code : undefined;
+		return {
+			status: "warn",
+			title: "Could not inspect pi --version.",
+			lines: [
+				`Pi ${RECOMMENDED_PI_VERSION} or newer is recommended for this release's validation baseline, but it is not hard-pinned as a runtime requirement.`,
+				"Make sure the same shell that launches pi can run `pi --version` when debugging lifecycle or package-install behavior.",
+				code && code !== "ENOENT" ? `Spawn error: ${String(code)}` : undefined,
+			].filter(Boolean),
+		};
+	}
+}
+
 async function checkAgentBrowserVersion({ runAgentBrowser }) {
 	try {
 		const rawOutput = await runAgentBrowser(["--version"]);
@@ -358,6 +423,7 @@ export async function evaluateDoctor(options = {}) {
 	const readText = options.readText ?? ((path) => readFile(path, "utf8"));
 	const pathExists = options.pathExists ?? defaultPathExists;
 	const runAgentBrowser = options.runAgentBrowser ?? defaultRunAgentBrowser;
+	const runPi = options.runPi ?? defaultRunPi;
 	const checks = [];
 	const failures = [];
 	const warnings = [];
@@ -366,6 +432,9 @@ export async function evaluateDoctor(options = {}) {
 	checks.push(versionCheck);
 	if (versionCheck.status === "fail") failures.push(versionCheck);
 
+	const piVersionCheck = await checkPiVersion({ runPi });
+	checks.push(piVersionCheck);
+
 	if (!options.skipSourceCheck) {
 		const sourceCheck = await checkPiSources({ cwd, agentDir, settingsPaths, readText, pathExists });
 		checks.push(sourceCheck);

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

@@ -14,49 +14,77 @@ function packageSlug(config = {}) {
 	return process.env.PLATFORM_SMOKE_PACKAGE_SLUG || config.packageName || "pi-agent-browser-native";
 }
 
-export function buildTargetBaseArgs(targetName, config = {}) {
+export function describeTarget(targetName, config = {}) {
+	const slug = packageSlug(config);
 	switch (targetName) {
 		case "macos": {
 			const user = env("PLATFORM_SMOKE_MAC_USER") || env("USER");
-			const host = env("PLATFORM_SMOKE_MAC_HOST") || "localhost";
-			const workRoot = env("PLATFORM_SMOKE_MAC_WORK_ROOT") || `/Users/${user}/crabbox/${packageSlug(config)}`;
-			return [
-				"--provider", "ssh",
-				"--target", "macos",
-				"--static-host", host,
-				"--static-user", user,
-				"--static-port", "22",
-				"--static-work-root", workRoot,
-			];
+			const host = env("PLATFORM_SMOKE_MAC_HOST") || config.macos?.host || "localhost";
+			const port = String(env("PLATFORM_SMOKE_MAC_PORT") || config.macos?.port || 22);
+			const workRoot = env("PLATFORM_SMOKE_MAC_WORK_ROOT") || config.macos?.workRoot || `/Users/${user}/crabbox/${slug}`;
+			return {
+				provider: "ssh",
+				crabboxTarget: "macos",
+				shell: "posix",
+				workRoot,
+				args: [
+					"--provider", "ssh",
+					"--target", "macos",
+					"--static-host", host,
+					"--static-user", user,
+					"--static-port", port,
+					"--static-work-root", workRoot,
+				],
+			};
 		}
 		case "ubuntu": {
 			const image = env("PLATFORM_SMOKE_UBUNTU_IMAGE") || config.ubuntuContainerImage || "pi-agent-browser-native-platform:node24-agent-browser0.27.1";
-			return [
-				"--provider", "local-container",
-				"--target", "linux",
-				"--local-container-image", image,
-			];
+			return {
+				provider: "local-container",
+				crabboxTarget: "linux",
+				shell: "posix",
+				image,
+				workRoot: config.localContainer?.workRoot || "/work/crabbox",
+				args: [
+					"--provider", "local-container",
+					"--target", "linux",
+					"--local-container-image", image,
+				],
+			};
 		}
 		case "windows-native": {
-			const vm = env("PLATFORM_SMOKE_WINDOWS_VM") || "pi-extension-windows-template";
-			const snapshot = env("PLATFORM_SMOKE_WINDOWS_SNAPSHOT") || "crabbox-ready";
-			const user = env("PLATFORM_SMOKE_WINDOWS_USER") || env("USER");
-			const workRoot = env("PLATFORM_SMOKE_WINDOWS_WORK_ROOT") || `C:\\crabbox\\${packageSlug(config)}`;
-			return [
-				"--provider", "parallels",
-				"--target", "windows",
-				"--windows-mode", "normal",
-				"--parallels-source", vm,
-				"--parallels-source-snapshot", snapshot,
-				"--parallels-user", user,
-				"--parallels-work-root", workRoot,
-			];
+			const vm = env("PLATFORM_SMOKE_WINDOWS_VM") || config.windowsParallels?.sourceVm || "pi-extension-windows-template";
+			const snapshot = env("PLATFORM_SMOKE_WINDOWS_SNAPSHOT") || config.windowsParallels?.snapshot || "crabbox-ready";
+			const user = env("PLATFORM_SMOKE_WINDOWS_USER") || config.windowsParallels?.user || env("USER");
+			const workRoot = env("PLATFORM_SMOKE_WINDOWS_WORK_ROOT") || config.windowsParallels?.workRoot || `C:\\crabbox\\${slug}`;
+			return {
+				provider: "parallels",
+				crabboxTarget: "windows",
+				shell: "powershell",
+				workRoot,
+				windowsMode: "normal",
+				sourceVm: vm,
+				snapshot,
+				args: [
+					"--provider", "parallels",
+					"--target", "windows",
+					"--windows-mode", "normal",
+					"--parallels-source", vm,
+					"--parallels-source-snapshot", snapshot,
+					"--parallels-user", user,
+					"--parallels-work-root", workRoot,
+				],
+			};
 		}
 		default:
 			throw new Error(`unknown platform smoke target: ${targetName}`);
 	}
 }
 
+export function buildTargetBaseArgs(targetName, config = {}) {
+	return describeTarget(targetName, config).args;
+}
+
 export function leaseIdFor(targetName, slug) {
 	if (targetName === "macos") return "static_localhost";
 	return slug;

package/scripts/platform-smoke/doctor.mjs

@@ -105,6 +105,17 @@ function checkForbiddenProjectFiles(failures) {
 }
 
 function crabboxProviders(cbox) {
+	const jsonOutput = silent(cbox, ["providers", "--json"]);
+	if (jsonOutput) {
+		try {
+			const parsed = JSON.parse(jsonOutput);
+			if (Array.isArray(parsed)) return parsed.map((provider) => provider.name ?? provider.id ?? provider.provider).filter(Boolean);
+			if (Array.isArray(parsed.providers)) return parsed.providers.map((provider) => provider.name ?? provider.id ?? provider.provider).filter(Boolean);
+			if (typeof parsed === "object" && parsed) return Object.keys(parsed.providers ?? parsed);
+		} catch {
+			// Fall through to text parsing for older or non-JSON provider output.
+		}
+	}
 	const output = silent(cbox, ["providers"]);
 	if (!output) return [];
 	return output.split(/\r?\n/)
@@ -212,9 +223,10 @@ export async function runDoctor(config) {
 		const ubuntuImage = env("PLATFORM_SMOKE_UBUNTU_IMAGE") || config?.ubuntuContainerImage || "pi-agent-browser-native-platform:node24-agent-browser0.27.1";
 		checkCrabboxProvider(cbox, ["--provider", "local-container", "--local-container-image", ubuntuImage], "ubuntu local-container", failures);
 		const macUser = env("PLATFORM_SMOKE_MAC_USER") || env("USER");
-		const macHost = env("PLATFORM_SMOKE_MAC_HOST") || "localhost";
-		const macRoot = env("PLATFORM_SMOKE_MAC_WORK_ROOT") || `/Users/${macUser}/crabbox/${packageName}`;
-		checkCrabboxProvider(cbox, ["--provider", "ssh", "--target", "macos", "--static-host", macHost, "--static-user", macUser, "--static-port", "22", "--static-work-root", macRoot], "macOS ssh", failures);
+		const macHost = env("PLATFORM_SMOKE_MAC_HOST") || config?.macos?.host || "localhost";
+		const macPort = String(env("PLATFORM_SMOKE_MAC_PORT") || config?.macos?.port || 22);
+		const macRoot = env("PLATFORM_SMOKE_MAC_WORK_ROOT") || config?.macos?.workRoot || `/Users/${macUser}/crabbox/${packageName}`;
+		checkCrabboxProvider(cbox, ["--provider", "ssh", "--target", "macos", "--static-host", macHost, "--static-user", macUser, "--static-port", macPort, "--static-work-root", macRoot], "macOS ssh", failures);
 	}
 
 	console.log("\n── Docker / Ubuntu ──");
@@ -226,8 +238,9 @@ export async function runDoctor(config) {
 
 	console.log("\n── macOS SSH ──");
 	const sshUser = env("PLATFORM_SMOKE_MAC_USER") || env("USER");
-	const sshHost = env("PLATFORM_SMOKE_MAC_HOST") || "localhost";
-	const sshProbe = shell(`ssh -o BatchMode=yes -o ConnectTimeout=5 -o StrictHostKeyChecking=no ${sshUser}@${sshHost} 'node --version && npm --version && git --version && agent-browser --version'`);
+	const sshHost = env("PLATFORM_SMOKE_MAC_HOST") || config?.macos?.host || "localhost";
+	const sshPort = String(env("PLATFORM_SMOKE_MAC_PORT") || config?.macos?.port || 22);
+	const sshProbe = shell(`ssh -o BatchMode=yes -o ConnectTimeout=5 -o StrictHostKeyChecking=no -p ${sshPort} ${sshUser}@${sshHost} 'node --version && npm --version && git --version && agent-browser --version'`);
 	if (sshProbe) {
 		ok(`SSH ${sshUser}@${sshHost}: ${sshProbe.split(/\r?\n/).join(" | ")}`);
 		if (agentBrowserVersion && !sshProbe.includes(agentBrowserVersion)) fail(`macOS SSH agent-browser does not match expected ${agentBrowserVersion}`, failures);
@@ -241,10 +254,10 @@ export async function runDoctor(config) {
 			fail("prlctl not found", failures);
 		} else {
 			ok("prlctl found");
-			const vmName = env("PLATFORM_SMOKE_WINDOWS_VM") || "pi-extension-windows-template";
-			const snapshot = env("PLATFORM_SMOKE_WINDOWS_SNAPSHOT") || "crabbox-ready";
-			const user = env("PLATFORM_SMOKE_WINDOWS_USER") || env("USER");
-			const workRoot = env("PLATFORM_SMOKE_WINDOWS_WORK_ROOT") || `C:\\crabbox\\${packageName}`;
+			const vmName = env("PLATFORM_SMOKE_WINDOWS_VM") || config?.windowsParallels?.sourceVm || "pi-extension-windows-template";
+			const snapshot = env("PLATFORM_SMOKE_WINDOWS_SNAPSHOT") || config?.windowsParallels?.snapshot || "crabbox-ready";
+			const user = env("PLATFORM_SMOKE_WINDOWS_USER") || config?.windowsParallels?.user || env("USER");
+			const workRoot = env("PLATFORM_SMOKE_WINDOWS_WORK_ROOT") || config?.windowsParallels?.workRoot || `C:\\crabbox\\${packageName}`;
 			const list = shell("prlctl list -a --no-header 2>/dev/null");
 			if (!list) {
 				fail("prlctl list returned no VMs", failures);

package/scripts/platform-smoke/targets.mjs

@@ -1,5 +1,6 @@
 /** Target/suite runner for pi-agent-browser-native platform smoke. */
 
+import { execFileSync } from "node:child_process";
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 
@@ -14,7 +15,7 @@ import {
 	writeManifest,
 	writeSummary,
 } from "./artifacts.mjs";
-import { cleanupStaleTargetState, runOnLease, stopLease, warmupLease } from "./crabbox-runner.mjs";
+import { cleanupStaleTargetState, crabboxBin, describeTarget, runOnLease, stopLease, warmupLease } from "./crabbox-runner.mjs";
 
 export function platformFor(targetName) {
 	return targetName === "windows-native" ? "powershell" : "posix";
@@ -38,6 +39,45 @@ function authEnvAllowList(config = {}) {
 	return names.map((name) => String(name).trim()).filter(Boolean);
 }
 
+function packageVersion() {
+	try {
+		return JSON.parse(readFileSync("package.json", "utf8")).version ?? null;
+	} catch {
+		return null;
+	}
+}
+
+function crabboxVersion() {
+	try {
+		return execFileSync(crabboxBin(), ["--version"], { encoding: "utf8", stdio: "pipe", timeout: 10_000 }).trim().split(/\r?\n/)[0] ?? null;
+	} catch {
+		return null;
+	}
+}
+
+function targetEvidence(config, targetName, runId, slug) {
+	const target = describeTarget(targetName, config);
+	return {
+		targetName,
+		platform: platformFor(targetName),
+		runId,
+		slug,
+		packageName: config.packageName,
+		packageVersion: packageVersion(),
+		crabbox: {
+			binary: crabboxBin(),
+			version: crabboxVersion(),
+			provider: target.provider,
+			target: target.crabboxTarget,
+			workRoot: target.workRoot,
+			image: target.image,
+			windowsMode: target.windowsMode,
+			sourceVm: target.sourceVm,
+			snapshot: target.snapshot,
+		},
+	};
+}
+
 function writeRedacted(path, text, secretValues) {
 	writeFileSync(path, redactSecrets(text ?? "", secretValues));
 }
@@ -141,12 +181,11 @@ function finalizeSuite(suiteDir, checks, summary, expectedFiles) {
 	return { assertions: finalAssertions, manifest: writeManifest(suiteDir, [...expectedFiles, "failures.md"]) };
 }
 
-export function createLeaseCleanupResult(config, targetName, leaseId, stopResult, staleCleanupResult = null) {
+export function createLeaseCleanupResult(config, targetName, leaseId, stopResult, staleCleanupResult = null, runId = makeRunId()) {
 	const suiteName = "lease-cleanup";
-	const runId = makeRunId();
 	const suiteDir = createSuiteDir(config.artifactRoot, runId, targetName, suiteName);
 	const secretValues = collectSecretValues(authEnvAllowList(config));
-	writeFileSync(resolve(suiteDir, "target.json"), JSON.stringify({ targetName, platform: platformFor(targetName), runId, slug: `${config.packageName}-${targetName}` }, null, 2));
+	writeFileSync(resolve(suiteDir, "target.json"), JSON.stringify(targetEvidence(config, targetName, runId, `${config.packageName}-${targetName}`), null, 2));
 	writeFileSync(resolve(suiteDir, "suite.json"), JSON.stringify({ suiteName, leaseId, modelCalls: 0 }, null, 2));
 	writeCommand(suiteDir, `crabbox stop ${targetName} --id ${leaseId}`);
 	writeExitCode(suiteDir, stopResult.code, stopResult.signal);
@@ -180,16 +219,15 @@ export function createLeaseCleanupResult(config, targetName, leaseId, stopResult
 	return { ok: assertions.ok, suiteDir, assertions };
 }
 
-export function createLeaseCleanupFailureResult(config, targetName, leaseId, stopResult) {
-	return createLeaseCleanupResult(config, targetName, leaseId, stopResult);
+export function createLeaseCleanupFailureResult(config, targetName, leaseId, stopResult, runId) {
+	return createLeaseCleanupResult(config, targetName, leaseId, stopResult, null, runId);
 }
 
-export function createLeaseWarmupFailureResult(config, targetName, warmupResult) {
+export function createLeaseWarmupFailureResult(config, targetName, warmupResult, runId = makeRunId()) {
 	const suiteName = "lease-warmup";
-	const runId = makeRunId();
 	const suiteDir = createSuiteDir(config.artifactRoot, runId, targetName, suiteName);
 	const secretValues = collectSecretValues(authEnvAllowList(config));
-	writeFileSync(resolve(suiteDir, "target.json"), JSON.stringify({ targetName, platform: platformFor(targetName), runId, slug: `${config.packageName}-${targetName}` }, null, 2));
+	writeFileSync(resolve(suiteDir, "target.json"), JSON.stringify(targetEvidence(config, targetName, runId, `${config.packageName}-${targetName}`), null, 2));
 	writeFileSync(resolve(suiteDir, "suite.json"), JSON.stringify({ suiteName, modelCalls: 0 }, null, 2));
 	writeCommand(suiteDir, `crabbox warmup ${targetName}`);
 	writeExitCode(suiteDir, warmupResult.code, warmupResult.signal);
@@ -301,14 +339,13 @@ export function buildBrowserDogfoodCommand(targetName, agentBrowserVersion = "0.
 	return lines.join("\n");
 }
 
-async function runBrowserDogfoodSuite(config, targetName, suiteName, leaseSession) {
-	const runId = makeRunId();
+async function runBrowserDogfoodSuite(config, targetName, suiteName, leaseSession, runId = makeRunId()) {
 	const suiteDir = createSuiteDir(config.artifactRoot, runId, targetName, suiteName);
 	const startedAt = Date.now();
 	const platform = platformFor(targetName);
 	const slug = `${config.packageName}-${targetName}`;
 	const command = buildBrowserDogfoodCommand(targetName, config.agentBrowserVersion);
-	writeFileSync(resolve(suiteDir, "target.json"), JSON.stringify({ targetName, platform, runId, slug }, null, 2));
+	writeFileSync(resolve(suiteDir, "target.json"), JSON.stringify(targetEvidence(config, targetName, runId, slug), null, 2));
 	writeFileSync(resolve(suiteDir, "suite.json"), JSON.stringify({ suiteName, modelCalls: 0, realBrowser: true }, null, 2));
 	writeCommand(suiteDir, command);
 
@@ -367,15 +404,14 @@ async function runBrowserDogfoodSuite(config, targetName, suiteName, leaseSessio
 	return { ok: assertions.ok, suiteDir, assertions };
 }
 
-async function runPlatformBuildSuite(config, targetName, suiteName, leaseSession) {
-	const runId = makeRunId();
+async function runPlatformBuildSuite(config, targetName, suiteName, leaseSession, runId = makeRunId()) {
 	const suiteDir = createSuiteDir(config.artifactRoot, runId, targetName, suiteName);
 	const startedAt = Date.now();
 	const platform = platformFor(targetName);
 	const slug = `${config.packageName}-${targetName}`;
 	const command = buildPlatformBuildCommand(targetName, config.packageName, config.nodeValidationMajor);
 	mkdirSync(dirname(suiteDir), { recursive: true });
-	writeFileSync(resolve(suiteDir, "target.json"), JSON.stringify({ targetName, platform, runId, slug }, null, 2));
+	writeFileSync(resolve(suiteDir, "target.json"), JSON.stringify(targetEvidence(config, targetName, runId, slug), null, 2));
 	writeFileSync(resolve(suiteDir, "suite.json"), JSON.stringify({ suiteName, modelCalls: 0 }, null, 2));
 	writeCommand(suiteDir, command);
 
@@ -436,17 +472,18 @@ async function runPlatformBuildSuite(config, targetName, suiteName, leaseSession
 	return { ok: assertions.ok, suiteDir, assertions };
 }
 
-export async function runTargetSuite(config, targetName, suiteName, leaseSession) {
-	if (suiteName === "platform-build") return await runPlatformBuildSuite(config, targetName, suiteName, leaseSession);
-	if (suiteName === "browser-dogfood-smoke") return await runBrowserDogfoodSuite(config, targetName, suiteName, leaseSession);
+export async function runTargetSuite(config, targetName, suiteName, leaseSession, runId) {
+	if (suiteName === "platform-build") return await runPlatformBuildSuite(config, targetName, suiteName, leaseSession, runId);
+	if (suiteName === "browser-dogfood-smoke") return await runBrowserDogfoodSuite(config, targetName, suiteName, leaseSession, runId);
 	throw new Error(`unknown suite: ${suiteName}`);
 }
 
 export async function runTargetSuites(config, targetName, suiteNames) {
 	const slug = `${config.packageName}-${targetName}`;
+	const runId = makeRunId();
 	const lease = await warmupLease(targetName, slug, config);
 	if (!lease.ok) {
-		const warmupFailure = createLeaseWarmupFailureResult(config, targetName, lease);
+		const warmupFailure = createLeaseWarmupFailureResult(config, targetName, lease, runId);
 		return { ok: false, results: [warmupFailure] };
 	}
 	const results = [];
@@ -455,7 +492,7 @@ export async function runTargetSuites(config, targetName, suiteNames) {
 	try {
 		let sync = true;
 		for (const suiteName of suiteNames) {
-			const result = await runTargetSuite(config, targetName, suiteName, { ...lease, sync });
+			const result = await runTargetSuite(config, targetName, suiteName, { ...lease, sync }, runId);
 			results.push(result);
 			sync = false;
 			if (!result.ok) break;
@@ -465,7 +502,7 @@ export async function runTargetSuites(config, targetName, suiteNames) {
 		staleCleanupResult = await cleanupStaleTargetState(targetName, config);
 	}
 	if (stopResult) {
-		results.push(createLeaseCleanupResult(config, targetName, lease.leaseId, stopResult, staleCleanupResult));
+		results.push(createLeaseCleanupResult(config, targetName, lease.leaseId, stopResult, staleCleanupResult, runId));
 	}
 	return { ok: results.every((result) => result.ok), results };
 }

package/scripts/platform-smoke.mjs

@@ -61,6 +61,7 @@ Environment:
   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_MAC_PORT             macOS SSH port; default 22
   PLATFORM_SMOKE_UBUNTU_IMAGE         Ubuntu local-container image; default pi-agent-browser-native-platform:node24-agent-browser0.27.1
   PLATFORM_SMOKE_WINDOWS_VM           Parallels Windows template VM
   PLATFORM_SMOKE_WINDOWS_SNAPSHOT     Parallels snapshot name