pi-cursor-sdk 0.1.39 → 0.1.41

package/scripts/platform-smoke/live-suite-runner.mjs

@@ -603,10 +603,10 @@ async function main() {
 			const npmInstallPacked = runLogged(logDir, "workspace-npm-install-packed", commandName("npm"), ["install", "--no-save", tarballPath], { cwd: workspaceDir, timeout: 180_000 });
 			requireOk(npmInstallPacked, "workspace npm install packed tarball");
 		}
-		const install = runLogged(logDir, "pi-install", piCli, ["install", "-l", installPath], { cwd: workspaceDir, env: piEnv, timeout: 120_000 });
-		requireOk(install, "pi install packed package directory");
-		const list = runLogged(logDir, "pi-list", piCli, ["list"], { cwd: workspaceDir, env: piEnv, timeout: 60_000 });
-		requireOk(list, "pi list");
+		const install = runLogged(logDir, "pi-install", piCli, ["install", "--approve", "-l", installPath], { cwd: workspaceDir, env: piEnv, timeout: 120_000 });
+		requireOk(install, "pi install --approve packed package directory");
+		const list = runLogged(logDir, "pi-list", piCli, ["list", "--approve"], { cwd: workspaceDir, env: piEnv, timeout: 60_000 });
+		requireOk(list, "pi list --approve");
 
 		const suiteEnv = {
 			...process.env,
@@ -620,16 +620,17 @@ async function main() {
 		if (args.suite === "cursor-abort-cleanup") writeProcessSnapshot(logDir, "process-before", platform);
 		const prompt = renderPrompt(scenario, platform);
 		writeFileSync(join(artifactDir, "prompt.txt"), prompt);
+		const piArgs = ["--approve", "--cursor-no-fast", "--cursor-mode", "agent", "--model", args.model, "--session-dir", sessionDir, "--session-id", `platform-${args.suite}-${Date.now()}`];
 		writeFileSync(join(artifactDir, "pi-command.json"), JSON.stringify({
 			piCli,
-			args: ["--cursor-no-fast", "--cursor-mode", "agent", "--model", args.model, "--session-dir", sessionDir, "--session-id", `platform-${args.suite}-${Date.now()}`],
+			args: piArgs,
 			cwd: workspaceDir,
 			env: Object.fromEntries(Object.entries(suiteEnv).filter(([key]) => key.startsWith("PI_CURSOR_") || key === "PI_CODING_AGENT_DIR" || key === "TERM")),
 		}, null, 2));
 		const ptyResult = await runPtyPi({
 			artifactDir,
 			piCli,
-			piArgs: ["--cursor-no-fast", "--cursor-mode", "agent", "--model", args.model, "--session-dir", sessionDir, "--session-id", `platform-${args.suite}-${Date.now()}`],
+			piArgs,
 			env: suiteEnv,
 			cwd: workspaceDir,
 			sessionDir,

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

@@ -137,7 +137,7 @@ if ($PackTarball -and $PiCli -and (Test-Path -LiteralPath $TarballPath)) {
 	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
+		& $PiCli install --approve -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 {
@@ -163,7 +163,7 @@ if ($PiCli) {
 	Push-Location $PiProject
 	$PreviousPiOffline = $env:PI_OFFLINE
 	$env:PI_OFFLINE = "1"
-	& $PiCli list 1> $PiListOut 2> $PiListErr
+	& $PiCli list --approve 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

package/scripts/platform-smoke/scenarios.mjs

@@ -131,7 +131,7 @@ BRIDGE_MATRIX_OK bash_ok=<yes/no> read_ok=<yes/no> read_missing_error=<yes/no>`,
 			{ 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-success", pattern: "^\\s*read (?:\\./package\\.json|.*[\\\\/]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" },
 		],

package/scripts/platform-smoke/targets.mjs

@@ -469,13 +469,13 @@ export function buildPlatformBuildCommand(targetName, packageName = "pi-cursor-s
 		lines.push('echo "PLATFORM_PACKED_NODE_INSTALL_EXIT=$PACKED_NODE_INSTALL_EXIT"');
 		lines.push(...posixSection("PACKED_NODE_INSTALL_STDOUT", 'cat "$PACK_DIR/packed-node-install.stdout.txt" 2>/dev/null || true'));
 		lines.push(...posixSection("PACKED_NODE_INSTALL_STDERR", 'cat "$PACK_DIR/packed-node-install.stderr.txt" 2>/dev/null || true'));
-		lines.push(`if [ "$PACKED_NODE_INSTALL_EXIT" -eq 0 ] && [ -n "$PI_CLI" ]; then (cd "$PI_PROJECT" && PI_OFFLINE=1 "$PI_CLI" install -l ./node_modules/${packageName} >"$PACK_DIR/pi-install.stdout.txt" 2>"$PACK_DIR/pi-install.stderr.txt"); PI_INSTALL_EXIT=$?; else echo "packed npm install failed or missing pi cli" >"$PACK_DIR/pi-install.stderr.txt"; PI_INSTALL_EXIT=1; fi`);
+		lines.push(`if [ "$PACKED_NODE_INSTALL_EXIT" -eq 0 ] && [ -n "$PI_CLI" ]; then (cd "$PI_PROJECT" && PI_OFFLINE=1 "$PI_CLI" install --approve -l ./node_modules/${packageName} >"$PACK_DIR/pi-install.stdout.txt" 2>"$PACK_DIR/pi-install.stderr.txt"); PI_INSTALL_EXIT=$?; else echo "packed npm install failed or missing pi cli" >"$PACK_DIR/pi-install.stderr.txt"; PI_INSTALL_EXIT=1; fi`);
 		lines.push('echo "PLATFORM_PI_INSTALL_EXIT=$PI_INSTALL_EXIT"');
 		lines.push(...posixSection("PI_INSTALL_STDOUT", 'cat "$PACK_DIR/pi-install.stdout.txt" 2>/dev/null || true'));
 		lines.push(...posixSection("PI_INSTALL_STDERR", 'cat "$PACK_DIR/pi-install.stderr.txt" 2>/dev/null || true'));
 		lines.push("");
 		lines.push('echo "=== pi list ==="');
-		lines.push('if [ -n "$PI_CLI" ]; then (cd "$PI_PROJECT" && PI_OFFLINE=1 "$PI_CLI" list >"$PACK_DIR/pi-list.stdout.txt" 2>"$PACK_DIR/pi-list.stderr.txt"); PI_LIST_EXIT=$?; else echo "missing pi cli" >"$PACK_DIR/pi-list.stderr.txt"; PI_LIST_EXIT=1; fi');
+		lines.push('if [ -n "$PI_CLI" ]; then (cd "$PI_PROJECT" && PI_OFFLINE=1 "$PI_CLI" list --approve >"$PACK_DIR/pi-list.stdout.txt" 2>"$PACK_DIR/pi-list.stderr.txt"); PI_LIST_EXIT=$?; else echo "missing pi cli" >"$PACK_DIR/pi-list.stderr.txt"; PI_LIST_EXIT=1; fi');
 		lines.push('echo "PLATFORM_PI_LIST_EXIT=$PI_LIST_EXIT"');
 		lines.push(...posixSection("PI_LIST_STDOUT", 'cat "$PACK_DIR/pi-list.stdout.txt" 2>/dev/null || true'));
 		lines.push(...posixSection("PI_LIST_STDERR", 'cat "$PACK_DIR/pi-list.stderr.txt" 2>/dev/null || true'));

package/scripts/platform-smoke.mjs

@@ -3,7 +3,9 @@
 import { createRequire } from "node:module";
 import { resolve, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
-import { accessSync, constants } from "node:fs";
+import { existsSync } from "node:fs";
+
+import { platformSmokeSuiteEvidence, prunePlatformSmokeArtifacts, redactSecrets, writeLatestPlatformSmokeIndex } from "./platform-smoke/artifacts.mjs";
 
 // ── helpers ────────────────────────────────────────────────────────────────
 const __filename = fileURLToPath(import.meta.url);
@@ -102,6 +104,53 @@ function validateSelections(targets, suites) {
 	}
 }
 
+function failedSuiteResults(result) {
+	if (!result) return [];
+	if (Array.isArray(result.results)) return result.results.filter((suiteResult) => suiteResult?.ok !== true);
+	return result.ok === true ? [] : [result];
+}
+
+function formatExistingPath(label, path) {
+	return path && existsSync(path) ? `  ${label}: ${path}` : undefined;
+}
+
+function printFailureEvidence(results, artifactRoot) {
+	const failed = [];
+	for (const { targetName, result } of results) {
+		let targetEvidenceCount = 0;
+		for (const suiteResult of failedSuiteResults(result)) {
+			const evidence = platformSmokeSuiteEvidence(suiteResult, artifactRoot);
+			if (evidence) {
+				targetEvidenceCount++;
+				failed.push({ targetName, ...evidence });
+			}
+		}
+		if (targetEvidenceCount === 0 && result?.ok !== true && result?.error) {
+			failed.push({ targetName, suite: "target", error: result.error });
+		}
+	}
+	if (failed.length === 0) return;
+	console.log("\nFailed suite artifacts:");
+	for (const item of failed) {
+		const paths = item.paths ?? {};
+		console.log(`- Suite: ${item.targetName}/${item.suite}`);
+		if (item.error) console.log(`  Target error: ${item.error}`);
+		const lines = [
+			formatExistingPath("Artifact dir", item.artifactDir),
+			formatExistingPath("Assertions", paths.assertions),
+			formatExistingPath("Failures", paths.failures),
+			formatExistingPath("Terminal HTML", paths.terminalHtml),
+			formatExistingPath("Terminal full PNG", paths.terminalFullPng),
+			formatExistingPath("Terminal final viewport PNG", paths.terminalFinalViewportPng),
+			formatExistingPath("Visual evidence", paths.visualEvidence),
+			formatExistingPath("Session JSONL", paths.sessionJsonl),
+			formatExistingPath("JSONL tool results", paths.jsonlToolResults),
+			formatExistingPath("Provider/Cursor debug artifacts", paths.providerDebugRoot),
+		].filter(Boolean);
+		for (const line of lines) console.log(line);
+	}
+}
+
 // ── commands ───────────────────────────────────────────────────────────────
 async function runDoctor() {
 	try {
@@ -123,8 +172,9 @@ async function runSuite(targetName, suiteName) {
 		const result = await runTargetSuite(config, targetName, suiteName);
 		return result;
 	} catch (err) {
-		console.error(`suite ${suiteName} on ${targetName} exception:`, err.message);
-		return { ok: false, error: err.message };
+		const message = redactSecrets(err.message);
+		console.error(`suite ${suiteName} on ${targetName} exception:`, message);
+		return { ok: false, error: message };
 	}
 }
 
@@ -133,8 +183,9 @@ async function runTarget(targetName, suites) {
 		const { runTargetSuites } = await import("./platform-smoke/targets.mjs");
 		return await runTargetSuites(config, targetName, suites);
 	} catch (err) {
-		console.error(`target ${targetName} exception:`, err.message);
-		return { ok: false, error: err.message };
+		const message = redactSecrets(err.message);
+		console.error(`target ${targetName} exception:`, message);
+		return { ok: false, error: message };
 	}
 }
 
@@ -172,6 +223,12 @@ async function main() {
 			process.exit(2);
 		}
 
+		const pruneResult = prunePlatformSmokeArtifacts(config.artifactRoot, config.artifactRetention);
+		if (pruneResult.removed.length > 0) {
+			console.log(`Pruned ${pruneResult.removed.length} old platform smoke artifact run(s) from ${pruneResult.root}`);
+		}
+
+		const startedAt = new Date().toISOString();
 		const targetRuns = targets.map(async (targetName) => {
 			console.log(`\n=== Target: ${targetName} ===`);
 			const result = args.suite
@@ -180,9 +237,21 @@ async function main() {
 			return { targetName, result };
 		});
 		const results = await Promise.all(targetRuns);
+		const finishedAt = new Date().toISOString();
+		const latest = writeLatestPlatformSmokeIndex(config, results, {
+			startedAt,
+			finishedAt,
+			command: {
+				cwd: process.cwd(),
+				targets,
+				suites,
+			},
+		});
+		console.log(`\nArtifact index: ${latest.path}`);
 		const anyFailed = results.some(({ result }) => !result.ok);
 		if (anyFailed) {
-			console.log("\nOne or more suites failed. Check .artifacts/platform-smoke/ for details.");
+			printFailureEvidence(results, config.artifactRoot);
+			console.log("\nOne or more suites failed.");
 			process.exit(1);
 		}
 		return;

package/scripts/steering-rpc-smoke.mjs

@@ -165,7 +165,7 @@ function buildPiRpcEnv(baseEnv = process.env, nodePath = process.execPath) {
 }
 
 async function runPiRpcSmoke(sessionDir, piBin) {
-	const args = ["-e", root, "--cursor-no-fast", "--model", "cursor/composer-2-5", "--mode", "rpc", "--session-dir", sessionDir];
+	const args = ["--approve", "-e", root, "--cursor-no-fast", "--model", "cursor/composer-2-5", "--mode", "rpc", "--session-dir", sessionDir];
 	const env = buildPiRpcEnv();
 
 	const child = spawn(piBin, args, { cwd: root, env, stdio: ["pipe", "pipe", "pipe"], detached: process.platform !== "win32" });

package/scripts/tmux-live-smoke.sh

@@ -392,7 +392,7 @@ if [[ "$SHELL_BIN" != /* ]]; then
 	SHELL_BIN="$(smoke_resolve_cmd "$SHELL_BIN")"
 fi
 PI_BASE=(
-	"$PI_BIN" -e "$ROOT"
+	"$PI_BIN" --approve -e "$ROOT"
 	--cursor-no-fast
 	--model cursor/composer-2-5
 )

package/scripts/visual-tui-smoke-self-test.mjs

@@ -0,0 +1,229 @@
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync, chmodSync, utimesSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { delimiter } from "node:path";
+import { dirname, join } from "node:path";
+
+function assertSelfTest(condition, message) {
+	if (!condition) throw new Error(`self-test failed: ${message}`);
+}
+
+function envMap(assignments) {
+	return new Map(assignments.map(([name, value]) => [name, value]));
+}
+
+function parseEnvCapture(path) {
+	return new Map(
+		readFileSync(path, "utf8")
+			.split("\n")
+			.filter(Boolean)
+			.map((line) => {
+				const index = line.indexOf("=");
+				return index === -1 ? [line, ""] : [line.slice(0, index), line.slice(index + 1)];
+			}),
+	);
+}
+
+export function runVisualSmokeSelfTest(deps) {
+	const { ROOT, DEFAULT_MODE, DEFAULT_MODEL, DEFAULT_SETTING_SOURCES, DEBUG_ENV_NAMES, shellQuote, parseArgs, snapshotJsonlMtimes, findLatestJsonl, sealedNodePath, resolveCommand, requireNode, requireCommand, buildLaunchPlan, run, runVisualSmoke } = deps;
+	const tempDir = mkdtempSync(join(tmpdir(), "pi-cursor-sdk-visual-self-test-"));
+	try {
+		const binDir = join(tempDir, "bin");
+		mkdirSync(binDir, { recursive: true });
+		const fakePi = join(binDir, "pi");
+		const fakeNode = join(binDir, "node");
+		const fakeNodeMarker = join(tempDir, "fake-node-used");
+		const envCapture = join(tempDir, "fake-pi.env");
+		writeFileSync(
+			fakePi,
+			`#!/usr/bin/env node\nconst { writeFileSync } = require("node:fs");\nwriteFileSync(${JSON.stringify(envCapture)}, Object.entries(process.env).map(([key, value]) => key + "=" + (value ?? "")).join("\\n") + "\\n", "utf8");\n`,
+			"utf8",
+		);
+		writeFileSync(fakeNode, `#!/bin/sh\necho fake-node-used > ${shellQuote(fakeNodeMarker)}\nexit 99\n`, "utf8");
+		chmodSync(fakePi, 0o755);
+		chmodSync(fakeNode, 0o755);
+
+		const promptFile = join(tempDir, "prompt.txt");
+		writeFileSync(promptFile, "file prompt", "utf8");
+		assertSelfTest(parseArgs(["--label", "prompt-order", "--prompt-file", promptFile, "--prompt", "inline prompt"]).prompt === "inline prompt", "--prompt should override an earlier --prompt-file");
+		assertSelfTest(parseArgs(["--label", "prompt-dash", "--prompt", "--starts-with-dash"]).prompt === "--starts-with-dash", "--prompt should accept dash-prefixed free-form text");
+		assertSelfTest(parseArgs(["--label", "prompt-order", "--prompt", "inline prompt", "--prompt-file", promptFile]).prompt === "file prompt", "--prompt-file should override an earlier --prompt");
+
+		const jsonlDir = join(tempDir, "jsonl-filter");
+		mkdirSync(jsonlDir, { recursive: true });
+		const staleJsonl = join(jsonlDir, "stale.jsonl");
+		const freshJsonl = join(jsonlDir, "fresh.jsonl");
+		writeFileSync(staleJsonl, "{}\n", "utf8");
+		utimesSync(staleJsonl, new Date(1_000), new Date(1_000));
+		const previousJsonlMtimes = snapshotJsonlMtimes(jsonlDir);
+		writeFileSync(freshJsonl, "{}\n", "utf8");
+		utimesSync(freshJsonl, new Date(3_000), new Date(3_000));
+		assertSelfTest(findLatestJsonl(jsonlDir, { sinceMs: 2_000, previousMtimes: previousJsonlMtimes }) === freshJsonl, "JSONL discovery should ignore unchanged stale files before run start");
+		assertSelfTest(findLatestJsonl(jsonlDir, { sinceMs: 4_000, previousMtimes: snapshotJsonlMtimes(jsonlDir) }) === undefined, "JSONL discovery should not return stale evidence when current run has no changed JSONL");
+
+		assertSelfTest(!sealedNodePath(process.execPath, "").includes(delimiter), "empty inherited PATH must not leave an empty PATH segment");
+		const hostilePath = `${binDir}${delimiter}${process.env.PATH ?? ""}`;
+		const sealedHostilePath = sealedNodePath(process.execPath, hostilePath);
+		assertSelfTest(resolveCommand("pi", hostilePath) === fakePi, "direct PATH resolver did not prefer fake PATH head");
+		assertSelfTest(requireNode() === process.execPath, "node resolver must use process.execPath");
+		assertSelfTest(requireCommand("pi", { envPath: hostilePath, env: { ...process.env, PATH: sealedHostilePath } }) === fakePi, "pi prereq should use sealed PATH when executing the shim");
+		assertSelfTest(!existsSync(fakeNodeMarker), "pi prereq should not use hostile fake node");
+
+		const baseOptions = {
+			ext: ROOT,
+			cwd: ROOT,
+			mode: DEFAULT_MODE,
+			model: DEFAULT_MODEL,
+			outDir: tempDir,
+			safeLabel: "self-test",
+			sessionDir: join(tempDir, "session"),
+			sessionId: "self-test",
+			settingSources: DEFAULT_SETTING_SOURCES,
+			bridge: false,
+			exposeBuiltinTools: false,
+			eventDebug: false,
+		};
+		const plan = buildLaunchPlan(baseOptions, { pi: fakePi, node: process.execPath, sealedPath: sealedHostilePath }, "/bin/sh");
+		const defaults = envMap(plan.envAssignments);
+		assertSelfTest(defaults.get("PI_CURSOR_NATIVE_TOOL_DISPLAY") === "1", "native display must be forced on");
+		assertSelfTest(defaults.get("PI_CURSOR_REGISTER_NATIVE_TOOLS") === "1", "native tool registration must be forced on");
+		assertSelfTest(defaults.get("PI_CURSOR_SETTING_SOURCES") === "none", "setting sources must default to none");
+		assertSelfTest(defaults.get("PI_CURSOR_PI_TOOL_BRIDGE") === "0", "bridge must default off");
+		assertSelfTest(defaults.get("PI_CURSOR_EXPOSE_BUILTIN_TOOLS") === "0", "built-in exposure must default off");
+		for (const name of DEBUG_ENV_NAMES) {
+			assertSelfTest(plan.clearEnvNames.includes(name), `${name} must be cleared by default`);
+		}
+		assertSelfTest(plan.script.includes(shellQuote(fakePi)), "launch script must use resolved pi path");
+		assertSelfTest(!plan.script.includes(" exec pi "), "launch script must not use bare pi");
+		const hostileEnv = {
+			...process.env,
+			...Object.fromEntries(DEBUG_ENV_NAMES.map((name) => [name, join(tempDir, name)])),
+			PATH: hostilePath,
+			PI_CURSOR_REGISTER_NATIVE_TOOLS: "0",
+			PI_CURSOR_SETTING_SOURCES: "all",
+			PI_CURSOR_PI_TOOL_BRIDGE: "1",
+			PI_CURSOR_EXPOSE_BUILTIN_TOOLS: "1",
+		};
+		const probe = run("/bin/sh", ["-c", plan.script], { env: hostileEnv });
+		assertSelfTest(probe.status === 0, `fake-pi env capture exited ${probe.status}: ${probe.stderr?.toString() ?? ""}`);
+		const capturedEnv = parseEnvCapture(envCapture);
+		assertSelfTest(!existsSync(fakeNodeMarker), "launch PATH should force the resolved node before hostile fake node");
+		assertSelfTest((capturedEnv.get("PATH") ?? "").split(delimiter)[0] === dirname(process.execPath), "captured PATH should start with resolved node directory");
+		assertSelfTest(capturedEnv.get("PI_CURSOR_NATIVE_TOOL_DISPLAY") === "1", "captured env should force native display on");
+		assertSelfTest(capturedEnv.get("PI_CURSOR_REGISTER_NATIVE_TOOLS") === "1", "captured env should force native registration on");
+		assertSelfTest(capturedEnv.get("PI_CURSOR_SETTING_SOURCES") === "none", "captured env should force settings off");
+		assertSelfTest(capturedEnv.get("PI_CURSOR_PI_TOOL_BRIDGE") === "0", "captured env should force bridge off");
+		assertSelfTest(capturedEnv.get("PI_CURSOR_EXPOSE_BUILTIN_TOOLS") === "0", "captured env should force built-in exposure off");
+		for (const name of DEBUG_ENV_NAMES) {
+			assertSelfTest(!capturedEnv.has(name), `${name} should be absent from captured env by default`);
+		}
+
+		const optInPlan = buildLaunchPlan(
+			{ ...baseOptions, settingSources: "all", bridge: true, exposeBuiltinTools: true, eventDebug: true },
+			{ pi: fakePi, node: process.execPath, sealedPath: sealedHostilePath },
+			"/bin/sh",
+		);
+		const optIns = envMap(optInPlan.envAssignments);
+		assertSelfTest(optIns.get("PI_CURSOR_SETTING_SOURCES") === "all", "setting source opt-in must be reflected");
+		assertSelfTest(optIns.get("PI_CURSOR_PI_TOOL_BRIDGE") === "1", "bridge opt-in must be reflected");
+		assertSelfTest(optIns.get("PI_CURSOR_EXPOSE_BUILTIN_TOOLS") === "1", "built-in exposure opt-in must be reflected");
+		assertSelfTest(optIns.get("PI_CURSOR_SDK_EVENT_DEBUG") === "1", "event debug opt-in must be reflected");
+		assertSelfTest(optIns.get("PI_CURSOR_SDK_EVENT_DEBUG_DIR") === join(tempDir, "self-test.cursor-sdk-events"), "event debug dir must be deterministic under out-dir");
+		for (const name of DEBUG_ENV_NAMES) {
+			assertSelfTest(optInPlan.clearEnvNames.includes(name), `${name} must be cleared even when event debug is explicit`);
+		}
+		const eventDebugProbe = run("/bin/sh", ["-c", optInPlan.script], { env: hostileEnv });
+		assertSelfTest(eventDebugProbe.status === 0, `fake-pi event-debug env capture exited ${eventDebugProbe.status}: ${eventDebugProbe.stderr?.toString() ?? ""}`);
+		const capturedEventDebugEnv = parseEnvCapture(envCapture);
+		assertSelfTest(capturedEventDebugEnv.get("PI_CURSOR_SDK_EVENT_DEBUG") === "1", "event debug should be explicitly enabled");
+		assertSelfTest(capturedEventDebugEnv.get("PI_CURSOR_SDK_EVENT_DEBUG_DIR") === join(tempDir, "self-test.cursor-sdk-events"), "event debug dir should be deterministic under out-dir");
+		assertSelfTest(!capturedEventDebugEnv.has("PI_CURSOR_SDK_EVENT_DEBUG_RUN_DIR"), "stale event debug run dir should be cleared");
+		assertSelfTest(!capturedEventDebugEnv.has("PI_CURSOR_SDK_EVENT_DEBUG_SESSION_DIR"), "stale event debug session dir should be cleared");
+		assertSelfTest(!capturedEventDebugEnv.has("PI_CURSOR_SDK_EVENT_DEBUG_STDERR"), "stale event debug stderr flag should be cleared");
+
+		const fakeTmux = join(binDir, "tmux");
+		const deleteBufferMarker = join(tempDir, "delete-buffer-called");
+		writeFileSync(
+			fakeTmux,
+			`#!/bin/sh\ncase "$1" in\n  -V) echo 'tmux fake'; exit 0 ;;\n  new-session) exit 0 ;;\n  load-buffer) cat >/dev/null; exit 0 ;;\n  paste-buffer) exit 77 ;;\n  delete-buffer) echo deleted > ${shellQuote(deleteBufferMarker)}; exit 0 ;;\n  kill-session) exit 0 ;;\n  *) echo "unexpected tmux command: $*" >&2; exit 64 ;;\nesac\n`,
+			"utf8",
+		);
+		chmodSync(fakeTmux, 0o755);
+		const originalPath = process.env.PATH;
+		try {
+			process.env.PATH = hostilePath;
+			let pasteFailed = false;
+			try {
+				runVisualSmoke({
+					...baseOptions,
+					prompt: "buffer cleanup prompt",
+					startupMs: 1,
+					waitMs: 1,
+					width: 80,
+					height: 24,
+					historyLines: 100,
+				});
+			} catch (error) {
+				pasteFailed = /paste-buffer failed/.test(error instanceof Error ? error.message : String(error));
+			}
+			assertSelfTest(pasteFailed, "fake tmux paste failure should exercise prompt-buffer cleanup path");
+			assertSelfTest(existsSync(deleteBufferMarker), "prompt tmux buffer should be deleted when paste/send fails");
+		} finally {
+			if (originalPath === undefined) delete process.env.PATH;
+			else process.env.PATH = originalPath;
+		}
+
+		writeFileSync(
+			fakeTmux,
+			`#!/bin/sh
+case "$1" in
+  -V) echo 'tmux fake'; exit 0 ;;
+  new-session) exit 0 ;;
+  load-buffer) cat >/dev/null; exit 0 ;;
+  paste-buffer) exit 0 ;;
+  send-keys) exit 0 ;;
+  delete-buffer) exit 0 ;;
+  capture-pane) echo 'captured visual smoke output'; exit 0 ;;
+  kill-session) exit 0 ;;
+  *) echo "unexpected tmux command: $*" >&2; exit 64 ;;
+esac
+`,
+			"utf8",
+		);
+		chmodSync(fakeTmux, 0o755);
+		const noJsonlManifest = join(tempDir, "self-test-jsonl-missing.manifest.json");
+		try {
+			process.env.PATH = hostilePath;
+			let missingJsonlFailed = false;
+			let missingJsonlError = "";
+			try {
+				runVisualSmoke({
+					...baseOptions,
+					label: "self-test-jsonl-missing",
+					safeLabel: "self-test-jsonl-missing",
+					prompt: "jsonl failure prompt",
+					startupMs: 1,
+					waitMs: 1,
+					width: 80,
+					height: 24,
+					historyLines: 100,
+					sessionDir: join(tempDir, "missing-jsonl-session"),
+				});
+			} catch (error) {
+				missingJsonlError = error instanceof Error ? error.message : String(error);
+				missingJsonlFailed = /no current-run persisted \.jsonl/.test(missingJsonlError);
+			}
+			assertSelfTest(missingJsonlFailed, `missing JSONL should fail after partial visual artifacts are written: ${missingJsonlError || "no error"}`);
+			assertSelfTest(existsSync(noJsonlManifest), "missing JSONL should still write a failure manifest");
+			const manifest = JSON.parse(readFileSync(noJsonlManifest, "utf8"));
+			assertSelfTest(manifest.failure?.message?.includes("no current-run persisted .jsonl"), "failure manifest should record the missing JSONL reason");
+			assertSelfTest(manifest.paths?.html?.endsWith("self-test-jsonl-missing.html"), "failure manifest should point at partial HTML evidence");
+		} finally {
+			if (originalPath === undefined) delete process.env.PATH;
+			else process.env.PATH = originalPath;
+		}
+		console.log("[visual-smoke] self-test PASS");
+	} finally {
+		rmSync(tempDir, { recursive: true, force: true });
+	}
+}
+