pi-oxidized 0.1.1

package/scripts/release/host.ts

@@ -0,0 +1,825 @@
+/**
+ * Host sidecar build + verification.
+ *
+ * Encapsulates the release-time host operations:
+ *   1. Compile the host deterministically: bundle with `bun build --target
+ *      bun --minify`, normalize the one photon-node `__dirname` path to the
+ *      Bun virtual filesystem root (fail closed on zero/multiple matches or
+ *      any residual checkout/home path), embed `photon_rs_bg.wasm` as a Bun
+ *      file asset, then `bun build --compile` the normalized bundle with a
+ *      target-stable output basename. When the target matches the build
+ *      machine, both stages run under the checksum-pinned official Bun
+ *      runtime so the embedded runtime shell never depends on whichever
+ *      `bun` is on PATH. The result is byte-identical across checkout paths.
+ *   2. Run the runtime-import fixture as a standalone executable, proving
+ *      the host can load an external `.ts` extension at runtime.
+ *   3. Run the photon probe (built through the identical deterministic
+ *      pipeline), proving the normalized wasm-bindgen glue reads the wasm
+ *      from the embedded `/$bunfs/root` asset.
+ *   4. Speak the JSONL `hello` handshake against the compiled sidecar to
+ *      confirm the wire protocol and compatibility version.
+ *
+ * If compile, runtime-import, or a probe fails for a target, the caller
+ * falls back to shipping the official Bun runtime + the bundled host
+ * JavaScript. If both paths fail, the release for that target fails — never
+ * embed the host into the Rust binary. Normalization failures do NOT fall
+ * back: they mean determinism can no longer be proven and must be reviewed.
+ */
+
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { copyFile, mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { homedir, tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+
+import {
+	COMPATIBILITY_VERSION,
+	MAX_FRAME_BYTES,
+	PROTOCOL_VERSION,
+} from "../../packages/pi-tui-protocol/src/index.ts";
+
+import type { CommandRunner, RunResult } from "./runner.ts";
+import { SpawnRunner } from "./runner.ts";
+import { BUN_RUNTIME_VERSION, provisionBunRuntime } from "./runtime.ts";
+import { isSupportedTarget, planFor, type TargetPlan } from "./targets.ts";
+
+/** Wire protocol version negotiated in `hello` (from pi-tui-protocol, the TS authority). */
+export const HOST_PROTOCOL_VERSION = PROTOCOL_VERSION;
+
+/** Compatibility target version (from pi-tui-protocol, the TS authority). */
+export const HOST_COMPATIBILITY_VERSION: string = COMPATIBILITY_VERSION;
+
+/** Maximum bytes of one JSONL frame line (from pi-tui-protocol, the TS authority). */
+const FRAME_MAX_BYTES = MAX_FRAME_BYTES;
+
+/** Commit `.references/pi` must be checked out at (the pinned submodule gitlink). */
+export const PINNED_REFERENCE_COMMIT = "e5e8726836465e575ca2d619db76cae4c29a1749";
+
+/** Reference monorepo packages the host compiles against. */
+const REFERENCE_PACKAGES = ["agent", "ai", "coding-agent", "tui"] as const;
+
+/**
+ * Third-party packages that must be provisioned inside the reference tree
+ * (`.references/pi/node_modules`) before the host can compile: reference
+ * source imports them, and the Node/Bun package walk starts at the importer
+ * under `.references`, never at the repo root or the host package.
+ */
+const REFERENCE_DEP_MARKERS = ["typebox", "@anthropic-ai/sdk"] as const;
+
+const SUBMODULE_REMEDY = "run `git submodule update --init .references/pi`";
+const PROVISION_REMEDY = "run `npm ci --ignore-scripts` inside .references/pi (upstream tracks package-lock.json; it has no bun.lock)";
+
+const HOST_SETUP_TIMEOUT_MS = 5 * 60_000;
+const HOST_BUILD_TIMEOUT_MS = 10 * 60_000;
+const HOST_PROBE_TIMEOUT_MS = 30_000;
+
+/**
+ * The artifact set the release script must place beside `pi`. The Rust
+ * binary resolves the host by trying, in order: `PI_EXTENSION_HOST` env,
+ * then the sibling `pi-extension-host[.exe]`, then (fallback) sibling
+ * `bun[.exe] pi-extension-host.js`.
+ */
+export type HostArtifact =
+	| { readonly kind: "compiled"; readonly binaryPath: string }
+	| {
+			readonly kind: "runtime-bundle";
+			readonly runtimePath: string;
+			readonly scriptPath: string;
+	  };
+
+/** Inputs to {@link buildHost}. */
+export interface BuildHostOptions {
+	/** Absolute path to the workspace root (contains `packages/extension-host`). */
+	readonly repoRoot: string;
+	/** Resolved release target. */
+	readonly plan: TargetPlan;
+	/** Working directory under which artifacts are emitted (a `host/` subdir is created). */
+	readonly stagingRoot: string;
+	/** Skip the host unit tests (`bun test`). */
+	readonly skipTests: boolean;
+	/** Skip the runtime-import fixture run. */
+	readonly skipRuntimeImport: boolean;
+	/** Skip the `hello` handshake against the compiled sidecar. */
+	readonly skipHandshake: boolean;
+	/** Command runner. Defaults to {@link SpawnRunner}. */
+	readonly runner?: CommandRunner;
+	/** Reference pin override (tests only). Defaults to {@link PINNED_REFERENCE_COMMIT}. */
+	readonly referencePin?: string;
+	/**
+	 * Executing Bun for the deterministic bundle/compile stages (tests only).
+	 * Defaults to the checksum-pinned official Bun runtime provisioned into
+	 * the staging dir when the target matches the build machine, else `bun`.
+	 */
+	readonly compileBun?: string;
+}
+
+/** Error raised when host build/verify fails on every available path. */
+export class HostBuildError extends Error {
+	readonly target: string;
+	constructor(target: string, message: string) {
+		super(`Host build failed for ${target}: ${message}`);
+		this.name = "HostBuildError";
+		this.target = target;
+	}
+}
+
+/** Absolute path to the host package directory inside the workspace. */
+function hostPackageDir(repoRoot: string): string {
+	return resolve(repoRoot, "packages/extension-host");
+}
+
+/** Absolute path to a per-target staging subdirectory. */
+function targetStagingDir(stagingRoot: string, plan: TargetPlan): string {
+	return resolve(stagingRoot, "host", plan.rustTarget);
+}
+
+/**
+ * Fail-closed preflight over the `.references/pi` submodule.
+ *
+ * Throws {@link HostBuildError} when the reference tree is missing, checked
+ * out at the wrong commit, labels a different compatibility version, or has
+ * not had its third-party dependencies provisioned. Every failure names its
+ * remedy; today those conditions otherwise surface only as opaque bun
+ * install/build stderr deep inside the host build.
+ */
+export function assertReferenceTree(repoRoot: string, pin: string = PINNED_REFERENCE_COMMIT): void {
+	const refDir = join(repoRoot, ".references", "pi");
+	if (!existsSync(join(refDir, "tsconfig.json"))) {
+		throw new HostBuildError(
+			refDir,
+			`reference tree is missing tsconfig.json (reference-internal module resolution depends on it); ${SUBMODULE_REMEDY}`,
+		);
+	}
+	const head = spawnSync("git", ["-C", refDir, "rev-parse", "HEAD"], { encoding: "utf8" });
+	const sha = head.status === 0 ? head.stdout.trim() : "";
+	if (sha !== pin) {
+		throw new HostBuildError(
+			refDir,
+			`reference tree is ${sha === "" ? "not a git checkout" : `at commit ${sha}`} but the pinned submodule commit is ${pin}; ${SUBMODULE_REMEDY}`,
+		);
+	}
+	for (const name of REFERENCE_PACKAGES) {
+		const pkgPath = join(refDir, "packages", name, "package.json");
+		if (!existsSync(pkgPath)) {
+			throw new HostBuildError(refDir, `reference package ${name} is missing ${pkgPath}; ${SUBMODULE_REMEDY}`);
+		}
+		const manifest = JSON.parse(readFileSync(pkgPath, "utf8")) as { version?: string };
+		if (manifest.version !== HOST_COMPATIBILITY_VERSION) {
+			throw new HostBuildError(
+				refDir,
+				`reference package ${name} declares version ${String(manifest.version)} but the host targets ${HOST_COMPATIBILITY_VERSION}; ${SUBMODULE_REMEDY}`,
+			);
+		}
+	}
+	for (const dep of REFERENCE_DEP_MARKERS) {
+		if (!existsSync(join(refDir, "node_modules", dep, "package.json"))) {
+			throw new HostBuildError(
+				refDir,
+				`reference third-party dependency ${dep} is not provisioned; ${PROVISION_REMEDY}`,
+			);
+		}
+	}
+}
+
+/**
+ * Build (and verify) the host sidecar for `plan`.
+ *
+ * Algorithm:
+ *   1. `bun install --frozen-lockfile` (host deps are source-pinned).
+ *   2. `tsc --noEmit` (host typecheck).
+ *   3. `bun test` (unless `skipTests`).
+ *   4. `bun build --compile --target <plan.bunTarget>` → sidecar binary.
+ *   5. Compile + run the runtime-import fixture (unless `skipRuntimeImport`).
+ *   6. Speak the JSONL `hello` handshake against the sidecar (unless
+ *      `skipHandshake`).
+ *
+ * If any of steps 4–6 fail, the function falls back to the runtime+bundle
+ * path: `bun build --target bun` produces `pi-extension-host.js`, and the
+ * caller must provide a sibling `bun[.exe]`. If that path also fails, the
+ * function throws {@link HostBuildError}.
+ */
+export async function buildHost(options: BuildHostOptions): Promise<HostArtifact> {
+	assertReferenceTree(options.repoRoot, options.referencePin);
+	const runner = options.runner ?? new SpawnRunner();
+	const hostDir = hostPackageDir(options.repoRoot);
+	const outDir = targetStagingDir(options.stagingRoot, options.plan);
+	await mkdir(outDir, { recursive: true });
+
+	await installHostDeps(hostDir, runner);
+	await typecheckHost(hostDir, runner);
+	if (!options.skipTests) await testHost(hostDir, runner);
+
+	const compiled = await tryCompiledPath(options, hostDir, outDir, runner);
+	if (compiled !== undefined) return compiled;
+
+	const bundled = await tryRuntimeBundlePath(options, hostDir, outDir, runner);
+	if (bundled !== undefined) return bundled;
+
+	throw new HostBuildError(
+		options.plan.rustTarget,
+		"compiled sidecar and runtime-bundle fallback both failed",
+	);
+}
+
+/** Install host dependencies with the locked file. */
+async function installHostDeps(hostDir: string, runner: CommandRunner): Promise<void> {
+	const res = await runner.run("bun", ["install", "--frozen-lockfile"], {
+		cwd: hostDir,
+		rejectOnError: false,
+		timeoutMs: HOST_SETUP_TIMEOUT_MS,
+	});
+	if (res.exitCode !== 0) {
+		throw new HostBuildError(
+			hostDir,
+			`bun install --frozen-lockfile failed (exit ${res.exitCode}); run 'bun install' in packages/extension-host and commit the refreshed lockfile. stderr=${res.stderr.slice(0, 500)}`,
+		);
+	}
+}
+
+/** Run `tsc --noEmit` against the host's `tsconfig.check.json`. */
+async function typecheckHost(hostDir: string, runner: CommandRunner): Promise<void> {
+	const res = await runner.run("bun", ["run", "check"], {
+		cwd: hostDir,
+		rejectOnError: false,
+		timeoutMs: HOST_SETUP_TIMEOUT_MS,
+	});
+	if (res.exitCode !== 0) {
+		throw new HostBuildError(
+			hostDir,
+			`host typecheck failed (exit ${res.exitCode}). stderr=${res.stderr.slice(0, 1000)}`,
+		);
+	}
+}
+
+/** Run `bun test` in the host package. */
+async function testHost(hostDir: string, runner: CommandRunner): Promise<void> {
+	const res = await runner.run("bun", ["run", "test"], {
+		cwd: hostDir,
+		rejectOnError: false,
+		timeoutMs: HOST_BUILD_TIMEOUT_MS,
+	});
+	if (res.exitCode !== 0) {
+		throw new HostBuildError(
+			hostDir,
+			`host tests failed (exit ${res.exitCode}). stderr=${res.stderr.slice(0, 1000)}`,
+		);
+	}
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Deterministic two-stage compile (bundle → normalize → compile)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Bun's virtual filesystem root inside a compiled standalone executable. */
+export const BUNFS_ROOT = "/$bunfs/root";
+
+/** Photon wasm asset embedded beside the normalized wasm-bindgen glue. */
+export const PHOTON_WASM_ASSET = "photon_rs_bg.wasm";
+
+/** Success marker printed by `fixtures/photon-probe.ts`. */
+export const PHOTON_PROBE_OK = "PHOTON_OK";
+
+/**
+ * The one CommonJS `__dirname` assignment `bun build --target bun` inlines
+ * for the photon-node wasm-bindgen glue as an absolute builder path. The
+ * glue reads `photon_rs_bg.wasm` relative to it at module init, so the raw
+ * bundle is both checkout-path-coupled and broken off the build machine.
+ */
+// Separators match `/`, `\`, or the backslash-escaped `\\` form Windows
+// builder paths take inside the bundle's JS string literal.
+const PHOTON_DIRNAME_PATTERN =
+	/var __dirname\s*=\s*"([^"]*[/\\]\\?@silvia-odwyer[/\\]\\?photon-node)"/g;
+
+/**
+ * Raised when bundle normalization cannot prove determinism. Never triggers
+ * the runtime-bundle fallback: the fallback bundle would carry the same
+ * defect, so the build must stop for review instead.
+ */
+export class BundleNormalizeError extends Error {
+	constructor(message: string) {
+		super(`Host bundle normalization failed: ${message}`);
+		this.name = "BundleNormalizeError";
+	}
+}
+
+/** Result of {@link normalizeHostBundle}. */
+export interface NormalizedBundle {
+	/** Normalized bundle text with the wasm file-asset import prepended. */
+	readonly code: string;
+	/** Absolute builder path of the photon-node package captured from the rewritten assignment (source of the wasm asset). */
+	readonly photonPackageDir: string;
+}
+
+/**
+ * Rewrite the photon-node `__dirname` assignment to {@link BUNFS_ROOT} and
+ * prove no absolute builder path survives.
+ *
+ * Fail-closed contract:
+ *   - exactly one photon `__dirname` assignment must match — zero means the
+ *     upstream dependency graph changed shape (the rewrite would silently do
+ *     nothing), multiple means the rewrite is ambiguous; both stop the build;
+ *   - after the rewrite, the bundle must not contain any `forbiddenPaths`
+ *     entry (checkout roots), `/home/`, or the builder's home directory.
+ */
+export function normalizeHostBundle(
+	bundle: string,
+	forbiddenPaths: readonly string[],
+): NormalizedBundle {
+	const matches = [...bundle.matchAll(PHOTON_DIRNAME_PATTERN)];
+	const match = matches[0];
+	if (matches.length !== 1 || match?.index === undefined) {
+		throw new BundleNormalizeError(
+			`expected exactly one photon-node __dirname assignment, found ${matches.length}; ` +
+				`the upstream dependency graph changed — review the bundle before trusting the rewrite`,
+		);
+	}
+	// Windows separators arrive backslash-escaped inside the JS string literal.
+	const photonPackageDir = (match[1] ?? "").replaceAll("\\\\", "\\");
+	const rewritten =
+		bundle.slice(0, match.index) +
+		`var __dirname="${BUNFS_ROOT}"` +
+		bundle.slice(match.index + match[0].length);
+	const forbidden = new Set<string>(["/home/", homedir()]);
+	for (const path of forbiddenPaths) {
+		forbidden.add(path);
+		// Windows absolute paths appear backslash-escaped inside JS strings.
+		forbidden.add(path.replaceAll("\\", "\\\\"));
+	}
+	for (const path of forbidden) {
+		if (path.length <= 1) continue;
+		const at = rewritten.indexOf(path);
+		if (at >= 0) {
+			const context = rewritten.slice(Math.max(0, at - 40), at + path.length + 40);
+			throw new BundleNormalizeError(
+				`normalized bundle still contains the absolute path ${path} (context: ${JSON.stringify(context)})`,
+			);
+		}
+	}
+	return {
+		code: `import "./${PHOTON_WASM_ASSET}" with {type:"file"};\n${rewritten}`,
+		photonPackageDir,
+	};
+}
+
+/** Checkout roots that must never survive into the normalized bundle. */
+function forbiddenBuildPaths(repoRoot: string, hostDir: string): string[] {
+	const paths = new Set<string>();
+	for (const path of [repoRoot, hostDir]) {
+		paths.add(path);
+		try {
+			paths.add(realpathSync(path));
+		} catch {
+			// The unresolved form is still checked; realpath is best-effort.
+		}
+	}
+	return [...paths];
+}
+
+/** The release target plan matching the build machine, when supported. */
+function buildMachinePlan(): TargetPlan | undefined {
+	const triple =
+		process.arch === "x64"
+			? process.platform === "linux"
+				? "x86_64-unknown-linux-gnu"
+				: process.platform === "darwin"
+					? "x86_64-apple-darwin"
+					: process.platform === "win32"
+						? "x86_64-pc-windows-msvc"
+						: undefined
+			: process.arch === "arm64"
+				? process.platform === "linux"
+					? "aarch64-unknown-linux-gnu"
+					: process.platform === "darwin"
+						? "aarch64-apple-darwin"
+						: undefined
+				: undefined;
+	return triple !== undefined && isSupportedTarget(triple) ? planFor(triple) : undefined;
+}
+
+/**
+ * Resolve the Bun executable for the deterministic bundle/compile stages.
+ *
+ * `bun build --compile` embeds the *executing* Bun as the runtime shell when
+ * the target matches it, so a system bun (e.g. a from-source distro build)
+ * makes the host bytes machine-coupled. We therefore always run both stages
+ * under a checksum-pinned official Bun release provisioned into the staging
+ * dir: the target's own runtime for native builds (it embeds itself), the
+ * build machine's pinned runtime for cross-compiles (Bun then downloads the
+ * official target runtime itself). Only unsupported build machines fall
+ * back to `bun` from PATH, and no pin is ever authored there.
+ */
+async function resolveCompileBun(options: BuildHostOptions, outDir: string): Promise<string> {
+	if (options.compileBun !== undefined) return options.compileBun;
+	const machinePlan = buildMachinePlan();
+	const executingPlan =
+		machinePlan?.rustTarget === options.plan.rustTarget ? options.plan : machinePlan;
+	if (executingPlan === undefined) return "bun";
+	const destination = join(outDir, executingPlan.windows ? "bun-compile.exe" : "bun-compile");
+	try {
+		await provisionBunRuntime({ plan: executingPlan, destination });
+	} catch (error) {
+		throw new HostBuildError(
+			options.plan.rustTarget,
+			`failed to provision the pinned official Bun ${BUN_RUNTIME_VERSION} compile runtime ` +
+				`(the deterministic host build must not embed an unpinned system bun): ${String(error)}`,
+		);
+	}
+	return destination;
+}
+
+/** One deterministic bundle → normalize → compile unit. */
+interface StagedCompileSpec {
+	/** Entry point, relative to the host package dir (e.g. `./src/main.ts`). */
+	readonly entry: string;
+	/** Base name for the staged `.bundle.js` / `.norm.js` intermediates. */
+	readonly stageBaseName: string;
+	/** Target-stable output basename; Bun embeds it as the bunfs self path. */
+	readonly outfileBaseName: string;
+}
+
+/**
+ * Run the deterministic two-stage compile for `spec`.
+ *
+ * Stage 1 bundles the entry as plain minified JS; the bundle is then
+ * normalized ({@link normalizeHostBundle}) and the photon wasm copied beside
+ * it. Stage 2 compiles the normalized bundle from the staging dir with a
+ * bare `--outfile` basename (the compiled binary embeds its own
+ * `/$bunfs/root/<basename>` path) and `--asset-naming=[name].[ext]` so the
+ * embedded asset is literally `/$bunfs/root/photon_rs_bg.wasm`, matching the
+ * rewritten `__dirname` join.
+ */
+async function compileDeterministic(
+	hostDir: string,
+	outDir: string,
+	spec: StagedCompileSpec,
+	plan: TargetPlan,
+	bunExe: string,
+	repoRoot: string,
+	runner: CommandRunner,
+): Promise<RunResult> {
+	const bundlePath = join(outDir, `${spec.stageBaseName}.bundle.js`);
+	const bundleRes = await runner.run(
+		bunExe,
+		["build", spec.entry, "--target", "bun", "--minify", "--outfile", bundlePath],
+		{ cwd: hostDir, rejectOnError: false, timeoutMs: HOST_BUILD_TIMEOUT_MS },
+	);
+	if (bundleRes.exitCode !== 0) return bundleRes;
+	if (!existsSync(bundlePath)) {
+		return { exitCode: 1, stdout: "", stderr: `bundle stage produced no output at ${bundlePath}` };
+	}
+
+	const normalized = normalizeHostBundle(
+		readFileSync(bundlePath, "utf8"),
+		forbiddenBuildPaths(repoRoot, hostDir),
+	);
+	const normPath = join(outDir, `${spec.stageBaseName}.norm.js`);
+	await writeFile(normPath, normalized.code, "utf8");
+	const wasmSource = join(normalized.photonPackageDir, PHOTON_WASM_ASSET);
+	if (!existsSync(wasmSource)) {
+		throw new BundleNormalizeError(
+			`photon wasm asset missing at ${wasmSource}; cannot embed ${PHOTON_WASM_ASSET}`,
+		);
+	}
+	await copyFile(wasmSource, join(outDir, PHOTON_WASM_ASSET));
+
+	return runner.run(
+		bunExe,
+		[
+			"build",
+			`./${spec.stageBaseName}.norm.js`,
+			"--compile",
+			"--minify",
+			"--compile-autoload-tsconfig",
+			"--compile-autoload-package-json",
+			"--asset-naming=[name].[ext]",
+			"--target",
+			plan.bunTarget,
+			"--outfile",
+			spec.outfileBaseName,
+		],
+		{ cwd: outDir, rejectOnError: false, timeoutMs: HOST_BUILD_TIMEOUT_MS },
+	);
+}
+
+/**
+ * Compile and run the photon runtime probe through the identical
+ * deterministic pipeline as the sidecar. Proves the rewritten glue reads
+ * `photon_rs_bg.wasm` from the embedded bunfs asset — a regression the
+ * `hello` handshake and runtime-import fixture can never observe. The probe
+ * runs from an empty tmp dir so no on-disk wasm can rescue a broken embed.
+ */
+async function runPhotonProbe(
+	options: BuildHostOptions,
+	hostDir: string,
+	outDir: string,
+	bunExe: string,
+	runner: CommandRunner,
+): Promise<boolean> {
+	const fixtureSource = resolve(hostDir, "fixtures", "photon-probe.ts");
+	if (!existsSync(fixtureSource)) return false;
+	const probeName = `photon-probe-test${options.plan.windows ? ".exe" : ""}`;
+	const probeBin = join(outDir, probeName);
+	if (existsSync(probeBin)) await rm(probeBin, { force: true });
+
+	const compile = await compileDeterministic(
+		hostDir,
+		outDir,
+		{ entry: "./fixtures/photon-probe.ts", stageBaseName: "photon-probe", outfileBaseName: probeName },
+		options.plan,
+		bunExe,
+		options.repoRoot,
+		runner,
+	);
+	if (compile.exitCode !== 0 || !existsSync(probeBin)) return false;
+
+	const probeDir = await mkdtemp(join(tmpdir(), "pi-host-photon-"));
+	try {
+		const run = await runner.run(probeBin, [], {
+			cwd: probeDir,
+			rejectOnError: false,
+			timeoutMs: HOST_PROBE_TIMEOUT_MS,
+		});
+		return run.exitCode === 0 && run.stdout.includes(PHOTON_PROBE_OK);
+	} finally {
+		await rm(probeDir, { recursive: true, force: true });
+	}
+}
+
+/**
+ * Try the compiled-sidecar path. Returns the artifact on success, or
+ * `undefined` if any step fails (caller falls back). Normalization errors
+ * ({@link BundleNormalizeError}) propagate instead: they invalidate the
+ * fallback too.
+ */
+async function tryCompiledPath(
+	options: BuildHostOptions,
+	hostDir: string,
+	outDir: string,
+	runner: CommandRunner,
+): Promise<HostArtifact | undefined> {
+	const sidecarPath = join(outDir, options.plan.hostBinaryName);
+	if (existsSync(sidecarPath)) await rm(sidecarPath, { force: true });
+
+	const bunExe = await resolveCompileBun(options, outDir);
+	const compileRes = await compileDeterministic(
+		hostDir,
+		outDir,
+		{
+			entry: "./src/main.ts",
+			stageBaseName: "host",
+			outfileBaseName: options.plan.hostBinaryName,
+		},
+		options.plan,
+		bunExe,
+		options.repoRoot,
+		runner,
+	);
+	if (compileRes.exitCode !== 0 || !existsSync(sidecarPath)) return undefined;
+
+	if (!options.skipRuntimeImport) {
+		const ok = await runRuntimeImportFixture(options, hostDir, outDir, runner, sidecarPath);
+		if (!ok) return undefined;
+		const photonOk = await runPhotonProbe(options, hostDir, outDir, bunExe, runner);
+		if (!photonOk) return undefined;
+	}
+	if (!options.skipHandshake) {
+		const ok = await runHelloHandshake(sidecarPath, runner);
+		if (!ok) return undefined;
+	}
+	return { kind: "compiled", binaryPath: sidecarPath };
+}
+
+/**
+ * Compile and run the runtime-import fixture against the freshly built
+ * sidecar. The fixture dynamically imports an external `.ts` extension, so
+ * this proves the compiled binary can load TypeScript extensions at runtime.
+ *
+ * The probe extension (`fixtures/extensions/virtual-imports.ts`, importing
+ * every VIRTUAL_MODULES specifier) is copied into a fresh tmp directory and
+ * loaded from there with the tmp dir as cwd, so neither the repo's
+ * node_modules nor `.references` can rescue resolution — the load succeeds
+ * iff the bundled virtual-module map is complete.
+ */
+async function runRuntimeImportFixture(
+	options: BuildHostOptions,
+	hostDir: string,
+	outDir: string,
+	runner: CommandRunner,
+	_sidecarPath: string,
+): Promise<boolean> {
+	const fixtureSource = resolve(hostDir, "fixtures", "runtime-import.ts");
+	if (!existsSync(fixtureSource)) return false;
+	const fixtureBin = join(outDir, `runtime-import-test${options.plan.windows ? ".exe" : ""}`);
+	if (existsSync(fixtureBin)) await rm(fixtureBin, { force: true });
+
+	const compile = await runner.run(
+		"bun",
+		[
+			"build",
+			"./fixtures/runtime-import.ts",
+			"--compile",
+			"--target",
+			options.plan.bunTarget,
+			"--outfile",
+			fixtureBin,
+		],
+		{ cwd: hostDir, rejectOnError: false, timeoutMs: HOST_BUILD_TIMEOUT_MS },
+	);
+	if (compile.exitCode !== 0 || !existsSync(fixtureBin)) return false;
+
+	const probeSource = resolve(hostDir, "fixtures", "extensions", "virtual-imports.ts");
+	if (!existsSync(probeSource)) return false;
+
+	const probeDir = await mkdtemp(join(tmpdir(), "pi-host-fixture-"));
+	try {
+		const probeExt = join(probeDir, "virtual-imports.ts");
+		await copyFile(probeSource, probeExt);
+		const run = await runner.run(fixtureBin, [probeExt], {
+			cwd: probeDir,
+			rejectOnError: false,
+			timeoutMs: HOST_PROBE_TIMEOUT_MS,
+		});
+		if (run.exitCode !== 0) return false;
+		// The fixture prints one JSON line summarizing registrations; require
+		// the probe tool so a partial virtual-module map fails the build.
+		let summary: unknown;
+		try {
+			summary = JSON.parse(run.stdout.trim().split("\n").at(-1) ?? "");
+		} catch {
+			return false;
+		}
+		if (typeof summary !== "object" || summary === null) return false;
+		const tools = (summary as { tools?: unknown }).tools;
+		return Array.isArray(tools) && tools.includes("virtual-imports-probe");
+	} finally {
+		await rm(probeDir, { recursive: true, force: true });
+	}
+}
+
+/**
+ * Speak the JSONL `hello` handshake with the compiled sidecar. Sends one
+ * hello request frame on stdin, reads the matching reply, validates the
+ * protocol + compatibility versions, then closes stdin.
+ */
+async function runHelloHandshake(
+	sidecarPath: string,
+	runner: CommandRunner,
+): Promise<boolean> {
+	const res = await runner.run(sidecarPath, [], {
+		cwd: dirname(sidecarPath),
+		stdin: helloRequestLine(),
+		rejectOnError: false,
+		timeoutMs: HOST_PROBE_TIMEOUT_MS,
+	});
+	const firstLine = res.stdout.split("\n", 1)[0] ?? "";
+	return res.exitCode === 0 && isHelloAckLine(firstLine);
+}
+
+/** Canonical JSONL request used by build-time and unpacked-archive probes. */
+export function helloRequestLine(): string {
+	return `${JSON.stringify({
+		id: 1,
+		kind: "req",
+		method: "hello",
+		payload: {
+			protocolVersion: HOST_PROTOCOL_VERSION,
+			compatibilityVersion: HOST_COMPATIBILITY_VERSION,
+		},
+	})}\n`;
+}
+
+/** Parse one line and validate the complete hello acknowledgement contract. */
+export function isHelloAckLine(line: string): boolean {
+	if (line.length === 0 || line.length > FRAME_MAX_BYTES) return false;
+	let frame: unknown;
+	try {
+		frame = JSON.parse(line) as unknown;
+	} catch {
+		return false;
+	}
+	return isHelloAck(frame);
+}
+
+/** Narrow a parsed frame into a hello-ack with the expected versions. */
+export function isHelloAck(frame: unknown): boolean {
+	if (typeof frame !== "object" || frame === null) return false;
+	const f = frame as { kind?: unknown; method?: unknown; payload?: unknown };
+	if (f.kind !== "res" || f.method !== "hello") return false;
+	if (typeof f.payload !== "object" || f.payload === null) return false;
+	const p = f.payload as { protocolVersion?: unknown; compatibilityVersion?: unknown };
+	return (
+		p.protocolVersion === HOST_PROTOCOL_VERSION &&
+		p.compatibilityVersion === HOST_COMPATIBILITY_VERSION
+	);
+}
+
+/** Fixture tool the unpacked-archive extension probe must register. */
+export const VIRTUAL_IMPORTS_PROBE_TOOL = "virtual-imports-probe";
+
+/**
+ * Canonical `extensions.load` request (id 2) used by the unpacked-archive
+ * probe after the hello ack. Payload keys match `parseExtensionsLoadRequest`
+ * in the host (`paths`/`cwd`/`projectTrusted`).
+ */
+export function extensionsLoadRequestLine(paths: readonly string[], cwd: string): string {
+	return `${JSON.stringify({
+		id: 2,
+		kind: "req",
+		method: "extensions.load",
+		payload: { paths, cwd, projectTrusted: true },
+	})}\n`;
+}
+
+/**
+ * Parse one line and validate the complete extensions.load acknowledgement:
+ * response id 2, exactly one loaded extension, zero errors, and a registered
+ * tool named `expectedTool`.
+ */
+export function isExtensionsLoadAck(line: string, expectedTool: string): boolean {
+	if (line.length === 0 || line.length > FRAME_MAX_BYTES) return false;
+	let frame: unknown;
+	try {
+		frame = JSON.parse(line) as unknown;
+	} catch {
+		return false;
+	}
+	if (typeof frame !== "object" || frame === null) return false;
+	const f = frame as { id?: unknown; kind?: unknown; method?: unknown; payload?: unknown };
+	if (f.id !== 2 || f.kind !== "res" || f.method !== "extensions.load") return false;
+	if (typeof f.payload !== "object" || f.payload === null) return false;
+	const p = f.payload as { extensions?: unknown; errors?: unknown; tools?: unknown };
+	if (p.extensions !== 1) return false;
+	if (!Array.isArray(p.errors) || p.errors.length !== 0) return false;
+	if (!Array.isArray(p.tools)) return false;
+	return p.tools.some(
+		(tool) =>
+			typeof tool === "object" &&
+			tool !== null &&
+			(tool as { name?: unknown }).name === expectedTool,
+	);
+}
+
+/**
+ * Loose predicate: any settled response (`res` or `error`) to the id-2
+ * extensions.load request. The smoke uses this to CLOSE stdin as soon as the
+ * host settles the request — success or failure — so a failed load fails the
+ * probe immediately instead of stalling until the process deadline. Strict
+ * validation happens afterwards via {@link isExtensionsLoadAck}.
+ */
+export function isExtensionsLoadResponseLine(line: string): boolean {
+	if (line.length === 0 || line.length > FRAME_MAX_BYTES) return false;
+	let frame: unknown;
+	try {
+		frame = JSON.parse(line) as unknown;
+	} catch {
+		return false;
+	}
+	if (typeof frame !== "object" || frame === null) return false;
+	const f = frame as { id?: unknown; kind?: unknown; method?: unknown };
+	return f.id === 2 && (f.kind === "res" || f.kind === "error") && f.method === "extensions.load";
+}
+
+/**
+ * Fallback path: bundle the host as plain JS for the platform's `bun`
+ * runtime. Returns the artifact pair, or `undefined` if bundling fails.
+ *
+ * The caller (release script) is responsible for placing a `bun[.exe]`
+ * binary next to `pi-extension-host.js` in the archive.
+ */
+async function tryRuntimeBundlePath(
+	options: BuildHostOptions,
+	hostDir: string,
+	outDir: string,
+	runner: CommandRunner,
+): Promise<HostArtifact | undefined> {
+	const scriptPath = join(outDir, options.plan.hostBundleName);
+	if (existsSync(scriptPath)) await rm(scriptPath, { force: true });
+	const res = await runner.run(
+		"bun",
+		[
+			"build",
+			"./src/main.ts",
+			"--target",
+			"bun",
+			"--minify",
+			"--outfile",
+			scriptPath,
+		],
+		{ cwd: hostDir, rejectOnError: false, timeoutMs: HOST_BUILD_TIMEOUT_MS },
+	);
+	if (res.exitCode !== 0 || !existsSync(scriptPath)) return undefined;
+	const runtimePath = join(outDir, options.plan.bunRuntimeName);
+	// Caller is responsible for populating `runtimePath` (from the official
+	// Bun release for this target) before archiving. We just record the path.
+	await writeFile(
+		join(outDir, "runtime-bundle.txt"),
+		`fallback\nscript=${scriptPath}\nruntime=${runtimePath}\ntarget=${options.plan.bunTarget}\n`,
+		"utf8",
+	);
+	return { kind: "runtime-bundle", runtimePath, scriptPath };
+}
+
+/** Drop the per-target staging directory created by {@link buildHost}. */
+export async function cleanupHostStaging(stagingRoot: string, plan: TargetPlan): Promise<void> {
+	await rm(targetStagingDir(stagingRoot, plan), { recursive: true, force: true });
+}