prismcast 1.10.3 → 1.11.0

package/dist/browser/index.js

@@ -1,4 +1,4 @@
-import { LOG, cancellableTimeout, delay, evaluateWithAbort, formatError, isProcessRunning, listProcesses, startTimer } from "../utils/index.js";
+import { LOG, boundedWait, delay, evaluateWithAbort, formatError, isProcessRunning, listProcesses, realClock, startTimer } from "../utils/index.js";
 import { clearLoginState, isLoginModeActive, setBrowserAccessors } from "./login.js";
 import { getAllStreams, getStreamCount } from "../streaming/registry.js";
 import { getChromeDataDir, getDataDir, getExtensionDir } from "../config/paths.js";
@@ -8,7 +8,9 @@ import { getGpuCapabilities, setBrowserChrome, setGpuCapabilities, setMaxSupport
 import { resizeAndMinimizeWindow, unminimizeWindow } from "./cdp.js";
 import { CONFIG } from "../config/index.js";
 import { clearChannelSelectionCaches } from "./channelSelection.js";
+import { createBrowserSupervisor } from "./browserSupervisor.js";
 import { emitSystemStatusChanged } from "../streaming/statusEmitter.js";
+import { evaluateStalePages } from "./pageStaleness.js";
 import fs from "node:fs";
 import path from "node:path";
 import { launch as puppeteerLaunch } from "puppeteer-core";
@@ -19,27 +21,101 @@ const { promises: fsPromises } = fs;
 /* Global variables maintain the application's runtime state across all operations. We minimize global state where possible, but some values must be shared across
  * the application lifecycle:
  *
- * - currentBrowser: The shared browser instance. All streaming sessions use a single Chrome process to avoid the overhead of launching multiple browsers. This is
- *   created on first stream request (or during warmup) and persists until the application shuts down or the browser crashes.
+ * - supervisor: The browser capture-readiness supervisor. It is the single source of truth for the shared Chrome instance and its lifecycle (absent / launching /
+ *   ready / degraded / trialing), so all streaming sessions use one Chrome process via supervisor.acquire(). It holds one discriminated-union lifecycle state that
+ *   captures the browser reference, its launch timestamp, and whether a launch is in flight, and routes every relaunch through one loop-safe governor.
  *
- * - dataDir: The filesystem location for persistent data (Chrome profile, extension files). Resolved via config/paths.ts, which is created on startup if it doesn't
- *   exist.
+ * - currentChromeVersion: The one piece of per-browser metadata the adapter holds directly, captured when the browser becomes ready and surfaced by the
+ *   health endpoint.
  *
- * Stream tracking and ID generation live in streaming/registry.ts for unified stream management across all output types (HLS, MPEG-TS, etc.).
+ * Stream tracking and ID generation live in streaming/registry.ts for unified stream management across all output types (HLS, MPEG-TS, etc.). Filesystem path
+ * resolution for persistent data (the Chrome profile and the streaming extension files) is centralized in config/paths.ts, whose getters create the data directory on
+ * startup if it does not exist; it is resolved on demand rather than held as module state here.
  */
-// The shared browser instance used by all streaming sessions. Created on first stream request or during warmup. Set to null when the browser is not running or
-// has disconnected.
-let currentBrowser = null;
-// The Chrome version string (e.g., "Chrome/144.0.7559.110") captured when the browser launches. Cleared when the browser disconnects. Used by the
-// health endpoint to report the active Chrome version.
+// The Chrome version string (e.g., "Chrome/144.0.7559.110") captured when the browser becomes capture-ready in launchReadyBrowser. Cleared when the browser
+// disconnects or is closed. This is the one piece of per-browser metadata the adapter holds directly; the browser instance, its launch timestamp, and the
+// launch mutex live inside the supervisor's lifecycle state, which is the single source of truth for "what is the browser doing, and is it usable?".
 let currentChromeVersion = null;
-// Timestamp (Date.now()) when the current browser instance was launched. Used by the opportunistic restart check to determine browser age. Cleared when the
-// browser disconnects.
-let browserLaunchTime = null;
-// Launch mutex. When a browser launch is in progress, this holds the pending promise so that concurrent callers piggyback on the same launch instead of
-// starting a second Chrome process. Cleared in a finally block once the launch settles.
-let browserLaunchPromise = null;
-// The data directory stores Chrome's profile data and the streaming extension files. Path resolution is centralized in config/paths.ts.
+/* The browser relaunch governor's escalating cooldown ladder: 5 minutes, then 15, then 60. This is the escalation SHAPE - a design constant - rather than an
+ * operational tolerance, so it stays in code while the scalar tolerances (failure threshold, window, health hold) are operator-tunable via CONFIG.recovery. Each
+ * successive trip cools down for the next-longer rung; the final rung is the ceiling.
+ */
+const RELAUNCH_COOLDOWN_LADDER_MS = [5 * 60 * 1000, 15 * 60 * 1000, 60 * 60 * 1000];
+/* How long Chrome is given to exit after SIGTERM, and then after SIGKILL. The escalation is SIGTERM-first so Chrome can flush its profile databases (LevelDB,
+ * extension state, session storage) instead of having them corrupted by an immediate kill, and the SIGTERM window is generous because containerized environments
+ * with software rendering and shared CPU may need all of it. Every path that signals Chrome - the orderly close of a running instance and the startup sweep of
+ * stale ones - shares this pair, so the escalation behaves identically wherever it runs.
+ */
+const TERM_WAIT_MS = 5000;
+const KILL_WAIT_MS = 2000;
+/* The worst case a browser teardown can take before the Chrome process is certainly gone. The supervisor's closing state hands this to requests that arrive
+ * mid-drain as their retry horizon, so it is derived from the waits above rather than restated: the bound cannot drift from what the teardown actually allows.
+ */
+const BROWSER_TEARDOWN_DRAIN_BOUND_MS = TERM_WAIT_MS + KILL_WAIT_MS;
+/**
+ * Builds the browser relaunch governor's policy from live configuration. The supervisor's policy port is a getter, so this is read fresh at each governor decision -
+ * an operator's change to the recovery.relaunch* settings takes effect without reconstructing the supervisor (and a deferred config reload that restarts the server
+ * applies it too). The scalar tolerances come from CONFIG.recovery (conservative, biased eager-for-the-first-failure: the first failures cost no cooldown; only
+ * repeated failures within the window trip the escalating cooldown); the cooldown ladder is the fixed escalation shape above.
+ * @returns The current launch governor policy.
+ */
+function buildRelaunchPolicy() {
+    return {
+        cooldownLadderMs: RELAUNCH_COOLDOWN_LADDER_MS,
+        failureThreshold: CONFIG.recovery.relaunchFailureThreshold,
+        failureWindowMs: CONFIG.recovery.relaunchFailureWindow,
+        healthHoldMs: CONFIG.recovery.relaunchHealthHold
+    };
+}
+/* The one browser capture-readiness supervisor for the process lifetime. It owns the lifecycle state (absent/launching/ready/degraded/trialing) that unifies the
+ * browser reference, launch promise, and launch timestamp, and routes every relaunch through one loop-safe governor. The adapter injects the impure
+ * ports: launchReadyBrowser (spawn Chrome and run the readiness gate), closeBrowserInstance (teardown), realClock.now (time), buildRelaunchPolicy (live config
+ * bounds), and onSupervisorStateChange (the loud degraded alarm and the recovery notice). All browser access flows through it: getCurrentBrowser is acquire(); the
+ * non-launching reads derive from current() and currentLaunchTime(). The injected ports are hoisted function declarations, so referencing them here is safe even
+ * though they are defined further down the module.
+ */
+const supervisor = createBrowserSupervisor({ close: closeBrowserInstance, launch: launchReadyBrowser, now: realClock.now, onStateChange: onSupervisorStateChange,
+    policy: buildRelaunchPolicy });
+/**
+ * Observes supervisor lifecycle transitions purely for operator-visible signals; it never affects the transition (the supervisor treats it as best-effort, so a
+ * throwing logger cannot corrupt the lifecycle). It raises the loud degraded alarm when the relaunch governor trips, an info notice when capture readiness is
+ * restored after a degraded period, and emits the SSE system status whenever a ready browser is published.
+ * @param next - The state being entered.
+ * @param previous - The state being left.
+ */
+function onSupervisorStateChange(next, previous) {
+    // The governor just tripped: relaunches are paused while the browser's capture system cools down. We log loudly at ERROR with the cooldown horizon so the
+    // condition is never invisible - the enforceable form of "it is impossible to be silently un-tunable."
+    if ((next.kind === "degraded") && (previous.kind !== "degraded")) {
+        const cooldownMinutes = Math.max(1, Math.round((next.until - realClock.now()) / 60000));
+        LOG.error("The browser capture system has degraded and the relaunch governor has tripped: %s Relaunches are paused for approximately %d minute(s) while it " +
+            "cools down; new stream requests will receive a 503 back-off until it recovers.", next.reason, cooldownMinutes);
+    }
+    else if ((next.kind === "ready") && ((previous.kind === "trialing") || (previous.kind === "degraded"))) {
+        // Capture readiness was restored by a successful trial after a degraded period. The ordinary first launch (absent -> launching -> ready) is intentionally
+        // silent; only a recovery from trialing/degraded is worth an operator notice.
+        LOG.info("The browser capture system has recovered and is serving captures again.");
+    }
+    // The browser's connectivity is part of the SSE system status, so emit when a ready browser is published. Readiness-loss emits are owned by handleBrowserDisconnect
+    // (genuine disconnect) and the shutdown path; emitSystemStatusChanged dedupes, so a redundant emit is a cheap no-op.
+    if (next.kind === "ready") {
+        void emitCurrentSystemStatus();
+    }
+}
+/* The capture-readiness probe (capability tier of the launch gate). Null until streaming/setup.ts injects the real getStream probe at module load, which the import
+ * order guarantees runs before any launch: app.ts imports the streaming layer, whose module bodies evaluate during import resolution, before startServer's warm-up.
+ * launchReadyBrowser refuses to publish a browser if it is somehow still null (see the call site), rather than serving an unverified one.
+ */
+let captureProbe = null;
+/**
+ * Injects the capture-readiness probe used as the capability tier of the launch gate. Called once from streaming/setup.ts at module load (which always precedes any
+ * launch, since the streaming layer is imported during server startup). Separating the wiring from the call keeps browser/index.ts free of a streaming-layer import.
+ * @param probe - The probe to run against a freshly-launched browser; it resolves when the browser can capture and rejects otherwise (or exits the process for the
+ *   unrecoverable stale-mutex case).
+ */
+export function setCaptureProbe(probe) {
+    captureProbe = probe;
+}
 // The stale page cleanup interval handle, stored so we can clear it during graceful shutdown. The interval periodically checks for browser pages that are not
 // associated with active streams and closes them to prevent resource exhaustion.
 let stalePageCleanupInterval = null;
@@ -52,7 +128,7 @@ const BROWSER_MAX_AGE = 6 * 60 * 60 * 1000;
 // Duration of the quiet period (zero streams) required before executing the restart (5 minutes).
 const BROWSER_RESTART_QUIET_PERIOD = 5 * 60 * 1000;
 // How often to check whether the browser qualifies for a restart (30 seconds).
-const BROWSER_RESTART_CHECK_INTERVAL = 30_000;
+const BROWSER_RESTART_CHECK_INTERVAL = 30000;
 // Timer handle for the quiet period countdown. When set, the browser has exceeded BROWSER_MAX_AGE and we are waiting for BROWSER_RESTART_QUIET_PERIOD to
 // elapse with zero active streams. Cancelled if a stream starts during the quiet period.
 let restartQuietTimer = null;
@@ -90,10 +166,20 @@ const managedPageIds = new Set();
 // Map from page ID to timestamp when a page was first observed as potentially stale (not associated with an active stream). Pages must remain in this state for
 // the configured grace period before being closed. This prevents race conditions where pages are briefly untracked during initialization or cleanup transitions.
 const potentiallyStalePages = new Map();
+/* Set of IDs for pages that stream setup created and whose ownership the stream registry does not yet record. Setup writes the registry's page reference only once
+ * it completes, which on a slow tune is long enough for the cleanup walk to see the page as unowned and close it out from under the setup driving it; membership
+ * here exempts the page from staleness for exactly that window. An entry leaves the set when unregisterManagedPage releases the page as setup tears it down, when
+ * the cleanup walk sees the registry record the ownership the mark stood in for, and when clearPageTracking wipes the collections at the end of a browser session.
+ */
+const inFlightSetupPageIds = new Set();
 // Login mode management. State and functions live in login.ts; re-exported here so existing consumers don't need import path changes. clearLoginState,
 // isLoginModeActive, and setBrowserAccessors are imported above; the first two for internal use, setBrowserAccessors for one-time initialization below.
 export { clearLoginState, isLoginModeActive };
-export { endLoginMode, getLoginPage, getLoginStatus, startLoginMode } from "./login.js";
+export { endLoginMode, getLoginPage, getLoginStatus, setLoginModeEndObserver, startLoginMode } from "./login.js";
+// Re-export the supervisor's acquire() rejection classes through the browser surface so the stream-setup layer can map them to a 503 back-off without reaching into
+// the supervisor module directly. Both signal a transient "retry me" condition: BrowserUnavailableError while the relaunch governor is cooling, BrowserSupersededError
+// when a launch was abandoned mid-flight by a readiness-loss.
+export { BrowserSupersededError, BrowserUnavailableError } from "./browserSupervisor.js";
 // Inject browser accessors into the login module. This breaks the circular dependency (login needs getBrowserInstance/minimizeBrowserWindow, index needs login
 // functions) using the same setter/getter pattern as setChromeUserAgent in chromeFetch.ts. Function declarations are hoisted, so both accessors are available here.
 setBrowserAccessors({ getBrowserInstance, minimizeBrowserWindow });
@@ -102,9 +188,12 @@ setBrowserAccessors({ getBrowserInstance, minimizeBrowserWindow });
  */
 export async function emitCurrentSystemStatus() {
     let pageCount = 0;
+    // The published browser, or null when the supervisor is not in its ready state. Connectivity and page count derive from it - there is no separate browser
+    // reference to consult.
+    const browser = supervisor.current();
     try {
-        if (currentBrowser?.connected) {
-            const pages = await currentBrowser.pages();
+        if (browser?.connected) {
+            const pages = await browser.pages();
             pageCount = pages.length;
         }
     }
@@ -114,7 +203,7 @@ export async function emitCurrentSystemStatus() {
     const memUsage = process.memoryUsage();
     const status = {
         browser: {
-            connected: !!currentBrowser && currentBrowser.connected,
+            connected: !!browser && browser.connected,
             pageCount
         },
         memory: {
@@ -136,14 +225,20 @@ export async function emitCurrentSystemStatus() {
  * Each registered page receives a unique ID that persists for the page's lifetime. This ID is used for comparison and staleness tracking, avoiding potential
  * issues with Page object reference identity.
  * @param page - The Puppeteer Page to register.
+ * @param options - Registration options. Set inFlightSetup when stream setup owns the page but has not yet recorded that ownership in the stream registry, so the
+ *   stale page cleanup never closes a page whose stream is still being established.
  */
-export function registerManagedPage(page) {
+export function registerManagedPage(page, options = {}) {
     // Generate a unique ID for this page.
     const pageId = "page-" + String(++managedPageIdCounter);
     // Associate the Page object with its ID.
     pageToId.set(page, pageId);
     // Track the ID as managed.
     managedPageIds.add(pageId);
+    // Exempt the page from staleness for as long as its stream setup is in flight.
+    if (options.inFlightSetup) {
+        inFlightSetupPageIds.add(pageId);
+    }
 }
 /**
  * Unregisters a page from PrismCast's management. This should be called when a page is being closed intentionally (during stream cleanup). Unregistering prevents the
@@ -156,6 +251,8 @@ export function unregisterManagedPage(page) {
         managedPageIds.delete(pageId);
         // Also remove from potentially stale tracking since we're intentionally closing it.
         potentiallyStalePages.delete(pageId);
+        // Release any in-flight setup mark. The page is leaving our management, so the exemption it carried has nothing left to protect.
+        inFlightSetupPageIds.delete(pageId);
         // Note: We don't delete from pageToId because WeakMap handles cleanup automatically when the Page is garbage collected.
     }
 }
@@ -167,6 +264,18 @@ export function unregisterManagedPage(page) {
 function getManagedPageId(page) {
     return pageToId.get(page);
 }
+/**
+ * Discards every page-tracking collection. The ids they hold are scoped to one browser session's pages, so they mean nothing once that session ends and would
+ * otherwise carry into the next one - which matters most for the scheduled restart, where the process lives on across the swap. Every path that ends a PUBLISHED
+ * browser session routes through here, which is why the collections are cleared in one place rather than at each of those paths. A launch that is superseded
+ * before it is ever published does not, and needs no clear: it never held stream pages, and its readiness-gate probe pages are released at their own registration
+ * sites. The WeakMap needs no clear - it releases its entries when the Page objects are collected.
+ */
+function clearPageTracking() {
+    managedPageIds.clear();
+    potentiallyStalePages.clear();
+    inFlightSetupPageIds.clear();
+}
 /**
  * Ensures the data directory exists, creating it if necessary. This should be called during application startup before any operations that depend on the data
  * directory (like browser launch or extension preparation).
@@ -244,9 +353,8 @@ function syncSleep(ms) {
  * rely on an in-memory flag; the parent-child relationship in the OS process table IS the ownership proof, which means this function is safe to call from any
  * code path, including from a rejected-duplicate startup's exit handler.
  *
- * Why ownership matters. A duplicate PrismCast that the instance guard rejects must NOT signal Chrome that belongs to the legitimate holder. With PID-based
- * cleanup the only defense was an in-memory ownsChromeCleanup flag set at startup. With process-table discovery, the OS itself tells us who owns what: a Chrome
- * whose ppid is a live unrelated PID belongs to that parent, not to us.
+ * Why ownership matters. A duplicate PrismCast that the instance guard rejects must NOT signal Chrome that belongs to the legitimate holder. Process-table
+ * discovery lets the OS itself tell us who owns what: a Chrome whose ppid is a live unrelated PID belongs to that parent, not to us.
  * @param processes - The current process table snapshot.
  * @param profileDir - The Chrome user-data-dir to match against.
  * @param ownPid - The current process's PID (anything whose parent is us is ours to kill).
@@ -299,9 +407,6 @@ export function killStaleChrome() {
             // databases, poisoning the Docker volume for subsequent restarts.
             process.kill(pid, "SIGTERM");
             LOG.debug("browser:lifecycle", "Sent SIGTERM to Chrome process %d.", pid);
-            // Wait up to 5 seconds for Chrome to flush its databases and exit after SIGTERM. Containerized environments with software rendering and shared CPU may
-            // need the full window.
-            const TERM_WAIT_MS = 5000;
             if (!waitForChromeExit(pid, TERM_WAIT_MS, POLL_INTERVAL_MS)) {
                 // SIGTERM didn't work. Escalate to SIGKILL. Orphaned Chrome processes (from a crashed parent or previous container) may not respond to SIGTERM.
                 LOG.debug("browser:lifecycle", "Chrome did not exit after SIGTERM. Escalating to SIGKILL.");
@@ -311,7 +416,6 @@ export function killStaleChrome() {
                 catch (_error) {
                     // ESRCH - Chrome exited between the poll check and the kill call.
                 }
-                const KILL_WAIT_MS = 2000;
                 if (!waitForChromeExit(pid, KILL_WAIT_MS, POLL_INTERVAL_MS)) {
                     LOG.warn("Chrome process %d did not exit after %dms of signal escalation. Proceeding anyway.", pid, TERM_WAIT_MS + KILL_WAIT_MS);
                 }
@@ -403,8 +507,9 @@ export function getExecutablePath() {
     throw new Error("No Chrome installation found. Set CHROME_BIN environment variable.");
 }
 /* Chrome extension ID for puppeteer-stream's bundled capture extension. This is the deterministic ID Chrome assigns based on the extension's public key, mirrored
- * from their dist at node_modules/puppeteer-stream/dist/PuppeteerStream.js (the extensionId constant). We use it below in --allowlisted-extension-id to work around
- * the broken activeTab grant path introduced in puppeteer-stream 3.0.22...see the "--allowlisted-extension-id" entry in buildLaunchOptions for the full rationale.
+ * from their dist at node_modules/puppeteer-stream/dist/PuppeteerStream.js (the extensionId constant). We pass it below via --allowlisted-extension-id as a
+ * defensive duplicate of the flag puppeteer-stream's own launch() call already re-adds; see the "--allowlisted-extension-id" entry in buildLaunchOptions for
+ * the full rationale.
  */
 const PUPPETEER_STREAM_EXTENSION_ID = "jjndjgheafjngoipoacpjgeicjeomjli";
 /**
@@ -423,11 +528,12 @@ export function buildLaunchOptions() {
          * --allow-running-insecure-content: Some streaming sites serve mixed HTTP/HTTPS content. Without this flag, the browser blocks HTTP resources on HTTPS
          *   pages, which can break video players that load some assets over HTTP.
          *
-         * --allowlisted-extension-id=<extension-id>: Restores Chrome's global allowlist for puppeteer-stream's capture extension. puppeteer-stream 3.0.22 stopped
-         *   injecting this flag in favor of granting activeTab via a synthetic Cmd/Ctrl+Shift+Y keystroke, but CDP-synthesized keystrokes do not satisfy
-         *   chrome.commands under automation (the renderer sees the event but the browser-process accelerator dispatcher does not), so the new flow fails to grant
-         *   activeTab and capture is denied at the API level (see github.com/Flam3rboy/puppeteer-stream/issues/206). Re-emitting the flag ourselves bypasses the
-         *   broken activeTab path. Remove this entry and the PUPPETEER_STREAM_EXTENSION_ID constant when issue #206 closes with a real fix.
+         * --allowlisted-extension-id=<extension-id>: Restores Chrome's global allowlist for puppeteer-stream's capture extension. puppeteer-stream's own launch()
+         *   call already re-adds this exact flag (see the addToArgs call for extensionId in node_modules/puppeteer-stream/dist/PuppeteerStream.js), so this entry
+         *   is a defensive duplicate: if a future puppeteer-stream release drops the flag again in favor of granting activeTab via a synthetic keystroke,
+         *   CDP-synthesized keystrokes do not satisfy chrome.commands under automation (the renderer sees the event but the browser-process accelerator dispatcher
+         *   does not), so capture would be denied at the API level (see github.com/Flam3rboy/puppeteer-stream/issues/206) without this fallback in place. Confirm
+         *   whether this duplicate is still warranted whenever the pinned puppeteer-stream version changes.
          *
          * --autoplay-policy=no-user-gesture-required: Allows video and audio to play without requiring a user click first. Essential for automated streaming
          *   since we cannot simulate genuine user interaction for autoplay policy purposes.
@@ -522,9 +628,11 @@ export function buildLaunchOptions() {
  * @returns The launched browser instance.
  */
 async function launchWithCustomArgs(opts) {
-    // When running as a packaged executable (process.pkg is set by the pkg bundler), we need to replace the extension paths. The puppeteer-stream library adds
-    // --load-extension and --disable-extensions-except arguments pointing to node_modules, but these paths don't exist in the packaged executable. We replace
-    // them with paths to our extracted extension files.
+    // When running as a packaged executable (process.pkg is set by the pkg bundler), we need to replace the extension paths. puppeteer-stream points
+    // opts.enableExtensions at its own node_modules-relative extension directory, which puppeteer-core installs via a CDP browser.installExtension() call after
+    // Chrome starts, rather than via --load-extension/--disable-extensions-except CLI flags - so that path still resolves inside node_modules, which does not
+    // exist at that location in the packaged executable. We route around it with Chrome's own native unpacked-extension flags, pointing them at our extracted
+    // extension files instead.
     if (process.pkg) {
         const extensionPath = getExtensionDir(CONFIG);
         // Remove any existing extension arguments and add our own pointing to the extracted extension.
@@ -557,11 +665,13 @@ function formatGpuSuffix(gpu) {
     return " (software rendering)";
 }
 /**
- * Detects the maximum supported viewport dimensions based on the user's display. This function measures the available screen space and subtracts browser chrome to
- * determine the largest viewport we can use for video capture.
+ * Detects the maximum supported viewport dimensions based on the user's display, and probes GPU hardware-encoding capabilities. The viewport half measures the
+ * available screen space and subtracts browser chrome to determine the largest viewport we can use for video capture; the GPU half queries CDP
+ * SystemInfo.getInfo for renderer identity and H.264/HEVC/AV1 hardware encoding support, falling back to a MediaRecorder capability probe where the CDP data
+ * is incomplete.
  *
- * The detection uses a temporary page (or existing page if available) to evaluate screen dimensions via JavaScript. The result is cached in the display module for
- * use by the preset system when determining effective viewport.
+ * The detection uses a temporary page (or existing page if available) to evaluate screen dimensions and GPU capabilities via JavaScript and CDP. Both results
+ * are cached in the display module for use by the preset system when determining effective viewport and capture codec.
  * @param browser - The browser instance to use for detection.
  */
 async function detectDisplayDimensions(browser) {
@@ -715,144 +825,176 @@ async function detectDisplayDimensions(browser) {
     }
 }
 /**
- * Handles browser disconnection events by cleaning up all active streams and resetting browser state. This function is called when the browser crashes, is closed
- * manually, or loses its connection for any other reason.
- *
- * When the browser disconnects, all pages (tabs) within it are immediately invalid and cannot be used. Any active streams using those pages will fail if they try
- * to interact with them. We proactively clean up by:
- * 1. Setting currentBrowser to null so the next stream request will launch a fresh browser
- * 2. Stopping all health monitors (they would fail trying to check page state)
- * 3. Removing all entries from activeStreams (the pages are gone)
- *
- * This ensures streams fail gracefully rather than hanging indefinitely trying to use closed pages.
+ * Relinquishes the current browser's capture readiness and tears down everything that depended on it. This is the single source of truth for "the published browser
+ * is no longer usable" - shared by the disconnect handler (the browser crashed) and by invalidateBrowser (the browser is alive but capture-dead). It drops the
+ * supervisor's readiness first (which supersedes any launch in flight, clears the governor's health anchor, and transitions the lifecycle to absent so the next
+ * request relaunches through the gate and governor), clears the adapter-held metadata and caches, ends login mode, terminates every active stream (they were
+ * capturing on the now-unusable browser), and emits status. Callers log the specific cause; the alive-but-dead caller additionally closes the Chrome instance.
+ * @param streamTerminationReason - The reason recorded against each terminated stream, for the stream-end logs.
  */
-function handleBrowserDisconnect() {
-    // Clear the browser reference, launch timestamp, cached version, and user agent so getCurrentBrowser() will launch a new instance on the next call. We do not
-    // track Chrome's PID directly anymore - killStaleChrome discovers orphans via the OS process table on the next startup, which removes a class of state that
-    // could go stale.
-    currentBrowser = null;
-    browserLaunchTime = null;
+function relinquishBrowserReadiness(streamTerminationReason) {
+    // Drop readiness first: supersede any in-flight launch, clear the governor's health anchor, and move the lifecycle to absent.
+    supervisor.noteReadinessLost();
+    // Clear the adapter-held Chrome version and the cached user agent so stale values are not served before the next ready browser. We do not track Chrome's PID
+    // directly - killStaleChrome discovers orphans via the OS process table on the next startup, which removes a class of state that could go stale.
     currentChromeVersion = null;
     setChromeUserAgent(null);
-    // Cancel any pending restart quiet timer since the browser is already gone.
+    // Cancel any pending scheduled-restart quiet timer since the browser this readiness applied to is gone.
     if (restartQuietTimer) {
         clearTimeout(restartQuietTimer);
         restartQuietTimer = null;
     }
-    // Clear all channel selection caches. Cached state (guide row positions, discovered page URLs) may be stale in a new browser session.
+    // Clear all channel selection caches. Cached state (guide row positions, discovered page URLs) belongs to the old browser session.
     clearChannelSelectionCaches();
-    // Clear login state if login mode was active. We use clearLoginState() rather than endLoginMode() because the browser is already gone and we don't want to
-    // attempt any browser operations (page close, window minimize).
+    // End login mode if it was active. We use clearLoginState() rather than endLoginMode() because the browser may already be gone and we do not want to attempt any
+    // browser operations (page close, window minimize).
     if (clearLoginState() && !gracefulShutdownInProgress) {
-        LOG.info("Login mode ended due to browser disconnect.");
+        LOG.info("Login mode ended due to browser readiness loss.");
     }
-    // Only log the error for unexpected disconnects. During graceful shutdown, closeBrowser() set the flag and this disconnect is intentional.
-    if (!gracefulShutdownInProgress) {
-        LOG.error("Browser disconnected unexpectedly. All active streams will be terminated.");
-    }
-    // Clean up all active streams using the authoritative terminateStream function for consistent cleanup. This is kept even during graceful shutdown as a defensive
-    // measure - terminateStream() is idempotent, so if streams were already terminated by the caller, this harmlessly iterates an empty array.
-    const streams = getAllStreams();
-    for (const streamInfo of streams) {
-        terminateStream(streamInfo.id, streamInfo.info.storeKey, "browser disconnect");
+    // Terminate every active stream using the authoritative terminateStream for consistent cleanup. Kept even during graceful shutdown as a defensive measure -
+    // terminateStream() is safe to call more than once, so if streams were already terminated by the caller, this harmlessly iterates an empty array.
+    for (const streamInfo of getAllStreams()) {
+        terminateStream(streamInfo.id, streamInfo.info.storeKey, streamTerminationReason);
     }
+    // The session those streams captured on is over, so whatever page tracking survived their termination belongs to a browser that is gone.
+    clearPageTracking();
     // Emit system status after stream cleanup. Skip during graceful shutdown since no clients are listening and the process is exiting.
     if (!gracefulShutdownInProgress) {
         void emitCurrentSystemStatus();
     }
 }
 /**
- * Provides access to the shared browser instance, launching one if needed. The browser is a shared resource used by all streaming sessions. This function handles:
- *
- * - Returning the existing browser if it's still connected
- * - Launching a new browser if none exists or the previous one disconnected
- * - Serializing concurrent callers so only one launch occurs at a time
- * - Waiting for the puppeteer-stream extension to initialize
- * - Setting up disconnect handlers for crash recovery
- * @returns The browser instance.
- * @throws If the browser cannot be launched.
+ * Handles browser disconnection events by relinquishing readiness and terminating all active streams. Called when the browser crashes, is closed externally, or
+ * otherwise loses its connection. It runs only for a genuine, unsolicited disconnect: every intentional teardown removes this listener via closeBrowserInstance
+ * first, so a scheduled restart, an orphan close, or an invalidation never reaches here. The browser is already gone, so there is nothing to close - relinquish
+ * readiness and the next request relaunches a fresh, gate-verified browser.
  */
-export async function getCurrentBrowser() {
-    // Fast path: if we have a browser and it's still connected, return it immediately. The connected property verifies the DevTools Protocol connection is
-    // still alive.
-    if (currentBrowser?.connected) {
-        return currentBrowser;
-    }
-    // If a launch is already in progress (e.g., from the restart path or a concurrent stream request), piggyback on that promise instead of starting a second
-    // Chrome process. Two concurrent launches with the same profile directory would contend on Chrome's profile lock.
-    if (browserLaunchPromise) {
-        return browserLaunchPromise;
-    }
-    // We need to launch a new browser. Store the promise so concurrent callers can piggyback on this launch.
-    browserLaunchPromise = launchBrowser();
-    try {
-        return await browserLaunchPromise;
+function handleBrowserDisconnect() {
+    // Announce the unexpected disconnect before tearing down (the message says streams will be terminated, which relinquish then does). Suppressed during a full
+    // server shutdown, where closeBrowser() set the flag and the disconnect is intentional.
+    if (!gracefulShutdownInProgress) {
+        LOG.error("Browser disconnected unexpectedly. All active streams will be terminated.");
     }
-    finally {
-        browserLaunchPromise = null;
+    relinquishBrowserReadiness("browser disconnect");
+}
+/**
+ * Invalidates a specific browser that is still connected but can no longer capture - a mid-life capture death that no "disconnected" event would surface. This is the
+ * single recovery action generalized to the alive-but-incapable case: relinquish readiness and terminate the browser's streams (exactly as a disconnect does),
+ * then additionally close the still-running Chrome so a leaked process is not left behind. The lifecycle is already absent after relinquish, so the next request
+ * relaunches a fresh, gate-verified browser through the supervisor. Exported for the streaming layer's passive mid-life detector to call once its probe confirms the
+ * browser cannot capture. noteReadinessLost stays internal: callers signal intent through this function, never the supervisor directly.
+ *
+ * The caller passes the exact instance it verified, and we invalidate only if it is still the published browser. The detector's probe runs in the background for
+ * seconds, during which the verified browser could have disconnected and been replaced by a fresh relaunch; without this identity guard we would tear down that
+ * new, healthy browser on the strength of a probe against the old, dead one.
+ * @param browser - The specific browser instance the caller verified as unable to capture.
+ * @param reason - A short description of why the browser is being invalidated, for the alarm log.
+ */
+export async function invalidateBrowser(browser, reason) {
+    // Only invalidate if this is still the published browser. If it was already superseded (a disconnect plus relaunch raced the caller's probe), there is nothing to
+    // do - the readiness loss was handled, and tearing down the current browser would wrongly disrupt a healthy, freshly-relaunched one.
+    if (supervisor.current() !== browser) {
+        return;
     }
+    LOG.error("The browser is connected but can no longer capture (%s). Invalidating it for a governed relaunch.", reason);
+    relinquishBrowserReadiness("capture system failure");
+    // Readiness was relinquished first, because that is what supersedes an in-flight launch; publishing the teardown synchronously, before any await, then keeps the
+    // launch window shut for the whole drain so nothing spawns a second Chrome against the profile lock this one still holds.
+    const teardown = closeBrowserInstance(browser);
+    supervisor.noteTeardownBegun(teardown, BROWSER_TEARDOWN_DRAIN_BOUND_MS);
+    await teardown;
 }
 /**
- * Launches a new browser instance and performs post-launch initialization (extension readiness, display detection, version capture). This is the inner launch
- * function called by getCurrentBrowser() and serialized by the browserLaunchPromise mutex.
- * @returns The browser instance.
- * @throws If the browser cannot be launched.
+ * Provides access to the capture-ready browser, launching one if needed. This is the single gated entry point for all browser access: it delegates to the
+ * supervisor's acquire(), which returns the ready browser, joins an in-flight launch (single-flight, so concurrent callers never contend on Chrome's profile lock),
+ * lazily launches when absent, or - while the relaunch governor is cooling after repeated failures - rejects fast with a BrowserUnavailableError WITHOUT spawning
+ * Chrome (the loop bound). The launch it drives runs the readiness gate, so a returned browser is verified capture-ready, not merely connected.
+ * @returns The capture-ready browser instance.
+ * @throws BrowserUnavailableError while the governor is cooling, BrowserSupersededError if an in-flight launch was abandoned by a readiness-loss, or the underlying
+ *   launch error when a launch attempt fails.
  */
-async function launchBrowser() {
+export async function getCurrentBrowser() {
+    return supervisor.acquire();
+}
+/**
+ * The supervisor's `launch` port: spawns Chrome, runs the readiness gate, performs post-launch initialization (display detection, version/UA capture, precaching),
+ * and resolves ONLY with a capture-ready browser. It builds into a local instance and publishes nothing - the supervisor owns publication and transitions to
+ * "ready" only after this resolves. A launch that fails the gate tears down its own Chrome here and throws, so a broken instance is never handed up; the supervisor
+ * counts the failure and decides whether to relaunch immediately or cool down. The gate throws rather than logging a failed extension load as a warning and serving
+ * the broken browser anyway, so only a verified-capturing instance is ever published.
+ * @returns The capture-ready browser instance.
+ * @throws If the launch or the readiness gate fails.
+ */
+async function launchReadyBrowser() {
     const browserElapsed = startTimer();
-    // This happens on first stream request, after a browser crash, during server warmup, or during an opportunistic restart.
+    // The launch function from puppeteer-stream wraps standard Puppeteer launch to inject the streaming extension. We pass our custom launch function that handles
+    // packaged-executable extension paths. This happens on first stream request, after a browser crash, during server warmup, or during a governed relaunch.
+    const browser = await launch({ launch: launchWithCustomArgs }, buildLaunchOptions());
     try {
-        const options = buildLaunchOptions();
-        // The launch function from puppeteer-stream wraps standard Puppeteer launch to inject the streaming extension. We pass our custom launch function that
-        // handles packaged executable extension paths.
-        currentBrowser = await launch({ launch: launchWithCustomArgs }, options);
-        // Register a handler for browser disconnection. This ensures we clean up properly if the browser crashes or is closed unexpectedly.
-        currentBrowser.on("disconnected", handleBrowserDisconnect);
         LOG.debug("timing:browser", "Chrome process spawned. (+%sms)", browserElapsed());
-        // Poll for the puppeteer-stream extension to finish initializing. The extension injects a START_RECORDING function into its options page context. We poll
-        // for this function's existence rather than using a fixed delay, so the browser is ready as soon as the extension loads - typically 200-500ms rather than the
-        // full configured timeout. Uses getExtensionPage() from puppeteer-stream to locate the extension's options page.
+        // Readiness gate, handshake tier (cheap, on-suspicion). Poll for the puppeteer-stream extension to finish initializing - it injects a START_RECORDING function
+        // into its options page context, so its presence is the extension's own readiness signal. We poll rather than fixed-delay so the browser is ready as soon as the
+        // extension loads (typically 200-500ms). On failure this THROWS rather than warning-and-proceeding: an unregistered extension means chrome.tabs is undefined and
+        // every getStream() would hang, so the instance is not capture-ready and must not be published. We reclassify the raw waitForFunction timeout into a
+        // capture-infrastructure error carrying "timed out" so the setup layer maps it to a 503 back-off (the same as the capability-tier probe failure), rather than a
+        // 500 the client would not back off from - an unregistered extension is a capture-infrastructure fault, and a fresh relaunch usually clears it.
         try {
-            const extensionPage = await getExtensionPage(currentBrowser);
+            const extensionPage = await getExtensionPage(browser);
             await extensionPage.waitForFunction("typeof START_RECORDING === 'function'", { timeout: CONFIG.browser.initTimeout });
         }
-        catch {
-            // If the extension page isn't found or START_RECORDING doesn't appear within the timeout, log a warning and proceed. The per-stream
-            // assertExtensionLoaded() in puppeteer-stream will retry before each capture attempt, so this isn't fatal.
-            LOG.warn("Extension did not initialize within %d ms. Streams may need additional time to start.", CONFIG.browser.initTimeout);
+        catch (handshakeError) {
+            throw new Error("The capture extension handshake timed out after " + String(CONFIG.browser.initTimeout) + " ms.", { cause: handshakeError });
         }
         LOG.debug("timing:browser", "Extension initialized. (+%sms)", browserElapsed());
-        // Detect display dimensions to determine maximum supported viewport. This must happen before we start streaming so the preset system can degrade to a
-        // smaller preset if needed.
-        await detectDisplayDimensions(currentBrowser);
+        // Readiness gate, capability tier (the authoritative arbiter). Run the injected capture probe - a real getStream against a throwaway page on THIS instance - so
+        // "ready" means "really captured," not merely "the extension handshake responded." This predicate must run at every (re)launch:
+        // it exercises the exact getStream path that hangs when the extension is unregistered. A probe failure throws, so the supervisor counts the launch failure and the
+        // browser is never published; the unrecoverable stale-mutex case exits the process from inside the probe, since a Chrome restart cannot fix a leaked module mutex.
+        //
+        // If the probe is not wired (the injection point left unset by a refactor - impossible in the normal import order, which always wires it before any launch),
+        // we reject the launch rather than publish a handshake-only browser: serving an unverified browser would be the "proceed and hope" path this design
+        // eliminates. The supervisor counts the rejected launch and, on repetition, degrades loudly.
+        if (!captureProbe) {
+            throw new Error("The capture-readiness probe is not wired; refusing to publish a browser whose capture capability was not verified.");
+        }
+        await captureProbe(browser);
+        LOG.debug("timing:browser", "Capture probe complete. (+%sms)", browserElapsed());
+        // Detect display dimensions to determine the maximum supported viewport. This must happen before streaming so the preset system can degrade to a smaller preset
+        // if needed.
+        await detectDisplayDimensions(browser);
         LOG.debug("timing:browser", "Display detection complete. (+%sms)", browserElapsed());
-        // Log the Chrome version for diagnostic reference. This helps correlate browser behavior changes (tab unresponsiveness, memory pressure, capture issues)
-        // with specific Chrome releases. We also capture the User-Agent string so that server-side fetch() calls to service CDNs can match Chrome's identity.
-        const chromeVersion = await currentBrowser.version();
-        const userAgent = await currentBrowser.userAgent();
-        browserLaunchTime = Date.now();
+        // Capture the Chrome version and User-Agent. The version is logged for diagnostics (correlating browser behavior changes with specific Chrome releases) and
+        // surfaced by the health endpoint; the User-Agent lets server-side fetch() calls to service CDNs match Chrome's identity.
+        const chromeVersion = await browser.version();
+        const userAgent = await browser.userAgent();
         currentChromeVersion = chromeVersion;
         setChromeUserAgent(userAgent);
         const gpu = getGpuCapabilities();
         const gpuSuffix = gpu ? formatGpuSuffix(gpu) : "";
         LOG.info("Chrome ready: %s%s.", chromeVersion, gpuSuffix);
         LOG.debug("timing:browser", "Browser ready. Total: %sms.", browserElapsed());
-        // Emit system status update for SSE subscribers.
-        await emitCurrentSystemStatus();
-        // Start background precaching of selected service channel lineups. Fire-and-forget - the setTimeout inside startPrecaching() ensures the actual work is fully
-        // async and non-blocking.
+        // Start background precaching of selected service channel lineups. Fire-and-forget - the setTimeout inside startPrecaching() defers the work until after this
+        // launch settles and the supervisor has published the ready browser, so its getCurrentBrowser() resolves immediately rather than re-entering this launch.
         startPrecaching();
+        // Arm the disconnect handler only now, as the very last step before the supervisor publishes this browser as ready. It is deliberately NOT armed earlier: during
+        // the gate/init window above, a Chrome crash surfaces as a thrown init step (CDP and waitForFunction reject on a dead browser), which the supervisor counts as a
+        // launch failure and feeds to the governor - keeping the relaunch loop bounded even if Chrome dies repeatedly during init. Arming the handler earlier would let
+        // its noteReadinessLost() bump the supervisor's launch generation and the launch would be treated as superseded (uncounted), defeating the loop bound. There is
+        // no gap: every statement from the last await to this return is synchronous, so a disconnect cannot be delivered between this registration and publication.
+        browser.on("disconnected", handleBrowserDisconnect);
+        return browser;
     }
     catch (error) {
         LOG.error("Failed to launch browser: %s.", formatError(error));
-        // Clear the browser reference, launch timestamp, cached version, and user agent on failure so the next call will attempt to launch again.
-        currentBrowser = null;
-        browserLaunchTime = null;
+        // The gate (or post-launch init) failed. Clear the adapter-held metadata and tear down the Chrome instance we just spawned before propagating, so a failed
+        // launch never leaks a process and the next governed relaunch starts from a clean profile. The disconnect handler is not yet armed on this instance (it is armed
+        // only on the success path above), so this teardown never re-enters handleBrowserDisconnect - which is exactly what lets the supervisor count this as a launch
+        // failure rather than a supersession.
         currentChromeVersion = null;
         setChromeUserAgent(null);
+        await closeBrowserInstance(browser);
         throw error;
     }
-    return currentBrowser;
 }
 /**
  * Returns the Chrome version string captured when the browser launched, or null if the browser is not connected.
@@ -867,14 +1009,15 @@ export function getChromeVersion() {
  * @returns The browser instance, or null if not running.
  */
 export function getBrowserInstance() {
-    return currentBrowser;
+    return supervisor.current();
 }
 /**
  * Checks if the browser is currently connected and usable. This is a synchronous check that can be used before attempting browser operations.
  * @returns True if the browser is connected and ready for use, false otherwise.
  */
 export function isBrowserConnected() {
-    return !!currentBrowser && currentBrowser.connected;
+    const browser = supervisor.current();
+    return !!browser && browser.connected;
 }
 /**
  * Resizes the browser window to the effective viewport and minimizes it. This function combines viewport sizing with minimization to ensure the window is
@@ -886,18 +1029,19 @@ export function isBrowserConnected() {
  */
 export async function minimizeBrowserWindow() {
     // Guard against calling this when no browser is running.
-    if (!currentBrowser?.connected) {
+    const browser = supervisor.current();
+    if (!browser?.connected) {
         return;
     }
     let tempPage = null;
     let usingTempPage = false;
     try {
         // Try to use an existing page first. Creating a new page can cause the window to restore/activate on macOS, which defeats the purpose of minimizing.
-        const existingPages = await currentBrowser.pages();
+        const existingPages = await browser.pages();
         let targetPage = existingPages.find((p) => !p.isClosed()) ?? null;
         // If no existing pages, we must create a temporary one. This is less ideal but necessary to get a CDP session target.
         if (!targetPage) {
-            tempPage = await currentBrowser.newPage();
+            tempPage = await browser.newPage();
             usingTempPage = true;
             // Register the temp page so stale cleanup knows it's ours.
             registerManagedPage(tempPage);
@@ -928,16 +1072,17 @@ export async function minimizeBrowserWindow() {
     }
 }
 /**
- * Gets all open browser pages (tabs). This is used by the health check endpoint to report page count and by stale page cleanup to find orphaned pages.
+ * Gets all open browser pages (tabs). This is used by the health check endpoint to report page count.
  * @returns Array of pages, or empty array if the browser is not connected.
  */
 export async function getBrowserPages() {
-    // Guard against calling this when no browser is running.
-    if (!currentBrowser?.connected) {
+    // Guard against calling this when no ready browser is running.
+    const browser = supervisor.current();
+    if (!browser?.connected) {
         return [];
     }
     try {
-        return await currentBrowser.pages();
+        return await browser.pages();
     }
     catch (_error) {
         // If getting pages fails (browser disconnecting, etc.), return empty array rather than throwing.
@@ -945,67 +1090,87 @@ export async function getBrowserPages() {
     }
 }
 /**
- * Closes the browser and cleans up resources. This is called during graceful shutdown to ensure Chrome exits cleanly. After this call, the browser reference is
- * cleared and any subsequent stream requests will launch a fresh browser.
+ * Tears down a specific Chrome instance and is the single teardown primitive: the supervisor's `close` port (for disposing an orphaned superseded launch), the
+ * launch-failure cleanup in launchReadyBrowser, the scheduled-restart teardown in executeBrowserRestart, and the full-server closeBrowser all route through it. It
+ * owns no lifecycle state - the supervisor is the single source of truth for that. It first removes the disconnect listener so this intentional teardown does not
+ * trip handleBrowserDisconnect: the SIGTERM-induced "disconnected" event can arrive after this function returns, and without the removal it could supersede a fresh
+ * launch the caller has already started (the late-disconnect race).
  *
  * Chrome termination uses Puppeteer's ChildProcess handle and its `exit` event for detection:
  *
- * - browserRef.close() sends CDP Browser.close and waits for WebSocket teardown, which hangs 3-5 seconds even after Chrome exits.
- * - browserRef.disconnect() drops the WebSocket instantly but orphans Chrome as a Node child process, creating a zombie that process.kill(pid, 0) cannot detect.
+ * - browser.close() sends CDP Browser.close and waits for WebSocket teardown, which hangs 3-5 seconds even after Chrome exits.
+ * - browser.disconnect() drops the WebSocket instantly but orphans Chrome as a Node child process, creating a zombie that process.kill(pid, 0) cannot detect.
  * - Synchronous polling (Atomics.wait) blocks the event loop, preventing Node from processing SIGCHLD to reap the child - Chrome becomes a zombie regardless
  *   of how SIGTERM was sent.
  *
- * Instead, we send SIGTERM through the ChildProcess handle and listen for the `exit` event. This keeps the event loop running so Node can process SIGCHLD and
- * reap Chrome properly. The exit event fires only after the process is fully reaped - no zombies, no polling, no event loop blocking.
+ * Instead, we send SIGTERM through the ChildProcess handle and listen for the `exit` event. This keeps the event loop running so Node can process SIGCHLD and reap
+ * Chrome properly. The exit event fires only after the process is fully reaped - no zombies, no polling, no event loop blocking. The await on the exit event is what
+ * lets the caller relaunch immediately afterward without contending on Chrome's profile lock.
+ * @param browser - The Chrome instance to terminate.
  */
-export async function closeBrowser() {
-    // Ensure the flag is set so the disconnect handler knows this is intentional. Normally set earlier by app.ts shutdown(), but set here as a fallback for direct
-    // calls to closeBrowser().
-    setGracefulShutdown(true);
-    const browserRef = currentBrowser;
-    // Clear the reference, launch timestamp, cached version, and user agent early to prevent any new operations from using it.
-    currentBrowser = null;
-    browserLaunchTime = null;
-    currentChromeVersion = null;
-    setChromeUserAgent(null);
-    if (!browserRef) {
-        return;
-    }
-    // Send SIGTERM through Puppeteer's ChildProcess handle and wait for the `exit` event. The ChildProcess handle is only available when Puppeteer launched
-    // Chrome (not when connecting to an existing browser), but PrismCast always launches Chrome directly.
-    const chromeProcess = browserRef.process();
+async function closeBrowserInstance(browser) {
+    // Remove the disconnect handler before signalling. Every call here is an intentional teardown, so the resulting "disconnected" event must not invoke the
+    // unexpected-disconnect handler - which would clear caches, log an error, and (critically) call noteReadinessLost(), superseding any launch the caller starts next.
+    browser.off("disconnected", handleBrowserDisconnect);
+    // Send SIGTERM through Puppeteer's ChildProcess handle and wait for the `exit` event. The ChildProcess handle is only available when Puppeteer launched Chrome
+    // (not when connecting to an existing browser), but PrismCast always launches Chrome directly.
+    const chromeProcess = browser.process();
     if (chromeProcess?.pid && !chromeProcess.killed) {
-        const TERM_WAIT_MS = 5000;
-        const KILL_WAIT_MS = 2000;
-        // Listen for the exit event before sending the signal. The event fires after the OS reaps the process, so there is no zombie window. Resolves to true so
-        // Promise.race can distinguish exit from timeout.
+        // Listen for the exit event before sending the signal. The event fires after the OS reaps the process, so there is no zombie window. The promise only ever
+        // resolves, so a null from either bounded wait below means the exit never came.
         const { promise: exitPromise, resolve: signalExit } = Promise.withResolvers();
         chromeProcess.on("exit", () => { signalExit(true); });
         chromeProcess.kill("SIGTERM");
         LOG.debug("browser:lifecycle", "Sent SIGTERM to Chrome process %d.", chromeProcess.pid);
-        // Wait for Chrome to exit after SIGTERM, with a timeout. If Chrome doesn't exit in time, escalate to SIGKILL.
-        const termTimeout = cancellableTimeout(TERM_WAIT_MS);
-        const exitedAfterTerm = await Promise.race([exitPromise, termTimeout.promise]);
-        termTimeout.cancel();
+        // Wait for Chrome to exit after SIGTERM, with a bound. If Chrome doesn't exit in time, escalate to SIGKILL.
+        const exitedAfterTerm = await boundedWait(exitPromise, TERM_WAIT_MS);
         if (!exitedAfterTerm) {
-            // SIGTERM didn't work within the timeout. Escalate to SIGKILL. Orphaned Chrome processes (from a crashed parent or previous container) may not
+            // SIGTERM didn't work within the bound. Escalate to SIGKILL. Orphaned Chrome processes (from a crashed parent or previous container) may not
             // respond to SIGTERM.
             LOG.debug("browser:lifecycle", "Chrome did not exit after SIGTERM. Escalating to SIGKILL.");
             chromeProcess.kill("SIGKILL");
-            const killTimeout = cancellableTimeout(KILL_WAIT_MS);
-            await Promise.race([exitPromise, killTimeout.promise]);
-            killTimeout.cancel();
+            // The same exit promise serves the second wait: if it already resolved, this returns its value immediately.
+            await boundedWait(exitPromise, KILL_WAIT_MS);
         }
     }
-    // Disconnect the Puppeteer WebSocket after Chrome has exited. This cleans up Puppeteer's internal state (event listeners, pending CDP calls) without
-    // waiting for the WebSocket close handshake to complete on a dead connection.
-    if (browserRef.connected) {
-        void browserRef.disconnect();
+    // Disconnect the Puppeteer WebSocket after Chrome has exited. This cleans up Puppeteer's internal state (event listeners, pending CDP calls) without waiting for
+    // the WebSocket close handshake to complete on a dead connection. We catch the rejection: disconnect() on a connection whose underlying transport already died of
+    // an unclean Chrome exit can reject, and an unhandled rejection on this fire-and-forget call would crash the process during an otherwise-successful teardown.
+    if (browser.connected) {
+        browser.disconnect().catch((error) => {
+            LOG.debug("browser:lifecycle", "Ignoring browser disconnect error during teardown: %s.", formatError(error));
+        });
     }
     // Remove stale Chrome profile lock files left behind by the disconnected browser. No per-PID state to clear here - killStaleChrome on the next launch will
     // discover any leftover Chrome via the OS process table.
     cleanStaleProfileFiles(getChromeDataDir(CONFIG));
 }
+/**
+ * Closes the browser and cleans up resources during full server shutdown. After this call the supervisor reports absent and any subsequent stream request launches
+ * a fresh browser. It retires the current instance from the lifecycle (so an in-flight launch is superseded and the metadata is cleared), then delegates the actual
+ * Chrome teardown to closeBrowserInstance. The graceful-shutdown flag is set so handleBrowserDisconnect, if it runs for any reason, stays quiet.
+ */
+export async function closeBrowser() {
+    // Ensure the flag is set so the disconnect handler stays quiet. Normally set earlier by app.ts shutdown(), but set here as a fallback for direct calls.
+    setGracefulShutdown(true);
+    // Capture the ready browser before retiring it from the lifecycle. noteReadinessLost() supersedes any launch in flight and transitions to absent; we then clear
+    // the adapter-held metadata so nothing stale is served.
+    const browser = supervisor.current();
+    supervisor.noteReadinessLost();
+    // The session is ending, so its page ids are spent. The call sits ahead of the early return below so the clear happens whether or not there was a browser to
+    // close.
+    clearPageTracking();
+    currentChromeVersion = null;
+    setChromeUserAgent(null);
+    if (!browser) {
+        return;
+    }
+    // Readiness was relinquished first, because that is what supersedes an in-flight launch; publishing the teardown synchronously, before any await, then keeps the
+    // launch window shut for the whole drain so nothing spawns a second Chrome against the profile lock this one still holds.
+    const teardown = closeBrowserInstance(browser);
+    supervisor.noteTeardownBegun(teardown, BROWSER_TEARDOWN_DRAIN_BOUND_MS);
+    await teardown;
+}
 /* Over time, browser pages (tabs) may accumulate if cleanup fails during stream termination. This can happen due to race conditions, errors during cleanup, or
  * edge cases in stream lifecycle management. Each orphaned page consumes memory and may continue running JavaScript, so we periodically clean them up.
  *
@@ -1021,6 +1186,12 @@ export async function closeBrowser() {
  *    briefly untracked during stream initialization or cleanup.
  *
  * 4. Minimum page preservation: We always keep at least one page open to prevent Chrome from exiting.
+ *
+ * 5. In-flight setup exemption: Pages whose stream setup is still running (tracked in inFlightSetupPageIds) are never considered stale. The registry records a
+ *    stream's page only once setup completes, so without this a slow tune would have its own page closed out from under it.
+ *
+ * The safeguards are expressed as rules in browser/pageStaleness.ts, which decides from a snapshot what to close, track, forget, and unmark. This function is the
+ * I/O shell around that decision: it reads Chrome's page list, applies the decision to the tracking collections, and performs the closes.
  */
 /**
  * Cleans up browser pages that are not associated with active streams. This function runs periodically to catch any pages that were not properly closed during
@@ -1028,17 +1199,18 @@ export async function closeBrowser() {
  *
  * The cleanup uses a multi-stage filtering process:
  * 1. Only consider pages we created (in managedPageIds)
- * 2. Exclude pages associated with active streams
+ * 2. Exclude pages associated with active streams, and pages whose stream setup is still in flight
  * 3. Apply a grace period before closing (to handle race conditions)
  * 4. Preserve at least one page to keep the browser alive
  */
 export async function cleanupStalePages() {
-    // Guard against calling this when no browser is running.
-    if (!currentBrowser?.connected) {
+    // Guard against calling this when no ready browser is running.
+    const browser = supervisor.current();
+    if (!browser?.connected) {
         return;
     }
     try {
-        const pages = await currentBrowser.pages();
+        const pages = await browser.pages();
         // If there's only one page or fewer, we must preserve it to keep the browser alive. Don't attempt cleanup.
         if (pages.length <= 1) {
             return;
@@ -1054,53 +1226,37 @@ export async function cleanupStalePages() {
             }
         }
         const now = Date.now();
-        const gracePeriod = CONFIG.recovery.stalePageGracePeriod;
-        // Build a list of pages that are candidates for cleanup. A page is a candidate if:
-        // - It has a managed page ID (was created by PrismCast)
-        // - It is not associated with any active stream
-        // - It has been stale for longer than the grace period
-        const candidatePages = [];
-        // Track which managed page IDs we've seen in the current browser pages. Used for cleanup of stale tracking data.
-        const currentManagedIds = new Set();
+        // Project the browser's pages into the shape the decision core reads: the managed ids in the browser's own order, with undefined standing in for pages we
+        // did not create, plus a lookup back to the Page objects so the ids it returns can be resolved to something closable.
+        const idToPage = new Map();
+        const pageIds = [];
         for (const page of pages) {
             const pageId = getManagedPageId(page);
-            // Skip pages we didn't create. This preserves manually opened pages and site popups.
-            if (!pageId) {
-                continue;
-            }
-            currentManagedIds.add(pageId);
-            // Skip pages associated with active streams.
-            if (activePageIds.has(pageId)) {
-                // If this page was previously marked as potentially stale, remove it from tracking since it's now active.
-                potentiallyStalePages.delete(pageId);
-                continue;
-            }
-            // This page is potentially stale. Track when we first observed it as such.
-            if (!potentiallyStalePages.has(pageId)) {
-                potentiallyStalePages.set(pageId, now);
-                // Don't close it yet - wait for the grace period.
-                continue;
-            }
-            // Check if the grace period has elapsed.
-            const firstSeenStale = potentiallyStalePages.get(pageId) ?? now;
-            if ((now - firstSeenStale) < gracePeriod) {
-                // Grace period hasn't elapsed yet. Leave this page alone for now.
-                continue;
+            pageIds.push(pageId);
+            if (pageId !== undefined) {
+                idToPage.set(pageId, page);
             }
-            // This page has been stale for longer than the grace period. It's a candidate for cleanup.
-            candidatePages.push({ page, pageId });
         }
-        // Clean up the potentiallyStalePages map by removing entries for pages that no longer exist. This handles cases where pages were closed by other means.
-        for (const trackedId of potentiallyStalePages.keys()) {
-            if (!currentManagedIds.has(trackedId)) {
-                potentiallyStalePages.delete(trackedId);
-            }
+        // The staleness judgment - clocks, exemptions, the dead-entry sweep, and the preserve-one budget - belongs to the pure core; this function only carries it out.
+        const actions = evaluateStalePages({ activePageIds, gracePeriodMs: CONFIG.recovery.stalePageGracePeriod, inFlightSetupPageIds, now, pageIds,
+            staleFirstSeen: potentiallyStalePages });
+        // Bring the tracking collections in line with the decision before any close runs, so a close that fails cannot leave the bookkeeping half-applied.
+        for (const pageId of actions.forgetTrackedIds) {
+            potentiallyStalePages.delete(pageId);
+        }
+        for (const pageId of actions.startTrackingIds) {
+            potentiallyStalePages.set(pageId, now);
+        }
+        for (const pageId of actions.clearInFlightIds) {
+            inFlightSetupPageIds.delete(pageId);
         }
-        // Calculate how many pages we can close while still keeping at least one page open.
-        const maxToClose = Math.max(0, pages.length - 1 - activePageIds.size);
-        const pagesToClose = candidatePages.slice(0, maxToClose);
         let closedCount = 0;
-        for (const { page, pageId } of pagesToClose) {
+        for (const pageId of actions.closeIds) {
+            // Every id the core returns for closing came from the page list built above, so this resolves; the check is what narrows it to a Page.
+            const page = idToPage.get(pageId);
+            if (!page) {
+                continue;
+            }
             try {
                 // Unregister the page before closing to prevent any race with re-registration.
                 managedPageIds.delete(pageId);
@@ -1146,16 +1302,29 @@ export function stopStalePageCleanup() {
  */
 /**
  * Checks whether the browser qualifies for an opportunistic restart. Called periodically by the restart check interval. The check skips when any of these
- * conditions hold: graceful shutdown in progress, login mode active, browser not connected, browser age below threshold. If active streams exist, any pending
- * quiet timer is cancelled (streams started during the quiet period reset the countdown). Otherwise a quiet timer is started if one is not already running.
+ * conditions hold: graceful shutdown in progress, login mode active, browser not ready, browser age below threshold. On every eligible tick it also drives the
+ * supervisor's health-gated governor reset. If active streams exist, any pending quiet timer is cancelled (streams started during the quiet period reset the
+ * countdown). Otherwise a quiet timer is started if one is not already running.
  */
 function checkBrowserRestart() {
-    // Skip if the server is shutting down, login mode is active, or the browser is not connected.
-    if (gracefulShutdownInProgress || isLoginModeActive() || !currentBrowser || !currentBrowser.connected || !browserLaunchTime) {
+    // Skip if the server is shutting down or login mode is active.
+    if (gracefulShutdownInProgress || isLoginModeActive()) {
         return;
     }
+    // Read the ready browser and its launch time from the supervisor. Both are non-null only in the ready state, so a single guard covers "no ready browser." The
+    // launch time is on the supervisor's clock (realClock.now), so age must be measured against the same clock - not Date.now() - or the units would not match.
+    const browser = supervisor.current();
+    const launchTime = supervisor.currentLaunchTime();
+    if (!browser?.connected || (launchTime === null)) {
+        return;
+    }
+    // Health-gated governor reset. On every eligible tick, tell the supervisor the browser is still ready; once it has been continuously ready for the policy's
+    // hold, this resets the relaunch governor to its normal state and returns true, so we log the recovery exactly once.
+    if (supervisor.noteSustainedHealth()) {
+        LOG.info("Browser capture readiness has been sustained; the relaunch governor has reset to its normal state.");
+    }
     // Skip if the browser has not exceeded the maximum age.
-    const age = Date.now() - browserLaunchTime;
+    const age = realClock.now() - launchTime;
     if (age < BROWSER_MAX_AGE) {
         return;
     }
@@ -1183,21 +1352,37 @@ function checkBrowserRestart() {
 async function executeBrowserRestart() {
     // Clear the timer handle.
     restartQuietTimer = null;
-    // Final guard: re-check all preconditions. Conditions may have changed during the quiet period (e.g., a stream started just before the timer fired, login
-    // mode was activated, or the browser disconnected on its own).
-    if (gracefulShutdownInProgress || isLoginModeActive() || (getStreamCount() > 0) || !currentBrowser || !currentBrowser.connected || !browserLaunchTime) {
+    // Final guard: re-check all preconditions. Conditions may have changed during the quiet period (e.g., a stream started just before the timer fired, login mode
+    // was activated, or the browser disconnected on its own). Reading current()/currentLaunchTime() together keeps the ready-state check and the age source consistent.
+    const browser = supervisor.current();
+    const launchTime = supervisor.currentLaunchTime();
+    if (gracefulShutdownInProgress || isLoginModeActive() || (getStreamCount() > 0) || !browser?.connected || (launchTime === null)) {
         LOG.debug("browser:lifecycle", "Browser restart aborted - preconditions no longer met.");
         return;
     }
-    const age = Date.now() - browserLaunchTime;
+    const age = realClock.now() - launchTime;
     const hours = Math.floor(age / 3600000);
     const minutes = Math.floor((age % 3600000) / 60000);
     LOG.info("Restarting browser for scheduled maintenance (uptime: %sh %sm).", hours, minutes);
     try {
-        // closeBrowser() sets gracefulShutdownInProgress = true internally and performs SIGTERM-based Chrome termination.
-        await closeBrowser();
-        // Reset the flag since the server is NOT shutting down - only the browser is restarting.
-        setGracefulShutdown(false);
+        // Retire the current instance from the lifecycle, tear it down, then acquire a fresh one through the supervisor. We do NOT touch the graceful-shutdown flag (the
+        // server is not shutting down): closeBrowserInstance removes the disconnect listener, which is what makes this intentional teardown quiet. acquire() publishes
+        // "ready" only after the readiness gate passes, so the completion log below is truthful: it verifies capture capability before claiming readiness, not mere liveness.
+        supervisor.noteReadinessLost();
+        // The restart swaps the whole Chrome session inside a living process, so the retiring session's page ids must not carry into the fresh one.
+        clearPageTracking();
+        // Readiness was relinquished first, because that is what supersedes an in-flight launch; publishing the teardown synchronously, before any await, then keeps the
+        // launch window shut for the whole drain so nothing spawns a second Chrome against the profile lock this one still holds.
+        const teardown = closeBrowserInstance(browser);
+        supervisor.noteTeardownBegun(teardown, BROWSER_TEARDOWN_DRAIN_BOUND_MS);
+        await teardown;
+        // The preconditions were checked before the teardown, but a shutdown can begin during the seconds it takes, and relaunching then would spawn Chrome into a
+        // dying process. Re-check on the far side of the await, for the same reason the guard above re-checks on the far side of the quiet period.
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- the shutdown path sets this while the teardown is awaited; TS cannot see that.
+        if (gracefulShutdownInProgress) {
+            LOG.debug("browser:lifecycle", "Browser restart relaunch declined because shutdown began while the previous instance was closing.");
+            return;
+        }
         // Launch a fresh browser instance so it is ready for the next stream request.
         await getCurrentBrowser();
         // Minimize the new window to reduce GPU usage and desktop clutter.
@@ -1206,8 +1391,6 @@ async function executeBrowserRestart() {
     }
     catch (error) {
         LOG.error("Browser restart failed: %s.", formatError(error));
-        // Ensure the graceful shutdown flag is cleared even on failure so new stream requests can still launch a browser.
-        setGracefulShutdown(false);
     }
 }
 /**