pi-agent-browser-native 0.9.6 → 0.9.8

package/scripts/capability-samples.mjs

@@ -1,9 +1,10 @@
 /** Audited upstream source evidence and the native help commands sampled for drift. */
 export const sourceEvidence = Object.freeze({
 	repository: "vercel-labs/agent-browser",
-	upstreamHead: "aff6125c023b810ea3f2e5deec5379e9a4270bdc",
-	upstreamPackageVersion: "0.38.1",
+	upstreamHead: "1453dd37a40c730fe00f592bc32198a896ff8747",
+	upstreamPackageVersion: "0.41.0",
 	inspectedSources: Object.freeze([
+		"stock npm agent-browser@0.41.0 tarball and skill-data/",
 		"agent-browser --version",
 		"agent-browser --help",
 		"selected agent-browser <command> --help output",
@@ -20,19 +21,28 @@ export const sourceEvidence = Object.freeze({
 		"bin/agent-browser.js",
 		"cli/src/ca_bundle.rs",
 		"cli/src/commands.rs",
+		"cli/src/connection.rs",
 		"cli/src/mcp.rs",
 		"cli/src/flags.rs",
+		"cli/src/main.rs",
+		"cli/src/session_files.rs",
+		"cli/src/plugins.rs",
 		"cli/src/read.rs",
+		"cli/src/tls.rs",
 		"cli/src/doctor/ffmpeg.rs",
 		"cli/src/doctor/webgpu.rs",
 		"cli/src/native/actions.rs",
 		"cli/src/native/a11y/mod.rs",
 		"cli/src/native/browser.rs",
+		"cli/src/native/cdp/obscura.rs",
+		"cli/src/native/policy.rs",
+		"cli/src/native/providers.rs",
 		"cli/src/native/tab_binding.rs",
 		"cli/src/native/daemon.rs",
 		"cli/src/native/element.rs",
 		"cli/src/native/recording.rs",
 		"cli/src/native/snapshot.rs",
+		"cli/src/native/state.rs",
 		"cli/src/native/interaction.rs",
 		"cli/src/native/screenshot.rs",
 		"cli/src/native/stream/cdp_loop.rs",
@@ -41,13 +51,17 @@ export const sourceEvidence = Object.freeze({
 		"cli/src/native/test_fixtures/webmcp_probe.html",
 		"cli/src/native/webmcp.rs",
 		"cli/src/output.rs",
-		"docs/src/app/webgpu/page.mdx",
-		"docs/src/app/webmcp/page.mdx",
-		"docs/src/app/network/page.mdx",
-		"docs/src/app/proxy/page.mdx",
-		"docs/src/app/selectors/page.mdx",
-		"docs/src/app/skills/page.mdx",
-		"docs/src/app/commands/page.mdx",
+		"docs/content/docs/webgpu.mdx",
+		"docs/content/docs/webmcp.mdx",
+		"docs/content/docs/network.mdx",
+		"docs/content/docs/proxy.mdx",
+		"docs/content/docs/selectors.mdx",
+		"docs/content/docs/skills.mdx",
+		"docs/content/docs/commands.mdx",
+		"docs/content/docs/engines/obscura.mdx",
+		"docs/content/docs/providers/browser-use.mdx",
+		"docs/content/docs/providers/kernel.mdx",
+		"cli/tests/tls_cli.rs",
 		"skill-data/derive-client/SKILL.md",
 		"skill-data/core/SKILL.md",
 		"skill-data/core/references/video-recording.md",
@@ -60,7 +74,6 @@ export const sourceEvidence = Object.freeze({
 		"packages/@agent-browser/sandbox/README.md",
 		"packages/@agent-browser/sandbox/src/shared.ts",
 		"packages/@agent-browser/sandbox/src/vercel.ts",
-		"packages/@agent-browser/sandbox/src/eve.ts",
 	]),
 });
 

package/scripts/platform-smoke/commands.mjs

@@ -10,10 +10,19 @@ function psSingleQuote(value) {
 	return `'${String(value).replace(/'/g, "''")}'`;
 }
 
-export function buildPlatformBuildCommand(targetName, packageName, nodeValidationVersion) {
+export function buildPlatformBuildCommand(
+	targetName,
+	packageName,
+	nodeValidationVersion,
+	candidate,
+) {
 	if (platformFor(targetName) === "powershell") {
-		return `powershell.exe -NoLogo -NoProfile -ExecutionPolicy Bypass -File .\\scripts\\platform-smoke\\platform-build-windows.ps1 -PackageName ${psSingleQuote(packageName)} -NodeValidationVersion ${psSingleQuote(nodeValidationVersion)}`;
+		const candidateArgs = candidate
+			? ` -CandidatePath ${psSingleQuote(candidate.path)} -CandidateSha256 ${psSingleQuote(candidate.sha256)}`
+			: "";
+		return `powershell.exe -NoLogo -NoProfile -ExecutionPolicy Bypass -File .\\scripts\\platform-smoke\\platform-build-windows.ps1 -PackageName ${psSingleQuote(packageName)} -NodeValidationVersion ${psSingleQuote(nodeValidationVersion)}${candidateArgs}`;
 	}
+	const candidateHash = `node -e 'process.stdout.write(require("node:crypto").createHash("sha256").update(require("node:fs").readFileSync(process.argv[1])).digest("hex"))' "$PACK_FILE"`;
 	return [
 		`echo "Starting platform-build in $(pwd) at $(date -u +%Y-%m-%dT%H:%M:%SZ)"`,
 		`RUN_ROOT=".platform-smoke-runs/platform-build-$(date -u +%Y%m%dT%H%M%SZ)-$$"`,
@@ -37,11 +46,21 @@ export function buildPlatformBuildCommand(targetName, packageName, nodeValidatio
 		`cat "$PACK_DIR/npm-pack.stderr.txt"`,
 		`PACK_FILE="$PACK_DIR/$PACK_TARBALL"`,
 		`echo "PLATFORM_NPM_PACK_EXIT=$PACK_EXIT"`,
+		...(candidate
+			? [
+					`CANDIDATE_EXIT=0`,
+					`CANDIDATE_SOURCE=${shellQuote(candidate.path)}`,
+					`PACK_FILE="$PACK_DIR/release-candidate.tgz"`,
+					`if cp "$SOURCE_ROOT/$CANDIDATE_SOURCE" "$PACK_FILE"; then CANDIDATE_BEFORE=$(${candidateHash}); else CANDIDATE_BEFORE=""; fi`,
+					`echo "PLATFORM_CANDIDATE_SHA256_BEFORE=$CANDIDATE_BEFORE"`,
+					`if [ "$CANDIDATE_BEFORE" != ${shellQuote(candidate.sha256)} ]; then CANDIDATE_EXIT=1; fi`,
+				]
+			: []),
 		`echo "PLATFORM_PACKED_TARBALL=$PACK_FILE"`,
 		`PI_CLI="$SOURCE_ROOT/node_modules/.bin/pi"`,
 		`if [ ! -x "$PI_CLI" ]; then PI_CLI="$(command -v pi || true)"; fi`,
 		`echo "PLATFORM_PI_CLI=$PI_CLI"`,
-		`if [ -n "$PACK_TARBALL" ] && [ -f "$PACK_FILE" ]; then (cd "$PI_PROJECT" && npm init -y >"$PACK_DIR/packed-node-install.stdout.txt" 2>"$PACK_DIR/packed-node-install.stderr.txt" && npm install --no-save "$PACK_FILE" >>"$PACK_DIR/packed-node-install.stdout.txt" 2>>"$PACK_DIR/packed-node-install.stderr.txt"); PACKED_NODE_INSTALL_EXIT=$?; else echo "missing tarball" >"$PACK_DIR/packed-node-install.stderr.txt"; PACKED_NODE_INSTALL_EXIT=1; fi`,
+		`if [ -n "$PACK_TARBALL" ] && [ -f "$PACK_FILE" ]${candidate ? ' && [ "$CANDIDATE_EXIT" -eq 0 ]' : ""}; then (cd "$PI_PROJECT" && npm init -y >"$PACK_DIR/packed-node-install.stdout.txt" 2>"$PACK_DIR/packed-node-install.stderr.txt" && npm install --no-save "$PACK_FILE" >>"$PACK_DIR/packed-node-install.stdout.txt" 2>>"$PACK_DIR/packed-node-install.stderr.txt"); PACKED_NODE_INSTALL_EXIT=$?; else echo "missing or invalid tarball" >"$PACK_DIR/packed-node-install.stderr.txt"; PACKED_NODE_INSTALL_EXIT=1; fi`,
 		`echo "PLATFORM_PACKED_NODE_INSTALL_EXIT=$PACKED_NODE_INSTALL_EXIT"`,
 		`echo "--- PACKED_NODE_INSTALL_STDOUT START ---"; cat "$PACK_DIR/packed-node-install.stdout.txt" 2>/dev/null || true; echo "--- PACKED_NODE_INSTALL_STDOUT END ---"`,
 		`echo "--- PACKED_NODE_INSTALL_STDERR START ---"; cat "$PACK_DIR/packed-node-install.stderr.txt" 2>/dev/null || true; echo "--- PACKED_NODE_INSTALL_STDERR END ---"`,
@@ -53,7 +72,14 @@ export function buildPlatformBuildCommand(targetName, packageName, nodeValidatio
 		`echo "PLATFORM_PI_LIST_EXIT=$PI_LIST_EXIT"`,
 		`echo "--- PI_LIST_STDOUT START ---"; cat "$PACK_DIR/pi-list.stdout.txt" 2>/dev/null || true; echo "--- PI_LIST_STDOUT END ---"`,
 		`echo "--- PI_LIST_STDERR START ---"; cat "$PACK_DIR/pi-list.stderr.txt" 2>/dev/null || true; echo "--- PI_LIST_STDERR END ---"`,
-		`if [ "$NODE_VERSION_EXIT" -ne 0 ] || [ "$NPM_CI_EXIT" -ne 0 ] || [ "$VERIFY_EXIT" -ne 0 ] || [ "$PACK_EXIT" -ne 0 ] || [ "$PACKED_NODE_INSTALL_EXIT" -ne 0 ] || [ "$PI_INSTALL_EXIT" -ne 0 ] || [ "$PI_LIST_EXIT" -ne 0 ]; then echo "PLATFORM_BUILD_FAILED"; exit 1; fi`,
+		...(candidate
+			? [
+					`CANDIDATE_AFTER=$(${candidateHash})`,
+					`echo "PLATFORM_CANDIDATE_SHA256_AFTER=$CANDIDATE_AFTER"`,
+					`if [ "$CANDIDATE_AFTER" != ${shellQuote(candidate.sha256)} ]; then CANDIDATE_EXIT=1; fi`,
+				]
+			: []),
+		`if [ "$NODE_VERSION_EXIT" -ne 0 ] || [ "$NPM_CI_EXIT" -ne 0 ] || [ "$VERIFY_EXIT" -ne 0 ] || [ "$PACK_EXIT" -ne 0 ] || [ "$PACKED_NODE_INSTALL_EXIT" -ne 0 ] || [ "$PI_INSTALL_EXIT" -ne 0 ] || [ "$PI_LIST_EXIT" -ne 0 ]${candidate ? ' || [ "$CANDIDATE_EXIT" -ne 0 ]' : ""}; then echo "PLATFORM_BUILD_FAILED"; exit 1; fi`,
 		`echo "PLATFORM_BUILD_OK"`,
 	].join("\n");
 }

package/scripts/platform-smoke/doctor-support.mjs

@@ -85,12 +85,21 @@ function isForbiddenProjectPath(path) {
 	);
 }
 function npmPackFiles() {
-	const output = silent("npm", ["pack", "--dry-run", "--json"]);
+	const windows = process.platform === "win32";
+	const output = silent(windows ? "npm.cmd" : "npm", ["pack", "--dry-run", "--json"], {
+		timeout: 0,
+		shell: windows,
+	});
 	if (!output) {
 		return null;
 	}
 	try {
-		return JSON.parse(output)[0]?.files?.map((file) => file.path) ?? [];
+		const parsed = JSON.parse(output);
+		const packages = Array.isArray(parsed) ? parsed : Object.values(parsed);
+		if (packages.length !== 1 || !Array.isArray(packages[0]?.files)) {
+			return null;
+		}
+		return packages[0].files.map((file) => file.path);
 	} catch {
 		return null;
 	}

package/scripts/platform-smoke/doctor-windows.mjs

@@ -183,7 +183,7 @@ export function checkWindows({
 }) {
 	console.log("\n── Windows native / Parallels ──");
 	if (!(config?.requiredTargets ?? []).includes("windows-native")) {
-		report.warn("windows-native is not listed in requiredTargets for this configuration");
+		report.warn("windows-native not selected (best-effort); setup not checked, not a pass");
 		return;
 	}
 	if (!commandPath("prlctl")) {

package/scripts/platform-smoke/doctor.mjs

@@ -51,13 +51,19 @@ function crabboxProviders(cbox) {
 		.filter(Boolean);
 }
 
-function checkRequiredProviders(cbox, report) {
+function checkRequiredProviders(cbox, config, report) {
 	const providers = crabboxProviders(cbox);
 	if (providers.length === 0) {
 		report.fail("could not read crabbox providers");
 		return;
 	}
-	for (const provider of ["ssh", "local-container", "parallels"]) {
+	const providersByTarget = {
+		macos: "ssh",
+		ubuntu: "local-container",
+		"windows-native": "parallels",
+	};
+	for (const target of config.requiredTargets) {
+		const provider = providersByTarget[target];
 		if (providers.includes(provider)) {
 			report.ok(`crabbox provider available: ${provider}`);
 		} else {
@@ -163,13 +169,18 @@ function macSettings(config, packageName) {
 }
 
 function checkProviders(cbox, config, settings, report) {
-	checkRequiredProviders(cbox, report);
-	checkCrabboxProvider(
-		cbox,
-		["--provider", "local-container", "--local-container-image", settings.ubuntuImage],
-		"ubuntu local-container",
-		report,
-	);
+	checkRequiredProviders(cbox, config, report);
+	if (config.requiredTargets.includes("ubuntu")) {
+		checkCrabboxProvider(
+			cbox,
+			["--provider", "local-container", "--local-container-image", settings.ubuntuImage],
+			"ubuntu local-container",
+			report,
+		);
+	}
+	if (!config.requiredTargets.includes("macos")) {
+		return;
+	}
 	const mac = macSettings(config, settings.packageName);
 	checkCrabboxProvider(
 		cbox,
@@ -251,8 +262,12 @@ export async function runDoctor(config) {
 	if (cboxPath) {
 		checkProviders(cbox, config, { packageName, ubuntuImage }, report);
 	}
-	checkDocker(ubuntuImage, report);
-	checkMacSsh(config, packageName, report);
+	if (config.requiredTargets.includes("ubuntu")) {
+		checkDocker(ubuntuImage, report);
+	}
+	if (config.requiredTargets.includes("macos")) {
+		checkMacSsh(config, packageName, report);
+	}
 	checkWindows({
 		cbox,
 		config,

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

@@ -1,6 +1,6 @@
 # Local Crabbox Ubuntu/Linux target image for pi-agent-browser-native platform smoke.
-# Build with npm run smoke:platform:ubuntu-image so the agent-browser version
-# comes from scripts/agent-browser-capability-baseline.mjs. The Go toolchain
+# Build with npm run smoke:platform:ubuntu-image to check the latest stock
+# agent-browser against the audited capability baseline. The Go toolchain
 # matches the version scripts/prepare-quality-checker.mjs selects for the
 # corrected quality checker that platform-target builds.
 
@@ -15,7 +15,10 @@ COPY --from=go /usr/local/go /usr/local/go
 RUN ln -s /usr/local/go/bin/go /usr/local/go/bin/gofmt /usr/local/bin/ \
 	&& apt-get update \
 	&& apt-get install -y --no-install-recommends ca-certificates chromium fonts-liberation git libvulkan1 mesa-vulkan-drivers openssh-client tar xvfb \
-	&& npm install -g "agent-browser@${AGENT_BROWSER_VERSION}" \
+	&& npm install -g agent-browser --allow-scripts=agent-browser \
+	&& actual="$(agent-browser --version)" \
+	&& printf 'Installed %s; audited baseline agent-browser %s\n' "$actual" "$AGENT_BROWSER_VERSION" \
+	&& test "$actual" = "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 \

package/scripts/platform-smoke/platform-build-windows.ps1

@@ -1,6 +1,8 @@
 param(
   [Parameter(Mandatory=$true)][string]$PackageName,
-  [Parameter(Mandatory=$true)][string]$NodeValidationVersion
+  [Parameter(Mandatory=$true)][string]$NodeValidationVersion,
+  [string]$CandidatePath = "",
+  [string]$CandidateSha256 = ""
 )
 
 $ErrorActionPreference = "Continue"
@@ -40,6 +42,17 @@ $PackTarball = ($PackOutput | Select-Object -Last 1)
 $PackFile = if ($PackTarball) { Join-Path $PackDir $PackTarball } else { "" }
 if (Test-Path $PackStderr) { Get-Content -Raw $PackStderr }
 Write-Output "PLATFORM_NPM_PACK_EXIT=$PackExit"
+$CandidateExit = 0
+if ($CandidatePath) {
+  $PackFile = Join-Path $PackDir "release-candidate.tgz"
+  $CandidateBefore = ""
+  try {
+    Copy-Item -LiteralPath (Join-Path $SourceRoot $CandidatePath) -Destination $PackFile -ErrorAction Stop
+    $CandidateBefore = (Get-FileHash -LiteralPath $PackFile -Algorithm SHA256 -ErrorAction Stop).Hash.ToLowerInvariant()
+  } catch { $CandidateExit = 1 }
+  Write-Output "PLATFORM_CANDIDATE_SHA256_BEFORE=$CandidateBefore"
+  if ($CandidateBefore -ne $CandidateSha256) { $CandidateExit = 1 }
+}
 Write-Output "PLATFORM_PACKED_TARBALL=$PackFile"
 
 $PiCli = Join-Path $SourceRoot "node_modules/.bin/pi.cmd"
@@ -49,7 +62,7 @@ Write-Output "PLATFORM_PI_CLI=$PiCli"
 
 $PackedNodeInstallStdout = Join-Path $PackDir "packed-node-install.stdout.txt"
 $PackedNodeInstallStderr = Join-Path $PackDir "packed-node-install.stderr.txt"
-if ($PackFile -and (Test-Path $PackFile)) {
+if ($CandidateExit -eq 0 -and $PackFile -and (Test-Path $PackFile)) {
   Push-Location $PiProject
   & npm init -y >$PackedNodeInstallStdout 2>$PackedNodeInstallStderr
   if ($LASTEXITCODE -eq 0) {
@@ -94,7 +107,14 @@ Write-Output "PLATFORM_PI_LIST_EXIT=$PiListExit"
 Write-Section "PI_LIST_STDOUT" $PiListStdout
 Write-Section "PI_LIST_STDERR" $PiListStderr
 
-if ($NodeVersionExit -ne 0 -or $NpmCiExit -ne 0 -or $VerifyExit -ne 0 -or $PackExit -ne 0 -or $PackedNodeInstallExit -ne 0 -or $PiInstallExit -ne 0 -or $PiListExit -ne 0) {
+if ($CandidatePath) {
+  $CandidateAfter = ""
+  try { $CandidateAfter = (Get-FileHash -LiteralPath $PackFile -Algorithm SHA256 -ErrorAction Stop).Hash.ToLowerInvariant() } catch { $CandidateExit = 1 }
+  Write-Output "PLATFORM_CANDIDATE_SHA256_AFTER=$CandidateAfter"
+  if ($CandidateAfter -ne $CandidateSha256) { $CandidateExit = 1 }
+}
+
+if ($NodeVersionExit -ne 0 -or $NpmCiExit -ne 0 -or $VerifyExit -ne 0 -or $PackExit -ne 0 -or $PackedNodeInstallExit -ne 0 -or $PiInstallExit -ne 0 -or $PiListExit -ne 0 -or $CandidateExit -ne 0) {
   Write-Output "PLATFORM_BUILD_FAILED"
   exit 1
 }

package/scripts/platform-smoke/suite-checks.mjs

@@ -28,7 +28,7 @@ export function commonChecks(result, secretViolations, stopResult) {
 	];
 }
 
-export function platformBuildChecks(config, result) {
+export function platformBuildChecks(config, result, candidate) {
 	const stdout = result.stdout;
 	const listOutput = section(stdout, "PI_LIST_STDOUT");
 	const nodeVersion = marker(stdout, "PLATFORM_NODE_VERSION");
@@ -48,6 +48,16 @@ export function platformBuildChecks(config, result) {
 				/PLATFORM_NPM_PACK_EXIT=0/.test(stdout) &&
 				marker(stdout, "PLATFORM_PACKED_TARBALL").length > 0,
 		},
+		...(candidate
+			? [
+					{
+						id: "release-candidate-sha256",
+						fn: () =>
+							marker(stdout, "PLATFORM_CANDIDATE_SHA256_BEFORE") === candidate.sha256 &&
+							marker(stdout, "PLATFORM_CANDIDATE_SHA256_AFTER") === candidate.sha256,
+					},
+				]
+			: []),
 		{ id: "packed-node-install", fn: () => /PLATFORM_PACKED_NODE_INSTALL_EXIT=0/.test(stdout) },
 		{ id: "pi-install-local-package", fn: () => /PLATFORM_PI_INSTALL_EXIT=0/.test(stdout) },
 		{

package/scripts/platform-smoke/targets.mjs

@@ -32,6 +32,7 @@ function suiteDefinition({ config, targetName, suiteName, leaseSession }) {
 				targetName,
 				config.packageName,
 				config.nodeValidationVersion,
+				leaseSession?.candidate,
 			),
 			timeout: 1_500_000,
 			metadata: { suiteName, modelCalls: 0 },
@@ -48,7 +49,7 @@ function suiteDefinition({ config, targetName, suiteName, leaseSession }) {
 			extract: (suiteDir, result, secretValues) => {
 				writePlatformExtracts(suiteDir, result.stdout, secretValues);
 			},
-			checks: (result) => platformBuildChecks(config, result),
+			checks: (result) => platformBuildChecks(config, result, leaseSession?.candidate),
 		};
 	}
 	if (suiteName === "browser-dogfood-smoke") {
@@ -150,7 +151,7 @@ export async function runTargetSuite({
 	return { ok: assertions.ok, suiteDir, assertions };
 }
 
-export async function runTargetSuites(config, targetName, suiteNames) {
+export async function runTargetSuites(config, targetName, suiteNames, candidate) {
 	const slug = `${config.packageName}-${targetName}`;
 	const runId = makeRunId();
 	const lease = await warmupLease(targetName, slug, config);
@@ -172,7 +173,7 @@ export async function runTargetSuites(config, targetName, suiteNames) {
 				config,
 				targetName,
 				suiteName,
-				leaseSession: { ...lease, dependenciesReady, sync },
+				leaseSession: { ...lease, dependenciesReady, sync, candidate },
 				runId,
 			});
 			results.push(result);

package/scripts/platform-smoke.mjs

@@ -5,8 +5,10 @@
  * Scope: Maintainer release verification only; target command rendering and artifact assertions live under scripts/platform-smoke/.
  */
 
+import { createHash } from "node:crypto";
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import { createRequire } from "node:module";
-import { dirname, resolve } from "node:path";
+import { basename, dirname, join, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
 const __filename = fileURLToPath(import.meta.url);
@@ -28,17 +30,17 @@ function printHelp() {
 	console.log(`Usage: node scripts/platform-smoke.mjs <command> [options]
 
 Commands:
-  doctor                     Validate Crabbox and platform prerequisites
-  run --target <names>       Run one or more comma-separated targets concurrently
-  run --suite <name>         Run one suite on all or specified targets
+  doctor [--target <names>]  Validate prerequisites for selected targets (required by default)
+  run [--target <names>]    Run required or explicitly selected targets concurrently
+  run --suite <name>         Run one suite on required or specified targets
 
 Package scripts:
   check:platform-smoke       Syntax-check harness scripts and run cheap harness invariant tests
   smoke:platform:ubuntu-image Build the local Ubuntu image used by default
-  smoke:platform:all         Runs doctor first, then the full macOS/Ubuntu/Windows matrix
+  smoke:platform:all         Runs doctor first, then required macOS/Ubuntu targets (not optional Windows)
 
 Targets:
-  macos, ubuntu, windows-native
+  macos, ubuntu (required); windows-native (explicit best-effort)
 
 Suites:
   platform-build             npm ci, npm run verify -- platform-target, npm pack, packed pi install --approve, pi list --approve
@@ -109,34 +111,75 @@ function validateNames(kind, names, allowed) {
 	}
 }
 
-async function runTargets(args) {
-	const { runTargetSuites } = await import("./platform-smoke/targets.mjs");
+function selectedTargets(args) {
 	const targets = args.target
 		? args.target
 				.split(",")
 				.map((name) => name.trim())
 				.filter(Boolean)
 		: config.requiredTargets;
+	validateNames("target", targets, [...config.requiredTargets, ...(config.optionalTargets ?? [])]);
+	if (targets.length === 0) {
+		throw new Error("Select at least one target");
+	}
+	return targets;
+}
+
+async function runTargets(args) {
+	const { runTargetSuites } = await import("./platform-smoke/targets.mjs");
+	const targets = selectedTargets(args);
 	const suites = args.suite ? [args.suite] : config.requiredSuites;
-	validateNames("target", targets, config.requiredTargets);
 	validateNames("suite", suites, config.requiredSuites);
-	const results = await Promise.all(
-		targets.map(async (targetName) => {
-			console.log(`\n=== Target: ${targetName} ===`);
-			return { targetName, result: await runTargetSuites(config, targetName, suites) };
-		}),
-	);
-	const failed = results.filter(({ result }) => !result.ok);
-	if (failed.length > 0) {
-		console.error(
-			`\nPlatform smoke failed for ${failed.map(({ targetName }) => targetName).join(", ")}. See ${config.artifactRoot}.`,
+	let stagedCandidate;
+	try {
+		const candidatePath = process.env.PI_AGENT_BROWSER_RELEASE_TARBALL;
+		if (candidatePath !== undefined && suites.includes("platform-build")) {
+			if (candidatePath.trim().length === 0) {
+				throw new Error("PI_AGENT_BROWSER_RELEASE_TARBALL must name a candidate tarball");
+			}
+			const bytes = await readFile(resolve(candidatePath));
+			const directory = await mkdtemp(resolve(process.cwd(), ".npm-release-candidate-"));
+			stagedCandidate = { directory };
+			await writeFile(join(directory, "candidate"), bytes, { flag: "wx", mode: 0o600 });
+			stagedCandidate.path = `${basename(directory)}/candidate`;
+			stagedCandidate.sha256 = createHash("sha256").update(bytes).digest("hex");
+		}
+		const settled = await Promise.allSettled(
+			targets.map(async (targetName) => {
+				console.log(`\n=== Target: ${targetName} ===`);
+				return {
+					targetName,
+					result: await runTargetSuites(config, targetName, suites, stagedCandidate),
+				};
+			}),
+		);
+		const errors = settled.filter((result) => result.status === "rejected");
+		if (errors.length > 0) {
+			const messages = errors.map((result) =>
+				result.reason instanceof Error ? result.reason.message : String(result.reason),
+			);
+			throw new AggregateError(
+				errors.map((result) => result.reason),
+				`Platform smoke could not complete: ${messages.join("; ")}`,
+			);
+		}
+		const results = settled.map((result) => result.value);
+		const failed = results.filter(({ result }) => !result.ok);
+		if (failed.length > 0) {
+			console.error(
+				`\nPlatform smoke failed for ${failed.map(({ targetName }) => targetName).join(", ")}. See ${config.artifactRoot}.`,
+			);
+			return 1;
+		}
+		console.log(
+			`\nPlatform smoke passed for ${results.map(({ targetName }) => targetName).join(", ")}.`,
 		);
-		return 1;
+		return 0;
+	} finally {
+		if (stagedCandidate) {
+			await rm(stagedCandidate.directory, { recursive: true, force: true });
+		}
 	}
-	console.log(
-		`\nPlatform smoke passed for ${results.map(({ targetName }) => targetName).join(", ")}.`,
-	);
-	return 0;
 }
 
 export async function main(argv = process.argv.slice(2)) {
@@ -151,7 +194,7 @@ export async function main(argv = process.argv.slice(2)) {
 
 	if (args.command === "doctor") {
 		const { runDoctor } = await import("./platform-smoke/doctor.mjs");
-		await runDoctor(config);
+		await runDoctor({ ...config, requiredTargets: selectedTargets(args) });
 		return process.exitCode ?? 0;
 	}