pi-cursor-sdk 0.1.32 → 0.1.33

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## 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

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.
@@ -53,7 +55,7 @@ Current baseline:
 
 ```text
 install: brew install openclaw/tap/crabbox
-version: 0.24.0 or newer
+version: 0.26.0 or newer
 binary: Homebrew `crabbox` on PATH (`/opt/homebrew/bin/crabbox` on Apple Silicon Homebrew installs)
 ```
 
@@ -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
 
@@ -189,18 +195,25 @@ export default {
   ],
   requiredCrabbox: {
     install: "Homebrew package or PLATFORM_SMOKE_CRABBOX override",
-    minVersion: "0.24.0",
+    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.
@@ -211,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="..."
 ```
 
@@ -278,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:
 
@@ -293,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
 
@@ -313,13 +335,13 @@ tar --version
 
 Doctor checks:
 
-1. Required env vars exist.
+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.
@@ -358,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`.
@@ -379,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`
 
@@ -596,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.32",
+	"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

@@ -14,8 +14,13 @@ export default {
 	],
 	requiredCrabbox: {
 		install: "Homebrew package or PLATFORM_SMOKE_CRABBOX override",
-		minVersion: "0.24.0",
+		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

@@ -55,11 +55,22 @@ function parseLeaseId(output) {
 		?? 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",
@@ -91,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 {
@@ -131,10 +142,6 @@ function runChecks(config) {
 	console.log("\n── Environment variables ──");
 	const requiredVars = [
 		"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",
@@ -142,15 +149,27 @@ function runChecks(config) {
 		"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 ──
@@ -205,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);
@@ -223,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 {
@@ -265,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);
@@ -279,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;
@@ -323,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

package/src/cursor-live-run-coordinator.ts

@@ -11,6 +11,7 @@ import type { CursorNativeToolDisplayItem } from "./cursor-native-tool-display.j
 import type { CursorPiBridgeToolRequest, CursorPiToolBridgeRun } from "./cursor-pi-tool-bridge.js";
 import { getCursorSessionScopeKey } from "./cursor-session-scope.js";
 import type { CursorSdkEventDebugRecorder } from "./cursor-sdk-event-debug.js";
+import { installCursorSdkProcessErrorGuard } from "./cursor-sdk-process-error-guard.js";
 
 export class CursorLiveRunAbortError extends Error {
 	constructor() {
@@ -118,6 +119,17 @@ interface LeaseWaiter {
 	onAbort?: () => void;
 }
 
+async function cancelCursorLiveSdkRun(run: CursorLiveRun): Promise<void> {
+	if (!run.sdkRun) return;
+	const guard = installCursorSdkProcessErrorGuard();
+	guard.suppressAbortErrors();
+	try {
+		await run.sdkRun.cancel();
+	} finally {
+		guard.dispose();
+	}
+}
+
 interface CursorLiveRunPrivateState {
 	waiters: Set<ProgressWaiter>;
 	idleDisposeTimer?: ReturnType<typeof setTimeout>;
@@ -474,7 +486,7 @@ export function createCursorLiveRunCoordinator(deps: CursorLiveRunCoordinatorDep
 				if (abandoned) {
 					if (!run.done) {
 						try {
-							await run.sdkRun?.cancel();
+							await cancelCursorLiveSdkRun(run);
 						} catch {
 							// cancellation failure should not block session-agent abandonment
 						}

package/src/cursor-provider-errors.ts

@@ -60,13 +60,15 @@ function getCursorConnectSource(error: unknown, record: Record<string, unknown>
 		const type = getErrorStringField(asRecord(detail), "type");
 		return typeof type === "string" && type.startsWith("aiserver.");
 	});
-	return hasCursorBackendDetails ? "cursor-backend-details" : "generic-connect";
+	if (hasCursorBackendDetails) return "cursor-backend-details";
+	return stack.includes("@connectrpc/connect-node") ? "connect-node-stack" : "generic-connect";
 }
 
 export type CursorConnectErrorSource =
 	| "cursor-sdk-stack"
 	| "cursor-extension-connect-stack"
 	| "cursor-backend-details"
+	| "connect-node-stack"
 	| "generic-connect";
 
 export type CursorConnectErrorClassification =

package/src/cursor-sdk-process-error-guard.ts

@@ -13,7 +13,7 @@ type GenericProcessEmit = (event: string | symbol, ...args: unknown[]) => boolea
 
 // The local Cursor SDK can surface some ConnectRPC failures as process-level
 // uncaught exceptions/unhandled rejections even when run.wait()/run.cancel() is awaited.
-// Keep suppression scoped to active Cursor provider turns and tightly matched SDK shapes.
+// Keep suppression scoped to active Cursor provider turns and tightly matched ConnectRPC shapes.
 const activeProviderTurns = new Set<CursorSdkProcessErrorGuardToken>();
 let originalProcessEmit: GenericProcessEmit | undefined;
 let captureCallbackInstalled = false;
@@ -35,7 +35,9 @@ function shouldSuppressProcessError(event: string | symbol, args: readonly unkno
 	const classification = classifyCursorConnectError(error);
 	if (!classification) return false;
 	if (classification.kind === "abort") return hasActiveAbortSuppression();
-	return activeProviderTurns.size > 0 && isCursorProvenance(classification.source);
+	if (activeProviderTurns.size === 0) return false;
+	if (classification.kind === "network") return isCursorProvenance(classification.source) || classification.source === "connect-node-stack";
+	return isCursorProvenance(classification.source);
 }
 
 function installProcessEmitPatch(): void {

package/docs/crabbox-platform-testing-lessons.md

@@ -1,508 +0,0 @@
-# Crabbox Local Platform Testing Guide for pi Extensions
-
-## Purpose
-
-This is the reusable field guide for adding **local Crabbox platform testing** to pi extension repositories.
-
-Current scope:
-
-- pi extension packages only;
-- local maintainer machine is macOS;
-- required target matrix is macOS, Ubuntu Linux, and native Windows;
-- Windows runs through the local Parallels template `pi-extension-windows-template` and snapshot `crabbox-ready` unless a project documents a different source of truth.
-
-This guide is generic on purpose. Do not copy another project's model IDs, package names, API keys, VM clones, artifact folders, prompts, or release decisions. Copy the architecture and conventions, then make the target project own its config, docs, assertions, and release gate.
-
-Official references:
-
-- [Crabbox docs](https://crabbox.sh/)
-- [openclaw/crabbox](https://github.com/openclaw/crabbox)
-- Crabbox source docs worth reading before changing a harness: `docs/commands/run.md`, `docs/commands/warmup.md`, `docs/commands/stop.md`, `docs/features/doctor.md`, `docs/features/sync.md`, `docs/features/env-forwarding.md`, `docs/providers/ssh.md`, `docs/providers/local-container.md`, and `docs/providers/parallels.md`.
-
-Local reference implementations reviewed for this guide:
-
-- `~/Projects/AI/pi-cursor-sdk` — full provider/runtime gate with live model, visual TUI, JSONL, bridge, usage/cache, and abort-cleanup assertions.
-- `~/Projects/AI/pi-oracle` — package/build platform gate plus project-specific real smoke, with a project-specific env prefix.
-- `~/Projects/AI/pi-codex-goal` — compact reusable harness with platform build plus real pi runtime smoke on all targets.
-
-## Standard local matrix
-
-| Harness target | Crabbox provider | Local purpose | Shell contract | Default work root |
-| --- | --- | --- | --- | --- |
-| `macos` | `ssh` static localhost | Current host macOS | POSIX shell over SSH | `/Users/$USER/crabbox/<project>` |
-| `ubuntu` | `local-container` | Linux smoke without cloud | POSIX shell in a Docker-compatible container | provider default `/work/crabbox` |
-| `windows-native` | `parallels` | Real native Windows behavior | PowerShell/OpenSSH, `--windows-mode normal` | `C:\crabbox\<project>` |
-
-Use this matrix by default for pi extensions. If a project does not need all three targets, that project's docs must say which target is non-required and why. A missing required target is a blocked local setup, not a skipped pass.
-
-## What Crabbox owns vs. what the project owns
-
-Crabbox owns the lease/sync/run loop:
-
-1. lease or claim a target;
-2. sync tracked plus nonignored local files;
-3. run a command remotely;
-4. stream output;
-5. expose timing, logs, failure bundles, and cleanup commands;
-6. stop or expire the lease.
-
-The project owns the test contract:
-
-- which targets and suites are required;
-- target setup and runtime versions;
-- package install semantics;
-- pi commands and prompts;
-- assertions over stdout, JSONL, visual evidence, artifacts, cleanup, and redaction;
-- docs and release criteria.
-
-Do not treat Crabbox as a runtime installer. If a target needs Node, npm, Git, `tar`, `rsync`, `zstd`, `ffmpeg`, a browser renderer, or another reusable tool, put that setup in the target image/template or in a documented project setup step.
-
-## Recommended repository shape
-
-Use names that fit the project, but keep this shape unless the project already has a better source of truth.
-
-```text
-platform-smoke.config.mjs
-scripts/platform-smoke.mjs
-scripts/platform-smoke/doctor.mjs
-scripts/platform-smoke/crabbox-runner.mjs
-scripts/platform-smoke/targets.mjs
-scripts/platform-smoke/artifacts.mjs
-scripts/platform-smoke/platform-build-windows.ps1
-scripts/platform-smoke/<runtime-suite>.mjs        # optional real pi/model smoke
-scripts/platform-smoke/pty-capture.mjs           # optional TUI/PTY suites
-scripts/platform-smoke/render-ansi.mjs           # optional host-side visual renderer
-docs/platform-smoke.md                           # project source of truth
-```
-
-Gitignored local state:
-
-```text
-.artifacts/
-.crabbox/
-.debug/
-.platform-smoke-runs/
-```
-
-Package scripts:
-
-```json
-{
-  "scripts": {
-    "check:platform-smoke": "node --check scripts/platform-smoke.mjs && node --check scripts/platform-smoke/doctor.mjs && node --check scripts/platform-smoke/crabbox-runner.mjs && node --check scripts/platform-smoke/targets.mjs",
-    "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",
-    "smoke:platform:ubuntu": "node scripts/platform-smoke.mjs run --target ubuntu",
-    "smoke:platform:windows-native": "node scripts/platform-smoke.mjs run --target windows-native",
-    "smoke:platform:all": "node scripts/platform-smoke.mjs run --target macos,ubuntu,windows-native"
-  }
-}
-```
-
-Add tests for cheap harness invariants: syntax, help text, target/suite validation, package-file inclusion or exclusion, packed-install command rendering, artifact-manifest failure behavior, cleanup-failure behavior, path traversal rejection, and secret redaction.
-
-## Host Crabbox install
-
-Install the Crabbox CLI on the macOS host and keep the harness explicit about the binary it uses:
-
-```sh
-brew install openclaw/tap/crabbox
-crabbox --version
-crabbox providers
-```
-
-If Homebrew already has the OpenClaw tap configured, `brew install crabbox` may resolve to the same formula. Use `PLATFORM_SMOKE_CRABBOX=/path/to/crabbox` only when testing a non-default binary or a locally built Crabbox.
-
-## Configuration conventions
-
-Keep project-specific defaults in `platform-smoke.config.mjs`:
-
-```js
-export default {
-  packageName: "pi-example-extension",
-  artifactRoot: ".artifacts/platform-smoke",
-  requiredTargets: ["macos", "ubuntu", "windows-native"],
-  requiredSuites: ["platform-build"],
-  requiredCrabbox: { minVersion: "0.24.0" },
-  ubuntuContainerImage: "cimg/node:24.16",
-  nodeValidationMajor: 24,
-};
-```
-
-Use the config as the harness source of truth. Crabbox itself resolves config as `flags > env > repo .crabbox.yaml/crabbox.yaml > user config > defaults`; local smoke harnesses should still pass critical provider/work-root flags explicitly so the gate does not depend on hidden user config.
-
-Environment conventions:
-
-- Prefer defaults derived from `config.packageName` for project-specific work roots and slugs.
-- Do not export project-specific work-root overrides globally.
-- Use `PLATFORM_SMOKE_*` for reusable harness knobs when scripts are shared across projects.
-- Use a project-specific prefix such as `PI_ORACLE_SMOKE_*` only when a repo needs to coexist with another harness or already has established project-specific environment names.
-- Keep auth variable names in config, not auth values.
-
-Useful standard variables:
-
-```text
-PLATFORM_SMOKE_CRABBOX=/opt/homebrew/bin/crabbox
-PLATFORM_SMOKE_MAC_HOST=localhost
-PLATFORM_SMOKE_MAC_USER=$USER
-PLATFORM_SMOKE_MAC_WORK_ROOT=/Users/$USER/crabbox/<project>
-PLATFORM_SMOKE_UBUNTU_IMAGE=cimg/node:24.16
-PLATFORM_SMOKE_WINDOWS_VM=pi-extension-windows-template
-PLATFORM_SMOKE_WINDOWS_SNAPSHOT=crabbox-ready
-PLATFORM_SMOKE_WINDOWS_USER=<windows-ssh-user>
-PLATFORM_SMOKE_WINDOWS_WORK_ROOT=C:\crabbox\<project>
-```
-
-Pin Crabbox deliberately. Exact pins are best for release-critical harnesses whose parsing depends on CLI output. Minimum version checks are fine for simpler gates. Current local baseline is Crabbox `0.24.0` or newer from the Homebrew package.
-
-## Target setup best practices
-
-### macOS: static SSH to the current host
-
-Use the `ssh` provider for current macOS. It is a static provider: Crabbox does not create or clean up the host.
-
-Required setup:
-
-- macOS Remote Login enabled.
-- Noninteractive SSH works: `ssh -o BatchMode=yes $USER@localhost 'whoami'`.
-- Target user has a writable work root such as `/Users/$USER/crabbox/<project>`.
-- `node`, `npm`, `git`, `rsync`, `tar`, and project-specific native tools are on the remote SSH path.
-
-Base args:
-
-```text
---provider ssh
---target macos
---static-host localhost
---static-user $USER
---static-port 22
---static-work-root /Users/$USER/crabbox/<project>
-```
-
-Notes:
-
-- Static `stop` removes Crabbox's local claim only; it does not clean the Mac.
-- Use `--reclaim` intentionally when multiple repos reuse localhost and a previous claim blocks the run.
-- Because this is the real host, avoid tests that mutate global user state unless the project explicitly owns cleanup.
-
-### Ubuntu: local-container provider
-
-Use `local-container` for the Linux target. It runs through Docker Desktop, OrbStack, Colima, or another Docker-compatible runtime on the local machine. There is no broker or cloud dependency.
-
-Required setup:
-
-- `docker info` passes.
-- The chosen image supports the project's Node/npm baseline or can bootstrap quickly.
-- Default image for current pi extension smokes: `cimg/node:24.16`.
-
-Base args:
-
-```text
---provider local-container
---target linux
---local-container-image cimg/node:24.16
-```
-
-Notes:
-
-- Use a prebuilt image when first-start package bootstrapping becomes a bottleneck.
-- Do not mount the host Docker socket unless the suite actually needs nested Docker; that grants the container access to the host daemon.
-- Treat container cache volumes as local mutable state. Name them per project and clean obsolete keys manually.
-
-### Windows: Parallels native Windows template
-
-Use the `parallels` provider for native Windows. The default reusable template is:
-
-```text
-source VM: pi-extension-windows-template
-snapshot:  crabbox-ready
-mode:      windows normal
-```
-
-Base args:
-
-```text
---provider parallels
---target windows
---windows-mode normal
---parallels-source pi-extension-windows-template
---parallels-source-snapshot crabbox-ready
---parallels-user <windows-ssh-user>
---parallels-work-root C:\crabbox\<project>
-```
-
-Template requirements:
-
-- Parallels Tools installed.
-- A stable SSH user.
-- OpenSSH Server enabled and reachable on port `22`.
-- PowerShell available.
-- Git for Windows installed.
-- `tar` available for archive sync.
-- Node/npm at the project validation baseline.
-- Writable `C:\crabbox` work root.
-- The source VM is not used as a normal work machine.
-- `crabbox-ready` is a known-good power-off snapshot. Linked clones depend on that snapshot, so do not delete or replace it casually.
-
-PowerShell rules:
-
-- Use a checked-in `.ps1` script for long Windows suites.
-- Run with `powershell.exe -NoLogo -NoProfile -ExecutionPolicy Bypass -File .\scripts\platform-smoke\platform-build-windows.ps1`.
-- Avoid one giant quoted `--shell` string for Windows unless it is a small probe.
-- If installing Git or tools changes PATH, restart `sshd` or validate in a fresh SSH session.
-
-### Windows template image policy
-
-Agents should reuse `pi-extension-windows-template` instead of creating one-off Windows VMs for each project.
-
-Add a tool to the template when all are true:
-
-- more than one pi extension is likely to need it;
-- installing it every run is slow, flaky, or network-dependent;
-- it is safe to have globally on Windows test machines;
-- it has no project secrets, local user auth, or repo-specific config.
-
-Keep project-specific tools in repo scripts when they are truly one-off.
-
-Template update runbook:
-
-1. Prefer updating `pi-extension-windows-template` over adding per-project/per-run installers when a tool is reusable across pi extensions.
-2. Boot the source VM, not a Crabbox clone.
-3. Install or update the globally useful tool.
-4. Verify from a fresh SSH session: `node --version`, `npm --version`, `git --version`, `tar --version`, and the new tool's `--version` or equivalent.
-5. Remove caches, downloads, auth files, local checkouts, `.pi` state, `.artifacts`, `.debug`, and secrets.
-6. Shut down the VM cleanly.
-7. Create a new known-good power-off snapshot. Prefer a dated snapshot for trial adoption; promote it to `crabbox-ready` only after at least one project passes the Windows smoke.
-8. Update project docs/config if the snapshot name changes.
-9. Stop or clean stale clones after the template update so future runs do not reuse pre-update state.
-
-Never bake API keys, browser sessions, user project checkouts, generated artifacts, or repo-specific `.env` files into the template.
-
-## Doctor is mandatory
-
-`npm run smoke:platform:doctor` should fail before any expensive, token-spending, or long-running suite starts. The release entrypoint should enforce this, either by making `smoke:platform:all` run doctor first or by making the canonical release command run `smoke:platform:doctor && smoke:platform:all`.
-
-Doctor should check:
-
-- Crabbox binary path and version/minimum version.
-- `crabbox providers` includes `ssh`, `local-container`, and `parallels`.
-- `crabbox doctor --provider local-container --json` passes for the configured image.
-- `crabbox doctor --provider ssh --target macos --json` passes or reports a concrete host setup failure.
-- Docker is running for Ubuntu.
-- macOS SSH probe reaches the host and sees Node/npm/Git.
-- `prlctl` exists.
-- The Windows source VM and snapshot exist.
-- The Windows snapshot is forkable/power-off; if the template has no live IP because it is stopped, a disposable Crabbox clone probe is acceptable.
-- Host `node`, `npm`, `git`, `tar`, and any host-side renderer tools exist.
-- Required auth variables for live suites are present, reported as redacted presence only.
-- Artifact root is writable.
-- Repo status is visible.
-- Forbidden files such as `.env`, `.env.*`, local package tarballs, `.artifacts`, `.crabbox`, and `.debug` are not in the package or source archive.
-
-Do not downgrade a missing required target to a warning. A release gate with missing Windows, Docker, SSH, auth, or Crabbox setup is blocked.
-
-## Lease and run strategy
-
-Use target sessions, not one fresh lease per suite.
-
-Recommended shape:
-
-```text
-for each target in parallel:
-  warmup once with slug <project>-<target>
-  run suites serially on that lease
-  stop lease in finally
-```
-
-Targets can run concurrently when the host can handle Docker, localhost SSH, and Parallels together. Suites should stay serial within a target unless the project has proven its ports, sessions, workspaces, and artifacts are isolated.
-
-Use stable slugs:
-
-```text
-<project>-macos
-<project>-ubuntu
-<project>-windows-native
-```
-
-Sync rules:
-
-- Start with `crabbox sync-plan` when first onboarding a repo or when sync is unexpectedly large.
-- Use `.gitignore`, `.crabboxignore`, or Crabbox `sync.exclude` for generated state.
-- Use `--fresh-sync` when a target workspace may be stale or a previous suite mutated the checkout.
-- Use `--no-sync` only after a deliberate shared prep step on the same lease.
-- If a private/local repo cannot use remote Git seeding reliably, set `CRABBOX_SYNC_GIT_SEED=false` in the harness and document why.
-- Do not use `--force-sync-large` unless the large transfer is understood and intentional.
-
-Always record:
-
-```text
-crabbox.stdout.txt
-crabbox.stderr.txt
-crabbox.timing.json
-crabbox.stop.stdout.txt
-crabbox.stop.stderr.txt
-crabbox.stop.exit-code.txt
-```
-
-A `stop` failure is a test result. Preserve the original suite result and add a failing `lease-cleanup` result or mark the owning suite failed.
-
-## pi extension release contract
-
-For pi extensions, the baseline `platform-build` suite should prove package installation, not only source-tree execution.
-
-On every required target:
-
-1. Check Node major version against `nodeValidationMajor`.
-2. Run `npm ci`.
-3. Run the repo's local verification command, usually `npm run verify` or the repo-specific equivalent.
-4. Run `npm pack`.
-5. Create a fresh target-local pi project/workspace.
-6. Run `npm install --no-save <packed tarball>`.
-7. Run `pi install -l ./node_modules/<package>`.
-8. Run `pi list`.
-9. Assert the installed package came from the packed install path.
-10. Assert the release proof did not use `pi -e .` or `pi --extension .`.
-
-`pi -e .` is inner-loop debug only. It is not release proof because it bypasses package contents, `files`, install layout, and publish-time mistakes.
-
-Add a real pi runtime suite when the extension's user contract depends on runtime behavior that unit tests cannot prove. Keep it deterministic:
-
-- install the packed package into a clean project;
-- use a fixed model/provider unless the project config overrides it;
-- forward only named auth env vars;
-- write session JSONL and target-local result files;
-- assert final assistant text, tool calls/results, extension state, and persisted files structurally, not by broad substring scans.
-
-Add visual/TUI suites only when the extension has user-facing terminal UI. The portable visual contract is:
-
-```text
-target captures PTY/ConPTY ANSI
-host renders ANSI through one xterm/Playwright renderer
-host writes HTML + PNG evidence
-assert rendered output, not prompt text
-```
-
-Do not make tmux the cross-platform visual source of truth when native Windows is required. Use PTY on POSIX targets and ConPTY on Windows.
-
-## Artifact contract
-
-Every suite should write a self-contained directory:
-
-```text
-.artifacts/platform-smoke/<run-id>/<target>/<suite>/
-  summary.json
-  artifact-manifest.json
-  target.json
-  suite.json
-  command.txt
-  exit-code.txt
-  crabbox.stdout.txt
-  crabbox.stderr.txt
-  crabbox.timing.json
-  assertions.json
-  failures.md                  # only when assertions fail
-```
-
-Add suite-specific evidence, for example:
-
-```text
-node-version.txt
-npm-ci.stdout.txt
-npm-ci.stderr.txt
-npm-test.stdout.txt
-npm-test.stderr.txt
-packed-tarball.txt
-packed-node-install.stdout.txt
-packed-node-install.stderr.txt
-pi-install.stdout.txt
-pi-install.stderr.txt
-pi-list.stdout.txt
-pi-list.stderr.txt
-session.jsonl
-terminal.ansi
-terminal.html
-terminal.png
-redaction-scan.json
-```
-
-Pass/fail invariant:
-
-```text
-summary.ok === assertions.ok
-artifact-manifest.missing.length === 0 for any passing suite
-missing required artifact => assertion failure + summary.ok=false
-```
-
-Do not rely on Crabbox `--artifact-glob` for this matrix. Crabbox's SSH artifact collector is useful on Linux, but native Windows and macOS targets reject that collector. A portable harness should write host-side artifact files from captured stdout/stderr, explicit target output markers, session paths, or a safe target-produced bundle whose paths are validated before unpacking.
-
-## Secrets and environment forwarding
-
-Crabbox intentionally does not forward your whole environment to the remote target. By default it forwards only narrow built-ins such as `CI` and `NODE_OPTIONS`. Live pi suites must opt in to exactly the variables they need.
-
-Local forwarding of secrets is acceptable for these maintainer-owned smoke gates when the suite needs real provider/model auth. The hard line is persistence and sharing: secrets must never be committed, baked into templates, written to artifacts, printed in docs/PRs, or posted in chat.
-
-Best practices:
-
-- Keep auth values out of docs, configs, shell commands, artifact names, and template images.
-- Store auth variable names in config, e.g. `defaultAuthEnv: ["ZAI_API_KEY"]`.
-- Forward only named auth variables with `--allow-env NAME` or `--env-from-profile <file> --allow-env NAME`.
-- Do not pass API keys as command-line arguments.
-- Preserve normal local process environment such as `PATH`, `HOME`, and tool configuration, but do not dump the full environment into artifacts.
-- Redact stdout, stderr, JSONL, HTML, ANSI, debug files, and failure bundles before committing, publishing, posting, or sharing them.
-- Fail if a redaction scan finds API keys, bearer tokens, cookies, auth headers, or raw `.env` contents in persisted artifacts.
-
-Docs may say `CURSOR_API_KEY=(present, redacted)` or `ZAI_API_KEY=(present, redacted)`. They must never include values.
-
-## Make false green states impossible
-
-The main guardrails:
-
-- `doctor` is required before `all`.
-- Required targets do not skip green.
-- Release proof uses packed install, not `pi -e .`.
-- A suite cannot pass with missing required artifacts.
-- Cleanup failures fail the target result.
-- Visual assertions inspect rendered output, not only prompt text.
-- JSONL assertions inspect specific message fields, not all-file substrings.
-- Auth is forwarded to targets by explicit allowlist only.
-- Secrets can be used locally, but artifacts/docs/comments never expose them.
-- Target-specific assumptions live in `docs/platform-smoke.md`, not in chat.
-
-## Adoption procedure for a new pi extension
-
-1. Identify the package name and pi install path.
-2. Define required targets: default to `macos`, `ubuntu`, and `windows-native`.
-3. Define required suites: always start with `platform-build`; add runtime or visual suites only for real user contracts.
-4. Add `platform-smoke.config.mjs` with package name, targets, suites, Crabbox version, Ubuntu image, and Node baseline.
-5. Add `scripts/platform-smoke.mjs` with `doctor`, per-target, and `all` commands.
-6. Add a thin `crabbox-runner.mjs` that owns target base args, warmup, run, timeout, env allowlist, and stop.
-7. Add target command builders in `targets.mjs`; keep POSIX and PowerShell paths explicit.
-8. Add `platform-build-windows.ps1` for the Windows suite body.
-9. Add `artifacts.mjs` and make missing artifacts fail.
-10. Add `doctor.mjs`; all required local prerequisites fail hard.
-11. Add cheap tests for harness syntax, help, target selection, packed-install command rendering, manifest failure, cleanup failure, and package inclusion/exclusion.
-12. Add `docs/platform-smoke.md` as the project-specific source of truth.
-13. Add a short pointer in `AGENTS.md` and README if the platform gate is release-blocking.
-14. Run `npm run check:platform-smoke`, then `npm run smoke:platform:doctor`, then a single target, then `npm run smoke:platform:all`.
-
-## Project adoption checklist
-
-Before declaring a project integrated, answer these in that project's docs:
-
-1. What package/install path must release prove?
-2. Which OS targets are release-blocking?
-3. What exact Crabbox version or minimum version is supported?
-4. Which Ubuntu image is used?
-5. Which Parallels template and snapshot are used?
-6. What target tools are expected globally, especially on Windows?
-7. What suite proves packed pi install?
-8. What suite, if any, proves real pi runtime behavior?
-9. What visual evidence, if any, is required?
-10. What auth env names are allowed to cross into targets?
-11. What artifacts must exist for a pass?
-12. What redaction scans run before sharing evidence?
-13. How are lease cleanup failures surfaced?
-14. Which docs, package scripts, and tests are the source of truth?
-
-The standard is not "copy every file from pi-cursor-sdk." The standard is: define the platform failure modes that matter for the extension, then make the local Crabbox gate produce durable evidence for them on macOS, Ubuntu, and native Windows without sharing state between repositories.