pi-cursor-sdk 0.1.32 → 0.1.34

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 ## Unreleased
 
+## 0.1.34 - 2026-06-04
+
+### Changed
+
+- Update the local pi validation baseline to `@earendil-works/pi-ai`, `@earendil-works/pi-coding-agent`, and `@earendil-works/pi-tui` `0.78.1` after reviewing the Pi 0.78.1 changelog and extension/provider docs. Pi core peer dependency ranges now follow current pi package guidance with `"*"` ranges, and docs call pi 0.78.1 the recommended validated baseline rather than a hard pin.
+- Gate Cursor native replay tool registration on Pi 0.78.1's precise `ctx.mode === "tui"` instead of treating all dialog-capable UI modes as safe for terminal replay rendering; RPC/JSON/print modes keep bridge/question tools without TUI-only replay wrappers.
+
+### Fixed
+
+- Align `cursor_ask_question` and `cursor_activate_skill` failure paths with Pi's current custom-tool contract by throwing on invalid input, unavailable UI, missing skills, and skill load failures instead of returning successful tool results with ignored `isError` fields.
+
+## 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
 
@@ -31,10 +51,10 @@ If pi started without a key, run `/cursor-refresh-models` after `/login` to refr
 ## Requirements
 
 - Node.js 22.19+
-- pi 0.76.0 or newer
+- pi 0.78.1 or newer recommended; pi core peer metadata is intentionally unpinned so newer pi releases are not blocked
 - a Cursor SDK API key saved through `/login`, available as `CURSOR_API_KEY`, or passed with pi's `--api-key`
 
-No global `@cursor/sdk` install is required. This package depends on exact `@cursor/sdk@1.0.17`, so normal package installation brings in the SDK version this extension was built and tested against. The Cursor SDK currently depends on `sqlite3@^5.1.7`, whose install path can print deprecated transitive `node-gyp@8` dependency warnings such as `inflight`, `rimraf`, `glob`, `npmlog`, `gauge`, `are-we-there-yet`, and `tar@6`. Those warnings are non-fatal and come from the closed-source Cursor SDK dependency boundary; this package cannot force npm overrides into consumer projects. If you install from a root `package.json` you control, you may choose a root-level override such as `"overrides": { "sqlite3": "6.0.1" }`; pi package installs will still follow npm's normal transitive dependency rules. This package declares a pi **minimum** of 0.76.0 with no maximum peer version, so users who update pi before this extension is republished are not blocked from trying the existing extension. The current validation baseline is pi 0.78.0 plus Cursor SDK 1.0.17; older pi or Cursor SDK compatibility paths are not maintained.
+No global `@cursor/sdk` install is required. This package depends on exact `@cursor/sdk@1.0.17`, so normal package installation brings in the SDK version this extension was built and tested against. The Cursor SDK currently depends on `sqlite3@^5.1.7`, whose install path can print deprecated transitive `node-gyp@8` dependency warnings such as `inflight`, `rimraf`, `glob`, `npmlog`, `gauge`, `are-we-there-yet`, and `tar@6`. Those warnings are non-fatal and come from the closed-source Cursor SDK dependency boundary; this package cannot force npm overrides into consumer projects. If you install from a root `package.json` you control, you may choose a root-level override such as `"overrides": { "sqlite3": "6.0.1" }`; pi package installs will still follow npm's normal transitive dependency rules. This package follows pi package guidance by declaring pi core package peers with `"*"` ranges, so users who update pi before this extension is republished are not blocked by peer metadata. The current recommended and validated pi baseline is 0.78.1 plus Cursor SDK 1.0.17; older pi compatibility paths are best-effort and older Cursor SDK compatibility paths are not maintained.
 
 ## Install
 

package/docs/cursor-live-smoke-checklist.md

@@ -67,8 +67,8 @@ The replay scan flags only error `toolResult` / error assistant messages with `T
 
 Pass criteria:
 
-- `pi --version` reports pi 0.78.0 for this cutover baseline.
-- `npm ls` shows `@cursor/sdk@1.0.17` and local `@earendil-works/*@0.78.0` packages.
+- `pi --version` reports pi 0.78.1 for this cutover baseline.
+- `npm ls` shows `@cursor/sdk@1.0.17` and local `@earendil-works/*@0.78.1` packages.
 - `cursor/composer-2-5` appears in the model list.
 - No Cursor key or auth token is printed.
 - If neither `~/.pi/agent/auth.json` cursor auth nor `CURSOR_API_KEY` is available, stop and report the live smoke as blocked.
@@ -125,7 +125,7 @@ Observe with `tmux capture-pane -pt "$SESSION"` or attach manually.
 Pass criteria:
 
 - Footer shows `(cursor) composer-2-5`. With `--cursor-no-fast`, Cursor fast mode is off and the Cursor extension status should not show `cursor fast`; ignore unrelated status text from other extensions.
-- The run uses pi 0.78.0 `--session-id` successfully.
+- The run uses pi 0.78.1 `--session-id` successfully.
 - Assistant answer appears correctly.
 - `/session` shows one user and one assistant message for the simple run.
 - Persisted JSONL has one assistant message. If the screen appears duplicated, inspect JSONL before deciding whether it is a rendering bug.
@@ -133,7 +133,7 @@ Pass criteria:
 
 ## 4. Focused visual card/color rendering check
 
-This is the canonical inner-loop visual debug path for Cursor provider/runtime changes. It requires offscreen TUI visual inspection, not only JSONL or code review. Use pi 0.78.0, `@cursor/sdk@1.0.17`, a fresh temporary session dir, Cursor SDK `plan` mode, native replay enabled, and the checked-in visual runner. The runner resolves `pi` by directly walking the parent `PATH`, uses `process.execPath` for Node, and prepends that Node directory for both prereq checks and tmux launches so `#!/usr/bin/env node` shims use the validated Node. The default matrix is native replay only: native replay registration is forced on, settings sources are `none`, the pi bridge is off, overlapping built-in pi tools are not exposed, and inherited Cursor SDK event-debug artifact env is cleared. With `--event-debug`, debug capture writes to a deterministic directory under `VISUAL_DIR`.
+This is the canonical inner-loop visual debug path for Cursor provider/runtime changes. It requires offscreen TUI visual inspection, not only JSONL or code review. Use pi 0.78.1, `@cursor/sdk@1.0.17`, a fresh temporary session dir, Cursor SDK `plan` mode, native replay enabled, and the checked-in visual runner. The runner resolves `pi` by directly walking the parent `PATH`, uses `process.execPath` for Node, and prepends that Node directory for both prereq checks and tmux launches so `#!/usr/bin/env node` shims use the validated Node. The default matrix is native replay only: native replay registration is forced on, settings sources are `none`, the pi bridge is off, overlapping built-in pi tools are not exposed, and inherited Cursor SDK event-debug artifact env is cleared. With `--event-debug`, debug capture writes to a deterministic directory under `VISUAL_DIR`.
 
 ```bash
 VISUAL_DIR="$(mktemp -d /tmp/pi-cursor-sdk-1016-visual.XXXXXX)"

package/docs/cursor-model-ux-spec.md

@@ -15,7 +15,7 @@ Current implementation notes:
 - Cursor status uses one coordinated `ctx.ui.setStatus("cursor", ...)` value for fast and non-default plan mode; the default pi footer remains intact.
 - Installed `@cursor/sdk` user messages accept images, and Cursor models are treated as image-capable; registered input metadata is `text` plus `image`.
 - Image payload forwarding sends images only from the latest user message. If the latest user turn is plain text after an earlier image turn, the transcript keeps an `[image omitted from transcript]` placeholder but no image bytes are sent to Cursor. The prompt explicitly tells Cursor that prior image bytes are unavailable and to ask the user to reattach or describe a prior image when needed. Carrying images forward across turns remains a future product decision because it affects token cost, privacy, stale visual context, and expected multimodal follow-up behavior.
-- Exact `@cursor/sdk@1.0.17` is a package dependency of this extension; users should not need a global SDK install. pi 0.78.0 is the current validation baseline, while published pi peer dependencies are minimum-only `>=0.76.0` ranges with no upper bound. Newer pi versions are allowed to attempt loading this extension before a matching extension release exists; compatibility is best-effort until validated.
+- Exact `@cursor/sdk@1.0.17` is a package dependency of this extension; users should not need a global SDK install. pi 0.78.1 is the current recommended validation baseline, while published pi core peer dependencies use `"*"` ranges per current pi package guidance. Newer pi versions are allowed to attempt loading this extension before a matching extension release exists; compatibility is best-effort until validated.
 - Cursor auth uses pi-native API-key resolution for provider `cursor`: CLI `--api-key`, stored `~/.pi/agent/auth.json` API key from `/login`, then `CURSOR_API_KEY`. The extension config file stores only non-secret Cursor-only state such as fast defaults.
 - Local agents pass `settingSources: ["all"]` by default so Cursor MCP servers, plugin tools, project/user settings, and related Cursor-native capabilities are available. Users can narrow loading with a comma-separated list such as `PI_CURSOR_SETTING_SOURCES=project,user,plugins`, or disable ambient setting sources with `PI_CURSOR_SETTING_SOURCES=none`. The provider suppresses direct Cursor SDK bootstrap stdout/stderr/console noise (including late first-send workspace loading such as hook compatibility warnings) so it does not pollute pi's TUI.
 - On `cursor/*` models, pi-cursor-sdk removes only pi-generated `<project_instructions>` blocks that overlap the effective Cursor `settingSources`: `user` for `~/.pi/agent/AGENTS.md`; `project` for discovered repo/parent `AGENTS.md` and `CLAUDE.md` (verified Cursor behavior: local agents load project `AGENTS.md` and `CLAUDE.md`). `~/.pi/agent/CLAUDE.md` is not removed (Cursor user layer uses `~/.claude/CLAUDE.md`). Blocks are removed by exact pi serialization match from structured `contextFiles` via the `before_agent_start` hook, not in `buildCursorPrompt` sanitization. Suppression is skipped with `-nc`, `PI_CURSOR_SETTING_SOURCES=none`, narrowed sources such as `plugins` that omit the matching layer, or `PI_CURSOR_PRESERVE_PI_AGENTS_MD=1`. Switching away from a Cursor model restores pi's full context block on the next user message.

package/docs/cursor-native-tool-visual-audit.md

@@ -6,16 +6,16 @@ This workflow is the canonical repo path for verifying Cursor SDK tool replay th
 
 Use it before accepting replay-card commits or PRs, and for every Cursor provider/runtime release where TUI card/color behavior could regress. Text logs and JSONL are necessary, but they are not enough when the claim is visual parity: always keep PNGs for the exact prompt, and keep before/after PNGs when reviewing a rendering change.
 
-Current validation baseline: pi 0.78.0, exact `@cursor/sdk@1.0.17`, local validation packages `@earendil-works/pi-ai`, `@earendil-works/pi-coding-agent`, and `@earendil-works/pi-tui` at 0.78.0. Published peer dependencies remain minimum-only at pi 0.76.0+ with no upper bound, so newer pi installs can try the extension before a matching validation release exists.
+Current validation baseline: pi 0.78.1, exact `@cursor/sdk@1.0.17`, local validation packages `@earendil-works/pi-ai`, `@earendil-works/pi-coding-agent`, and `@earendil-works/pi-tui` at 0.78.1. Published pi core peer dependencies use `"*"` ranges per current pi package guidance, so newer pi installs can try the extension before a matching validation release exists.
 
-## Cursor SDK 1.0.17 / pi 0.78.0 cutover visual record
+## Cursor SDK 1.0.17 / pi 0.78.1 cutover visual record
 
 Record the required cutover validation here or in the final release handoff. The default matrix is native replay only: the runner forces native replay registration on, forces Cursor setting sources off, disables the pi bridge, disables overlapping built-in pi tool exposure, and clears inherited Cursor SDK event-debug artifact env. With `--event-debug`, debug capture writes to a deterministic directory under the visual output directory. Do not commit raw ANSI logs, screenshots, terminal recordings, debug artifacts, or `.debug/visual-smoke` scratch files.
 
 | Field | Required value / evidence |
 | --- | --- |
 | Command/session used | `npm run smoke:visual -- --ext "$PWD" --cwd "$PWD" --mode plan --out-dir <fresh /tmp dir> --label <matrix label> --prompt <matrix prompt>` with default native-replay isolation |
-| Baseline versions | `pi --version` = 0.78.0; `npm ls` = `@cursor/sdk@1.0.17` and local `@earendil-works/*@0.78.0` |
+| Baseline versions | `pi --version` = 0.78.1; `npm ls` = `@cursor/sdk@1.0.17` and local `@earendil-works/*@0.78.1` |
 | Card categories checked | Claim only categories proven by both PNG and JSONL. Required cutover categories are read, grep/search, find/glob, shell success, write, edit/diff, and true read failure. Direct `ls`/list is tracked as excluded from the current one-prompt platform matrix because composer-2-5 does not route it through native `ls` reliably; source-enumeration coverage is gated through find/glob. Neutral Cursor plan/todo/task/mode activity is optional/opportunistic and only counts when JSONL contains a completed Cursor workflow event. |
 | Observed status/card colors | Confirm native-looking cards use native pi styling; neutral Cursor activity is not red; true errors are distinct; diff previews show red/green; plan status is readable |
 | Screenshot/ANSI evidence location | External path only, for example `/tmp/pi-cursor-sdk-1016-visual.*/read-package.{ansi,txt,html,png,jsonl.path}` |

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
 
@@ -243,7 +243,7 @@ The script writes timestamped artifacts under `--out` (default `/tmp/pi-cursor-s
 
 Stdout prints artifact paths and summary counts only. Raw payloads stay on disk and may contain local paths, project text, tool args/results, or secrets — do not commit or share them.
 
-Hard repo rule: Cursor SDK behavior claims must come from the installed `@cursor/sdk` package and/or https://cursor.com/docs/sdk/typescript, not from memory or ad-hoc probes alone. Current cutover validation targets exact `@cursor/sdk@1.0.17` and pi 0.78.0 local packages.
+Hard repo rule: Cursor SDK behavior claims must come from the installed `@cursor/sdk` package and/or https://cursor.com/docs/sdk/typescript, not from memory or ad-hoc probes alone. Current cutover validation targets exact `@cursor/sdk@1.0.17` and pi 0.78.1 local packages.
 
 ## Pi provider SDK event capture
 

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.34",
 	"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",
@@ -111,15 +110,15 @@
 		"@modelcontextprotocol/sdk": "^1.29.0"
 	},
 	"peerDependencies": {
-		"@earendil-works/pi-ai": ">=0.76.0",
-		"@earendil-works/pi-coding-agent": ">=0.76.0",
-		"@earendil-works/pi-tui": ">=0.76.0",
+		"@earendil-works/pi-ai": "*",
+		"@earendil-works/pi-coding-agent": "*",
+		"@earendil-works/pi-tui": "*",
 		"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",
 		"@xterm/xterm": "^6.0.0",
 		"node-pty": "^1.1.0",
 		"playwright": "^1.60.0",

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'));