pi-agent-browser-native 0.2.37 → 0.2.39

package/scripts/platform-smoke/browser-dogfood-windows.ps1

@@ -0,0 +1,110 @@
+param(
+  [Parameter(Mandatory=$true)][string]$AgentBrowserVersion
+)
+
+$ErrorActionPreference = "Continue"
+$SourceRoot = (Get-Location).Path
+$RunRoot = Join-Path ".platform-smoke-runs" ("browser-dogfood-{0}-{1}" -f ((Get-Date).ToUniversalTime().ToString("yyyyMMddTHHmmssZ")), $PID)
+$DogfoodDir = Join-Path $SourceRoot (Join-Path $RunRoot "dogfood")
+$DogfoodArtifactDir = Join-Path $env:TEMP ("pi-agent-browser-dogfood-artifacts-{0}" -f $PID)
+New-Item -ItemType Directory -Force -Path $DogfoodDir | Out-Null
+New-Item -ItemType Directory -Force -Path $DogfoodArtifactDir | Out-Null
+
+function Write-Section($Name, $Path) {
+  Write-Output "--- $Name START ---"
+  if (Test-Path $Path) { Get-Content -Raw $Path }
+  Write-Output "--- $Name END ---"
+}
+
+function Get-AgentBrowserVersion() {
+  if (-not (Get-Command agent-browser -ErrorAction SilentlyContinue)) { return "" }
+  return (& agent-browser --version 2>$null)
+}
+
+function Test-AgentBrowser($Version) {
+  $Expected = "agent-browser $Version"
+  $Current = Get-AgentBrowserVersion
+  Write-Output "PLATFORM_AGENT_BROWSER_VERSION=$Current"
+  $script:AgentBrowserReadyExit = if ($Current -eq $Expected) { 0 } else { 1 }
+}
+
+function Test-AgentBrowserBrowserCache() {
+  $Candidates = @(
+    (Join-Path $env:USERPROFILE ".agent-browser\browsers"),
+    "C:\WINDOWS\system32\config\systemprofile\.agent-browser\browsers"
+  )
+  foreach ($Candidate in $Candidates) {
+    if (-not $Candidate -or -not (Test-Path $Candidate)) { continue }
+    $Chrome = Get-ChildItem -Path $Candidate -Recurse -Filter chrome.exe -ErrorAction SilentlyContinue | Select-Object -First 1
+    if ($Chrome) {
+      Write-Output "PLATFORM_AGENT_BROWSER_BROWSER_PATH=$($Chrome.FullName)"
+      $script:BrowserCacheExit = 0
+      return
+    }
+  }
+  Write-Output "PLATFORM_AGENT_BROWSER_BROWSER_PATH="
+  $script:BrowserCacheExit = 1
+}
+
+Write-Output "Starting browser-dogfood-smoke in $SourceRoot at $((Get-Date).ToUniversalTime().ToString('o'))"
+Write-Output "PLATFORM_RUN_ROOT=$RunRoot"
+Write-Output "PLATFORM_DOGFOOD_ARTIFACT_DIR=$DogfoodArtifactDir"
+
+$NodeVersion = (& node --version 2>$null)
+Write-Output "PLATFORM_NODE_VERSION=$NodeVersion"
+
+& npm ci 2>&1
+$NpmCiExit = $LASTEXITCODE
+Write-Output "PLATFORM_NPM_CI_EXIT=$NpmCiExit"
+
+$script:AgentBrowserReadyExit = 1
+Test-AgentBrowser $AgentBrowserVersion
+$AgentBrowserExit = $script:AgentBrowserReadyExit
+Write-Output "PLATFORM_AGENT_BROWSER_READY_EXIT=$AgentBrowserExit"
+$script:BrowserCacheExit = 1
+if ($AgentBrowserExit -eq 0) { Test-AgentBrowserBrowserCache }
+$BrowserCacheExit = $script:BrowserCacheExit
+Write-Output "PLATFORM_AGENT_BROWSER_BROWSER_CACHE_EXIT=$BrowserCacheExit"
+$BrowserPrewarmExit = 1
+if ($BrowserCacheExit -eq 0) {
+  $PrewarmPath = Join-Path $DogfoodArtifactDir "prewarm.html"
+  "<h1>Example Domain</h1>" | Set-Content $PrewarmPath
+  $PrewarmUrl = "file:///" + ($PrewarmPath -replace "\\", "/")
+  for ($Attempt = 1; $Attempt -le 3; $Attempt++) {
+    Write-Output "PLATFORM_AGENT_BROWSER_PREWARM_ATTEMPT=$Attempt"
+    & agent-browser open --json --session "platform-smoke-prewarm-$Attempt" $PrewarmUrl 2>&1
+    $BrowserPrewarmExit = $LASTEXITCODE
+    & agent-browser close --json --session "platform-smoke-prewarm-$Attempt" 2>&1
+    if ($BrowserPrewarmExit -eq 0) { break }
+    Start-Sleep -Seconds 2
+  }
+}
+Write-Output "PLATFORM_AGENT_BROWSER_PREWARM_EXIT=$BrowserPrewarmExit"
+
+$env:PI_AGENT_BROWSER_PROCESS_TIMEOUT_MS = "55000"
+Write-Output "PLATFORM_PI_AGENT_BROWSER_PROCESS_TIMEOUT_MS=$env:PI_AGENT_BROWSER_PROCESS_TIMEOUT_MS"
+
+$TsxCli = Join-Path $SourceRoot "node_modules/.bin/tsx.cmd"
+if (-not (Test-Path $TsxCli)) { $TsxCli = Join-Path $SourceRoot "node_modules/.bin/tsx" }
+if (-not (Test-Path $TsxCli)) { $TsxCli = "tsx" }
+Write-Output "PLATFORM_TSX_CLI=$TsxCli"
+
+$DogfoodStdout = Join-Path $DogfoodDir "dogfood.stdout.txt"
+$DogfoodStderr = Join-Path $DogfoodDir "dogfood.stderr.txt"
+if ($NpmCiExit -eq 0 -and $AgentBrowserExit -eq 0 -and $BrowserCacheExit -eq 0 -and $BrowserPrewarmExit -eq 0) {
+  & $TsxCli "scripts/verify-agent-browser-dogfood.ts" --artifact-dir $DogfoodArtifactDir --json >$DogfoodStdout 2>$DogfoodStderr
+  $DogfoodExit = $LASTEXITCODE
+} else {
+  "npm ci or agent-browser setup failed" | Set-Content $DogfoodStderr
+  $DogfoodExit = 1
+}
+Write-Output "PLATFORM_DOGFOOD_EXIT=$DogfoodExit"
+Write-Section "DOGFOOD_STDOUT" $DogfoodStdout
+Write-Section "DOGFOOD_STDERR" $DogfoodStderr
+
+if ($NpmCiExit -ne 0 -or $AgentBrowserExit -ne 0 -or $BrowserCacheExit -ne 0 -or $BrowserPrewarmExit -ne 0 -or $DogfoodExit -ne 0) {
+  Write-Output "PLATFORM_BROWSER_DOGFOOD_FAILED"
+  exit 1
+}
+
+Write-Output "PLATFORM_BROWSER_DOGFOOD_OK"

package/scripts/platform-smoke/crabbox-runner.mjs

@@ -0,0 +1,149 @@
+/** Thin Crabbox CLI wrapper for cross-platform smoke tests. */
+
+import { spawn } from "node:child_process";
+
+function env(name) {
+	return process.env[name] ?? "";
+}
+
+export function crabboxBin() {
+	return process.env.PLATFORM_SMOKE_CRABBOX || "crabbox";
+}
+
+function packageSlug(config = {}) {
+	return process.env.PLATFORM_SMOKE_PACKAGE_SLUG || config.packageName || "pi-agent-browser-native";
+}
+
+export function buildTargetBaseArgs(targetName, config = {}) {
+	switch (targetName) {
+		case "macos": {
+			const user = env("PLATFORM_SMOKE_MAC_USER") || env("USER");
+			const host = env("PLATFORM_SMOKE_MAC_HOST") || "localhost";
+			const workRoot = env("PLATFORM_SMOKE_MAC_WORK_ROOT") || `/Users/${user}/crabbox/${packageSlug(config)}`;
+			return [
+				"--provider", "ssh",
+				"--target", "macos",
+				"--static-host", host,
+				"--static-user", user,
+				"--static-port", "22",
+				"--static-work-root", workRoot,
+			];
+		}
+		case "ubuntu": {
+			const image = env("PLATFORM_SMOKE_UBUNTU_IMAGE") || config.ubuntuContainerImage || "pi-agent-browser-native-platform:node24-agent-browser0.27.1";
+			return [
+				"--provider", "local-container",
+				"--target", "linux",
+				"--local-container-image", image,
+			];
+		}
+		case "windows-native": {
+			const vm = env("PLATFORM_SMOKE_WINDOWS_VM") || "pi-extension-windows-template";
+			const snapshot = env("PLATFORM_SMOKE_WINDOWS_SNAPSHOT") || "crabbox-ready";
+			const user = env("PLATFORM_SMOKE_WINDOWS_USER") || env("USER");
+			const workRoot = env("PLATFORM_SMOKE_WINDOWS_WORK_ROOT") || `C:\\crabbox\\${packageSlug(config)}`;
+			return [
+				"--provider", "parallels",
+				"--target", "windows",
+				"--windows-mode", "normal",
+				"--parallels-source", vm,
+				"--parallels-source-snapshot", snapshot,
+				"--parallels-user", user,
+				"--parallels-work-root", workRoot,
+			];
+		}
+		default:
+			throw new Error(`unknown platform smoke target: ${targetName}`);
+	}
+}
+
+export function leaseIdFor(targetName, slug) {
+	if (targetName === "macos") return "static_localhost";
+	return slug;
+}
+
+function parseLeaseId(text) {
+	return text.match(/\bleased\s+(\S+)/)?.[1]
+		?? text.match(/\blease=(\S+)/)?.[1]
+		?? null;
+}
+
+export function execCrabbox(args, options = {}) {
+	return new Promise((resolvePromise) => {
+		const child = spawn(crabboxBin(), args, {
+			stdio: ["ignore", "pipe", "pipe"],
+			env: { ...process.env, CRABBOX_SYNC_GIT_SEED: "false", ...options.env },
+		});
+		const stdout = [];
+		const stderr = [];
+		let timeout;
+		let killTimeout;
+		if (options.timeout) {
+			timeout = setTimeout(() => {
+				stderr.push(Buffer.from(`\n[platform-smoke] crabbox timed out after ${options.timeout}ms\n`));
+				try { child.kill("SIGTERM"); } catch {}
+				killTimeout = setTimeout(() => {
+					try { child.kill("SIGKILL"); } catch {}
+				}, 10_000);
+			}, options.timeout);
+		}
+		child.stdout.on("data", (chunk) => stdout.push(chunk));
+		child.stderr.on("data", (chunk) => stderr.push(chunk));
+		child.on("error", (error) => {
+			if (timeout) clearTimeout(timeout);
+			if (killTimeout) clearTimeout(killTimeout);
+			resolvePromise({ stdout: Buffer.concat(stdout).toString(), stderr: `${Buffer.concat(stderr).toString()}${error.message}\n`, code: 1, signal: null });
+		});
+		child.on("close", (code, signal) => {
+			if (timeout) clearTimeout(timeout);
+			if (killTimeout) clearTimeout(killTimeout);
+			resolvePromise({ stdout: Buffer.concat(stdout).toString(), stderr: Buffer.concat(stderr).toString(), code: code ?? (signal ? 1 : 0), signal });
+		});
+	});
+}
+
+function isRetryableWarmupFailure(targetName, result) {
+	if (targetName !== "windows-native" || result.code === 0) return false;
+	return /Could not create a linked clone of the virtual hard disk|due to an internal error|context canceled|timed out after 300000ms/i.test(`${result.stdout}\n${result.stderr}`);
+}
+
+export async function warmupLease(targetName, slug, config = {}) {
+	const args = ["warmup", ...buildTargetBaseArgs(targetName, config), "--slug", slug, "--keep"];
+	let result;
+	for (let attempt = 1; attempt <= 2; attempt += 1) {
+		console.log(`  [crabbox] ${args.join(" ")}${attempt > 1 ? ` (retry ${attempt})` : ""}`);
+		result = await execCrabbox(args, { timeout: 300_000 });
+		if (!isRetryableWarmupFailure(targetName, result)) break;
+		await cleanupStaleTargetState(targetName, config);
+	}
+	return {
+		...result,
+		ok: result.code === 0,
+		leaseId: parseLeaseId(`${result.stdout}\n${result.stderr}`) ?? leaseIdFor(targetName, slug),
+	};
+}
+
+export async function runOnLease(targetName, leaseId, command, options = {}) {
+	const args = ["run", ...buildTargetBaseArgs(targetName, options.config ?? {}), "--id", leaseId];
+	for (const name of options.allowEnv ?? []) {
+		args.push("--allow-env", name);
+	}
+	if (options.sync === false) args.push("--no-sync");
+	else args.push("--fresh-sync");
+	args.push("--shell", command);
+	console.log(`  [crabbox] run ${targetName} ${options.sync === false ? "--no-sync" : "--fresh-sync"}`);
+	return execCrabbox(args, { timeout: options.timeout ?? 900_000 });
+}
+
+export async function stopLease(targetName, leaseId, config = {}) {
+	const args = ["stop", ...buildTargetBaseArgs(targetName, config), "--id", leaseId];
+	console.log(`  [crabbox] ${args.join(" ")}`);
+	return execCrabbox(args, { timeout: 90_000 });
+}
+
+export async function cleanupStaleTargetState(targetName, config = {}) {
+	if (targetName === "macos") return null;
+	const args = ["cleanup", ...buildTargetBaseArgs(targetName, config)];
+	console.log(`  [crabbox] ${args.join(" ")}`);
+	return execCrabbox(args, { timeout: 120_000 });
+}

package/scripts/platform-smoke/doctor.mjs

@@ -0,0 +1,307 @@
+/** Platform smoke doctor. Fails before target runs when Crabbox/platform setup is missing. */
+
+import { execFileSync, execSync } from "node:child_process";
+import { accessSync, constants, mkdirSync, unlinkSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+function env(name) {
+	return process.env[name] ?? "";
+}
+
+function ok(label) {
+	console.log(`  ✓ ${label}`);
+}
+
+function warn(label) {
+	console.log(`  ⚠ ${label}`);
+}
+
+function fail(label, failures) {
+	console.error(`  ✗ ${label}`);
+	failures.count += 1;
+}
+
+function silent(cmd, args, options = {}) {
+	try {
+		return execFileSync(cmd, args, { timeout: 20_000, stdio: "pipe", ...options }).toString().trim();
+	} catch {
+		return null;
+	}
+}
+
+function shell(command, options = {}) {
+	try {
+		return execSync(command, { timeout: 20_000, stdio: "pipe", ...options }).toString().trim();
+	} catch {
+		return null;
+	}
+}
+
+function hasCommand(name) {
+	return silent("which", [name]) !== null;
+}
+
+function commandPath(name) {
+	return silent("which", [name]);
+}
+
+function parseVersion(version) {
+	const match = String(version).match(/\d+(?:\.\d+){0,2}/);
+	return match ? match[0].split(".").map((part) => Number(part)) : null;
+}
+
+function versionAtLeast(actual, minimum) {
+	const parsedActual = parseVersion(actual);
+	const parsedMinimum = parseVersion(minimum);
+	if (!parsedActual || !parsedMinimum) return false;
+	for (let index = 0; index < Math.max(parsedActual.length, parsedMinimum.length); index += 1) {
+		const a = parsedActual[index] ?? 0;
+		const b = parsedMinimum[index] ?? 0;
+		if (a > b) return true;
+		if (a < b) return false;
+	}
+	return true;
+}
+
+function isForbiddenProjectPath(path) {
+	return /(^|\/)\.env(?:\..*)?$/.test(path)
+		|| /(^|\/)[^/]+\.tgz$/.test(path)
+		|| /(^|\/)\.artifacts(?:\/|$)/.test(path)
+		|| /(^|\/)\.crabbox(?:\/|$)/.test(path)
+		|| /(^|\/)\.debug(?:\/|$)/.test(path)
+		|| /(^|\/)\.platform-smoke-runs(?:\/|$)/.test(path);
+}
+
+function npmPackFiles() {
+	const output = silent("npm", ["pack", "--dry-run", "--json"]);
+	if (!output) return null;
+	try {
+		const parsed = JSON.parse(output);
+		return parsed[0]?.files?.map((file) => file.path) ?? [];
+	} catch {
+		return null;
+	}
+}
+
+function checkForbiddenProjectFiles(failures) {
+	const tracked = shell("git ls-files")?.split(/\r?\n/).filter(Boolean) ?? [];
+	const trackedForbidden = tracked.filter(isForbiddenProjectPath);
+	if (trackedForbidden.length === 0) ok("tracked source files exclude forbidden local artifacts");
+	else fail(`forbidden tracked source path(s): ${trackedForbidden.join(", ")}`, failures);
+
+	const localForbidden = shell("find . -maxdepth 2 \\( -name '.env' -o -name '.env.*' -o -name '*.tgz' \\) -not -path './node_modules/*' 2>/dev/null")
+		?.split(/\r?\n/).filter(Boolean) ?? [];
+	if (localForbidden.length === 0) ok("no local .env or package tarball artifacts at repo top level");
+	else fail(`forbidden local artifact(s): ${localForbidden.join(", ")}`, failures);
+
+	const packFiles = npmPackFiles();
+	if (!packFiles) {
+		fail("could not inspect npm pack contents", failures);
+		return;
+	}
+	const packedForbidden = packFiles.filter(isForbiddenProjectPath);
+	if (packedForbidden.length === 0) ok("npm package excludes forbidden local artifacts");
+	else fail(`forbidden npm package path(s): ${packedForbidden.join(", ")}`, failures);
+}
+
+function crabboxProviders(cbox) {
+	const output = silent(cbox, ["providers"]);
+	if (!output) return [];
+	return output.split(/\r?\n/)
+		.filter((line) => /^\S/.test(line))
+		.map((line) => line.trim().split(/\s+/)[0])
+		.filter(Boolean);
+}
+
+function checkRequiredProviders(cbox, failures) {
+	const providers = crabboxProviders(cbox);
+	if (providers.length === 0) {
+		fail("could not read crabbox providers", failures);
+		return;
+	}
+	for (const provider of ["ssh", "local-container", "parallels"]) {
+		if (providers.includes(provider)) ok(`crabbox provider available: ${provider}`);
+		else fail(`crabbox provider missing: ${provider}`, failures);
+	}
+}
+
+function checkCrabboxProvider(cbox, args, label, failures) {
+	const output = silent(cbox, ["doctor", ...args, "--json"]);
+	if (!output) {
+		fail(`${label} crabbox doctor failed`, failures);
+		return;
+	}
+	try {
+		const parsed = JSON.parse(output);
+		if (parsed.ok) ok(`${label} provider OK`);
+		else fail(`${label} provider not ready: ${parsed.error ?? "unknown error"}`, failures);
+	} catch {
+		warn(`${label} provider returned non-JSON doctor output`);
+	}
+}
+
+function checkAgentBrowserVersion(expectedVersion, failures, command = "agent-browser") {
+	const version = shell(`${command} --version`);
+	if (!version) {
+		fail(`${command} not found or did not report a version`, failures);
+		return;
+	}
+	const firstLine = version.split(/\r?\n/)[0];
+	if (!expectedVersion || firstLine.includes(expectedVersion)) ok(`${command}: ${firstLine}`);
+	else fail(`${command} version ${firstLine} does not match expected ${expectedVersion}`, failures);
+}
+
+export async function runDoctor(config) {
+	const failures = { count: 0 };
+	const packageName = config?.packageName ?? "pi-agent-browser-native";
+	const artifactRoot = config?.artifactRoot ?? ".artifacts/platform-smoke";
+	const nodeMajor = config?.nodeValidationMajor ?? 22;
+	const agentBrowserVersion = config?.agentBrowserVersion;
+
+	console.log("\n── Platform smoke config ──");
+	ok(`package: ${packageName}`);
+	ok(`targets: ${(config?.requiredTargets ?? []).join(", ")}`);
+	ok(`suites: ${(config?.requiredSuites ?? []).join(", ")}`);
+	ok(`agent-browser baseline: ${agentBrowserVersion ?? "not configured"}`);
+
+	console.log("\n── Crabbox binary ──");
+	const cbox = env("PLATFORM_SMOKE_CRABBOX") || "crabbox";
+	const cboxPath = env("PLATFORM_SMOKE_CRABBOX") || commandPath("crabbox");
+	if (!cboxPath) {
+		fail("crabbox not found on PATH; install with Homebrew or set PLATFORM_SMOKE_CRABBOX", failures);
+	} else {
+		if (env("PLATFORM_SMOKE_CRABBOX")) {
+			try {
+				accessSync(cboxPath, constants.X_OK);
+				ok(`binary: ${cboxPath}`);
+			} catch {
+				fail(`${cboxPath} is not executable`, failures);
+			}
+		} else {
+			ok(`binary: ${cboxPath}`);
+		}
+		const version = silent(cbox, ["--version"]);
+		if (version) {
+			const displayVersion = version.split(/\r?\n/)[0];
+			ok(`version: ${displayVersion}`);
+			const minVersion = config?.requiredCrabbox?.minVersion;
+			if (minVersion) {
+				if (versionAtLeast(displayVersion, minVersion)) ok(`version ${displayVersion} >= ${minVersion}`);
+				else fail(`Crabbox version ${displayVersion} < ${minVersion}`, failures);
+			}
+		} else {
+			fail("could not read Crabbox version", failures);
+		}
+	}
+
+	console.log("\n── Host tools ──");
+	for (const [name, command] of [["node", "node --version"], ["npm", "npm --version"], ["git", "git --version"], ["tar", "tar --version"]]) {
+		const output = shell(command);
+		if (!output) fail(`${name} not found`, failures);
+		else ok(`${name}: ${output.split(/\r?\n/)[0]}`);
+	}
+	const localNode = shell("node --version");
+	const localNodeMajor = Number(localNode?.replace(/^v/, "").split(".")[0] ?? 0);
+	if (localNodeMajor >= nodeMajor) ok(`host Node major ${localNodeMajor} >= ${nodeMajor}`);
+	else fail(`host Node major ${localNodeMajor || "unknown"} < ${nodeMajor}`, failures);
+	checkAgentBrowserVersion(agentBrowserVersion, failures);
+
+	console.log("\n── Crabbox providers ──");
+	if (cboxPath) {
+		checkRequiredProviders(cbox, failures);
+		const ubuntuImage = env("PLATFORM_SMOKE_UBUNTU_IMAGE") || config?.ubuntuContainerImage || "pi-agent-browser-native-platform:node24-agent-browser0.27.1";
+		checkCrabboxProvider(cbox, ["--provider", "local-container", "--local-container-image", ubuntuImage], "ubuntu local-container", failures);
+		const macUser = env("PLATFORM_SMOKE_MAC_USER") || env("USER");
+		const macHost = env("PLATFORM_SMOKE_MAC_HOST") || "localhost";
+		const macRoot = env("PLATFORM_SMOKE_MAC_WORK_ROOT") || `/Users/${macUser}/crabbox/${packageName}`;
+		checkCrabboxProvider(cbox, ["--provider", "ssh", "--target", "macos", "--static-host", macHost, "--static-user", macUser, "--static-port", "22", "--static-work-root", macRoot], "macOS ssh", failures);
+	}
+
+	console.log("\n── Docker / Ubuntu ──");
+	const dockerVersion = shell("docker info --format '{{.ServerVersion}}'");
+	if (dockerVersion) ok(`Docker ${dockerVersion}`);
+	else fail("Docker is not available or not running", failures);
+	const ubuntuImage = env("PLATFORM_SMOKE_UBUNTU_IMAGE") || config?.ubuntuContainerImage || "pi-agent-browser-native-platform:node24-agent-browser0.27.1";
+	ok(`Ubuntu image: ${ubuntuImage}`);
+
+	console.log("\n── macOS SSH ──");
+	const sshUser = env("PLATFORM_SMOKE_MAC_USER") || env("USER");
+	const sshHost = env("PLATFORM_SMOKE_MAC_HOST") || "localhost";
+	const sshProbe = shell(`ssh -o BatchMode=yes -o ConnectTimeout=5 -o StrictHostKeyChecking=no ${sshUser}@${sshHost} 'node --version && npm --version && git --version && agent-browser --version'`);
+	if (sshProbe) {
+		ok(`SSH ${sshUser}@${sshHost}: ${sshProbe.split(/\r?\n/).join(" | ")}`);
+		if (agentBrowserVersion && !sshProbe.includes(agentBrowserVersion)) fail(`macOS SSH agent-browser does not match expected ${agentBrowserVersion}`, failures);
+	} else {
+		fail(`SSH probe failed for ${sshUser}@${sshHost}`, failures);
+	}
+
+	if ((config?.requiredTargets ?? []).includes("windows-native")) {
+		console.log("\n── Windows native / Parallels ──");
+		if (!hasCommand("prlctl")) {
+			fail("prlctl not found", failures);
+		} else {
+			ok("prlctl found");
+			const vmName = env("PLATFORM_SMOKE_WINDOWS_VM") || "pi-extension-windows-template";
+			const snapshot = env("PLATFORM_SMOKE_WINDOWS_SNAPSHOT") || "crabbox-ready";
+			const user = env("PLATFORM_SMOKE_WINDOWS_USER") || env("USER");
+			const workRoot = env("PLATFORM_SMOKE_WINDOWS_WORK_ROOT") || `C:\\crabbox\\${packageName}`;
+			const list = shell("prlctl list -a --no-header 2>/dev/null");
+			if (!list) {
+				fail("prlctl list returned no VMs", failures);
+			} else if (!list.includes(vmName)) {
+				fail(`Windows VM ${vmName} not found`, failures);
+			} else {
+				ok(`Windows VM ${vmName} found`);
+				const status = shell(`prlctl status "${vmName.replace(/"/g, "\\\"")}" 2>/dev/null`);
+				if (/\bstopped\b/i.test(status ?? "")) ok(`Windows source VM ${vmName} is stopped`);
+				else fail(`Windows source VM ${vmName} must be stopped for forkable snapshot use; current status: ${status ?? "unknown"}`, failures);
+				const snapshotsJson = shell(`prlctl snapshot-list "${vmName.replace(/"/g, "\\\"")}" -j 2>/dev/null`);
+				let snapshotMatch = null;
+				try {
+					const snapshots = JSON.parse(snapshotsJson ?? "{}");
+					snapshotMatch = Object.entries(snapshots).find(([id, data]) => id === snapshot || data?.name === snapshot);
+				} catch {
+					// Fall through to the failure below.
+				}
+				if (snapshotMatch) {
+					ok(`snapshot ${snapshot} found`);
+					const snapshotState = snapshotMatch[1]?.state ?? "unknown";
+					if (snapshotState === "poweroff") ok(`snapshot ${snapshot} state is poweroff`);
+					else fail(`snapshot ${snapshot} must be poweroff; current snapshot state: ${snapshotState}`, failures);
+				} else {
+					fail(`snapshot ${snapshot} not found on ${vmName}`, failures);
+				}
+				checkCrabboxProvider(cbox, ["--provider", "parallels", "--target", "windows", "--windows-mode", "normal", "--parallels-source", vmName, "--parallels-source-snapshot", snapshot, "--parallels-user", user, "--parallels-work-root", workRoot], "windows parallels", failures);
+			}
+		}
+	} else {
+		console.log("\n── Windows native / Parallels ──");
+		warn("windows-native is not listed in requiredTargets for this configuration");
+	}
+
+	console.log("\n── Artifact root ──");
+	const artRoot = resolve(process.cwd(), artifactRoot);
+	try {
+		mkdirSync(artRoot, { recursive: true });
+		const probe = resolve(artRoot, ".doctor-write-test");
+		writeFileSync(probe, "ok");
+		unlinkSync(probe);
+		ok(`writable: ${artRoot}`);
+	} catch (error) {
+		fail(`artifact root not writable: ${error.message}`, failures);
+	}
+
+	console.log("\n── Repository hygiene ──");
+	const status = shell("git status --short");
+	if (status) warn(`${status.split(/\r?\n/).length} uncommitted change(s) recorded for smoke evidence`);
+	else ok("git status clean");
+	checkForbiddenProjectFiles(failures);
+
+	console.log(`\n=== Results: ${failures.count} failure(s) ===`);
+	if (failures.count > 0) {
+		console.log("Fix doctor failures before running smoke:platform:all.");
+		process.exitCode = 1;
+	} else {
+		console.log("Platform smoke setup is ready.");
+	}
+}

package/scripts/platform-smoke/linux-image/Dockerfile

@@ -0,0 +1,23 @@
+# Local Crabbox Ubuntu/Linux target image for pi-agent-browser-native platform smoke.
+# Build with:
+#   docker build -t pi-agent-browser-native-platform:node24-agent-browser0.27.1 \
+#     --build-arg AGENT_BROWSER_VERSION=0.27.1 \
+#     -f scripts/platform-smoke/linux-image/Dockerfile .
+
+FROM node:24-bookworm
+
+ARG AGENT_BROWSER_VERSION=0.27.1
+
+USER root
+RUN apt-get update \
+	&& apt-get install -y --no-install-recommends ca-certificates chromium fonts-liberation git openssh-client tar \
+	&& npm install -g "agent-browser@${AGENT_BROWSER_VERSION}" \
+	&& groupadd -g 1002 circleci \
+	&& useradd -m -u 1001 -g 1002 -s /bin/bash circleci \
+	&& mkdir -p /work/crabbox /home/circleci/.cache \
+	&& chown -R circleci:circleci /work /home/circleci \
+	&& rm -rf /var/lib/apt/lists/*
+
+USER circleci
+ENV AGENT_BROWSER_EXECUTABLE_PATH=/usr/bin/chromium
+ENV AGENT_BROWSER_PLATFORM_SMOKE_IMAGE=1