pi-cursor-sdk 0.4.0 → 0.5.0

package/docs/platform-smoke-implementation.md

@@ -1,6 +1,6 @@
 # Platform Smoke Implementation Reference
 
-Back to the canonical [Platform Smoke Gate runbook](./platform-smoke.md) for release commands, required targets and suites, artifacts, assertions, security, and the release bar.
+Back to the canonical [Platform Smoke runbook](./platform-smoke.md) for cost-conscious verification, focused suite selection, optional comprehensive targets/suites, artifacts, assertions, security, and the release bar. Offline/faux checks and exact-input retained evidence come first; only necessary changed-behavior proof warrants the smallest live check on one representative environment. No paid Cloud testing for generic PRs/releases; only explicitly Cursor Cloud-focused PRs/issues may select a necessary focused Cloud check. Automated Cursor PR reviews continue unchanged.
 
 This document records detailed detector, registry, command-rendering, implementation-history, replacement, and portability material. The phase plan is retained as implementation history, not as active release instructions.
 
@@ -18,13 +18,15 @@ Required behavior:
 - fail when a card/evidence item has the wrong success/error state;
 - fail when footer/status is missing or unreadable.
 
-The plain-text card inventory uses Node's `stripVTControlCharacters` on the complete captured ANSI stream. OSC-8 hyperlinks may use either BEL or ST (ESC followed by a backslash) terminators, and a PTY chunk may split either sequence. Do not strip chunks independently or use a greedy OSC regex: that can consume the visible `package.json` label, successful read content, or subsequent cards even when xterm renders them correctly. Raw ANSI remains unchanged for independent xterm/PNG rendering and secret scanning; exact card patterns and JSONL success/error assertions still apply. `test/fixtures/platform-read-hyperlinks.json` retains minimal native/bridge headers from real captures with only the local hyperlink target anonymized.
+The legacy card inventory and required-card assertions use the same rendered xterm buffer lines already collected for visual evidence and screenshots. Raw ANSI stripping cannot reconstruct cursor movement, line erasure, or redraws; `terminal.txt` remains raw diagnostic text, not card evidence. Raw ANSI remains unchanged for xterm/PNG rendering and secret scanning; exact card patterns, wrapped-line matching, and JSONL success/error assertions still apply. `test/fixtures/platform-read-hyperlinks.json` retains minimal native/bridge OSC-8 headers from real captures with only the local hyperlink target anonymized.
+
+Run the host renderer regression with `node --test test/platform-smoke-rendered-cards.test.mjs`. It requires the host Playwright Chromium checked by platform doctor and fails, rather than skips, if rendering is unavailable. Default `npm test` does not require a guest/CI browser install; the full platform gate still requires doctor and live rendered-card evidence.
 
 Meaningful gap closed: earlier card assertions could pass when the prompt mentioned `pi__read` or a missing-file path even if the actual tool card/result never rendered. The gate now requires JSONL result evidence and per-evidence rendered screenshots for native read, native shell success/failure, native edit diffs, bridge read success/failure, and bridge shell success.
 
 ## Registry visual classification
 
-The implementation must classify every `CURSOR_TOOL_PRESENTATION_SPECS` entry from `src/cursor-tool-presentation-registry.ts` as required or excluded for the release visual gate. A validation check fails when a registry entry lacks classification.
+The implementation must classify every `CURSOR_TOOL_PRESENTATION_SPECS` entry from `src/cursor-tool-presentation-registry.ts` as required or excluded for the optional comprehensive visual matrix. A validation check fails when a registry entry lacks classification.
 
 Required deterministic cards:
 
@@ -176,8 +178,10 @@ Update:
 
 They must state:
 
-- required local release gate is `npm run smoke:platform:all`;
-- cloud-runtime changes additionally require `npm run smoke:cloud`;
+- offline/faux checks and exact-input retained proof come first; new live proof is limited to the smallest meaningful changed-behavior check on one representative environment;
+- `npm run smoke:platform:all` is an optional comprehensive matrix, not an unconditional commit/release gate;
+- no paid Cloud testing for generic PRs/releases; only explicitly Cursor Cloud-focused PRs/issues may select necessary focused Cloud proof, with unchanged run/evidence and cleanup contracts;
+- no full paid campaign replay, matrix-only host coverage, or automatic paid retries; automated Cursor PR reviews continue unchanged;
 - legacy smoke scripts are inner-loop/debug helpers;
 - `tmux` visual smoke is not the canonical cross-platform gate.
 
@@ -195,7 +199,7 @@ Replace or redesign this platform runner if any of these become true:
 - The full gate exceeds the fixed Cursor invocation budget.
 - Node 24 + `node-pty` cannot be made reliable on Windows native.
 
-If the gate is replaced, document the new cross-platform release process before removing this one. Existing local smoke scripts remain inner-loop/debug helpers, not release gates.
+If the runner is replaced, document the new verification process before removing it. Keep offline cross-platform contracts and selected-suite evidence fidelity; the comprehensive paid matrix is optional, not a default ship step.
 
 ## Portability to other pi extensions
 

package/docs/platform-smoke.md

@@ -1,6 +1,6 @@
-# Platform Smoke Gate
+# Platform Smoke
 
-Status: current local-runtime release gate for Cursor provider/runtime changes. Cloud-runtime changes also require the separate paid `npm run smoke:cloud` gate. The Crabbox runner, packed-install platform-build suite, and real live PTY/ConPTY suite runner are implemented for macOS, Ubuntu, and Windows native targets with one-lease-per-target orchestration.
+Status: optional comprehensive local-runtime matrix plus focused changed-behavior checks. Offline/faux verification and exact-input retained-evidence reuse come first. Paid checks are only the smallest meaningful proof needed for changed behavior on one representative environment; docs/metadata-only changes need none. No full paid campaign replay, matrix-only host coverage, or automatic paid retries. No paid Cloud testing for generic PRs/releases; only PRs/issues explicitly focused on Cursor Cloud may select a necessary focused Cloud check. Automated Cursor PR reviews continue unchanged. The Crabbox runner, packed-install platform-build suite, and real live PTY/ConPTY suite runner are implemented for macOS, Ubuntu, and Windows native targets with one-lease-per-target orchestration.
 
 Detailed detector, registry, command-rendering, implementation-history, replacement, and portability reference: [Platform Smoke Implementation Reference](./platform-smoke-implementation.md).
 
@@ -12,48 +12,47 @@ Crabbox best-practice baseline applied from `~/Projects/crabbox`: Crabbox owns l
 
 ## Decision
 
-Crabbox is the required local platform smoke runner for `pi-cursor-sdk` releases that touch Cursor provider/runtime behavior. PRs that touch actual cloud runtime execution must also run `npm run smoke:cloud`.
+Keep offline cross-platform CI, build/type/package checks, and native/faux contracts. Reuse retained proof when its tested inputs are unchanged. If changed behavior needs new real-service proof, choose the smallest existing check and one representative environment. Source-file touch alone does not require a live run.
 
-Inner-loop checks remain useful, but they are not release gates:
+Offline checks:
 
 ```bash
 npm run verify
 npm pack --dry-run
 ```
 
-The required local release gate is exactly:
+Example focused live selection for changed restart behavior (choose the relevant suite/target, not this example by default):
 
 ```bash
-npm run smoke:platform:all
+node scripts/platform-smoke.mjs run --target macos --suite cursor-local-resume-restart
 ```
 
-Cloud-runtime changes additionally require:
+Optional comprehensive coverage, not an unconditional commit/release gate:
 
 ```bash
-npm run smoke:cloud
+npm run smoke:platform:all
 ```
 
-`smoke:platform:all` runs `smoke:platform:doctor` first and only starts the target matrix after doctor passes. Maintainers may still run `npm run smoke:platform:doctor` by itself for setup diagnosis.
-
+That command runs doctor first, then all configured targets/suites. The CLI can run one existing suite on one target without running the full matrix. Doctor itself makes no Cursor calls but checks the comprehensive setup; it is not proof of a provider turn. Per-target commands without `--suite` run every configured suite on that target, so prefer explicit suite selection.
 
-Per-target commands exist for diagnosis and iteration. They are not additional release-gate commands because requiring each per-target command plus `all` doubles Cursor token use.
+Only a PR/issue explicitly focused on Cursor Cloud permits necessary paid Cloud testing; generic PRs/releases and incidental Cloud changes do not. Even for Cloud-focused work, `npm run smoke:cloud` is an optional multi-lane matrix, not mandatory. Select coverage only when its live proof is needed, retaining the selected check's full assertions and cleanup contract.
 
-No partial adoption exists. The release evidence must include macOS, Ubuntu, and Windows native passing through `smoke:platform:all`.
+Do not repeat successful unchanged lanes or automatically retry paid failures. Preserve raw failed evidence, diagnose offline, and choose another call only when necessary. Report selected scope honestly; optional unrun hosts/lanes do not block landing, and focused evidence is not full-matrix proof.
 
 ## Non-negotiable constraints
 
 - No GitHub Actions dependency.
-- No cloud provider dependency in the default local platform gate; cloud-runtime changes use the separate paid cloud gate.
+- No paid Cloud testing for generic PRs/releases. Explicitly Cursor Cloud-focused PRs/issues are the only testing exception; keep Cloud checks separate from local checks.
 - No Crabbox broker/coordinator dependency.
-- No release gate that runs on only one operating system.
-- No release gate that proves command behavior but not TUI visual behavior.
-- No platform release gate based on `pi -e .`.
-- No skipped target because setup is missing; missing setup is a doctor failure.
+- Keep offline cross-platform coverage; do not require a paid host matrix merely for matrix coverage.
+- Visual claims require rendered evidence, not command success alone.
+- Packed-install claims require packed-install evidence; direct `pi -e .` proof has a narrower scope.
+- Missing setup fails a selected check; optional unselected targets are not failed release prerequisites.
 - No one-prompt-per-card visual matrix.
 - No `tmux` as the canonical visual test contract.
 - No target passes from stdout alone when JSONL or visual proof is required.
 - No target loses artifacts on failure.
-- No hidden optional evidence. Every required artifact is produced or the suite fails.
+- Every selected suite retains its required artifacts and assertions or fails. Do not weaken a check to reduce cost.
 
 ## Required Crabbox baseline
 
@@ -67,7 +66,7 @@ version: 0.26.0 or newer
 binary: Homebrew `crabbox` on PATH (`/opt/homebrew/bin/crabbox` on Apple Silicon Homebrew installs)
 ```
 
-Use the Homebrew Crabbox binary on PATH for normal release gates. `PLATFORM_SMOKE_CRABBOX=/path/to/crabbox` is only an explicit override for testing a non-default binary. `smoke:platform:doctor` verifies the configured binary and fails when it is older than the configured minimum version.
+Use the Homebrew Crabbox binary on PATH for selected platform checks. `PLATFORM_SMOKE_CRABBOX=/path/to/crabbox` is only an explicit override for testing a non-default binary. `smoke:platform:doctor` verifies the configured binary and fails when it is older than the configured minimum version.
 
 Required Crabbox providers:
 
@@ -106,7 +105,7 @@ Rendering is host-side. Targets capture the real ANSI stream; the macOS host ren
 
 ## Target session model
 
-Each target opens one Crabbox target session, syncs once, runs all suites for that target under one coherent target run id, collects artifacts, and stops/releases the target. The release-gate entrypoint runs required targets sequentially to prevent shared host, VM/container, and Cursor API contention; each target runs its own suites in order and fails fast within that target. Platform smoke disables Crabbox git-seed sync (`CRABBOX_SYNC_GIT_SEED=false`) so every run tests the current local checkout and uncommitted smoke-runner changes rather than a remote Git seed.
+Each selected target opens one Crabbox session, syncs once, runs selected suites under one coherent run id, collects artifacts, and stops/releases the target. The comprehensive entrypoint runs configured targets sequentially to prevent shared host, VM/container, and Cursor API contention; each target runs its own suites in order and fails fast within that target. Platform smoke disables Crabbox git-seed sync (`CRABBOX_SYNC_GIT_SEED=false`) so every run tests the current local checkout and uncommitted smoke-runner changes rather than a remote Git seed.
 
 ```text
 start target session
@@ -135,7 +134,7 @@ start target session
 end target session
 ```
 
-The target session fails fast. The release-gate path handles one target at a time: it warms one Crabbox lease, performs one fresh sync, runs suites in order, and stops that target after the first failure before starting the next target. Total wall time is therefore additive across required targets; this avoids nondeterministic worker loss and live-run stalls from competing VM/container load and concurrent Cursor API calls. Per-suite commands remain available for diagnosis, but they are intentionally not the normal release path because repeated warmup/sync/install cycles make releases too slow.
+The target session fails fast. The comprehensive path handles one target at a time: it warms one lease, syncs once, runs suites in order, and stops the target after its first failure before starting the next. This avoids competing VM/container load and Cursor calls. Routine verification should instead select the smallest meaningful changed-behavior suite on one representative target; do not replay the full campaign or duplicate a focused run with the full matrix.
 
 Runtime budget is part of the contract:
 
@@ -146,7 +145,7 @@ Runtime budget is part of the contract:
 - Visual coverage is batched into one native prompt, one focused HTTP/1.1 transport prompt, one bridge prompt, and one abort/cleanup prompt per target. Do not split the card matrices into one prompt per card.
 - The gate is fail-fast by target to avoid burning Cursor calls after a platform has already failed.
 
-## Required targets
+## Comprehensive matrix targets
 
 | Target | Crabbox provider | Execution contract | TUI visual contract |
 | --- | --- | --- | --- |
@@ -156,15 +155,15 @@ Runtime budget is part of the contract:
 
 Ubuntu is covered as its own local-container target, and Windows native remains a full visual TUI target.
 
-## Required cloud smoke gate
+## Explicit Cursor Cloud-focused testing exception
 
-Cloud validation stays separate from `smoke:platform:all`. Releases that touch actual cloud execution must run both the local platform gate and:
+No paid Cloud testing for generic PRs or releases. Only a PR or issue explicitly focused on Cursor Cloud may select necessary paid Cloud proof, after offline/faux checks and retained-evidence reuse. Incidental Cloud code changes do not qualify. The no-flag multi-lane command remains callable but is not mandatory even for Cloud-focused work:
 
 ```bash
 npm run smoke:cloud
 ```
 
-The no-flag command is the required `cursor/grok-4.6` matrix. It uses current `gh` CLI authentication to create one private throwaway GitHub repository, seeds clean `main`, `starting-ref`, and `direct-push` branches, and runs persisted-session named lanes for:
+This optional `cursor/grok-4.6` matrix retains its complete run/evidence and cleanup contract. It uses current `gh` CLI authentication to create one private throwaway GitHub repository, seeds clean `main`, `starting-ref`, and `direct-push` branches, and runs persisted-session named lanes for:
 
 - cancellation, with exact agent/run IDs captured before abort, retained `runIdSource` (`metadata` or installed-SDK `Agent.listRuns()` recovery), and terminal `cancelled` independently read through the SDK;
 - explicit HTTPS repository plus `startingRef`, requiring a distinct pushed cloud branch with remote-content and starting-ref-ancestry proof, recording whether the SDK returned branch metadata, and validating any returned PR URL through GitHub;
@@ -179,13 +178,13 @@ Every path harvests exact IDs from provider metadata and canonical lifecycle ses
 
 Before removing successful raw artifacts, the gate atomically replaces `docs/evidence/cursor-cloud-smoke-matrix-latest.json` with a known-shape summary containing timestamp, model, lane observations, exact agent/run IDs, agent cleanup proof, repository cleanup proof, and retained evidence provenance. Provenance records the extension package version, installed `@cursor/sdk` version, git source revision, and a deterministic `packageSourceSha256` over the full published package surface from `package.json` `files` plus `package.json` itself (relative path + bytes; directories expanded; symlinks/non-regular paths rejected). Generated `docs/evidence/*` is outside that published surface and is not hashed. Because successful pre-commit checkouts may be uncommitted, the package-source hash is authoritative for code identity and the revision is baseline identity only. The summary is a runtime-validated known shape (explicit six-lane allowlist, complete lane-agent cleanup coverage, repository proof, provenance) that round-trips through the persisted-evidence validator with no prompts or raw output, and must pass canonical secret scrubbing plus forbidden-field scanning; a run or cleanup failure observed before the atomic rename commit point never overwrites the last successful summary. A signal first dispatched after that point can fail the process while retaining the newly committed completed-cleanup summary, as defined above. Offline release-gate resource coordination (run → harvest IDs → cleanup agents → cleanup repo → evidence only on complete success) lives in `coordinateCloudSmokeReleaseGate()` inside `scripts/lib/cloud-smoke-cleanup-evidence.mjs`. GitHub throwaway fixture ownership lives in `scripts/lib/cloud-smoke-github.mjs`, signal-safe child shutdown lives in `scripts/lib/cloud-smoke-shutdown.mjs`, and `scripts/cloud-runtime-smoke.mjs` keeps concrete lane logic.
 
-`npm run smoke:cloud:context` (`--context-matrix`) remains optional, separate proof for fresh-versus-bootstrap context handoff. `fresh` must answer `NO_MARKER`; `bootstrap` must recall the marker. Its agents receive the same archive, delete, `Agent.get` not-found/404, and archived-inclusive list-exclusion verification, but it does not create a GitHub repository or replace the required-matrix evidence summary.
+Only within the explicitly Cursor Cloud-focused exception, `npm run smoke:cloud:context` (`--context-matrix`) remains optional, separate proof for fresh-versus-bootstrap context handoff. `fresh` must answer `NO_MARKER`; `bootstrap` must recall the marker. Its agents receive the same archive, delete, `Agent.get` not-found/404, and archived-inclusive list-exclusion verification, but it does not create a GitHub repository or replace the required-matrix evidence summary.
 
-This cloud gate does not replace the local macOS/Ubuntu/Windows `smoke:platform:all` gate.
+Cloud product capabilities and offline contracts remain supported. Neither this Cloud matrix nor the comprehensive local matrix is an unconditional ship requirement.
 
 ## Focused local resume smoke
 
-The platform matrix includes the required local-resume lanes: restart, safety, tool-surface, abort, tree, copy/switch, fallback, compaction, default/opt-out proof, and recorded-ID-only cleanup. Platform lanes run those scripts against the target's shared packed package path, then copy each lane's session JSONL, Cursor SDK debug metadata, runtime-launch record, and other bounded smoke artifacts into its canonical platform suite directory. The same scripts still load the source checkout by default when run directly as focused host-local inner-loop checks. Windows uses the intentionally short target-side evidence component `lr` so the Cursor SDK's derived SQLite path remains below legacy `MAX_PATH`; every suite removes and verifies that directory before use, failing closed on stale or locked evidence.
+The optional comprehensive platform matrix includes these local-resume lanes: restart, safety, tool-surface, abort, tree, copy/switch, fallback, compaction, default/opt-out proof, and recorded-ID-only cleanup. Platform lanes run those scripts against the target's shared packed package path, then copy each lane's session JSONL, Cursor SDK debug metadata, runtime-launch record, and other bounded smoke artifacts into its canonical platform suite directory. The same scripts still load the source checkout by default when run directly as focused host-local inner-loop checks. Windows uses the intentionally short target-side evidence component `lr` so the Cursor SDK's derived SQLite path remains below legacy `MAX_PATH`; every suite removes and verifies that directory before use, failing closed on stale or locked evidence.
 
 The smoke starts one sessionful local Cursor run with local resume enabled by default, records the SDK agent id from provider debug metadata, restarts pi against the same session, asks for the remembered marker, and verifies:
 
@@ -319,7 +318,7 @@ export default {
 };
 ```
 
-`ubuntuContainerBaseImage` is `cimg/node:24.21`, the Ubuntu 24.04 Node 24 base with the current glibc baseline for native test dependencies. The runner builds the local `ubuntuContainerImage` wrapper with only `USER root` changed before warmup because Crabbox 0.36.0 must install SSH/Git/rsync/curl during bootstrap and `cimg/node` defaults to an unprivileged user. An explicit `PLATFORM_SMOKE_UBUNTU_IMAGE` bypasses that build and must already support Crabbox bootstrap. Package 0.4.0 requires Node 24+, and this gate validates Node 24 on macOS, Ubuntu, and Windows.
+`ubuntuContainerBaseImage` is `cimg/node:24.21`, the Ubuntu 24.04 Node 24 base with the current glibc baseline for native test dependencies. The runner builds the local `ubuntuContainerImage` wrapper with only `USER root` changed before warmup because Crabbox 0.36.0 must install SSH/Git/rsync/curl during bootstrap and `cimg/node` defaults to an unprivileged user. An explicit `PLATFORM_SMOKE_UBUNTU_IMAGE` bypasses that build and must already support Crabbox bootstrap. The package requires Node 24+, and this gate validates Node 24 on macOS, Ubuntu, and Windows.
 
 `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.
 
@@ -524,7 +523,7 @@ Cursor calls: `2`.
 
 Purpose:
 
-- prove guarded local resume default-on behavior across a pi process restart on each required OS;
+- prove guarded local resume default-on behavior across a pi process restart on each selected OS;
 - assert the first turn creates a local `agent-*` and the second turn resumes the same `agent-*`;
 - force local runtime and clear cloud env knobs so ambient cloud settings cannot satisfy this suite.
 
@@ -637,9 +636,9 @@ PI_CURSOR_SDK_EVENT_DEBUG=1
 
 Purpose:
 
-- prove the packed extension completes a real local provider turn through the SDK's opt-in HTTP/1.1/SSE transport on every required OS;
+- prove the packed extension completes a real local provider turn through the SDK's opt-in HTTP/1.1/SSE transport on each selected OS;
 - prove the final TUI status visibly includes `cursor:local ... http1`;
-- keep the default transport covered by the other required live suites.
+- use offline contracts or valid retained default-transport evidence rather than adding unrelated live runs.
 
 Required final marker: `HTTP1_LIVE_OK`.
 
@@ -796,9 +795,9 @@ cursor-local-resume-cleanup: 4
 
 Maximum per target: `37` Cursor invocations.
 
-Maximum full gate: `111` Cursor invocations.
+Declared maximum full matrix: `111` Cursor invocations (`37` per target across three targets). These are scenario budgets, not measured fixed billable model-call or SDK-step counts; actual service usage can differ.
 
-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 the scenario source of truth (`scripts/platform-smoke/scenarios.mjs`, plus `scripts/platform-smoke/local-resume-suites.mjs` for local-resume lanes).
+`npm run smoke:platform:all` is optional comprehensive coverage; it runs doctor first and then the matrix within these declared budgets. Routine verification selects only necessary changed-behavior proof on one representative environment. No suite adds a new Cursor invocation without updating this plan and the scenario source of truth (`scripts/platform-smoke/scenarios.mjs`, plus `scripts/platform-smoke/local-resume-suites.mjs` for local-resume lanes).
 
 ## Artifact contract
 
@@ -982,16 +981,6 @@ Bridge diagnostics may include safe tool names and correlation IDs only.
 
 ## Release bar
 
-A local provider/runtime release is ready only after this exact command passes on the maintainer machine:
-
-```bash
-npm run smoke:platform:all
-```
-
-Cloud-runtime releases additionally require:
-
-```bash
-npm run smoke:cloud
-```
+Complete offline/faux verification and reuse valid exact-input retained proof. If changed behavior still needs real-service evidence, run the smallest meaningful existing check on one representative environment. Keep its assertions, visual proof when relevant, persisted session/debug evidence, and cleanup intact. Docs/metadata-only changes need no paid calls; optional unrun matrix lanes do not block landing.
 
-`smoke:platform:all` runs doctor first and then all required local targets and suites in one full gate execution.
+No paid Cloud testing for generic PRs/releases; only explicitly Cursor Cloud-focused PRs/issues may select necessary focused Cloud proof. The multi-lane Cloud command and `smoke:platform:all` remain optional comprehensive tools, not unconditional gates. No full paid campaign replay, matrix-only host coverage, or automatic paid retries. Automated Cursor PR reviews continue unchanged. Record exactly what passed, what retained evidence was reused, and any specific necessary proof still missing.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-cursor-sdk",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "pi provider extension backed by @cursor/sdk local and cloud agents",
   "author": "Mitch Fultz (https://github.com/fitchmultz)",
   "license": "MIT",
@@ -120,7 +120,7 @@
     "node": ">=24"
   },
   "scripts": {
-    "check:compat": "npm run build && npm run verify && node --test test/native-provider.test.mjs",
+    "check:compat": "npm run build && npm run verify && node --test test/ci-compatibility.test.mjs test/native-provider.test.mjs test/native-cursor-flow.test.mjs",
     "build": "node ./scripts/build.mjs",
     "prepare": "node ./scripts/prepare.mjs",
     "typecheck": "npm run typecheck:src && npm run typecheck:tests && npm run typecheck:replay-compile",
@@ -180,16 +180,16 @@
     "typebox": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-ai": "0.87.1",
-    "@earendil-works/pi-coding-agent": "0.87.1",
-    "@earendil-works/pi-tui": "0.87.1",
+    "@earendil-works/pi-ai": "0.99.1",
+    "@earendil-works/pi-coding-agent": "0.99.1",
+    "@earendil-works/pi-tui": "0.99.1",
     "@modelcontextprotocol/client": "2.1.0",
     "@types/node": "24.19.0",
     "@typescript/typescript6": "6.0.2",
     "@xterm/xterm": "6.0.0",
     "node-pty": "1.1.0",
     "playwright": "1.63.0",
-    "typebox": "1.3.34",
+    "typebox": "1.3.27",
     "typescript": "7.0.2",
     "vitest": "5.0.2"
   },

package/scripts/cloud-runtime-smoke.mjs

@@ -84,14 +84,16 @@ class SmokeFailure extends Error {
 }
 
 function printHelp() {
-	console.log(`Required live Cursor cloud release smoke for pi-cursor-sdk.
+	console.log(`Explicit Cursor Cloud-focused live smoke for pi-cursor-sdk.
+
+No paid Cloud testing for generic PRs/releases. Only PRs/issues explicitly focused on Cursor Cloud may select necessary focused Cloud proof after offline checks and retained-evidence reuse. Automated Cursor PR reviews continue unchanged. The multi-lane matrix is optional, not an unconditional ship gate; no automatic paid retries.
 
 Usage:
   npm run smoke:cloud
   npm run smoke:cloud:context
   node scripts/cloud-runtime-smoke.mjs [--context-matrix]
 
-The no-flag release gate creates and deletes one private throwaway GitHub repository and runs named lanes for cancel, explicit repo/startingRef branch reporting, direct push, missing branch failure, lifecycle delete, and account-conditional artifacts/raw usage. It requires current gh auth with private-repo create/push/delete access and Cursor Cloud access to that repository.
+The optional no-flag matrix creates and deletes one private throwaway GitHub repository and runs named lanes for cancel, explicit repo/startingRef branch reporting, direct push, missing branch failure, lifecycle delete, and account-conditional artifacts/raw usage. It requires current gh auth with private-repo create/push/delete access and Cursor Cloud access to that repository.
 
 Environment:
   CURSOR_API_KEY                    Required for cloud runs and verified agent cleanup.

package/scripts/local-resume-smoke.mjs

@@ -473,7 +473,7 @@ async function runFallbackSmoke() {
 			const fallback = await promptAndRead({
 				rpc,
 				artifactDir: artifactRoot,
-				message: "What exact LOCAL_FALLBACK marker is visible after the missing local agent fallback? Reply exactly MARKER=<marker> if visible, otherwise NO_MARKER.",
+				message: "Repeat the exact LOCAL_FALLBACK marker from my immediately previous message in this conversation. Use only conversation history; do not use tools or inspect files. Reply exactly MARKER=<marker> if that prior message is present, otherwise NO_MARKER.",
 				timeoutMs,
 				seenMetadata,
 			});

package/scripts/platform-smoke/card-detect.mjs

@@ -8,7 +8,6 @@
 
 import { writeFileSync, mkdirSync } from "node:fs";
 import { resolve } from "node:path";
-import { stripVTControlCharacters } from "node:util";
 import { matchesWrappedLineAt } from "./wrapped-line-match.mjs";
 
 const CARD_PATTERNS = [
@@ -35,21 +34,16 @@ const CARD_PATTERNS = [
 	{ id: "footer-status", pattern: /\bgrok-4\.6\b|\bcomposer-2-5\b|\bcomposer-2\.5\b/i },
 ];
 
-function cleanLine(line) {
-	return stripVTControlCharacters(line).replace(/\r/g, "");
-}
-
 function matchesCardAt(lines, index, card) {
 	return matchesWrappedLineAt(lines, index, card.pattern, card.wrappedPattern);
 }
 
 /**
- * Detect stable rendered evidence regions in terminal text.
+ * Detect stable evidence regions in canonical rendered xterm buffer lines.
  *
  * Returns an array of { id, label, startLine, endLine }.
  */
-export function detectCards(txtContent) {
-	const lines = txtContent.split("\n").map(cleanLine);
+export function detectCards(lines) {
 	const cards = [];
 	const seen = new Set();
 

package/scripts/platform-smoke/targets.mjs

@@ -23,7 +23,7 @@ export { isSafePlatformBundlePath as isSafeBundlePath } from "./artifacts.mjs";
 import { getScenario } from "./scenarios.mjs";
 import { warmupLease, runOnLease, stopLease } from "./crabbox-runner.mjs";
 import { renderAll } from "./render-ansi.mjs";
-import { assertRequiredCards, detectCards, writeCardArtifacts } from "./card-detect.mjs";
+import { assertRequiredCards } from "./card-detect.mjs";
 import { collectVisualEvidence } from "./visual-evidence.mjs";
 import { extractContentText, extractFinalTextContent } from "./jsonl-text.mjs";
 import { executeLocalResumeSuite } from "./local-resume-runner.mjs";
@@ -531,7 +531,6 @@ async function executeLiveSuite(config, targetName, suiteName, suiteDir, slug, l
 	const terminalAnsi = resolve(liveArtifactDir, "terminal.ansi");
 	const terminalTxt = resolve(liveArtifactDir, "terminal.txt");
 	let renderResult = { pngOk: false };
-	let cards = [];
 	if (existsSync(terminalAnsi)) {
 		renderResult = await renderAll(terminalAnsi, liveArtifactDir, {
 			label: `${targetName}-${suiteName}`,
@@ -540,17 +539,12 @@ async function executeLiveSuite(config, targetName, suiteName, suiteDir, slug, l
 			sessionId: `${targetName}-${suiteName}`,
 		});
 	}
-	if (existsSync(terminalTxt)) {
-		cards = detectCards(readFileSync(terminalTxt, "utf8"));
-		writeCardArtifacts(liveArtifactDir, cards);
-	}
 
 	const statusPath = resolve(liveArtifactDir, "live-status.json");
 	const status = readJson(statusPath);
 	const terminalText = existsSync(terminalTxt) ? readFileSync(terminalTxt, "utf8") : "";
 	const jsonlPath = resolve(liveArtifactDir, "session.jsonl");
 	const jsonlRaw = existsSync(jsonlPath) ? readFileSync(jsonlPath, "utf8") : "";
-	const cardChecks = assertRequiredCards(liveArtifactDir, cards, scenario?.requiredCards ?? []);
 	const jsonlToolNames = collectJsonlToolNames(jsonlRaw);
 	const jsonlResults = collectJsonlToolResults(jsonlRaw);
 	const usageChecks = collectUsageChecks(jsonlRaw);
@@ -586,14 +580,13 @@ async function executeLiveSuite(config, targetName, suiteName, suiteDir, slug, l
 		{ id: "bridge-diagnostic-request-resolved", fn: () => bridgeDiagnostics.some((event) => event.event === "request_resolved") },
 	] : [];
 	const visualEvidenceSpecs = scenario?.visualEvidence ?? [];
-	const visualEvidence = existsSync(resolve(liveArtifactDir, "terminal.html"))
-		? await collectVisualEvidence({
-			htmlPath: resolve(liveArtifactDir, "terminal.html"),
-			pngPath: resolve(liveArtifactDir, "terminal.full.png"),
-			outDir: liveArtifactDir,
-			specs: visualEvidenceSpecs,
-		})
-		: { ok: false, checks: [{ id: "visual-html-present", ok: false, error: "terminal.html missing" }] };
+	const visualEvidence = await collectVisualEvidence({
+		htmlPath: resolve(liveArtifactDir, "terminal.html"),
+		pngPath: resolve(liveArtifactDir, "terminal.full.png"),
+		outDir: liveArtifactDir,
+		specs: visualEvidenceSpecs,
+	});
+	const cardChecks = assertRequiredCards(liveArtifactDir, visualEvidence.cards, scenario?.requiredCards ?? []);
 	const visualEvidenceResultChecks = visualEvidenceSpecs
 		.filter((spec) => spec.jsonlResultId)
 		.map((spec) => ({

package/scripts/platform-smoke/visual-evidence.mjs

@@ -2,6 +2,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { matchesWrappedLineAt } from "./wrapped-line-match.mjs";
+import { detectCards, writeCardArtifacts } from "./card-detect.mjs";
 
 function pngSize(path) {
 	try {
@@ -39,6 +40,7 @@ export function findVisualEvidenceItems(lines, specs = []) {
 
 export async function collectVisualEvidence({ htmlPath, pngPath, outDir, specs = [] }) {
 	mkdirSync(outDir, { recursive: true });
+	let cards = [];
 	const evidence = {
 		ok: false,
 		htmlPath,
@@ -52,8 +54,9 @@ export async function collectVisualEvidence({ htmlPath, pngPath, outDir, specs =
 
 	if (!existsSync(htmlPath)) {
 		evidence.checks.push({ id: "visual-html-present", ok: false, error: "terminal.html missing" });
+		writeCardArtifacts(outDir, cards);
 		writeFileSync(resolve(outDir, "visual-evidence.json"), JSON.stringify(evidence, null, 2));
-		return evidence;
+		return { ...evidence, cards };
 	}
 
 	let browser;
@@ -99,6 +102,7 @@ export async function collectVisualEvidence({ htmlPath, pngPath, outDir, specs =
 			}
 			return out;
 		});
+		cards = detectCards(lines);
 
 		for (const item of findVisualEvidenceItems(lines, specs)) {
 			if (item.ok) {
@@ -133,6 +137,7 @@ export async function collectVisualEvidence({ htmlPath, pngPath, outDir, specs =
 		evidence.checks.push({ id: `visual-evidence-${item.id}`, ok: item.ok === true, line: item.line, screenshot: item.screenshot, pattern: item.pattern, error: item.error });
 	}
 	evidence.ok = evidence.checks.every((check) => check.ok);
+	writeCardArtifacts(outDir, cards);
 	writeFileSync(resolve(outDir, "visual-evidence.json"), JSON.stringify(evidence, null, 2));
-	return evidence;
+	return { ...evidence, cards };
 }