@diegopetrucci/pi-extensions 0.1.64 → 0.1.66

package/.pi-fleet-tested-version

@@ -1 +1 @@
-0.83.0
+0.84.4

package/README.md

@@ -39,7 +39,7 @@ A collection of [pi](https://pi.dev) agent extensions I made. (Btw, [I am also b
 
 - [`confirm-destructive`](./extensions/confirm-destructive): Confirms before destructive session actions like clear, switch, and fork.
 - [`dirty-repo-guard`](./extensions/dirty-repo-guard): Prompts before new sessions, session switches, or forks when the current git repo has uncommitted changes.
-- [`permission-gate`](./extensions/permission-gate): Prompts for confirmation before dangerous bash commands and protected `write`/`edit` targets like `.git`, `node_modules`, and secret-bearing `.env` files.
+- [`permission-gate`](./extensions/permission-gate): Prompts for confirmation before dangerous bash/PowerShell commands and protected `write`/`edit` targets like `.git`, `node_modules`, and secret-bearing `.env` files.
 
 ### Quality of life
 
@@ -53,7 +53,7 @@ A collection of [pi](https://pi.dev) agent extensions I made. (Btw, [I am also b
 ### Deprecated
 
 - [`claude-fast`](./extensions/claude-fast): Standalone-only provider-specific alternative that adds `/claude-fast` for supported Anthropic Claude Opus models. [Deprecated, please use [`fast`](https://github.com/diegopetrucci/pi-extensions/blob/main/extensions/fast) instead.]
-- [`openai-fast`](./extensions/openai-fast): Standalone-only provider-specific alternative that adds `/fast` for ChatGPT-auth GPT-5.4, GPT-5.5, and GPT-5.6 Codex variants. [Deprecated, please use [`fast`](https://github.com/diegopetrucci/pi-extensions/blob/main/extensions/fast) instead.]
+- [`openai-fast`](./extensions/openai-fast): Standalone-only provider-specific alternative that adds `/fast` for ChatGPT-auth GPT-5.5 and GPT-5.6 Codex variants. [Deprecated, please use [`fast`](https://github.com/diegopetrucci/pi-extensions/blob/main/extensions/fast) instead.]
 
 ## Install
 

package/extensions/agent-workflow-audit/.pi-fleet-tested-version

@@ -1 +1 @@
-0.83.0
+0.84.4

package/extensions/agent-workflow-audit/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diegopetrucci/pi-agent-workflow-audit",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "A pi extension that runs an isolated repo workflow audit and returns only the final report to the main session.",
   "keywords": [
     "pi-package",

package/extensions/annotate-git-diff/.pi-fleet-tested-version

@@ -1 +1 @@
-0.83.0
+0.84.4

package/extensions/annotate-git-diff/README.md

@@ -29,6 +29,8 @@ Run `/annotate-git-diff` inside a git repository. The command opens a native rev
 
 Submitting feedback does not auto-apply code changes. The extension appends a structured prompt to the current editor buffer so you can send that feedback back to the active agent.
 
+The review UI does not fetch assets from a CDN. While the window is open, the extension serves its packaged Monaco graph from an ephemeral, tokenized HTTP server bound only to `127.0.0.1`; closing, cancelling, submitting, startup failure, or Pi shutdown stops that server.
+
 ## Requirements
 
 - Run inside a git repository.
@@ -41,3 +43,4 @@ Submitting feedback does not auto-apply code changes. The extension appends a st
 - `Review failed: Not inside a git repository.` → change into a git repo and rerun `/annotate-git-diff`.
 - `No reviewable files found.` → make or fetch reviewable changes, then rerun.
 - `Review failed: Glimpse host not found ...` → the native window runtime is unavailable; reinstall/update the package and rerun from a machine/session that can open native windows.
+- `Review failed: Unable to locate packaged ... runtime` → reinstall/update the package so its declared Monaco and Tailwind dependencies are present, then rerun.

package/extensions/annotate-git-diff/index.ts

@@ -6,6 +6,7 @@ import { readSystemClipboard, writeSystemClipboard } from "./clipboard.js";
 import { getCommitFiles, getReviewWindowData, isWorkingTreeCommitSha, loadReviewFileContents } from "./git.js";
 import { composeReviewPrompt } from "./prompt.js";
 import { openQuietGlimpse, type QuietGlimpseWindow } from "./quiet-glimpse.js";
+import { startReviewUiServer, type ReviewUiServer } from "./review-server.js";
 import type {
 	ReviewCancelPayload,
 	ReviewClipboardReadPayload,
@@ -19,7 +20,6 @@ import type {
 	ReviewSubmitPayload,
 	ReviewWindowMessage,
 } from "./types.js";
-import { buildReviewHtml } from "./ui.js";
 import { createRepoChangeWatcher, type RepoChangeWatcher } from "./watch.js";
 
 function hasMessageType(value: unknown, type: ReviewWindowMessage["type"]): boolean {
@@ -69,7 +69,10 @@ function appendReviewPrompt(ctx: ExtensionCommandContext, prompt: string): void
 
 export default function (pi: ExtensionAPI) {
 	let activeWindow: QuietGlimpseWindow | null = null;
+	let activeUiServer: ReviewUiServer | null = null;
 	let activeWatcher: RepoChangeWatcher | null = null;
+	let reviewOpening = false;
+	let reviewAttempt = 0;
 	const suppressedWindows = new WeakSet<QuietGlimpseWindow>();
 
 	function stopActiveWatcher(): void {
@@ -79,10 +82,13 @@ export default function (pi: ExtensionAPI) {
 	}
 
 	function closeActiveWindow(options: { suppressResults?: boolean } = {}): void {
-		if (activeWindow == null) return;
+		reviewAttempt += 1;
 		const windowToClose = activeWindow;
 		activeWindow = null;
+		activeUiServer?.dispose();
+		activeUiServer = null;
 		stopActiveWatcher();
+		if (windowToClose == null) return;
 		if (options.suppressResults) {
 			suppressedWindows.add(windowToClose);
 		}
@@ -99,26 +105,43 @@ export default function (pi: ExtensionAPI) {
 			return;
 		}
 
-		if (activeWindow != null) {
+		if (reviewOpening || activeWindow != null || activeUiServer != null) {
 			ctx.ui.notify("A review window is already open.", "warning");
 			return;
 		}
 
+		reviewOpening = true;
+		const attempt = ++reviewAttempt;
 		try {
 			let reviewData = await getReviewWindowData(pi, ctx.cwd);
+			if (attempt !== reviewAttempt) return;
 			const { repoRoot } = reviewData;
 			if (reviewData.files.length === 0 && reviewData.commits.length === 0) {
 				ctx.ui.notify("No reviewable files found.", "info");
 				return;
 			}
 
-			const html = buildReviewHtml(reviewData);
-			const window = await openQuietGlimpse(html, {
+			const uiServer = await startReviewUiServer(reviewData);
+			if (attempt !== reviewAttempt) {
+				uiServer.dispose();
+				return;
+			}
+			activeUiServer = uiServer;
+			const window = await openQuietGlimpse(uiServer.html, {
 				width: 1680,
 				height: 1020,
 				title: "annotate-git-diff",
 			});
+			if (attempt !== reviewAttempt) {
+				suppressedWindows.add(window);
+				window.close();
+				uiServer.dispose();
+				return;
+			}
 			activeWindow = window;
+			if (uiServer.failure != null) throw uiServer.failure;
+			if (window.failure != null) throw window.failure;
+			if (window.closed) throw new Error("Glimpse closed while the review window was starting.");
 
 			const fileMap = new Map(reviewData.files.map((file) => [file.id, file]));
 			const commitFileCache = new Map<string, Promise<ReviewFile[]>>();
@@ -185,6 +208,15 @@ export default function (pi: ExtensionAPI) {
 				(resolve, reject) => {
 					let settled = false;
 					let closeTimer: ReturnType<typeof setTimeout> | null = null;
+					let removeUiServerErrorListener = (): void => {};
+
+					const requestWindowClose = (): void => {
+						try {
+							window.close();
+						} catch {
+							// Ignore races when the native process has already exited.
+						}
+					};
 
 					const cleanup = (): void => {
 						if (closeTimer != null) {
@@ -194,10 +226,14 @@ export default function (pi: ExtensionAPI) {
 						window.removeListener("message", onMessage);
 						window.removeListener("closed", onClosed);
 						window.removeListener("error", onError);
+						removeUiServerErrorListener();
+						removeUiServerErrorListener = (): void => {};
 						if (activeWindow === window) {
 							activeWindow = null;
 							stopActiveWatcher();
 						}
+						if (activeUiServer === uiServer) activeUiServer = null;
+						uiServer.dispose();
 					};
 
 					const settle = (value: ReviewSubmitPayload | ReviewCancelPayload | null): void => {
@@ -345,6 +381,7 @@ export default function (pi: ExtensionAPI) {
 							return;
 						}
 						if (isSubmitPayload(message) || isCancelPayload(message)) {
+							requestWindowClose();
 							settle(message);
 						}
 					};
@@ -360,6 +397,7 @@ export default function (pi: ExtensionAPI) {
 					const onError = (error: Error): void => {
 						if (settled) return;
 						settled = true;
+						requestWindowClose();
 						cleanup();
 						reject(error);
 					};
@@ -367,6 +405,10 @@ export default function (pi: ExtensionAPI) {
 					window.on("message", onMessage);
 					window.on("closed", onClosed);
 					window.on("error", onError);
+					removeUiServerErrorListener = uiServer.onError(onError);
+					if (uiServer.failure != null) onError(uiServer.failure);
+					else if (window.failure != null) onError(window.failure);
+					else if (window.closed) onClosed();
 				},
 			);
 
@@ -396,6 +438,8 @@ export default function (pi: ExtensionAPI) {
 			closeActiveWindow({ suppressResults: true });
 			const message = error instanceof Error ? error.message : String(error);
 			ctx.ui.notify(`Review failed: ${message}`, "error");
+		} finally {
+			reviewOpening = false;
 		}
 	}
 

package/extensions/annotate-git-diff/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diegopetrucci/pi-annotate-git-diff",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "A standalone pi extension that adds /annotate-git-diff, a native Glimpse UI for annotating git diffs and sending feedback to the editor.",
   "keywords": [
     "pi-package",
@@ -22,6 +22,7 @@
     "git.ts",
     "prompt.ts",
     "quiet-glimpse.ts",
+    "review-server.ts",
     "types.ts",
     "ui.ts",
     "watch.ts",

package/extensions/annotate-git-diff/quiet-glimpse.ts

@@ -23,6 +23,8 @@ interface GlimpseProtocolMessage {
 }
 
 export interface QuietGlimpseWindow {
+	readonly closed: boolean;
+	readonly failure: Error | null;
 	on(event: "message", listener: (data: unknown) => void): this;
 	on(event: "closed", listener: () => void): this;
 	on(event: "error", listener: (error: Error) => void): this;
@@ -38,11 +40,15 @@ class QuietGlimpseWindowImpl extends EventEmitter implements QuietGlimpseWindow
 	#closed = false;
 	#pendingHTML: string | null;
 	#stderr = "";
+	#failure: Error | null = null;
 
 	constructor(proc: ChildProcessWithoutNullStreams, initialHTML: string) {
 		super();
 		this.#proc = proc;
 		this.#pendingHTML = initialHTML;
+		// EventEmitter treats an unobserved `error` as fatal. Keep a permanent
+		// fallback while callers attach and detach their lifecycle listeners.
+		this.on("error", () => {});
 
 		proc.stdin.on("error", () => {});
 		proc.stderr.on("data", (chunk) => {
@@ -55,7 +61,7 @@ class QuietGlimpseWindowImpl extends EventEmitter implements QuietGlimpseWindow
 			try {
 				message = JSON.parse(line) as GlimpseProtocolMessage;
 			} catch {
-				this.emit("error", new Error(`Malformed glimpse protocol line: ${line}`));
+				this.#reportError(new Error(`Malformed glimpse protocol line: ${line}`));
 				return;
 			}
 
@@ -77,16 +83,18 @@ class QuietGlimpseWindowImpl extends EventEmitter implements QuietGlimpseWindow
 			}
 		});
 
-		proc.on("error", (error) => this.emit("error", error));
+		proc.on("error", (error) => this.#reportError(error));
 		proc.on("exit", (code, signal) => {
 			const stderr = this.#stderr.trim();
 			const failed = signal != null || (code != null && code !== 0);
 			if (!this.#closed && failed) {
 				const message = stderr || `Glimpse process exited abnormally (code: ${code}, signal: ${signal}).`;
-				this.emit("error", new Error(message));
+				this.#reportError(new Error(message));
 			}
 			this.#markClosed();
 		});
+		// Spawn failures can emit `error` and then `close` without `exit`.
+		proc.on("close", () => this.#markClosed());
 	}
 
 	send(js: string): void {
@@ -97,6 +105,19 @@ class QuietGlimpseWindowImpl extends EventEmitter implements QuietGlimpseWindow
 		this.#write({ type: "close" });
 	}
 
+	get closed(): boolean {
+		return this.#closed;
+	}
+
+	get failure(): Error | null {
+		return this.#failure;
+	}
+
+	#reportError(error: Error): void {
+		this.#failure ??= error;
+		this.emit("error", error);
+	}
+
 	#markClosed(): void {
 		if (this.#closed) return;
 		this.#closed = true;

package/extensions/annotate-git-diff/review-server.ts

@@ -0,0 +1,379 @@
+import { createReadStream, readFileSync, realpathSync, statSync } from "node:fs";
+import { createServer, type IncomingMessage, type Server, type ServerResponse } from "node:http";
+import { dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { randomBytes } from "node:crypto";
+import { fileURLToPath } from "node:url";
+import { buildReviewHtml } from "./ui.js";
+import type { ReviewWindowData } from "./types.js";
+
+const moduleDir = dirname(fileURLToPath(import.meta.url));
+const loopbackHost = "127.0.0.1";
+
+export interface ReviewUiServer {
+	readonly failure: Error | null;
+	html: string;
+	url: string;
+	onError(listener: (error: Error) => void): () => void;
+	dispose(): void;
+}
+
+export interface ReviewUiAssetPaths {
+	tailwindBrowserPath: string;
+	monacoLoaderPath: string;
+	monacoVsDirectory: string;
+}
+
+interface StartReviewUiServerOptions {
+	extensionDir?: string;
+	token?: string;
+}
+
+function parentDirectories(startPath: string): string[] {
+	const directories: string[] = [];
+	let current = resolve(startPath);
+
+	while (true) {
+		directories.push(current);
+		const parent = dirname(current);
+		if (parent === current) return directories;
+		current = parent;
+	}
+}
+
+function findInstalledAsset(extensionDir: string, dependencyPath: string, label: string, expected: "file" | "directory"): string {
+	const searched: string[] = [];
+	const starts = [extensionDir];
+
+	try {
+		const realExtensionDir = realpathSync(extensionDir);
+		if (realExtensionDir !== resolve(extensionDir)) starts.push(realExtensionDir);
+	} catch {
+		// The direct path below will produce the useful not-found diagnostic.
+	}
+
+	for (const start of starts) {
+		for (const ancestor of parentDirectories(start)) {
+			const candidate = join(ancestor, "node_modules", dependencyPath);
+			if (searched.includes(candidate)) continue;
+			searched.push(candidate);
+
+			try {
+				const stats = statSync(candidate);
+				const matches = expected === "file" ? stats.isFile() : stats.isDirectory();
+				if (matches) return realpathSync(candidate);
+			} catch {
+				// Keep walking toward the package-manager installation root.
+			}
+		}
+	}
+
+	throw new Error(`Unable to locate packaged ${label}. Searched: ${searched.join(", ")}`);
+}
+
+function readDependencyVersion(packageRoot: string, packageName: string): string {
+	try {
+		const manifest = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8")) as {
+			name?: unknown;
+			version?: unknown;
+		};
+		if (manifest.name !== packageName || typeof manifest.version !== "string") throw new Error("invalid manifest");
+		return manifest.version;
+	} catch {
+		throw new Error(`Unable to validate packaged ${packageName} runtime at ${packageRoot}.`);
+	}
+}
+
+function isCompatibleTailwindBrowserVersion(version: string): boolean {
+	const match = /^(\d+)\.(\d+)\.(\d+)$/.exec(version);
+	if (match == null) return false;
+	const [, major, minor, patch] = match.map(Number);
+	return major === 4 && (minor > 3 || (minor === 3 && patch >= 2));
+}
+
+export function resolveTailwindBrowserPath(extensionDir = moduleDir): string {
+	const browserPath = findInstalledAsset(
+		extensionDir,
+		join("@tailwindcss", "browser", "dist", "index.global.js"),
+		"@tailwindcss/browser runtime",
+		"file",
+	);
+	const version = readDependencyVersion(dirname(dirname(browserPath)), "@tailwindcss/browser");
+	if (!isCompatibleTailwindBrowserVersion(version)) {
+		throw new Error(`Incompatible packaged @tailwindcss/browser runtime ${version}; expected ^4.3.2.`);
+	}
+	return browserPath;
+}
+
+export function resolveMonacoVsDirectory(extensionDir = moduleDir): string {
+	const vsDirectory = findInstalledAsset(extensionDir, join("monaco-editor", "min", "vs"), "monaco-editor runtime", "directory");
+	const version = readDependencyVersion(dirname(dirname(vsDirectory)), "monaco-editor");
+	if (version !== "0.52.2") {
+		throw new Error(`Incompatible packaged monaco-editor runtime ${version}; expected 0.52.2.`);
+	}
+	return vsDirectory;
+}
+
+export function resolveReviewUiAssetPaths(extensionDir = moduleDir): ReviewUiAssetPaths {
+	const tailwindBrowserPath = resolveTailwindBrowserPath(extensionDir);
+	const monacoVsDirectory = resolveMonacoVsDirectory(extensionDir);
+	const monacoLoaderPath = join(monacoVsDirectory, "loader.js");
+
+	try {
+		if (!statSync(monacoLoaderPath).isFile()) throw new Error("not a file");
+	} catch {
+		throw new Error(`Unable to locate packaged Monaco loader: ${monacoLoaderPath}`);
+	}
+
+	return {
+		tailwindBrowserPath,
+		monacoLoaderPath: realpathSync(monacoLoaderPath),
+		monacoVsDirectory,
+	};
+}
+
+function contentType(filePath: string): string {
+	switch (extname(filePath).toLowerCase()) {
+		case ".css":
+			return "text/css; charset=utf-8";
+		case ".html":
+			return "text/html; charset=utf-8";
+		case ".js":
+		case ".mjs":
+			return "text/javascript; charset=utf-8";
+		case ".json":
+			return "application/json; charset=utf-8";
+		case ".svg":
+			return "image/svg+xml";
+		case ".ttf":
+			return "font/ttf";
+		case ".wasm":
+			return "application/wasm";
+		default:
+			return "application/octet-stream";
+	}
+}
+
+function setSecurityHeaders(response: ServerResponse): void {
+	response.setHeader("Cache-Control", "no-store");
+	response.setHeader(
+		"Content-Security-Policy",
+		"default-src 'none'; base-uri 'none'; form-action 'none'; frame-ancestors 'none'; object-src 'none'; script-src 'self' 'unsafe-inline' 'unsafe-eval' blob:; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob:; font-src 'self' data:; worker-src 'self' blob:; connect-src 'self'",
+	);
+	response.setHeader("Cross-Origin-Resource-Policy", "same-origin");
+	response.setHeader("Referrer-Policy", "no-referrer");
+	response.setHeader("X-Content-Type-Options", "nosniff");
+}
+
+function sendText(response: ServerResponse, statusCode: number, body: string): void {
+	response.statusCode = statusCode;
+	response.setHeader("Content-Type", "text/plain; charset=utf-8");
+	response.setHeader("Content-Length", Buffer.byteLength(body));
+	response.end(body);
+}
+
+function isContainedPath(rootPath: string, candidatePath: string): boolean {
+	const relativePath = relative(rootPath, candidatePath);
+	return relativePath.length > 0 && !relativePath.startsWith(`..${sep}`) && relativePath !== ".." && !isAbsolute(relativePath);
+}
+
+function decodeAssetPath(encodedPath: string): string | null {
+	try {
+		const decoded = decodeURIComponent(encodedPath);
+		if (!decoded || decoded.includes("\0") || decoded.includes("\\")) return null;
+		const segments = decoded.split("/");
+		if (segments.some((segment) => segment === "" || segment === "." || segment === "..")) return null;
+		return segments.join(sep);
+	} catch {
+		return null;
+	}
+}
+
+function serveMonacoAsset(
+	request: IncomingMessage,
+	response: ServerResponse,
+	monacoVsDirectory: string,
+	encodedPath: string,
+): void {
+	const relativePath = decodeAssetPath(encodedPath);
+	if (relativePath == null) {
+		sendText(response, 404, "Not found");
+		return;
+	}
+
+	let assetPath: string;
+	let assetSize: number;
+	try {
+		const candidate = resolve(monacoVsDirectory, relativePath);
+		if (!isContainedPath(monacoVsDirectory, candidate)) throw new Error("outside asset root");
+		assetPath = realpathSync(candidate);
+		const stats = statSync(assetPath);
+		if (!isContainedPath(monacoVsDirectory, assetPath) || !stats.isFile()) throw new Error("not a file");
+		assetSize = stats.size;
+	} catch {
+		sendText(response, 404, "Not found");
+		return;
+	}
+
+	response.statusCode = 200;
+	response.setHeader("Content-Type", contentType(assetPath));
+	response.setHeader("Content-Length", assetSize);
+	if (request.method === "HEAD") {
+		response.end();
+		return;
+	}
+
+	const stream = createReadStream(assetPath);
+	stream.on("error", () => {
+		if (!response.headersSent) sendText(response, 500, "Unable to read asset");
+		else response.destroy();
+	});
+	response.on("close", () => stream.destroy());
+	stream.pipe(response);
+}
+
+function redirectHtml(url: string): string {
+	const safeUrl = JSON.stringify(url).replace(/</g, "\\u003c");
+	return `<!doctype html><html><head><meta charset="utf-8"><title>annotate-git-diff</title></head><body><p>Loading review…</p><script>location.replace(${safeUrl});</script></body></html>`;
+}
+
+function disposeServer(server: Server): void {
+	server.close();
+	server.closeAllConnections();
+}
+
+export async function startReviewUiServer(
+	data: ReviewWindowData,
+	options: StartReviewUiServerOptions = {},
+): Promise<ReviewUiServer> {
+	const assetPaths = resolveReviewUiAssetPaths(options.extensionDir ?? moduleDir);
+	const token = options.token ?? randomBytes(24).toString("hex");
+	if (!/^[A-Za-z0-9_-]{24,128}$/.test(token)) throw new Error("Invalid review UI server token.");
+
+	const routeRoot = `/${token}/`;
+	const monacoRoutePrefix = `${routeRoot}vs/`;
+	let expectedHost = "";
+	let reviewHtml = "";
+
+	const server = createServer((request, response) => {
+		setSecurityHeaders(response);
+		if (request.headers.host !== expectedHost) {
+			sendText(response, 403, "Forbidden");
+			return;
+		}
+		if (request.method !== "GET" && request.method !== "HEAD") {
+			response.setHeader("Allow", "GET, HEAD");
+			sendText(response, 405, "Method not allowed");
+			return;
+		}
+
+		let pathname: string;
+		try {
+			pathname = new URL(request.url ?? "/", `http://${expectedHost}`).pathname;
+		} catch {
+			sendText(response, 400, "Bad request");
+			return;
+		}
+
+		if (pathname === routeRoot || pathname === `${routeRoot}index.html`) {
+			response.statusCode = 200;
+			response.setHeader("Content-Type", "text/html; charset=utf-8");
+			response.setHeader("Content-Length", Buffer.byteLength(reviewHtml));
+			response.end(request.method === "HEAD" ? undefined : reviewHtml);
+			return;
+		}
+
+		if (pathname.startsWith(monacoRoutePrefix)) {
+			serveMonacoAsset(request, response, assetPaths.monacoVsDirectory, pathname.slice(monacoRoutePrefix.length));
+			return;
+		}
+
+		sendText(response, 404, "Not found");
+	});
+	// Keep Node's special EventEmitter `error` event non-fatal across disposal
+	// races; the scoped listener below still records and reports live failures.
+	server.on("error", () => {});
+	server.maxHeadersCount = 50;
+	server.headersTimeout = 5_000;
+	server.keepAliveTimeout = 1_000;
+	server.requestTimeout = 15_000;
+	server.on("clientError", (_error, socket) => socket.destroy());
+	const errorListeners = new Set<(error: Error) => void>();
+	let disposed = false;
+	let runtimeFailure: Error | null = null;
+	const onRuntimeServerError = (error: Error): void => {
+		if (disposed || runtimeFailure != null) return;
+		runtimeFailure = error;
+		disposeServer(server);
+		for (const listener of [...errorListeners]) {
+			try {
+				listener(error);
+			} catch {
+				// A lifecycle observer must not turn a server failure into an
+				// uncaught process-level exception.
+			}
+		}
+	};
+
+	try {
+		await new Promise<void>((resolveListen, rejectListen) => {
+			const onError = (error: Error): void => {
+				server.off("listening", onListening);
+				rejectListen(error);
+			};
+			const onListening = (): void => {
+				server.off("error", onError);
+				resolveListen();
+			};
+			server.once("error", onError);
+			server.once("listening", onListening);
+			server.listen({ host: loopbackHost, port: 0, exclusive: true });
+		});
+		server.on("error", onRuntimeServerError);
+
+		const address = server.address();
+		if (address == null || typeof address === "string") throw new Error("Review UI server did not expose a TCP address.");
+		expectedHost = `${loopbackHost}:${address.port}`;
+		const url = `http://${expectedHost}${routeRoot}`;
+		reviewHtml = buildReviewHtml(data, {
+			tailwindBrowserJs: readFileSync(assetPaths.tailwindBrowserPath, "utf8"),
+			monacoLoaderJs: readFileSync(assetPaths.monacoLoaderPath, "utf8"),
+			monacoVsBaseUrl: `${url}vs`,
+		});
+		server.unref();
+
+		return {
+			get failure() {
+				return runtimeFailure;
+			},
+			html: redirectHtml(url),
+			url,
+			onError(listener) {
+				if (runtimeFailure != null) {
+					let active = true;
+					queueMicrotask(() => {
+						if (active) listener(runtimeFailure as Error);
+					});
+					return () => {
+						active = false;
+					};
+				}
+				if (disposed) return () => {};
+				errorListeners.add(listener);
+				return () => errorListeners.delete(listener);
+			},
+			dispose() {
+				if (disposed) return;
+				disposed = true;
+				errorListeners.clear();
+				server.off("error", onRuntimeServerError);
+				disposeServer(server);
+			},
+		};
+	} catch (error) {
+		disposed = true;
+		errorListeners.clear();
+		server.off("error", onRuntimeServerError);
+		disposeServer(server);
+		throw error;
+	}
+}