@oh-my-pi/pi-coding-agent 17.2.1 → 17.2.3

package/src/tools/browser/launch.ts

@@ -1,7 +1,7 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-import { $which, getPuppeteerDir, logger } from "@oh-my-pi/pi-utils";
+import { $which, getPuppeteerDir, logger, removeWithRetries } from "@oh-my-pi/pi-utils";
 import type * as BrowsersNs from "@puppeteer/browsers";
 import type { Browser, CDPSession, Page, default as Puppeteer, Target } from "puppeteer-core";
 import stealthTamperingScript from "../puppeteer/00_stealth_tampering.txt" with { type: "text" };
@@ -285,19 +285,28 @@ export interface LaunchHeadlessOptions {
 	ignoreDefaultArgs?: readonly string[];
 }
 
-export async function launchHeadlessBrowser(opts: LaunchHeadlessOptions): Promise<Browser> {
-	const vp = opts.viewport ?? DEFAULT_VIEWPORT;
-	const initialViewport = {
-		width: vp.width,
-		height: vp.height,
-		deviceScaleFactor: vp.deviceScaleFactor ?? DEFAULT_VIEWPORT.deviceScaleFactor,
-	};
-	const puppeteer = await loadPuppeteer();
+/** Result of a headless Chromium launch. */
+export interface LaunchHeadlessResult {
+	browser: Browser;
+	/**
+	 * OMP-owned temporary Chromium profile directory to remove after the browser
+	 * process tree exits, or `undefined` when the caller supplied its own
+	 * `--user-data-dir` (which OMP must not delete).
+	 */
+	userDataDir?: string;
+}
+
+/**
+ * Base Chromium argv shared by process-local puppeteer launches and the
+ * broker-owned shared browser: sandbox/stealth flags, window size, and
+ * PUPPETEER_PROXY* env-derived proxy flags.
+ */
+export function buildHeadlessLaunchArgs(viewport: { width: number; height: number }): string[] {
 	const launchArgs = [
 		"--no-sandbox",
 		"--disable-setuid-sandbox",
 		"--disable-blink-features=AutomationControlled",
-		`--window-size=${initialViewport.width},${initialViewport.height}`,
+		`--window-size=${viewport.width},${viewport.height}`,
 	];
 	const proxy = process.env.PUPPETEER_PROXY;
 	if (proxy) {
@@ -313,18 +322,103 @@ export async function launchHeadlessBrowser(opts: LaunchHeadlessOptions): Promis
 	if (ignoreCert === "true" || ignoreCert === "1" || ignoreCert === "yes" || ignoreCert === "on") {
 		launchArgs.push("--ignore-certificate-errors");
 	}
+	return launchArgs;
+}
+
+export async function launchHeadlessBrowser(opts: LaunchHeadlessOptions): Promise<LaunchHeadlessResult> {
+	const vp = opts.viewport ?? DEFAULT_VIEWPORT;
+	const initialViewport = {
+		width: vp.width,
+		height: vp.height,
+		deviceScaleFactor: vp.deviceScaleFactor ?? DEFAULT_VIEWPORT.deviceScaleFactor,
+	};
+	const puppeteer = await loadPuppeteer();
+	const launchArgs = buildHeadlessLaunchArgs(initialViewport);
 	for (const arg of opts.args ?? []) {
 		if (!launchArgs.includes(arg)) launchArgs.push(arg);
 	}
+	// Own the Chromium profile directory instead of letting puppeteer-core create
+	// (and delete) a temporary one. Passing `--user-data-dir` makes puppeteer
+	// treat the profile as non-temporary, so `ChromeLauncher.cleanUserDataDir`
+	// becomes a no-op and can no longer reject its eager process-exit hook with an
+	// unhandled EBUSY when Chromium still holds the profile lock on Windows
+	// (issue #7058). `removeUserDataDir` cleans it up on our terms instead.
+	let userDataDir: string | undefined;
+	if (!launchArgs.some(arg => arg.startsWith("--user-data-dir"))) {
+		userDataDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), "omp-chrome-profile-"));
+		launchArgs.push(`--user-data-dir=${userDataDir}`);
+	}
+	try {
+		const executablePath = await ensureChromiumExecutable();
+		const browser = await puppeteer.launch({
+			headless: opts.headless,
+			defaultViewport: opts.headless ? initialViewport : null,
+			executablePath,
+			args: launchArgs,
+			ignoreDefaultArgs: [
+				...new Set([...stealthIgnoreDefaultArgs(executablePath), ...(opts.ignoreDefaultArgs ?? [])]),
+			],
+			protocolTimeout: BROWSER_PROTOCOL_TIMEOUT_MS,
+		});
+		return { browser, userDataDir };
+	} catch (error) {
+		if (userDataDir) await removeUserDataDir(userDataDir);
+		throw error;
+	}
+}
+
+/** Fully resolved executable and argv for a broker-spawned shared Chromium. */
+export interface SharedBrowserLaunchSpec {
+	executablePath: string;
+	args: string[];
+}
+
+/**
+ * Resolve the executable and complete argv for a shared Chromium the daemon
+ * broker spawns directly (no puppeteer inside the broker). Mirrors
+ * `launchHeadlessBrowser` flag assembly — puppeteer's default args minus the
+ * stealth-suppressed set — plus `--remote-debugging-port=0` so every client
+ * attaches over CDP. Returns null when no Chromium executable resolves;
+ * callers fall back to a process-local launch.
+ */
+export async function resolveSharedBrowserLaunchSpec(opts: {
+	headless: boolean;
+	userDataDir: string;
+	viewport?: { width: number; height: number };
+}): Promise<SharedBrowserLaunchSpec | null> {
 	const executablePath = await ensureChromiumExecutable();
-	return await puppeteer.launch({
+	if (!executablePath) return null;
+	const puppeteer = await loadPuppeteer();
+	const vp = opts.viewport ?? DEFAULT_VIEWPORT;
+	const ignored = new Set(stealthIgnoreDefaultArgs(executablePath));
+	const defaults = await puppeteer.defaultArgs({
 		headless: opts.headless,
-		defaultViewport: opts.headless ? initialViewport : null,
-		executablePath,
-		args: launchArgs,
-		ignoreDefaultArgs: [...new Set([...stealthIgnoreDefaultArgs(executablePath), ...(opts.ignoreDefaultArgs ?? [])])],
-		protocolTimeout: BROWSER_PROTOCOL_TIMEOUT_MS,
+		args: buildHeadlessLaunchArgs(vp),
+		userDataDir: opts.userDataDir,
 	});
+	return {
+		executablePath,
+		args: [...defaults.filter(arg => !ignored.has(arg)), "--remote-debugging-port=0"],
+	};
+}
+
+/**
+ * Remove an OMP-owned headless Chromium profile directory, tolerating the brief
+ * window on Windows in which Chromium (or an orphaned browser subprocess) still
+ * holds the profile lock. The shared temp remover centralizes retry handling
+ * for EBUSY/EPERM/ENOTEMPTY; if the directory is still busy afterwards we warn
+ * and leave it for a later cleanup pass rather than throwing — a shutdown cleanup
+ * failure must never crash the process (issue #7058).
+ */
+export async function removeUserDataDir(dir: string): Promise<void> {
+	try {
+		await removeWithRetries(dir);
+	} catch (error) {
+		logger.warn("Left Chromium profile directory in place after cleanup failure", {
+			dir,
+			error: error instanceof Error ? error.message : String(error),
+		});
+	}
 }
 
 export async function applyViewport(

package/src/tools/browser/registry.ts

@@ -1,12 +1,20 @@
 import * as path from "node:path";
-import { logger, withTimeout } from "@oh-my-pi/pi-utils";
+import { isCompiledBinary, logger, withTimeout, workerHostEntry } from "@oh-my-pi/pi-utils";
 import type { Subprocess } from "bun";
 import type { Browser, CDPSession } from "puppeteer-core";
 import { ToolAbortError, ToolError } from "../tool-errors";
 import { findFreeCdpPort, findReusableCdp, gracefulKillTreeOnce, killExistingByPath, waitForCdp } from "./attach";
 import type { CmuxKind } from "./cmux/rpc";
 import { CmuxSocketClient } from "./cmux/socket-client";
-import { BROWSER_PROTOCOL_TIMEOUT_MS, launchHeadlessBrowser, loadPuppeteer, type UserAgentOverride } from "./launch";
+import {
+	BROWSER_PROTOCOL_TIMEOUT_MS,
+	DEFAULT_VIEWPORT,
+	launchHeadlessBrowser,
+	loadPuppeteer,
+	removeUserDataDir,
+	type UserAgentOverride,
+} from "./launch";
+import { ensureSharedBrowser } from "./shared-daemon";
 
 export type PuppeteerBrowserKind =
 	| { kind: "headless"; headless: boolean }
@@ -35,6 +43,10 @@ export interface PuppeteerBrowserHandle extends BrowserHandleCommon {
 	browser: Browser;
 	cdpUrl?: string;
 	pid?: number;
+	/** OMP-owned temp Chromium profile directory removed on dispose (process-local headless launches). */
+	userDataDir?: string;
+	/** Broker daemon backing this handle; dispose disconnects instead of closing, kill routes to the broker. */
+	sharedDaemon?: { name: string; projectDir: string };
 	subprocess?: Subprocess;
 	stealth: { browserSession: CDPSession | null; override: UserAgentOverride | null };
 }
@@ -55,6 +67,8 @@ export interface ReleaseBrowserOptions {
 }
 
 const browsers = new Map<string, BrowserHandle>();
+/** In-flight opens by browser key, so concurrent acquisitions share one launch instead of storming Chromium. */
+const pendingOpens = new Map<string, Promise<BrowserHandle>>();
 
 function browserKey(kind: BrowserKind): string {
 	switch (kind.kind) {
@@ -78,37 +92,51 @@ export interface AcquireBrowserOptions {
 
 export async function acquireBrowser(kind: BrowserKind, opts: AcquireBrowserOptions): Promise<BrowserHandle> {
 	const key = browserKey(kind);
-	const existing = browsers.get(key);
-	if (existing) {
-		if ("client" in existing) return existing;
-		if (existing.browser.connected) return existing;
-		browsers.delete(key);
-		await disposeBrowserHandle(existing, { kill: false });
-	}
-	// Short-circuit before launching: the tool wrapper's `untilAborted` only
-	// rejects its outer promise on abort; without this check `openBrowserHandle`
-	// would still fire and its result would land in `browsers` below.
-	if (opts.signal?.aborted) throw new ToolAbortError("Browser open aborted");
+	for (;;) {
+		const existing = browsers.get(key);
+		if (existing) {
+			if ("client" in existing) return existing;
+			if (existing.browser.connected) return existing;
+			browsers.delete(key);
+			await disposeBrowserHandle(existing, { kill: false });
+			continue;
+		}
+		// Short-circuit before launching: the tool wrapper's `untilAborted` only
+		// rejects its outer promise on abort; without this check `openBrowserHandle`
+		// would still fire and its result would land in `browsers` below.
+		if (opts.signal?.aborted) throw new ToolAbortError("Browser open aborted");
 
-	const handle = await openBrowserHandle(kind, opts);
-	// The launch may resolve AFTER the caller has already aborted (the outer
-	// `untilAborted` rejects immediately on abort but does not cancel the
-	// inner promise, and `launchHeadlessBrowser` does not accept a signal).
-	// Without this branch the completed handle sits in `browsers` at
-	// refCount:0 forever — no tab ever takes a hold, `releaseBrowser` never
-	// fires, and `releaseAllTabs` walks `tabs`, not `browsers`, so the
-	// orphaned Chromium/app process / puppeteer handle survives to process
-	// exit. (Issue #3963.)
-	if (opts.signal?.aborted) {
-		await disposeBrowserHandle(handle, { kill: kind.kind === "spawned" }).catch(err => {
-			logger.debug("Failed to dispose orphan browser after abort", {
-				error: err instanceof Error ? err.message : String(err),
+		// Single-flight per key: a concurrent caller already opening this browser
+		// wins; everyone else waits and re-reads the registry. Without this, N
+		// simultaneous opens each launch a Chromium and the last write wins,
+		// leaking the rest as unreferenced process trees.
+		const pending = pendingOpens.get(key);
+		if (pending) {
+			await pending.catch(() => undefined);
+			continue;
+		}
+		const open = openBrowserHandle(kind, opts).finally(() => pendingOpens.delete(key));
+		pendingOpens.set(key, open);
+		const handle = await open;
+		// The launch may resolve AFTER the caller has already aborted (the outer
+		// `untilAborted` rejects immediately on abort but does not cancel the
+		// inner promise, and `launchHeadlessBrowser` does not accept a signal).
+		// Without this branch the completed handle sits in `browsers` at
+		// refCount:0 forever — no tab ever takes a hold, `releaseBrowser` never
+		// fires, and `releaseAllTabs` walks `tabs`, not `browsers`, so the
+		// orphaned Chromium/app process / puppeteer handle survives to process
+		// exit. (Issue #3963.)
+		if (opts.signal?.aborted) {
+			await disposeBrowserHandle(handle, { kill: kind.kind === "spawned" }).catch(err => {
+				logger.debug("Failed to dispose orphan browser after abort", {
+					error: err instanceof Error ? err.message : String(err),
+				});
 			});
-		});
-		throw new ToolAbortError("Browser open aborted");
+			throw new ToolAbortError("Browser open aborted");
+		}
+		browsers.set(key, handle);
+		return handle;
 	}
-	browsers.set(key, handle);
-	return handle;
 }
 
 export function normalizeConnectedCdpUrl(rawCdpUrl: string): string {
@@ -134,11 +162,23 @@ async function openBrowserHandle(kind: BrowserKind, opts: AcquireBrowserOptions)
 		};
 	}
 	if (kind.kind === "headless") {
-		const browser = await launchHeadlessBrowser({ headless: kind.headless, viewport: opts.viewport });
+		// Every real omp process (session, subagent, worker — anything with a CLI
+		// worker host) MUST go through the project-shared broker-owned Chromium:
+		// per-process launches are what produced launch storms and orphaned
+		// process trees. The process-local launch survives only for hosts that
+		// cannot spawn the broker (bun test, SDK embedding without a CLI entry).
+		if (isCompiledBinary() || workerHostEntry() !== null) {
+			return await openSharedHeadlessHandle(kind, opts);
+		}
+		const { browser, userDataDir } = await launchHeadlessBrowser({
+			headless: kind.headless,
+			viewport: opts.viewport,
+		});
 		return {
 			key: browserKey(kind),
 			kind,
 			browser,
+			userDataDir,
 			refCount: 0,
 			stealth: { browserSession: null, override: null },
 		};
@@ -245,6 +285,21 @@ async function disposeBrowserHandle(handle: BrowserHandle, opts: ReleaseBrowserO
 		return;
 	}
 	if (handle.kind.kind === "headless") {
+		if (handle.sharedDaemon) {
+			// The broker owns the Chromium; this process only drops its CDP
+			// connection. `kill` is scoped to spawned-app browsers — stopping the
+			// shared daemon here would tear down every other session's tabs. The
+			// daemon dies with the last omp client in the project (broker idle
+			// teardown), or via an explicit hub stop.
+			if (handle.browser.connected) {
+				try {
+					handle.browser.disconnect();
+				} catch (err) {
+					logger.debug("Failed to disconnect from shared browser", { error: (err as Error).message });
+				}
+			}
+			return;
+		}
 		if (handle.browser.connected) {
 			// Puppeteer's `browser.close()` resolves only once the Chromium
 			// process fully exits. A wedged Chromium (a known Windows failure
@@ -259,6 +314,10 @@ async function disposeBrowserHandle(handle: BrowserHandle, opts: ReleaseBrowserO
 				if (proc?.pid !== undefined) await gracefulKillTreeOnce(proc.pid).catch(() => undefined);
 			}
 		}
+		// OMP owns the profile directory (puppeteer's temp cleanup is disabled by
+		// our explicit --user-data-dir), so remove it now the process tree has
+		// exited. Tolerant of the Windows lock-held window (issue #7058).
+		if (handle.userDataDir) await removeUserDataDir(handle.userDataDir);
 		return;
 	}
 	if (handle.kind.kind === "connected") {
@@ -281,6 +340,56 @@ async function disposeBrowserHandle(handle: BrowserHandle, opts: ReleaseBrowserO
 	if (opts.kill && handle.pid !== undefined) await gracefulKillTreeOnce(handle.pid);
 }
 
+/**
+ * Attach to the project-shared broker-owned Chromium. Failures surface as
+ * `ToolError` — a CLI-host process never silently falls back to a private
+ * Chromium, so a broken broker cannot quietly recreate per-process launch
+ * storms.
+ */
+async function openSharedHeadlessHandle(
+	kind: Extract<PuppeteerBrowserKind, { kind: "headless" }>,
+	opts: AcquireBrowserOptions,
+): Promise<PuppeteerBrowserHandle> {
+	const vp = opts.viewport ?? DEFAULT_VIEWPORT;
+	try {
+		const shared = await ensureSharedBrowser({
+			projectDir: opts.cwd,
+			headless: kind.headless,
+			viewport: vp,
+			signal: opts.signal,
+		});
+		if (!shared) {
+			throw new ToolError(
+				"Shared browser daemon unavailable (broker start or Chromium launch failed); check `hub ps` for omp.browser.* daemons and ~/.omp/logs for details",
+			);
+		}
+		const puppeteer = await loadPuppeteer();
+		const browser = await puppeteer.connect({
+			browserWSEndpoint: shared.wsEndpoint,
+			defaultViewport: kind.headless
+				? {
+						width: vp.width,
+						height: vp.height,
+						deviceScaleFactor: vp.deviceScaleFactor ?? DEFAULT_VIEWPORT.deviceScaleFactor,
+					}
+				: null,
+			protocolTimeout: BROWSER_PROTOCOL_TIMEOUT_MS,
+		});
+		return {
+			key: browserKey(kind),
+			kind,
+			browser,
+			sharedDaemon: { name: shared.daemonName, projectDir: shared.projectDir },
+			refCount: 0,
+			stealth: { browserSession: null, override: null },
+		};
+	} catch (err) {
+		if (err instanceof ToolAbortError || err instanceof ToolError) throw err;
+		if (opts.signal?.aborted) throw new ToolAbortError("Browser open aborted");
+		throw new ToolError(`Shared browser attach failed: ${err instanceof Error ? err.message : String(err)}`);
+	}
+}
+
 /** Test-only accessor for the module-global browsers map. */
 export function getBrowsersMapForTest(): ReadonlyMap<string, BrowserHandle> {
 	return browsers;

package/src/tools/browser/shared-daemon.ts

@@ -0,0 +1,190 @@
+/**
+ * Shared automation Chromium owned by the per-project daemon broker.
+ *
+ * Instead of every omp process launching (and sometimes orphaning) a private
+ * Chromium, the headless browser kind attaches to one broker-supervised Chrome
+ * per project directory — sessions and subagents each open their own tabs in
+ * it. The broker stops the daemon when the last omp client in the project
+ * exits, so Chrome can never outlive omp, and concurrent acquisitions across
+ * processes converge on a single launch instead of a launch storm.
+ */
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { logger } from "@oh-my-pi/pi-utils";
+import { type DaemonBrokerClient, daemonClientForProject } from "../../launch/client";
+import { daemonRuntimeDir } from "../../launch/paths";
+import type { DaemonSnapshot } from "../../launch/protocol";
+import { throwIfAborted } from "../tool-errors";
+import { resolveSharedBrowserLaunchSpec } from "./launch";
+
+/** Chrome prints this on stderr once the CDP listener is up; the broker's ready probe captures the line. */
+const READY_LOG_PATTERN = String.raw`DevTools listening on ws://\S+`;
+const READY_TIMEOUT_MS = 30_000;
+const STOP_TIMEOUT_MS = 5_000;
+const PROBE_TIMEOUT_MS = 1_500;
+/** describe→start rounds before giving up; bounds cross-process start races and wedged-Chrome replacement. */
+const ENSURE_ATTEMPTS = 3;
+
+/** Broker-owned browser endpoint one omp process can attach to. */
+export interface SharedBrowserEndpoint {
+	wsEndpoint: string;
+	daemonName: string;
+	/** Canonical project directory owning the broker (used to address later stop requests). */
+	projectDir: string;
+}
+
+/** Stable broker daemon name for the shared automation browser. */
+export function sharedBrowserDaemonName(headless: boolean): string {
+	return headless ? "omp.browser.headless" : "omp.browser.headed";
+}
+
+function wsEndpointOf(snapshot: DaemonSnapshot | undefined): string | undefined {
+	return snapshot?.readyMatch?.match(/ws:\/\/\S+/)?.[0];
+}
+
+/** CDP liveness probe: the ws endpoint host must answer /json/version. */
+async function probeEndpoint(wsEndpoint: string): Promise<boolean> {
+	let host: string;
+	try {
+		host = new URL(wsEndpoint).host;
+	} catch {
+		return false;
+	}
+	try {
+		const res = await fetch(`http://${host}/json/version`, { signal: AbortSignal.timeout(PROBE_TIMEOUT_MS) });
+		await res.body?.cancel();
+		return res.ok;
+	} catch {
+		return false;
+	}
+}
+
+/** Snapshot the daemon, treating "unknown daemon" as absent. */
+async function describeQuietly(
+	client: DaemonBrokerClient,
+	name: string,
+	signal?: AbortSignal,
+): Promise<DaemonSnapshot | undefined> {
+	try {
+		const result = await client.request({ op: "describe", name }, signal);
+		return result.op === "describe" ? result.daemon : undefined;
+	} catch (error) {
+		throwIfAborted(signal);
+		logger.debug("Shared browser describe failed", {
+			name,
+			error: error instanceof Error ? error.message : String(error),
+		});
+		return undefined;
+	}
+}
+
+/** Block until the daemon reports ready; undefined on timeout or pre-ready exit. */
+async function waitReady(
+	client: DaemonBrokerClient,
+	name: string,
+	signal?: AbortSignal,
+): Promise<DaemonSnapshot | undefined> {
+	try {
+		const result = await client.request({ op: "wait", name, for: "ready", timeoutMs: READY_TIMEOUT_MS }, signal);
+		if (result.op !== "wait" || result.timedOut) return undefined;
+		return result.daemon;
+	} catch (error) {
+		throwIfAborted(signal);
+		logger.debug("Shared browser ready wait failed", {
+			name,
+			error: error instanceof Error ? error.message : String(error),
+		});
+		return undefined;
+	}
+}
+
+/** Best-effort stop before replacing a wedged or endpoint-less daemon. */
+async function stopQuietly(client: DaemonBrokerClient, name: string, signal?: AbortSignal): Promise<void> {
+	try {
+		await client.request({ op: "stop", name, timeoutMs: STOP_TIMEOUT_MS }, signal);
+	} catch (error) {
+		throwIfAborted(signal);
+		logger.debug("Shared browser stop failed", {
+			name,
+			error: error instanceof Error ? error.message : String(error),
+		});
+	}
+}
+
+/**
+ * Ensure the project-shared automation Chromium is running and reachable,
+ * launching it under the daemon broker when needed. Idempotent across
+ * processes: losers of the start race adopt the winner's endpoint on the next
+ * describe round. Returns null when the shared path is unavailable (no
+ * resolvable Chromium, broker failure, or a daemon that never becomes
+ * reachable); callers fall back to a process-local launch.
+ */
+export async function ensureSharedBrowser(opts: {
+	projectDir: string;
+	headless: boolean;
+	viewport?: { width: number; height: number };
+	signal?: AbortSignal;
+}): Promise<SharedBrowserEndpoint | null> {
+	const client = await daemonClientForProject(opts.projectDir);
+	const name = sharedBrowserDaemonName(opts.headless);
+	// Stable profile under the broker's runtime dir: reused across launches, and
+	// never contended by pre-daemon Chromiums that used throwaway temp profiles.
+	const userDataDir = path.join(daemonRuntimeDir(client.projectDir), `${name}.profile`);
+	const launch = await resolveSharedBrowserLaunchSpec({
+		headless: opts.headless,
+		userDataDir,
+		viewport: opts.viewport,
+	});
+	if (!launch) return null;
+	await fs.mkdir(userDataDir, { recursive: true });
+	for (let attempt = 0; attempt < ENSURE_ATTEMPTS; attempt++) {
+		throwIfAborted(opts.signal);
+		const existing = await describeQuietly(client, name, opts.signal);
+		if (existing && existing.state !== "exited" && existing.state !== "failed") {
+			const settled = existing.readyAt !== undefined ? existing : await waitReady(client, name, opts.signal);
+			const wsEndpoint = wsEndpointOf(settled);
+			if (wsEndpoint && (await probeEndpoint(wsEndpoint))) {
+				return { wsEndpoint, daemonName: name, projectDir: client.projectDir };
+			}
+			// Live record but unreachable Chrome (wedged, or readiness never
+			// matched): replace it rather than handing out a dead endpoint.
+			await stopQuietly(client, name, opts.signal);
+			continue;
+		}
+		try {
+			const started = await client.request(
+				{
+					op: "start",
+					spec: {
+						name,
+						application: launch.executablePath,
+						args: launch.args,
+						env: {},
+						cwd: client.projectDir,
+						pty: false,
+						ready: { log: READY_LOG_PATTERN, timeoutMs: READY_TIMEOUT_MS },
+						restart: "no",
+						persist: false,
+						detached: false,
+					},
+				},
+				opts.signal,
+			);
+			if (started.op !== "start") continue;
+			const wsEndpoint = started.readyTimedOut ? undefined : wsEndpointOf(started.daemon);
+			if (wsEndpoint && (await probeEndpoint(wsEndpoint))) {
+				return { wsEndpoint, daemonName: name, projectDir: client.projectDir };
+			}
+			await stopQuietly(client, name, opts.signal);
+		} catch (error) {
+			throwIfAborted(opts.signal);
+			// Lost a cross-process start race ("already starting/ready"); the next
+			// describe round adopts the winner's endpoint.
+			logger.debug("Shared browser start contention", {
+				name,
+				error: error instanceof Error ? error.message : String(error),
+			});
+		}
+	}
+	return null;
+}

package/src/tools/browser/tab-protocol.ts

@@ -59,12 +59,20 @@ export type WorkerInitPayload =
 			safeDir: string;
 			targetId: string;
 			dialogs?: "accept" | "dismiss";
+			url?: string;
+			waitUntil?: "load" | "domcontentloaded" | "networkidle0" | "networkidle2";
+			timeoutMs: number;
 			/**
 			 * Post-timeout recycle: before adopting the page, dismiss any open JS dialog and
 			 * stop a pending navigation so a blocked target cannot stall worker init (which
 			 * previously force-killed the tab). Never set for first-time Electron attach.
 			 */
 			recover?: boolean;
+			/**
+			 * Whether the worker may raise this tab before capturing a screenshot. Unset
+			 * behaves as `true`; the supervisor clears it for browsers we did not launch.
+			 */
+			activateForScreenshot?: boolean;
 	  };
 
 export type ToolReply = { ok: true; value: unknown } | { ok: false; error: RunErrorPayload };