@orkestrel/browser 0.0.24 → 0.0.25

package/dist/src/server/index.js

@@ -1,4 +1,4 @@
-import { BROWSER_DEFAULT_TIMEOUT_MS, BROWSER_JOURNEY_FORMAT_VERSION, BROWSER_JOURNEY_NAME_PATTERN, BROWSER_JOURNEY_TOOL_NAMES, BROWSER_RUN_ID_PATTERN, BROWSER_TOOL_COPY, BROWSER_TOOL_NAMES, BrowserConnectionError, BrowserContext, BrowserError, BrowserTransition, CDPClient, createBrowserToolset, createCDPClient, generateBrowserRunId, isBrowserConnectionError, isBrowserError, isCDPTimeoutError, normalizeBrowserJourneyReason, validateBrowserContextOptions, validateBrowserJourney, validateBrowserRun, validateBrowserStorePage } from "../core/index.js";
+import { BROWSER_DEFAULT_TIMEOUT_MS, BROWSER_JOURNEY_FORMAT_VERSION, BROWSER_JOURNEY_NAME_PATTERN, BROWSER_JOURNEY_TOOL_NAMES, BROWSER_RUN_ID_PATTERN, BROWSER_TOOL_COPY, BROWSER_TOOL_NAMES, BrowserConnectionError, BrowserContext, BrowserError, BrowserTransition, CDPClient, createBrowserToolset, createCDPClient, generateBrowserRunId, isBrowserConnectionError, isBrowserError, isCDPConnectionError, isCDPTimeoutError, normalizeBrowserJourneyReason, validateBrowserContextOptions, validateBrowserJourney, validateBrowserRun, validateBrowserStorePage } from "../core/index.js";
 import { attempt, isArray, isError, isInstance, isInteger, isNumber, isRecord, isString, parseInteger, parseJSON } from "@orkestrel/contract";
 import { existsSync, globSync, realpathSync } from "node:fs";
 import { lstat, mkdir, mkdtemp, open, readFile, readdir, rename, rm, rmdir, unlink, writeFile } from "node:fs/promises";
@@ -37,8 +37,18 @@ var BROWSER_CDP_VERSION_PATH = "/json/version";
 * other target category Chromium reports — `'/json/list'`.
 */
 var BROWSER_CDP_LIST_PATH = "/json/list";
-/** Lists the flags always passed to a launched browser process, alongside the caller's own. */
-var BROWSER_LAUNCH_ARGS = Object.freeze(["--no-first-run", "--no-default-browser-check"]);
+/**
+* Lists the flags always passed to a launched browser process, alongside the caller's own.
+*
+* @remarks
+* Disables account sync so extension installs cannot reset URL loader factories during page imports.
+* Edge can still sign a fresh Windows profile in to the operating-system account.
+*/
+var BROWSER_LAUNCH_ARGS = Object.freeze([
+	"--no-first-run",
+	"--no-default-browser-check",
+	"--disable-sync"
+]);
 /**
 * Names the flag that enables headless mode on a launched browser process, `'--headless=new'`.
 */
@@ -218,6 +228,10 @@ var BROWSER_SERVER_UNAVAILABLE = "BROWSER_SERVER_UNAVAILABLE";
 var BROWSER_SERVER_LAUNCH = "BROWSER_SERVER_LAUNCH";
 /** Sets the default number of warm browsers to 1. */
 var BROWSER_SERVER_POOL_SIZE = 1;
+/** Sets the default context capacity per browser, including the shared holder. */
+var BROWSER_SERVER_CONTEXTS = 2;
+/** Limits context capacity to the largest measured per-browser count. */
+var BROWSER_SERVER_CONTEXTS_LIMIT = 4;
 /** 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. */
@@ -1041,7 +1055,7 @@ var FileBrowserWriter = class {
 };
 //#endregion
 //#region package.json
-var version = "0.0.24";
+var version = "0.0.25";
 //#endregion
 //#region src/server/BrowserMCPServer.ts
 /**
@@ -1057,17 +1071,18 @@ var version = "0.0.24";
 * 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 server also advertises `acquire`, `execute`, `tools`, and `destroy` with
-* `BROWSER_SERVER_COPY`. Startup warms the pool and leases the shared browser. The legacy
+* `BROWSER_SERVER_COPY`. Startup warms the pool and assigns a prepared context to the shared holder. The legacy
 * handshake and browser calls await that setup. Named holders each own a lease, a pending grant,
 * and loss notices; concurrent calls on a holder share its replacement grant. Ending a holder
-* destroys its token, and admission counts that holder until disposal settles.
+* closes its context and releases its lease, and admission counts that holder until disposal settles.
 * 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;
+* A disconnect retires its browser and every hosted generation. A current-page crash retires only
+* that holder's context. 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.
 * Concurrent checks share one ping per slot. Cancelling a call ends only its wait; the ping keeps
@@ -1075,7 +1090,8 @@ var version = "0.0.24";
 *
 * `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 every
-* slot through the pool — its toolset, which aborts the active replay, then its browser, then its
+* slot through the pool — each toolset, which aborts its active replay, then its context and downloads,
+* then its browser and 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
@@ -1110,8 +1126,16 @@ var BrowserMCPServer = class {
 	#folders = /* @__PURE__ */ new Set();
 	#faults = /* @__PURE__ */ new Set();
 	#losses = /* @__PURE__ */ new WeakMap();
+	#departures = /* @__PURE__ */ new WeakMap();
 	#pings = /* @__PURE__ */ new WeakMap();
 	#watches = /* @__PURE__ */ new Map();
+	#observed = /* @__PURE__ */ new Map();
+	#prepared = /* @__PURE__ */ new Map();
+	#owned = /* @__PURE__ */ new Map();
+	#building = /* @__PURE__ */ new Map();
+	#cleaning = /* @__PURE__ */ new WeakMap();
+	#endings = /* @__PURE__ */ new WeakMap();
+	#retentions = /* @__PURE__ */ new Map();
 	#shared = {
 		id: "shared",
 		purpose: "Shared browser",
@@ -1125,7 +1149,7 @@ var BrowserMCPServer = class {
 	#drains = /* @__PURE__ */ new Map();
 	#readers = /* @__PURE__ */ new Map();
 	#writers = /* @__PURE__ */ new Set();
-	#size;
+	#admission;
 	#reference;
 	#references = 0;
 	#failure;
@@ -1140,17 +1164,20 @@ var BrowserMCPServer = class {
 	*/
 	constructor(options) {
 		const size = options?.pool?.size ?? 1;
+		const contexts = options?.pool?.contexts ?? 2;
 		if (!isInteger(size) || size < 1 || size > 3) throw new BrowserError(`pool.size must be an integer from 1 through 3`, BROWSER_SERVER_OPTIONS);
-		this.#size = size;
+		if (!isInteger(contexts) || contexts < 1 || contexts > 4) throw new BrowserError(`pool.contexts must be an integer from 1 through 4`, BROWSER_SERVER_OPTIONS);
+		this.#admission = size * contexts;
 		this.#log = options?.log ?? process.stderr;
 		this.#reference = this.#issue.bind(this);
 		this.#pool = createPool({
 			create: this.#warm.bind(this),
-			destroy: (slot) => this.#destroySlot(slot.profile, slot.browser, slot.toolset, this.#losses.get(slot)?.cause),
+			destroy: this.#destroyRecord.bind(this),
 			validate: this.#validate.bind(this),
 			watch: this.#watch.bind(this),
 			error: this.#fault.bind(this),
 			min: size,
+			capacity: contexts,
 			restarts: 1
 		});
 		this.#root = resolve(options?.root ?? "tmp/browsers");
@@ -1233,6 +1260,7 @@ var BrowserMCPServer = class {
 		this.#transport.stop();
 		for (const tool of this.#tools.tools()) this.#tools.remove(tool.name);
 		this.#unmirror();
+		for (const generation of this.#observed.keys()) this.#untrack(generation);
 		this.#leases.clear();
 		for (const holder of this.#holders.values()) holder.abort.abort();
 		this.#abort.abort();
@@ -1241,6 +1269,7 @@ var BrowserMCPServer = class {
 		});
 		await this.#starting?.catch(() => void 0);
 		await barrier;
+		await Promise.allSettled(this.#grants.values());
 		await Promise.allSettled(this.#disposals.values());
 		this.#holders.clear();
 		await this.#sweeping;
@@ -1292,7 +1321,7 @@ var BrowserMCPServer = class {
 		if (this.#closing !== void 0) throw this.#ended();
 		const purpose = args["purpose"];
 		if (!isString(purpose) || purpose.trim().length === 0) throw new BrowserError("purpose must describe the work", "BROWSER_TOOLSET_ARGUMENT");
-		if (this.#holders.size >= this.#size) throw new BrowserError(`${BROWSER_SERVER_BUSY}: ${[...this.#holders.values()].map((holder) => `${holder.id} (${holder.purpose})`).join(", ")}. Call destroy for a holder no longer needed or call the named tools to share the shared browser.`, BROWSER_SERVER_BUSY);
+		if (this.#holders.size >= this.#admission) throw new BrowserError(`${BROWSER_SERVER_BUSY}: ${[...this.#holders.values()].map((holder) => `${holder.id} (${holder.purpose})`).join(", ")}. Call destroy for a holder no longer needed or call the named tools to share the shared browser.`, BROWSER_SERVER_BUSY);
 		const holder = {
 			id: randomUUID(),
 			purpose,
@@ -1301,13 +1330,13 @@ var BrowserMCPServer = class {
 		this.#holders.set(holder.id, holder);
 		const listener = addAbortListener(context.signal, () => holder.abort.abort(context.signal.reason));
 		try {
-			const slot = await this.#serve(holder, context.signal);
+			const lease = await this.#serve(holder, context.signal);
 			context.signal.throwIfAborted();
 			if (holder.abort.signal.aborted || this.#holders.get(holder.id) !== holder) throw this.#ended();
-			if (this.#leases.get(holder)?.value !== slot) throw this.#unavailable(this.#losses.get(slot)?.cause);
+			if (this.#leases.get(holder) !== lease) throw this.#unavailable(this.#departures.get(lease)?.cause);
 			const catalog = {
 				holder: holder.id,
-				tools: slot.toolset.tools.definitions()
+				tools: lease.generation.toolset.tools.definitions()
 			};
 			return JSON.stringify(catalog);
 		} catch (error) {
@@ -1333,12 +1362,12 @@ var BrowserMCPServer = class {
 		const holder = this.#holder(args["holder"]);
 		const signal = AbortSignal.any([context.signal, holder.abort.signal]);
 		try {
-			const slot = await this.#serve(holder, signal);
+			const lease = await this.#serve(holder, signal);
 			signal.throwIfAborted();
-			if (this.#leases.get(holder)?.value !== slot) throw this.#unavailable(this.#losses.get(slot)?.cause);
+			if (this.#leases.get(holder) !== lease) throw this.#unavailable(this.#departures.get(lease)?.cause);
 			const catalog = {
 				holder: holder.id,
-				tools: slot.toolset.tools.definitions()
+				tools: lease.generation.toolset.tools.definitions()
 			};
 			return this.#annotate(holder, JSON.stringify(catalog));
 		} catch (error) {
@@ -1357,17 +1386,19 @@ var BrowserMCPServer = class {
 		const pending = this.#disposals.get(holder.id);
 		if (pending !== void 0) return pending;
 		holder.abort.abort();
-		const token = this.#leases.get(holder);
+		const lease = this.#leases.get(holder);
 		this.#leases.delete(holder);
+		if (lease !== void 0) this.#untrack(lease.generation);
 		const disposal = Promise.resolve().then(async () => {
 			try {
 				await this.#grants.get(holder)?.catch(() => void 0);
-				await token?.destroy();
+				if (lease !== void 0) await this.#release(holder, lease);
 				await Promise.all(this.#drains.get(holder) ?? []);
+				await Promise.all([...this.#notices.get(holder) ?? []].filter((lost) => this.#losses.has(lost.token.value)).map((lost) => this.#endings.get(lost.token.value)?.promise));
 			} catch (error) {
 				this.#faults.add(error);
 			} finally {
-				if (this.#holders.get(holder.id) === holder) this.#holders.delete(holder.id);
+				if (this.#holders.get(holder.id) === holder && !this.#retentions.has(holder)) this.#holders.delete(holder.id);
 				this.#notices.delete(holder);
 				this.#drains.delete(holder);
 			}
@@ -1400,9 +1431,9 @@ var BrowserMCPServer = class {
 	}
 	async #perform(holder, name, args, context) {
 		const signal = holder === this.#shared ? context.signal : AbortSignal.any([context.signal, holder.abort.signal]);
-		let slot;
+		let lease;
 		try {
-			slot = await this.#serve(holder, signal);
+			lease = await this.#serve(holder, signal);
 		} catch (error) {
 			context.signal.throwIfAborted();
 			if (holder !== this.#shared && holder.abort.signal.aborted) throw new BrowserError(`${BROWSER_SERVER_UNRESOLVED}: the holder ended during the call`, BROWSER_SERVER_UNRESOLVED);
@@ -1411,7 +1442,7 @@ var BrowserMCPServer = class {
 		}
 		let result;
 		try {
-			const execution = slot.toolset.tools.execute({
+			const execution = lease.generation.toolset.tools.execute({
 				id: name,
 				name,
 				arguments: args
@@ -1433,23 +1464,23 @@ var BrowserMCPServer = class {
 		context.signal.throwIfAborted();
 		if (holder !== this.#shared && holder.abort.signal.aborted) throw new BrowserError(BROWSER_SERVER_UNRESOLVED + ": the holder ended during the call", BROWSER_SERVER_UNRESOLVED);
 		if (!result.success) {
-			if (this.#leases.get(holder)?.value === slot && !context.signal.aborted) try {
-				await this.#race(this.#ping(slot), context.signal);
+			if (this.#leases.get(holder) === lease && !context.signal.aborted) try {
+				await this.#race(this.#ping(lease.token.value), context.signal);
 			} catch {}
 			context.signal.throwIfAborted();
-			if (this.#leases.get(holder)?.value !== slot) {
-				const loss = this.#losses.get(slot);
-				throw new BrowserError(this.#annotate(holder, describeBrowserServerLoss(BROWSER_SERVER_UNRESOLVED, loss?.cause, loss?.url), slot), BROWSER_SERVER_UNRESOLVED);
+			if (this.#leases.get(holder) !== lease) {
+				const loss = this.#departures.get(lease);
+				throw new BrowserError(this.#annotate(holder, describeBrowserServerLoss(BROWSER_SERVER_UNRESOLVED, loss?.cause, loss?.url), lease), BROWSER_SERVER_UNRESOLVED);
 			}
-			throw new BrowserError(this.#annotate(holder, result.error, slot));
+			throw new BrowserError(this.#annotate(holder, result.error, lease));
 		}
-		return typeof result.value === "string" ? this.#annotate(holder, result.value, slot) : result.value;
+		return typeof result.value === "string" ? this.#annotate(holder, result.value, lease) : result.value;
 	}
-	#annotate(holder, value, slot) {
+	#annotate(holder, value, lease) {
 		const notes = [];
 		for (const lost of this.#notices.get(holder) ?? []) {
-			if (lost === slot) continue;
-			const loss = this.#losses.get(lost);
+			if (lost === lease) continue;
+			const loss = this.#departures.get(lost);
 			notes.push(describeBrowserServerLoss(BROWSER_SERVER_CRASH, loss?.cause, loss?.url));
 			this.#notices.get(holder)?.delete(lost);
 		}
@@ -1480,41 +1511,70 @@ var BrowserMCPServer = class {
 		if (held !== void 0) return held;
 		let granting = this.#grants.get(holder);
 		if (granting === void 0) {
-			granting = this.#pool.acquire(holder.abort.signal).then(this.#hold.bind(this, holder));
+			granting = Promise.resolve().then(async () => {
+				await Promise.allSettled(this.#drains.get(holder) ?? []);
+				if (this.#retentions.has(holder)) throw this.#unavailable(this.#retentions.get(holder));
+				const token = await this.#pool.acquire(holder.abort.signal);
+				return this.#hold(holder, token);
+			});
 			this.#grants.set(holder, granting);
 			granting.finally(() => {
 				if (this.#grants.get(holder) === granting) this.#grants.delete(holder);
 			}).catch(() => void 0);
 		}
-		const token = await this.#race(granting, signal);
-		if (token === void 0) throw this.#ended();
-		return token;
+		const lease = await this.#race(granting, signal);
+		if (lease === void 0) throw this.#ended();
+		return lease;
 	}
 	async #hold(holder, token) {
+		const slot = token.value;
 		if (this.#closing !== void 0 || this.#holders.get(holder.id) !== holder || holder.abort.signal.aborted) {
-			await token.destroy();
+			token.release();
+			throw this.#ended();
+		}
+		if (!this.#prepared.has(slot)) await this.#ping(slot);
+		if (this.#closing !== void 0 || holder.abort.signal.aborted) {
+			token.release();
 			throw this.#ended();
 		}
-		if (this.#losses.has(token.value)) {
-			await token.destroy().catch(() => void 0);
-			throw this.#unavailable(this.#losses.get(token.value)?.cause);
+		if (this.#losses.has(slot)) {
+			token.release();
+			throw this.#unavailable(this.#losses.get(slot)?.cause);
 		}
-		this.#leases.set(holder, token);
+		let generation = this.#prepared.get(slot);
+		this.#prepared.delete(slot);
+		try {
+			generation ??= await this.#build(slot, token);
+		} catch (error) {
+			if (this.#losses.has(slot)) await this.#endings.get(slot)?.promise;
+			else token.release();
+			throw this.#unavailable(error);
+		}
+		const lease = {
+			token,
+			generation
+		};
+		if (this.#closing !== void 0 || this.#holders.get(holder.id) !== holder || holder.abort.signal.aborted || this.#losses.has(slot)) {
+			await this.#release(holder, lease);
+			throw this.#ended();
+		}
+		this.#leases.set(holder, lease);
+		this.#observe(slot, generation);
 		if (holder === this.#shared) {
-			const tools = token.value.toolset.tools;
+			const tools = generation.toolset.tools;
 			const mirrored = {
-				token,
-				added: this.#mirror.bind(this, token),
-				removed: this.#withdraw.bind(this, token),
-				cleared: this.#clear.bind(this, token)
+				lease,
+				added: this.#mirror.bind(this, lease),
+				removed: this.#withdraw.bind(this, lease),
+				cleared: this.#clear.bind(this, lease)
 			};
 			this.#mirrored = mirrored;
-			for (const tool of tools.tools()) this.#mirror(token, tool);
+			for (const tool of tools.tools()) this.#mirror(lease, tool);
 			tools.emitter.on("add", mirrored.added);
 			tools.emitter.on("remove", mirrored.removed);
 			tools.emitter.on("clear", mirrored.cleared);
 		}
-		return token;
+		return lease;
 	}
 	async #serve(holder, signal) {
 		if (this.#closing !== void 0 || holder.abort.signal.aborted) throw this.#ended();
@@ -1522,16 +1582,16 @@ var BrowserMCPServer = class {
 		if (this.#closing !== void 0 || holder.abort.signal.aborted) throw this.#ended();
 		const held = this.#leases.get(holder);
 		if (held !== void 0) try {
-			await this.#race(this.#ping(held.value), signal);
-			if (this.#leases.get(holder) === held) return held.value;
+			await this.#race(this.#ping(held.token.value), signal);
+			if (this.#leases.get(holder) === held) return held;
 		} catch {
 			signal.throwIfAborted();
 			if (holder.abort.signal.aborted) throw this.#ended();
 		}
 		try {
-			const token = await this.#grant(holder, signal);
-			if (this.#leases.get(holder) !== token) throw this.#unavailable(this.#losses.get(token.value)?.cause);
-			return token.value;
+			const lease = await this.#grant(holder, signal);
+			if (this.#leases.get(holder) !== lease) throw this.#unavailable(this.#departures.get(lease)?.cause);
+			return lease;
 		} catch (error) {
 			signal.throwIfAborted();
 			if (holder.abort.signal.aborted || isPoolError(error) && error.code === "destroyed") throw this.#ended();
@@ -1562,78 +1622,211 @@ var BrowserMCPServer = class {
 	}
 	#lose(slot, cause) {
 		if (this.#closing !== void 0 || this.#losses.has(slot)) return;
-		this.#losses.set(slot, {
-			cause,
-			url: slot.toolset.view.url
-		});
+		this.#losses.set(slot, { cause });
 		this.#failure = cause;
-		for (const [holder, token] of this.#leases) {
-			if (token.value !== slot || this.#holders.get(holder.id) !== holder) continue;
-			if (holder === this.#shared) this.#unmirror();
-			this.#leases.delete(holder);
-			const notices = this.#notices.get(holder) ?? /* @__PURE__ */ new Set();
-			notices.add(slot);
-			this.#notices.set(holder, notices);
-			const drain = token.destroy();
-			const drains = this.#drains.get(holder) ?? /* @__PURE__ */ new Set();
-			drains.add(drain);
-			this.#drains.set(holder, drains);
-			drain.finally(() => drains.delete(drain)).catch(() => void 0);
+		for (const [holder, lease] of this.#leases) {
+			if (lease.token.value !== slot) continue;
+			this.#detach(holder, lease, cause);
 		}
+		const watch = this.#watches.get(slot);
+		this.#unwatch(slot);
+		watch?.resolve(cause);
+	}
+	#detach(holder, lease, cause) {
+		if (this.#leases.get(holder) !== lease || this.#holders.get(holder.id) !== holder) return;
+		this.#departures.set(lease, {
+			cause,
+			url: lease.generation.toolset.view.url
+		});
+		if (holder === this.#shared) this.#unmirror();
+		this.#leases.delete(holder);
+		this.#untrack(lease.generation);
+		const notices = this.#notices.get(holder) ?? /* @__PURE__ */ new Set();
+		notices.add(lease);
+		this.#notices.set(holder, notices);
 	}
 	#watch(slot, signal) {
 		const loss = Promise.withResolvers();
 		const disconnect = this.#disconnect.bind(this, slot);
-		const page = this.#track.bind(this, slot);
 		const subscription = addAbortListener(signal, this.#unwatch.bind(this, slot));
 		this.#watches.set(slot, {
 			resolve: loss.resolve,
 			disconnect,
-			page,
-			subscription,
-			crashes: /* @__PURE__ */ new Map()
+			subscription
 		});
 		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);
+	#observe(slot, generation) {
+		if (this.#observed.has(generation)) return;
+		const page = this.#track.bind(this, slot, generation);
+		this.#observed.set(generation, {
+			page,
+			crashes: /* @__PURE__ */ new Map()
+		});
+		generation.context.emitter.on("page", page);
+		for (const current of generation.context.pages()) this.#track(slot, generation, current);
+	}
+	#track(slot, generation, page) {
+		const watch = this.#observed.get(generation);
 		if (watch === void 0 || watch.crashes.has(page)) return;
-		const crash = this.#createCrash(slot, page);
+		const crash = this.#crash.bind(this, slot, generation, page);
 		page.emitter.on("crash", crash);
-		this.#watches.set(slot, {
+		this.#observed.set(generation, {
 			...watch,
 			crashes: new Map([...watch.crashes, [page, crash]])
 		});
 	}
-	#createCrash(slot, page) {
-		return () => {
-			if (page === slot.toolset.view) this.#report(slot, /* @__PURE__ */ new Error("The current page renderer crashed"));
-		};
+	#crash(slot, generation, page) {
+		if (this.#prepared.get(slot) === generation) {
+			this.#prepared.delete(slot);
+			this.#untrack(generation);
+			this.#clean(slot, generation).catch(this.#fault.bind(this));
+			return;
+		}
+		const held = [...this.#leases].find(([, lease]) => lease.generation === generation);
+		if (held === void 0 || page !== generation.toolset.view) return;
+		const [holder, lease] = held;
+		this.#detach(holder, lease, /* @__PURE__ */ new Error("The current page renderer crashed"));
+		const drain = this.#release(holder, lease);
+		const drains = this.#drains.get(holder) ?? /* @__PURE__ */ new Set();
+		drains.add(drain);
+		this.#drains.set(holder, drains);
+		drain.finally(() => drains.delete(drain)).catch(this.#fault.bind(this));
+	}
+	#untrack(generation) {
+		const watch = this.#observed.get(generation);
+		if (watch === void 0) return;
+		this.#observed.delete(generation);
+		generation.context.emitter.off("page", watch.page);
+		for (const [page, crash] of watch.crashes) page.emitter.off("crash", crash);
 	}
 	#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);
+		this.#lose(slot, /* @__PURE__ */ new Error(slot.browser.pid === void 0 ? "The browser process exited" : "The browser transport disconnected"));
 	}
 	#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]();
 	}
+	async #release(holder, lease) {
+		const slot = lease.token.value;
+		const removed = await this.#clean(slot, lease.generation);
+		const disposal = lease.generation.context.disposal;
+		if (!removed) this.#retentions.set(holder, /* @__PURE__ */ new Error("The context downloads directory remains owned"));
+		if (disposal?.confirmed !== true && !this.#losses.has(slot) && this.#closing === void 0) {
+			if (![...this.#leases.values()].some((held) => held.token.value === slot && held !== lease) && (this.#building.get(slot)?.size ?? 0) === 0) lease.token.release();
+			this.#lose(slot, disposal?.error ?? /* @__PURE__ */ new Error("The context disposal is unconfirmed"));
+			await this.#endings.get(slot)?.promise;
+		} else if (removed) lease.token.release();
+	}
+	#clean(slot, generation) {
+		let cleaning = this.#cleaning.get(generation);
+		if (cleaning !== void 0) return cleaning;
+		cleaning = Promise.resolve().then(async () => {
+			await generation.toolset.destroy().catch(this.#fault.bind(this));
+			await generation.context.close().catch((error) => {
+				if (!this.#losses.has(slot) && slot.browser.status === "connected") this.#fault(error);
+			});
+			try {
+				await rm(generation.directory, {
+					recursive: true,
+					force: true
+				});
+				this.#owned.get(slot)?.delete(generation);
+				return true;
+			} catch (error) {
+				this.#fault(error);
+				return false;
+			}
+		});
+		this.#cleaning.set(generation, cleaning);
+		return cleaning;
+	}
+	#build(slot, token) {
+		const construction = this.#construct(slot, token);
+		const building = this.#building.get(slot) ?? /* @__PURE__ */ new Set();
+		building.add(construction);
+		this.#building.set(slot, building);
+		construction.finally(() => building.delete(construction)).catch(() => void 0);
+		return construction;
+	}
+	async #construct(slot, token) {
+		const directory = join(slot.profile, "contexts", randomUUID(), "downloads");
+		let context;
+		let toolset;
+		try {
+			await mkdir(directory, { recursive: true });
+			let page;
+			try {
+				context = await slot.browser.isolate({
+					reference: this.#reference,
+					downloads: { path: directory },
+					...this.#viewport === void 0 ? {} : { emulation: { viewport: this.#viewport } }
+				});
+				page = await context.create();
+			} catch (error) {
+				if (token !== void 0) {
+					if (![...this.#leases.values()].some((lease) => lease.token.value === slot) && (this.#building.get(slot)?.size ?? 0) === 1) token.release();
+					this.#lose(slot, error);
+				}
+				throw error;
+			}
+			toolset = createBrowserToolset(page, {
+				context,
+				journeys: {
+					store: createFileBrowserJourneyStore({ root: this.#root }),
+					runs: createFileBrowserRunStore({ root: this.#root }),
+					readonly: this.#readonly
+				}
+			});
+			await toolset.start();
+			const generation = {
+				context,
+				toolset,
+				directory
+			};
+			const owned = this.#owned.get(slot) ?? /* @__PURE__ */ new Set();
+			owned.add(generation);
+			this.#owned.set(slot, owned);
+			return generation;
+		} catch (error) {
+			await toolset?.destroy().catch(this.#fault.bind(this));
+			await context?.close().catch((failure) => {
+				if (!this.#losses.has(slot) && slot.browser.status === "connected" && this.#closing === void 0 && !isCDPConnectionError(failure)) this.#fault(failure);
+			});
+			await rm(directory, {
+				recursive: true,
+				force: true
+			}).catch(this.#fault.bind(this));
+			throw error;
+		}
+	}
+	async #destroyRecord(slot) {
+		if (isCDPTimeoutError(this.#losses.get(slot)?.cause) && slot.browser.pid !== void 0) try {
+			process.kill(slot.browser.pid, "SIGKILL");
+		} catch (error) {
+			if (!isError(error) || !("code" in error) || error.code !== "ESRCH") this.#faults.add(error);
+		}
+		try {
+			await Promise.allSettled(this.#building.get(slot) ?? []);
+			const prepared = this.#prepared.get(slot);
+			if (prepared !== void 0) this.#untrack(prepared);
+			this.#prepared.delete(slot);
+			await Promise.all([...this.#owned.get(slot) ?? []].map((generation) => this.#clean(slot, generation)));
+			await this.#destroySlot(slot.profile, slot.browser);
+			this.#owned.delete(slot);
+			this.#building.delete(slot);
+			this.#endings.get(slot)?.resolve();
+		} catch (error) {
+			this.#endings.get(slot)?.reject(error);
+			throw error;
+		}
+	}
 	#fault(error) {
 		this.#faults.add(error);
 	}
@@ -1642,7 +1835,7 @@ var BrowserMCPServer = class {
 		if (this.#stranded !== void 0) throw new BrowserError(isError(this.#stranded) ? this.#stranded.message : String(this.#stranded), BROWSER_SERVER_TEARDOWN, isBrowserError(this.#stranded) ? this.#stranded.context : void 0);
 		const profile = join(this.#root, ".profiles", formatBrowserLockEntry(process.pid, randomUUID()));
 		let browser;
-		let toolset;
+		let slot;
 		try {
 			await mkdir(profile);
 			this.#folders.add(profile);
@@ -1664,42 +1857,26 @@ var BrowserMCPServer = class {
 				}));
 				await rename(`${record}.tmp`, record);
 			}
-			const context = await browser.isolate({
-				reference: this.#reference,
-				downloads: { path: join(profile, "downloads") },
-				...this.#viewport === void 0 ? {} : { emulation: { viewport: this.#viewport } }
-			});
-			const page = await context.create();
-			toolset = createBrowserToolset(page, {
-				context,
-				journeys: {
-					store: createFileBrowserJourneyStore({ root: this.#root }),
-					runs: createFileBrowserRunStore({ root: this.#root }),
-					readonly: this.#readonly
-				}
-			});
-			await toolset.start();
-			return {
+			slot = {
 				browser,
-				profile,
-				context,
-				toolset
+				profile
 			};
+			const ending = Promise.withResolvers();
+			ending.promise.catch(() => void 0);
+			this.#endings.set(slot, ending);
+			const generation = await this.#build(slot);
+			this.#prepared.set(slot, generation);
+			this.#observe(slot, generation);
+			return slot;
 		} catch (error) {
-			if (this.#folders.has(profile)) await this.#destroySlot(profile, browser, toolset).catch((failure) => {
+			if (this.#folders.has(profile)) await (slot === void 0 ? this.#destroySlot(profile, browser) : this.#destroyRecord(slot)).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 (isCDPTimeoutError(cause) && browser?.pid !== void 0) try {
-			process.kill(browser.pid, "SIGKILL");
-		} catch (error) {
-			if (!isError(error) || !("code" in error) || error.code !== "ESRCH") this.#faults.add(error);
-		}
-		await toolset?.destroy().catch((error) => this.#faults.add(error));
+	async #destroySlot(profile, browser) {
 		try {
 			await browser?.destroy();
 		} catch (error) {
@@ -1775,27 +1952,27 @@ var BrowserMCPServer = class {
 	#issue() {
 		return `e${++this.#references}`;
 	}
-	#mirror(token, tool) {
-		if (this.#leases.get(this.#shared) !== token || this.#vocabulary.has(tool.name)) return;
+	#mirror(lease, tool) {
+		if (this.#leases.get(this.#shared) !== lease || this.#vocabulary.has(tool.name)) return;
 		this.#tools.add(createTool({
 			...toolToDefinition(tool),
 			execute: this.#forward.bind(this, this.#shared, tool.name)
 		}));
 	}
-	#withdraw(token, tool) {
-		if (this.#leases.get(this.#shared) !== token || this.#vocabulary.has(tool.name)) return;
-		const current = token.value.toolset.tools.tool(tool.name);
+	#withdraw(lease, tool) {
+		if (this.#leases.get(this.#shared) !== lease || this.#vocabulary.has(tool.name)) return;
+		const current = lease.generation.toolset.tools.tool(tool.name);
 		if (current === void 0) this.#tools.remove(tool.name);
-		else this.#mirror(token, current);
+		else this.#mirror(lease, current);
 	}
-	#clear(token, tools) {
-		for (const tool of tools) this.#withdraw(token, tool);
+	#clear(lease, tools) {
+		for (const tool of tools) this.#withdraw(lease, tool);
 	}
 	#unmirror() {
 		const mirrored = this.#mirrored;
 		if (mirrored === void 0) return;
 		this.#mirrored = void 0;
-		const tools = mirrored.token.value.toolset.tools;
+		const tools = mirrored.lease.generation.toolset.tools;
 		for (const tool of tools.tools()) if (!this.#vocabulary.has(tool.name)) this.#tools.remove(tool.name);
 		tools.emitter.off("add", mirrored.added);
 		tools.emitter.off("remove", mirrored.removed);
@@ -2226,11 +2403,14 @@ var FileBrowserJourneyStore = class {
 /**
 * Persists runs and captures only in directories allocated by this instance.
 * @remarks Requires an existing root. Reopened stores can read and delete saved runs.
+* Allocations of one journey share a process-local queue across instances; the filesystem lock
+* still refuses conflicting mutations and allocations from another process.
 * @example
 * const store = new FileBrowserRunStore({ root: directory })
 * const slot = await store.open('check-ready')
 */
-var FileBrowserRunStore = class {
+var FileBrowserRunStore = class FileBrowserRunStore {
+	static #allocations = /* @__PURE__ */ new Map();
 	#files;
 	#slots = /* @__PURE__ */ new WeakMap();
 	#directories = /* @__PURE__ */ new Set();
@@ -2258,16 +2438,27 @@ var FileBrowserRunStore = class {
 	async open(name, options) {
 		options?.signal?.throwIfAborted();
 		this.#files.validateName(name);
-		return this.#files.lock(this.#files.resolvePath(name, BROWSER_JOURNEY_LOCK_DIRECTORY), async () => {
-			const directory = await this.#files.allocate(this.#files.resolvePath(name, BROWSER_RUN_DIRECTORY), generateBrowserRunId, options);
-			const slot = Object.freeze({
-				id: directory.id,
-				directory: directory.path
-			});
-			this.#directories.add(directory.path);
-			this.#slots.set(slot, directory.path);
-			return slot;
-		}, options);
+		const path = this.#files.resolvePath(name, BROWSER_JOURNEY_LOCK_DIRECTORY);
+		const previous = FileBrowserRunStore.#allocations.get(path);
+		const allocation = Promise.withResolvers();
+		FileBrowserRunStore.#allocations.set(path, allocation.promise);
+		try {
+			await previous;
+			options?.signal?.throwIfAborted();
+			return await this.#files.lock(path, async () => {
+				const directory = await this.#files.allocate(this.#files.resolvePath(name, BROWSER_RUN_DIRECTORY), generateBrowserRunId, options);
+				const slot = Object.freeze({
+					id: directory.id,
+					directory: directory.path
+				});
+				this.#directories.add(directory.path);
+				this.#slots.set(slot, directory.path);
+				return slot;
+			}, options);
+		} finally {
+			allocation.resolve();
+			if (FileBrowserRunStore.#allocations.get(path) === allocation.promise) FileBrowserRunStore.#allocations.delete(path);
+		}
 	}
 	async get(name, id, options) {
 		options?.signal?.throwIfAborted();
@@ -2477,6 +2668,7 @@ var Browser = class {
 	#servingPid;
 	#profile;
 	#contexts = [];
+	#isolating = /* @__PURE__ */ new Set();
 	#destroyed = false;
 	#connecting = new BrowserTransition();
 	#disconnecting = new BrowserTransition();
@@ -2563,33 +2755,13 @@ var Browser = class {
 		return [...this.#contexts];
 	}
 	async isolate(options) {
-		if (this.#destroyed) throw new BrowserDestroyedError();
-		const client = this.#client;
-		if (this.#status !== "connected" || client === void 0) throw new BrowserNotConnectedError();
-		validateBrowserContextOptions(options);
-		const params = { disposeOnDetach: false };
-		if (options?.proxy !== void 0) {
-			params["proxyServer"] = options.proxy.server;
-			if (options.proxy.bypass !== void 0) params["proxyBypassList"] = options.proxy.bypass.join(",");
-		}
-		if (options?.origins !== void 0) params["originsWithUniversalNetworkAccess"] = [...options.origins];
-		const result = await client.send("Target.createBrowserContext", params);
-		if (!isRecord(result) || !isString(result["browserContextId"])) throw new BrowserConnectionError("Failed to create isolated browser context");
-		const id = result["browserContextId"];
-		const context = new BrowserContext(client, id, options?.emulation?.viewport ?? this.#options.viewport, createBrowserWriter(), options?.emulation, options?.downloads, options);
+		const attempt = this.#isolate(options);
+		this.#isolating.add(attempt);
 		try {
-			if (options?.downloads !== void 0) await client.send("Browser.setDownloadBehavior", {
-				behavior: options.downloads.named === true ? "allowAndName" : "allow",
-				browserContextId: id,
-				downloadPath: options.downloads.path,
-				eventsEnabled: true
-			});
-		} catch (error) {
-			await context.close().catch(() => void 0);
-			throw error;
+			return await attempt;
+		} finally {
+			this.#isolating.delete(attempt);
 		}
-		this.#registerContext(context);
-		return context;
 	}
 	async create(options) {
 		if (this.#destroyed) throw new BrowserDestroyedError();
@@ -2624,6 +2796,37 @@ var Browser = class {
 		this.#shutdown = shutdown;
 		return shutdown;
 	}
+	async #isolate(options) {
+		if (this.#destroyed) throw new BrowserDestroyedError();
+		const client = this.#client;
+		if (this.#status !== "connected" || client === void 0) throw new BrowserNotConnectedError();
+		validateBrowserContextOptions(options);
+		const params = { disposeOnDetach: false };
+		if (options?.proxy !== void 0) {
+			params["proxyServer"] = options.proxy.server;
+			if (options.proxy.bypass !== void 0) params["proxyBypassList"] = options.proxy.bypass.join(",");
+		}
+		if (options?.origins !== void 0) params["originsWithUniversalNetworkAccess"] = [...options.origins];
+		const result = await client.send("Target.createBrowserContext", params);
+		if (!isRecord(result) || !isString(result["browserContextId"])) throw new BrowserConnectionError("Failed to create isolated browser context");
+		const id = result["browserContextId"];
+		const context = new BrowserContext(client, id, options?.emulation?.viewport ?? this.#options.viewport, createBrowserWriter(), options?.emulation, options?.downloads, options);
+		try {
+			if (this.#destroyed || this.#client !== client) throw new BrowserDestroyedError();
+			if (options?.downloads !== void 0) await client.send("Browser.setDownloadBehavior", {
+				behavior: options.downloads.named === true ? "allowAndName" : "allow",
+				browserContextId: id,
+				downloadPath: options.downloads.path,
+				eventsEnabled: true
+			});
+			if (this.#destroyed || this.#client !== client) throw new BrowserDestroyedError();
+		} catch (error) {
+			await context.close().catch(() => void 0);
+			throw error;
+		}
+		this.#registerContext(context);
+		return context;
+	}
 	async #establish() {
 		const disconnecting = this.#disconnecting.pending;
 		if (disconnecting !== void 0) await disconnecting;
@@ -3097,6 +3300,7 @@ var Browser = class {
 		}
 	}
 	async #settle() {
+		await Promise.allSettled(this.#isolating);
 		await this.#connecting.pending?.catch(() => void 0);
 		await this.#disconnecting.pending?.catch(() => void 0);
 		await this.#settleExit();
@@ -3285,6 +3489,6 @@ var Browser = class {
 	}
 };
 //#endregion
-export { BROWSER_CDP_LIST_PATH, BROWSER_CDP_PROTOCOL, BROWSER_CDP_VERSION_PATH, BROWSER_DEFAULT_CDP_PORT, BROWSER_DEFAULT_HOST, BROWSER_DEVTOOLS_PATTERN, BROWSER_DRAIN_INTERVAL_MS, BROWSER_ENGINE_HINTS, BROWSER_ENV_PATH_KEYS, BROWSER_EXECUTABLE_NAMES, BROWSER_EXECUTABLE_PATHS, BROWSER_FILE_STORE_LIMIT, BROWSER_HEADLESS_ARG, BROWSER_JOURNEY_LOCK_ATTEMPTS, BROWSER_JOURNEY_LOCK_DIRECTORY, BROWSER_JOURNEY_REVISION_FILE, BROWSER_JOURNEY_SNAPSHOT_FILE, BROWSER_KILL_GRACE_MS, BROWSER_LAUNCH_ARGS, BROWSER_PORT_PROBE_TIMEOUT_MS, BROWSER_PROCESS_EXIT_CAUSE, BROWSER_PROFILE_PREFIX, BROWSER_RUN_DIRECTORY, BROWSER_RUN_FILE, BROWSER_SERVER_BUSY, BROWSER_SERVER_COPY, BROWSER_SERVER_CRASH, BROWSER_SERVER_EXHAUSTED, BROWSER_SERVER_HOLDER, BROWSER_SERVER_LAUNCH, BROWSER_SERVER_OPTIONS, BROWSER_SERVER_POOL_LIMIT, BROWSER_SERVER_POOL_SIZE, BROWSER_SERVER_RECORD, BROWSER_SERVER_RESTARTS, BROWSER_SERVER_SWEEP, BROWSER_SERVER_TEARDOWN, BROWSER_SERVER_UNAVAILABLE, BROWSER_SERVER_UNRESOLVED, BROWSER_STORE_CACHE_DIRS, BROWSER_STORE_DEFAULT_DIRS, BROWSER_STORE_ENV_KEY, BROWSER_STORE_GLOBS, BROWSER_STORE_LINK_NAME, BROWSER_TRANSPORT_LOSS_CAUSE, BROWSER_TRANSPORT_LOSS_DEFER_MS, BROWSER_WINDOWS_ROOT_FALLBACKS, BROWSER_WINDOWS_SUFFIXES, Browser, BrowserDestroyedError, BrowserMCPServer, BrowserNotConnectedError, FileBrowserJourneyStore, FileBrowserRunStore, FileBrowserWriter, WebSocketCDPTransport, browserToEngine, buildInstallPaths, buildStoreBases, buildWindowsRoots, createBrowser, createBrowserMCPServer, createBrowserProfile, createBrowserWriter, createCDPTransport, createFileBrowserJourneyStore, createFileBrowserRunStore, describeBrowserServerLoss, fetchCDPTargets, findEnvOverrides, findInstallPaths, findStorePaths, findSystemBrowser, findSystemBrowsers, formatBrowserLockEntry, isBrowserDestroyedError, isBrowserNotConnectedError, launchBrowserProcess, normalizeExecutablePath, parseBrowserEngine, parseBrowserLockEntry, parseBrowserProfileRecord, parseBrowserViewport, probePathNames, probeProcess, readBrowserEndpoint, readFirstLine, removeBrowserProfile };
+export { BROWSER_CDP_LIST_PATH, BROWSER_CDP_PROTOCOL, BROWSER_CDP_VERSION_PATH, BROWSER_DEFAULT_CDP_PORT, BROWSER_DEFAULT_HOST, BROWSER_DEVTOOLS_PATTERN, BROWSER_DRAIN_INTERVAL_MS, BROWSER_ENGINE_HINTS, BROWSER_ENV_PATH_KEYS, BROWSER_EXECUTABLE_NAMES, BROWSER_EXECUTABLE_PATHS, BROWSER_FILE_STORE_LIMIT, BROWSER_HEADLESS_ARG, BROWSER_JOURNEY_LOCK_ATTEMPTS, BROWSER_JOURNEY_LOCK_DIRECTORY, BROWSER_JOURNEY_REVISION_FILE, BROWSER_JOURNEY_SNAPSHOT_FILE, BROWSER_KILL_GRACE_MS, BROWSER_LAUNCH_ARGS, BROWSER_PORT_PROBE_TIMEOUT_MS, BROWSER_PROCESS_EXIT_CAUSE, BROWSER_PROFILE_PREFIX, BROWSER_RUN_DIRECTORY, BROWSER_RUN_FILE, BROWSER_SERVER_BUSY, BROWSER_SERVER_CONTEXTS, BROWSER_SERVER_CONTEXTS_LIMIT, BROWSER_SERVER_COPY, BROWSER_SERVER_CRASH, BROWSER_SERVER_EXHAUSTED, BROWSER_SERVER_HOLDER, BROWSER_SERVER_LAUNCH, BROWSER_SERVER_OPTIONS, BROWSER_SERVER_POOL_LIMIT, BROWSER_SERVER_POOL_SIZE, BROWSER_SERVER_RECORD, BROWSER_SERVER_RESTARTS, BROWSER_SERVER_SWEEP, BROWSER_SERVER_TEARDOWN, BROWSER_SERVER_UNAVAILABLE, BROWSER_SERVER_UNRESOLVED, BROWSER_STORE_CACHE_DIRS, BROWSER_STORE_DEFAULT_DIRS, BROWSER_STORE_ENV_KEY, BROWSER_STORE_GLOBS, BROWSER_STORE_LINK_NAME, BROWSER_TRANSPORT_LOSS_CAUSE, BROWSER_TRANSPORT_LOSS_DEFER_MS, BROWSER_WINDOWS_ROOT_FALLBACKS, BROWSER_WINDOWS_SUFFIXES, Browser, BrowserDestroyedError, BrowserMCPServer, BrowserNotConnectedError, FileBrowserJourneyStore, FileBrowserRunStore, FileBrowserWriter, WebSocketCDPTransport, browserToEngine, buildInstallPaths, buildStoreBases, buildWindowsRoots, createBrowser, createBrowserMCPServer, createBrowserProfile, createBrowserWriter, createCDPTransport, createFileBrowserJourneyStore, createFileBrowserRunStore, describeBrowserServerLoss, fetchCDPTargets, findEnvOverrides, findInstallPaths, findStorePaths, findSystemBrowser, findSystemBrowsers, formatBrowserLockEntry, isBrowserDestroyedError, isBrowserNotConnectedError, launchBrowserProcess, normalizeExecutablePath, parseBrowserEngine, parseBrowserLockEntry, parseBrowserProfileRecord, parseBrowserViewport, probePathNames, probeProcess, readBrowserEndpoint, readFirstLine, removeBrowserProfile };
 
 //# sourceMappingURL=index.js.map