pi-cursor-sdk 0.1.31 → 0.1.33

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 ## Unreleased
 
+## 0.1.33 - 2026-06-04
+
+### Fixed
+
+- Prevent connect-node-only Cursor SDK network resets such as `ConnectError: [aborted] read ECONNRESET` from escaping as process-level uncaught exceptions during active Cursor turns, while keeping provenance-free generic ConnectRPC errors unsuppressed (#121).
+- Suppress expected Cursor SDK abort `ConnectError` / `AbortError` shapes during abandoned live-run cancellation so idle-resume and interrupt cleanup paths keep pi alive for later prompts (#120).
+
+## 0.1.32 - 2026-06-02
+
+### Added
+
+- Add a production typing-safety regression test that blocks broad TypeScript escape hatches such as `as unknown as`, `as any`, `as never`, explicit `any`, and production `@ts-ignore` / `@ts-expect-error` usage.
+
+### Changed
+
+- Replace repeated native replay render-test `as never` casts with typed test render fixture helpers.
+- Use the maintained Homebrew Crabbox binary on `PATH` for platform smoke with a `0.24.0` minimum version, keeping `PLATFORM_SMOKE_CRABBOX` as an explicit override only.
+
+### Fixed
+
+- Harden local Cursor cache/config JSON parsing so model-list, context-window, and fast-default files are validated from `unknown` before trusted values are used.
+
 ## 0.1.31 - 2026-06-01
 
 ### Added

package/README.md

@@ -2,7 +2,27 @@
 
 A pi provider extension that lets pi use Cursor models through the local `@cursor/sdk` agent runtime.
 
-Use this extension if you want Cursor's model catalog inside pi while keeping pi's native model picker, thinking controls where the SDK exposes them, session restore, context display, and default footer UX.
+Use this extension if you primarily use Cursor models inside pi and want Cursor's local SDK agent loop preserved while pi adds native model selection, auth, thinking/context controls, session behavior, replay UI, and optional pi tool bridging.
+
+## Why use this instead of an OpenAI-compatible Cursor endpoint?
+
+Use `pi-cursor-sdk` when you primarily want to use Cursor models **inside pi**.
+
+This extension runs Cursor models through the local `@cursor/sdk` agent runtime and keeps Cursor's agent loop intact. pi integrates around that loop: model discovery, model selection, context-window variants, thinking controls where Cursor exposes them, fast/slow aliases, Cursor mode, session handling, native replay cards, and the optional pi tool bridge.
+
+OpenAI-compatible Cursor proxies are useful when you want a generic `/v1/chat/completions` or `/v1/responses` endpoint for many clients such as curl, the OpenAI SDK, OpenCode, or other tools. That compatibility comes from translating Cursor behavior into OpenAI-shaped requests, responses, and tool calls.
+
+For pi users, that translation is usually the wrong abstraction. `pi-cursor-sdk` is pi-specific on purpose: it lets Cursor remain Cursor while making it feel native in pi.
+
+| If you want... | Prefer |
+| --- | --- |
+| First-class Cursor usage inside pi | `pi-cursor-sdk` |
+| Cursor's local SDK agent loop preserved, not replaced by an OpenAI-shaped adapter | `pi-cursor-sdk` |
+| pi model picker, `/login`, `/model`, sessions, context display, footer/status UX | `pi-cursor-sdk` |
+| Cursor SDK local-agent tools, settings, MCP, and native replay surfaced in pi | `pi-cursor-sdk` |
+| pi extension tools exposed to Cursor through a local MCP bridge | `pi-cursor-sdk` |
+| A generic OpenAI-compatible localhost `/v1` API for non-pi clients | An OpenAI-compatible Cursor proxy |
+| One Cursor-ish endpoint shared across several unrelated tools | An OpenAI-compatible Cursor proxy |
 
 ## Quick start
 

package/docs/cursor-testing-lessons.md

@@ -1,6 +1,6 @@
 # Cursor Testing Lessons
 
-> **Platform Smoke (new):** The required cross-platform release gate is `npm run smoke:platform:doctor && npm run smoke:platform:all`. See [docs/platform-smoke.md](./platform-smoke.md). For portable lessons other pi extension projects can adapt without sharing repo-specific state, see [Crabbox Platform Testing Lessons](./crabbox-platform-testing-lessons.md). The live smoke checklist remains useful for inner-loop development but is not the release gate.
+> **Platform Smoke (new):** The required cross-platform release gate is `npm run smoke:platform:doctor && npm run smoke:platform:all`. See [docs/platform-smoke.md](./platform-smoke.md). For portable lessons other pi extension projects can adapt without sharing repo-specific state, see the generic Crabbox platform testing guide at `/Users/mitchfultz/Projects/crabbox/docs/pi-extension-platform-testing.md`. The live smoke checklist remains useful for inner-loop development but is not the release gate.
 
 ## Purpose
 

package/docs/platform-smoke.md

@@ -6,6 +6,8 @@ Branch introduced by: `feat/crabbox-platform-smoke`
 
 Oracle review incorporated: this gate resolves the packed-install workspace conflict, Cursor budget contradiction, Windows shell drift, artifact-on-failure gap, render-location ambiguity, provider-debug ambiguity, and registry-classification gap called out during review.
 
+Crabbox best-practice baseline applied from `~/Projects/crabbox`: Crabbox owns lease, sync, run, evidence transport, and cleanup; this repo owns target policy, package setup, scenario meaning, assertions, artifacts, auth forwarding, redaction, and release criteria.
+
 ## Decision
 
 Crabbox is the required platform smoke runner for `pi-cursor-sdk` releases that touch Cursor provider/runtime behavior.
@@ -52,12 +54,12 @@ The runner uses one supported Crabbox build.
 Current baseline:
 
 ```text
-install: brew install crabbox
-version: 0.24.0
-binary: /opt/homebrew/bin/crabbox on Apple Silicon Homebrew installs
+install: brew install openclaw/tap/crabbox
+version: 0.26.0 or newer
+binary: Homebrew `crabbox` on PATH (`/opt/homebrew/bin/crabbox` on Apple Silicon Homebrew installs)
 ```
 
-Keep this exact version or replace it with another exact released Crabbox version when updating the gate. `smoke:platform:doctor` verifies the configured Crabbox binary and fails on mismatch.
+Use the Homebrew Crabbox binary on PATH for normal release gates. `PLATFORM_SMOKE_CRABBOX=/path/to/crabbox` is only an explicit override for testing a non-default binary. `smoke:platform:doctor` verifies the configured binary and fails when it is older than the configured minimum version.
 
 Required Crabbox providers:
 
@@ -75,6 +77,8 @@ scenario + target capability + artifact contract
 
 not a one-off shell script.
 
+Crabbox is deliberately kept as the transport/lifecycle layer. It must not be treated as proof that the pi extension behavior passed; every suite still fails or passes from project-owned assertions and artifact manifests.
+
 High-level flow:
 
 ```text
@@ -145,19 +149,21 @@ scripts/platform-smoke/artifacts.mjs
 scripts/platform-smoke/card-detect.mjs
 scripts/platform-smoke/crabbox-runner.mjs
 scripts/platform-smoke/doctor.mjs
+scripts/platform-smoke/jsonl-text.mjs
 scripts/platform-smoke/live-suite-runner.mjs
 scripts/platform-smoke/platform-build-windows.ps1
 scripts/platform-smoke/pty-capture.mjs
 scripts/platform-smoke/render-ansi.mjs
 scripts/platform-smoke/scenarios.mjs
 scripts/platform-smoke/targets.mjs
+scripts/platform-smoke/visual-evidence.mjs
 ```
 
 Package scripts:
 
 ```json
 {
-  "check:platform-smoke": "node --check <platform smoke scripts> && vitest run test/smoke-tooling.test.ts",
+  "check:platform-smoke": "node --check platform-smoke.config.mjs && node --check <platform smoke scripts> && vitest run test/smoke-tooling.test.ts",
   "smoke:platform": "node scripts/platform-smoke.mjs",
   "smoke:platform:doctor": "node scripts/platform-smoke.mjs doctor",
   "smoke:platform:macos": "node scripts/platform-smoke.mjs run --target macos",
@@ -167,7 +173,7 @@ Package scripts:
 }
 ```
 
-Add `.artifacts/`, `.crabbox/`, and `.platform-smoke-runs/` to `.gitignore`.
+Add `.artifacts/`, `.crabbox/`, `.debug/`, and `.platform-smoke-runs/` to `.gitignore`.
 
 ## Configuration source
 
@@ -188,21 +194,29 @@ export default {
     "cursor-abort-cleanup",
   ],
   requiredCrabbox: {
-    install: "brew install crabbox",
-    version: "0.24.0",
+    install: "Homebrew package or PLATFORM_SMOKE_CRABBOX override",
+    minVersion: "0.26.0",
   },
   ubuntuContainerImage: "cimg/node:24.16",
   nodeValidationMajor: 24,
+  windowsParallels: {
+    sourceVm: "pi-extension-windows-template",
+    snapshot: "crabbox-ready",
+    workRoot: "C:\\crabbox\\pi-cursor-sdk",
+  },
 };
 ```
 
 `ubuntuContainerImage` defaults the local-container Ubuntu target to an Ubuntu 24.04 Node 24 image with a current glibc baseline for native test dependencies; Crabbox still bootstraps SSH/Git/rsync/curl as needed. `nodeValidationMajor: 24` is the release-smoke validation baseline. It does not change the package engine by itself. A separate compatibility lane can test Node 22.19 later; this required gate validates Node 24 on every target.
 
+`windowsParallels` records this repo's default shared Windows template contract. Environment overrides may point at a temporary candidate template during infrastructure work, but release runs should use the shared `pi-extension-windows-template` / `crabbox-ready` baseline unless this document is updated.
+
 ## Required local environment
 
-The doctor fails if any required value is missing.
+The config owns reusable defaults. Environment variables are local-machine knobs and one-off overrides, not a second source of truth. The doctor fails if required auth or target readiness is missing.
 
 ```bash
+# Optional override; by default the gate uses Homebrew `crabbox` from PATH.
 PLATFORM_SMOKE_CRABBOX=/opt/homebrew/bin/crabbox
 
 PLATFORM_SMOKE_MAC_HOST=localhost
@@ -210,11 +224,13 @@ PLATFORM_SMOKE_MAC_USER="$USER"
 PLATFORM_SMOKE_MAC_WORK_ROOT="/Users/$USER/crabbox/pi-cursor-sdk"
 PLATFORM_SMOKE_UBUNTU_IMAGE="cimg/node:24.16"
 
-PLATFORM_SMOKE_WINDOWS_VM="Windows 11"
+# Optional Parallels overrides; defaults come from platform-smoke.config.mjs.
+PLATFORM_SMOKE_WINDOWS_VM="pi-extension-windows-template"
 PLATFORM_SMOKE_WINDOWS_SNAPSHOT="crabbox-ready"
 PLATFORM_SMOKE_WINDOWS_USER="<windows-ssh-user>"
 PLATFORM_SMOKE_WINDOWS_NATIVE_WORK_ROOT="C:\\crabbox\\pi-cursor-sdk"
 
+# Required for live suites; doctor fails before spending Cursor tokens if absent.
 CURSOR_API_KEY="..."
 ```
 
@@ -277,7 +293,13 @@ Required:
 
 ### Windows template VM
 
-The user's daily Windows VM is not the long-term test target. A dedicated template VM and snapshot are required.
+The user's daily Windows VM is not the long-term test target. Use the shared pi-extension Parallels template unless this project documents a replacement with equal evidence:
+
+```text
+source VM: pi-extension-windows-template
+snapshot: crabbox-ready
+work root: C:\\crabbox\\pi-cursor-sdk
+```
 
 Template requirements:
 
@@ -292,8 +314,9 @@ Template requirements:
 - `node-pty` self-test passes in native Windows.
 - Source VM is powered off.
 - Snapshot named `crabbox-ready` exists.
+- The template contains reusable platform tools only; no repo checkout, `.pi` state, Cursor API key, browser auth, smoke artifacts, or temp files.
 
-Crabbox Parallels creates linked clones from the powered-off snapshot. The source template VM is never used directly for smoke runs.
+Crabbox Parallels creates linked clones from the powered-off snapshot. The source template VM is never used directly for smoke runs. If a run has to install a missing global tool or browser on every Windows clone, treat that as template drift and refresh the shared template instead of making the per-run fallback normal.
 
 ### Windows native
 
@@ -312,13 +335,13 @@ tar --version
 
 Doctor checks:
 
-1. Required env vars exist.
-2. `PLATFORM_SMOKE_CRABBOX` exists and is executable.
+1. Required auth is present and optional target overrides resolve against config defaults.
+2. Homebrew `crabbox` is available on PATH, or `PLATFORM_SMOKE_CRABBOX` points at an executable override.
 3. Crabbox build matches the configured baseline.
 4. Crabbox provider registry includes `local-container`, `ssh`, and `parallels`.
-5. `crabbox doctor --provider local-container --json` passes.
+5. `crabbox doctor --provider local-container --target linux --json` passes.
 6. Docker runtime is active.
-7. macOS SSH localhost probe passes and sees Node, npm, Git, rsync, and tar.
+7. Crabbox macOS static SSH doctor with `--doctor-probe-ssh` passes, and the localhost SSH probe sees Node, npm, Git, rsync, and tar.
 8. `prlctl` exists.
 9. Windows source VM exists.
 10. Windows source snapshot exists.
@@ -357,7 +380,7 @@ Per target, `platform-build` must:
 
 1. Record `node --version` and assert the target Node major is at least `nodeValidationMajor`.
 2. Run `npm ci` in `extensionSourceRoot`.
-3. Run `npm run check:platform-smoke` on the target so smoke harness syntax and invariant tests fail before live Cursor calls, with only the target-local release-tag guard bypassed because Crabbox worktrees may not have release tags.
+3. Run `npm run check:platform-smoke` on the target so config syntax, smoke harness syntax, invalid target/suite guards, and invariant tests fail before live Cursor calls.
 4. Run `npm test` on the target with the same target-local release-tag guard bypass.
 5. Run `npm run typecheck`.
 6. Run `npm pack`.
@@ -378,7 +401,7 @@ Purpose:
 - fail before spending Cursor tokens;
 - produce the packed extension used by later suites.
 
-The host `smoke:platform:all` entrypoint enforces doctor first and then the release-version reuse guard before running targets, using local git tags and `package.json`. Required artifacts include `node-version.txt`, `npm-version.txt`, stdout/stderr for `npm ci`, `npm run check:platform-smoke`, `npm test`, `npm run typecheck`, `npm pack`, packed npm install, `pi install`, and `pi list`, plus `packed-tarball.txt`, `summary.json`, `artifact-manifest.json`, `assertions.json`, and `failures.md` on failed assertions.
+The host `smoke:platform:all` entrypoint enforces doctor first before running targets. Required artifacts include `node-version.txt`, `npm-version.txt`, stdout/stderr for `npm ci`, `npm run check:platform-smoke`, `npm test`, `npm run typecheck`, `npm pack`, packed npm install, `pi install`, and `pi list`, plus `packed-tarball.txt`, `summary.json`, `artifact-manifest.json`, `assertions.json`, and `failures.md` on failed assertions.
 
 ### `cursor-native-visual-matrix`
 
@@ -595,7 +618,7 @@ cursor-abort-cleanup: 1
 
 Maximum per target: `3` Cursor invocations.
 
-Maximum full gate: `12` Cursor invocations.
+Maximum full gate: `9` Cursor invocations.
 
 The merge gate is `npm run smoke:platform:all`; that script runs doctor first and then the matrix to preserve this budget. No suite adds a new Cursor invocation without updating this plan and `platform-smoke.config.mjs`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-cursor-sdk",
-	"version": "0.1.31",
+	"version": "0.1.33",
 	"description": "pi provider extension backed by @cursor/sdk local agents",
 	"author": "Mitch Fultz (https://github.com/fitchmultz)",
 	"license": "MIT",
@@ -69,7 +69,6 @@
 		"docs/cursor-tool-surfaces.md",
 		"docs/cursor-live-smoke-checklist.md",
 		"docs/cursor-testing-lessons.md",
-		"docs/crabbox-platform-testing-lessons.md",
 		"docs/cursor-dogfood-checklist.md",
 		"docs/cursor-native-tool-replay.md",
 		"docs/cursor-native-tool-visual-audit.md",
@@ -98,7 +97,7 @@
 		"debug:sdk-events": "node scripts/debug-sdk-events.mjs",
 		"debug:provider-events": "node scripts/debug-provider-events.mjs",
 		"debug:mcp-coldstart": "node scripts/probe-mcp-coldstart.mjs",
-		"check:platform-smoke": "node --check scripts/platform-smoke.mjs && node --check scripts/platform-smoke/assertions.mjs && node --check scripts/platform-smoke/artifacts.mjs && node --check scripts/platform-smoke/card-detect.mjs && node --check scripts/platform-smoke/crabbox-runner.mjs && node --check scripts/platform-smoke/doctor.mjs && node --check scripts/platform-smoke/jsonl-text.mjs && node --check scripts/platform-smoke/live-suite-runner.mjs && node --check scripts/platform-smoke/pty-capture.mjs && node --check scripts/platform-smoke/render-ansi.mjs && node --check scripts/platform-smoke/scenarios.mjs && node --check scripts/platform-smoke/targets.mjs && node --check scripts/platform-smoke/visual-evidence.mjs && vitest run test/smoke-tooling.test.ts",
+		"check:platform-smoke": "node --check platform-smoke.config.mjs && node --check scripts/platform-smoke.mjs && node --check scripts/platform-smoke/assertions.mjs && node --check scripts/platform-smoke/artifacts.mjs && node --check scripts/platform-smoke/card-detect.mjs && node --check scripts/platform-smoke/crabbox-runner.mjs && node --check scripts/platform-smoke/doctor.mjs && node --check scripts/platform-smoke/jsonl-text.mjs && node --check scripts/platform-smoke/live-suite-runner.mjs && node --check scripts/platform-smoke/pty-capture.mjs && node --check scripts/platform-smoke/render-ansi.mjs && node --check scripts/platform-smoke/scenarios.mjs && node --check scripts/platform-smoke/targets.mjs && node --check scripts/platform-smoke/visual-evidence.mjs && vitest run test/smoke-tooling.test.ts",
 		"smoke:platform": "node scripts/platform-smoke.mjs",
 		"smoke:platform:doctor": "node scripts/platform-smoke.mjs doctor",
 		"smoke:platform:macos": "node scripts/platform-smoke.mjs run --target macos",

package/platform-smoke.config.mjs

@@ -13,9 +13,14 @@ export default {
 		"cursor-abort-cleanup",
 	],
 	requiredCrabbox: {
-		install: "brew install crabbox",
-		version: "0.24.0",
+		install: "Homebrew package or PLATFORM_SMOKE_CRABBOX override",
+		minVersion: "0.26.0",
 	},
 	ubuntuContainerImage: "cimg/node:24.16",
 	nodeValidationMajor: 24,
+	windowsParallels: {
+		sourceVm: "pi-extension-windows-template",
+		snapshot: "crabbox-ready",
+		workRoot: "C:\\crabbox\\pi-cursor-sdk",
+	},
 };

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

@@ -98,10 +98,11 @@ export function buildTargetBaseArgs(targetName, config = {}) {
 			];
 		}
 		case "windows-native": {
-			const vm = env("PLATFORM_SMOKE_WINDOWS_VM") || "pi-extension-windows-template";
-			const snap = env("PLATFORM_SMOKE_WINDOWS_SNAPSHOT") || "crabbox-ready";
-			const user = env("PLATFORM_SMOKE_WINDOWS_USER") || env("USER");
-			const workRoot = env("PLATFORM_SMOKE_WINDOWS_NATIVE_WORK_ROOT") || "C:\\crabbox\\pi-cursor-sdk";
+			const windows = config.windowsParallels ?? {};
+			const vm = env("PLATFORM_SMOKE_WINDOWS_VM") || windows.sourceVm || "pi-extension-windows-template";
+			const snap = env("PLATFORM_SMOKE_WINDOWS_SNAPSHOT") || windows.snapshot || "crabbox-ready";
+			const user = env("PLATFORM_SMOKE_WINDOWS_USER") || windows.user || env("USER");
+			const workRoot = env("PLATFORM_SMOKE_WINDOWS_NATIVE_WORK_ROOT") || windows.workRoot || "C:\\crabbox\\pi-cursor-sdk";
 			return [
 				"--provider", "parallels",
 				"--target", "windows",

package/scripts/platform-smoke/doctor.mjs

@@ -45,17 +45,32 @@ function shell(cmd, opts = {}) {
 	catch { return null; }
 }
 
+function commandPath(command) {
+	return shell(`command -v ${command}`);
+}
+
 function parseLeaseId(output) {
 	return output.match(/\bleased\s+(\S+)/)?.[1]
 		?? output.match(/\blease=(\S+)/)?.[1]
 		?? null;
 }
 
-function windowsCrabboxBaseArgs() {
-	const vm = env("PLATFORM_SMOKE_WINDOWS_VM") || "pi-extension-windows-template";
-	const snap = env("PLATFORM_SMOKE_WINDOWS_SNAPSHOT") || "crabbox-ready";
-	const user = env("PLATFORM_SMOKE_WINDOWS_USER") || env("USER");
-	const workRoot = env("PLATFORM_SMOKE_WINDOWS_NATIVE_WORK_ROOT") || "C:\\crabbox\\pi-cursor-sdk";
+function windowsParallelsDefaults(config = {}) {
+	const windows = config?.windowsParallels ?? {};
+	return {
+		vm: windows.sourceVm || "pi-extension-windows-template",
+		snapshot: windows.snapshot || "crabbox-ready",
+		user: windows.user || env("USER"),
+		workRoot: windows.workRoot || "C:\\crabbox\\pi-cursor-sdk",
+	};
+}
+
+function windowsCrabboxBaseArgs(config = {}) {
+	const defaults = windowsParallelsDefaults(config);
+	const vm = env("PLATFORM_SMOKE_WINDOWS_VM") || defaults.vm;
+	const snap = env("PLATFORM_SMOKE_WINDOWS_SNAPSHOT") || defaults.snapshot;
+	const user = env("PLATFORM_SMOKE_WINDOWS_USER") || defaults.user;
+	const workRoot = env("PLATFORM_SMOKE_WINDOWS_NATIVE_WORK_ROOT") || defaults.workRoot;
 	return [
 		"--provider", "parallels",
 		"--target", "windows",
@@ -87,9 +102,9 @@ function crabbox(cbox, args, timeout = 300_000) {
 	}
 }
 
-function disposableWindowsSshProbe(cbox) {
+function disposableWindowsSshProbe(cbox, config = {}) {
 	const slug = "pi-cursor-sdk-doctor-windows";
-	const baseArgs = windowsCrabboxBaseArgs();
+	const baseArgs = windowsCrabboxBaseArgs(config);
 	const warm = crabbox(cbox, ["warmup", ...baseArgs, "--slug", slug, "--keep", "--reclaim"], 300_000);
 	const leaseId = parseLeaseId(warm.stdout) ?? parseLeaseId(warm.stderr) ?? slug;
 	try {
@@ -126,37 +141,50 @@ function runChecks(config) {
 	// ── Phase 1: environment variables ──
 	console.log("\n── Environment variables ──");
 	const requiredVars = [
-		"PLATFORM_SMOKE_CRABBOX",
 		"CURSOR_API_KEY",
-		"PLATFORM_SMOKE_WINDOWS_VM",
-		"PLATFORM_SMOKE_WINDOWS_SNAPSHOT",
-		"PLATFORM_SMOKE_WINDOWS_USER",
-		"PLATFORM_SMOKE_WINDOWS_NATIVE_WORK_ROOT",
 	];
 	const optionalVars = [
+		"PLATFORM_SMOKE_CRABBOX",
 		"PLATFORM_SMOKE_MAC_HOST",
 		"PLATFORM_SMOKE_MAC_USER",
 		"PLATFORM_SMOKE_MAC_WORK_ROOT",
 		"PLATFORM_SMOKE_UBUNTU_IMAGE",
+		"PLATFORM_SMOKE_WINDOWS_VM",
+		"PLATFORM_SMOKE_WINDOWS_SNAPSHOT",
+		"PLATFORM_SMOKE_WINDOWS_USER",
+		"PLATFORM_SMOKE_WINDOWS_NATIVE_WORK_ROOT",
 	];
 	for (const name of requiredVars) {
 		const v = env(name);
 		v ? ok(`${name} = ${name === "CURSOR_API_KEY" ? "(present, redacted)" : (v.length > 50 ? v.slice(0, 50) + "..." : v)}`)
 			: fail(`${name} missing`);
 	}
+	const windowsDefaults = windowsParallelsDefaults(config);
+	const optionalDefaults = {
+		PLATFORM_SMOKE_WINDOWS_VM: windowsDefaults.vm,
+		PLATFORM_SMOKE_WINDOWS_SNAPSHOT: windowsDefaults.snapshot,
+		PLATFORM_SMOKE_WINDOWS_USER: windowsDefaults.user,
+		PLATFORM_SMOKE_WINDOWS_NATIVE_WORK_ROOT: windowsDefaults.workRoot,
+	};
 	for (const name of optionalVars) {
 		const v = env(name);
-		ok(`${name} = ${v || "(default)"}`);
+		const fallback = optionalDefaults[name] ? `(default: ${optionalDefaults[name]})` : "(default)";
+		ok(`${name} = ${v || fallback}`);
 	}
 
 	// ── Phase 2: Crabbox binary ──
 	console.log("\n── Crabbox binary ──");
-	const cbox = env("PLATFORM_SMOKE_CRABBOX");
-	if (!cbox) {
-		fail("PLATFORM_SMOKE_CRABBOX not set");
+	const cbox = env("PLATFORM_SMOKE_CRABBOX") || "crabbox";
+	const cboxPath = env("PLATFORM_SMOKE_CRABBOX") || commandPath("crabbox");
+	if (!cboxPath) {
+		fail(`crabbox not found on PATH; install with ${config.requiredCrabbox?.install ?? "Homebrew"} or set PLATFORM_SMOKE_CRABBOX`);
 	} else {
-		try { accessSync(cbox, constants.X_OK); ok(`binary: ${cbox}`); }
-		catch { fail(`${cbox} not executable`); }
+		if (env("PLATFORM_SMOKE_CRABBOX")) {
+			try { accessSync(cboxPath, constants.X_OK); ok(`binary: ${cboxPath} (env override)`); }
+			catch { fail(`${cboxPath} not executable`); }
+		} else {
+			ok(`binary: ${cboxPath} (PATH)`);
+		}
 		const ver = silent(cbox, ["--version"]);
 		const actualVersion = ver?.split("\n")[0]?.trim();
 		if (actualVersion) ok(`version: ${actualVersion}`);
@@ -174,9 +202,9 @@ function runChecks(config) {
 		}
 		const requiredCommit = config.requiredCrabbox?.commit;
 		if (!requiredVersion && !minimumVersion && requiredCommit) {
-			const gitRoot = findGitRoot(dirname(cbox));
+			const gitRoot = findGitRoot(dirname(cboxPath));
 			const actualCommit = gitRoot ? silent("git", ["-C", gitRoot, "rev-parse", "HEAD"]) : null;
-			if (!actualCommit) fail(`could not verify Crabbox source commit for ${cbox}`);
+			if (!actualCommit) fail(`could not verify Crabbox source commit for ${cboxPath}`);
 			else if (actualCommit !== requiredCommit) fail(`Crabbox commit mismatch: expected ${requiredCommit}, got ${actualCommit}`);
 			else ok(`commit: ${actualCommit}`);
 		}
@@ -184,7 +212,7 @@ function runChecks(config) {
 
 	// ── Phase 3: Crabbox providers ──
 	console.log("\n── Crabbox providers ──");
-	if (cbox) {
+	if (cboxPath) {
 		const providerList = silent(cbox, ["providers"]);
 		if (providerList) {
 			for (const provider of ["ssh", "local-container", "parallels"]) {
@@ -196,7 +224,7 @@ function runChecks(config) {
 			fail("crabbox providers failed");
 		}
 		const ubuntuImage = env("PLATFORM_SMOKE_UBUNTU_IMAGE") || config?.ubuntuContainerImage || "cimg/node:24.16";
-		const lcDoc = silent(cbox, ["doctor", "--provider", "local-container", "--local-container-image", ubuntuImage, "--json"]);
+		const lcDoc = silent(cbox, ["doctor", "--provider", "local-container", "--target", "linux", "--local-container-image", ubuntuImage, "--json"]);
 		if (lcDoc) {
 			try {
 				const d = JSON.parse(lcDoc);
@@ -214,7 +242,7 @@ function runChecks(config) {
 			"doctor", "--provider", "ssh", "--target", "macos",
 			"--static-host", sshHost, "--static-user", sshUser,
 			"--static-port", "22", "--static-work-root", sshRoot,
-			"--json",
+			"--doctor-probe-ssh", "--json",
 		]);
 		if (sshDoc) {
 			try {
@@ -256,7 +284,7 @@ function runChecks(config) {
 		fail("prlctl not found");
 	} else {
 		ok("prlctl found");
-		const vmName = env("PLATFORM_SMOKE_WINDOWS_VM") || "pi-extension-windows-template";
+		const vmName = env("PLATFORM_SMOKE_WINDOWS_VM") || windowsParallelsDefaults(config).vm;
 		const list = shell("prlctl list -a --no-header 2>/dev/null");
 		if (list) {
 			const vms = list.split("\n").filter(Boolean);
@@ -270,7 +298,7 @@ function runChecks(config) {
 					fail(`VM "${vmName}" state: ${status} — source VM must be stopped for linked clones`);
 				}
 
-				const snapName = env("PLATFORM_SMOKE_WINDOWS_SNAPSHOT") || "crabbox-ready";
+				const snapName = env("PLATFORM_SMOKE_WINDOWS_SNAPSHOT") || windowsParallelsDefaults(config).snapshot;
 				const snapsJson = shell(`prlctl snapshot-list "${vmName}" -j 2>/dev/null`);
 				let snapshotFound = false;
 				let snapshotPowerOff = false;
@@ -314,7 +342,7 @@ function runChecks(config) {
 					} else {
 						ok(`template "${vmName}" has no IP; verifying Windows SSH/tools through a disposable Crabbox clone`);
 						if (cbox && snapshotFound && snapshotPowerOff) {
-							const probe = disposableWindowsSshProbe(cbox);
+							const probe = disposableWindowsSshProbe(cbox, config);
 							probe.ok ? ok(`disposable Windows clone SSH/tool probe OK: ${probe.message}`) : fail(probe.message);
 						} else {
 							fail(`Windows SSH probe could not run because "${vmName}" has no IP and no verified snapshot was available`);

package/scripts/platform-smoke/platform-build-windows.ps1

@@ -62,19 +62,15 @@ Write-SectionFile "NPM_CI_STDOUT" $NpmCiOut
 Write-SectionFile "NPM_CI_STDERR" $NpmCiErr
 
 Write-Output "=== check:platform-smoke ==="
-$env:PI_CURSOR_SKIP_RELEASE_VERSION_GUARD = "1"
 & npm.cmd run check:platform-smoke 1> $CheckPlatformSmokeOut 2> $CheckPlatformSmokeErr
 $CHECK_PLATFORM_SMOKE_EXIT = Exit-CodeFromLastCommand
-Remove-Item Env:\PI_CURSOR_SKIP_RELEASE_VERSION_GUARD -ErrorAction SilentlyContinue
 Write-Output "PLATFORM_CHECK_PLATFORM_SMOKE_EXIT=$CHECK_PLATFORM_SMOKE_EXIT"
 Write-SectionFile "CHECK_PLATFORM_SMOKE_STDOUT" $CheckPlatformSmokeOut
 Write-SectionFile "CHECK_PLATFORM_SMOKE_STDERR" $CheckPlatformSmokeErr
 
 Write-Output "=== npm test ==="
-$env:PI_CURSOR_SKIP_RELEASE_VERSION_GUARD = "1"
 & npm.cmd test 1> $NpmTestOut 2> $NpmTestErr
 $TEST_EXIT = Exit-CodeFromLastCommand
-Remove-Item Env:\PI_CURSOR_SKIP_RELEASE_VERSION_GUARD -ErrorAction SilentlyContinue
 Write-Output "PLATFORM_NPM_TEST_EXIT=$TEST_EXIT"
 Write-SectionFile "NPM_TEST_STDOUT" $NpmTestOut
 Write-SectionFile "NPM_TEST_STDERR" $NpmTestErr

package/scripts/platform-smoke/targets.mjs

@@ -422,14 +422,14 @@ export function buildPlatformBuildCommand(targetName, packageName = "pi-cursor-s
 		lines.push(...posixSection("NPM_CI_STDERR", 'cat "$PACK_DIR/npm-ci.stderr.txt" 2>/dev/null || true'));
 		lines.push("");
 		lines.push('echo "=== check:platform-smoke ==="');
-		lines.push('PI_CURSOR_SKIP_RELEASE_VERSION_GUARD=1 npm run check:platform-smoke >"$PACK_DIR/check-platform-smoke.stdout.txt" 2>"$PACK_DIR/check-platform-smoke.stderr.txt"');
+		lines.push('npm run check:platform-smoke >"$PACK_DIR/check-platform-smoke.stdout.txt" 2>"$PACK_DIR/check-platform-smoke.stderr.txt"');
 		lines.push("CHECK_PLATFORM_SMOKE_EXIT=$?");
 		lines.push('echo "PLATFORM_CHECK_PLATFORM_SMOKE_EXIT=$CHECK_PLATFORM_SMOKE_EXIT"');
 		lines.push(...posixSection("CHECK_PLATFORM_SMOKE_STDOUT", 'cat "$PACK_DIR/check-platform-smoke.stdout.txt" 2>/dev/null || true'));
 		lines.push(...posixSection("CHECK_PLATFORM_SMOKE_STDERR", 'cat "$PACK_DIR/check-platform-smoke.stderr.txt" 2>/dev/null || true'));
 		lines.push("");
 		lines.push('echo "=== npm test ==="');
-		lines.push('PI_CURSOR_SKIP_RELEASE_VERSION_GUARD=1 npm test >"$PACK_DIR/npm-test.stdout.txt" 2>"$PACK_DIR/npm-test.stderr.txt"');
+		lines.push('npm test >"$PACK_DIR/npm-test.stdout.txt" 2>"$PACK_DIR/npm-test.stderr.txt"');
 		lines.push("TEST_EXIT=$?");
 		lines.push('echo "PLATFORM_NPM_TEST_EXIT=$TEST_EXIT"');
 		lines.push(...posixSection("NPM_TEST_STDOUT", 'cat "$PACK_DIR/npm-test.stdout.txt" 2>/dev/null || true'));

package/scripts/platform-smoke.mjs

@@ -3,8 +3,7 @@
 import { createRequire } from "node:module";
 import { resolve, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
-import { accessSync, constants, readFileSync } from "node:fs";
-import { spawnSync } from "node:child_process";
+import { accessSync, constants } from "node:fs";
 
 // ── helpers ────────────────────────────────────────────────────────────────
 const __filename = fileURLToPath(import.meta.url);
@@ -47,11 +46,11 @@ 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 work root
-  PLATFORM_SMOKE_WINDOWS_VM       Parallels source VM name
-  PLATFORM_SMOKE_WINDOWS_SNAPSHOT Snapshot name
-  PLATFORM_SMOKE_WINDOWS_USER     Windows SSH user
-  PLATFORM_SMOKE_UBUNTU_IMAGE        Ubuntu container image
-  PLATFORM_SMOKE_WINDOWS_NATIVE_WORK_ROOT  Windows native work root
+  PLATFORM_SMOKE_UBUNTU_IMAGE     Ubuntu container image
+  PLATFORM_SMOKE_WINDOWS_VM       Parallels source VM override (default from config)
+  PLATFORM_SMOKE_WINDOWS_SNAPSHOT Snapshot override (default from config)
+  PLATFORM_SMOKE_WINDOWS_USER     Windows SSH user override (default: \$USER)
+  PLATFORM_SMOKE_WINDOWS_NATIVE_WORK_ROOT  Windows native work root override (default from config)
 `);
 }
 
@@ -90,17 +89,17 @@ function parseArgs(argv) {
 	return args;
 }
 
-function assertHostReleaseVersionGuard() {
-	const packageJson = JSON.parse(readFileSync(resolve(repoRoot, "package.json"), "utf8"));
-	const result = spawnSync("git", ["tag", "--list", "v[0-9]*.[0-9]*.[0-9]*", "--sort=-v:refname"], {
-		cwd: repoRoot,
-		encoding: "utf8",
-	});
-	if (result.status !== 0) throw new Error(`failed to inspect release tags: ${result.stderr || result.error?.message || "unknown git error"}`);
-	const latestTag = result.stdout.split(/\r?\n/).find((tag) => tag.length > 0);
-	if (!latestTag) throw new Error("no local release tags found; cannot enforce package version reuse guard");
-	const latestVersion = latestTag.replace(/^v/, "");
-	if (packageJson.version === latestVersion) throw new Error(`package version ${packageJson.version} reuses latest release tag ${latestTag}`);
+function validateSelections(targets, suites) {
+	const allowedTargets = new Set(config.requiredTargets ?? []);
+	const allowedSuites = new Set(config.requiredSuites ?? []);
+	const badTargets = targets.filter((target) => !allowedTargets.has(target));
+	const badSuites = suites.filter((suite) => !allowedSuites.has(suite));
+	if (badTargets.length > 0) {
+		throw new Error(`unknown target(s): ${badTargets.join(", ")}; allowed: ${[...allowedTargets].join(", ")}`);
+	}
+	if (badSuites.length > 0) {
+		throw new Error(`unknown suite(s): ${badSuites.join(", ")}; allowed: ${[...allowedSuites].join(", ")}`);
+	}
 }
 
 // ── commands ───────────────────────────────────────────────────────────────
@@ -158,7 +157,6 @@ async function main() {
 	}
 
 	if (args.command === "run") {
-		assertHostReleaseVersionGuard();
 		const targets = args.target
 			? args.target.split(",").map((s) => s.trim()).filter(Boolean)
 			: config.requiredTargets;
@@ -167,6 +165,13 @@ async function main() {
 			? [args.suite]
 			: config.requiredSuites;
 
+		try {
+			validateSelections(targets, suites);
+		} catch (err) {
+			console.error(err.message);
+			process.exit(2);
+		}
+
 		const targetRuns = targets.map(async (targetName) => {
 			console.log(`\n=== Target: ${targetName} ===`);
 			const result = args.suite