pi-cursor-sdk 0.1.40 → 0.1.42

package/scripts/platform-smoke/artifacts.mjs

@@ -2,12 +2,13 @@
  * Artifact management — directory layout, manifest, redaction scanning, packaging.
  */
 
-import { mkdirSync, writeFileSync, readFileSync, readdirSync, existsSync, rmSync } from "node:fs";
-import { resolve, relative, basename } from "node:path";
+import { mkdirSync, writeFileSync, readFileSync, readdirSync, existsSync, rmSync, renameSync } from "node:fs";
+import { resolve, relative, basename, dirname } from "node:path";
 
 const PLATFORM_SMOKE_RUN_DIR_PATTERN = /^run-(\d+)-[a-z0-9]+$/i;
 const HOURS_TO_MS = 60 * 60 * 1000;
 const DAYS_TO_MS = 24 * HOURS_TO_MS;
+const LATEST_INDEX_NAME = "latest.json";
 
 function finiteNonNegativeNumber(value) {
 	return typeof value === "number" && Number.isFinite(value) && value >= 0;
@@ -178,6 +179,150 @@ export function writeSummary(dir, data) {
 	}, null, 2));
 }
 
+function readJsonFile(path) {
+	try {
+		return JSON.parse(readFileSync(path, "utf8"));
+	} catch {
+		return undefined;
+	}
+}
+
+function collectFiles(root) {
+	const files = [];
+	function walk(dir) {
+		let entries;
+		try {
+			entries = readdirSync(dir, { withFileTypes: true });
+		} catch {
+			return;
+		}
+		for (const entry of entries) {
+			const path = resolve(dir, entry.name);
+			if (entry.isDirectory()) walk(path);
+			else if (entry.isFile()) files.push(path);
+		}
+	}
+	if (existsSync(root)) walk(root);
+	files.sort();
+	return files;
+}
+
+function existingPath(path) {
+	return existsSync(path) ? path : undefined;
+}
+
+function providerDebugPathFields(debugRoot) {
+	if (!existsSync(debugRoot)) return {};
+	const providerDebugArtifacts = collectFiles(debugRoot);
+	const keyArtifacts = providerDebugArtifacts.filter((path) => /(?:^|[\\/])(?:session|summary|timeline|provider-events|bridge-events|wait-result)\.(?:json|jsonl)$/i.test(path));
+	const capped = keyArtifacts.slice(0, 40);
+	return {
+		providerDebugRoot: debugRoot,
+		providerDebugArtifactCount: providerDebugArtifacts.length,
+		providerDebugArtifacts: capped,
+		...(providerDebugArtifacts.length > capped.length ? { providerDebugArtifactsTruncated: true } : {}),
+	};
+}
+
+function pathFields(suiteDir) {
+	const artifactsDir = resolve(suiteDir, "artifacts");
+	const debugRoot = resolve(suiteDir, "cursor-sdk-events");
+	const paths = {
+		artifactManifest: existingPath(resolve(suiteDir, "artifact-manifest.json")),
+		summary: existingPath(resolve(suiteDir, "summary.json")),
+		assertions: existingPath(resolve(suiteDir, "assertions.json")),
+		failures: existingPath(resolve(suiteDir, "failures.md")),
+		terminalHtml: existingPath(resolve(artifactsDir, "terminal.html")),
+		terminalFullPng: existingPath(resolve(artifactsDir, "terminal.full.png")),
+		terminalFinalViewportPng: existingPath(resolve(artifactsDir, "terminal.final-viewport.png")),
+		visualEvidence: existingPath(resolve(artifactsDir, "visual-evidence.json")),
+		sessionJsonl: existingPath(resolve(artifactsDir, "session.jsonl")),
+		jsonlToolResults: existingPath(resolve(artifactsDir, "jsonl-tool-results.json")),
+		...providerDebugPathFields(debugRoot),
+	};
+	for (const [key, value] of Object.entries(paths)) {
+		if (value === undefined) delete paths[key];
+	}
+	return paths;
+}
+
+function suiteIndexFromResult(result, artifactRoot) {
+	if (!result?.suiteDir) return undefined;
+	const suiteDir = resolve(result.suiteDir);
+	const summary = readJsonFile(resolve(suiteDir, "summary.json"));
+	const target = readJsonFile(resolve(suiteDir, "target.json"));
+	const suite = readJsonFile(resolve(suiteDir, "suite.json"));
+	const rel = relative(resolve(process.cwd(), artifactRoot), suiteDir).split(/[\\/]/);
+	return {
+		target: summary?.target ?? target?.targetName ?? rel.at(-2),
+		suite: summary?.suite ?? suite?.suiteName ?? rel.at(-1),
+		runId: target?.runId ?? rel.at(-3),
+		ok: result.ok === true,
+		artifactDir: suiteDir,
+		paths: pathFields(suiteDir),
+	};
+}
+
+function targetIndexesFromRun(targetName, result, artifactRoot) {
+	const suiteResults = Array.isArray(result?.results) ? result.results : [result];
+	const suites = suiteResults.map((suiteResult) => suiteIndexFromResult(suiteResult, artifactRoot)).filter(Boolean);
+	const runIds = [...new Set(suites.map((suite) => suite.runId).filter(Boolean))];
+	return {
+		target: targetName,
+		ok: result?.ok === true,
+		...(result?.error ? { error: redactSecrets(result.error) } : {}),
+		runId: runIds.length === 1 ? runIds[0] : undefined,
+		runIds,
+		suites,
+	};
+}
+
+/** Build a stable, agent-readable platform-smoke latest index from target run results. */
+export function buildLatestPlatformSmokeIndex(config, runResults, metadata = {}) {
+	const artifactRoot = resolve(process.cwd(), config?.artifactRoot ?? ".artifacts/platform-smoke");
+	const targets = runResults.map(({ targetName, result }) => targetIndexesFromRun(targetName, result, artifactRoot));
+	const runIds = [...new Set(targets.flatMap((target) => target.runIds).filter(Boolean))].sort();
+	const newestRunId = runIds
+		.map((runId) => ({ runId, match: PLATFORM_SMOKE_RUN_DIR_PATTERN.exec(runId) }))
+		.filter((entry) => entry.match)
+		.sort((a, b) => Number(b.match[1]) - Number(a.match[1]))[0]?.runId ?? runIds.at(-1);
+	return {
+		schemaVersion: 1,
+		kind: "platform-smoke-latest",
+		runId: runIds.length === 1 ? runIds[0] : newestRunId,
+		runIds,
+		artifactRoot,
+		startedAt: metadata.startedAt,
+		finishedAt: metadata.finishedAt,
+		command: metadata.command,
+		pid: process.pid,
+		ok: targets.every((target) => target.ok),
+		targets,
+	};
+}
+
+/** Atomically write .artifacts/platform-smoke/latest.json. */
+export function writeLatestPlatformSmokeIndex(config, runResults, metadata = {}) {
+	const index = buildLatestPlatformSmokeIndex(config, runResults, metadata);
+	mkdirSync(index.artifactRoot, { recursive: true });
+	const outPath = resolve(index.artifactRoot, LATEST_INDEX_NAME);
+	const tmpPath = resolve(dirname(outPath), `.${LATEST_INDEX_NAME}.${process.pid}.${Date.now()}.tmp`);
+	writeFileSync(tmpPath, `${JSON.stringify(index, null, 2)}\n`);
+	renameSync(tmpPath, outPath);
+	return { index, path: outPath };
+}
+
+/** Return concise existing evidence paths for a failed suite result. */
+export function platformSmokeSuiteEvidence(result, artifactRoot) {
+	const suite = suiteIndexFromResult(result, artifactRoot ?? ".artifacts/platform-smoke");
+	if (!suite) return undefined;
+	return {
+		suite: suite.suite,
+		artifactDir: suite.artifactDir,
+		paths: suite.paths,
+	};
+}
+
 /** Write command.txt recording the command that was executed. */
 export function writeCommand(dir, cmd) {
 	writeFileSync(resolve(dir, "command.txt"), Array.isArray(cmd) ? cmd.join(" ") + "\n" : cmd + "\n");

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

@@ -18,7 +18,7 @@ const CARD_PATTERNS = [
 	{ id: "write", pattern: /^\s*\+.*beta\s*$/i },
 	{ id: "edit-diff", pattern: /^\s*\+.*gamma\s*$/i },
 	{ id: "shell-failure", pattern: /^\s*(?:native shell failure|Command exited with code 7)\s*$/i },
-	{ id: "bridge-read-success", pattern: /^\s*read \.\/package\.json\s*$/i },
+	{ id: "bridge-read-success", pattern: /^\s*read (?:\.\/package\.json|.*[\\/]package\.json)\s*$/i },
 	{ id: "bridge-read-failure", pattern: /^\s*(?:read \.\/definitely-missing-platform-smoke-file\.txt|ENOENT: no such file)\s*/i },
 	{ id: "bridge-shell-success", pattern: /^\s*bridge visual smoke\s*$/i },
 	{ id: "footer-status", pattern: /\bcomposer-2-5\b|\bcomposer-2\.5\b/i },

package/scripts/platform-smoke/doctor.mjs

@@ -7,8 +7,9 @@
  */
 
 import { execSync, execFileSync } from "node:child_process";
-import { accessSync, constants, existsSync, mkdirSync, writeFileSync, unlinkSync } from "node:fs";
+import { accessSync, constants, existsSync, mkdirSync, writeFileSync, unlinkSync, rmSync, statSync } from "node:fs";
 import { dirname, resolve } from "node:path";
+import { renderAll } from "./render-ansi.mjs";
 
 let failures = 0;
 
@@ -126,6 +127,41 @@ function disposableWindowsSshProbe(cbox, config = {}) {
 
 function hasBin(name) { return silent("which", [name]) !== null; }
 
+async function runRenderProbe(artifactRoot) {
+	const probeDir = resolve(artifactRoot, `.doctor-render-${process.pid}-${Date.now()}`);
+	try {
+		mkdirSync(probeDir, { recursive: true });
+		const ansiPath = resolve(probeDir, "terminal.ansi");
+		writeFileSync(ansiPath, "\u001b[32mplatform smoke render probe\u001b[0m\n");
+		const rendered = await renderAll(ansiPath, probeDir, {
+			label: "doctor-render-probe",
+			model: "doctor",
+			mode: "doctor",
+			cwd: process.cwd(),
+			sessionId: "doctor-render-probe",
+			width: 80,
+			height: 10,
+			historyLines: 100,
+		});
+		const pngPath = resolve(probeDir, "terminal.full.png");
+		const pngOk = rendered.pngOk && existsSync(pngPath) && statSync(pngPath).size > 100;
+		if (!pngOk) {
+			return {
+				ok: false,
+				message: `host-side xterm/Playwright render probe did not produce a PNG at ${pngPath}. Run: npx playwright install chromium`,
+			};
+		}
+		return { ok: true, message: pngPath };
+	} catch (error) {
+		return {
+			ok: false,
+			message: `host-side xterm/Playwright render probe failed: ${error instanceof Error ? error.message : String(error)}. Run npm install, then: npx playwright install chromium`,
+		};
+	} finally {
+		rmSync(probeDir, { recursive: true, force: true });
+	}
+}
+
 function findGitRoot(startPath) {
 	let dir = startPath;
 	for (let i = 0; i < 8; i++) {
@@ -137,7 +173,7 @@ function findGitRoot(startPath) {
 	return null;
 }
 
-function runChecks(config) {
+async function runChecks(config) {
 	// ── Phase 1: environment variables ──
 	console.log("\n── Environment variables ──");
 	const requiredVars = [
@@ -396,7 +432,16 @@ function runChecks(config) {
 		fail(`cannot write to ${artRoot}: ${e.message}`);
 	}
 
-	// ── Phase 10: Git status ──
+	// ── Phase 10: Host-side visual render probe ──
+	console.log("\n── Host-side visual render probe ──");
+	const renderProbe = await runRenderProbe(artRoot);
+	if (renderProbe.ok) {
+		ok("xterm/Playwright Chromium render probe wrote a PNG");
+	} else {
+		fail(renderProbe.message);
+	}
+
+	// ── Phase 11: Git status ──
 	console.log("\n── Git status ──");
 	const branch = shell("git branch --show-current");
 	branch ? ok(`branch: ${branch}`) : warn("could not determine branch");
@@ -408,7 +453,7 @@ function runChecks(config) {
 		ok("clean worktree");
 	}
 
-	// ── Phase 11: Forbidden files ──
+	// ── Phase 12: Forbidden files ──
 	console.log("\n── Forbidden files ──");
 	let anyForbidden = false;
 	for (const pat of [".env", "*.tgz"]) {
@@ -428,7 +473,7 @@ function runChecks(config) {
 	}
 	ok("no tracked .env.*");
 
-	// ── Phase 12: Cursor auth ──
+	// ── Phase 13: Cursor auth ──
 	console.log("\n── Cursor auth ──");
 	const key = env("CURSOR_API_KEY");
 	if (key && key.length > 10) {
@@ -439,7 +484,7 @@ function runChecks(config) {
 		fail("CURSOR_API_KEY missing — live Cursor suites will not run");
 	}
 
-	// ── Phase 13: node-pty self-test ──
+	// ── Phase 14: node-pty self-test ──
 	console.log("\n── node-pty self-test ──");
 	const ptyPath = resolve(process.cwd(), "node_modules", "node-pty");
 	if (existsSync(ptyPath)) {
@@ -458,7 +503,7 @@ function runChecks(config) {
 		warn("node-pty not installed — live PTY suites will not run. Run: npm ci");
 	}
 
-	// ── Phase 14: Summary ──
+	// ── Phase 15: Summary ──
 	console.log(`\n=== Results: ${failures} failure(s) ===`);
 	if (failures > 0) {
 		console.log("Fix failures above before running live Cursor suites.");
@@ -470,5 +515,5 @@ function runChecks(config) {
 }
 
 export async function runDoctor(config) {
-	runChecks(config);
+	await runChecks(config);
 }

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.mjs

@@ -3,9 +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 { prunePlatformSmokeArtifacts } from "./platform-smoke/artifacts.mjs";
+import { platformSmokeSuiteEvidence, prunePlatformSmokeArtifacts, redactSecrets, writeLatestPlatformSmokeIndex } from "./platform-smoke/artifacts.mjs";
 
 // ── helpers ────────────────────────────────────────────────────────────────
 const __filename = fileURLToPath(import.meta.url);
@@ -104,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 {
@@ -125,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 };
 	}
 }
 
@@ -135,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 };
 	}
 }
 
@@ -179,6 +228,7 @@ async function main() {
 			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
@@ -187,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/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 });
+	}
+}
+