@orkestrel/browser 0.0.22 → 0.0.23

package/dist/src/server/index.d.cts

@@ -1,3 +1,4 @@
+import type { BrowserCallOptions } from '@orkestrel/browser';
 import type { BrowserContextInterface } from '@orkestrel/browser';
 import type { BrowserContextOptions } from '@orkestrel/browser';
 import { BrowserError } from '@orkestrel/browser';
@@ -11,6 +12,7 @@ import type { BrowserRunSlot } from '@orkestrel/browser';
 import type { BrowserRunStoreInterface } from '@orkestrel/browser';
 import type { BrowserStoreOptions } from '@orkestrel/browser';
 import type { BrowserStorePage } from '@orkestrel/browser';
+import type { BrowserToolsetInterface } from '@orkestrel/browser';
 import type { BrowserViewport } from '@orkestrel/browser';
 import type { BrowserWriterInterface } from '@orkestrel/browser';
 import type { CDPTarget } from '@orkestrel/browser';
@@ -46,6 +48,8 @@ export declare class Browser implements BrowserInterface {
     get connection(): BrowserConnection | undefined;
     get owned(): boolean | undefined;
     get pid(): number | undefined;
+    get endpoint(): string | undefined;
+    ping(options?: BrowserCallOptions): Promise<void>;
     discover(): Promise<BrowserDiscoveryResult>;
     connect(): Promise<void>;
     adopt(): void;
@@ -181,6 +185,42 @@ export declare const BROWSER_RUN_DIRECTORY = "runs";
 /** Names the persisted run snapshot. */
 export declare const BROWSER_RUN_FILE = "run.json";
 
+/** Names the notice that a browser and its session state were lost. */
+export declare const BROWSER_SERVER_CRASH = "BROWSER_SERVER_CRASH";
+
+/** Names the diagnostic when the warm floor spends its restart bound. */
+export declare const BROWSER_SERVER_EXHAUSTED = "BROWSER_SERVER_EXHAUSTED";
+
+/** Names a failed attempt to warm a browser. */
+export declare const BROWSER_SERVER_LAUNCH = "BROWSER_SERVER_LAUNCH";
+
+/** Names a refused browser server option. */
+export declare const BROWSER_SERVER_OPTIONS = "BROWSER_SERVER_OPTIONS";
+
+/** Limits the number of warm browsers to 3. */
+export declare const BROWSER_SERVER_POOL_LIMIT = 3;
+
+/** Sets the default number of warm browsers to 1. */
+export declare const BROWSER_SERVER_POOL_SIZE = 1;
+
+/** Names the browser process record in each profile. */
+export declare const BROWSER_SERVER_RECORD = "browse.json";
+
+/** Permits one failed refill before the next failure spends the bound. */
+export declare const BROWSER_SERVER_RESTARTS = 1;
+
+/** Names a failed profile sweep. */
+export declare const BROWSER_SERVER_SWEEP = "BROWSER_SERVER_SWEEP";
+
+/** Names a failed browser server teardown. */
+export declare const BROWSER_SERVER_TEARDOWN = "BROWSER_SERVER_TEARDOWN";
+
+/** Names the refusal when no browser can serve a call. */
+export declare const BROWSER_SERVER_UNAVAILABLE = "BROWSER_SERVER_UNAVAILABLE";
+
+/** Names an interrupted call whose outcome is unknown. */
+export declare const BROWSER_SERVER_UNRESOLVED = "BROWSER_SERVER_UNRESOLVED";
+
 /** Names the per-OS default Playwright browser cache directory, relative to the home directory (win32 uses `LOCALAPPDATA` directly). */
 export declare const BROWSER_STORE_CACHE_DIRS: Readonly<Record<string, string>>;
 
@@ -237,7 +277,7 @@ export declare const BROWSER_WINDOWS_SUFFIXES: readonly string[];
  * - `endpoint` — explicit CDP WebSocket URL; when provided, skips discovery
  * - `discover` — whether `connect()` passively probes for an existing browser
  *   before launching (default `true`); set `false` to skip discovery and go
- *   straight to launch — a short probe of `port` still runs first and rejects
+ *   straight to launch — when `port` is explicit, a short probe runs first and rejects
  *   with a coded error naming the occupied port if something is already
  *   listening there, so a demanded fresh launch never silently attaches to a
  *   stranger browser
@@ -355,6 +395,10 @@ export declare type BrowserEventMap = {
  * - `create(options?)` → shortcut to open a page in the default context
  */
 export declare interface BrowserInterface {
+    /** Reports the CDP WebSocket endpoint of the represented session, or undefined when none is. */
+    readonly endpoint: string | undefined;
+    /** Sends CDP `Browser.getVersion` and resolves when the browser answers, changing no state. */
+    ping(options?: BrowserCallOptions): Promise<void>;
     readonly emitter: EmitterInterface<BrowserEventMap>;
     readonly engine: BrowserEngine;
     readonly status: BrowserStatus;
@@ -435,7 +479,7 @@ export declare interface BrowserInterface {
 }
 
 /**
- * Creates the browser a browse server connects on its first tool call.
+ * Creates a browser a browse server connects while warming its pool.
  *
  * @param options - The launch the server composes: `headless`, `executable`, the profile it
  *   owns, `cdp.discover` set to `false`, and the signal its `destroy()` aborts
@@ -445,7 +489,7 @@ export declare type BrowserLaunchFunction = (options: BrowserOptions) => Browser
 
 /**
  * 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`, `plain`,
@@ -455,18 +499,22 @@ export declare type BrowserLaunchFunction = (options: BrowserOptions) => Browser
  * 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
@@ -496,13 +544,14 @@ export declare class BrowserMCPServer implements BrowserMCPServerInterface {
 /** Serves the browser vocabulary and the journey tools over MCP on stdio. */
 export declare interface BrowserMCPServerInterface {
     /**
-     * Serves the tool list over stdio before Chromium starts; the first tool call launches Chromium
-     * with a profile the server owns.
+     * Serves stdio, sweeps the profiles ended servers left, warms the pool, and resolves after the
+     * session leases a warm browser; the legacy handshake and every tool call await the same setup.
+     * Rejects with `BROWSER_SERVER_UNAVAILABLE` when no browser can serve and with
+     * `BROWSER_TOOLSET_ENDED` after `destroy()`, and resolves when `destroy()` interrupts setup.
      */
     start(): Promise<void>;
     /**
-     * Stops admission, aborts the active replay, destroys the toolset and the browser it launched,
-     * and removes its profile.
+     * Stops admission, tears down every browser, its toolset, and its profile, then rechecks the folders it answers for.
      */
     destroy(): Promise<void>;
 }
@@ -517,11 +566,15 @@ export declare interface BrowserMCPServerInterface {
  *   `true`
  * - `executable` — the path of the Chromium executable the server launches. Default: the browser
  *   `findSystemBrowser` finds
- * - `readonly` — if `true`, refuses `record`, `save`, and `edit`, and `replay` still writes runs;
+ * - `readonly` — if `true`, refuses `record`, `save`, `edit`, and `forget`, and `replay` still writes runs;
  *   if `false` or omitted, every tool runs
- * - `launch` — creates the browser the first tool call connects. Default: `createBrowser`
+ * - `launch` — creates each browser the pool warms. Default: `createBrowser`
  * - `stdio` — the streams the server reads requests from and writes answers to; the end of
  *   `input` destroys the server. Default: `process.stdin` and `process.stdout`
+ * - `pool.size` — the integer number of browsers kept warm, from 1 through
+ *   `BROWSER_SERVER_POOL_LIMIT`. Default: `BROWSER_SERVER_POOL_SIZE`.
+ * - `log` — receives diagnostic lines. Default: `process.stderr`
+ * @throws Thrown when `pool.size` is outside that range or is not an integer, with `BROWSER_SERVER_OPTIONS`
  */
 export declare interface BrowserMCPServerOptions {
     readonly root?: string;
@@ -530,6 +583,10 @@ export declare interface BrowserMCPServerOptions {
     readonly readonly?: boolean;
     readonly launch?: BrowserLaunchFunction;
     readonly stdio?: StdioServerOptions;
+    readonly pool?: {
+        readonly size?: number;
+    };
+    readonly log?: NodeJS.WritableStream;
 }
 
 /**
@@ -577,6 +634,12 @@ export declare interface BrowserOptions {
     readonly browsers?: SystemBrowserOptions;
 }
 
+/** Names the browser a browse profile serves, which a later start's sweep reads. */
+export declare interface BrowserProfileRecord {
+    readonly pid: number;
+    readonly endpoint: string;
+}
+
 /**
  * Describes the resolved browser profile directory used for a Chromium-family launch.
  *
@@ -590,6 +653,23 @@ export declare interface BrowserProfileResult {
     readonly temporary: boolean;
 }
 
+/** Holds one warm browser a browse server owns: the browser, its profile, its isolated context, and its started toolset. */
+export declare interface BrowserSlot {
+    readonly browser: BrowserInterface;
+    readonly profile: string;
+    readonly context: BrowserContextInterface;
+    readonly toolset: BrowserToolsetInterface;
+}
+
+/** Holds the listeners and resolver of one browser slot's loss watch. */
+export declare interface BrowserSlotWatch {
+    readonly resolve: (cause: unknown) => void;
+    readonly disconnect: () => void;
+    readonly page: (page: BrowserPageInterface) => void;
+    readonly crashes: ReadonlyMap<BrowserPageInterface, () => void>;
+    readonly subscription: Disposable;
+}
+
 /** Names the lifecycle status of a browser wrapper. */
 export declare type BrowserStatus = 'idle' | 'connecting' | 'connected' | 'disconnected' | 'error';
 
@@ -628,7 +708,7 @@ export declare function createBrowser(options?: BrowserOptions): BrowserInterfac
 
 /**
  * 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()`
@@ -638,7 +718,7 @@ export declare function createBrowser(options?: BrowserOptions): BrowserInterfac
  * 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()
  * ```
  */
@@ -686,6 +766,17 @@ export declare function createFileBrowserJourneyStore(options: FileBrowserStoreO
  */
 export declare function createFileBrowserRunStore(options: FileBrowserStoreOptions): BrowserRunStoreInterface;
 
+/**
+ * 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'))
+ */
+export declare function describeBrowserServerLoss(code: string, cause: unknown, url?: string): string;
+
 /**
  * Fetches the current CDP target list from a browser's `/json/list` endpoint, as a `Result`
  * carrying either the targets or a coded `BrowserConnectionError`.
@@ -903,9 +994,27 @@ export declare function parseBrowserEngine(executable: string): BrowserEngine |
  */
 export declare function parseBrowserLockEntry(name: string): number | undefined;
 
+/**
+ * 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"}')
+ */
+export declare function parseBrowserProfileRecord(text: string): BrowserProfileRecord | undefined;
+
 /** Probes PATH (`which`/`where`) for every resolvable command name, in the given order. */
 export declare function probePathNames(names: readonly string[], platform: string): readonly string[];
 
+/**
+ * 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
+ */
+export declare function probeProcess(pid: number): boolean;
+
 /**
  * Reads the CDP endpoint a launched browser announces on its standard error.
  *

package/dist/src/server/index.d.ts

@@ -1,3 +1,4 @@
+import type { BrowserCallOptions } from '@orkestrel/browser';
 import type { BrowserContextInterface } from '@orkestrel/browser';
 import type { BrowserContextOptions } from '@orkestrel/browser';
 import { BrowserError } from '@orkestrel/browser';
@@ -11,6 +12,7 @@ import type { BrowserRunSlot } from '@orkestrel/browser';
 import type { BrowserRunStoreInterface } from '@orkestrel/browser';
 import type { BrowserStoreOptions } from '@orkestrel/browser';
 import type { BrowserStorePage } from '@orkestrel/browser';
+import type { BrowserToolsetInterface } from '@orkestrel/browser';
 import type { BrowserViewport } from '@orkestrel/browser';
 import type { BrowserWriterInterface } from '@orkestrel/browser';
 import type { CDPTarget } from '@orkestrel/browser';
@@ -46,6 +48,8 @@ export declare class Browser implements BrowserInterface {
     get connection(): BrowserConnection | undefined;
     get owned(): boolean | undefined;
     get pid(): number | undefined;
+    get endpoint(): string | undefined;
+    ping(options?: BrowserCallOptions): Promise<void>;
     discover(): Promise<BrowserDiscoveryResult>;
     connect(): Promise<void>;
     adopt(): void;
@@ -181,6 +185,42 @@ export declare const BROWSER_RUN_DIRECTORY = "runs";
 /** Names the persisted run snapshot. */
 export declare const BROWSER_RUN_FILE = "run.json";
 
+/** Names the notice that a browser and its session state were lost. */
+export declare const BROWSER_SERVER_CRASH = "BROWSER_SERVER_CRASH";
+
+/** Names the diagnostic when the warm floor spends its restart bound. */
+export declare const BROWSER_SERVER_EXHAUSTED = "BROWSER_SERVER_EXHAUSTED";
+
+/** Names a failed attempt to warm a browser. */
+export declare const BROWSER_SERVER_LAUNCH = "BROWSER_SERVER_LAUNCH";
+
+/** Names a refused browser server option. */
+export declare const BROWSER_SERVER_OPTIONS = "BROWSER_SERVER_OPTIONS";
+
+/** Limits the number of warm browsers to 3. */
+export declare const BROWSER_SERVER_POOL_LIMIT = 3;
+
+/** Sets the default number of warm browsers to 1. */
+export declare const BROWSER_SERVER_POOL_SIZE = 1;
+
+/** Names the browser process record in each profile. */
+export declare const BROWSER_SERVER_RECORD = "browse.json";
+
+/** Permits one failed refill before the next failure spends the bound. */
+export declare const BROWSER_SERVER_RESTARTS = 1;
+
+/** Names a failed profile sweep. */
+export declare const BROWSER_SERVER_SWEEP = "BROWSER_SERVER_SWEEP";
+
+/** Names a failed browser server teardown. */
+export declare const BROWSER_SERVER_TEARDOWN = "BROWSER_SERVER_TEARDOWN";
+
+/** Names the refusal when no browser can serve a call. */
+export declare const BROWSER_SERVER_UNAVAILABLE = "BROWSER_SERVER_UNAVAILABLE";
+
+/** Names an interrupted call whose outcome is unknown. */
+export declare const BROWSER_SERVER_UNRESOLVED = "BROWSER_SERVER_UNRESOLVED";
+
 /** Names the per-OS default Playwright browser cache directory, relative to the home directory (win32 uses `LOCALAPPDATA` directly). */
 export declare const BROWSER_STORE_CACHE_DIRS: Readonly<Record<string, string>>;
 
@@ -237,7 +277,7 @@ export declare const BROWSER_WINDOWS_SUFFIXES: readonly string[];
  * - `endpoint` — explicit CDP WebSocket URL; when provided, skips discovery
  * - `discover` — whether `connect()` passively probes for an existing browser
  *   before launching (default `true`); set `false` to skip discovery and go
- *   straight to launch — a short probe of `port` still runs first and rejects
+ *   straight to launch — when `port` is explicit, a short probe runs first and rejects
  *   with a coded error naming the occupied port if something is already
  *   listening there, so a demanded fresh launch never silently attaches to a
  *   stranger browser
@@ -355,6 +395,10 @@ export declare type BrowserEventMap = {
  * - `create(options?)` → shortcut to open a page in the default context
  */
 export declare interface BrowserInterface {
+    /** Reports the CDP WebSocket endpoint of the represented session, or undefined when none is. */
+    readonly endpoint: string | undefined;
+    /** Sends CDP `Browser.getVersion` and resolves when the browser answers, changing no state. */
+    ping(options?: BrowserCallOptions): Promise<void>;
     readonly emitter: EmitterInterface<BrowserEventMap>;
     readonly engine: BrowserEngine;
     readonly status: BrowserStatus;
@@ -435,7 +479,7 @@ export declare interface BrowserInterface {
 }
 
 /**
- * Creates the browser a browse server connects on its first tool call.
+ * Creates a browser a browse server connects while warming its pool.
  *
  * @param options - The launch the server composes: `headless`, `executable`, the profile it
  *   owns, `cdp.discover` set to `false`, and the signal its `destroy()` aborts
@@ -445,7 +489,7 @@ export declare type BrowserLaunchFunction = (options: BrowserOptions) => Browser
 
 /**
  * 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`, `plain`,
@@ -455,18 +499,22 @@ export declare type BrowserLaunchFunction = (options: BrowserOptions) => Browser
  * 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
@@ -496,13 +544,14 @@ export declare class BrowserMCPServer implements BrowserMCPServerInterface {
 /** Serves the browser vocabulary and the journey tools over MCP on stdio. */
 export declare interface BrowserMCPServerInterface {
     /**
-     * Serves the tool list over stdio before Chromium starts; the first tool call launches Chromium
-     * with a profile the server owns.
+     * Serves stdio, sweeps the profiles ended servers left, warms the pool, and resolves after the
+     * session leases a warm browser; the legacy handshake and every tool call await the same setup.
+     * Rejects with `BROWSER_SERVER_UNAVAILABLE` when no browser can serve and with
+     * `BROWSER_TOOLSET_ENDED` after `destroy()`, and resolves when `destroy()` interrupts setup.
      */
     start(): Promise<void>;
     /**
-     * Stops admission, aborts the active replay, destroys the toolset and the browser it launched,
-     * and removes its profile.
+     * Stops admission, tears down every browser, its toolset, and its profile, then rechecks the folders it answers for.
      */
     destroy(): Promise<void>;
 }
@@ -517,11 +566,15 @@ export declare interface BrowserMCPServerInterface {
  *   `true`
  * - `executable` — the path of the Chromium executable the server launches. Default: the browser
  *   `findSystemBrowser` finds
- * - `readonly` — if `true`, refuses `record`, `save`, and `edit`, and `replay` still writes runs;
+ * - `readonly` — if `true`, refuses `record`, `save`, `edit`, and `forget`, and `replay` still writes runs;
  *   if `false` or omitted, every tool runs
- * - `launch` — creates the browser the first tool call connects. Default: `createBrowser`
+ * - `launch` — creates each browser the pool warms. Default: `createBrowser`
  * - `stdio` — the streams the server reads requests from and writes answers to; the end of
  *   `input` destroys the server. Default: `process.stdin` and `process.stdout`
+ * - `pool.size` — the integer number of browsers kept warm, from 1 through
+ *   `BROWSER_SERVER_POOL_LIMIT`. Default: `BROWSER_SERVER_POOL_SIZE`.
+ * - `log` — receives diagnostic lines. Default: `process.stderr`
+ * @throws Thrown when `pool.size` is outside that range or is not an integer, with `BROWSER_SERVER_OPTIONS`
  */
 export declare interface BrowserMCPServerOptions {
     readonly root?: string;
@@ -530,6 +583,10 @@ export declare interface BrowserMCPServerOptions {
     readonly readonly?: boolean;
     readonly launch?: BrowserLaunchFunction;
     readonly stdio?: StdioServerOptions;
+    readonly pool?: {
+        readonly size?: number;
+    };
+    readonly log?: NodeJS.WritableStream;
 }
 
 /**
@@ -577,6 +634,12 @@ export declare interface BrowserOptions {
     readonly browsers?: SystemBrowserOptions;
 }
 
+/** Names the browser a browse profile serves, which a later start's sweep reads. */
+export declare interface BrowserProfileRecord {
+    readonly pid: number;
+    readonly endpoint: string;
+}
+
 /**
  * Describes the resolved browser profile directory used for a Chromium-family launch.
  *
@@ -590,6 +653,23 @@ export declare interface BrowserProfileResult {
     readonly temporary: boolean;
 }
 
+/** Holds one warm browser a browse server owns: the browser, its profile, its isolated context, and its started toolset. */
+export declare interface BrowserSlot {
+    readonly browser: BrowserInterface;
+    readonly profile: string;
+    readonly context: BrowserContextInterface;
+    readonly toolset: BrowserToolsetInterface;
+}
+
+/** Holds the listeners and resolver of one browser slot's loss watch. */
+export declare interface BrowserSlotWatch {
+    readonly resolve: (cause: unknown) => void;
+    readonly disconnect: () => void;
+    readonly page: (page: BrowserPageInterface) => void;
+    readonly crashes: ReadonlyMap<BrowserPageInterface, () => void>;
+    readonly subscription: Disposable;
+}
+
 /** Names the lifecycle status of a browser wrapper. */
 export declare type BrowserStatus = 'idle' | 'connecting' | 'connected' | 'disconnected' | 'error';
 
@@ -628,7 +708,7 @@ export declare function createBrowser(options?: BrowserOptions): BrowserInterfac
 
 /**
  * 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()`
@@ -638,7 +718,7 @@ export declare function createBrowser(options?: BrowserOptions): BrowserInterfac
  * 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()
  * ```
  */
@@ -686,6 +766,17 @@ export declare function createFileBrowserJourneyStore(options: FileBrowserStoreO
  */
 export declare function createFileBrowserRunStore(options: FileBrowserStoreOptions): BrowserRunStoreInterface;
 
+/**
+ * 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'))
+ */
+export declare function describeBrowserServerLoss(code: string, cause: unknown, url?: string): string;
+
 /**
  * Fetches the current CDP target list from a browser's `/json/list` endpoint, as a `Result`
  * carrying either the targets or a coded `BrowserConnectionError`.
@@ -903,9 +994,27 @@ export declare function parseBrowserEngine(executable: string): BrowserEngine |
  */
 export declare function parseBrowserLockEntry(name: string): number | undefined;
 
+/**
+ * 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"}')
+ */
+export declare function parseBrowserProfileRecord(text: string): BrowserProfileRecord | undefined;
+
 /** Probes PATH (`which`/`where`) for every resolvable command name, in the given order. */
 export declare function probePathNames(names: readonly string[], platform: string): readonly string[];
 
+/**
+ * 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
+ */
+export declare function probeProcess(pid: number): boolean;
+
 /**
  * Reads the CDP endpoint a launched browser announces on its standard error.
  *