pi-cursor-sdk 0.1.19 → 0.1.21

package/scripts/probe-mcp-coldstart.mjs

@@ -0,0 +1,226 @@
+#!/usr/bin/env node
+/**
+ * Maintainer probe: measure Cursor SDK cold-start timing with/without ambient MCP settings
+ * and with the pi-cursor-sdk MCP connect timeout override installed.
+ */
+import { spawn } from "node:child_process";
+import { performance } from "node:perf_hooks";
+import { fileURLToPath } from "node:url";
+import {
+	installCursorMcpToolTimeoutOverride,
+	restoreCursorMcpToolTimeoutOverride,
+} from "../src/cursor-mcp-timeout-override.ts";
+import { apiKeySecretsFromProcess, defaultApiKeyFromEnv, parseArgv } from "./lib/cursor-cli-args.mjs";
+import { scrubSensitiveText } from "../shared/cursor-sensitive-text.mjs";
+import { createScriptFail } from "./lib/cursor-script-fail.mjs";
+import { installCursorSdkOutputFilter, suppressCursorSdkOutput } from "./lib/cursor-sdk-output-filter.mjs";
+
+const SCRIPT_PATH = fileURLToPath(import.meta.url);
+const SCENARIOS = [
+	{ label: "with-all-settings", settingSources: ["all"] },
+	{ label: "with-all-settings+connect-override", settingSources: ["all"], installConnectOverride: true },
+	{ label: "no-setting-sources", settingSources: undefined },
+];
+
+function printHelp() {
+	console.log(`Measure Cursor SDK first-send MCP cold-start timing.
+
+Usage:
+  CURSOR_API_KEY=... npm run debug:mcp-coldstart
+  node scripts/probe-mcp-coldstart.mjs [options]
+
+Options:
+  --api-key <key>     Cursor API key. Prefer CURSOR_API_KEY to avoid shell history.
+  --scenario <label>  Run one scenario in this process. Used by the orchestrator.
+  -h, --help          Show this help without importing or calling the Cursor SDK.
+
+Stdout:
+  Emits one JSON object per scenario. Human status lines go to stderr.
+
+Scenarios:
+  with-all-settings                   Cursor settingSources=["all"]
+  with-all-settings+connect-override  Same, with pi-cursor-sdk timeout override installed
+  no-setting-sources                  No explicit settingSources
+
+Safety:
+  - --help never performs live Cursor calls.
+  - Each default scenario runs in a fresh child process before its first Cursor SDK import.
+  - SDK startup noise is suppressed.
+  - Error messages are scrubbed for API keys, bearer tokens, cookies, and bridge endpoints.`);
+}
+
+const exitWithFailure = createScriptFail("probe-mcp-coldstart");
+
+function fail(message, secrets) {
+	const secretList = secrets === undefined ? [] : Array.isArray(secrets) ? secrets : [secrets];
+	exitWithFailure(message, secretList.filter(Boolean));
+}
+
+function findScenario(label) {
+	return SCENARIOS.find((scenario) => scenario.label === label);
+}
+
+function parseArgs(argv, env = process.env) {
+	const args = parseArgv(argv, {
+		defaults: {
+			apiKey: defaultApiKeyFromEnv(env),
+			scenario: undefined,
+		},
+		flags: {
+			apiKey: { names: ["--api-key"], assign: (value) => value.trim() },
+			scenario: { names: ["--scenario"], assign: (value) => value.trim() },
+		},
+		fail: (message) => fail(message, defaultApiKeyFromEnv(env)),
+	});
+	if (args.scenario && !findScenario(args.scenario)) {
+		fail(`unknown scenario: ${args.scenario}`, args.apiKey);
+	}
+	return args;
+}
+
+async function probe(Agent, apiKey, label, { settingSources, installConnectOverride = false } = {}) {
+	let agent;
+	try {
+		const marks = [];
+		const t0 = performance.now();
+		const mark = (name) => marks.push({ name, ms: Math.round(performance.now() - t0) });
+
+		mark("start");
+		agent = await suppressCursorSdkOutput(() =>
+			Agent.create({
+				apiKey,
+				model: { id: "composer-2.5" },
+				local: settingSources
+					? { cwd: process.cwd(), settingSources }
+					: { cwd: process.cwd() },
+			}),
+		);
+		mark("agent.create");
+
+		let firstDeltaMs;
+		const run = await suppressCursorSdkOutput(() =>
+			agent.send("Reply with exactly: pong", {
+				onDelta: ({ update }) => {
+					if (firstDeltaMs === undefined && update.type === "text-delta") {
+						firstDeltaMs = Math.round(performance.now() - t0);
+						mark("first-delta");
+					}
+				},
+			}),
+		);
+		mark("agent.send-returned");
+
+		const result = await suppressCursorSdkOutput(() => run.wait());
+		mark("run.wait");
+
+		await suppressCursorSdkOutput(() => agent[Symbol.asyncDispose]());
+		agent = undefined;
+		mark("dispose");
+
+		const sendReturnedMs = marks.find((entry) => entry.name === "agent.send-returned")?.ms;
+		const mcpBlockingMs =
+			firstDeltaMs !== undefined && sendReturnedMs !== undefined ? firstDeltaMs - sendReturnedMs : undefined;
+
+		return {
+			label,
+			settingSources: settingSources ?? null,
+			installConnectOverride,
+			marks,
+			firstDeltaMs,
+			mcpBlockingMs,
+			status: result.status,
+			text: typeof result.result === "string" ? result.result.slice(0, 120) : null,
+		};
+	} finally {
+		if (agent) {
+			await suppressCursorSdkOutput(() => agent[Symbol.asyncDispose]()).catch(() => undefined);
+		}
+	}
+}
+
+async function runScenarioInThisProcess(args, scenario) {
+	const restoreOutputFilter = installCursorSdkOutputFilter();
+	try {
+		if (scenario.installConnectOverride) {
+			const state = installCursorMcpToolTimeoutOverride();
+			console.error(
+				`probe-mcp-coldstart: installed connect override (${state.connectTimeoutMs}ms initialize/listTools, ${state.timeoutMs}ms callTool)`,
+			);
+		}
+		const { Agent } = await suppressCursorSdkOutput(() => import("@cursor/sdk"));
+		console.log(JSON.stringify(await probe(Agent, args.apiKey, scenario.label, scenario)));
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		console.log(
+			JSON.stringify({
+				label: scenario.label,
+				error: scrubSensitiveText(message, args.apiKey),
+			}),
+		);
+	} finally {
+		restoreCursorMcpToolTimeoutOverride();
+		restoreOutputFilter();
+	}
+}
+
+function runScenarioChild(args, scenario) {
+	return new Promise((resolve) => {
+		const child = spawn(process.execPath, [SCRIPT_PATH, "--scenario", scenario.label], {
+			cwd: process.cwd(),
+			env: { ...process.env, CURSOR_API_KEY: args.apiKey },
+			stdio: ["ignore", "pipe", "pipe"],
+		});
+		let stdout = "";
+		let stderr = "";
+
+		child.stdout.on("data", (chunk) => {
+			stdout += chunk;
+		});
+		child.stderr.on("data", (chunk) => {
+			stderr += chunk;
+		});
+		child.on("error", (error) => {
+			stderr += error instanceof Error ? error.message : String(error);
+		});
+		child.on("close", (code) => {
+			const scrubbedStderr = scrubSensitiveText(stderr, args.apiKey);
+			if (scrubbedStderr) process.stderr.write(scrubbedStderr.endsWith("\n") ? scrubbedStderr : `${scrubbedStderr}\n`);
+			if (code === 0 && stdout.trim()) {
+				process.stdout.write(stdout.endsWith("\n") ? stdout : `${stdout}\n`);
+				resolve();
+				return;
+			}
+			const error = scrubbedStderr.trim() || `child process exited with code ${code ?? "unknown"}`;
+			console.log(JSON.stringify({ label: scenario.label, error }));
+			resolve();
+		});
+	});
+}
+
+async function main(argv = process.argv.slice(2), env = process.env) {
+	const args = parseArgs(argv, env);
+	if (args.help) {
+		printHelp();
+		return;
+	}
+	if (!args.apiKey) {
+		fail("CURSOR_API_KEY is required. Set CURSOR_API_KEY or pass --api-key.");
+	}
+
+	const scenario = args.scenario ? findScenario(args.scenario) : undefined;
+	if (scenario) {
+		await runScenarioInThisProcess(args, scenario);
+		return;
+	}
+
+	for (const scenarioToRun of SCENARIOS) {
+		await runScenarioChild(args, scenarioToRun);
+	}
+}
+
+if (import.meta.url === new URL(process.argv[1], "file:").href) {
+	main().catch((error) => {
+		const message = error instanceof Error ? error.message : String(error);
+		fail(message, apiKeySecretsFromProcess());
+	});
+}

package/scripts/refresh-cursor-model-snapshots.mjs

@@ -1,7 +1,9 @@
 #!/usr/bin/env node
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
-import { basename, resolve } from "node:path";
 import { Cursor } from "@cursor/sdk";
+import { defaultApiKeyFromEnv, parseArgv } from "./lib/cursor-cli-args.mjs";
+import { scrubSensitiveText } from "../shared/cursor-sensitive-text.mjs";
+import { createScriptFail } from "./lib/cursor-script-fail.mjs";
 
 const FALLBACK_MODELS_PATH = "src/cursor-fallback-models.generated.ts";
 const CONTEXT_WINDOWS_PATH = "src/bundled-context-windows.ts";
@@ -38,70 +40,32 @@ Notes:
     requires successful local SDK runs; this script does not start agents.`);
 }
 
-function fail(message) {
-	console.error(`refresh-cursor-snapshots: ${message}`);
-	process.exit(1);
-}
+const fail = createScriptFail("refresh-cursor-snapshots");
 
-function scrubSensitiveText(text, secrets = []) {
-	let scrubbed = text;
-	for (const secret of secrets) {
-		if (secret) scrubbed = scrubbed.split(secret).join("[REDACTED]");
-	}
-	return scrubbed
-		.replace(/Bearer\s+[A-Za-z0-9._~+/=-]+/gi, "Bearer [REDACTED]")
-		.replace(/(api[_-]?key|authorization|auth[_-]?token)([\"'\s:=]+)[^\"'\s,}]+/gi, "$1$2[REDACTED]");
-}
-
-function parseArgs(argv) {
-	const args = {
-		write: false,
-		apiKey: process.env.CURSOR_API_KEY?.trim() || undefined,
-		contextWindowsPath: undefined,
-		fallbackContextWindow: DEFAULT_CONTEXT_WINDOW,
-	};
-	for (let index = 0; index < argv.length; index++) {
-		const arg = argv[index];
-		if (arg === "-h" || arg === "--help") {
-			printHelp();
-			process.exit(0);
-		}
-		if (arg === "--write") {
-			args.write = true;
-			continue;
-		}
-		if (arg === "--api-key") {
-			const value = argv[++index];
-			if (!value || value.startsWith("--")) fail("--api-key requires a value");
-			args.apiKey = value.trim();
-			continue;
-		}
-		if (arg.startsWith("--api-key=")) {
-			args.apiKey = arg.slice("--api-key=".length).trim();
-			continue;
-		}
-		if (arg === "--context-windows") {
-			const value = argv[++index];
-			if (!value || value.startsWith("--")) fail("--context-windows requires a file path");
-			args.contextWindowsPath = value;
-			continue;
-		}
-		if (arg.startsWith("--context-windows=")) {
-			args.contextWindowsPath = arg.slice("--context-windows=".length);
-			continue;
-		}
-		if (arg === "--fallback-context-window") {
-			const value = argv[++index];
-			if (!value || value.startsWith("--")) fail("--fallback-context-window requires a positive integer");
-			args.fallbackContextWindow = parsePositiveInteger(value, "--fallback-context-window");
-			continue;
-		}
-		if (arg.startsWith("--fallback-context-window=")) {
-			args.fallbackContextWindow = parsePositiveInteger(arg.slice("--fallback-context-window=".length), "--fallback-context-window");
-			continue;
-		}
-		fail(`unknown argument ${arg}`);
+function parseRefreshArgs(argv) {
+	if (argv.includes("-h") || argv.includes("--help")) {
+		printHelp();
+		process.exit(0);
 	}
+	const write = argv.includes("--write");
+	const filteredArgv = argv.filter((arg) => arg !== "--write");
+	const args = parseArgv(filteredArgv, {
+		defaults: {
+			write,
+			apiKey: defaultApiKeyFromEnv(),
+			contextWindowsPath: undefined,
+			fallbackContextWindow: DEFAULT_CONTEXT_WINDOW,
+		},
+		flags: {
+			apiKey: { names: ["--api-key"], assign: (value) => value.trim() },
+			contextWindowsPath: { names: ["--context-windows"] },
+			fallbackContextWindow: {
+				names: ["--fallback-context-window"],
+				assign: (value) => parsePositiveInteger(value, "--fallback-context-window"),
+			},
+		},
+		fail,
+	});
 	if (!args.apiKey) fail("missing Cursor API key; set CURSOR_API_KEY or pass --api-key");
 	return args;
 }
@@ -200,13 +164,13 @@ function formatContextWindows(models, checkpointWindows, fallbackContextWindow)
 	return `// Generated from Cursor SDK checkpoint tokenDetails.maxTokens on ${date}.\n// Refresh with: npm run refresh:cursor-snapshots -- --write --context-windows ~/.pi/agent/cursor-sdk-context-windows.json\n// These are default/non-Max-mode SDK context windows for Cursor models that do not\n// expose a catalog \`context\` parameter. Do not replace them with Max Mode values\n// unless the Cursor SDK exposes an exact Max Mode model selection and the extension\n// uses that selection for matching pi model IDs.\nexport const BUNDLED_CONTEXT_WINDOWS = {\n${lines.join("\n")}\n} as const satisfies Record<string, number>;\n`;
 }
 
-const args = parseArgs(process.argv.slice(2));
+const args = parseRefreshArgs(process.argv.slice(2));
 let rawModels;
 try {
 	rawModels = await Cursor.models.list({ apiKey: args.apiKey });
 } catch (error) {
 	const rawMessage = error instanceof Error ? error.message : String(error);
-	fail(`Cursor.models.list() failed: ${scrubSensitiveText(rawMessage, [args.apiKey])}`);
+	fail(`Cursor.models.list() failed: ${scrubSensitiveText(rawMessage, args.apiKey)}`);
 }
 if (!Array.isArray(rawModels) || rawModels.length === 0) fail("Cursor.models.list() returned no models");
 

package/scripts/steering-rpc-smoke.mjs

@@ -2,13 +2,20 @@
 /**
  * RPC steering smoke: queue steer after a native-replay tool-use turn completes execution.
  */
-import { spawn } from "node:child_process";
-import { mkdirSync } from "node:fs";
-import { join } from "node:path";
+import { spawn, spawnSync } from "node:child_process";
+import { EventEmitter } from "node:events";
+import { accessSync, chmodSync, constants, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { delimiter, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { parseJsonLines, terminateChild, waitForChildClose } from "./lib/cursor-child-process.mjs";
+import { apiKeySecretsFromProcess } from "./lib/cursor-cli-args.mjs";
+import { buildCursorSmokeEnv, CURSOR_SDK_EVENT_DEBUG_ENV_NAMES } from "./lib/cursor-smoke-env.mjs";
+import { scrubSensitiveText } from "../shared/cursor-sensitive-text.mjs";
 
 const root = fileURLToPath(new URL("..", import.meta.url));
-const CHILD_SHUTDOWN_GRACE_MS = 2_000;
+const DEBUG_ENV_NAMES = CURSOR_SDK_EVENT_DEBUG_ENV_NAMES;
+const DEFAULT_CHILD_CLOSE_TIMEOUT_MS = 30_000;
 
 function printHelp() {
 	console.log(`RPC steering smoke for pi-cursor-sdk live runs.
@@ -18,10 +25,12 @@ Usage:
 
 Environment:
   SMOKE_SESSION_DIR            Session directory for the RPC pi run. Defaults to /tmp/pi-cursor-steer-smoke-<timestamp>.
-  CURSOR_API_KEY               Required Cursor API key for live pi runs.
+  PI_BIN                       Optional absolute pi executable path. smoke:live injects the parent-resolved path.
+  CURSOR_API_KEY               Optional fallback auth. Stored pi auth in ~/.pi/agent/auth.json is also supported.
 
 Options:
   -h, --help                   Show this help.
+  --self-test                  Run the fake-PATH resolver probe without launching pi.
 
 Exit codes:
   0  steering scenario completed without AgentBusyError; STEER_OK and STEER_CHAIN present
@@ -37,17 +46,63 @@ function fail(message) {
 	throw new Error(message);
 }
 
-function parseEvents(stdout) {
-	const events = [];
-	for (const line of stdout.split("\n")) {
-		if (!line.trim()) continue;
-		try {
-			events.push(JSON.parse(line));
-		} catch {
-			// ignore partial lines
-		}
+function scrubForReport(text) {
+	let scrubbed = scrubSensitiveText(text);
+	for (const secret of apiKeySecretsFromProcess()) {
+		if (secret) scrubbed = scrubSensitiveText(scrubbed, secret);
+	}
+	return scrubbed;
+}
+
+function smokeOutputTail(stdout, stderr) {
+	return `stdoutTail=${scrubForReport(stdout.slice(-2000))}\nstderrTail=${scrubForReport(stderr.slice(-2000))}`;
+}
+
+async function waitForChildCloseWithTimeout(child, timeoutMs, outputSummary = () => "") {
+	let timeout;
+	try {
+		return await Promise.race([
+			waitForChildClose(child),
+			new Promise((_, reject) => {
+				timeout = setTimeout(() => {
+					const summary = outputSummary();
+					reject(new Error(`pi did not exit within ${timeoutMs}ms after agent_end${summary ? `\n${summary}` : ""}`));
+				}, timeoutMs);
+			}),
+		]);
+	} finally {
+		clearTimeout(timeout);
+	}
+}
+
+function isExecutable(path) {
+	try {
+		accessSync(path, constants.X_OK);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+function resolveCommand(command, envPath = process.env.PATH ?? "") {
+	if (!command.trim()) fail("empty command name");
+	if (command.includes("/")) {
+		const path = resolve(command);
+		if (!isExecutable(path)) fail(`${command} is not executable`);
+		return path;
+	}
+	for (const entry of envPath.split(delimiter)) {
+		if (!entry) continue;
+		const candidate = resolve(entry, command);
+		if (isExecutable(candidate)) return candidate;
 	}
-	return events;
+	fail(`${command} is required on PATH`);
+}
+
+function resolvePiBin() {
+	const path = process.env.PI_BIN?.trim() || resolveCommand("pi");
+	if (!path.startsWith("/")) fail(`PI_BIN must be an absolute path when provided: ${path}`);
+	return path;
 }
 
 function assistantText(events) {
@@ -79,7 +134,7 @@ function waitFor(getStdout, predicate, timeoutMs = 300_000) {
 	const start = Date.now();
 	return new Promise((resolve, reject) => {
 		const tick = () => {
-			const events = parseEvents(getStdout());
+			const events = parseJsonLines(getStdout());
 			if (predicate(events)) {
 				resolve(events);
 				return;
@@ -98,52 +153,22 @@ function waitFor(getStdout, predicate, timeoutMs = 300_000) {
 	});
 }
 
-function waitForChildClose(child) {
-	if (child.exitCode !== null || child.signalCode !== null) return Promise.resolve(child.exitCode ?? 1);
-	return new Promise((resolve) => {
-		child.once("close", (code) => resolve(code ?? 1));
+function buildPiRpcEnv(baseEnv = process.env, nodePath = process.execPath) {
+	return buildCursorSmokeEnv({
+		baseEnv,
+		nodePath,
+		settingSources: "none",
+		nativeToolDisplay: true,
+		registerNativeTools: true,
+		bridge: false,
 	});
 }
 
-function signalChild(child, signal) {
-	if (!child.pid) return;
-	try {
-		if (process.platform === "win32") {
-			child.kill(signal);
-		} else {
-			process.kill(-child.pid, signal);
-		}
-	} catch {
-		try {
-			child.kill(signal);
-		} catch {
-			// child already exited
-		}
-	}
-}
-
-async function terminateChild(child) {
-	child.stdin.destroy();
-	if (child.exitCode !== null || child.signalCode !== null) return;
-	signalChild(child, "SIGTERM");
-	const killTimer = setTimeout(() => signalChild(child, "SIGKILL"), CHILD_SHUTDOWN_GRACE_MS);
-	try {
-		await waitForChildClose(child);
-	} finally {
-		clearTimeout(killTimer);
-	}
-}
-
-async function runPiRpcSmoke(sessionDir) {
+async function runPiRpcSmoke(sessionDir, piBin) {
 	const args = ["-e", root, "--cursor-no-fast", "--model", "cursor/composer-2.5", "--mode", "rpc", "--session-dir", sessionDir];
-	const env = {
-		...process.env,
-		PI_CURSOR_SETTING_SOURCES: "none",
-		PI_CURSOR_NATIVE_TOOL_DISPLAY: "1",
-		PI_CURSOR_PI_TOOL_BRIDGE: "0",
-	};
+	const env = buildPiRpcEnv();
 
-	const child = spawn("pi", args, { cwd: root, env, stdio: ["pipe", "pipe", "pipe"], detached: process.platform !== "win32" });
+	const child = spawn(piBin, args, { cwd: root, env, stdio: ["pipe", "pipe", "pipe"], detached: process.platform !== "win32" });
 	let closed = false;
 	let stdout = "";
 	let stderr = "";
@@ -191,7 +216,7 @@ async function runPiRpcSmoke(sessionDir) {
 			fail("AgentBusyError detected in smoke output");
 		}
 
-		const text = assistantText(parseEvents(stdout));
+		const text = assistantText(parseJsonLines(stdout));
 		if (!text.includes("STEER_OK=yes")) {
 			fail(`missing STEER_OK=yes in assistant output: ${text.slice(0, 500)}`);
 		}
@@ -200,10 +225,10 @@ async function runPiRpcSmoke(sessionDir) {
 		}
 
 		child.stdin.end();
-		const exitCode = await waitForChildClose(child);
+		const exitCode = await waitForChildCloseWithTimeout(child, DEFAULT_CHILD_CLOSE_TIMEOUT_MS, () => smokeOutputTail(stdout, stderr));
 		closed = true;
 		if (exitCode !== 0) {
-			fail(`pi exited ${exitCode}\nstderr=${stderr.slice(-2000)}`);
+			fail(`pi exited ${exitCode}\nstderr=${scrubForReport(stderr.slice(-2000))}`);
 		}
 
 		return {
@@ -217,22 +242,102 @@ async function runPiRpcSmoke(sessionDir) {
 	}
 }
 
+async function runSelfTest() {
+	const tempDir = mkdtempSync(join(tmpdir(), "pi-cursor-sdk-steering-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 > ${JSON.stringify(fakeNodeMarker)}\nexit 99\n`, "utf8");
+		chmodSync(fakePi, 0o755);
+		chmodSync(fakeNode, 0o755);
+		const hostilePath = `${binDir}${delimiter}${process.env.PATH ?? ""}`;
+		if (buildPiRpcEnv({ PATH: "" }).PATH?.includes(delimiter)) fail("self-test failed: empty inherited PATH left an empty PATH segment");
+		if (resolveCommand("pi", hostilePath) !== fakePi) fail("self-test failed: direct PATH resolver did not prefer fake PATH head");
+		const originalPiBin = process.env.PI_BIN;
+		const originalPath = process.env.PATH;
+		try {
+			delete process.env.PI_BIN;
+			process.env.PATH = hostilePath;
+			if (resolvePiBin() !== fakePi) fail("self-test failed: resolvePiBin should use PATH when PI_BIN is absent");
+			process.env.PI_BIN = fakePi;
+			if (resolvePiBin() !== fakePi) fail("self-test failed: resolvePiBin should honor absolute PI_BIN");
+			const hostileEnv = buildPiRpcEnv({
+				...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",
+			});
+			if ((hostileEnv.PATH ?? "").split(delimiter)[0] !== dirname(process.execPath)) fail("self-test failed: sealed PATH should start with resolved node directory");
+			if (hostileEnv.PI_CURSOR_REGISTER_NATIVE_TOOLS !== "1") fail("self-test failed: native registration should be forced on");
+			if (hostileEnv.PI_CURSOR_SETTING_SOURCES !== "none") fail("self-test failed: setting sources should be forced off");
+			if (hostileEnv.PI_CURSOR_PI_TOOL_BRIDGE !== "0") fail("self-test failed: bridge should be forced off");
+			for (const name of DEBUG_ENV_NAMES) {
+				if (name in hostileEnv) fail(`self-test failed: ${name} should be cleared`);
+			}
+			const probe = spawnSync(fakePi, ["--version"], { cwd: root, env: hostileEnv, encoding: "utf8" });
+			if (probe.status !== 0) fail(`self-test failed: fake pi shim exited ${probe.status}; stderr=${probe.stderr}`);
+			let fakeNodeUsed = false;
+			try {
+				accessSync(fakeNodeMarker, constants.F_OK);
+				fakeNodeUsed = true;
+			} catch {
+				// Expected: sealed PATH should keep /usr/bin/env node away from the hostile fake node.
+			}
+			if (fakeNodeUsed) fail("self-test failed: steering child env used hostile fake node");
+			const hangingChild = new EventEmitter();
+			hangingChild.exitCode = null;
+			hangingChild.signalCode = null;
+			let closeTimedOut = false;
+			try {
+				await waitForChildCloseWithTimeout(hangingChild, 10, () => smokeOutputTail("STEER_OK=yes", ""));
+			} catch (error) {
+				const message = error instanceof Error ? error.message : String(error);
+				closeTimedOut = message.includes("pi did not exit within 10ms after agent_end") && message.includes("stdoutTail=STEER_OK=yes");
+			}
+			if (!closeTimedOut) fail("self-test failed: post-agent_end child close wait should be bounded and report output tail");
+		} finally {
+			if (originalPiBin === undefined) delete process.env.PI_BIN;
+			else process.env.PI_BIN = originalPiBin;
+			if (originalPath === undefined) delete process.env.PATH;
+			else process.env.PATH = originalPath;
+		}
+		console.log("[steering-rpc-smoke] self-test PASS");
+	} finally {
+		rmSync(tempDir, { recursive: true, force: true });
+	}
+}
+
 async function main() {
 	if (process.argv.includes("-h") || process.argv.includes("--help")) {
 		printHelp();
 		return;
 	}
-
-	if (!process.env.CURSOR_API_KEY) {
-		fail("steering-rpc-smoke: CURSOR_API_KEY is required");
+	if (process.argv.includes("--self-test")) {
+		await runSelfTest();
+		return;
 	}
 
 	const sessionDir = process.env.SMOKE_SESSION_DIR ?? join("/tmp", `pi-cursor-steer-smoke-${Date.now()}`);
+	const piBin = resolvePiBin();
 	mkdirSync(sessionDir, { recursive: true });
-	console.log(JSON.stringify(await runPiRpcSmoke(sessionDir)));
+	console.log(JSON.stringify(await runPiRpcSmoke(sessionDir, piBin)));
 }
 
 main().catch((error) => {
-	console.error(error instanceof Error ? error.message : String(error));
+	let scrubbed = scrubSensitiveText(error instanceof Error ? error.message : String(error));
+	for (const secret of apiKeySecretsFromProcess()) {
+		if (secret) scrubbed = scrubSensitiveText(scrubbed, secret);
+	}
+	console.error(scrubbed);
 	process.exitCode = 1;
 });