@orkestrel/browser 0.0.17 → 0.0.19

package/dist/src/server/index.js

@@ -1,17 +1,19 @@
-import { BROWSER_DEFAULT_TIMEOUT_MS, BROWSER_WAIT_POLL_INTERVAL_MS, BrowserContext, BrowserError, BrowserTransition, CDPClient, validateBrowserContextOptions } from "../core/index.js";
-import { attempt, isArray, isError, isInstance, isInteger, isRecord, isString } from "@orkestrel/contract";
-import { existsSync, globSync } from "node:fs";
-import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { BROWSER_DEFAULT_TIMEOUT_MS, BROWSER_JOURNEY_FORMAT_VERSION, BROWSER_JOURNEY_NAME_PATTERN, BROWSER_JOURNEY_TOOL_NAMES, BROWSER_RUN_ID_PATTERN, BROWSER_TOOL_COPY, BROWSER_TOOL_NAMES, BrowserConnectionError, BrowserContext, BrowserError, BrowserTransition, CDPClient, createBrowserToolset, generateBrowserRunId, isBrowserConnectionError, normalizeBrowserJourneyReason, validateBrowserContextOptions, validateBrowserJourney, validateBrowserRun, validateBrowserStorePage } from "../core/index.js";
+import { attempt, isArray, isError, isInstance, isInteger, isRecord, isString, parseJSON } from "@orkestrel/contract";
+import { existsSync, globSync, realpathSync } from "node:fs";
+import { lstat, mkdir, mkdtemp, open, readFile, readdir, rename, rm, rmdir, unlink, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
-import { basename, dirname, join, posix, resolve, win32 } from "node:path";
+import { basename, dirname, join, posix, relative, resolve, sep, win32 } from "node:path";
 import { spawn, spawnSync } from "node:child_process";
-import { setTimeout as setTimeout$1 } from "node:timers/promises";
-import { randomBytes } from "node:crypto";
+import { randomBytes, randomUUID } from "node:crypto";
 import { request } from "node:http";
 import { request as request$1 } from "node:https";
 import { Emitter } from "@orkestrel/emitter";
 import { WEBSOCKET_READY_CLOSED, WEBSOCKET_READY_OPEN, WEBSOCKET_VERSION, computeWebSocketAccept, createNodeWebSocket } from "@orkestrel/websocket";
 import { addAbortListener, once } from "node:events";
+import { createMCPLegacy, createMCPServer } from "@orkestrel/mcp";
+import { createStdioServer } from "@orkestrel/mcp/server";
+import { createTool, createToolManager, toolToDefinition } from "@orkestrel/tool";
 //#region src/server/constants.ts
 /**
 * Sets the default CDP port probed for an existing browser and used for launches, `9222`.
@@ -57,9 +59,28 @@ var BROWSER_KILL_GRACE_MS = 3e3;
 */
 var BROWSER_PORT_PROBE_TIMEOUT_MS = 200;
 /**
+* Matches the stderr line Chromium prints when its CDP endpoint accepts connections, and
+* captures the `ws://` endpoint the line names.
+*
+* @remarks
+* Chromium prints the line only when launched with `--remote-debugging-port`, which is why an
+* owned launch always passes that flag.
+*/
+var BROWSER_DEVTOOLS_PATTERN = /DevTools listening on (ws:\/\/\S+)/;
+/**
+* Sets the interval in milliseconds between liveness probes of a terminated browser process
+* group.
+*
+* @remarks
+* Node raises an exit event for the direct child only. Neither the rest of a POSIX process
+* group nor a process a launcher handed the endpoint to raises one, so the bounded drain in
+* `Browser` probes on this interval until the group is gone or the grace period ends.
+*/
+var BROWSER_DRAIN_INTERVAL_MS = 100;
+/**
 * Defers once for `50` milliseconds when a transport loss is observed on an owned process,
-* giving a near-simultaneous process-exit event, which libuv may reap slightly later than the
-* socket close, first say over the diagnosis.
+* so a near-simultaneous process-exit event, which libuv might reap slightly later than the
+* socket close, decides the diagnosis first.
 */
 var BROWSER_TRANSPORT_LOSS_DEFER_MS = 50;
 /**
@@ -176,19 +197,23 @@ var BROWSER_STORE_GLOBS = Object.freeze({
 	darwin: "chromium-*/chrome-mac*/Chromium.app/Contents/MacOS/Chromium",
 	win32: "chromium-*/chrome-win*/chrome.exe"
 });
+/** Names the persisted journey snapshot. */
+var BROWSER_JOURNEY_SNAPSHOT_FILE = "journey.json";
+/** Names the retained journey revision counter. */
+var BROWSER_JOURNEY_REVISION_FILE = "revision";
+/** Names the exclusive journey write lock directory. */
+var BROWSER_JOURNEY_LOCK_DIRECTORY = "journey.lock";
+/** Bounds attempts to acquire a journey lock after concurrent recovery. */
+var BROWSER_JOURNEY_LOCK_ATTEMPTS = 8;
+/** Names the persisted run snapshot. */
+var BROWSER_RUN_FILE = "run.json";
+/** Names the journey directory holding its runs. */
+var BROWSER_RUN_DIRECTORY = "runs";
+/** Bounds a file-store listing page by default. */
+var BROWSER_FILE_STORE_LIMIT = 100;
 //#endregion
 //#region src/server/errors.ts
 /**
-* Reports that a CDP connection, discovery, or launch attempt failed, under the code
-* `BROWSER_CONNECTION_ERROR`.
-*/
-var BrowserConnectionError = class extends BrowserError {
-	constructor(message, context) {
-		super(message, "BROWSER_CONNECTION_ERROR", context);
-		this.name = "BrowserConnectionError";
-	}
-};
-/**
 * Reports that an operation requiring an active connection was attempted while disconnected,
 * under the code `BROWSER_NOT_CONNECTED_ERROR`.
 */
@@ -209,15 +234,6 @@ var BrowserDestroyedError = class extends BrowserError {
 	}
 };
 /**
-* Narrows an unknown value to a `BrowserConnectionError`.
-*
-* @param value - Value to check
-* @returns True if value is a BrowserConnectionError instance; false otherwise
-*/
-function isBrowserConnectionError(value) {
-	return isInstance(value, BrowserConnectionError);
-}
-/**
 * Narrows an unknown value to a `BrowserNotConnectedError`.
 *
 * @param value - Value to check
@@ -238,6 +254,30 @@ function isBrowserDestroyedError(value) {
 //#endregion
 //#region src/server/helpers.ts
 /**
+* Formats a process identifier and UUID token as a lock entry name.
+* @param pid - Positive safe integer identifying the holder process
+* @param token - Lowercase UUID token identifying this acquisition
+* @returns The entry name
+* @example
+* formatBrowserLockEntry(123, '11111111-1111-4111-8111-111111111111')
+*/
+function formatBrowserLockEntry(pid, token) {
+	return `${pid}-${token}`;
+}
+/**
+* Parses the holder process identifier from a lock entry name.
+* @remarks Requires a positive safe integer followed by a lowercase UUID token.
+* @param name - Directory entry name
+* @returns The process identifier, or undefined when the entry is malformed
+* @example
+* parseBrowserLockEntry('123-11111111-1111-4111-8111-111111111111') // 123
+*/
+function parseBrowserLockEntry(name) {
+	const match = /^([1-9]\d*)-[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/.exec(name);
+	const pid = Number(match?.[1]);
+	return Number.isSafeInteger(pid) && pid > 0 ? pid : void 0;
+}
+/**
 * Enumerates every Chrome/Chromium/Edge executable discoverable on this
 * machine, deduplicated by normalized absolute path.
 *
@@ -467,57 +507,69 @@ function findStorePaths(base, platform) {
 * subprocesses with it, so that single signal drains the tree.
 *
 * @param executable - Absolute path to the browser executable
-* @param port - Port the browser exposes its CDP endpoint on
+* @param port - Port the browser exposes its CDP endpoint on, or undefined for a port the operating system picks
 * @param headless - Whether to launch in headless mode
 * @param profile - Optional user-data-dir for a persistent profile
 * @param extra - Additional command-line flags
-* @returns The spawned ChildProcess
+* @returns The spawned ChildProcess, whose standard error carries the endpoint line `readBrowserEndpoint` reads
 */
 function launchBrowserProcess(executable, port, headless, profile, extra) {
 	const args = [];
 	if (extra !== void 0) args.push(...extra);
-	args.push(`--remote-debugging-port=${port}`, ...BROWSER_LAUNCH_ARGS);
+	args.push(`--remote-debugging-port=${port ?? 0}`, ...BROWSER_LAUNCH_ARGS);
 	if (headless) args.push(BROWSER_HEADLESS_ARG);
 	if (profile !== void 0) args.push(`--user-data-dir=${profile}`);
 	return spawn(executable, args, {
-		stdio: "ignore",
+		stdio: [
+			"ignore",
+			"ignore",
+			"pipe"
+		],
 		detached: process.platform !== "win32"
 	});
 }
 /**
-* Polls a browser's CDP version endpoint until it responds or the timeout elapses.
+* Reads the CDP endpoint a launched browser announces on its standard error.
 *
-* @param port - Port the browser exposes its CDP endpoint on
-* @param timeout - Maximum time to wait in milliseconds
-* @param host - Host the browser exposes its CDP endpoint on (default `127.0.0.1`)
-* @param signal - Optional external abort; an abort while waiting rethrows rather than resolving
-* @returns The browser's WebSocket debugger URL
+* @remarks
+* Chromium prints `DevTools listening on ws://HOST:PORT/devtools/browser/ID` after it binds the
+* debugging port. The read splits arriving text on line breaks across chunks, so a line split
+* between two chunks and a line ending `\r\n` both resolve. After resolving, the stream keeps
+* draining until it closes so the browser's logging never fills the pipe.
+*
+* @param stream - The browser's standard error
+* @param signal - Abort that rejects the read with its reason
+* @returns The `ws://` endpoint the browser announced
 *
-* @throws When the endpoint does not become ready before the timeout
+* @throws When the stream closes without the line, or the signal aborts first
 */
-async function waitForCDPReady(port, timeout, host = BROWSER_DEFAULT_HOST, signal) {
-	const url = `${BROWSER_CDP_PROTOCOL}://${host}:${port}${BROWSER_CDP_VERSION_PATH}`;
-	const deadline = Date.now() + timeout;
-	while (Date.now() < deadline) {
-		signal?.throwIfAborted();
-		const remaining = Math.max(0, deadline - Date.now());
-		const requestSignal = signal === void 0 ? AbortSignal.timeout(remaining) : AbortSignal.any([signal, AbortSignal.timeout(remaining)]);
-		try {
-			const response = await fetch(url, { signal: requestSignal });
-			if (response.ok) {
-				const info = await response.json();
-				if (isRecord(info) && isString(info["webSocketDebuggerUrl"])) return info["webSocketDebuggerUrl"];
-			}
-		} catch (error) {
-			if (signal?.aborted === true) throw error;
+function readBrowserEndpoint(stream, signal) {
+	const read = Promise.withResolvers();
+	let pending = "";
+	let found = false;
+	if (signal.aborted) read.reject(signal.reason);
+	signal.addEventListener("abort", () => read.reject(signal.reason), { once: true });
+	stream.on("error", read.reject);
+	stream.setEncoding("utf8");
+	stream.on("data", (chunk) => {
+		if (found || !isString(chunk)) return;
+		const lines = (pending + chunk).split(/\r\n|\n/);
+		pending = lines.pop() ?? "";
+		for (const line of lines) {
+			const endpoint = BROWSER_DEVTOOLS_PATTERN.exec(line)?.[1];
+			if (endpoint === void 0) continue;
+			found = true;
+			pending = "";
+			read.resolve(endpoint);
+			return;
 		}
-		const delay = Math.min(BROWSER_WAIT_POLL_INTERVAL_MS, Math.max(0, deadline - Date.now()));
-		if (delay > 0) await setTimeout$1(delay, void 0, { signal });
-	}
-	throw new BrowserConnectionError(`CDP endpoint on port ${port} did not become ready within ${timeout}ms`, {
-		port,
-		timeout
 	});
+	stream.on("close", () => {
+		const endpoint = found ? void 0 : BROWSER_DEVTOOLS_PATTERN.exec(pending)?.[1];
+		if (endpoint !== void 0) read.resolve(endpoint);
+		else read.reject(new BrowserConnectionError("Browser closed its standard error before reporting a CDP endpoint"));
+	});
+	return read.promise;
 }
 /**
 * Fetches the current CDP target list from a browser's `/json/list` endpoint, as a `Result`
@@ -814,6 +866,790 @@ var FileBrowserWriter = class {
 	}
 };
 //#endregion
+//#region package.json
+var version = "0.0.19";
+//#endregion
+//#region src/server/BrowserMCPServer.ts
+/**
+* Implements `BrowserMCPServerInterface`: serves the browser vocabulary and the journey tools over
+* the Model Context Protocol on stdio, and launches Chromium on the first tool call.
+*
+* @remarks
+* The server's own manager holds one dispatcher per name of the vocabulary — `look`, `read`,
+* `click`, `type`, `press`, `navigate`, `wait`, `dialog`, `tabs`, `switch`, `record`, `save`,
+* `journeys`, `edit`, and `replay` — each carrying the description, parameters, and annotations
+* `BROWSER_TOOL_COPY` gives, so `tools/list` answers before Chromium starts and with Chromium
+* absent. After the launch, a tool the toolset's manager adds under another name, such as a page
+* tool it adopts, is mirrored as a dispatcher with that tool's definition, and the mirror is
+* removed when the toolset withdraws the tool, so the server's tool list changes and a subscribed
+* client is notified. The first call of any dispatcher launches Chromium one time: concurrent callers await
+* the same launch, a failed launch rejects every one of them, and the next call launches again.
+* A launch creates `ROOT/.profiles/ID/` exclusively, connects a browser that never attaches to an
+* existing endpoint, opens one page in an isolated context, and constructs the page toolset with
+* that context and the file journey and run stores under the root, on a manager the toolset owns.
+* A dispatcher forwards its arguments and the call's context, signal included, to the toolset's
+* manager and returns that manager's value, or rejects with its failure message; a text value
+* reaches the client as one text block rather than as its JSON text.
+*
+* `start()` serves stdio and destroys the server at the end of its input, on `SIGINT`, and on
+* `SIGTERM`. `destroy()` stops reading requests and removes every dispatcher, then destroys the
+* toolset, which aborts the active replay, then the browser it launched, then removes the profile.
+*
+* Chromium on Linux refuses to start as the root user unless its sandbox is disabled, so a server
+* running as root on Linux launches Chromium with `--no-sandbox`; a launch that could run
+* sandboxed is never changed.
+*
+* @example
+* ```ts
+* import { BrowserMCPServer } from '@orkestrel/browser/server'
+*
+* const server = new BrowserMCPServer({ root: 'tmp/browsers', readonly: true })
+* await server.start()
+* await server.destroy()
+* ```
+*/
+var BrowserMCPServer = class {
+	#root;
+	#headless;
+	#executable;
+	#readonly;
+	#launcher;
+	#input;
+	#tools;
+	#transport;
+	#abort = new AbortController();
+	#signal;
+	#vocabulary;
+	#added;
+	#removed;
+	#cleared;
+	#mirrored;
+	#session;
+	#browser;
+	#profile;
+	#started = false;
+	#closing;
+	/**
+	* Registers the dispatchers and binds the protocol to the stdio streams without reading them.
+	*
+	* @param options - The root, the launch, the journeys' read-only switch, and the streams
+	*/
+	constructor(options) {
+		this.#root = resolve(options?.root ?? "tmp/browsers");
+		this.#headless = options?.headless ?? true;
+		this.#executable = options?.executable;
+		this.#readonly = options?.readonly ?? false;
+		this.#launcher = options?.launch ?? createBrowser;
+		this.#input = options?.stdio?.input ?? process.stdin;
+		this.#tools = createToolManager();
+		const names = [...BROWSER_TOOL_NAMES, ...BROWSER_JOURNEY_TOOL_NAMES];
+		this.#vocabulary = new Set(names);
+		for (const name of names) this.#tools.add(createTool({
+			...BROWSER_TOOL_COPY[name],
+			execute: this.#forward.bind(this, name)
+		}));
+		const server = createMCPServer({
+			identity: {
+				name: "browse",
+				version
+			},
+			tools: this.#tools,
+			execution: this.#execute.bind(this)
+		});
+		this.#transport = createStdioServer(createMCPLegacy(server), {
+			input: this.#input,
+			...options?.stdio?.output === void 0 ? {} : { output: options.stdio.output }
+		});
+		this.#signal = this.#end.bind(this);
+		this.#added = this.#mirror.bind(this);
+		this.#removed = this.#withdraw.bind(this);
+		this.#cleared = this.#clear.bind(this);
+	}
+	async start() {
+		if (this.#closing !== void 0) throw this.#ended();
+		if (this.#started) return;
+		this.#started = true;
+		this.#transport.start();
+		this.#input.on("end", this.#signal);
+		process.on("SIGINT", this.#signal);
+		process.on("SIGTERM", this.#signal);
+	}
+	destroy() {
+		this.#closing ??= this.#destroy();
+		return this.#closing;
+	}
+	async #destroy() {
+		process.removeListener("SIGINT", this.#signal);
+		process.removeListener("SIGTERM", this.#signal);
+		this.#input.removeListener("end", this.#signal);
+		this.#transport.stop();
+		for (const tool of this.#tools.tools()) this.#tools.remove(tool.name);
+		this.#unmirror();
+		this.#abort.abort();
+		const failures = [];
+		await (await this.#session?.catch(() => void 0))?.destroy().catch((error) => failures.push(error));
+		await this.#browser?.destroy().catch((error) => failures.push(error));
+		this.#browser = void 0;
+		const profile = this.#profile;
+		this.#profile = void 0;
+		if (profile !== void 0) await rm(profile, {
+			recursive: true,
+			force: true,
+			maxRetries: 5
+		});
+		if (failures.length > 0) throw new AggregateError(failures, "The browse server teardown failed");
+	}
+	async #execute(context) {
+		const result = await context.tools.execute(context.call, {
+			signal: context.signal,
+			...context.caller === void 0 ? {} : { caller: context.caller }
+		});
+		if (!result.success || typeof result.value !== "string") return result;
+		return {
+			resultType: "complete",
+			content: [{
+				type: "text",
+				text: result.value
+			}]
+		};
+	}
+	#end() {
+		this.destroy();
+	}
+	async #forward(name, args, context) {
+		const result = await (await this.#open()).tools.execute({
+			id: name,
+			name,
+			arguments: args
+		}, context);
+		if (!result.success) throw new BrowserError(result.error);
+		return result.value;
+	}
+	#open() {
+		if (this.#closing !== void 0) return Promise.reject(this.#ended());
+		const current = this.#session;
+		if (current !== void 0) return current;
+		const session = this.#launch();
+		this.#session = session;
+		session.catch(() => {
+			if (this.#session === session) this.#session = void 0;
+		});
+		return session;
+	}
+	async #launch() {
+		await mkdir(this.#root, { recursive: true });
+		const profiles = join(this.#root, ".profiles");
+		await mkdir(profiles, { recursive: true });
+		const profile = join(profiles, randomUUID());
+		await mkdir(profile);
+		this.#profile = profile;
+		let browser;
+		let toolset;
+		try {
+			browser = this.#launcher({
+				headless: this.#headless,
+				profile,
+				cdp: { discover: false },
+				signal: this.#abort.signal,
+				...this.#executable === void 0 ? {} : { executable: this.#executable },
+				...process.platform === "linux" && process.getuid?.() === 0 ? { args: ["--no-sandbox"] } : {}
+			});
+			this.#browser = browser;
+			await browser.connect();
+			const context = await browser.isolate();
+			const page = await context.create();
+			toolset = createBrowserToolset(page, {
+				context,
+				journeys: {
+					store: createFileBrowserJourneyStore({ root: this.#root }),
+					runs: createFileBrowserRunStore({ root: this.#root }),
+					readonly: this.#readonly
+				}
+			});
+			this.#mirrored = toolset.tools;
+			toolset.tools.emitter.on("add", this.#added);
+			toolset.tools.emitter.on("remove", this.#removed);
+			toolset.tools.emitter.on("clear", this.#cleared);
+			await toolset.start();
+			return toolset;
+		} catch (error) {
+			this.#unmirror();
+			if (this.#browser === browser) this.#browser = void 0;
+			if (this.#profile === profile) this.#profile = void 0;
+			await toolset?.destroy().catch(() => void 0);
+			await browser?.destroy().catch(() => void 0);
+			await rm(profile, {
+				recursive: true,
+				force: true,
+				maxRetries: 5
+			});
+			throw error;
+		}
+	}
+	#mirror(tool) {
+		if (this.#vocabulary.has(tool.name)) return;
+		this.#tools.add(createTool({
+			...toolToDefinition(tool),
+			execute: this.#forward.bind(this, tool.name)
+		}));
+	}
+	#withdraw(tool) {
+		if (this.#vocabulary.has(tool.name)) return;
+		const current = this.#mirrored?.tool(tool.name);
+		if (current === void 0) this.#tools.remove(tool.name);
+		else this.#mirror(current);
+	}
+	#clear(tools) {
+		for (const tool of tools) this.#withdraw(tool);
+	}
+	#unmirror() {
+		const mirrored = this.#mirrored;
+		if (mirrored === void 0) return;
+		this.#mirrored = void 0;
+		mirrored.emitter.off("add", this.#added);
+		mirrored.emitter.off("remove", this.#removed);
+		mirrored.emitter.off("clear", this.#cleared);
+	}
+	#ended() {
+		return new BrowserError("the browser session ended", "BROWSER_TOOLSET_ENDED");
+	}
+};
+//#endregion
+//#region src/server/stores/FileBrowserStore.ts
+/**
+* Shares confined filesystem operations between the journey and run stores.
+* @remarks Requires an existing root directory. Links present during a component check are refused;
+* replacement between a check and its use by another filesystem writer is outside this boundary.
+* @example
+* const files = new FileBrowserStore({ root: directory })
+* files.validateName('check-ready')
+*/
+var FileBrowserStore = class {
+	#root;
+	#limit;
+	constructor(options) {
+		this.#limit = options.limit ?? 100;
+		if (!Number.isSafeInteger(this.#limit) || this.#limit < 1) throw new BrowserError("The listing cap must be a positive integer", "BROWSER_JOURNEY_ARGUMENT");
+		try {
+			this.#root = realpathSync(options.root);
+		} catch (error) {
+			if (error instanceof Error && "code" in error && error.code === "ENOENT") throw new BrowserError(`Missing root: ${options.root}`, "BROWSER_JOURNEY_PATH", { path: options.root });
+			throw this.translateError(options.root, error);
+		}
+	}
+	/** Checks a journey name before filesystem access. @param name - Journey name */
+	validateName(name) {
+		if (!BROWSER_JOURNEY_NAME_PATTERN.test(name)) throw new BrowserError(`Refused journey name: ${name}`, "BROWSER_JOURNEY_PATH");
+	}
+	/** Checks a run id before filesystem access. @param id - Producer id */
+	validateId(id) {
+		if (!BROWSER_RUN_ID_PATTERN.test(id)) throw new BrowserError(`Refused run id: ${id}`, "BROWSER_JOURNEY_PATH");
+	}
+	/** Resolves a confined target. @param parts - Relative components @returns Absolute target */
+	resolvePath(...parts) {
+		const path = resolve(this.#root, ...parts);
+		if (path !== this.#root && !path.startsWith(this.#root.endsWith(sep) ? this.#root : this.#root + sep)) throw new BrowserError(`Refused path: ${path}`, "BROWSER_JOURNEY_PATH");
+		return path;
+	}
+	/**
+	* Checks every existing component including the root and target.
+	* @param path - Absolute target
+	* @param options - Cancellation options
+	* @returns True if the target exists; false if a component is missing
+	*/
+	async check(path, options) {
+		this.resolvePath(path);
+		let current = this.#root;
+		const parts = relative(this.#root, path).split(sep).filter(Boolean);
+		for (let index = 0; index <= parts.length; index += 1) {
+			options?.signal?.throwIfAborted();
+			try {
+				const status = await lstat(current);
+				options?.signal?.throwIfAborted();
+				if (status.isSymbolicLink()) throw new BrowserError(`Refused symbolic link: ${current}`, "BROWSER_JOURNEY_PATH");
+				if (index < parts.length && !status.isDirectory()) throw new BrowserError(`Not a directory: ${current}`, "BROWSER_JOURNEY_PATH");
+			} catch (error) {
+				options?.signal?.throwIfAborted();
+				if (error instanceof Error && "code" in error && error.code === "ENOENT") return false;
+				throw this.translateError(current, error);
+			}
+			const part = parts[index];
+			if (part !== void 0) current = this.resolvePath(current, part);
+		}
+		return true;
+	}
+	/** Creates checked directories one component at a time. @param path - Directory @param options - Cancellation options */
+	async createDirectory(path, options) {
+		if (await this.check(path, options)) return;
+		if (path === this.#root) throw new BrowserError(`Missing root: ${path}`, "BROWSER_JOURNEY_PATH");
+		await this.createDirectory(dirname(path), options);
+		options?.signal?.throwIfAborted();
+		try {
+			await mkdir(path);
+		} catch (error) {
+			if (!(error instanceof Error && "code" in error && error.code === "EEXIST")) throw this.translateError(path, error);
+		}
+		await this.check(path, options);
+	}
+	/** Reads an existing file without collapsing a fault to absence. @param path - File @param options - Cancellation options @returns Bytes as UTF-8, or absence */
+	async read(path, options) {
+		if (!await this.check(path, options)) return void 0;
+		try {
+			options?.signal?.throwIfAborted();
+			const value = await readFile(path, {
+				encoding: "utf8",
+				signal: options?.signal
+			});
+			options?.signal?.throwIfAborted();
+			return value;
+		} catch (error) {
+			options?.signal?.throwIfAborted();
+			if (error instanceof Error && "code" in error && error.code === "ENOENT") return void 0;
+			throw this.translateError(path, error);
+		}
+	}
+	/** Atomically replaces a file and cleans its owned temporary file on failure. @param path - Destination @param value - Bytes or UTF-8 @param options - Cancellation options */
+	async write(path, value, options) {
+		const temporary = this.resolvePath(dirname(path), `.${randomUUID()}.tmp`);
+		let owned = false;
+		try {
+			await this.check(path, options);
+			await this.check(temporary, options);
+			options?.signal?.throwIfAborted();
+			const file = await open(temporary, "wx");
+			owned = true;
+			try {
+				options?.signal?.throwIfAborted();
+				await file.writeFile(value, { signal: options?.signal });
+			} finally {
+				await file.close();
+			}
+			await this.check(path, options);
+			await this.check(temporary, options);
+			options?.signal?.throwIfAborted();
+			await rename(temporary, path);
+			owned = false;
+		} catch (error) {
+			options?.signal?.throwIfAborted();
+			throw this.translateError(path, error);
+		} finally {
+			if (owned) await this.remove(temporary);
+		}
+	}
+	/** Removes a checked file, accepting absence. @param path - File @param options - Cancellation options */
+	async remove(path, options) {
+		if (!await this.check(path, options)) return;
+		try {
+			options?.signal?.throwIfAborted();
+			await unlink(path);
+		} catch (error) {
+			options?.signal?.throwIfAborted();
+			if (!(error instanceof Error && "code" in error && error.code === "ENOENT")) throw this.translateError(path, error);
+		}
+	}
+	/**
+	* Holds a directory lock through a mutation and releases only its named entry.
+	* @remarks Reclaims dead or empty locks within a bounded attempt count; a live or unknown holder refuses.
+	* @param path - Lock directory
+	* @param action - Mutation inside the lock
+	* @param options - Cancellation options
+	* @returns The mutation result
+	*/
+	async lock(path, action, options) {
+		await this.createDirectory(dirname(path), options);
+		const name = formatBrowserLockEntry(process.pid, randomUUID());
+		const entry = this.resolvePath(path, name);
+		for (let attempt = 0; attempt < 8; attempt += 1) {
+			await this.check(path, options);
+			options?.signal?.throwIfAborted();
+			try {
+				await mkdir(path);
+			} catch (error) {
+				if (!(error instanceof Error && "code" in error && error.code === "EEXIST")) throw this.translateError(path, error);
+				const entries = await this.#readLock(path, options);
+				if (entries === void 0) continue;
+				if (entries.length > 1) break;
+				const holder = entries[0];
+				if (holder !== void 0) {
+					const pid = parseBrowserLockEntry(holder);
+					if (pid === void 0) break;
+					try {
+						process.kill(pid, 0);
+						break;
+					} catch (cause) {
+						if (!(cause instanceof Error && "code" in cause && cause.code === "ESRCH")) break;
+					}
+					if (!await this.#unlinkLock(this.resolvePath(path, holder))) continue;
+				}
+				await this.#removeLock(path);
+				continue;
+			}
+			let owned = false;
+			try {
+				await this.check(entry, options);
+				try {
+					const file = await open(entry, "wx");
+					owned = true;
+					await file.close();
+				} catch (error) {
+					if (error instanceof Error && "code" in error && error.code === "ENOENT") continue;
+					throw this.translateError(entry, error);
+				}
+				const entries = await this.#readLock(path, options);
+				if (entries?.length !== 1 || entries[0] !== name) break;
+				options?.signal?.throwIfAborted();
+				return await action();
+			} finally {
+				if (owned) await this.#unlinkLock(entry);
+				await this.#removeLock(path);
+			}
+		}
+		throw new BrowserError(`Journey is locked: ${path}`, "BROWSER_JOURNEY_LOCKED");
+	}
+	/**
+	* Lists readable entries in sorted order with a bounded page and one extra readable probe.
+	* @param path - Parent directory
+	* @param reader - Entry reader
+	* @param options - Paging and cancellation
+	* @returns Page and observed entry faults
+	*/
+	async list(path, reader, options) {
+		const offset = options?.offset ?? 0;
+		const requested = options?.limit ?? this.#limit;
+		validateBrowserStorePage(offset, requested);
+		const limit = Math.min(requested, this.#limit);
+		const entries = [];
+		const faults = [];
+		if (!await this.check(path, options)) return {
+			entries,
+			faults,
+			truncated: false
+		};
+		let names;
+		try {
+			options?.signal?.throwIfAborted();
+			names = (await readdir(path)).sort();
+		} catch (error) {
+			options?.signal?.throwIfAborted();
+			throw this.translateError(path, error);
+		}
+		let count = 0;
+		for (const name of names) {
+			options?.signal?.throwIfAborted();
+			try {
+				const entry = await reader(name);
+				if (entry === void 0) continue;
+				if (count++ < offset) continue;
+				if (entries.length === limit) return {
+					entries,
+					faults,
+					truncated: true
+				};
+				entries.push(entry);
+			} catch (error) {
+				options?.signal?.throwIfAborted();
+				const reason = error instanceof BrowserError ? error.context?.["reason"] : void 0;
+				faults.push({
+					name,
+					reason: typeof reason === "string" ? reason : error instanceof BrowserError && error.code === "BROWSER_JOURNEY_PATH" ? "The entry path is refused" : error instanceof BrowserError && error.code === "BROWSER_JOURNEY_ACCESS" ? "Permission denied" : error instanceof BrowserError && error.code === "BROWSER_JOURNEY_FORMAT" ? "Unknown file format" : "The stored entry is malformed or unreadable"
+				});
+			}
+		}
+		return {
+			entries,
+			faults,
+			truncated: false
+		};
+	}
+	/**
+	* Allocates a run directory exclusively, retrying colliding producer candidates.
+	* @param parent - Checked parent directory
+	* @param candidate - Producer id source
+	* @param options - Cancellation options
+	* @returns Allocated id and absolute directory
+	*/
+	async allocate(parent, candidate, options) {
+		await this.createDirectory(parent, options);
+		for (;;) {
+			options?.signal?.throwIfAborted();
+			const id = candidate();
+			this.validateId(id);
+			const path = this.resolvePath(parent, id);
+			await this.check(path, options);
+			try {
+				options?.signal?.throwIfAborted();
+				await mkdir(path);
+				options?.signal?.throwIfAborted();
+				return {
+					id,
+					path
+				};
+			} catch (error) {
+				options?.signal?.throwIfAborted();
+				if (error instanceof Error && "code" in error && error.code === "EEXIST") continue;
+				throw this.translateError(path, error);
+			}
+		}
+	}
+	/** Translates filesystem and validation failures with their path. @param path - Failed path @param error - Cause @returns Coded error */
+	translateError(path, error) {
+		const code = error instanceof Error && "code" in error ? error.code : void 0;
+		return new BrowserError(`${path}: ${error instanceof Error ? error.message : String(error)}`, code === "EACCES" || code === "EPERM" ? "BROWSER_JOURNEY_ACCESS" : error instanceof BrowserError && code !== "BROWSER_JOURNEY_INVALID" ? error.code : "BROWSER_JOURNEY_FILE", { path });
+	}
+	async #readLock(path, options) {
+		await this.check(path, options);
+		try {
+			const entries = await readdir(path, { withFileTypes: true });
+			for (const entry of entries) {
+				await this.check(this.resolvePath(path, entry.name), options);
+				if (!entry.isFile()) throw new BrowserError(`Journey is locked: ${path}`, "BROWSER_JOURNEY_LOCKED");
+			}
+			return entries.map((entry) => entry.name);
+		} catch (error) {
+			if (error instanceof Error && "code" in error) {
+				if (error.code === "ENOENT") return void 0;
+				if (error.code === "ENOTDIR") throw new BrowserError(`Journey is locked: ${path}`, "BROWSER_JOURNEY_LOCKED");
+			}
+			throw this.translateError(path, error);
+		}
+	}
+	async #unlinkLock(path) {
+		await this.check(path);
+		try {
+			await unlink(path);
+			return true;
+		} catch (error) {
+			if (error instanceof Error && "code" in error && (error.code === "ENOENT" || error.code === "ENOTEMPTY")) return false;
+			throw new BrowserError(`Cannot remove lock entry: ${path}`, "BROWSER_JOURNEY_ACCESS", { path });
+		}
+	}
+	async #removeLock(path) {
+		await this.check(path);
+		try {
+			await rmdir(path);
+		} catch (error) {
+			if (error instanceof Error && "code" in error && (error.code === "ENOENT" || error.code === "ENOTEMPTY")) return;
+			throw new BrowserError(`Cannot remove lock directory: ${path}`, "BROWSER_JOURNEY_ACCESS", { path });
+		}
+	}
+};
+//#endregion
+//#region src/server/stores/FileBrowserJourneyStore.ts
+/**
+* Persists journeys with exclusive writes and revision counters retained across deletion.
+* @remarks Requires an existing root. A live holder refuses immediately; dead or empty locks are reclaimed within a bounded attempt count.
+* @example
+* const store = new FileBrowserJourneyStore({ root: directory })
+* await store.set(journey)
+*/
+var FileBrowserJourneyStore = class {
+	#files;
+	constructor(options) {
+		this.#files = new FileBrowserStore(options);
+	}
+	async get(name, options) {
+		options?.signal?.throwIfAborted();
+		this.#files.validateName(name);
+		const path = this.#files.resolvePath(name, BROWSER_JOURNEY_SNAPSHOT_FILE);
+		const source = await this.#files.read(path, options);
+		if (source === void 0) return void 0;
+		try {
+			const value = parseJSON(source);
+			if (!isRecord(value) || typeof value["revision"] !== "number" || !Number.isSafeInteger(value["revision"]) || value["revision"] < 1) throw new BrowserError("Malformed journey revision", "BROWSER_JOURNEY_FILE");
+			if (!isRecord(value["journey"]) || !("format" in value["journey"])) throw new BrowserError("Missing journey format", "BROWSER_JOURNEY_FILE");
+			validateBrowserJourney(value["journey"]);
+			if (value["journey"].name !== name) throw new BrowserError("Journey name differs from its directory", "BROWSER_JOURNEY_FILE");
+			return {
+				journey: value["journey"],
+				revision: value["revision"]
+			};
+		} catch (error) {
+			const translated = this.#files.translateError(path, error);
+			throw new BrowserError(translated.message, translated.code, {
+				...translated.context,
+				reason: normalizeBrowserJourneyReason(error)
+			});
+		}
+	}
+	async set(journey, expected, options) {
+		options?.signal?.throwIfAborted();
+		this.#files.validateName(journey.name);
+		validateBrowserJourney(journey);
+		const owned = structuredClone(journey);
+		const path = this.#files.resolvePath(owned.name, BROWSER_JOURNEY_SNAPSHOT_FILE);
+		const counter = this.#files.resolvePath(owned.name, BROWSER_JOURNEY_REVISION_FILE);
+		return this.#files.lock(this.#files.resolvePath(owned.name, BROWSER_JOURNEY_LOCK_DIRECTORY), async () => {
+			const current = await this.get(owned.name, options);
+			if (expected !== void 0 && expected !== (current?.revision ?? 0)) throw new BrowserError(`Journey ${owned.name} changed since you read it`, "BROWSER_JOURNEY_STALE");
+			const source = await this.#files.read(counter, options);
+			const previous = source === void 0 ? 0 : Number(source);
+			if (!Number.isSafeInteger(previous) || previous < 0 || source?.trim() === "") throw new BrowserError(`Malformed revision: ${counter}`, "BROWSER_JOURNEY_FILE");
+			const revision = Math.max(previous, current?.revision ?? 0) + 1;
+			if (!Number.isSafeInteger(revision)) throw new BrowserError(`Exhausted revision: ${counter}`, "BROWSER_JOURNEY_FILE");
+			const saved = {
+				journey: owned,
+				revision
+			};
+			await this.#files.write(path, JSON.stringify(saved), options);
+			try {
+				await this.#files.write(counter, String(revision), options);
+			} catch (error) {
+				if (current === void 0) await this.#files.remove(path);
+				else await this.#files.write(path, JSON.stringify(current));
+				throw error;
+			}
+			return saved;
+		}, options);
+	}
+	async delete(name, options) {
+		options?.signal?.throwIfAborted();
+		this.#files.validateName(name);
+		await this.#files.lock(this.#files.resolvePath(name, BROWSER_JOURNEY_LOCK_DIRECTORY), async () => {
+			const current = await this.get(name, options);
+			if (current === void 0) return;
+			const counter = this.#files.resolvePath(name, BROWSER_JOURNEY_REVISION_FILE);
+			const source = await this.#files.read(counter, options);
+			const previous = source === void 0 ? 0 : Number(source);
+			if (!Number.isSafeInteger(previous) || previous < 0 || source?.trim() === "") throw new BrowserError(`Malformed revision: ${counter}`, "BROWSER_JOURNEY_FILE");
+			await this.#files.write(counter, String(Math.max(previous, current.revision ?? 0)), options);
+			await this.#files.remove(this.#files.resolvePath(name, BROWSER_JOURNEY_SNAPSHOT_FILE), options);
+		}, options);
+	}
+	async list(options) {
+		options?.signal?.throwIfAborted();
+		return this.#files.list(this.#files.resolvePath(), async (name) => {
+			if (!BROWSER_JOURNEY_NAME_PATTERN.test(name)) return void 0;
+			return this.get(name, options);
+		}, options);
+	}
+};
+//#endregion
+//#region src/server/stores/FileBrowserRunStore.ts
+/**
+* Persists runs and captures only in directories allocated by this instance.
+* @remarks Requires an existing root. Reopened stores can read and delete saved runs.
+* @example
+* const store = new FileBrowserRunStore({ root: directory })
+* const slot = await store.open('check-ready')
+*/
+var FileBrowserRunStore = class {
+	#files;
+	#slots = /* @__PURE__ */ new WeakMap();
+	#directories = /* @__PURE__ */ new Set();
+	constructor(options) {
+		this.#files = new FileBrowserStore(options);
+	}
+	async open(name, options) {
+		options?.signal?.throwIfAborted();
+		this.#files.validateName(name);
+		return this.#files.lock(this.#files.resolvePath(name, BROWSER_JOURNEY_LOCK_DIRECTORY), async () => {
+			const directory = await this.#files.allocate(this.#files.resolvePath(name, BROWSER_RUN_DIRECTORY), generateBrowserRunId, options);
+			const slot = Object.freeze({
+				id: directory.id,
+				directory: directory.path
+			});
+			this.#directories.add(directory.path);
+			this.#slots.set(slot, directory.path);
+			return slot;
+		}, options);
+	}
+	async get(name, id, options) {
+		options?.signal?.throwIfAborted();
+		this.#files.validateName(name);
+		this.#files.validateId(id);
+		const path = this.#files.resolvePath(name, BROWSER_RUN_DIRECTORY, id, BROWSER_RUN_FILE);
+		const source = await this.#files.read(path, options);
+		if (source === void 0) return void 0;
+		try {
+			const value = parseJSON(source);
+			if (!isRecord(value) || !("format" in value)) throw new BrowserError("Missing run format", "BROWSER_JOURNEY_FILE");
+			if (value["format"] === BROWSER_JOURNEY_FORMAT_VERSION && (!isRecord(value["journey"]) || !("format" in value["journey"]))) throw new BrowserError("Missing run journey format", "BROWSER_JOURNEY_FILE");
+			validateBrowserRun(value);
+			if (value.id !== id || value.journey.name !== name) throw new BrowserError("Run identity differs from its directory", "BROWSER_JOURNEY_FILE");
+			return value;
+		} catch (error) {
+			throw this.#files.translateError(path, error);
+		}
+	}
+	async set(run, options) {
+		options?.signal?.throwIfAborted();
+		this.#files.validateName(run.journey.name);
+		this.#files.validateId(run.id);
+		validateBrowserRun(run);
+		const source = JSON.stringify(run);
+		const directory = this.#files.resolvePath(run.journey.name, BROWSER_RUN_DIRECTORY, run.id);
+		await this.#requireDirectory(directory, options);
+		await this.#files.write(this.#files.resolvePath(directory, BROWSER_RUN_FILE), source, options);
+	}
+	async capture(slot, name, bytes, options) {
+		options?.signal?.throwIfAborted();
+		const directory = this.#slots.get(slot);
+		if (directory === void 0 || !/^s[1-9]\d*\.png$/.test(name)) throw new BrowserError("Capture requires an opened slot and an sN.png name", "BROWSER_JOURNEY_PATH");
+		const owned = new Uint8Array(bytes);
+		await this.#requireDirectory(directory, options);
+		await this.#files.write(this.#files.resolvePath(directory, name), owned, options);
+		return name;
+	}
+	async delete(name, id, options) {
+		options?.signal?.throwIfAborted();
+		this.#files.validateName(name);
+		this.#files.validateId(id);
+		const directory = this.#files.resolvePath(name, BROWSER_RUN_DIRECTORY, id);
+		await this.#files.check(this.#files.resolvePath(directory, BROWSER_RUN_FILE), options);
+		try {
+			options?.signal?.throwIfAborted();
+			await rm(directory, {
+				recursive: true,
+				force: true,
+				maxRetries: 3
+			});
+			this.#directories.delete(directory);
+			options?.signal?.throwIfAborted();
+		} catch (error) {
+			options?.signal?.throwIfAborted();
+			throw this.#files.translateError(directory, error);
+		}
+	}
+	async clear(name, options) {
+		options?.signal?.throwIfAborted();
+		this.#files.validateName(name);
+		const parent = this.#files.resolvePath(name, BROWSER_RUN_DIRECTORY);
+		if (!await this.#files.check(parent, options)) return 0;
+		return this.#files.lock(this.#files.resolvePath(name, BROWSER_JOURNEY_LOCK_DIRECTORY), async () => {
+			try {
+				options?.signal?.throwIfAborted();
+				const ids = await readdir(parent);
+				for (const id of ids) {
+					this.#files.validateId(id);
+					await this.#files.check(this.#files.resolvePath(parent, id, BROWSER_RUN_FILE), options);
+				}
+				for (const id of ids) await this.delete(name, id, options);
+				return ids.length;
+			} catch (error) {
+				options?.signal?.throwIfAborted();
+				throw this.#files.translateError(parent, error);
+			}
+		}, options);
+	}
+	async list(name, options) {
+		options?.signal?.throwIfAborted();
+		this.#files.validateName(name);
+		return this.#files.list(this.#files.resolvePath(name, BROWSER_RUN_DIRECTORY), (id) => this.get(name, id, options), options);
+	}
+	async #requireDirectory(directory, options) {
+		if (!this.#directories.has(directory) || !await this.#files.check(directory, options)) throw new BrowserError(`Run directory was not opened or is missing: ${directory}`, "BROWSER_JOURNEY_PATH");
+		try {
+			options?.signal?.throwIfAborted();
+			const status = await lstat(directory);
+			options?.signal?.throwIfAborted();
+			if (!status.isDirectory()) throw new BrowserError(`Run directory is not a directory: ${directory}`, "BROWSER_JOURNEY_PATH");
+		} catch (error) {
+			options?.signal?.throwIfAborted();
+			throw this.#files.translateError(directory, error);
+		}
+	}
+};
+//#endregion
 //#region src/server/factories.ts
 /**
 * Creates a raw-CDP `BrowserInterface` façade with discovery, connection, and lifecycle
@@ -829,7 +1665,7 @@ var FileBrowserWriter = class {
 * const browser = createBrowser({ headless: true })
 * await browser.connect() // CDP endpoint discovery → connect, else launch
 * const page = await browser.create({ url: 'https://example.com' })
-* await page.click('#accept')
+* await (await page.elements.find({ css: '#accept' }))[0]?.click()
 * const shot = await page.screenshot({ path: './out.png' })
 * await browser.destroy()
 * ```
@@ -855,6 +1691,45 @@ function createCDPTransport(options) {
 function createBrowserWriter() {
 	return new FileBrowserWriter();
 }
+/**
+* Creates a journey store over an existing filesystem root.
+* @param options - Root and listing cap
+* @returns A durable journey store
+* @example
+* const store = createFileBrowserJourneyStore({ root: directory })
+*/
+function createFileBrowserJourneyStore(options) {
+	return new FileBrowserJourneyStore(options);
+}
+/**
+* Creates a run store over an existing filesystem root.
+* @param options - Root and listing cap
+* @returns A durable run and capture store
+* @example
+* const store = createFileBrowserRunStore({ root: directory })
+*/
+function createFileBrowserRunStore(options) {
+	return new FileBrowserRunStore(options);
+}
+/**
+* Creates the browse server, which serves the browser vocabulary and the journey tools over the
+* Model Context Protocol on stdio and launches Chromium on the first tool call.
+*
+* @param options - The root, the launch, the journeys' read-only switch, and the streams
+* @returns A {@link BrowserMCPServerInterface} that reads nothing until `start()`
+*
+* @example
+* ```ts
+* import { createBrowserMCPServer } from '@orkestrel/browser/server'
+*
+* const server = createBrowserMCPServer({ root: 'tmp/browsers', headless: true })
+* await server.start() // answers tools/list before Chromium starts
+* await server.destroy()
+* ```
+*/
+function createBrowserMCPServer(options) {
+	return new BrowserMCPServer(options);
+}
 //#endregion
 //#region src/server/Browser.ts
 /**
@@ -1057,7 +1932,8 @@ var Browser = class {
 			this.#status = "error";
 			this.#emitter.emit("error", error);
 			if (isBrowserConnectionError(error)) throw error;
-			throw new BrowserConnectionError(isError(error) ? error.message : String(error), { executable: this.#options.executable });
+			const message = isError(error) ? error.message : String(error);
+			throw new BrowserConnectionError(message, { executable: this.#options.executable });
 		}
 	}
 	async #detach() {
@@ -1275,7 +2151,7 @@ var Browser = class {
 		this.#profile = profile;
 		let process;
 		try {
-			process = launchBrowserProcess(executable, this.#cdpPort, this.#options.headless ?? true, profile.path, this.#options.args);
+			process = launchBrowserProcess(executable, this.#options.cdp?.port, this.#options.headless ?? true, profile.path, this.#options.args);
 		} catch (error) {
 			await this.#releaseProfile();
 			throw error;
@@ -1360,10 +2236,25 @@ var Browser = class {
 			executable,
 			args
 		};
+		const timeout = this.#timeout();
 		const controller = new AbortController();
-		const signal = AbortSignal.any([controller.signal, this.#signal()]);
-		const ready = waitForCDPReady(this.#cdpPort, this.#timeout(), this.#cdpHost, signal);
-		const exited = once(process, "exit", { signal }).then((values) => {
+		const deadline = AbortSignal.timeout(timeout);
+		const signal = AbortSignal.any([
+			controller.signal,
+			this.#signal(),
+			deadline
+		]);
+		const stderr = process.stderr;
+		if (stderr === null) throw new BrowserConnectionError("The browser process has no standard error to read", context);
+		const exit = once(process, "exit", { signal });
+		exit.catch(() => void 0);
+		const ready = readBrowserEndpoint(stderr, signal).catch(async (error) => {
+			if (signal.aborted) throw error;
+			const values = await exit;
+			if (values[0] === 0 && values[1] === null) throw error;
+			throw new BrowserConnectionError(this.#formatLaunchExit(isInteger(values[0]) ? values[0] : null, isString(values[1]) ? values[1] : null), context);
+		});
+		const exited = exit.then((values) => {
 			const code = isInteger(values[0]) ? values[0] : null;
 			const exitSignal = isString(values[1]) ? values[1] : null;
 			if (code === 0 && exitSignal === null) return ready;
@@ -1374,7 +2265,12 @@ var Browser = class {
 		} catch (error) {
 			if (isBrowserConnectionError(error)) throw error;
 			if (this.#signal().aborted) throw new BrowserConnectionError("Connection aborted", context);
-			throw new BrowserConnectionError(isError(error) ? error.message : String(error), context);
+			if (deadline.aborted) throw new BrowserConnectionError(`Browser did not report a CDP endpoint within ${timeout}ms`, {
+				...context,
+				timeout
+			});
+			const message = isError(error) ? error.message : String(error);
+			throw new BrowserConnectionError(message, context);
 		} finally {
 			controller.abort();
 			ready.catch(() => void 0);
@@ -1599,6 +2495,16 @@ var Browser = class {
 			});
 		}
 	}
+	/**
+	* Waits within a bound for the rest of a terminated process group, or the process a
+	* launcher handed the endpoint to, to disappear.
+	*
+	* @remarks
+	* This is the one interval loop in the server. Node raises an exit event for the direct
+	* child only, so no event source reports the remainder of a POSIX process group or a
+	* handed-off process, and the drain probes on `BROWSER_DRAIN_INTERVAL_MS` until the
+	* remainder is gone or `timeout` elapses.
+	*/
 	async #waitForRemainderWithin(process, timeout) {
 		const deadline = performance.now() + timeout;
 		let confirmed = false;
@@ -1608,7 +2514,7 @@ var Browser = class {
 			if (alive === true) confirmed = true;
 			const remaining = deadline - performance.now();
 			if (remaining <= 0) return confirmed ? false : void 0;
-			await new Promise((resolve) => setTimeout(resolve, Math.min(BROWSER_WAIT_POLL_INTERVAL_MS, remaining)));
+			await new Promise((resolve) => setTimeout(resolve, Math.min(100, remaining)));
 		}
 	}
 	async #waitForTerminationWithin(process, timeout, final = false) {
@@ -1642,6 +2548,6 @@ var Browser = class {
 	}
 };
 //#endregion
-export { BROWSER_CDP_LIST_PATH, BROWSER_CDP_PROTOCOL, BROWSER_CDP_VERSION_PATH, BROWSER_DEFAULT_CDP_PORT, BROWSER_DEFAULT_HOST, BROWSER_ENGINE_HINTS, BROWSER_ENV_PATH_KEYS, BROWSER_EXECUTABLE_NAMES, BROWSER_EXECUTABLE_PATHS, BROWSER_HEADLESS_ARG, BROWSER_KILL_GRACE_MS, BROWSER_LAUNCH_ARGS, BROWSER_PORT_PROBE_TIMEOUT_MS, BROWSER_PROCESS_EXIT_CAUSE, BROWSER_PROFILE_PREFIX, BROWSER_STORE_CACHE_DIRS, BROWSER_STORE_DEFAULT_DIRS, BROWSER_STORE_ENV_KEY, BROWSER_STORE_GLOBS, BROWSER_STORE_LINK_NAME, BROWSER_TRANSPORT_LOSS_CAUSE, BROWSER_TRANSPORT_LOSS_DEFER_MS, BROWSER_WINDOWS_ROOT_FALLBACKS, BROWSER_WINDOWS_SUFFIXES, Browser, BrowserConnectionError, BrowserDestroyedError, BrowserNotConnectedError, FileBrowserWriter, WebSocketCDPTransport, browserToEngine, buildInstallPaths, buildStoreBases, buildWindowsRoots, createBrowser, createBrowserProfile, createBrowserWriter, createCDPTransport, fetchCDPTargets, findEnvOverrides, findInstallPaths, findStorePaths, findSystemBrowser, findSystemBrowsers, isBrowserConnectionError, isBrowserDestroyedError, isBrowserNotConnectedError, launchBrowserProcess, normalizeExecutablePath, parseBrowserEngine, probePathNames, readFirstLine, removeBrowserProfile, waitForCDPReady };
+export { BROWSER_CDP_LIST_PATH, BROWSER_CDP_PROTOCOL, BROWSER_CDP_VERSION_PATH, BROWSER_DEFAULT_CDP_PORT, BROWSER_DEFAULT_HOST, BROWSER_DEVTOOLS_PATTERN, BROWSER_DRAIN_INTERVAL_MS, BROWSER_ENGINE_HINTS, BROWSER_ENV_PATH_KEYS, BROWSER_EXECUTABLE_NAMES, BROWSER_EXECUTABLE_PATHS, BROWSER_FILE_STORE_LIMIT, BROWSER_HEADLESS_ARG, BROWSER_JOURNEY_LOCK_ATTEMPTS, BROWSER_JOURNEY_LOCK_DIRECTORY, BROWSER_JOURNEY_REVISION_FILE, BROWSER_JOURNEY_SNAPSHOT_FILE, BROWSER_KILL_GRACE_MS, BROWSER_LAUNCH_ARGS, BROWSER_PORT_PROBE_TIMEOUT_MS, BROWSER_PROCESS_EXIT_CAUSE, BROWSER_PROFILE_PREFIX, BROWSER_RUN_DIRECTORY, BROWSER_RUN_FILE, BROWSER_STORE_CACHE_DIRS, BROWSER_STORE_DEFAULT_DIRS, BROWSER_STORE_ENV_KEY, BROWSER_STORE_GLOBS, BROWSER_STORE_LINK_NAME, BROWSER_TRANSPORT_LOSS_CAUSE, BROWSER_TRANSPORT_LOSS_DEFER_MS, BROWSER_WINDOWS_ROOT_FALLBACKS, BROWSER_WINDOWS_SUFFIXES, Browser, BrowserDestroyedError, BrowserMCPServer, BrowserNotConnectedError, FileBrowserJourneyStore, FileBrowserRunStore, FileBrowserWriter, WebSocketCDPTransport, browserToEngine, buildInstallPaths, buildStoreBases, buildWindowsRoots, createBrowser, createBrowserMCPServer, createBrowserProfile, createBrowserWriter, createCDPTransport, createFileBrowserJourneyStore, createFileBrowserRunStore, fetchCDPTargets, findEnvOverrides, findInstallPaths, findStorePaths, findSystemBrowser, findSystemBrowsers, formatBrowserLockEntry, isBrowserDestroyedError, isBrowserNotConnectedError, launchBrowserProcess, normalizeExecutablePath, parseBrowserEngine, parseBrowserLockEntry, probePathNames, readBrowserEndpoint, readFirstLine, removeBrowserProfile };
 
 //# sourceMappingURL=index.js.map