pi-agent-browser-native 0.2.38 → 0.2.39

package/extensions/agent-browser/lib/process.ts

@@ -1,15 +1,16 @@
 /**
  * Purpose: Execute the upstream agent-browser binary for the pi-agent-browser extension.
- * Responsibilities: Spawn the agent-browser subprocess without a shell, forward a curated environment surface, stream optional stdin, bound in-memory output buffering, spill oversized stdout safely to a private temp file under a disk budget, and honor abort signals.
+ * Responsibilities: Spawn the agent-browser subprocess, forward a curated environment surface, stream optional stdin, bound in-memory output buffering, spill oversized stdout safely to a private temp file under a disk budget, and honor abort signals.
  * Scope: Process execution only; argument planning, output formatting, and pi tool registration live elsewhere.
  * Usage: Called by the extension tool after argument validation and session planning are complete.
- * Invariants/Assumptions: The binary name is always `agent-browser`, the wrapper never shells out, and callers handle semantic success/error interpretation.
+ * Invariants/Assumptions: The binary name is always `agent-browser`; Windows routes through PowerShell to invoke npm launchers with escaped argv; callers handle semantic success/error interpretation.
  */
 
 import { type ChildProcessWithoutNullStreams, spawn } from "node:child_process";
 import { chmod, mkdir } from "node:fs/promises";
 import { env as processEnv, platform as processPlatform } from "node:process";
 
+import { GLOBAL_BOOLEAN_FLAGS_WITH_OPTIONAL_VALUES, GLOBAL_VALUE_FLAGS, getFlagName } from "./argv-grammar.js";
 import { openSecureTempFile, writeSecureTempChunk } from "./temp.js";
 
 const MAX_BUFFERED_STDOUT_BYTES = 512 * 1_024;
@@ -107,6 +108,52 @@ function appendTail(text: string, addition: string, maxChars: number): string {
 	return combined.length <= maxChars ? combined : combined.slice(combined.length - maxChars);
 }
 
+function quoteWindowsPowerShellArg(value: string): string {
+	return `'${value.replace(/'/g, "''")}'`;
+}
+
+const WINDOWS_LEADING_GLOBAL_VALUE_FLAGS = new Set<string>(GLOBAL_VALUE_FLAGS);
+
+/** Exported for unit tests that lock Windows launcher argv ordering. */
+export function reorderWindowsLeadingGlobalArgs(args: string[]): string[] {
+	const leadingGlobals: string[] = [];
+	let index = 0;
+	while (index < args.length && args[index]?.startsWith("-")) {
+		const token = args[index];
+		const flagName = getFlagName(token);
+		leadingGlobals.push(token);
+		index += 1;
+		if (WINDOWS_LEADING_GLOBAL_VALUE_FLAGS.has(flagName) && !token.includes("=") && index < args.length) {
+			leadingGlobals.push(args[index]);
+			index += 1;
+			continue;
+		}
+		if (GLOBAL_BOOLEAN_FLAGS_WITH_OPTIONAL_VALUES.has(flagName) && ["true", "false"].includes(args[index] ?? "")) {
+			leadingGlobals.push(args[index]);
+			index += 1;
+		}
+	}
+	if (leadingGlobals.length === 0 || index >= args.length) return args;
+	return [args[index], ...leadingGlobals, ...args.slice(index + 1)];
+}
+
+function buildAgentBrowserSpawnCommand(args: string[]): { command: string; args: string[] } {
+	if (processPlatform !== "win32") {
+		return { command: "agent-browser", args };
+	}
+	const commandLine = ["&", "agent-browser", ...reorderWindowsLeadingGlobalArgs(args).map(quoteWindowsPowerShellArg)].join(" ");
+	return { command: "powershell.exe", args: ["-NoLogo", "-NoProfile", "-ExecutionPolicy", "Bypass", "-Command", commandLine] };
+}
+
+function terminateSpawnedChild(child: ChildProcessWithoutNullStreams, signal: NodeJS.Signals): void {
+	if (processPlatform === "win32" && child.pid) {
+		const killer = spawn("taskkill.exe", ["/PID", String(child.pid), "/T", "/F"], { stdio: "ignore" });
+		killer.on("error", () => undefined);
+		killer.unref();
+	}
+	child.kill(signal);
+}
+
 /** Exported for unit tests that lock subprocess exit-code precedence. */
 export function resolveSpawnedChildExitCode(input: {
 	closeCode?: number | null;
@@ -234,17 +281,27 @@ async function ensureAgentBrowserSocketDir(socketDir: string): Promise<boolean>
 	}
 }
 
+function getChildEnvName(name: string): string | undefined {
+	if (processPlatform === "win32") {
+		const upperName = name.toUpperCase();
+		if (INHERITED_ENV_NAMES.has(upperName)) return upperName;
+		return INHERITED_ENV_PREFIXES.some((prefix) => upperName.startsWith(prefix)) ? upperName : undefined;
+	}
+	if (INHERITED_ENV_NAMES.has(name) || INHERITED_ENV_PREFIXES.some((prefix) => name.startsWith(prefix))) {
+		return name;
+	}
+	return undefined;
+}
+
 export function buildAgentBrowserProcessEnv(
 	baseEnv: NodeJS.ProcessEnv = processEnv,
 	overrides: NodeJS.ProcessEnv | undefined = undefined,
 ): NodeJS.ProcessEnv {
 	const childEnv: NodeJS.ProcessEnv = {};
 	for (const [name, value] of Object.entries(baseEnv)) {
-		if (
-			value !== undefined &&
-			(INHERITED_ENV_NAMES.has(name) || INHERITED_ENV_PREFIXES.some((prefix) => name.startsWith(prefix)))
-		) {
-			childEnv[name] = value;
+		const childName = getChildEnvName(name);
+		if (value !== undefined && childName) {
+			childEnv[childName] = value;
 		}
 	}
 
@@ -254,10 +311,11 @@ export function buildAgentBrowserProcessEnv(
 	}
 
 	for (const [name, value] of Object.entries(overrides)) {
+		const childName = getChildEnvName(name) ?? name;
 		if (value === undefined) {
-			delete childEnv[name];
+			delete childEnv[childName];
 		} else {
-			childEnv[name] = value;
+			childEnv[childName] = value;
 		}
 	}
 	clampUpstreamDefaultTimeout(childEnv);
@@ -371,7 +429,8 @@ export async function runAgentBrowserProcess(options: {
 			});
 		};
 
-		const child = spawn("agent-browser", args, {
+		const spawnCommand = buildAgentBrowserSpawnCommand(args);
+		const child = spawn(spawnCommand.command, spawnCommand.args, {
 			cwd,
 			env: buildAgentBrowserProcessEnv(processEnv, effectiveEnv),
 			stdio: ["pipe", "pipe", "pipe"],
@@ -384,15 +443,15 @@ export async function runAgentBrowserProcess(options: {
 			} else {
 				timedOut = true;
 			}
-			child.kill("SIGTERM");
+			terminateSpawnedChild(child, "SIGTERM");
 			killTimer = setTimeout(() => {
-				child.kill("SIGKILL");
+				terminateSpawnedChild(child, "SIGKILL");
 			}, 2_000);
 		};
 		const recordStdinError = (error: unknown) => {
 			const stdinError = error instanceof Error ? error : new Error(String(error));
 			const errorCode = (stdinError as NodeJS.ErrnoException).code;
-			if (errorCode === "EPIPE" || errorCode === "ERR_STREAM_DESTROYED") {
+			if (errorCode === "EPIPE" || errorCode === "EOF" || errorCode === "ERR_STREAM_DESTROYED") {
 				return;
 			}
 			if (!spawnError) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-agent-browser-native",
-  "version": "0.2.38",
+  "version": "0.2.39",
   "description": "pi extension that exposes agent-browser as a native tool for browser automation",
   "type": "module",
   "author": "Mitch Fultz (https://github.com/fitchmultz)",
@@ -31,8 +31,11 @@
   },
   "files": [
     "extensions",
+    "platform-smoke.config.mjs",
     "scripts/doctor.mjs",
     "scripts/agent-browser-capability-baseline.mjs",
+    "scripts/platform-smoke.mjs",
+    "scripts/platform-smoke",
     "README.md",
     "CHANGELOG.md",
     "LICENSE",
@@ -40,6 +43,7 @@
     "docs/COMMAND_REFERENCE.md",
     "docs/ELECTRON.md",
     "docs/RELEASE.md",
+    "docs/platform-smoke.md",
     "docs/REQUIREMENTS.md",
     "docs/SUPPORT_MATRIX.md",
     "docs/TOOL_CONTRACT.md"
@@ -71,6 +75,14 @@
     "docs": "node ./scripts/project.mjs docs",
     "doctor": "node ./scripts/doctor.mjs",
     "benchmark:agent-browser": "node ./scripts/agent-browser-efficiency-benchmark.mjs",
+    "check:platform-smoke": "node --check platform-smoke.config.mjs && node --check scripts/platform-smoke.mjs && node --check scripts/platform-smoke/doctor.mjs && node --check scripts/platform-smoke/crabbox-runner.mjs && node --check scripts/platform-smoke/targets.mjs && node --check scripts/platform-smoke/artifacts.mjs && tsx --test test/platform-smoke.test.ts",
+    "smoke:platform": "node scripts/platform-smoke.mjs",
+    "smoke:platform:doctor": "node scripts/platform-smoke.mjs doctor",
+    "smoke:platform:ubuntu-image": "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 .",
+    "smoke:platform:macos": "node scripts/platform-smoke.mjs run --target macos",
+    "smoke:platform:ubuntu": "node scripts/platform-smoke.mjs run --target ubuntu",
+    "smoke:platform:windows-native": "node scripts/platform-smoke.mjs run --target windows-native",
+    "smoke:platform:all": "npm run smoke:platform:doctor && node scripts/platform-smoke.mjs run --target macos,ubuntu,windows-native",
     "typecheck": "node ./scripts/project.mjs verify typecheck",
     "test": "tsx --test test/**/*.test.ts",
     "verify": "node ./scripts/project.mjs verify",

package/platform-smoke.config.mjs

@@ -0,0 +1,18 @@
+// Platform smoke configuration for pi-agent-browser-native.
+// Crabbox owns the target lease/sync loop; this file is the project source of truth for release-blocking platform coverage.
+
+import { CAPABILITY_BASELINE } from "./scripts/agent-browser-capability-baseline.mjs";
+
+export default {
+	packageName: "pi-agent-browser-native",
+	artifactRoot: ".artifacts/platform-smoke",
+	requiredTargets: ["macos", "ubuntu", "windows-native"],
+	requiredSuites: ["platform-build", "browser-dogfood-smoke"],
+	requiredCrabbox: {
+		install: "Homebrew package or PLATFORM_SMOKE_CRABBOX override",
+		minVersion: "0.24.0",
+	},
+	ubuntuContainerImage: "pi-agent-browser-native-platform:node24-agent-browser0.27.1",
+	nodeValidationMajor: 22,
+	agentBrowserVersion: CAPABILITY_BASELINE.targetVersion,
+};

package/scripts/agent-browser-capability-baseline.mjs

@@ -14,8 +14,8 @@ export const COMMAND_REFERENCE_BASELINE_BLOCK_IDS = Object.freeze(["upstream-bas
 
 const sourceEvidence = Object.freeze({
   repository: "vercel-labs/agent-browser",
-  upstreamHead: "4ad284890cb59564af603e6de403dd75dd19e832",
-  upstreamPackageVersion: "0.27.0",
+  upstreamHead: "90050f2913159875e2c3719e424746396ccb3cbf",
+  upstreamPackageVersion: "0.27.1",
   inspectedSources: Object.freeze([
     "agent-browser --version",
     "agent-browser --help",
@@ -349,7 +349,8 @@ const inventorySections = Object.freeze([
       "diff screenshot --baseline <file> --output <file> --threshold <0-1> --selector <sel> --full",
       "diff url <u1> <u2>",
       "diff url <u1> <u2> --screenshot --wait-until <strategy> --selector <sel> --compact --depth <n>",
-      "trace start|stop [path]",
+      "trace start",
+      "trace stop [path]",
       "profiler start|stop [path]",
       "record start <path> [url]",
       "record restart <path> [url]",
@@ -386,7 +387,8 @@ const inventorySections = Object.freeze([
       root("storage <local|session>"),
       root("diff snapshot"),
       root("diff screenshot --baseline"),
-      root("trace start|stop [path]"),
+      root("trace start"),
+      root("trace stop [path]"),
       root("profiler start|stop [path]"),
       root("record start <path> [url]"),
       root("record stop"),
@@ -422,7 +424,8 @@ const inventorySections = Object.freeze([
       ["diff help", "--threshold <0-1>"],
       ["diff help", "--wait-until <strategy>"],
       ["diff help", "diff screenshot --baseline <f>"],
-      ["trace help", "trace <operation> [path]"],
+      ["trace help", "trace start"],
+      ["trace help", "trace stop [path]"],
       ["profiler help", "--categories <list>"],
       ["record help", "record restart <path.webm> [url]"],
       ["console help", "--clear"],
@@ -703,7 +706,7 @@ const inventorySections = Object.freeze([
 ]);
 
 export const CAPABILITY_BASELINE = Object.freeze({
-  targetVersion: "0.27.0",
+  targetVersion: "0.27.1",
   sourceEvidence,
   helpCommands,
   inventorySections,

package/scripts/platform-smoke/artifacts.mjs

@@ -0,0 +1,94 @@
+/** Artifact helpers for platform smoke suites. */
+
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { relative, resolve } from "node:path";
+
+export function createSuiteDir(artifactRoot, runId, targetName, suiteName) {
+	const dir = resolve(process.cwd(), artifactRoot, runId, targetName, suiteName);
+	mkdirSync(dir, { recursive: true });
+	return dir;
+}
+
+export function writeCommand(dir, command) {
+	writeFileSync(resolve(dir, "command.txt"), `${command}\n`);
+}
+
+export function writeExitCode(dir, code, signal) {
+	writeFileSync(resolve(dir, "exit-code.txt"), `code=${code}\nsignal=${signal ?? "none"}\n`);
+}
+
+export function writeSummary(dir, data) {
+	writeFileSync(resolve(dir, "summary.json"), JSON.stringify({ ...data, writtenAt: new Date().toISOString() }, null, 2));
+}
+
+export function writeManifest(dir, expectedFiles) {
+	const present = [];
+	function walk(current) {
+		for (const entry of readdirSync(current, { withFileTypes: true })) {
+			const path = resolve(current, entry.name);
+			if (entry.isDirectory()) walk(path);
+			else if (entry.isFile()) present.push(relative(dir, path));
+		}
+	}
+	if (existsSync(dir)) walk(dir);
+	const allPresent = [...new Set([...present, "artifact-manifest.json"])].sort();
+	const manifest = {
+		expected: expectedFiles,
+		present: allPresent,
+		missing: expectedFiles.filter((file) => !allPresent.includes(file)),
+		writtenAt: new Date().toISOString(),
+	};
+	writeFileSync(resolve(dir, "artifact-manifest.json"), JSON.stringify(manifest, null, 2));
+	return manifest;
+}
+
+export function collectSecretValues(envNames, env = process.env) {
+	return [...new Set(envNames.map((name) => env[name]).filter((value) => typeof value === "string" && value.length >= 8))];
+}
+
+export function redactSecrets(text, secretValues = []) {
+	let redacted = String(text ?? "");
+	for (const secret of secretValues) {
+		redacted = redacted.split(secret).join("[REDACTED_SECRET]");
+	}
+	return redacted;
+}
+
+export function scanForSecrets(text, secretValues = []) {
+	const content = String(text ?? "");
+	const violations = [];
+	for (const secret of secretValues) {
+		if (secret && content.includes(secret)) violations.push("raw forwarded secret value");
+	}
+	for (const [pattern, label] of [
+		[/bearer\s+[A-Za-z0-9\-._~+/]{20,}=*/gi, "bearer token"],
+		[/Authorization:\s*Bearer\s+[A-Za-z0-9\-._~+/]{20,}=*/gi, "authorization header"],
+		[/(?:api[_-]?key|access[_-]?token|refresh[_-]?token|cookie)\s*[:=]\s*["']?[A-Za-z0-9_./+\-=]{20,}/gi, "token-like field"],
+	]) {
+		if (pattern.test(content)) violations.push(label);
+	}
+	return [...new Set(violations)];
+}
+
+export function scanArtifactTextFiles(dir, secretValues = []) {
+	const findings = [];
+	function walk(current) {
+		for (const entry of readdirSync(current, { withFileTypes: true })) {
+			const path = resolve(current, entry.name);
+			if (entry.isDirectory()) {
+				walk(path);
+				continue;
+			}
+			if (!entry.isFile()) continue;
+			if (!/\.(?:txt|json|jsonl|md|log|ps1|mjs|js)$/i.test(entry.name)) continue;
+			try {
+				const text = readFileSync(path, "utf8");
+				for (const violation of scanForSecrets(text, secretValues)) findings.push({ file: relative(dir, path), violation });
+			} catch {
+				// Ignore unreadable or non-text files.
+			}
+		}
+	}
+	walk(dir);
+	return findings;
+}

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 });
+}