@orkestrel/browser 0.0.18 → 0.0.19

package/dist/src/server/index.cjs

@@ -6,13 +6,15 @@ let node_fs_promises = require("node:fs/promises");
 let node_os = require("node:os");
 let node_path = require("node:path");
 let node_child_process = require("node:child_process");
-let node_timers_promises = require("node:timers/promises");
 let node_crypto = require("node:crypto");
 let node_http = require("node:http");
 let node_https = require("node:https");
 let _orkestrel_emitter = require("@orkestrel/emitter");
 let _orkestrel_websocket = require("@orkestrel/websocket");
 let node_events = require("node:events");
+let _orkestrel_mcp = require("@orkestrel/mcp");
+let _orkestrel_mcp_server = require("@orkestrel/mcp/server");
+let _orkestrel_tool = require("@orkestrel/tool");
 //#region src/server/constants.ts
 /**
 * Sets the default CDP port probed for an existing browser and used for launches, `9222`.
@@ -58,9 +60,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;
 /**
@@ -177,19 +198,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 _src_core.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`.
 */
@@ -210,15 +235,6 @@ var BrowserDestroyedError = class extends _src_core.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 (0, _orkestrel_contract.isInstance)(value, BrowserConnectionError);
-}
-/**
 * Narrows an unknown value to a `BrowserNotConnectedError`.
 *
 * @param value - Value to check
@@ -239,6 +255,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.
 *
@@ -468,57 +508,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 (0, node_child_process.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 ((0, _orkestrel_contract.isRecord)(info) && (0, _orkestrel_contract.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 || !(0, _orkestrel_contract.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(_src_core.BROWSER_WAIT_POLL_INTERVAL_MS, Math.max(0, deadline - Date.now()));
-		if (delay > 0) await (0, node_timers_promises.setTimeout)(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 _src_core.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`
@@ -552,7 +604,7 @@ async function fetchCDPTargets(port, timeout, host = BROWSER_DEFAULT_HOST) {
 		const response = await fetch(url, { signal: controller.signal });
 		if (!response.ok) return {
 			success: false,
-			error: new BrowserConnectionError("CDP target list request was refused", {
+			error: new _src_core.BrowserConnectionError("CDP target list request was refused", {
 				url,
 				status: response.status
 			})
@@ -560,7 +612,7 @@ async function fetchCDPTargets(port, timeout, host = BROWSER_DEFAULT_HOST) {
 		const list = await response.json();
 		if (!(0, _orkestrel_contract.isArray)(list)) return {
 			success: false,
-			error: new BrowserConnectionError("CDP target list is not a JSON array", { url })
+			error: new _src_core.BrowserConnectionError("CDP target list is not a JSON array", { url })
 		};
 		const targets = [];
 		for (const entry of list) {
@@ -580,7 +632,7 @@ async function fetchCDPTargets(port, timeout, host = BROWSER_DEFAULT_HOST) {
 	} catch (error) {
 		return {
 			success: false,
-			error: new BrowserConnectionError("CDP target list is unreachable", {
+			error: new _src_core.BrowserConnectionError("CDP target list is unreachable", {
 				url,
 				error
 			})
@@ -648,7 +700,7 @@ var WebSocketCDPTransport = class {
 	}
 	async send(data) {
 		const socket = this.#socket;
-		if (socket === void 0 || socket.readyState !== _orkestrel_websocket.WEBSOCKET_READY_OPEN) throw new BrowserConnectionError("WebSocket CDP transport is not open", { url: this.#url });
+		if (socket === void 0 || socket.readyState !== _orkestrel_websocket.WEBSOCKET_READY_OPEN) throw new _src_core.BrowserConnectionError("WebSocket CDP transport is not open", { url: this.#url });
 		socket.send(data);
 	}
 	async close() {
@@ -656,12 +708,12 @@ var WebSocketCDPTransport = class {
 	}
 	async #start() {
 		const parsed = (0, _orkestrel_contract.attempt)(() => new URL(this.#url));
-		if (!parsed.success) throw new BrowserConnectionError(`WebSocket CDP URL is invalid: ${this.#url}`, {
+		if (!parsed.success) throw new _src_core.BrowserConnectionError(`WebSocket CDP URL is invalid: ${this.#url}`, {
 			url: this.#url,
 			error: parsed.error
 		});
 		const url = parsed.value;
-		if (url.protocol !== "ws:" && url.protocol !== "wss:") throw new BrowserConnectionError(`WebSocket CDP connection requires a ws: or wss: URL: ${this.#url}`, { url: this.#url });
+		if (url.protocol !== "ws:" && url.protocol !== "wss:") throw new _src_core.BrowserConnectionError(`WebSocket CDP connection requires a ws: or wss: URL: ${this.#url}`, { url: this.#url });
 		const key = (0, node_crypto.randomBytes)(16).toString("base64");
 		const deferred = Promise.withResolvers();
 		const options = {
@@ -693,7 +745,7 @@ var WebSocketCDPTransport = class {
 	async #close() {
 		const request = this.#request;
 		if (request !== void 0) {
-			this.#rejectRequest(request, new BrowserConnectionError(`WebSocket CDP connection to ${this.#url} was closed before it finished connecting`, { url: this.#url }));
+			this.#rejectRequest(request, new _src_core.BrowserConnectionError(`WebSocket CDP connection to ${this.#url} was closed before it finished connecting`, { url: this.#url }));
 			request.destroy();
 		}
 		await this.#starting.pending?.catch(() => void 0);
@@ -722,7 +774,7 @@ var WebSocketCDPTransport = class {
 		const accept = response.headers["sec-websocket-accept"];
 		if (!(0, _orkestrel_contract.isString)(accept) || accept !== (0, _orkestrel_websocket.computeWebSocketAccept)(key)) {
 			socket.destroy();
-			this.#rejectRequest(request, new BrowserConnectionError(`WebSocket CDP connection to ${this.#url} failed: Sec-WebSocket-Accept mismatch`, { url: this.#url }));
+			this.#rejectRequest(request, new _src_core.BrowserConnectionError(`WebSocket CDP connection to ${this.#url} failed: Sec-WebSocket-Accept mismatch`, { url: this.#url }));
 			return;
 		}
 		try {
@@ -738,13 +790,13 @@ var WebSocketCDPTransport = class {
 	#decline(request, response) {
 		response.resume();
 		const reason = response.statusCode === void 0 ? "upgrade was declined without a status code" : `upgrade declined with status ${response.statusCode}`;
-		this.#rejectRequest(request, new BrowserConnectionError(`WebSocket CDP connection to ${this.#url} failed: ${reason}`, { url: this.#url }));
+		this.#rejectRequest(request, new _src_core.BrowserConnectionError(`WebSocket CDP connection to ${this.#url} failed: ${reason}`, { url: this.#url }));
 	}
 	#fail(request, error) {
-		this.#rejectRequest(request, new BrowserConnectionError(`WebSocket CDP connection to ${this.#url} failed: ${error.message}`, { url: this.#url }));
+		this.#rejectRequest(request, new _src_core.BrowserConnectionError(`WebSocket CDP connection to ${this.#url} failed: ${error.message}`, { url: this.#url }));
 	}
 	#expire(request) {
-		this.#rejectRequest(request, new BrowserConnectionError(`WebSocket CDP connection to ${this.#url} timed out after ${this.#timeout}ms`, {
+		this.#rejectRequest(request, new _src_core.BrowserConnectionError(`WebSocket CDP connection to ${this.#url} timed out after ${this.#timeout}ms`, {
 			url: this.#url,
 			timeout: this.#timeout
 		}));
@@ -815,6 +867,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 = (0, node_path.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 = (0, _orkestrel_tool.createToolManager)();
+		const names = [..._src_core.BROWSER_TOOL_NAMES, ..._src_core.BROWSER_JOURNEY_TOOL_NAMES];
+		this.#vocabulary = new Set(names);
+		for (const name of names) this.#tools.add((0, _orkestrel_tool.createTool)({
+			..._src_core.BROWSER_TOOL_COPY[name],
+			execute: this.#forward.bind(this, name)
+		}));
+		const server = (0, _orkestrel_mcp.createMCPServer)({
+			identity: {
+				name: "browse",
+				version
+			},
+			tools: this.#tools,
+			execution: this.#execute.bind(this)
+		});
+		this.#transport = (0, _orkestrel_mcp_server.createStdioServer)((0, _orkestrel_mcp.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 (0, node_fs_promises.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 _src_core.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 (0, node_fs_promises.mkdir)(this.#root, { recursive: true });
+		const profiles = (0, node_path.join)(this.#root, ".profiles");
+		await (0, node_fs_promises.mkdir)(profiles, { recursive: true });
+		const profile = (0, node_path.join)(profiles, (0, node_crypto.randomUUID)());
+		await (0, node_fs_promises.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 = (0, _src_core.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 (0, node_fs_promises.rm)(profile, {
+				recursive: true,
+				force: true,
+				maxRetries: 5
+			});
+			throw error;
+		}
+	}
+	#mirror(tool) {
+		if (this.#vocabulary.has(tool.name)) return;
+		this.#tools.add((0, _orkestrel_tool.createTool)({
+			...(0, _orkestrel_tool.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 _src_core.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 _src_core.BrowserError("The listing cap must be a positive integer", "BROWSER_JOURNEY_ARGUMENT");
+		try {
+			this.#root = (0, node_fs.realpathSync)(options.root);
+		} catch (error) {
+			if (error instanceof Error && "code" in error && error.code === "ENOENT") throw new _src_core.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 (!_src_core.BROWSER_JOURNEY_NAME_PATTERN.test(name)) throw new _src_core.BrowserError(`Refused journey name: ${name}`, "BROWSER_JOURNEY_PATH");
+	}
+	/** Checks a run id before filesystem access. @param id - Producer id */
+	validateId(id) {
+		if (!_src_core.BROWSER_RUN_ID_PATTERN.test(id)) throw new _src_core.BrowserError(`Refused run id: ${id}`, "BROWSER_JOURNEY_PATH");
+	}
+	/** Resolves a confined target. @param parts - Relative components @returns Absolute target */
+	resolvePath(...parts) {
+		const path = (0, node_path.resolve)(this.#root, ...parts);
+		if (path !== this.#root && !path.startsWith(this.#root.endsWith(node_path.sep) ? this.#root : this.#root + node_path.sep)) throw new _src_core.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 = (0, node_path.relative)(this.#root, path).split(node_path.sep).filter(Boolean);
+		for (let index = 0; index <= parts.length; index += 1) {
+			options?.signal?.throwIfAborted();
+			try {
+				const status = await (0, node_fs_promises.lstat)(current);
+				options?.signal?.throwIfAborted();
+				if (status.isSymbolicLink()) throw new _src_core.BrowserError(`Refused symbolic link: ${current}`, "BROWSER_JOURNEY_PATH");
+				if (index < parts.length && !status.isDirectory()) throw new _src_core.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 _src_core.BrowserError(`Missing root: ${path}`, "BROWSER_JOURNEY_PATH");
+		await this.createDirectory((0, node_path.dirname)(path), options);
+		options?.signal?.throwIfAborted();
+		try {
+			await (0, node_fs_promises.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 (0, node_fs_promises.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((0, node_path.dirname)(path), `.${(0, node_crypto.randomUUID)()}.tmp`);
+		let owned = false;
+		try {
+			await this.check(path, options);
+			await this.check(temporary, options);
+			options?.signal?.throwIfAborted();
+			const file = await (0, node_fs_promises.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 (0, node_fs_promises.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 (0, node_fs_promises.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((0, node_path.dirname)(path), options);
+		const name = formatBrowserLockEntry(process.pid, (0, node_crypto.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 (0, node_fs_promises.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 (0, node_fs_promises.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 _src_core.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;
+		(0, _src_core.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 (0, node_fs_promises.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 _src_core.BrowserError ? error.context?.["reason"] : void 0;
+				faults.push({
+					name,
+					reason: typeof reason === "string" ? reason : error instanceof _src_core.BrowserError && error.code === "BROWSER_JOURNEY_PATH" ? "The entry path is refused" : error instanceof _src_core.BrowserError && error.code === "BROWSER_JOURNEY_ACCESS" ? "Permission denied" : error instanceof _src_core.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 (0, node_fs_promises.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 _src_core.BrowserError(`${path}: ${error instanceof Error ? error.message : String(error)}`, code === "EACCES" || code === "EPERM" ? "BROWSER_JOURNEY_ACCESS" : error instanceof _src_core.BrowserError && code !== "BROWSER_JOURNEY_INVALID" ? error.code : "BROWSER_JOURNEY_FILE", { path });
+	}
+	async #readLock(path, options) {
+		await this.check(path, options);
+		try {
+			const entries = await (0, node_fs_promises.readdir)(path, { withFileTypes: true });
+			for (const entry of entries) {
+				await this.check(this.resolvePath(path, entry.name), options);
+				if (!entry.isFile()) throw new _src_core.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 _src_core.BrowserError(`Journey is locked: ${path}`, "BROWSER_JOURNEY_LOCKED");
+			}
+			throw this.translateError(path, error);
+		}
+	}
+	async #unlinkLock(path) {
+		await this.check(path);
+		try {
+			await (0, node_fs_promises.unlink)(path);
+			return true;
+		} catch (error) {
+			if (error instanceof Error && "code" in error && (error.code === "ENOENT" || error.code === "ENOTEMPTY")) return false;
+			throw new _src_core.BrowserError(`Cannot remove lock entry: ${path}`, "BROWSER_JOURNEY_ACCESS", { path });
+		}
+	}
+	async #removeLock(path) {
+		await this.check(path);
+		try {
+			await (0, node_fs_promises.rmdir)(path);
+		} catch (error) {
+			if (error instanceof Error && "code" in error && (error.code === "ENOENT" || error.code === "ENOTEMPTY")) return;
+			throw new _src_core.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 = (0, _orkestrel_contract.parseJSON)(source);
+			if (!(0, _orkestrel_contract.isRecord)(value) || typeof value["revision"] !== "number" || !Number.isSafeInteger(value["revision"]) || value["revision"] < 1) throw new _src_core.BrowserError("Malformed journey revision", "BROWSER_JOURNEY_FILE");
+			if (!(0, _orkestrel_contract.isRecord)(value["journey"]) || !("format" in value["journey"])) throw new _src_core.BrowserError("Missing journey format", "BROWSER_JOURNEY_FILE");
+			(0, _src_core.validateBrowserJourney)(value["journey"]);
+			if (value["journey"].name !== name) throw new _src_core.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 _src_core.BrowserError(translated.message, translated.code, {
+				...translated.context,
+				reason: (0, _src_core.normalizeBrowserJourneyReason)(error)
+			});
+		}
+	}
+	async set(journey, expected, options) {
+		options?.signal?.throwIfAborted();
+		this.#files.validateName(journey.name);
+		(0, _src_core.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 _src_core.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 _src_core.BrowserError(`Malformed revision: ${counter}`, "BROWSER_JOURNEY_FILE");
+			const revision = Math.max(previous, current?.revision ?? 0) + 1;
+			if (!Number.isSafeInteger(revision)) throw new _src_core.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 _src_core.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 (!_src_core.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), _src_core.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 = (0, _orkestrel_contract.parseJSON)(source);
+			if (!(0, _orkestrel_contract.isRecord)(value) || !("format" in value)) throw new _src_core.BrowserError("Missing run format", "BROWSER_JOURNEY_FILE");
+			if (value["format"] === _src_core.BROWSER_JOURNEY_FORMAT_VERSION && (!(0, _orkestrel_contract.isRecord)(value["journey"]) || !("format" in value["journey"]))) throw new _src_core.BrowserError("Missing run journey format", "BROWSER_JOURNEY_FILE");
+			(0, _src_core.validateBrowserRun)(value);
+			if (value.id !== id || value.journey.name !== name) throw new _src_core.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);
+		(0, _src_core.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 _src_core.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 (0, node_fs_promises.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 (0, node_fs_promises.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 _src_core.BrowserError(`Run directory was not opened or is missing: ${directory}`, "BROWSER_JOURNEY_PATH");
+		try {
+			options?.signal?.throwIfAborted();
+			const status = await (0, node_fs_promises.lstat)(directory);
+			options?.signal?.throwIfAborted();
+			if (!status.isDirectory()) throw new _src_core.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
@@ -830,7 +1666,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()
 * ```
@@ -856,6 +1692,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
 /**
@@ -975,7 +1850,7 @@ var Browser = class {
 		}
 		if (options?.origins !== void 0) params["originsWithUniversalNetworkAccess"] = [...options.origins];
 		const result = await client.send("Target.createBrowserContext", params);
-		if (!(0, _orkestrel_contract.isRecord)(result) || !(0, _orkestrel_contract.isString)(result["browserContextId"])) throw new BrowserConnectionError("Failed to create isolated browser context");
+		if (!(0, _orkestrel_contract.isRecord)(result) || !(0, _orkestrel_contract.isString)(result["browserContextId"])) throw new _src_core.BrowserConnectionError("Failed to create isolated browser context");
 		const id = result["browserContextId"];
 		const context = new _src_core.BrowserContext(client, id, options?.emulation?.viewport ?? this.#options.viewport, createBrowserWriter(), options?.emulation, options?.downloads, options);
 		try {
@@ -1057,8 +1932,9 @@ var Browser = class {
 			if (this.#destroyed) throw new BrowserDestroyedError();
 			this.#status = "error";
 			this.#emitter.emit("error", error);
-			if (isBrowserConnectionError(error)) throw error;
-			throw new BrowserConnectionError((0, _orkestrel_contract.isError)(error) ? error.message : String(error), { executable: this.#options.executable });
+			if ((0, _src_core.isBrowserConnectionError)(error)) throw error;
+			const message = (0, _orkestrel_contract.isError)(error) ? error.message : String(error);
+			throw new _src_core.BrowserConnectionError(message, { executable: this.#options.executable });
 		}
 	}
 	async #detach() {
@@ -1079,7 +1955,7 @@ var Browser = class {
 		this.#emitter.emit("idle");
 	}
 	#assertNotAborted() {
-		if (this.#signal().aborted) throw new BrowserConnectionError("Connection aborted");
+		if (this.#signal().aborted) throw new _src_core.BrowserConnectionError("Connection aborted");
 	}
 	#signal() {
 		const external = this.#options.signal;
@@ -1087,10 +1963,10 @@ var Browser = class {
 	}
 	async #raceAbort(promise) {
 		const signal = this.#signal();
-		if (signal.aborted) throw new BrowserConnectionError("Connection aborted");
+		if (signal.aborted) throw new _src_core.BrowserConnectionError("Connection aborted");
 		const aborted = Promise.withResolvers();
 		const listener = (0, node_events.addAbortListener)(signal, () => {
-			aborted.reject(new BrowserConnectionError("Connection aborted"));
+			aborted.reject(new _src_core.BrowserConnectionError("Connection aborted"));
 		});
 		try {
 			return await Promise.race([promise, aborted.promise]);
@@ -1118,7 +1994,7 @@ var Browser = class {
 		this.#owned = void 0;
 		this.#endpoint = void 0;
 		if (connected) this.#status = "disconnected";
-		this.#emitter.emit("error", new BrowserConnectionError("The browser process exited unexpectedly", { cause: BROWSER_PROCESS_EXIT_CAUSE }));
+		this.#emitter.emit("error", new _src_core.BrowserConnectionError("The browser process exited unexpectedly", { cause: BROWSER_PROCESS_EXIT_CAUSE }));
 		if (connected) {
 			this.#emitter.emit("disconnect");
 			this.#emitter.emit("idle");
@@ -1156,7 +2032,7 @@ var Browser = class {
 		}
 		this.#destroyContextList(contexts);
 		this.#closeClient(client);
-		this.#emitter.emit("error", new BrowserConnectionError("The CDP transport connection was lost", { cause: BROWSER_TRANSPORT_LOSS_CAUSE }));
+		this.#emitter.emit("error", new _src_core.BrowserConnectionError("The CDP transport connection was lost", { cause: BROWSER_TRANSPORT_LOSS_CAUSE }));
 		this.#emitter.emit("disconnect");
 		this.#emitter.emit("idle");
 	}
@@ -1209,7 +2085,7 @@ var Browser = class {
 		};
 	}
 	async #assertPortFree() {
-		if (await this.#probePort()) throw new BrowserConnectionError(`Port ${this.#cdpPort} on ${this.#cdpHost} is already occupied by another CDP endpoint`, {
+		if (await this.#probePort()) throw new _src_core.BrowserConnectionError(`Port ${this.#cdpPort} on ${this.#cdpHost} is already occupied by another CDP endpoint`, {
 			port: this.#cdpPort,
 			host: this.#cdpHost
 		});
@@ -1256,7 +2132,7 @@ var Browser = class {
 		}
 	}
 	async #launch() {
-		if (this.#process !== void 0) throw new BrowserConnectionError("A browser process is already active on this instance");
+		if (this.#process !== void 0) throw new _src_core.BrowserConnectionError("A browser process is already active on this instance");
 		const requestedEngine = this.#options.engine ?? this.#options.browsers?.engine;
 		let executable = this.#options.executable;
 		let resolvedEngine;
@@ -1269,14 +2145,14 @@ var Browser = class {
 			executable = found?.executable;
 			resolvedEngine = found?.engine;
 		}
-		if (executable === void 0) throw new BrowserConnectionError("No Chromium browser found. Install Chrome, Edge, or Chromium.", requestedEngine === void 0 ? void 0 : { engine: requestedEngine });
+		if (executable === void 0) throw new _src_core.BrowserConnectionError("No Chromium browser found. Install Chrome, Edge, or Chromium.", requestedEngine === void 0 ? void 0 : { engine: requestedEngine });
 		this.#engine = resolvedEngine ?? "chromium";
 		await this.#releaseProfile();
 		const profile = await createBrowserProfile(this.#options.profile);
 		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;
@@ -1349,7 +2225,7 @@ var Browser = class {
 		}
 		if (pid === void 0) {
 			await this.#closeRemote(client);
-			throw new BrowserConnectionError("The browser launcher exited without naming the process serving its CDP endpoint", {
+			throw new _src_core.BrowserConnectionError("The browser launcher exited without naming the process serving its CDP endpoint", {
 				executable: this.#options.executable,
 				pid: process.pid
 			});
@@ -1361,21 +2237,41 @@ 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 = (0, node_events.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 _src_core.BrowserConnectionError("The browser process has no standard error to read", context);
+		const exit = (0, node_events.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 _src_core.BrowserConnectionError(this.#formatLaunchExit((0, _orkestrel_contract.isInteger)(values[0]) ? values[0] : null, (0, _orkestrel_contract.isString)(values[1]) ? values[1] : null), context);
+		});
+		const exited = exit.then((values) => {
 			const code = (0, _orkestrel_contract.isInteger)(values[0]) ? values[0] : null;
 			const exitSignal = (0, _orkestrel_contract.isString)(values[1]) ? values[1] : null;
 			if (code === 0 && exitSignal === null) return ready;
-			throw new BrowserConnectionError(this.#formatLaunchExit(code, exitSignal), context);
+			throw new _src_core.BrowserConnectionError(this.#formatLaunchExit(code, exitSignal), context);
 		});
 		try {
 			return await Promise.race([ready, exited]);
 		} catch (error) {
-			if (isBrowserConnectionError(error)) throw error;
-			if (this.#signal().aborted) throw new BrowserConnectionError("Connection aborted", context);
-			throw new BrowserConnectionError((0, _orkestrel_contract.isError)(error) ? error.message : String(error), context);
+			if ((0, _src_core.isBrowserConnectionError)(error)) throw error;
+			if (this.#signal().aborted) throw new _src_core.BrowserConnectionError("Connection aborted", context);
+			if (deadline.aborted) throw new _src_core.BrowserConnectionError(`Browser did not report a CDP endpoint within ${timeout}ms`, {
+				...context,
+				timeout
+			});
+			const message = (0, _orkestrel_contract.isError)(error) ? error.message : String(error);
+			throw new _src_core.BrowserConnectionError(message, context);
 		} finally {
 			controller.abort();
 			ready.catch(() => void 0);
@@ -1593,13 +2489,23 @@ var Browser = class {
 			const code = (0, _orkestrel_contract.isError)(error) && "code" in error && (0, _orkestrel_contract.isString)(error.code) ? error.code : void 0;
 			if (code === "ESRCH") return false;
 			if (signal === 0) return code === "EPERM" ? true : void 0;
-			throw new BrowserConnectionError("Failed to signal the browser process", {
+			throw new _src_core.BrowserConnectionError("Failed to signal the browser process", {
 				pid: serving ?? pid,
 				signal,
 				cause: error
 			});
 		}
 	}
+	/**
+	* 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;
@@ -1609,7 +2515,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(_src_core.BROWSER_WAIT_POLL_INTERVAL_MS, remaining)));
+			await new Promise((resolve) => setTimeout(resolve, Math.min(100, remaining)));
 		}
 	}
 	async #waitForTerminationWithin(process, timeout, final = false) {
@@ -1624,7 +2530,7 @@ var Browser = class {
 		if (await this.#waitForTerminationWithin(process, 3e3)) return;
 		if (this.#signalProcess(process, "SIGKILL") === false) return;
 		if (await this.#waitForTerminationWithin(process, 3e3, true)) return;
-		throw new BrowserConnectionError("Browser process did not exit after SIGKILL", { pid: this.#servingPid ?? process.pid });
+		throw new _src_core.BrowserConnectionError("Browser process did not exit after SIGKILL", { pid: this.#servingPid ?? process.pid });
 	}
 	#finish() {
 		this.#unbindTransport();
@@ -1648,16 +2554,25 @@ exports.BROWSER_CDP_PROTOCOL = BROWSER_CDP_PROTOCOL;
 exports.BROWSER_CDP_VERSION_PATH = BROWSER_CDP_VERSION_PATH;
 exports.BROWSER_DEFAULT_CDP_PORT = BROWSER_DEFAULT_CDP_PORT;
 exports.BROWSER_DEFAULT_HOST = BROWSER_DEFAULT_HOST;
+exports.BROWSER_DEVTOOLS_PATTERN = BROWSER_DEVTOOLS_PATTERN;
+exports.BROWSER_DRAIN_INTERVAL_MS = BROWSER_DRAIN_INTERVAL_MS;
 exports.BROWSER_ENGINE_HINTS = BROWSER_ENGINE_HINTS;
 exports.BROWSER_ENV_PATH_KEYS = BROWSER_ENV_PATH_KEYS;
 exports.BROWSER_EXECUTABLE_NAMES = BROWSER_EXECUTABLE_NAMES;
 exports.BROWSER_EXECUTABLE_PATHS = BROWSER_EXECUTABLE_PATHS;
+exports.BROWSER_FILE_STORE_LIMIT = BROWSER_FILE_STORE_LIMIT;
 exports.BROWSER_HEADLESS_ARG = BROWSER_HEADLESS_ARG;
+exports.BROWSER_JOURNEY_LOCK_ATTEMPTS = BROWSER_JOURNEY_LOCK_ATTEMPTS;
+exports.BROWSER_JOURNEY_LOCK_DIRECTORY = BROWSER_JOURNEY_LOCK_DIRECTORY;
+exports.BROWSER_JOURNEY_REVISION_FILE = BROWSER_JOURNEY_REVISION_FILE;
+exports.BROWSER_JOURNEY_SNAPSHOT_FILE = BROWSER_JOURNEY_SNAPSHOT_FILE;
 exports.BROWSER_KILL_GRACE_MS = BROWSER_KILL_GRACE_MS;
 exports.BROWSER_LAUNCH_ARGS = BROWSER_LAUNCH_ARGS;
 exports.BROWSER_PORT_PROBE_TIMEOUT_MS = BROWSER_PORT_PROBE_TIMEOUT_MS;
 exports.BROWSER_PROCESS_EXIT_CAUSE = BROWSER_PROCESS_EXIT_CAUSE;
 exports.BROWSER_PROFILE_PREFIX = BROWSER_PROFILE_PREFIX;
+exports.BROWSER_RUN_DIRECTORY = BROWSER_RUN_DIRECTORY;
+exports.BROWSER_RUN_FILE = BROWSER_RUN_FILE;
 exports.BROWSER_STORE_CACHE_DIRS = BROWSER_STORE_CACHE_DIRS;
 exports.BROWSER_STORE_DEFAULT_DIRS = BROWSER_STORE_DEFAULT_DIRS;
 exports.BROWSER_STORE_ENV_KEY = BROWSER_STORE_ENV_KEY;
@@ -1668,9 +2583,11 @@ exports.BROWSER_TRANSPORT_LOSS_DEFER_MS = BROWSER_TRANSPORT_LOSS_DEFER_MS;
 exports.BROWSER_WINDOWS_ROOT_FALLBACKS = BROWSER_WINDOWS_ROOT_FALLBACKS;
 exports.BROWSER_WINDOWS_SUFFIXES = BROWSER_WINDOWS_SUFFIXES;
 exports.Browser = Browser;
-exports.BrowserConnectionError = BrowserConnectionError;
 exports.BrowserDestroyedError = BrowserDestroyedError;
+exports.BrowserMCPServer = BrowserMCPServer;
 exports.BrowserNotConnectedError = BrowserNotConnectedError;
+exports.FileBrowserJourneyStore = FileBrowserJourneyStore;
+exports.FileBrowserRunStore = FileBrowserRunStore;
 exports.FileBrowserWriter = FileBrowserWriter;
 exports.WebSocketCDPTransport = WebSocketCDPTransport;
 exports.browserToEngine = browserToEngine;
@@ -1678,24 +2595,28 @@ exports.buildInstallPaths = buildInstallPaths;
 exports.buildStoreBases = buildStoreBases;
 exports.buildWindowsRoots = buildWindowsRoots;
 exports.createBrowser = createBrowser;
+exports.createBrowserMCPServer = createBrowserMCPServer;
 exports.createBrowserProfile = createBrowserProfile;
 exports.createBrowserWriter = createBrowserWriter;
 exports.createCDPTransport = createCDPTransport;
+exports.createFileBrowserJourneyStore = createFileBrowserJourneyStore;
+exports.createFileBrowserRunStore = createFileBrowserRunStore;
 exports.fetchCDPTargets = fetchCDPTargets;
 exports.findEnvOverrides = findEnvOverrides;
 exports.findInstallPaths = findInstallPaths;
 exports.findStorePaths = findStorePaths;
 exports.findSystemBrowser = findSystemBrowser;
 exports.findSystemBrowsers = findSystemBrowsers;
-exports.isBrowserConnectionError = isBrowserConnectionError;
+exports.formatBrowserLockEntry = formatBrowserLockEntry;
 exports.isBrowserDestroyedError = isBrowserDestroyedError;
 exports.isBrowserNotConnectedError = isBrowserNotConnectedError;
 exports.launchBrowserProcess = launchBrowserProcess;
 exports.normalizeExecutablePath = normalizeExecutablePath;
 exports.parseBrowserEngine = parseBrowserEngine;
+exports.parseBrowserLockEntry = parseBrowserLockEntry;
 exports.probePathNames = probePathNames;
+exports.readBrowserEndpoint = readBrowserEndpoint;
 exports.readFirstLine = readFirstLine;
 exports.removeBrowserProfile = removeBrowserProfile;
-exports.waitForCDPReady = waitForCDPReady;
 
 //# sourceMappingURL=index.cjs.map