@orkestrel/browser 0.0.21 → 0.0.23

package/dist/src/server/index.cjs

@@ -13,6 +13,7 @@ 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_pool = require("@orkestrel/pool");
 let _orkestrel_mcp_server = require("@orkestrel/mcp/server");
 let _orkestrel_tool = require("@orkestrel/tool");
 //#region src/server/constants.ts
@@ -212,6 +213,30 @@ var BROWSER_RUN_FILE = "run.json";
 var BROWSER_RUN_DIRECTORY = "runs";
 /** Bounds a file-store listing page by default. */
 var BROWSER_FILE_STORE_LIMIT = 100;
+/** Names the refusal when no browser can serve a call. */
+var BROWSER_SERVER_UNAVAILABLE = "BROWSER_SERVER_UNAVAILABLE";
+/** Names a failed attempt to warm a browser. */
+var BROWSER_SERVER_LAUNCH = "BROWSER_SERVER_LAUNCH";
+/** Sets the default number of warm browsers to 1. */
+var BROWSER_SERVER_POOL_SIZE = 1;
+/** Limits the number of warm browsers to 3. */
+var BROWSER_SERVER_POOL_LIMIT = 3;
+/** Permits one failed refill before the next failure spends the bound. */
+var BROWSER_SERVER_RESTARTS = 1;
+/** Names the browser process record in each profile. */
+var BROWSER_SERVER_RECORD = "browse.json";
+/** Names the diagnostic when the warm floor spends its restart bound. */
+var BROWSER_SERVER_EXHAUSTED = "BROWSER_SERVER_EXHAUSTED";
+/** Names a failed browser server teardown. */
+var BROWSER_SERVER_TEARDOWN = "BROWSER_SERVER_TEARDOWN";
+/** Names a failed profile sweep. */
+var BROWSER_SERVER_SWEEP = "BROWSER_SERVER_SWEEP";
+/** Names a refused browser server option. */
+var BROWSER_SERVER_OPTIONS = "BROWSER_SERVER_OPTIONS";
+/** Names the notice that a browser and its session state were lost. */
+var BROWSER_SERVER_CRASH = "BROWSER_SERVER_CRASH";
+/** Names an interrupted call whose outcome is unknown. */
+var BROWSER_SERVER_UNRESOLVED = "BROWSER_SERVER_UNRESOLVED";
 //#endregion
 //#region src/server/errors.ts
 /**
@@ -255,6 +280,58 @@ function isBrowserDestroyedError(value) {
 //#endregion
 //#region src/server/helpers.ts
 /**
+* Probes whether a process has not been confirmed absent.
+* @param pid - Process identifier to probe with signal zero
+* @returns True if the host has not confirmed absence with ESRCH; false otherwise
+* @example
+* probeProcess(process.pid) // true
+*/
+function probeProcess(pid) {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (error) {
+		return !((0, _orkestrel_contract.isError)(error) && "code" in error && error.code === "ESRCH");
+	}
+}
+/**
+* Parses a profile record naming a positive process identifier and a loopback DevTools endpoint.
+* @param text - JSON record read from a browse profile
+* @returns The record, or undefined when its shape or endpoint is refused
+* @example
+* parseBrowserProfileRecord('{"pid":123,"endpoint":"ws://127.0.0.1:9222/devtools/browser/session"}')
+*/
+function parseBrowserProfileRecord(text) {
+	const record = (0, _orkestrel_contract.parseJSON)(text);
+	if (!(0, _orkestrel_contract.isRecord)(record)) return void 0;
+	const pid = record["pid"];
+	const endpoint = record["endpoint"];
+	if (!(0, _orkestrel_contract.isNumber)(pid) || !Number.isSafeInteger(pid) || pid <= 0 || !(0, _orkestrel_contract.isString)(endpoint)) return void 0;
+	const match = /^ws:\/\/127\.0\.0\.1:([1-9]\d*)\/devtools\/browser\/[^/?#\s\\]+$/.exec(endpoint);
+	if (match === null || Number(match[1]) > 65535) return void 0;
+	return {
+		pid,
+		endpoint
+	};
+}
+/**
+* Describes a browser loss with its code, cause, and the session state it invalidates.
+* @param code - Browser server diagnostic code
+* @param cause - The loss or refusal, including its process context when present
+* @param url - The lost page's last URL, when known
+* @returns The coded diagnostic and any operation-lifecycle guidance
+* @example
+* describeBrowserServerLoss('BROWSER_SERVER_UNAVAILABLE', new Error('Browser exited'))
+*/
+function describeBrowserServerLoss(code, cause, url) {
+	const pid = (0, _src_core.isBrowserError)(cause) ? cause.context?.["pid"] : void 0;
+	const message = `${code}: ${(cause === void 0 ? "Browser session lost" : (0, _orkestrel_contract.isError)(cause) ? cause.message : String(cause)).replace(/\.+$/u, "")}${(0, _orkestrel_contract.isNumber)(pid) ? ` (pid ${pid})` : ""}.`;
+	if (code !== "BROWSER_SERVER_CRASH" && code !== "BROWSER_SERVER_UNRESOLVED") return message;
+	const lost = `Lost the page${url === void 0 ? "" : ` at ${url}`}, its tabs, every element reference, the retained reading, dialogs, holds, an unsaved recording, the active replay, and the isolated context's cookies.`;
+	const next = `The next call acquires a browser that starts at about:blank, or answers ${BROWSER_SERVER_UNAVAILABLE} when none can serve.`;
+	return code === "BROWSER_SERVER_UNRESOLVED" ? `${message} The outcome is unknown. ${lost} Browse did not repeat the call. ${next}` : `${message} ${lost}`;
+}
+/**
 * 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
@@ -868,33 +945,37 @@ var FileBrowserWriter = class {
 };
 //#endregion
 //#region package.json
-var version = "0.0.21";
+var version = "0.0.23";
 //#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.
+* the Model Context Protocol on stdio, and warms Chromium at server start.
 *
 * @remarks
-* The server's own manager holds one dispatcher per name of the vocabulary — `look`, `read`,
+* The server's own manager holds one dispatcher per name of the vocabulary — `look`, `read`, `plain`,
 * `click`, `type`, `press`, `navigate`, `wait`, `dialog`, `tabs`, `switch`, `record`, `save`,
-* `journeys`, `edit`, and `replay` — each carrying the description, parameters, and annotations
+* `journeys`, `edit`, `replay`, and `forget` — 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
+* client is notified. Startup warms the pool and leases one validated browser. The legacy
+* handshake and every tool call await that setup; concurrent callers share a replacement lease.
+* A launch creates `ROOT/.profiles/PID-UUID/` 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.
+* A disconnect or current-page crash retires its slot. A failed call receives a liveness ping;
+* loss makes its outcome unresolved, while a known success remains successful. Pending losses
+* prefix the next outcome on a successor, or a refusal, and calls are never repeated.
 *
 * `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.
+* `SIGTERM`. `destroy()` stops reading requests and removes every dispatcher, then destroys every
+* slot through the pool — its toolset, which aborts the active replay, then its browser, then its
+* profile — and rechecks the profile folders this server made or kept.
 *
 * 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
@@ -924,11 +1005,21 @@ var BrowserMCPServer = class {
 	#added;
 	#removed;
 	#cleared;
-	#mirrored;
-	#session;
-	#browser;
-	#profile;
-	#started = false;
+	#pool;
+	#log;
+	#folders = /* @__PURE__ */ new Set();
+	#faults = /* @__PURE__ */ new Set();
+	#losses = /* @__PURE__ */ new WeakMap();
+	#watches = /* @__PURE__ */ new Map();
+	#notice = /* @__PURE__ */ new Set();
+	#reference;
+	#references = 0;
+	#failure;
+	#stranded;
+	#lease;
+	#granting;
+	#starting;
+	#sweeping;
 	#closing;
 	/**
 	* Registers the dispatchers and binds the protocol to the stdio streams without reading them.
@@ -936,6 +1027,19 @@ var BrowserMCPServer = class {
 	* @param options - The root, the launch, the journeys' read-only switch, and the streams
 	*/
 	constructor(options) {
+		const size = options?.pool?.size ?? 1;
+		if (!(0, _orkestrel_contract.isInteger)(size) || size < 1 || size > 3) throw new _src_core.BrowserError(`pool.size must be an integer from 1 through 3`, BROWSER_SERVER_OPTIONS);
+		this.#log = options?.log ?? process.stderr;
+		this.#reference = this.#issue.bind(this);
+		this.#pool = (0, _orkestrel_pool.createPool)({
+			create: this.#warm.bind(this),
+			destroy: (slot) => this.#destroySlot(slot.profile, slot.browser, slot.toolset, this.#losses.get(slot)?.cause),
+			validate: this.#validate.bind(this),
+			watch: this.#watch.bind(this),
+			error: this.#fault.bind(this),
+			min: size,
+			restarts: 1
+		});
 		this.#root = (0, node_path.resolve)(options?.root ?? "tmp/browsers");
 		this.#headless = options?.headless ?? true;
 		this.#executable = options?.executable;
@@ -955,7 +1059,8 @@ var BrowserMCPServer = class {
 				version
 			},
 			tools: this.#tools,
-			execution: this.#execute.bind(this)
+			execution: this.#execute.bind(this),
+			handshake: this.#handshake.bind(this)
 		});
 		this.#transport = (0, _orkestrel_mcp_server.createStdioServer)((0, _orkestrel_mcp.createMCPLegacy)(server), {
 			input: this.#input,
@@ -968,17 +1073,32 @@ var BrowserMCPServer = class {
 	}
 	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);
+		this.#starting ??= this.#setup();
+		return this.#starting;
 	}
 	destroy() {
-		this.#closing ??= this.#destroy();
+		this.#closing ??= Promise.resolve().then(this.#destroy.bind(this));
 		return this.#closing;
 	}
+	async #setup() {
+		this.#input.on("end", this.#signal);
+		process.on("SIGINT", this.#signal);
+		process.on("SIGTERM", this.#signal);
+		this.#transport.start();
+		try {
+			await (0, node_fs_promises.mkdir)((0, node_path.join)(this.#root, ".profiles"), { recursive: true });
+			if (this.#closing !== void 0) return;
+			this.#sweeping = this.#sweep();
+			const warming = this.#pool.start().then(void 0, (error) => error);
+			await this.#grant(this.#abort.signal);
+			if (this.#closing !== void 0) return;
+			warming.then(this.#exhaust.bind(this));
+		} catch (error) {
+			if (this.#closing !== void 0) return;
+			if ((0, _src_core.isBrowserError)(error) && error.code === "BROWSER_SERVER_UNAVAILABLE") throw error;
+			throw this.#unavailable((0, _orkestrel_pool.isPoolError)(error) ? error.cause ?? this.#failure : error);
+		}
+	}
 	async #destroy() {
 		process.removeListener("SIGINT", this.#signal);
 		process.removeListener("SIGTERM", this.#signal);
@@ -986,19 +1106,34 @@ var BrowserMCPServer = class {
 		this.#transport.stop();
 		for (const tool of this.#tools.tools()) this.#tools.remove(tool.name);
 		this.#unmirror();
+		this.#lease = void 0;
 		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
+		const barrier = this.#pool.destroy().catch((error) => {
+			for (const failure of (0, _orkestrel_pool.isPoolError)(error) ? error.context?.failures ?? [error] : [error]) this.#faults.add(failure);
 		});
-		if (failures.length > 0) throw new AggregateError(failures, "The browse server teardown failed");
+		await this.#starting?.catch(() => void 0);
+		await barrier;
+		await this.#sweeping;
+		if (this.#stranded !== void 0) this.#faults.add(this.#stranded);
+		for (const folder of this.#folders) {
+			try {
+				const record = parseBrowserProfileRecord(await (0, node_fs_promises.readFile)((0, node_path.join)(folder, BROWSER_SERVER_RECORD), "utf8"));
+				if (record === void 0 || probeProcess(record.pid)) continue;
+			} catch (error) {
+				if (!(0, _orkestrel_contract.isError)(error) || !("code" in error) || error.code !== "ENOENT") continue;
+			}
+			try {
+				await (0, node_fs_promises.rm)(folder, {
+					recursive: true,
+					force: true,
+					maxRetries: 5
+				});
+				this.#folders.delete(folder);
+			} catch (error) {
+				this.#faults.add(error);
+			}
+		}
+		if (this.#faults.size > 0) throw new AggregateError([...this.#faults], "The browse server teardown failed");
 	}
 	async #execute(context) {
 		const result = await context.tools.execute(context.call, {
@@ -1015,38 +1150,224 @@ var BrowserMCPServer = class {
 		};
 	}
 	#end() {
-		this.destroy();
+		if (this.#closing !== void 0) return;
+		this.destroy().catch(this.#endFailure.bind(this));
+	}
+	#endFailure(error) {
+		process.exitCode = 1;
+		this.#write(`browse: ${describeBrowserServerLoss(BROWSER_SERVER_TEARDOWN, error)}`);
 	}
 	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;
+		let slot;
+		try {
+			slot = await this.#serve(context.signal);
+		} catch (error) {
+			context.signal.throwIfAborted();
+			if ((0, _src_core.isBrowserError)(error)) throw new _src_core.BrowserError(this.#annotate(`${error.code}: ${error.message}`), error.code);
+			throw error;
+		}
+		let result;
+		try {
+			result = await slot.toolset.tools.execute({
+				id: name,
+				name,
+				arguments: args
+			}, context);
+		} catch (error) {
+			result = {
+				id: name,
+				name,
+				success: false,
+				error: (0, _orkestrel_contract.isError)(error) ? error.message : String(error)
+			};
+		}
+		context.signal.throwIfAborted();
+		if (!result.success) {
+			if (this.#lease?.value === slot && !context.signal.aborted) try {
+				await slot.browser.ping({ signal: AbortSignal.any([context.signal, this.#abort.signal]) });
+			} catch (error) {
+				if (!context.signal.aborted && !this.#abort.signal.aborted) this.#lose(slot, error);
+			}
+			context.signal.throwIfAborted();
+			if (this.#lease?.value !== slot) {
+				const loss = this.#losses.get(slot);
+				throw new _src_core.BrowserError(this.#annotate(describeBrowserServerLoss(BROWSER_SERVER_UNRESOLVED, loss?.cause, loss?.url), slot), BROWSER_SERVER_UNRESOLVED);
+			}
+			throw new _src_core.BrowserError(this.#annotate(result.error, slot));
+		}
+		return typeof result.value === "string" ? this.#annotate(result.value, slot) : result.value;
+	}
+	#annotate(value, slot) {
+		const notes = [];
+		for (const lost of this.#notice) {
+			if (lost === slot) continue;
+			const loss = this.#losses.get(lost);
+			notes.push(describeBrowserServerLoss(BROWSER_SERVER_CRASH, loss?.cause, loss?.url));
+			this.#notice.delete(lost);
+		}
+		return [...notes, value].join("\n");
+	}
+	async #handshake(options) {
+		try {
+			await this.#race(this.#starting, options.signal);
+			if (this.#closing !== void 0) throw this.#ended();
+		} catch (error) {
+			options.signal.throwIfAborted();
+			if ((0, _src_core.isBrowserError)(error)) throw new _orkestrel_mcp.MCPError(`${error.code}: ${error.message}`, _orkestrel_mcp.JSONRPC_SERVER_ERROR, { code: error.code });
+			throw error;
+		}
+	}
+	async #race(promise, signal) {
+		signal.throwIfAborted();
+		const aborted = Promise.withResolvers();
+		const listener = (0, node_events.addAbortListener)(signal, () => aborted.reject(signal.reason));
+		try {
+			return await Promise.race([promise, aborted.promise]);
+		} finally {
+			listener[Symbol.dispose]();
+		}
+	}
+	async #grant(signal) {
+		if (this.#lease !== void 0) return this.#lease;
+		this.#granting ??= this.#pool.acquire(this.#abort.signal).then(this.#hold.bind(this), this.#refuse.bind(this));
+		const token = await this.#race(this.#granting, signal);
+		if (token === void 0) throw this.#ended();
+		return token;
+	}
+	#hold(token) {
+		this.#granting = void 0;
+		if (this.#closing !== void 0) throw this.#ended();
+		if (this.#losses.has(token.value)) {
+			token.destroy().catch(() => void 0);
+			throw this.#unavailable(this.#losses.get(token.value)?.cause);
+		}
+		this.#lease = token;
+		const tools = token.value.toolset.tools;
+		for (const tool of tools.tools()) this.#mirror(tool);
+		tools.emitter.on("add", this.#added);
+		tools.emitter.on("remove", this.#removed);
+		tools.emitter.on("clear", this.#cleared);
+		return token;
+	}
+	#refuse(error) {
+		this.#granting = void 0;
+		throw error;
+	}
+	async #serve(signal) {
+		if (this.#closing !== void 0) throw this.#ended();
+		await this.#race(this.#starting, signal);
+		if (this.#closing !== void 0) throw this.#ended();
+		const held = this.#lease;
+		if (held !== void 0) try {
+			await held.value.browser.ping({ signal: AbortSignal.any([signal, this.#abort.signal]) });
+			if (this.#lease === held) return held.value;
+		} catch (error) {
+			signal.throwIfAborted();
+			if (this.#abort.signal.aborted) throw this.#ended();
+			this.#lose(held.value, error);
+		}
+		try {
+			const token = await this.#grant(signal);
+			if (this.#lease !== token) throw this.#unavailable(this.#losses.get(token.value)?.cause);
+			return token.value;
+		} catch (error) {
+			signal.throwIfAborted();
+			if (this.#abort.signal.aborted || (0, _orkestrel_pool.isPoolError)(error) && error.code === "destroyed") throw this.#ended();
+			if ((0, _orkestrel_pool.isPoolError)(error) && (error.code === "create" || error.code === "cleanup")) {
+				this.#exhaust(error);
+				throw this.#unavailable(error.cause ?? this.#failure);
+			}
+			throw error;
+		}
+	}
+	async #validate(slot) {
+		try {
+			await slot.browser.ping({ signal: this.#abort.signal });
+			return true;
+		} catch (error) {
+			if (!this.#abort.signal.aborted) this.#lose(slot, error);
+			return false;
+		}
+	}
+	#lose(slot, cause) {
+		if (this.#closing !== void 0 || this.#losses.has(slot)) return;
+		this.#losses.set(slot, {
+			cause,
+			url: slot.toolset.view.url
+		});
+		this.#failure = cause;
+		if (this.#lease?.value !== slot) return;
+		const token = this.#lease;
+		this.#unmirror();
+		this.#lease = void 0;
+		this.#notice.add(slot);
+		token.destroy().catch(() => void 0);
+	}
+	#watch(slot, signal) {
+		const loss = Promise.withResolvers();
+		const disconnect = this.#disconnect.bind(this, slot);
+		const page = this.#track.bind(this, slot);
+		const subscription = (0, node_events.addAbortListener)(signal, this.#unwatch.bind(this, slot));
+		this.#watches.set(slot, {
+			resolve: loss.resolve,
+			disconnect,
+			page,
+			subscription,
+			crashes: /* @__PURE__ */ new Map()
+		});
+		slot.browser.emitter.on("disconnect", disconnect);
+		slot.context.emitter.on("page", page);
+		for (const current of slot.context.pages()) this.#track(slot, current);
+		if (signal.aborted) this.#unwatch(slot);
+		else if (slot.browser.status !== "connected") this.#disconnect(slot);
+		return loss.promise;
+	}
+	#track(slot, page) {
+		const watch = this.#watches.get(slot);
+		if (watch === void 0 || watch.crashes.has(page)) return;
+		const crash = this.#createCrash(slot, page);
+		page.emitter.on("crash", crash);
+		this.#watches.set(slot, {
+			...watch,
+			crashes: new Map([...watch.crashes, [page, crash]])
 		});
-		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;
+	#createCrash(slot, page) {
+		return () => {
+			if (page === slot.toolset.view) this.#report(slot, /* @__PURE__ */ new Error("The current page renderer crashed"));
+		};
+	}
+	#disconnect(slot) {
+		this.#report(slot, /* @__PURE__ */ new Error(slot.browser.pid === void 0 ? "The browser process exited" : "The browser transport disconnected"));
+	}
+	#report(slot, cause) {
+		const watch = this.#watches.get(slot);
+		if (watch === void 0) return;
+		this.#unwatch(slot);
+		this.#lose(slot, cause);
+		watch.resolve(cause);
+	}
+	#unwatch(slot) {
+		const watch = this.#watches.get(slot);
+		if (watch === void 0) return;
+		this.#watches.delete(slot);
+		slot.browser.emitter.off("disconnect", watch.disconnect);
+		slot.context.emitter.off("page", watch.page);
+		for (const [page, crash] of watch.crashes) page.emitter.off("crash", crash);
+		watch.subscription[Symbol.dispose]();
+	}
+	#fault(error) {
+		this.#faults.add(error);
+	}
+	async #warm() {
+		if (this.#closing !== void 0) throw this.#ended();
+		if (this.#stranded !== void 0) throw new _src_core.BrowserError((0, _orkestrel_contract.isError)(this.#stranded) ? this.#stranded.message : String(this.#stranded), BROWSER_SERVER_TEARDOWN, (0, _src_core.isBrowserError)(this.#stranded) ? this.#stranded.context : void 0);
+		const profile = (0, node_path.join)(this.#root, ".profiles", formatBrowserLockEntry(process.pid, (0, node_crypto.randomUUID)()));
 		let browser;
 		let toolset;
 		try {
+			await (0, node_fs_promises.mkdir)(profile);
+			this.#folders.add(profile);
 			browser = this.#launcher({
 				headless: this.#headless,
 				profile,
@@ -1055,9 +1376,16 @@ var BrowserMCPServer = class {
 				...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();
+			if (browser.pid !== void 0 && browser.endpoint !== void 0) {
+				const record = (0, node_path.join)(profile, BROWSER_SERVER_RECORD);
+				await (0, node_fs_promises.writeFile)(`${record}.tmp`, JSON.stringify({
+					pid: browser.pid,
+					endpoint: browser.endpoint
+				}));
+				await (0, node_fs_promises.rename)(`${record}.tmp`, record);
+			}
+			const context = await browser.isolate({ reference: this.#reference });
 			const page = await context.create();
 			toolset = (0, _src_core.createBrowserToolset)(page, {
 				context,
@@ -1067,26 +1395,103 @@ var BrowserMCPServer = class {
 					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;
+			return {
+				browser,
+				profile,
+				context,
+				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);
+			if (this.#folders.has(profile)) await this.#destroySlot(profile, browser, toolset).catch((failure) => {
+				this.#stranded = failure;
+			});
+			if (this.#closing === void 0) this.#write(`browse: ${describeBrowserServerLoss(BROWSER_SERVER_LAUNCH, error)}`);
+			throw error;
+		}
+	}
+	async #destroySlot(profile, browser, toolset, cause) {
+		if ((0, _src_core.isCDPTimeoutError)(cause) && browser?.pid !== void 0) try {
+			process.kill(browser.pid, "SIGKILL");
+		} catch (error) {
+			if (!(0, _orkestrel_contract.isError)(error) || !("code" in error) || error.code !== "ESRCH") this.#faults.add(error);
+		}
+		await toolset?.destroy().catch((error) => this.#faults.add(error));
+		try {
+			await browser?.destroy();
+		} catch (error) {
+			if (this.#closing === void 0) this.#write(`browse: ${describeBrowserServerLoss(BROWSER_SERVER_TEARDOWN, error)}`);
+			throw error;
+		}
+		try {
 			await (0, node_fs_promises.rm)(profile, {
 				recursive: true,
 				force: true,
 				maxRetries: 5
 			});
-			throw error;
+			this.#folders.delete(profile);
+		} catch {}
+	}
+	async #sweep() {
+		const profiles = (0, node_path.join)(this.#root, ".profiles");
+		try {
+			for (const entry of await (0, node_fs_promises.readdir)(profiles)) {
+				if (this.#closing !== void 0) return;
+				const pid = parseBrowserLockEntry(entry);
+				if (pid === void 0 || pid === process.pid || probeProcess(pid)) continue;
+				const folder = (0, node_path.join)(profiles, entry);
+				this.#folders.add(folder);
+				try {
+					const record = parseBrowserProfileRecord(await (0, node_fs_promises.readFile)((0, node_path.join)(folder, BROWSER_SERVER_RECORD), "utf8"));
+					if (record === void 0) continue;
+					if (probeProcess(record.pid)) {
+						const transport = createCDPTransport({ url: record.endpoint });
+						const client = (0, _src_core.createCDPClient)({ transport });
+						try {
+							this.#abort.signal.throwIfAborted();
+							await this.#race(client.connect(), this.#abort.signal);
+							await client.send("Browser.close", void 0, { signal: this.#abort.signal });
+						} catch {} finally {
+							await transport.close();
+							await client.close();
+						}
+						if (probeProcess(record.pid)) continue;
+					}
+				} catch (error) {
+					if (!(0, _orkestrel_contract.isError)(error) || !("code" in error) || error.code !== "ENOENT") continue;
+				}
+				try {
+					await (0, node_fs_promises.rm)(folder, {
+						recursive: true,
+						force: true,
+						maxRetries: 5
+					});
+					this.#folders.delete(folder);
+				} catch {}
+			}
+		} catch (error) {
+			this.#write(`browse: ${describeBrowserServerLoss(BROWSER_SERVER_SWEEP, error)}`);
 		}
 	}
+	#write(line) {
+		try {
+			this.#log.write(`${line}\n`, (error) => {
+				if (error !== void 0 && error !== null) this.#faults.add(error);
+			});
+		} catch (error) {
+			this.#faults.add(error);
+		}
+	}
+	#exhaust(error) {
+		if ((0, _orkestrel_pool.isPoolError)(error) && error.code === "create") this.#write(`browse: ${describeBrowserServerLoss(BROWSER_SERVER_EXHAUSTED, error.cause ?? this.#failure)}`);
+	}
+	#unavailable(cause) {
+		const message = describeBrowserServerLoss(BROWSER_SERVER_UNAVAILABLE, cause);
+		return new _src_core.BrowserError(message.slice(BROWSER_SERVER_UNAVAILABLE.length + 2), BROWSER_SERVER_UNAVAILABLE);
+	}
+	#issue() {
+		return `e${++this.#references}`;
+	}
 	#mirror(tool) {
 		if (this.#vocabulary.has(tool.name)) return;
 		this.#tools.add((0, _orkestrel_tool.createTool)({
@@ -1096,7 +1501,7 @@ var BrowserMCPServer = class {
 	}
 	#withdraw(tool) {
 		if (this.#vocabulary.has(tool.name)) return;
-		const current = this.#mirrored?.tool(tool.name);
+		const current = this.#lease?.value.toolset.tools.tool(tool.name);
 		if (current === void 0) this.#tools.remove(tool.name);
 		else this.#mirror(current);
 	}
@@ -1104,9 +1509,9 @@ var BrowserMCPServer = class {
 		for (const tool of tools) this.#withdraw(tool);
 	}
 	#unmirror() {
-		const mirrored = this.#mirrored;
+		const mirrored = this.#lease?.value.toolset.tools;
 		if (mirrored === void 0) return;
-		this.#mirrored = void 0;
+		for (const tool of mirrored.tools()) if (!this.#vocabulary.has(tool.name)) this.#tools.remove(tool.name);
 		mirrored.emitter.off("add", this.#added);
 		mirrored.emitter.off("remove", this.#removed);
 		mirrored.emitter.off("clear", this.#cleared);
@@ -1228,7 +1633,13 @@ var FileBrowserStore = class {
 			await this.check(path, options);
 			await this.check(temporary, options);
 			options?.signal?.throwIfAborted();
-			await (0, node_fs_promises.rename)(temporary, path);
+			try {
+				await (0, node_fs_promises.rename)(temporary, path);
+			} catch (error) {
+				const target = await (0, node_fs_promises.lstat)(path).catch(() => void 0);
+				if (error instanceof Error && "code" in error && (error.code === "EISDIR" || error.code === "EPERM") && target?.isDirectory()) throw new _src_core.BrowserError(`Cannot replace directory: ${path}`, "BROWSER_JOURNEY_FILE", { path });
+				throw error;
+			}
 			owned = false;
 		} catch (error) {
 			options?.signal?.throwIfAborted();
@@ -1273,13 +1684,7 @@ var FileBrowserStore = class {
 				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 (pid === void 0 || probeProcess(pid)) break;
 					if (!await this.#unlinkLock(this.resolvePath(path, holder))) continue;
 				}
 				await this.#removeLock(path);
@@ -1429,7 +1834,14 @@ var FileBrowserStore = class {
 		try {
 			await (0, node_fs_promises.rmdir)(path);
 		} catch (error) {
-			if (error instanceof Error && "code" in error && (error.code === "ENOENT" || error.code === "ENOTEMPTY")) return;
+			if (error instanceof Error && "code" in error) {
+				if (error.code === "ENOTEMPTY") return;
+				if (error.code === "ENOENT" || error.code === "EPERM") try {
+					if ((await (0, node_fs_promises.lstat)(path)).isDirectory()) return;
+				} catch (cause) {
+					if (cause instanceof Error && "code" in cause && cause.code === "ENOENT") return;
+				}
+			}
 			throw new _src_core.BrowserError(`Cannot remove lock directory: ${path}`, "BROWSER_JOURNEY_ACCESS", { path });
 		}
 	}
@@ -1714,7 +2126,7 @@ function createFileBrowserRunStore(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.
+* Model Context Protocol on stdio and warms Chromium at server start.
 *
 * @param options - The root, the launch, the journeys' read-only switch, and the streams
 * @returns A {@link BrowserMCPServerInterface} that reads nothing until `start()`
@@ -1724,7 +2136,7 @@ function createFileBrowserRunStore(options) {
 * 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.start() // resolves after leasing a connected browser
 * await server.destroy()
 * ```
 */
@@ -1800,6 +2212,15 @@ var Browser = class {
 	get pid() {
 		return this.#servingPid ?? this.#process?.pid;
 	}
+	get endpoint() {
+		return this.#endpoint;
+	}
+	async ping(options) {
+		if (this.#destroyed) throw new BrowserDestroyedError();
+		const client = this.#client;
+		if (this.#status !== "connected" || client === void 0) throw new BrowserNotConnectedError();
+		await client.send("Browser.getVersion", void 0, options);
+	}
 	async discover() {
 		const result = await this.#discoverCDP();
 		this.#emitter.emit("discover", result);
@@ -1925,7 +2346,7 @@ var Browser = class {
 					await this.#connectCDP(discovery.endpoint);
 					return;
 				}
-			} else await this.#raceAbort(this.#assertPortFree());
+			} else if (this.#options.cdp?.port !== void 0) await this.#raceAbort(this.#assertPortFree());
 			this.#assertNotAborted();
 			await this.#launch();
 		} catch (error) {
@@ -2354,6 +2775,7 @@ var Browser = class {
 			const process = this.#process;
 			if (process !== void 0) {
 				if (!await this.#waitForTerminationWithin(process, 3e3)) await this.#terminate(process);
+				await this.#closeProcessPipe(process);
 			}
 			this.#process = void 0;
 			this.#servingPid = void 0;
@@ -2525,12 +2947,23 @@ var Browser = class {
 		return results[0] && (results[1] === true || final && results[1] === void 0);
 	}
 	async #terminate(process) {
-		if (process === void 0 || (process.exitCode !== null || process.signalCode !== null) && this.#inspectRemainder(process) === false) return;
-		if (this.#signalProcess(process, "SIGTERM") === false) return;
-		if (await this.#waitForTerminationWithin(process, 3e3)) return;
-		if (this.#signalProcess(process, "SIGKILL") === false) return;
-		if (await this.#waitForTerminationWithin(process, 3e3, true)) return;
-		throw new _src_core.BrowserConnectionError("Browser process did not exit after SIGKILL", { pid: this.#servingPid ?? process.pid });
+		try {
+			if (process === void 0 || (process.exitCode !== null || process.signalCode !== null) && this.#inspectRemainder(process) === false) return;
+			if (this.#signalProcess(process, "SIGTERM") === false) return;
+			if (await this.#waitForTerminationWithin(process, 3e3)) return;
+			if (this.#signalProcess(process, "SIGKILL") === false) return;
+			if (await this.#waitForTerminationWithin(process, 3e3, true)) return;
+			throw new _src_core.BrowserConnectionError("Browser process did not exit after SIGKILL", { pid: this.#servingPid ?? process.pid });
+		} finally {
+			await this.#closeProcessPipe(process);
+		}
+	}
+	async #closeProcessPipe(process) {
+		const stream = process?.stderr;
+		if (stream === void 0 || stream === null || stream.closed) return;
+		const closed = (0, node_events.once)(stream, "close");
+		stream.destroy();
+		await closed;
 	}
 	#finish() {
 		this.#unbindTransport();
@@ -2573,6 +3006,18 @@ 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_SERVER_CRASH = BROWSER_SERVER_CRASH;
+exports.BROWSER_SERVER_EXHAUSTED = BROWSER_SERVER_EXHAUSTED;
+exports.BROWSER_SERVER_LAUNCH = BROWSER_SERVER_LAUNCH;
+exports.BROWSER_SERVER_OPTIONS = BROWSER_SERVER_OPTIONS;
+exports.BROWSER_SERVER_POOL_LIMIT = BROWSER_SERVER_POOL_LIMIT;
+exports.BROWSER_SERVER_POOL_SIZE = BROWSER_SERVER_POOL_SIZE;
+exports.BROWSER_SERVER_RECORD = BROWSER_SERVER_RECORD;
+exports.BROWSER_SERVER_RESTARTS = BROWSER_SERVER_RESTARTS;
+exports.BROWSER_SERVER_SWEEP = BROWSER_SERVER_SWEEP;
+exports.BROWSER_SERVER_TEARDOWN = BROWSER_SERVER_TEARDOWN;
+exports.BROWSER_SERVER_UNAVAILABLE = BROWSER_SERVER_UNAVAILABLE;
+exports.BROWSER_SERVER_UNRESOLVED = BROWSER_SERVER_UNRESOLVED;
 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;
@@ -2601,6 +3046,7 @@ exports.createBrowserWriter = createBrowserWriter;
 exports.createCDPTransport = createCDPTransport;
 exports.createFileBrowserJourneyStore = createFileBrowserJourneyStore;
 exports.createFileBrowserRunStore = createFileBrowserRunStore;
+exports.describeBrowserServerLoss = describeBrowserServerLoss;
 exports.fetchCDPTargets = fetchCDPTargets;
 exports.findEnvOverrides = findEnvOverrides;
 exports.findInstallPaths = findInstallPaths;
@@ -2614,7 +3060,9 @@ exports.launchBrowserProcess = launchBrowserProcess;
 exports.normalizeExecutablePath = normalizeExecutablePath;
 exports.parseBrowserEngine = parseBrowserEngine;
 exports.parseBrowserLockEntry = parseBrowserLockEntry;
+exports.parseBrowserProfileRecord = parseBrowserProfileRecord;
 exports.probePathNames = probePathNames;
+exports.probeProcess = probeProcess;
 exports.readBrowserEndpoint = readBrowserEndpoint;
 exports.readFirstLine = readFirstLine;
 exports.removeBrowserProfile = removeBrowserProfile;