pi-cursor-sdk 0.1.28 → 0.1.30

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

@@ -0,0 +1,187 @@
+param(
+	[string]$PackageName = "pi-cursor-sdk",
+	[int]$NodeValidationMajor = 24
+)
+
+$ErrorActionPreference = "Continue"
+
+function Exit-CodeFromLastCommand {
+	if ($null -ne $global:LASTEXITCODE) { return [int]$global:LASTEXITCODE }
+	if ($?) { return 0 }
+	return 1
+}
+
+function Write-SectionFile {
+	param([string]$Name, [string]$Path)
+	Write-Output "--- $Name START ---"
+	if (Test-Path -LiteralPath $Path) {
+		Get-Content -LiteralPath $Path -ErrorAction SilentlyContinue
+	}
+	Write-Output "--- $Name END ---"
+}
+
+Write-Output "Starting platform-build in $(Get-Location) at $(Get-Date -Format o)"
+$SourceRoot = (Get-Location).Path
+$RunRoot = Join-Path $SourceRoot (Join-Path ".platform-smoke-runs" ("platform-build-" + (Get-Date -Format "yyyyMMddTHHmmssZ") + "-" + $PID))
+$PackDir = Join-Path $RunRoot "pack"
+$TestWorkspace = Join-Path $RunRoot "test-workspace"
+$PiProject = Join-Path $RunRoot "pi-project"
+New-Item -ItemType Directory -Force -Path $PackDir, $TestWorkspace, $PiProject | Out-Null
+Write-Output "PLATFORM_RUN_ROOT=$RunRoot"
+Write-Output "PLATFORM_TEST_WORKSPACE=$TestWorkspace"
+Write-Output "PLATFORM_PI_PROJECT=$PiProject"
+
+$NodeVersion = (& node.exe --version).Trim()
+$NpmVersion = (& npm.cmd --version).Trim()
+$NodeMajor = [int](($NodeVersion -replace '^v', '').Split('.')[0])
+Set-Content -LiteralPath (Join-Path $PackDir "node-version.txt") -Value $NodeVersion
+Set-Content -LiteralPath (Join-Path $PackDir "npm-version.txt") -Value $NpmVersion
+if ($NodeMajor -ge $NodeValidationMajor) { $NODE_VERSION_EXIT = 0 } else { $NODE_VERSION_EXIT = 1 }
+Write-Output "PLATFORM_NODE_VERSION=$NodeVersion"
+Write-Output "PLATFORM_NPM_VERSION=$NpmVersion"
+Write-Output "PLATFORM_NODE_VERSION_EXIT=$NODE_VERSION_EXIT"
+Write-SectionFile "NODE_VERSION_STDOUT" (Join-Path $PackDir "node-version.txt")
+Write-SectionFile "NPM_VERSION_STDOUT" (Join-Path $PackDir "npm-version.txt")
+
+$NpmCiOut = Join-Path $PackDir "npm-ci.stdout.txt"
+$NpmCiErr = Join-Path $PackDir "npm-ci.stderr.txt"
+$CheckPlatformSmokeOut = Join-Path $PackDir "check-platform-smoke.stdout.txt"
+$CheckPlatformSmokeErr = Join-Path $PackDir "check-platform-smoke.stderr.txt"
+$NpmTestOut = Join-Path $PackDir "npm-test.stdout.txt"
+$NpmTestErr = Join-Path $PackDir "npm-test.stderr.txt"
+$TypecheckOut = Join-Path $PackDir "typecheck.stdout.txt"
+$TypecheckErr = Join-Path $PackDir "typecheck.stderr.txt"
+$NpmPackOut = Join-Path $PackDir "npm-pack.stdout.txt"
+$NpmPackErr = Join-Path $PackDir "npm-pack.stderr.txt"
+
+Write-Output "=== npm ci ==="
+& npm.cmd ci 1> $NpmCiOut 2> $NpmCiErr
+$CI_EXIT = Exit-CodeFromLastCommand
+Write-Output "PLATFORM_NPM_CI_EXIT=$CI_EXIT"
+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
+
+Write-Output "=== typecheck ==="
+& npm.cmd run typecheck 1> $TypecheckOut 2> $TypecheckErr
+$TC_EXIT = Exit-CodeFromLastCommand
+Write-Output "PLATFORM_TYPECHECK_EXIT=$TC_EXIT"
+Write-SectionFile "TYPECHECK_STDOUT" $TypecheckOut
+Write-SectionFile "TYPECHECK_STDERR" $TypecheckErr
+
+Write-Output "=== npm pack ==="
+& npm.cmd pack --silent 1> $NpmPackOut 2> $NpmPackErr
+$PACK_EXIT = Exit-CodeFromLastCommand
+Write-Output "PLATFORM_NPM_PACK_EXIT=$PACK_EXIT"
+Write-SectionFile "NPM_PACK_STDOUT" $NpmPackOut
+Write-SectionFile "NPM_PACK_STDERR" $NpmPackErr
+$PackTarball = (Get-Content -LiteralPath $NpmPackOut -ErrorAction SilentlyContinue | Select-Object -First 1)
+if ($PackTarball) { $PackTarball = $PackTarball.Trim() }
+Write-Output "PLATFORM_NPM_PACK_EXIT=$PACK_EXIT"
+if ($PackTarball -and (Test-Path -LiteralPath $PackTarball)) {
+	Move-Item -LiteralPath $PackTarball -Destination (Join-Path $PackDir $PackTarball) -Force
+}
+Write-Output "PLATFORM_PACKED_TARBALL=$PackTarball"
+Set-Content -Path (Join-Path $PackDir "packed-tarball.txt") -Value $PackTarball
+
+Write-Output "=== fixture workspace ==="
+Copy-Item -LiteralPath package.json, README.md -Destination $TestWorkspace -ErrorAction SilentlyContinue
+Copy-Item -LiteralPath src -Destination $TestWorkspace -Recurse -ErrorAction SilentlyContinue
+if ((Test-Path -LiteralPath (Join-Path $TestWorkspace "package.json")) -and (Test-Path -LiteralPath (Join-Path $TestWorkspace "README.md")) -and (Test-Path -LiteralPath (Join-Path $TestWorkspace "src"))) {
+	$FIXTURE_EXIT = 0
+} else {
+	$FIXTURE_EXIT = 1
+}
+Write-Output "PLATFORM_FIXTURE_EXIT=$FIXTURE_EXIT"
+
+$PiCli = Join-Path (Get-Location) "node_modules\.bin\pi.cmd"
+if (-not (Test-Path -LiteralPath $PiCli)) { $PiCli = Join-Path (Get-Location) "node_modules\.bin\pi" }
+if (-not (Test-Path -LiteralPath $PiCli)) {
+	$Command = Get-Command pi -ErrorAction SilentlyContinue
+	$PiCli = $Command.Source
+}
+Write-Output "PLATFORM_PI_CLI=$PiCli"
+
+$PackedNodeInstallOut = Join-Path $PackDir "packed-node-install.stdout.txt"
+$PackedNodeInstallErr = Join-Path $PackDir "packed-node-install.stderr.txt"
+$PiInstallOut = Join-Path $PackDir "pi-install.stdout.txt"
+$PiInstallErr = Join-Path $PackDir "pi-install.stderr.txt"
+$PiListOut = Join-Path $PackDir "pi-list.stdout.txt"
+$PiListErr = Join-Path $PackDir "pi-list.stderr.txt"
+
+Write-Output "=== pi install packed tarball ==="
+$TarballPath = Join-Path $PackDir $PackTarball
+if ($PackTarball -and $PiCli -and (Test-Path -LiteralPath $TarballPath)) {
+	Push-Location $PiProject
+	& npm.cmd init -y 1> $PackedNodeInstallOut 2> $PackedNodeInstallErr
+	$NPM_INIT_EXIT = Exit-CodeFromLastCommand
+	if ($NPM_INIT_EXIT -eq 0) {
+		& npm.cmd install --no-save $TarballPath 1>> $PackedNodeInstallOut 2>> $PackedNodeInstallErr
+		$PACKED_NODE_INSTALL_EXIT = Exit-CodeFromLastCommand
+	} else {
+		$PACKED_NODE_INSTALL_EXIT = $NPM_INIT_EXIT
+	}
+	if ($PACKED_NODE_INSTALL_EXIT -eq 0) {
+		$PreviousPiOffline = $env:PI_OFFLINE
+		$env:PI_OFFLINE = "1"
+		& $PiCli install -l (Join-Path ".\node_modules" $PackageName) 1> $PiInstallOut 2> $PiInstallErr
+		$PI_INSTALL_EXIT = Exit-CodeFromLastCommand
+		if ($null -eq $PreviousPiOffline) { Remove-Item Env:\PI_OFFLINE -ErrorAction SilentlyContinue } else { $env:PI_OFFLINE = $PreviousPiOffline }
+	} else {
+		Set-Content -LiteralPath $PiInstallErr -Value "packed npm install failed"
+		$PI_INSTALL_EXIT = 1
+	}
+	Pop-Location
+} else {
+	Set-Content -LiteralPath $PackedNodeInstallErr -Value "missing pi cli or tarball"
+	Set-Content -LiteralPath $PiInstallErr -Value "missing pi cli or tarball"
+	$PACKED_NODE_INSTALL_EXIT = 1
+	$PI_INSTALL_EXIT = 1
+}
+Write-Output "PLATFORM_PACKED_NODE_INSTALL_EXIT=$PACKED_NODE_INSTALL_EXIT"
+Write-SectionFile "PACKED_NODE_INSTALL_STDOUT" $PackedNodeInstallOut
+Write-SectionFile "PACKED_NODE_INSTALL_STDERR" $PackedNodeInstallErr
+Write-Output "PLATFORM_PI_INSTALL_EXIT=$PI_INSTALL_EXIT"
+Write-SectionFile "PI_INSTALL_STDOUT" $PiInstallOut
+Write-SectionFile "PI_INSTALL_STDERR" $PiInstallErr
+
+Write-Output "=== pi list ==="
+if ($PiCli) {
+	Push-Location $PiProject
+	$PreviousPiOffline = $env:PI_OFFLINE
+	$env:PI_OFFLINE = "1"
+	& $PiCli list 1> $PiListOut 2> $PiListErr
+	$PI_LIST_EXIT = Exit-CodeFromLastCommand
+	if ($null -eq $PreviousPiOffline) { Remove-Item Env:\PI_OFFLINE -ErrorAction SilentlyContinue } else { $env:PI_OFFLINE = $PreviousPiOffline }
+	Pop-Location
+} else {
+	Set-Content -LiteralPath $PiListErr -Value "missing pi cli"
+	$PI_LIST_EXIT = 1
+}
+Write-Output "PLATFORM_PI_LIST_EXIT=$PI_LIST_EXIT"
+Write-SectionFile "PI_LIST_STDOUT" $PiListOut
+Write-SectionFile "PI_LIST_STDERR" $PiListErr
+
+Write-Output "node=$NODE_VERSION_EXIT ci=$CI_EXIT checkPlatformSmoke=$CHECK_PLATFORM_SMOKE_EXIT test=$TEST_EXIT typecheck=$TC_EXIT pack=$PACK_EXIT fixture=$FIXTURE_EXIT packedNodeInstall=$PACKED_NODE_INSTALL_EXIT install=$PI_INSTALL_EXIT list=$PI_LIST_EXIT"
+if ($NODE_VERSION_EXIT -ne 0 -or $CI_EXIT -ne 0 -or $CHECK_PLATFORM_SMOKE_EXIT -ne 0 -or $TEST_EXIT -ne 0 -or $TC_EXIT -ne 0 -or $PACK_EXIT -ne 0 -or $FIXTURE_EXIT -ne 0 -or $PACKED_NODE_INSTALL_EXIT -ne 0 -or $PI_INSTALL_EXIT -ne 0 -or $PI_LIST_EXIT -ne 0) {
+	Write-Output "PLATFORM_BUILD_FAILED: node=$NODE_VERSION_EXIT ci=$CI_EXIT checkPlatformSmoke=$CHECK_PLATFORM_SMOKE_EXIT test=$TEST_EXIT typecheck=$TC_EXIT pack=$PACK_EXIT fixture=$FIXTURE_EXIT packedNodeInstall=$PACKED_NODE_INSTALL_EXIT install=$PI_INSTALL_EXIT list=$PI_LIST_EXIT"
+	exit 1
+}
+Write-Output "PLATFORM_BUILD_OK"

package/scripts/platform-smoke/pty-capture.mjs

@@ -0,0 +1,131 @@
+/**
+ * PTY capture harness — records the full ANSI stream from a terminal session.
+ *
+ * Captures: pty.events.jsonl, terminal.ansi, terminal.txt, exit code, signal.
+ * Terminal dimensions: 150 columns × 45 rows.
+ */
+
+import { spawn } from "node:child_process";
+import { writeFileSync, appendFileSync, mkdirSync } from "node:fs";
+import { resolve } from "node:path";
+
+const COLS = 150;
+const ROWS = 45;
+
+/**
+ * Capture a command inside a PTY and write artifacts to `dir`.
+ *
+ * Returns { code, signal, ansiPath, txtPath, eventsPath }.
+ *
+ * Uses node-pty if available, otherwise falls back to plain child_process.
+ */
+export async function capturePTY(dir, command, opts = {}) {
+	mkdirSync(dir, { recursive: true });
+
+	const eventsPath = resolve(dir, "pty.events.jsonl");
+	const ansiPath = resolve(dir, "terminal.ansi");
+	const txtPath = resolve(dir, "terminal.txt");
+
+	let ansiBuffer = "";
+	let txtBuffer = "";
+
+	function appendEvent(event) {
+		appendFileSync(eventsPath, JSON.stringify(event) + "\n");
+	}
+	function appendOutput(data) {
+		const text = typeof data === "string" ? data : data.toString();
+		ansiBuffer += text;
+		// Strip ANSI for plain text
+		txtBuffer += stripANSI(text);
+	}
+
+	// Try node-pty first
+	let pty;
+	try {
+		const ptyModule = await import("node-pty");
+		pty = ptyModule;
+	} catch {
+		console.log("  node-pty not available — using plain child_process spawn (no PTY sizing)");
+	}
+
+	const startTime = Date.now();
+	appendEvent({ type: "start", time: startTime, cols: COLS, rows: ROWS, command });
+
+	if (pty) {
+		// Use real PTY — always spawn through a shell for portability
+		const shellCmd = process.platform === "win32" ? "powershell.exe" : "/bin/bash";
+		const shellArgs = process.platform === "win32"
+			? ["-NoProfile", "-Command", command.join(" ")]
+			: ["-lc", command.join(" ")];
+
+		const ptyProcess = pty.spawn(shellCmd, shellArgs, {
+			name: "xterm-256color",
+			cols: COLS,
+			rows: ROWS,
+			cwd: opts.cwd ?? process.cwd(),
+			env: { ...process.env, ...opts.env },
+		});
+
+		ptyProcess.onData((data) => {
+			appendOutput(data);
+			appendEvent({ type: "output", time: Date.now() - startTime, bytes: data.length });
+		});
+
+		const { code, signal } = await new Promise((resolvePromise) => {
+			ptyProcess.onExit((e) => {
+				appendEvent({ type: "exit", time: Date.now() - startTime, code: e.exitCode, signal: e.signal });
+				resolvePromise({ code: e.exitCode, signal: e.signal });
+			});
+		});
+
+		writeFileSync(ansiPath, ansiBuffer);
+		writeFileSync(txtPath, txtBuffer);
+
+		return { code: code ?? (signal ? 1 : 0), signal, ansiPath, txtPath, eventsPath };
+	} else {
+		// Fallback: plain child_process
+		const child = spawn(command[0], command.slice(1), {
+			stdio: ["pipe", "pipe", "pipe"],
+			cwd: opts.cwd ?? process.cwd(),
+			env: { ...process.env, ...opts.env, COLUMNS: String(COLS), LINES: String(ROWS) },
+		});
+
+		child.stdout.on("data", (d) => {
+			appendOutput(d.toString());
+			appendEvent({ type: "output", time: Date.now() - startTime, bytes: d.length });
+		});
+		child.stderr.on("data", (d) => {
+			appendOutput(d.toString());
+			appendEvent({ type: "stderr", time: Date.now() - startTime, bytes: d.length });
+		});
+
+		const { code, signal } = await new Promise((resolvePromise) => {
+			child.on("close", (c, s) => {
+				appendEvent({ type: "exit", time: Date.now() - startTime, code: c, signal: s });
+				resolvePromise({ code: c, signal: s });
+			});
+			child.on("error", (err) => {
+				appendEvent({ type: "error", time: Date.now() - startTime, error: err.message });
+				resolvePromise({ code: 1, signal: null });
+			});
+		});
+
+		writeFileSync(ansiPath, ansiBuffer);
+		writeFileSync(txtPath, txtBuffer);
+
+		return { code: code ?? (signal ? 1 : 0), signal, ansiPath, txtPath, eventsPath };
+	}
+}
+
+/** Strip ANSI escape sequences from a string. */
+function stripANSI(str) {
+	return str.replace(/\x1b\[[0-9;]*[a-zA-Z]/g, "").replace(/\x1b\][^\x07]*\x07/g, "");
+}
+
+/** Self-test: can we create a simple PTY? */
+export async function ptySelfTest() {
+	const dir = resolve(process.cwd(), ".artifacts", "pty-self-test");
+	mkdirSync(dir, { recursive: true });
+	const result = await capturePTY(dir, ["echo", "pty-self-test-ok"]);
+	return result;
+}

package/scripts/platform-smoke/render-ansi.mjs

@@ -0,0 +1,65 @@
+/**
+ * Host-side ANSI renderer — converts terminal.ansi into HTML and PNG screenshots.
+ *
+ * This wraps the existing visual smoke renderer so platform smoke uses the same
+ * xterm.js/Playwright path as the maintainer visual TUI smoke.
+ */
+
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+import { buildTerminalHtml, writeTerminalScreenshot } from "../lib/cursor-visual-render.mjs";
+
+const COLS = 150;
+const ROWS = 45;
+const HISTORY_LINES = 3_000;
+
+function stripANSI(text) {
+	return text.replace(/\x1b\[[0-9;?]*[ -/]*[@-~]/g, "").replace(/\x1b\][^\x07]*(?:\x07|\x1b\\)/g, "");
+}
+
+/** Render terminal.ansi to terminal.html using the shared xterm.js renderer. */
+export async function renderHTML(ansiPath, htmlPath, options = {}) {
+	const ansi = readFileSync(ansiPath, "utf8");
+	const plain = options.plain ?? stripANSI(ansi);
+	const html = buildTerminalHtml({
+		ansi,
+		plain,
+		options: {
+			label: options.label ?? "platform-smoke",
+			model: options.model ?? "cursor/composer-2-5",
+			mode: options.mode ?? "agent",
+			cwd: options.cwd ?? process.cwd(),
+			sessionId: options.sessionId ?? "platform-smoke",
+			width: options.width ?? COLS,
+			height: options.height ?? ROWS,
+			historyLines: options.historyLines ?? HISTORY_LINES,
+		},
+	});
+	writeFileSync(htmlPath, html);
+	return htmlPath;
+}
+
+/** Render terminal.html to terminal.full.png and terminal.final-viewport.png using Playwright. */
+export async function renderPNG(htmlPath, fullPNGPath, viewportPNGPath, options = {}) {
+	try {
+		await writeTerminalScreenshot(htmlPath, fullPNGPath, options.width ?? COLS, options.height ?? ROWS);
+		// The shared renderer captures the terminal element. Keep a second artifact name for the platform contract.
+		writeFileSync(viewportPNGPath, readFileSync(fullPNGPath));
+		return { fullPNGPath, viewportPNGPath };
+	} catch (error) {
+		console.log(`  PNG render skipped: ${error instanceof Error ? error.message : String(error)}`);
+		return null;
+	}
+}
+
+/** Full render pipeline: ANSI → HTML → PNG. */
+export async function renderAll(ansiPath, dir, options = {}) {
+	mkdirSync(dir, { recursive: true });
+	const htmlPath = resolve(dir, "terminal.html");
+	const fullPNGPath = resolve(dir, "terminal.full.png");
+	const viewportPNGPath = resolve(dir, "terminal.final-viewport.png");
+	await renderHTML(ansiPath, htmlPath, options);
+	const pngResult = await renderPNG(htmlPath, fullPNGPath, viewportPNGPath, options);
+	return { htmlPath, fullPNGPath, viewportPNGPath, pngOk: pngResult !== null };
+}

package/scripts/platform-smoke/scenarios.mjs

@@ -0,0 +1,186 @@
+/**
+ * Scenario definitions for all required platform smoke suites.
+ *
+ * Each scenario defines the prompt template, environment, command rendering,
+ * required artifacts, and assertion contracts.
+ *
+ * Platform rendering: posix (macOS/Ubuntu) or powershell (Windows native).
+ */
+
+export const SCENARIOS = {
+	"platform-build": {
+		description: "Build, test, typecheck, pack, and install the extension without Cursor calls.",
+		cursorCalls: 0,
+		commands: {
+			npmCi: { posix: "npm ci", powershell: "npm ci" },
+			npmTest: { posix: "npm test", powershell: "npm test" },
+			npmTypecheck: { posix: "npm run typecheck", powershell: "npm run typecheck" },
+			npmPack: { posix: "npm pack", powershell: "npm pack" },
+		},
+	},
+
+	"cursor-native-visual-matrix": {
+		description: "Prove provider reality, native tool replay, card rendering, JSONL correctness.",
+		cursorCalls: 1,
+		env: {
+			PI_CURSOR_SETTING_SOURCES: "none",
+			PI_CURSOR_NATIVE_TOOL_DISPLAY: "1",
+			PI_CURSOR_REGISTER_NATIVE_TOOLS: "1",
+			PI_CURSOR_PI_TOOL_BRIDGE: "0",
+			PI_CURSOR_EXPOSE_BUILTIN_TOOLS: "0",
+			PI_CURSOR_SDK_EVENT_DEBUG: "1",
+		},
+		commands: {
+			shellSmoke: {
+				posix: "printf 'cursor visual smoke\\n'",
+				powershell: "Write-Output 'cursor visual smoke'",
+			},
+			shellFailure: {
+				posix: "sh -c 'echo native shell failure >&2; exit 7'",
+				powershell: "Write-Error 'native shell failure'; exit 7",
+			},
+		},
+		promptTemplate: `Native visual matrix.
+
+Use Cursor-native tools only. Do not use pi__ tools.
+
+Steps:
+1. read ./package.json and remember the package name.
+2. grep ./README.md for "pi-cursor-sdk".
+3. find README.md from repo root.
+4. find src/cursor-provider.ts from repo root.
+5. run shell: {{shellSmoke}}
+6. write .debug/platform-smoke/native.txt with alpha and beta.
+7. edit beta to gamma in that file.
+8. run shell and preserve the failure: {{shellFailure}}
+9. answer exactly:
+NATIVE_MATRIX_OK package=<name> grep=<yes/no> find=<yes/no> list=<yes/no> shell=<yes/no> shell_fail=<yes/no> write=<yes/no> edit=<yes/no>`,
+		finalMarker: "NATIVE_MATRIX_OK package=pi-cursor-sdk",
+		requiredCards: [
+			"read", "grep", "find", "shell-success", "write", "edit-diff", "shell-failure", "footer-status",
+		],
+		requiredJSONLTools: [
+			{ name: "read" },
+			{ name: "grep" },
+			{ name: "find" },
+			{ name: "bash" },
+			{ name: "cursor" },
+			{ name: "edit" },
+		],
+		requiredJSONLResults: [
+			{ id: "native-read-package", toolName: "read", isError: false, contains: "pi-cursor-sdk" },
+			{ id: "native-grep-readme", toolName: "grep", isError: false, contains: "README.md" },
+			{ id: "native-find-readme", toolName: "find", isError: false, contains: "README.md" },
+			{ id: "native-list-src", toolName: "find", isError: false, contains: "cursor-provider.ts" },
+			{ id: "native-shell-output", toolName: "bash", isError: false, contains: "cursor visual smoke" },
+			{ id: "native-write-diff", toolName: "cursor", sourceToolName: "edit", isError: false, contains: "+beta" },
+			{ id: "native-edit-diff", toolName: "cursor", sourceToolName: "edit", isError: false, contains: "+gamma" },
+			{ id: "native-shell-failure", toolName: "bash", isError: true, contains: "native shell failure" },
+		],
+		visualEvidence: [
+			{ id: "native-read-package", pattern: "^\\s*read (\\./)?package\\.json", jsonlResultId: "native-read-package" },
+			{ id: "native-shell-success", pattern: "^\\s*cursor visual smoke\\s*$", jsonlResultId: "native-shell-output" },
+			{ id: "native-write-diff", pattern: "^\\s*\\+.*beta", jsonlResultId: "native-write-diff" },
+			{ id: "native-edit-diff", pattern: "^\\s*\\+.*gamma", jsonlResultId: "native-edit-diff" },
+			{ id: "native-shell-failure", pattern: "^\\s*native shell failure\\s*$|^\\s*Command exited with code 7\\s*$", jsonlResultId: "native-shell-failure" },
+		],
+	},
+
+	"cursor-bridge-visual-matrix": {
+		description: "Prove pi bridge routing, bridge tool cards, diagnostics, real pi tool names.",
+		cursorCalls: 1,
+		env: {
+			PI_CURSOR_SETTING_SOURCES: "none",
+			PI_CURSOR_NATIVE_TOOL_DISPLAY: "1",
+			PI_CURSOR_REGISTER_NATIVE_TOOLS: "1",
+			PI_CURSOR_PI_TOOL_BRIDGE: "1",
+			PI_CURSOR_EXPOSE_BUILTIN_TOOLS: "1",
+			PI_CURSOR_PI_TOOL_BRIDGE_DEBUG: "1",
+			PI_CURSOR_SDK_EVENT_DEBUG: "1",
+		},
+		commands: {
+			shellSmoke: {
+				posix: "node -e \"console.log('bridge visual smoke')\"",
+				powershell: "node -e \"console.log('bridge visual smoke')\"",
+			},
+		},
+		promptTemplate: `Bridge visual matrix.
+
+Use pi bridge tools only. Use exact pi__ names.
+
+You must make exactly three pi bridge tool calls before your final answer: pi__bash, pi__read, then pi__read. Do not answer until all three calls complete.
+
+Steps:
+1. call pi__bash with command: {{shellSmoke}}
+2. call pi__read on ./package.json.
+3. call pi__read on ./definitely-missing-platform-smoke-file.txt.
+4. answer exactly:
+BRIDGE_MATRIX_OK bash_ok=<yes/no> read_ok=<yes/no> read_missing_error=<yes/no>`,
+		finalMarker: "BRIDGE_MATRIX_OK bash_ok=yes",
+		requiredCards: [
+			"bridge-read-success", "bridge-read-failure",
+			"bridge-shell-success", "footer-status",
+		],
+		requiredJSONLTools: [
+			{ name: "read" },
+			{ name: "bash" },
+		],
+		requiredJSONLResults: [
+			{ id: "bridge-read-success", toolName: "read", isError: false, contains: "pi-cursor-sdk" },
+			{ id: "bridge-read-failure", toolName: "read", isError: true, contains: "definitely-missing-platform-smoke-file.txt" },
+			{ id: "bridge-shell-success", toolName: "bash", isError: false, contains: "bridge visual smoke" },
+		],
+		visualEvidence: [
+			{ id: "bridge-read-success", pattern: "^\\s*read \\./package\\.json", jsonlResultId: "bridge-read-success" },
+			{ id: "bridge-read-failure", pattern: "^\\s*read \\./definitely-missing-platform-smoke-file\\.txt|ENOENT: no such file", jsonlResultId: "bridge-read-failure" },
+			{ id: "bridge-shell-success", pattern: "^\\s*bridge visual smoke\\s*$", jsonlResultId: "bridge-shell-success" },
+		],
+		requiredBridgeDiagnostics: true,
+	},
+
+	"cursor-abort-cleanup": {
+		description: "Prove long-running bridge cancellation with no orphan processes.",
+		cursorCalls: 1,
+		env: {
+			PI_CURSOR_SETTING_SOURCES: "none",
+			PI_CURSOR_NATIVE_TOOL_DISPLAY: "1",
+			PI_CURSOR_REGISTER_NATIVE_TOOLS: "1",
+			PI_CURSOR_PI_TOOL_BRIDGE: "1",
+			PI_CURSOR_EXPOSE_BUILTIN_TOOLS: "1",
+			PI_CURSOR_PI_TOOL_BRIDGE_DEBUG: "1",
+			PI_CURSOR_SDK_EVENT_DEBUG: "1",
+		},
+		commands: {
+			longRunning: {
+				posix: "node -e \"const fs=require('fs');fs.mkdirSync('.debug/platform-smoke',{recursive:true});fs.writeFileSync('.debug/platform-smoke/abort-started.txt',String(process.pid));setTimeout(() => console.log(process.env.PLATFORM_ABORT_MARKER), 30000)\"",
+				powershell: "node -e \"const fs=require('fs');fs.mkdirSync('.debug/platform-smoke',{recursive:true});fs.writeFileSync('.debug/platform-smoke/abort-started.txt',String(process.pid));setTimeout(() => console.log(process.env.PLATFORM_ABORT_MARKER), 30000)\"",
+			},
+		},
+		promptTemplate: `Abort cleanup matrix.
+
+Call pi__bash with command:
+{{longRunning}}
+
+Do not answer until the tool completes.`,
+		finalMarker: null, // Should NOT succeed — harness interrupts
+		visualEvidence: [
+			{ id: "abort-long-running-shell", pattern: "^\\s*Elapsed [1-9](?:\\.\\d)?s\\s*$" },
+		],
+		requiredBridgeDiagnostics: "abort",
+	},
+};
+
+export function getScenario(name) {
+	return SCENARIOS[name] ?? null;
+}
+
+export function renderPrompt(scenario, platform) {
+	let prompt = scenario.promptTemplate;
+	if (scenario.commands) {
+		for (const [key, cmdMap] of Object.entries(scenario.commands)) {
+			const cmd = platform === "powershell" ? (cmdMap.powershell ?? cmdMap.posix) : (cmdMap.posix ?? cmdMap.powershell);
+			prompt = prompt.replaceAll(`{{${key}}}`, cmd ?? "");
+		}
+	}
+	return prompt;
+}