pi-cursor-sdk 0.1.39 → 0.1.41

package/docs/platform-smoke.md

@@ -123,7 +123,7 @@ Runtime budget is part of the contract:
 - `smoke:platform:doctor` never calls Cursor.
 - `platform-build` runs once per target and is the only suite that performs the full local CI/build/typecheck/package gate.
 - Live suites reuse the target checkout and prepared `node_modules` when run after `platform-build`; they do not repeat `npm ci` in a target-session release run.
-- Live suites share one target-local packed-install prep directory per target-session release run. The first live suite runs `npm pack` and `npm install --no-save <tarball>` once, then each suite still performs its own `pi install -l <packed package path>`, `pi list`, fresh `--session-dir`, suite `PI_CODING_AGENT_DIR`, workspace fixture, JSONL, visual, bridge, and abort assertions.
+- Live suites share one target-local packed-install prep directory per target-session release run. The first live suite runs `npm pack` and `npm install --no-save <tarball>` once, then each suite still performs its own `pi install --approve -l <packed package path>`, `pi list --approve`, fresh `--session-dir`, suite `PI_CODING_AGENT_DIR`, workspace fixture, JSONL, visual, bridge, and abort assertions.
 - Visual coverage is batched into one native prompt, one bridge prompt, and one abort/cleanup prompt per target. Do not split these into one prompt per card.
 - The gate is fail-fast by target to avoid burning Cursor calls after a platform has already failed.
 
@@ -186,6 +186,11 @@ export default {
   packageName: "pi-cursor-sdk",
   cursorModel: "cursor/composer-2-5",
   artifactRoot: ".artifacts/platform-smoke",
+  artifactRetention: {
+    maxRunDirs: 18,
+    maxAgeDays: 14,
+    preserveRecentHours: 24,
+  },
   requiredTargets: ["macos", "ubuntu", "windows-native"],
   requiredSuites: [
     "platform-build",
@@ -211,6 +216,8 @@ export default {
 
 `windowsParallels` records this repo's default shared Windows template contract. Environment overrides may point at a temporary candidate template during infrastructure work, but release runs should use the shared `pi-extension-windows-template` / `crabbox-ready` baseline unless this document is updated.
 
+`artifactRetention` bounds local host evidence growth under `artifactRoot`. `smoke:platform:run` prunes only top-level directories named `run-<timestamp>-<suffix>` before starting a new matrix; it leaves non-run/manual directories untouched and preserves directories newer than `preserveRecentHours` to avoid deleting evidence from active or very recent runs. Doctor is read-only and does not prune artifacts.
+
 ## Required local environment
 
 The config owns reusable defaults. Environment variables are local-machine knobs and one-off overrides, not a second source of truth. The doctor fails if required auth or target readiness is missing.
@@ -261,12 +268,12 @@ Definitions:
 - `piProjectRoot`: target-local pi project where platform-build proves packed install.
 - `livePrepRoot`: target-local shared live-suite prep where the first live suite installs the packed tarball once for reuse by later live suites in the same target session.
 
-Live suites run in a suite-local `testWorkspaceRoot`. The extension loaded by pi is the packed tarball package path from `livePrepRoot`, installed into that suite-local workspace with `pi install -l`; no live suite uses `pi -e .`.
+Live suites run in a suite-local `testWorkspaceRoot`. The extension loaded by pi is the packed tarball package path from `livePrepRoot`, installed into that suite-local workspace with `pi install --approve -l`; no live suite uses `pi -e .`.
 
 The runner must prove this by recording:
 
 - packed tarball path;
-- `pi list` output from the suite-local project after `pi install -l <packed package path>`;
+- `pi list --approve` output from the suite-local project after `pi install --approve -l <packed package path>`;
 - command line showing no `-e .`;
 - live suite cwd as `testWorkspaceRoot`.
 
@@ -354,7 +361,7 @@ Doctor checks:
 17. `tar` is available on macOS and native Windows.
 18. `node-pty` self-test passes on every target.
 19. Target pi tool probe proves the shell tool accepts platform-rendered commands on every target.
-20. Host-side xterm/Playwright render self-test passes.
+20. Host-side xterm/Playwright render self-test passes by rendering a minimal ANSI fixture through the repo xterm helper and launching Playwright Chromium to write a tiny PNG. If this fails, run `npm install` and `npx playwright install chromium` before live suites.
 21. `CURSOR_API_KEY` is present.
 22. Artifact root is writable.
 23. `git status --short` is recorded.
@@ -386,8 +393,8 @@ Per target, `platform-build` must:
 6. Run `npm pack`.
 7. Create `testWorkspaceRoot` with deterministic fixture files copied from the repo.
 8. Create `piProjectRoot`.
-9. Install the packed tarball into `piProjectRoot` with `pi install -l <tarball>`.
-10. Run `pi list` and assert the installed package points at the packed tarball/install, not `-e .`.
+9. Install the packed tarball into `piProjectRoot` with `pi install --approve -l <tarball>`.
+10. Run `pi list --approve` and assert the installed package points at the packed tarball/install, not `-e .`.
 
 ## Required suites
 
@@ -401,7 +408,7 @@ Purpose:
 - fail before spending Cursor tokens;
 - produce the packed extension used by later suites.
 
-The host `smoke:platform:all` entrypoint enforces doctor first before running targets. Required artifacts include `node-version.txt`, `npm-version.txt`, stdout/stderr for `npm ci`, `npm run check:platform-smoke`, `npm test`, `npm run typecheck`, `npm pack`, packed npm install, `pi install`, and `pi list`, plus `packed-tarball.txt`, `summary.json`, `artifact-manifest.json`, `assertions.json`, and `failures.md` on failed assertions.
+The host `smoke:platform:all` entrypoint enforces doctor first before running targets. Required artifacts include `node-version.txt`, `npm-version.txt`, stdout/stderr for `npm ci`, `npm run check:platform-smoke`, `npm test`, `npm run typecheck`, `npm pack`, packed npm install, `pi install --approve`, and `pi list --approve`, plus `packed-tarball.txt`, `summary.json`, `artifact-manifest.json`, `assertions.json`, and `failures.md` on failed assertions.
 
 ### `cursor-native-visual-matrix`
 
@@ -636,6 +643,14 @@ Every suite writes under:
 .artifacts/platform-smoke/<run-id>/<target>/<suite>/
 ```
 
+After each `smoke:platform run` invocation, the host writes an atomic latest artifact index for agents and humans:
+
+```text
+.artifacts/platform-smoke/latest.json
+```
+
+`latest.json` records the invocation timestamps, command selection, PID, run id(s), target/suite artifact directories, paths to suite summaries/assertions/failures when present, rendered terminal HTML/PNG paths, visual evidence, session JSONL, JSONL tool-result summaries, and capped Cursor SDK/provider debug artifact paths. The per-suite artifact directories remain the source of truth; `latest.json` is only a discoverability pointer.
+
 Common required artifacts:
 
 ```text

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-cursor-sdk",
-	"version": "0.1.39",
+	"version": "0.1.41",
 	"description": "pi provider extension backed by @cursor/sdk local agents",
 	"author": "Mitch Fultz (https://github.com/fitchmultz)",
 	"license": "MIT",
@@ -28,6 +28,7 @@
 		"scripts/steering-rpc-smoke.mjs",
 		"scripts/tmux-live-smoke.sh",
 		"scripts/visual-tui-smoke.mjs",
+		"scripts/visual-tui-smoke-self-test.mjs",
 		"scripts/isolated-cursor-smoke.sh",
 		"scripts/fixtures/plan-strip-shim",
 		"scripts/validate-smoke-jsonl.mjs",
@@ -60,6 +61,8 @@
 		"scripts/lib/cursor-smoke-env.mjs",
 		"scripts/lib/cursor-smoke-env.d.mts",
 		"scripts/lib/cursor-smoke-shell.sh",
+		"scripts/lib/cursor-visual-manifest.mjs",
+		"scripts/lib/cursor-visual-manifest.d.mts",
 		"scripts/lib/cursor-visual-render.mjs",
 		"scripts/lib/cursor-visual-render.d.mts",
 		"scripts/lib/cursor-sdk-output-filter.mjs",
@@ -106,7 +109,7 @@
 		"smoke:platform:all": "npm run smoke:platform:doctor && node scripts/platform-smoke.mjs run --target macos,ubuntu,windows-native"
 	},
 	"dependencies": {
-		"@cursor/sdk": "1.0.17",
+		"@cursor/sdk": "1.0.18",
 		"@modelcontextprotocol/sdk": "^1.29.0"
 	},
 	"peerDependencies": {
@@ -116,9 +119,9 @@
 		"typebox": "*"
 	},
 	"devDependencies": {
-		"@earendil-works/pi-ai": "0.78.1",
-		"@earendil-works/pi-coding-agent": "0.78.1",
-		"@earendil-works/pi-tui": "0.78.1",
+		"@earendil-works/pi-ai": "0.79.1",
+		"@earendil-works/pi-coding-agent": "0.79.1",
+		"@earendil-works/pi-tui": "0.79.1",
 		"@xterm/xterm": "^6.0.0",
 		"node-pty": "^1.1.0",
 		"playwright": "^1.60.0",

package/platform-smoke.config.mjs

@@ -5,6 +5,11 @@ export default {
 	packageName: "pi-cursor-sdk",
 	cursorModel: "cursor/composer-2-5",
 	artifactRoot: ".artifacts/platform-smoke",
+	artifactRetention: {
+		maxRunDirs: 18,
+		maxAgeDays: 14,
+		preserveRecentHours: 24,
+	},
 	requiredTargets: ["macos", "ubuntu", "windows-native"],
 	requiredSuites: [
 		"platform-build",

package/scripts/debug-provider-events.mjs

@@ -194,6 +194,7 @@ export async function runDebugProviderEvents(args, envInput = process.env) {
 	mkdirSync(sessionDir, { recursive: true });
 
 	const piArgs = [
+		"--approve",
 		"-e",
 		root,
 		"--cursor-no-fast",

package/scripts/isolated-cursor-smoke.sh

@@ -344,12 +344,12 @@ fi
 log "npm install packed extension deps"
 run_in_dir_capture_combined "npm install --omit=dev" 120 "$EXTRACT_DIR/package" "$ISOLATED/npm-install.log" "${TOOL_ENV[@]}" "$NPM_BIN" install --omit=dev
 
-log "pi install -l (clean HOME)"
+log "pi install --approve -l (clean HOME)"
 cp "$REPO/README.md" "$PROJECT_DIR/README.md"
-run_in_dir_capture_combined "pi install" 30 "$PROJECT_DIR" "$ISOLATED/pi-install.log" "${PI_DEFAULT_ENV[@]}" "$PI_BIN" install -l "$EXTRACT_DIR/package"
+run_in_dir_capture_combined "pi install" 30 "$PROJECT_DIR" "$ISOLATED/pi-install.log" "${PI_DEFAULT_ENV[@]}" "$PI_BIN" install --approve -l "$EXTRACT_DIR/package"
 
 PI_LIST_OUT="$ISOLATED/pi-list.txt"
-run_in_dir_capture_combined "pi list" 15 "$PROJECT_DIR" "$PI_LIST_OUT" "${PI_DEFAULT_ENV[@]}" "$PI_BIN" list
+run_in_dir_capture_combined "pi list" 15 "$PROJECT_DIR" "$PI_LIST_OUT" "${PI_DEFAULT_ENV[@]}" "$PI_BIN" list --approve
 "$RG_BIN" -q "extract/package" "$PI_LIST_OUT" || fail "packed extension not installed"
 
 PI_CURSOR_ENV=( "${PI_NONE_ENV[@]}" )
@@ -360,14 +360,14 @@ fi
 log "check: list-models"
 LIST_OUT="$ISOLATED/list-models.txt"
 run_in_dir_capture_combined "list-models" 30 "$PROJECT_DIR" "$LIST_OUT" "${PI_CURSOR_ENV[@]}" \
-	"$PI_BIN" --cursor-no-fast --list-models cursor
+	"$PI_BIN" --approve --cursor-no-fast --list-models cursor
 "$RG_BIN" -q "composer-2\\.5|composer-2-5" "$LIST_OUT" || fail "composer-2-5 not listed (see $LIST_OUT)"
 
 log "check: basic provider prompt"
 BASIC_DIR="$SESSION_ROOT/basic"
 mkdir -p "$BASIC_DIR"
 run_in_dir_capture_split "basic prompt" "$PI_LIVE_TIMEOUT" "$PROJECT_DIR" "$ISOLATED/basic.stdout.txt" "$ISOLATED/basic.stderr.txt" "${PI_CURSOR_ENV[@]}" \
-	"$PI_BIN" --cursor-no-fast --model cursor/composer-2-5 --session-dir "$BASIC_DIR" --no-tools -p 'Reply exactly: PI_CURSOR_ISOLATED_OK'
+	"$PI_BIN" --approve --cursor-no-fast --model cursor/composer-2-5 --session-dir "$BASIC_DIR" --no-tools -p 'Reply exactly: PI_CURSOR_ISOLATED_OK'
 "$RG_BIN" -q "PI_CURSOR_ISOLATED_OK" "$ISOLATED/basic.stdout.txt" || fail "basic prompt missing PI_CURSOR_ISOLATED_OK"
 validate_replay_jsonl "$BASIC_DIR"
 
@@ -375,14 +375,14 @@ log "check: native replay"
 REPLAY_DIR="$SESSION_ROOT/native-replay"
 mkdir -p "$REPLAY_DIR"
 run_in_dir_capture_split "native replay" "$PI_LIVE_TIMEOUT" "$PROJECT_DIR" "$ISOLATED/replay.stdout.txt" "$ISOLATED/replay.stderr.txt" "${PI_CURSOR_ENV[@]}" PI_CURSOR_NATIVE_TOOL_DISPLAY=1 \
-	"$PI_BIN" --cursor-no-fast --model cursor/composer-2-5 --session-dir "$REPLAY_DIR" -p 'Read ./README.md briefly, then answer README_SEEN=yes if it mentions pi-cursor-sdk.'
+	"$PI_BIN" --approve --cursor-no-fast --model cursor/composer-2-5 --session-dir "$REPLAY_DIR" -p 'Read ./README.md briefly, then answer README_SEEN=yes if it mentions pi-cursor-sdk.'
 validate_replay_jsonl "$REPLAY_DIR"
 
 log "check: plan-strip shim (plan-mode execute reset)"
 PLAN_DIR="$SESSION_ROOT/plan-strip"
 mkdir -p "$PLAN_DIR"
 run_in_dir_capture_split "plan-strip replay" "$PI_LIVE_TIMEOUT" "$PROJECT_DIR" "$ISOLATED/plan.stdout.txt" "$ISOLATED/plan.stderr.txt" "${PI_CURSOR_ENV[@]}" PI_CURSOR_NATIVE_TOOL_DISPLAY=1 \
-	"$PI_BIN" -e "$SHIM_DIR" --cursor-no-fast --model cursor/composer-2-5 --session-dir "$PLAN_DIR" -p 'After reset, read README.md and answer PLAN_STRIP_OK=yes.'
+	"$PI_BIN" --approve -e "$SHIM_DIR" --cursor-no-fast --model cursor/composer-2-5 --session-dir "$PLAN_DIR" -p 'After reset, read README.md and answer PLAN_STRIP_OK=yes.'
 validate_replay_jsonl "$PLAN_DIR"
 
 log "PASS isolated install smoke: $ISOLATED"

package/scripts/lib/cursor-visual-manifest.d.mts

@@ -0,0 +1,3 @@
+export function redactedArgv(argv: string[]): string[];
+export function promptDigest(prompt: string): string;
+export function writeVisualManifest(path: string, options: Record<string, unknown>, artifacts: Record<string, unknown>, failure?: Record<string, unknown>): void;

package/scripts/lib/cursor-visual-manifest.mjs

@@ -0,0 +1,82 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+
+function writeUtf8(path, text) {
+	mkdirSync(dirname(path), { recursive: true });
+	writeFileSync(path, text, "utf8");
+}
+
+export function redactedArgv(argv) {
+	const redacted = [];
+	let redactNext = false;
+	for (const arg of argv) {
+		if (redactNext) {
+			redacted.push("[redacted]");
+			redactNext = false;
+			continue;
+		}
+		if (arg === "--prompt" || arg === "--prompt-file") {
+			redacted.push(arg);
+			redactNext = true;
+			continue;
+		}
+		if (arg.startsWith("--prompt=") || arg.startsWith("--prompt-file=")) {
+			const [flag] = arg.split("=", 1);
+			redacted.push(`${flag}=[redacted]`);
+			continue;
+		}
+		redacted.push(arg);
+	}
+	return redacted;
+}
+
+export function promptDigest(prompt) {
+	return createHash("sha256").update(prompt).digest("hex");
+}
+
+function manifestExistingPath(path) {
+	return path && existsSync(path) ? path : undefined;
+}
+
+export function writeVisualManifest(path, options, artifacts, failure) {
+	const paths = {
+		ansi: manifestExistingPath(artifacts.ansiPath),
+		text: manifestExistingPath(artifacts.textPath),
+		html: manifestExistingPath(artifacts.htmlPath),
+		png: artifacts.pngWritten === true ? manifestExistingPath(artifacts.pngPath) : undefined,
+		jsonlPathFile: manifestExistingPath(artifacts.jsonlPathFile),
+		jsonl: manifestExistingPath(artifacts.jsonlPath),
+	};
+	for (const [key, value] of Object.entries(paths)) {
+		if (value === undefined) delete paths[key];
+	}
+	writeUtf8(path, `${JSON.stringify({
+		schemaVersion: 1,
+		kind: "visual-tui-smoke-manifest",
+		label: options.label,
+		safeLabel: options.safeLabel,
+		promptLength: options.prompt.length,
+		promptSha256: promptDigest(options.prompt),
+		width: options.width,
+		height: options.height,
+		model: options.model,
+		mode: options.mode,
+		cwd: options.cwd,
+		ext: options.ext,
+		outDir: options.outDir,
+		sessionDir: options.sessionDir,
+		sessionId: options.sessionId,
+		waitMs: options.waitMs,
+		startupMs: options.startupMs,
+		screenshot: options.screenshot,
+		paths,
+		command: {
+			argv: redactedArgv(process.argv.slice(2)),
+			cwd: process.cwd(),
+			pid: process.pid,
+		},
+		...(failure ? { failure } : {}),
+		writtenAt: new Date().toISOString(),
+	}, null, 2)}\n`);
+}

package/scripts/platform-smoke/artifacts.mjs

@@ -2,8 +2,87 @@
  * Artifact management — directory layout, manifest, redaction scanning, packaging.
  */
 
-import { mkdirSync, writeFileSync, readFileSync, readdirSync, statSync, existsSync } 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;
+}
+
+function finiteNonNegativeInteger(value) {
+	return Number.isInteger(value) && value >= 0;
+}
+
+/** Prune old top-level platform-smoke run artifact directories. */
+export function prunePlatformSmokeArtifacts(artifactRoot, retention = {}, options = {}) {
+	const root = resolve(process.cwd(), artifactRoot);
+	const maxRunDirs = finiteNonNegativeInteger(retention.maxRunDirs) ? retention.maxRunDirs : undefined;
+	const maxAgeDays = finiteNonNegativeNumber(retention.maxAgeDays) ? retention.maxAgeDays : undefined;
+	const preserveRecentHours = finiteNonNegativeNumber(retention.preserveRecentHours) ? retention.preserveRecentHours : 24;
+	const enabled = retention.enabled !== false && (maxRunDirs !== undefined || maxAgeDays !== undefined);
+	const result = { root, enabled, removed: [], kept: [], ignored: [] };
+	if (!enabled || !existsSync(root)) return result;
+
+	const nowMs = finiteNonNegativeNumber(options.nowMs) ? options.nowMs : Date.now();
+	const preserveRecentMs = preserveRecentHours * HOURS_TO_MS;
+	const maxAgeMs = maxAgeDays === undefined ? undefined : maxAgeDays * DAYS_TO_MS;
+	const runDirs = [];
+
+	for (const entry of readdirSync(root, { withFileTypes: true })) {
+		if (!entry.isDirectory()) {
+			result.ignored.push(entry.name);
+			continue;
+		}
+		const match = PLATFORM_SMOKE_RUN_DIR_PATTERN.exec(entry.name);
+		if (!match) {
+			result.ignored.push(entry.name);
+			continue;
+		}
+		runDirs.push({ name: entry.name, path: resolve(root, entry.name), timestampMs: Number(match[1]) });
+	}
+
+	const recentCutoffMs = nowMs - preserveRecentMs;
+	const protectedRecent = new Set(runDirs.filter((dir) => dir.timestampMs > recentCutoffMs).map((dir) => dir.name));
+	const removeNames = new Set();
+
+	if (maxAgeMs !== undefined) {
+		const staleCutoffMs = nowMs - maxAgeMs;
+		for (const dir of runDirs) {
+			if (dir.timestampMs < staleCutoffMs) removeNames.add(dir.name);
+		}
+	}
+
+	if (maxRunDirs !== undefined && runDirs.length > maxRunDirs) {
+		const sortedNewestFirst = [...runDirs].sort((a, b) => b.timestampMs - a.timestampMs);
+		let remainingKeepSlots = maxRunDirs - protectedRecent.size;
+		for (const dir of sortedNewestFirst) {
+			if (protectedRecent.has(dir.name)) continue;
+			if (remainingKeepSlots > 0) {
+				remainingKeepSlots--;
+				continue;
+			}
+			removeNames.add(dir.name);
+		}
+	}
+
+	for (const dir of runDirs) {
+		if (!removeNames.has(dir.name)) {
+			result.kept.push(dir.name);
+			continue;
+		}
+		rmSync(dir.path, { recursive: true, force: true });
+		result.removed.push(dir.name);
+	}
+	result.kept.sort();
+	result.removed.sort();
+	result.ignored.sort();
+	return result;
+}
 
 /** Create a suite artifact directory. */
 export function createSuiteDir(artifactRoot, runId, targetName, suiteName) {
@@ -100,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);
 }