prismcast 1.13.0 → 1.14.0

package/dist/browser/index.js

@@ -3,10 +3,10 @@ import { TimerRegistry, systemClock } from "homebridge-plugin-utils";
 import { clearLoginState, isLoginModeActive, setLoginDeps } from "./login.js";
 import { getAllStreams, getStreamCount, hasActiveCaptureStreams, hasEstablishedStreams, isCaptureIdentity } from "../streaming/registry.js";
 import { getCachedTabId, installStrayOpenTabReaper, onTabActivation } from "./tabSelection.js";
-import { getChromeDataDir, getDataDir, getExtensionDir } from "../config/paths.js";
+import { getChromeDataDir, getDataDir } from "../config/paths.js";
 import { getExtensionPage, launch } from "puppeteer-stream";
 import { getGpuCapabilities, setGpuCapabilities } from "./display.js";
-import { minimizeWindow, readWindowPlacement, reaffirmCaptureSurface, unminimizeWindow, withCDPSession } from "./cdp.js";
+import { minimizeWindow, readWindowPlacement, unminimizeWindow, withCDPSession } from "./cdp.js";
 import { CONFIG } from "../config/index.js";
 import { EXTENSION_READY_EXPRESSION } from "./tabCapture.js";
 import { clearChannelSelectionCaches } from "./channelSelection.js";
@@ -18,21 +18,22 @@ import fs from "node:fs";
 import { getPresetViewport } from "../config/presets.js";
 import path from "node:path";
 import { launch as puppeteerLaunch } from "puppeteer-core";
+import { registerConfigChangeHandler } from "../config/reactivity.js";
 import { startPrecaching } from "./precaching.js";
 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:
  *
- * - 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.
+ * - supervisor: The browser capture-readiness supervisor. It is the single source of truth for the shared Chrome instance and its lifecycle (every phase from
+ *   absent to closing), 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.
  *
  * - 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.). 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.
+ * resolution for persistent data (the Chrome profile and the streaming extension files) is centralized in config/paths.ts and resolved on demand rather than held
+ * as module state here; ensureDataDirectory() below creates the data directory at startup.
  */
 // 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
@@ -56,8 +57,8 @@ const KILL_WAIT_MS = 2000;
 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
+ * an operator's change to the recovery.relaunch* settings takes effect at the next governor decision without reconstructing the supervisor. 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.
  */
@@ -69,12 +70,12 @@ function buildRelaunchPolicy() {
         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), systemClock.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.
+/* The one browser capture-readiness supervisor for the process lifetime. It owns the lifecycle state (one discriminated union covering every phase from absent to
+ * closing) 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), systemClock.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: () => systemClock.now(),
     onStateChange: onSupervisorStateChange, policy: buildRelaunchPolicy });
@@ -121,7 +122,8 @@ function onSupervisorStateChange(next, previous) {
 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.
+ * launch, since the streaming layer is imported during server startup). Separating the wiring from the call keeps browser/index.ts from importing
+ * streaming/setup.ts, which already imports this module, so the dependency stays one-directional.
  * @param probe - The probe to run against a freshly-launched browser; it resolves when the browser can capture and rejects when it cannot.
  */
 export function setCaptureProbe(probe) {
@@ -136,7 +138,7 @@ export function setCaptureProbe(probe) {
 let streamTerminator = null;
 /**
  * Injects the authoritative stream terminator used when browser readiness is lost. Called once from streaming/lifecycle.ts at module load. Separating the wiring
- * from the call keeps browser/index.ts free of a streaming-layer import.
+ * from the call keeps browser/index.ts from importing streaming/lifecycle.ts, which already imports this module, so the dependency stays one-directional.
  * @param terminator - The function that tears down one stream and all of the resources it owns.
  */
 export function setStreamTerminator(terminator) {
@@ -144,10 +146,8 @@ export function setStreamTerminator(terminator) {
 }
 // The identity of the periodic sweep on the stale-page owner's registry.
 const STALE_PAGE_SWEEP_KEY = "sweep";
-/* The stale-page owner's timers: the periodic sweep that closes browser pages no active stream is using, so a long session cannot exhaust resources. The registry
- * is built on the clock the start receives and disposed by the stop, so the sweep can never outlive the owner. Null until started, and again once stopped.
- */
-let stalePageTimers = null;
+// The running stale-page sweep. Null until started, and again once stopped.
+let stalePageSweep = null;
 /* Opportunistic browser restart state. Chrome accumulates memory pressure, GPU process issues, and general flakiness over multi-hour sessions with continuous
  * media playback. We proactively restart Chrome after it has been running for BROWSER_MAX_AGE, waiting for a quiet period with zero active streams before
  * executing the restart. After the restart, a fresh browser is launched immediately so it is ready for the next stream request.
@@ -175,8 +175,9 @@ let restartTimers = null;
 function cancelRestartQuietTimer() {
     restartTimers?.clear(RESTART_QUIET_KEY);
 }
-// Flag indicating that the browser is being closed intentionally via closeBrowser(). When true, the disconnect handler skips error logging and stream termination
-// since these are handled by the shutdown code path. This prevents false "unexpected disconnect" errors during graceful shutdown.
+// The process-wide graceful-shutdown state. app.ts shutdown() sets it early, and closeBrowser() sets it as a fallback for direct calls. While it is set, the
+// disconnect path stays quiet (no error log and no status emit) and the restart paths stand down; stream termination still runs. This prevents false
+// "unexpected disconnect" errors during graceful shutdown.
 let gracefulShutdownInProgress = false;
 /**
  * Returns true if graceful shutdown is in progress.
@@ -241,7 +242,7 @@ export function pickCarrierPage(pages) {
     return pages.find(isCarrierPage) ?? null;
 }
 /* Which window Chrome's own tables call the shared one, keyed on the browser that owns it. The value belongs to CDP's window table and is never comparable with
- * the capture extension's chrome.windows ids: those are two independent tables, and this is the only place a value from the CDP side is held.
+ * the capture extension's chrome.windows ids: those are two independent tables, and this is the only place the shared window's identity is recorded.
  *
  * Keyed on the browser and never cleared, for the reason the own-window mark above is: the identity is a fact about how that browser was created, an entry dies
  * with the browser holding it, and a relaunch records its own. An id that outlived its browser is exactly what would place a capture tab in the wrong window
@@ -277,7 +278,7 @@ async function readPageWindow(page) {
  * Records which window the shared one is, reading it from a page that sits in it.
  *
  * This is the one way an identity is written. The launch path calls it once the launch-era pages exist, so every browser this process publishes carries the
- * answer before anything asks for a capture tab, and a probe running against a browser of its own calls the same function rather than reaching for the map.
+ * answer before anything asks for a capture tab.
  * @param browser - The browser whose shared window is being recorded.
  * @param page - A page that sits in that window.
  */
@@ -341,6 +342,16 @@ export { endLoginMode, getLoginPage, getLoginStatus, setLoginModeEndObserver, st
 // captures and is waiting for its streams to end. The purpose and impairment types cross the same boundary, so a caller declares what it needs the browser for and
 // reads the mark without importing the supervisor.
 export { BrowserCaptureImpairedError, BrowserSupersededError, BrowserUnavailableError } from "./browserSupervisor.js";
+/**
+ * Thrown when the browser launched but its capture system failed a launch gate: the capture extension never became ready, or the capture probe found no
+ * working capture across its attempts. setupStream answers it as a capture-infrastructure failure by its type, so its message is free to state what happened.
+ */
+export class CaptureLaunchError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "CaptureLaunchError";
+    }
+}
 /* The one window-presentation executor for the process lifetime. Its collaborators all live in this module: the registry predicate that says whether capture is
  * reading the compositor, login mode's own flag, the shutdown gate, the two CDP primitives, and a page resolver built on the supervisor.
  *
@@ -406,6 +417,20 @@ export async function syncWindowVisibility(page) {
 // same setter/getter pattern as setChromeUserAgent in chromeFetch.ts. Both accessors are hoisted function declarations, so this call reads them at module
 // evaluation time regardless of where they sit in the file. No clock is supplied, so login runs on the system clock the port defaults to.
 setLoginDeps({ getBrowserInstance, syncWindowVisibility });
+/**
+ * Composes the system status the SSE bus carries. A browser reads as connected only when one is published and its connection is live, and the memory readings
+ * carry only the figures the status reports.
+ * @param facts - The browser and capture state and the process and registry readings, read at the moment the status is composed.
+ * @returns The system status.
+ */
+export function composeSystemStatus(facts) {
+    return {
+        browser: { captureImpaired: facts.captureImpaired, connected: facts.browser?.connected ?? false, pageCount: facts.pageCount },
+        memory: { heapUsed: facts.memory.heapUsed, rss: facts.memory.rss },
+        streams: { active: facts.streams.active, limit: facts.streams.limit },
+        uptime: facts.uptime
+    };
+}
 /**
  * Computes the current system status and emits it to SSE subscribers. Called when browser state changes significantly or when streams are added/removed.
  */
@@ -423,36 +448,20 @@ export async function emitCurrentSystemStatus() {
     catch (_error) {
         // Ignore errors getting page count.
     }
-    const memUsage = process.memoryUsage();
-    const status = {
-        browser: {
-            /* Read at compose time, beside the connectivity read below rather than as a snapshot taken before the page-count await. This function is called un-awaited
-             * from many sites, so two calls can be in flight around the instant a mark lands; a pre-mark snapshot settling after the mark's own emit would broadcast
-             * false over the cached true and the dedupe would honor it. Reading here makes every emit describe the state at the moment consumers receive it, so the
-             * later of two racing emits is also the truer one.
-             */
-            captureImpaired: supervisor.captureImpairment() !== null,
-            connected: !!browser && browser.connected,
-            pageCount
-        },
-        memory: {
-            heapUsed: memUsage.heapUsed,
-            rss: memUsage.rss
-        },
-        streams: {
-            active: getStreamCount(),
-            limit: CONFIG.streaming.maxConcurrentStreams
-        },
-        uptime: process.uptime()
-    };
-    emitSystemStatusChanged(status);
+    /* The capture-impairment mark is read here, at compose time, beside the connectivity the composer reads, rather than as a snapshot taken before the page-count
+     * await. This function is called un-awaited from many sites, so two calls can be in flight around the instant a mark lands; a pre-mark snapshot settling after
+     * the mark's own emit would broadcast false over the cached true and the dedupe would honor it. Reading here makes every emit describe the state at the moment
+     * consumers receive it, so the later of two racing emits is also the truer one.
+     */
+    emitSystemStatusChanged(composeSystemStatus({ browser, captureImpaired: supervisor.captureImpairment() !== null, memory: process.memoryUsage(), pageCount,
+        streams: { active: getStreamCount(), limit: CONFIG.streaming.maxConcurrentStreams }, uptime: process.uptime() }));
 }
 /**
  * Registers a page as managed by PrismCast. This should be called immediately after creating a page via browser.newPage(). Registered pages are tracked for stale
  * page cleanup, while unregistered pages (manually opened, site popups, etc.) are left alone.
  *
- * 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.
+ * Each registered page receives a unique ID that persists for the page's lifetime, read back through the Page reference by getManagedPageId. The staleness map,
+ * the in-flight set and the stale page cleanup's decision core all work on this stable string key rather than on Page objects.
  * @param page - The Puppeteer Page to register.
  * @param options - Registration options. Set inFlight when an operation owns the page for its duration but nothing the stale page cleanup reads records that
  *   ownership - a stream setup that has not yet written its page into the registry, or a discovery walk whose page belongs to no stream at all - so the cleanup
@@ -508,11 +517,7 @@ function clearPageTracking() {
 }
 /**
  * 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).
- *
- * The data directory stores:
- * - Chrome profile data (cookies, local storage, session state)
- * - Extension files (when running as a packaged executable)
+ * directory, browser launch above all, because the directory holds the Chrome profile data (cookies, local storage, session state).
  */
 export async function ensureDataDirectory() {
     try {
@@ -524,7 +529,7 @@ export async function ensureDataDirectory() {
         throw error;
     }
     // Purge on-disk artifacts retired in earlier releases. The data directory is the right boundary for this work - it runs once per startup, after the directory
-    // exists, before any subsequent step reads it. Future retirements add a single line to purgeLegacyArtifacts; the call site here does not change.
+    // exists, before any subsequent step reads it. Future retirements add an entry to RETIRED_ARTIFACTS; neither purgeLegacyArtifacts nor this call site changes.
     await purgeLegacyArtifacts();
 }
 const RETIRED_ARTIFACTS = [
@@ -577,6 +582,38 @@ async function purgeLegacyArtifacts() {
 function syncSleep(ms) {
     Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
 }
+/**
+ * Reports whether a process's command line runs Chrome on the given profile directory: the first stage of the kill filter and of the holder test, so they agree
+ * on which processes are on the profile.
+ * @param commandLine - The process's command line as the OS reports it.
+ * @param profileDir - The Chrome user-data-dir to match against.
+ * @returns True when the command line carries the profile flag for exactly that directory.
+ */
+function usesProfile(commandLine, profileDir) {
+    const target = "--user-data-dir=" + profileDir;
+    // Chrome puppeteer launches with --user-data-dir=<path> (equals form, no quotes). We also verify the character following the path is whitespace or
+    // end-of-string, otherwise "/x/y" would match "--user-data-dir=/x/yz".
+    const idx = commandLine.indexOf(target);
+    if (idx === -1) {
+        return false;
+    }
+    const after = commandLine.charAt(idx + target.length);
+    return (after === "") || (after === " ") || (after === "\t");
+}
+/**
+ * Reports whether a Chrome process on our profile is ours to terminate: the ownership stage of the kill filter, and the stage the holder test reads to decide
+ * which Chrome the sweep spares, so the sweep never keeps the files of a Chrome it ends nor removes those of one it spares. The parent-child relationship in the
+ * OS process table is the ownership proof, so no in-memory flag is consulted.
+ * @param entry - The process-table row of a Chrome process on our profile.
+ * @param ownPid - The current process's PID.
+ * @param isProcessAlive - Predicate that returns true when the given PID is currently a live process.
+ * @returns True when we spawned the process or its parent is no longer alive.
+ */
+function isOwnedChrome(entry, ownPid, isProcessAlive) {
+    // Ours if we spawned it (ppid is us) or if its parent is no longer alive (orphaned from a previous PrismCast that died). A live unrelated parent owns it, not
+    // us.
+    return (entry.ppid === ownPid) || !isProcessAlive(entry.ppid);
+}
 /**
  * Identifies Chrome processes that this PrismCast instance is responsible for terminating. The filter has two stages: command-line discovery (anything using
  * our profile directory) followed by ownership verification (we spawned it, or its parent is no longer alive). The ownership stage is structural - we do not
@@ -592,22 +629,25 @@ function syncSleep(ms) {
  * @returns The PIDs to terminate, in process-table order.
  */
 export function findChromeProcessesUsingProfile(processes, profileDir, ownPid, isProcessAlive) {
-    const target = "--user-data-dir=" + profileDir;
-    return processes.filter((p) => {
-        // Stage 1: command-line match. Chrome puppeteer launches with --user-data-dir=<path> (equals form, no quotes). We also verify the character following
-        // the path is whitespace or end-of-string, otherwise "/x/y" would match "--user-data-dir=/x/yz".
-        const idx = p.commandLine.indexOf(target);
-        if (idx === -1) {
-            return false;
-        }
-        const after = p.commandLine.charAt(idx + target.length);
-        if ((after !== "") && (after !== " ") && (after !== "\t")) {
-            return false;
-        }
-        // Stage 2: ownership verification. Kill if we spawned it (ppid is us) or if its parent is no longer alive (orphaned from a previous PrismCast that died).
-        // Skip if its parent is a live unrelated PID - that process owns it, not us.
-        return (p.ppid === ownPid) || !isProcessAlive(p.ppid);
-    }).map((p) => p.pid);
+    return processes.filter((p) => usesProfile(p.commandLine, profileDir) && isOwnedChrome(p, ownPid, isProcessAlive)).map((p) => p.pid);
+}
+/**
+ * Finds a live Chrome outside this process that holds our profile directory. A Chrome holds the profile when it roots a tree of processes on the profile and the
+ * kill filter's ownership stage spares it, its parent alive and not this process. The test reads the root because Chrome's helpers carry the profile flag with
+ * the Chrome main as their parent, so a helper's parent, the main, is a live process that is not this one, and every helper of this process's own Chrome would
+ * otherwise read as a holder. It reads the ownership stage rather than a liveness test of its own so it stays in step with the kill filter: the sweep never keeps
+ * the files of a Chrome it ends nor removes those of one it spares. A helper whose parent lacks the profile flag reads as a root, so that error keeps the lock files
+ * rather than removing them, and the next sweep with no Chrome alive removes them.
+ * @param processes - The current process table snapshot: the sweep's scan from before its kill loop, or the teardown's scan once its Chrome has exited.
+ * @param profileDir - The Chrome user-data-dir to match against.
+ * @param ownPid - The current process's PID (a Chrome whose parent is us is ours, never a holder).
+ * @param isProcessAlive - Predicate that returns true when the given PID is currently a live process. Injected so tests do not depend on real PIDs.
+ * @returns The PID of the first holder in process-table order, or null when no live Chrome outside this process holds the profile.
+ */
+export function findProfileHolder(processes, profileDir, ownPid, isProcessAlive) {
+    const onProfile = processes.filter((p) => usesProfile(p.commandLine, profileDir));
+    const profilePids = new Set(onProfile.map((p) => p.pid));
+    return onProfile.find((p) => !profilePids.has(p.ppid) && !isOwnedChrome(p, ownPid, isProcessAlive))?.pid ?? null;
 }
 /**
  * Ensures a clean slate for browser launch by terminating any stale Chrome processes and removing orphaned profile lock files. Chrome locks its profile
@@ -620,8 +660,9 @@ export function findChromeProcessesUsingProfile(processes, profileDir, ownPid, i
  * process exit handler: Chrome may be running normally (e.g., after a capture probe timeout) and an immediate SIGKILL would corrupt its profile databases,
  * poisoning the Docker volume for subsequent container restarts.
  *
- * The ownership filter makes this function safe to call from any context, including a rejected-duplicate startup's exit handler: a duplicate that never
- * spawned Chrome will find nothing matching its ownership criteria and signal nothing.
+ * The ownership filter and the holder test together make this function safe to call from any context, including a rejected-duplicate startup's exit handler: a
+ * duplicate that never spawned Chrome finds nothing matching its ownership criteria, signals nothing, and leaves the profile's lock files to the live Chrome
+ * that holds them.
  *
  * Called at startup before launching the browser and from the process exit handler as a crash recovery fallback. Safe to call when no stale processes or files
  * exist - the discovery and lock-file cleanup are both no-ops in the empty case.
@@ -629,7 +670,10 @@ export function findChromeProcessesUsingProfile(processes, profileDir, ownPid, i
 export function killStaleChrome() {
     const profileDir = getChromeDataDir(CONFIG);
     const POLL_INTERVAL_MS = 200;
-    const pidsToKill = findChromeProcessesUsingProfile(listProcesses(), profileDir, process.pid, isProcessRunning);
+    // The kill filter and the lock-file removal's holder test read the one scan taken before the kill loop, because a scan after it would read the helpers of each
+    // Chrome the loop ends, adopted by a live process once their main exits, as live holders.
+    const processes = listProcesses();
+    const pidsToKill = findChromeProcessesUsingProfile(processes, profileDir, process.pid, isProcessRunning);
     for (const pid of pidsToKill) {
         try {
             // Send SIGTERM first to give Chrome a chance to flush its profile databases (LevelDB, extension state, session storage) before exiting. This is critical
@@ -652,15 +696,13 @@ export function killStaleChrome() {
             }
         }
         catch (error) {
-            // ESRCH means the process does not exist - expected when there are no stale processes from a clean shutdown, or in Docker where the PID belongs to a
-            // previous container's PID namespace.
+            // ESRCH means the process exited between the process-table scan above and the signal, which is a benign race.
             if (error.code !== "ESRCH") {
                 LOG.warn("Failed to signal Chrome process %d: %s.", pid, formatError(error));
             }
         }
     }
-    // Remove stale lock and port files left behind by an unclean Chrome exit.
-    cleanStaleProfileFiles(profileDir);
+    cleanStaleProfileFiles(processes, profileDir);
 }
 /**
  * Polls until the Chrome process with the given PID has exited, or the timeout expires. Uses process.kill(pid, 0) to check process existence - throws ESRCH
@@ -682,12 +724,23 @@ function waitForChromeExit(pid, timeoutMs, pollIntervalMs) {
     return !isProcessRunning(pid);
 }
 /**
- * Removes stale Chrome profile lock files and the DevTools port file. Chrome writes these while running and removes them on clean shutdown, but an unclean exit
- * (container kill, SIGKILL, crash) leaves them behind. Stale lock files prevent Chrome from acquiring the profile, and a stale DevToolsActivePort can confuse the
- * Puppeteer connection.
+ * Removes the profile's lock files and the DevTools port file unless a live Chrome outside this process holds the profile. Chrome writes these while running and
+ * removes them on clean shutdown, but an unclean exit (container kill, SIGKILL, crash) leaves them behind. Stale lock files prevent Chrome from acquiring the
+ * profile, and a stale DevToolsActivePort can confuse the Puppeteer connection. This is the one removal of those files, so each caller, the stale-Chrome sweep and
+ * the teardown primitive, reaches them through the holder test, and none removes them from under a live holder.
+ * @param processes - The process table the holder test reads: the sweep's scan from before its kill loop, or the teardown's scan once its Chrome has exited.
  * @param profileDir - The Chrome user data directory path.
  */
-function cleanStaleProfileFiles(profileDir) {
+export function cleanStaleProfileFiles(processes, profileDir) {
+    const holder = findProfileHolder(processes, profileDir, process.pid, isProcessRunning);
+    /* The lock and port files belong to whichever Chrome holds the profile, so they are stale only when no live Chrome outside this process holds it. Removing
+     * them from under a live holder, such as the instance a refused second start found, would let the next Chrome launched on the profile start beside the
+     * running one instead of meeting its singleton.
+     */
+    if (holder !== null) {
+        LOG.debug("browser:lifecycle", "Kept the profile lock files of live Chrome process %d.", holder);
+        return;
+    }
     // Chrome's profile lock mechanism uses three symlinks: SingletonLock (hostname-PID pair), SingletonCookie (numeric verification token), and SingletonSocket
     // (path to the IPC socket). All three must be removed for Chrome to acquire a fresh lock. DevToolsActivePort contains the debugging port from the previous
     // session and is irrelevant when launching a new browser instance.
@@ -893,9 +946,9 @@ export function buildLaunchOptions() {
         executablePath: getExecutablePath(),
         /* PrismCast owns process signals, so the launcher's own listeners are off. Left on, the puppeteer launcher installs handlers for SIGHUP, SIGINT, and SIGTERM
          * on the node process and, on SIGTERM or SIGHUP, ends Chrome's entire process group with SIGKILL - and on SIGINT it kills the group and then exits the process
-         * outright. Either way it races the shutdown handlers in app.ts and preempts closeBrowserInstance's SIGTERM ladder below, so Chrome gets no shutdown at all
-         * and forfeits whatever it had pending: a window placement inside its save debounce, its session state. With the listeners off, a signal reaches PrismCast's
-         * own handler, the graceful path runs, and Chrome exits through the ladder with its pending writes committed.
+         * outright. Each of them races the shutdown handler app.ts installs for the same signal and preempts closeBrowserInstance's SIGTERM ladder below, so Chrome
+         * gets no shutdown at all and forfeits whatever it had pending: a window placement inside its save debounce, its session state. With the listeners off, every
+         * one of these signals reaches PrismCast's own handlers, the graceful path runs, and Chrome exits through the ladder with its pending writes committed.
          */
         handleSIGHUP: false,
         handleSIGINT: false,
@@ -929,8 +982,8 @@ export function buildLaunchOptions() {
             "--enable-blink-features=IdleDetection",
             "--mute-audio"
         ],
-        // Use pipe mode for browser communication instead of WebSocket. Pipe mode is faster and more reliable, especially under load. It uses stdin/stdout for
-        // the DevTools Protocol connection rather than a network socket.
+        // Use pipe mode for browser communication instead of WebSocket. Pipe mode is faster and more reliable, especially under load. It runs the DevTools Protocol
+        // over a dedicated pair of pipes (file descriptors 3 and 4) rather than a network socket.
         pipe: true,
         // Persistent user data directory for Chrome profile. This directory stores cookies, local storage, and other session data. By persisting this across
         // restarts, sites remember login state and don't require re-authentication.
@@ -981,6 +1034,32 @@ export async function emulateCaptureSurface(page) {
 export async function emulateLayoutSurface(page) {
     return declareSurface(page, NATIVE_DENSITY);
 }
+/**
+ * Re-issues a capture page's own standing device-metrics override. Chrome composes the capture of a selected tab from the window's fitted presentation rather than
+ * from the emulated surface, and re-sending the page's standing override is what moves the composition back to the emulated surface, while a capture already
+ * composing that surface is left exactly as it was. Callable at any time, from anywhere, at any frequency, because the values sent are the ones Puppeteer has
+ * already declared on this page - nothing about the page's emulation changes.
+ *
+ * The re-issue goes through the page's own emulation session, the one Puppeteer keeps on the page's primary target, because the override is only as durable as
+ * the session that holds it and Chrome restores the window's view size when a session that declared one detaches.
+ * @param page - The page to re-affirm. A page carrying no explicitly declared density is left alone.
+ * @throws Whatever the viewport setter rejects with. Each trigger site decides whether that matters to it.
+ */
+export async function reaffirmCaptureSurface(page) {
+    /* An explicitly declared, positive density is precisely the mark of a capture page, which is what makes this function safe to fire at any page from any trigger.
+     * A page PrismCast has not emulated carries no viewport at all and falls out on the first test; a page emulated for layout declares the display's own density
+     * through Chrome's disable value of 0, which the positive test excludes.
+     */
+    const viewport = page.viewport();
+    if (!viewport) {
+        return;
+    }
+    const deviceScaleFactor = viewport.deviceScaleFactor;
+    if ((typeof deviceScaleFactor !== "number") || !(deviceScaleFactor > 0)) {
+        return;
+    }
+    await page.setViewport(viewport);
+}
 /**
  * Derives the creation bounds for a window that should open exactly where an existing window rests. The four numbers always travel, so the new window lands on
  * the same frame. The state travels only when it is "maximized", because that is the one state Chrome saves alongside the frame and a maximized window mirrored
@@ -1164,27 +1243,6 @@ export function healActivatedCaptureTab(tabId, deps = { getAllStreams, getCached
 onTabActivation((tabId) => {
     healActivatedCaptureTab(tabId);
 });
-/**
- * Custom launch function that modifies Chrome arguments when running as a packaged executable. The packaged version cannot load extensions from node_modules
- * (which is bundled inside the executable), so we point the extension paths to our extracted extension files in the data directory.
- * @param opts - The launch options to modify.
- * @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. 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.
-        opts.args = (opts.args ?? [])
-            .filter((arg) => !arg.startsWith("--load-extension=") && !arg.startsWith("--disable-extensions-except="))
-            .concat(["--disable-extensions-except=" + extensionPath, "--load-extension=" + extensionPath]);
-    }
-    return puppeteerLaunch(opts);
-}
 /**
  * Formats the GPU capabilities into a human-readable suffix for the "Chrome ready" log line. The renderer string is already cleaned (ANGLE wrapper and Metal
  * prefix stripped) at detection time, so this function uses it directly and appends hardware-accelerated codec names in brackets when available.
@@ -1249,7 +1307,8 @@ async function detectBrowserCapabilities(browser) {
                     return ext ? String(gl.getParameter(ext.UNMASKED_RENDERER_WEBGL)) : String(gl.getParameter(gl.RENDERER));
                 });
                 // Extract the meaningful GPU name. ANGLE wraps the actual GPU identity: "ANGLE (Vendor, GPU Name, API Version)". The GPU name is the second
-                // comma-separated field. For non-ANGLE renderers, use the device string from CDP.
+                // comma-separated field. A non-ANGLE renderer string is used as is, and the device string from CDP is used only when WebGL reports the masked
+                // "WebKit WebGL" or nothing at all.
                 let renderer = webglRenderer;
                 const anglePart = /^ANGLE \([^,]+, ([^,]+)/.exec(webglRenderer)?.[1];
                 if (anglePart) {
@@ -1373,7 +1432,7 @@ function relinquishBrowserReadiness(streamTerminationReason) {
  */
 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.
+    // server shutdown, where app.ts shutdown() (or closeBrowser() as a fallback) set the flag and the disconnect is intentional.
     if (!gracefulShutdownInProgress) {
         LOG.error("Browser disconnected unexpectedly. All active streams will be terminated.");
     }
@@ -1434,23 +1493,36 @@ async function launchReadyBrowser() {
     // Seed the profile's extension developer-mode flag before Chrome reads the profile. Chrome loads the unpacked capture extension only when the flag is set, and
     // this is the one function every launch passes through, so it is also the only place that runs before the first-ever launch on a fresh install.
     seedProfilePreferences(getChromeDataDir(CONFIG));
-    // 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());
+    // The launch function from puppeteer-stream wraps a standard Puppeteer launch to inject the streaming extension. We hand it puppeteer-core's own launch as its
+    // launch port, so the browser comes from the puppeteer-core this module depends on rather than whichever copy puppeteer-stream resolves for itself. This happens
+    // on first stream request, after a browser crash, during server warmup, or during a governed relaunch.
+    const browser = await launch({ launch: puppeteerLaunch }, buildLaunchOptions());
     try {
         LOG.debug("timing:browser", "Chrome process spawned. (+%sms)", browserElapsed());
-        // 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 capture acquisition 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.
+        // The init timeout is live, so it is read once per launch: the error below then names the bound the wait applied, and a save made during a handshake applies
+        // at the next launch.
+        const initTimeout = CONFIG.browser.initTimeout;
+        /* 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 capture acquisition would hang, so the instance is not capture-ready and must not be published.
+         *
+         * Each step throws a CaptureLaunchError whose message states what that step saw, with the underlying error as its cause. The type, not the wording, is what
+         * earns the 503 back-off at the setup layer (the same answer the capability-tier probe failure gets), 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.
+         */
+        let extensionPage;
         try {
-            const extensionPage = await getExtensionPage(browser);
-            await extensionPage.waitForFunction(EXTENSION_READY_EXPRESSION, { timeout: CONFIG.browser.initTimeout });
+            extensionPage = await getExtensionPage(browser);
         }
-        catch (handshakeError) {
-            throw new Error("The capture extension handshake timed out after " + String(CONFIG.browser.initTimeout) + " ms.", { cause: handshakeError });
+        catch (error) {
+            throw new CaptureLaunchError("The capture extension page did not open.", { cause: error });
+        }
+        try {
+            await extensionPage.waitForFunction(EXTENSION_READY_EXPRESSION, { timeout: initTimeout });
+        }
+        catch (error) {
+            throw new CaptureLaunchError("The capture extension did not become ready within " + String(initTimeout) + " ms.", { cause: error });
         }
         LOG.debug("timing:browser", "Extension initialized. (+%sms)", browserElapsed());
         /* The tab the window rests on. It is created once and selected by construction because nothing asks otherwise, so whatever the window shows when nothing has
@@ -1578,8 +1650,9 @@ export async function getBrowserPages() {
  *
  * Chrome termination uses Puppeteer's ChildProcess handle and its `exit` event for detection:
  *
- * - 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.
+ * - browser.close() first runs puppeteer-stream's pass that closes every page but the extension's capture page and queries the extension's tabs, then sends CDP
+ *   Browser.close and waits for Chrome's process to exit, with no bound of its own on that wait.
+ * - browser.disconnect() drops the DevTools connection 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.
  *
@@ -1605,25 +1678,27 @@ async function closeBrowserInstance(browser) {
         // 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 bound. Escalate to SIGKILL. Orphaned Chrome processes (from a crashed parent or previous container) may not
-            // respond to SIGTERM.
+            // SIGTERM didn't work within the bound. Escalate to SIGKILL. A wedged or hung Chrome can fail to exit on SIGTERM within the bound.
             LOG.debug("browser:lifecycle", "Chrome did not exit after SIGTERM. Escalating to SIGKILL.");
             chromeProcess.kill("SIGKILL");
             // 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. We catch the rejection: disconnect() on a connection whose underlying transport already died of
+    // Disconnect Puppeteer's DevTools connection (the CDP pipe) after Chrome has exited. This cleans up Puppeteer's internal state (event listeners, pending CDP
+    // calls) without waiting for an orderly close 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));
+    /* The lock files go through the holder test on a scan taken here, once this process's Chrome has exited, because only a scan after the exit can see a Chrome
+     * another instance launched on a shared profile in its place. This process's own Chrome never reads as that holder: a main still running after the bounded
+     * waits is ours by the ownership test, and its helpers are not roots. A helper still shutting down after its main exited has been adopted by a live process
+     * and reads as a holder, so that teardown keeps the files, the adopted-orphan limit the sweep shares, and the next startup sweep with no Chrome alive removes them.
+     */
+    cleanStaleProfileFiles(listProcesses(), 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
@@ -1659,8 +1734,8 @@ export async function closeBrowser() {
  * 1. Only managed pages: We only consider pages that PrismCast created (tracked in managedPageIds). Pages opened manually by the user for debugging, or pages opened
  *    by streaming sites (OAuth popups, etc.) are left alone.
  *
- * 2. Target ID comparison: We use target IDs (strings) instead of Page object references for comparison. Puppeteer may return different wrapper objects for the
- *    same underlying page, making reference comparison unreliable.
+ * 2. Managed page IDs: Each managed page is assigned a string ID ("page-" plus a counter) by registerManagedPage and read back through the Page reference by
+ *    getManagedPageId. The staleness map, the in-flight set and the decision core all work on these stable string keys rather than on Page objects.
  *
  * 3. Grace period: Pages must be observed as potentially stale for a configurable grace period before being closed. This handles race conditions where pages are
  *    briefly untracked during stream initialization or cleanup.
@@ -1756,32 +1831,62 @@ export async function cleanupStalePages(now) {
         }
     }
     catch (error) {
-        // Cleanup failure is not critical - log a warning and try again next interval.
+        // Cleanup failure is not critical - log it at debug level and let the next interval retry.
         LOG.debug("browser:lifecycle", "Stale page cleanup failed: %s.", formatError(error));
     }
 }
+/**
+ * Arms the stale-page sweep's interval on the owner's registry: cleanupStalePages at the owner's clock reading, every interval. Arming under the sweep's key
+ * replaces an interval already armed there, so a re-arm leaves one sweep, on the new cadence from the moment it is armed.
+ * @param sweep - The running stale-page owner.
+ * @param interval - Milliseconds between sweeps.
+ */
+function armStalePageSweep(sweep, interval) {
+    sweep.timers.setInterval(STALE_PAGE_SWEEP_KEY, () => { void cleanupStalePages(sweep.clock.now()); }, interval);
+}
 /**
  * Starts the periodic stale page cleanup. This should be called once during server startup, after the browser is initialized. The sweep runs indefinitely until
- * stopStalePageCleanup() is called (typically during graceful shutdown). A second start while one is running changes nothing.
+ * stopStalePageCleanup() is called (typically during graceful shutdown), and a saved interval re-arms it through applyStalePageCleanupChanges(). A second start
+ * while one is running changes nothing.
  * @param clock - The clock the sweep's interval arms on and whose reading each sweep judges staleness against, so the cadence and the judgment share one time
  * source. Defaults to the system clock.
  */
 export function startStalePageCleanup(clock = systemClock) {
-    if (stalePageTimers) {
+    if (stalePageSweep) {
         return;
     }
-    const timers = new TimerRegistry({ clock });
-    timers.setInterval(STALE_PAGE_SWEEP_KEY, () => { void cleanupStalePages(clock.now()); }, CONFIG.recovery.stalePageCleanupInterval);
-    stalePageTimers = timers;
+    const sweep = { clock, timers: new TimerRegistry({ clock }) };
+    armStalePageSweep(sweep, CONFIG.recovery.stalePageCleanupInterval);
+    stalePageSweep = sweep;
 }
 /**
  * Stops the periodic stale page cleanup. This should be called during graceful shutdown to prevent the sweep from running after we've started shutting down the
  * browser and streams. Disposing the registry drains the interval, and a stop with nothing running is a no-op.
  */
 export function stopStalePageCleanup() {
-    stalePageTimers?.dispose();
-    stalePageTimers = null;
+    stalePageSweep?.timers.dispose();
+    stalePageSweep = null;
+}
+/**
+ * Re-arms the running stale-page sweep at a saved cleanup interval. The re-arm restarts the cadence from the save, so the next sweep runs one full interval after
+ * it, and the grace period needs nothing here, because each sweep already reads it when it runs. The handler reads the running sweep and never creates one, so a
+ * save before the boot's start or after the stop arms nothing, and a save can never resurrect a stopped sweep. The interval comes from the candidate, because
+ * the reconcile commits CONFIG only after its handlers run. Re-arming cannot fail, so the handler refuses nothing.
+ * @param _changes - The change to the cleanup interval; the candidate carries the interval, so the handler reads that instead.
+ * @param next - The candidate running configuration.
+ * @returns No rejections.
+ */
+export async function applyStalePageCleanupChanges(_changes, next) {
+    if (stalePageSweep) {
+        const interval = next.recovery.stalePageCleanupInterval;
+        armStalePageSweep(stalePageSweep, interval);
+        LOG.debug("browser:lifecycle", "Stale page cleanup re-armed at %d ms.", interval);
+    }
+    return [];
 }
+// Module-load side effect: register the handler once per process, as every config-change handler registers, so it is in place before the first save can reach
+// the reconcile.
+registerConfigChangeHandler("recovery.stalePageCleanupInterval", applyStalePageCleanupChanges);
 /**
  * Decides whether the browser may be torn down for the given cause, from facts read at the call. Each cause asks a different question of the same registry, so
  * the decision is stated once here rather than spelled out at each guard.
@@ -1814,6 +1919,23 @@ export function isBrowserIdleForRestart(cause, facts) {
 function readRestartFacts() {
     return { establishedStreams: hasEstablishedStreams(), inFlightPages: inFlightPageIds.size, streamCount: getStreamCount() };
 }
+/**
+ * Decides what a restart check's tick does about the maintenance quiet period. A browser younger than BROWSER_MAX_AGE needs no maintenance, so the tick leaves
+ * the countdown as it stands. An old browser with streams registered waits for them: a countdown already running is cancelled, so a stream that starts during
+ * the quiet period resets it, and with no countdown running there is nothing to do. An old browser with an empty registry starts the countdown, unless one is
+ * already running.
+ * @param facts - The browser's age, the registry's size and the countdown's state, read at the tick.
+ * @returns The action the tick takes.
+ */
+export function decideRestartQuietPeriod(facts) {
+    if (facts.age < BROWSER_MAX_AGE) {
+        return "skip";
+    }
+    if (facts.streamCount > 0) {
+        return facts.quietPending ? "cancel" : "skip";
+    }
+    return facts.quietPending ? "skip" : "arm";
+}
 /**
  * Relaunches a browser that can no longer start captures, as soon as nothing depends on it. Every trigger routes here - the mark itself, each stream termination,
  * and the periodic restart check as the backstop for a moment when the other two could not act (login mode above all) - so the decision lives in one place rather
@@ -1839,18 +1961,17 @@ export async function restartBrowserIfImpairedAndIdle() {
 /**
  * Checks whether the browser qualifies for a 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 ready. A marked browser is handed to the impairment path and the tick ends there. Otherwise the
- * tick drives the supervisor's health-gated governor reset and applies the maintenance rules: skip below the age threshold, cancel any pending quiet timer while
- * active streams exist (streams started during the quiet period reset the countdown), and otherwise start a quiet timer if one is not already running.
+ * tick drives the supervisor's health-gated governor reset and carries out what decideRestartQuietPeriod decides about the maintenance quiet period.
  * @param timers - The restart owner's registry, whose quiet period this check arms and reads. Handed in by the interval closure, so the check never reads the
  * nullable module binding and needs no null branch of its own.
+ * @param clock - The clock the check was started with, which the browser's age is measured on.
  */
-function checkBrowserRestart(timers) {
+function checkBrowserRestart(timers, clock) {
     // 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 read from the supervisor's clock (systemClock.now), so age is measured against that same clock rather than against any other time source.
+    // 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."
     const browser = supervisor.current();
     const launchTime = supervisor.currentLaunchTime();
     if (!browser?.connected || (launchTime === null)) {
@@ -1870,31 +1991,32 @@ function checkBrowserRestart(timers) {
     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 = systemClock.now() - launchTime;
-    if (age < BROWSER_MAX_AGE) {
-        return;
-    }
-    // If there are active streams, cancel any pending quiet timer and return. Streams that start during the quiet period reset the countdown.
-    if (getStreamCount() > 0) {
-        if (timers.has(RESTART_QUIET_KEY)) {
+    /* The age is measured on the clock this check was started with. The supervisor stamps the launch time on the system clock, which is the clock production
+     * starts the check with, so in production the launch time and the reading it is subtracted from come from the same source.
+     */
+    const action = decideRestartQuietPeriod({ age: clock.now() - launchTime, quietPending: timers.has(RESTART_QUIET_KEY), streamCount: getStreamCount() });
+    switch (action) {
+        case "arm": {
+            LOG.debug("browser:lifecycle", "Browser uptime exceeds threshold. Quiet period started - restart will proceed if no streams start within %s minutes.", Math.round(BROWSER_RESTART_QUIET_PERIOD / 60000));
+            timers.setTimeout(RESTART_QUIET_KEY, () => {
+                void executeBrowserRestart("maintenance");
+            }, BROWSER_RESTART_QUIET_PERIOD);
+            break;
+        }
+        case "cancel": {
             LOG.debug("browser:lifecycle", "Browser restart quiet period cancelled - streams are active.");
+            cancelRestartQuietTimer();
+            break;
+        }
+        case "skip": {
+            break;
         }
-        cancelRestartQuietTimer();
-        return;
-    }
-    // No active streams and the browser is old enough. Start the quiet timer if one is not already running.
-    if (!timers.has(RESTART_QUIET_KEY)) {
-        LOG.debug("browser:lifecycle", "Browser uptime exceeds threshold. Quiet period started - restart will proceed if no streams start within %s minutes.", Math.round(BROWSER_RESTART_QUIET_PERIOD / 60000));
-        timers.setTimeout(RESTART_QUIET_KEY, () => {
-            void executeBrowserRestart("maintenance");
-        }, BROWSER_RESTART_QUIET_PERIOD);
     }
 }
 /**
- * Executes a browser restart: a final guard check, then the current instance is retired and torn down and a fresh one is launched in its place. Every cause shares
- * that whole sequence; only the log line that announces the restart differs, since only the cause knows why the browser is being replaced.
- * @param cause - Why the restart is running, for the announcement.
+ * Executes a browser restart: a final guard check, then the current instance is retired and torn down and a fresh one is launched in its place. The guard's
+ * idleness test and the log line that announces the restart both depend on the cause; the teardown and relaunch sequence is shared by every cause.
+ * @param cause - Why the restart is running, for the guard's idleness test and the announcement.
  */
 async function executeBrowserRestart(cause) {
     // Retire any pending quiet period. For a maintenance restart this is the timer that just fired, and clearing a fired handle costs nothing. For an impairment
@@ -1960,14 +2082,14 @@ async function executeBrowserRestart(cause) {
 /**
  * Starts the periodic browser restart eligibility check. This should be called once during server startup, after the browser is initialized. The check runs
  * indefinitely until stopBrowserRestartChecking() is called (typically during graceful shutdown). A second start while one is running changes nothing.
- * @param clock - The clock the check's interval and the quiet period it arms both run on. Defaults to the system clock.
+ * @param clock - The clock the check's interval and the quiet period it arms both run on, and the browser's age is measured on. Defaults to the system clock.
  */
 export function startBrowserRestartChecking(clock = systemClock) {
     if (restartTimers) {
         return;
     }
     const timers = new TimerRegistry({ clock });
-    timers.setInterval(RESTART_CHECK_KEY, () => { checkBrowserRestart(timers); }, BROWSER_RESTART_CHECK_INTERVAL);
+    timers.setInterval(RESTART_CHECK_KEY, () => { checkBrowserRestart(timers, clock); }, BROWSER_RESTART_CHECK_INTERVAL);
     restartTimers = timers;
 }
 /**
@@ -1978,61 +2100,6 @@ export function stopBrowserRestartChecking() {
     restartTimers?.dispose();
     restartTimers = null;
 }
-/* When running as a packaged executable (created by the `pkg` tool), the application is bundled into a single binary. Node modules like puppeteer-stream are
- * included in the bundle, but Chrome cannot load extensions from within the packaged binary - it needs actual files on the filesystem.
- *
- * To solve this, we extract the puppeteer-stream extension files to the application's data directory during startup. This happens only when process.pkg is
- * defined (indicating we're running as a packaged executable).
- *
- * The extracted files are:
- * - background.js: The extension's service worker that handles media capture
- * - manifest.json: The extension manifest declaring permissions and capabilities
- * - options.html/options.js: Extension options page (not used by our automation, but required by the manifest)
- */
-/**
- * Extracts the Puppeteer Stream extension files when running as a packaged executable. This copies the extension files from within the packaged binary to the
- * filesystem where Chrome can load them.
- *
- * When running from source (not packaged), this function does nothing - puppeteer-stream can load the extension directly from node_modules.
- * @throws If extension extraction fails.
- */
-export async function prepareExtension() {
-    // Only needed when running as a packaged executable.
-    if (!process.pkg) {
-        return;
-    }
-    try {
-        // The extension files are extracted to the extension directory within the data directory (ensured to exist before this function is called).
-        const out = getExtensionDir(CONFIG);
-        // Create the extension directory if it doesn't exist.
-        try {
-            await fsPromises.mkdir(out, { recursive: true });
-        }
-        catch (error) {
-            LOG.error("Failed to create extension directory: %s.", formatError(error));
-            throw error;
-        }
-        // The extension files that need to be extracted. These are the files from puppeteer-stream's extension directory.
-        const files = ["background.js", "manifest.json", "options.html", "options.js"];
-        for (const file of files) {
-            try {
-                // Copy each file from the packaged location (relative to the executable) to the data directory. The source path assumes the executable is in the
-                // same directory as node_modules (which is how pkg packages the application).
-                // eslint-disable-next-line no-await-in-loop
-                await fsPromises.copyFile(path.join(path.dirname(process.execPath), "node_modules", "puppeteer-stream", "extension", file), path.join(out, file));
-            }
-            catch (error) {
-                LOG.error("Failed to copy extension file %s: %s.", file, formatError(error));
-                throw error;
-            }
-        }
-        LOG.debug("browser:lifecycle", "Extension files prepared successfully.");
-    }
-    catch (error) {
-        LOG.error("Extension preparation failed: %s.", formatError(error));
-        throw error;
-    }
-}
 /* Re-export the capture acquisition for the streaming module. The browser directory owns every conversation with puppeteer-stream - index.ts launches it and
  * tabCapture.ts speaks its extension's protocol - so no other layer imports the library, and the streaming layer asks this module for a capture the same way it
  * asks it for a browser.