prismcast 1.12.0 → 1.13.0

package/dist/streaming/monitor.js

@@ -1,7 +1,9 @@
-import { EvaluateTimeoutError, LOG, capitalize, formatError, getAbortSignal, isPageDeathError, isSessionClosedError, runWithStreamContext, startTimer } from "../utils/index.js";
-import { RECOVERY_METHODS, checkCircuitBreaker, classifyNativeSegmentHealth, computeNextRecoveryLevel, createRecoveryMetrics, deriveStreamHealth, formatIssueType, formatRecoveryDuration, getIssueCategory, getIssueDescription, getRecoveryMethod, recordRecoveryAttempt, recordRecoverySuccess, resetCircuitBreaker, shouldTriggerRecovery } from "./recovery.js";
+import { EvaluateTimeoutError, LOG, capitalize, formatError, formatResolution, getAbortSignal, isPageDeathError, isSessionClosedError, runWithStreamContext, startTimer } from "../utils/index.js";
+import { RECOVERY_METHODS, checkCircuitBreaker, classifyNativeSegmentHealth, computeNextRecoveryLevel, createRecoveryMetrics, deriveStreamHealth, describeResolutionOutcome, formatIssueType, formatRecoveryDuration, getIssueCategory, getIssueDescription, getRecoveryMethod, isResolutionDegraded, nextNativeIssueRecord, recordRecoveryAttempt, recordRecoverySuccess, resetCircuitBreaker, resolutionAreaRatio, shouldTriggerRecovery, updateResolutionPeak } from "./recovery.js";
+import { applyNativeQualityRefresh, getLastSegmentHasVideo, getLastSegmentSize, getStream, getStreamMemoryUsage, getStreamSegmenter, isCaptureIdentity, isHardwareAccelerated, makePendingCaptureIdentity } from "./registry.js";
 import { applyVideoStyles, buildVideoSelectorType, checkVideoPresence, enforceVideoVolume, ensurePlayback, findVideoContext, getVideoState, tuneToChannel, validateVideoElement, verifyFullscreen } from "../browser/video.js";
-import { getLastSegmentHasVideo, getLastSegmentSize, getStream, getStreamMemoryUsage } from "./registry.js";
+import { getCaptureImpairment, syncWindowVisibility } from "../browser/index.js";
+import { getEffectiveCaptureCodec, isCaptureHardwareAccelerated } from "./codec.js";
 import { CONFIG } from "../config/index.js";
 import { clearNativeInitState } from "./hlsSegments.js";
 import { clearProbeCache } from "../native/probe.js";
@@ -11,8 +13,10 @@ import { getClientSummary } from "./clients.js";
 import { getPresetViewport } from "../config/presets.js";
 import { getProviderBySlug } from "../browser/channelSelection.js";
 import { getShowName } from "./showInfo.js";
-import { minimizeWindow } from "../browser/cdp.js";
+import { reaffirmCaptureSurface } from "../browser/cdp.js";
 import { refreshNativeManifest } from "../native/index.js";
+import { systemClock } from "homebridge-plugin-utils";
+const defaultMonitorDeps = { clock: systemClock, getCaptureImpairment, getEffectiveCaptureCodec, isCaptureHardwareAccelerated, syncWindowVisibility };
 /**
  * Monitors video playback health and attempts escalating recovery when issues are detected. This function runs on an interval, checking video state and triggering
  * increasingly aggressive recovery actions when playback stalls, pauses, or errors occur.
@@ -36,9 +40,11 @@ import { refreshNativeManifest } from "../native/index.js";
  * @param onTabReplacement - Optional callback for tab replacement recovery. When provided and 3+ consecutive timeouts occur, this is called to replace the hung tab.
  *                           If null/undefined, tab replacement is not available; sustained evaluate timeouts are only surfaced via status (lastIssueType) with no
  *                           automatic recovery escalation.
+ * @param deps - The injected browser-boundary collaborators; defaults to defaultMonitorDeps. Threaded so a test drives the ladder's availability decision and the
+ *               window sync without a live Chrome.
  * @returns A MonitorHandle exposing the live recovery metrics (getMetrics) and a self-contained dispose that stops the monitor's polling interval.
  */
-export function monitorPlaybackHealth(page, context, profile, url, streamId, streamInfo, onCircuitBreak, onTabReplacement) {
+export function monitorPlaybackHealth(page, context, profile, url, streamId, streamInfo, onCircuitBreak, onTabReplacement, deps = defaultMonitorDeps) {
     /* Monitor state. These track the video's behavior over time and control recovery decisions. Mutable variables are organized into typed state objects by subsystem
      * (recovery, segments, native health, resolution) to clarify ownership and interaction boundaries. Variables that don't belong to a specific subsystem remain as
      * standalone declarations.
@@ -46,6 +52,12 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
     // The current page reference. This can change after tab replacement recovery, when the old tab is closed and a new one is created. We use a mutable variable so we
     // can update the reference after replacement.
     let currentPage = page;
+    /* How many ticks pass between capture-surface re-affirmations, and the count of ticks since this stream's monitor started. Thirty ticks is about a minute at the
+     * default cadence, which is the resolution the catch-all is aiming for: fast enough that no disturbance survives long in a recording, slow enough that the
+     * command costs nothing measurable next to the health reads the same tick performs.
+     */
+    const SURFACE_REAFFIRM_TICK_INTERVAL = 30;
+    let reaffirmTickCounter = 0;
     // The video's currentTime from the previous check. Used to detect whether the video is progressing. Null on first check since we have no previous value.
     let lastTime = null;
     // Timestamp when buffering started, or null if not currently buffering. Used to apply the buffering grace period - we don't trigger recovery for buffering until
@@ -56,9 +68,6 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
     // Counter for consecutive page navigation failures. If navigation fails twice in a row, we fall back to source reload (level 2) instead. This prevents getting
     // stuck in a loop when navigation itself is the problem.
     let consecutiveNavigationFailures = 0;
-    // Track whether the browser window needs to be re-minimized after recovery. Recovery actions (especially ensureFullscreen) can cause the window to un-minimize.
-    // We set this flag when recovery is triggered and clear it after the recovery grace period passes and we see a healthy check.
-    let pendingReMinimize = false;
     // Graduated fullscreen reinforcement counter. Counts consecutive ticks where verifyFullscreen() returns false. On tick 1 we apply basic CSS styles (sufficient
     // for well-behaved sites like Hulu). On tick 2+ we escalate to !important priority to override sites that actively fight style changes. Reset to 0 when the
     // video fills the viewport again.
@@ -125,13 +134,16 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
     // appear healthy. This catches the case where Chrome's MediaRecorder silently stops emitting data without raising an error - the input stream stays "open" but no
     // data events fire. The 20-second threshold is 4x the maximum expected moof delivery interval (5 seconds) to avoid false positives during normal bursty delivery.
     const SEGMENT_STALENESS_TIMEOUT = 20000;
-    // The capture surface this stream is measured against, read once for the monitor's lifetime. The quality preset is restart-gated, so it cannot change while a
-    // stream is running, and re-deriving it on every two-second tick would be work that can only ever produce the same answer.
+    // The capture surface: the size capture encodes at, reported beside the source's own size in the status the monitor emits. Read once for the monitor's lifetime,
+    // because the quality preset is restart-gated and cannot change while a stream is running, so re-deriving it on every two-second tick would be work that can only
+    // ever produce the same answer.
     const presetViewport = getPresetViewport(CONFIG);
-    // Resolution degradation detection. When the video element's intrinsic resolution is significantly below the capture surface, the service's ABR is delivering
-    // low-quality content. The threshold is expressed as a ratio - if either dimension is below this fraction of the surface, the resolution is considered degraded.
-    // 50% catches clear ABR degradation (768x432 on 1080p = 40%) while allowing legitimate 720p content on 1080p (67% > 50%).
-    const RESOLUTION_RATIO_THRESHOLD = 0.5;
+    // Resolution degradation detection. When the video element's intrinsic resolution falls well below the best the stream has delivered, the service's ABR is stuck
+    // on a low rendition. The threshold is a fraction of that best reading by pixel area. The field's stuck renditions read 16 to 27 percent of their peaks, while
+    // an ordinary one-rung adaptive downshift - 1600x900 to 1024x576 on CNN, 41 percent by area - is a service pacing its own bitrate and heals on its own. A third
+    // sits between the two: every stuck rendition on record fails it, a one-rung dip passes it, and a source whose best is 720p is never judged against a surface
+    // it cannot fill. Each recovery this detector drives is a capture restart, so the line is drawn where the picture has actually collapsed, not merely shrunk.
+    const RESOLUTION_RATIO_THRESHOLD = 1 / 3;
     // Grace period in milliseconds after stream start and after each recovery action. Gives ABR time to ramp up before flagging degradation.
     const RESOLUTION_GRACE_PERIOD = 30000;
     // Number of consecutive degraded readings required before triggering recovery. At ~2 seconds per monitor tick, 15 readings = ~30 seconds of sustained
@@ -141,12 +153,12 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
     // navigation and video reinitialization to complete before the site enforces its cutoff.
     const PROACTIVE_RELOAD_MARGIN_MS = 120000;
     // Timestamp of the most recent full page navigation. Used to calculate elapsed continuous playback for proactive reload when maxContinuousPlayback is configured.
-    // Initialized to Date.now() because the monitor starts immediately after stream setup establishes playback, meaning a page load just completed. Reset
+    // Initialized to the clock's reading because the monitor starts immediately after stream setup establishes playback, meaning a page load just completed. Reset
     // after any successful page navigation recovery or tab replacement, but NOT after source reloads (L2) which preserve the page's JavaScript context.
-    let lastPageNavigationTime = Date.now();
+    let lastPageNavigationTime = deps.clock.now();
     // Pre-compute the selector type string for video element selection. This is passed to evaluate() calls.
     const selectorType = buildVideoSelectorType(profile);
-    // Capture stream context for re-establishing on each interval tick. AsyncLocalStorage context is lost when entering setInterval callbacks. The show name
+    // Capture stream context for re-establishing on each interval tick. AsyncLocalStorage context is lost when entering the callback timer. The show name
     // resolver is lazy - it reads from the live show name cache at log time, so messages always reflect the current program even as shows change mid-stream.
     const streamContext = {
         channelName: streamInfo.channelName ?? undefined,
@@ -165,13 +177,21 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
         stallCount: 0,
         totalAttempts: 0
     };
+    /* Whether the ladder can offer tab replacement at this moment. A replacement starts a fresh capture, which a browser marked as unable to start captures refuses,
+     * and the handler disposes the working pipeline before it asks - so on a marked browser the ladder treats replacement as unavailable and every decline site keeps
+     * the behavior it already has for a stream that was given no handler. The mark is read on each decision rather than captured once, because it can land at any
+     * point in a stream's life.
+     */
+    const canReplaceTab = () => (onTabReplacement !== undefined) && (deps.getCaptureImpairment() === null);
+    // The reason a replacement cannot proceed, put into words in one place so every message that has to explain a decline says the same thing.
+    const tabReplacementUnavailableReason = () => (onTabReplacement ? "the browser can no longer start captures" : "no tab replacement handler");
     // Segment production state. Tracks both post-recovery segment verification and continuous segment size monitoring. After L2/L3 recovery, we verify segments are
     // actually being produced. Independently, we monitor segment sizes on every tick to detect spontaneous capture pipeline death (dead pipelines produce tiny segments
     // while the video element appears healthy).
     const segmentState = {
         consecutiveTinySegments: 0,
         lastCheckedIndex: 0,
-        lastSegmentAdvanceTime: Date.now(),
+        lastSegmentAdvanceTime: deps.clock.now(),
         preRecoveryIndex: null,
         productionStalled: false,
         waitStartTime: null,
@@ -184,14 +204,15 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
         issueTime: null,
         issueType: null,
         lastCheckedSegmentIndex: 0,
-        lastSegmentAdvanceTime: Date.now(),
+        lastSegmentAdvanceTime: deps.clock.now(),
         recoveryAttempts: 0
     };
     // Resolution degradation monitoring. Separate from the recovery escalation (L1-L3 plus tab replacement) which handles broken playback. Resolution degradation is a
-    // quality issue - the stream works but at lower-than-expected resolution. Uses its own tracking and two-step escalation: page reload, then tab replacement.
+    // quality issue - the stream works but at lower than the best it has delivered. Uses its own tracking and two-step escalation: page reload, then tab replacement.
     const resolutionState = {
         consecutiveDegradedReadings: 0,
-        graceEnd: Date.now() + RESOLUTION_GRACE_PERIOD,
+        graceEnd: deps.clock.now() + RESOLUTION_GRACE_PERIOD,
+        peak: null,
         recoveryAttempt: 0
     };
     /**
@@ -208,12 +229,15 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
      * @param entry - The stream registry entry for the native stream.
      */
     function checkNativeStreamHealth(entry) {
-        const proxy = entry.nativeProxy;
-        if (!proxy) {
+        // The narrow happens here rather than being inherited from the tick's dispatch: a narrowing does not cross a function call, and the entry's identity can be
+        // replaced by a fallback that ran between the dispatch and this frame. A stream that is no longer native has nothing here to check.
+        const identity = entry.identity;
+        if (identity.mode !== "native") {
             emitStatusUpdate();
             return;
         }
-        const now = Date.now();
+        const proxy = identity.nativeProxy;
+        const now = deps.clock.now();
         const currentSegmentIndex = proxy.getSegmentIndex();
         const lastSegmentTime = proxy.getLastSegmentTime();
         const targetDuration = proxy.getTargetDuration();
@@ -222,9 +246,12 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
         // Fast path: if the proxy hit its error threshold and stopped itself, trigger L3 fallback immediately. This avoids waiting for the staleness threshold when hard
         // errors (HTTP 403, network failures) have already been detected by the proxy's internal retry loop.
         if (proxy.hasErrored()) {
-            LOG.debug("native:monitor", "Native proxy errored for %s. Initiating capture fallback.", storeKey);
             nativeHealthState.issueType = "proxy error";
             nativeHealthState.issueTime = now;
+            if (deferFallbackInsideGrace(entry, identity)) {
+                return;
+            }
+            LOG.debug("native:monitor", "Native proxy errored for %s. Initiating capture fallback.", storeKey);
             // The caller establishes the stream context for this interval tick, so the fire-and-forget recovery promise inherits it across its async continuations.
             void executeNativeL3Fallback(entry);
             return;
@@ -252,11 +279,12 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
             stalenessMs,
             targetDurationMs: targetDuration * 1000
         });
-        // Record the issue label the decision named when none is already tracked, so an earlier issue keeps its original timestamp across ticks.
-        if (decision.issueType && !nativeHealthState.issueType) {
-            nativeHealthState.issueType = decision.issueType;
-            nativeHealthState.issueTime = now;
-        }
+        /* Advance the recorded issue through the pure rule in recovery.ts: an unchanged cause keeps its original start time across ticks, and a changed cause takes
+         * both the new label and a fresh stamp. A stream that degrades from fetch errors into a segment stall therefore reports the stall it is actually in.
+         */
+        const issueRecord = nextNativeIssueRecord(nativeHealthState, decision.issueType, now);
+        nativeHealthState.issueTime = issueRecord.issueTime;
+        nativeHealthState.issueType = issueRecord.issueType;
         const staleSec = Math.round(stalenessMs / 1000);
         // Diagnostic logging mirrors the classification. The staleness threshold reported is 2x the target duration in seconds.
         if (decision.health === "recovering") {
@@ -276,42 +304,69 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
         }
         // L3: at 4x target duration once an L2 attempt has already been made and the stall persists, fall back to capture mode via tab replacement.
         if (decision.action === "l3") {
+            if (deferFallbackInsideGrace(entry, identity)) {
+                return;
+            }
             LOG.warn("Falling back to capture mode for %s: native streaming stalled after recovery attempt.", storeKey);
             // The caller establishes the stream context for this interval tick, so the fire-and-forget recovery promise inherits it across its async continuations.
             void executeNativeL3Fallback(entry);
             return;
         }
-        emitNativeStatus(entry, decision.health);
+        emitNativeStatus(entry, identity, decision.health);
+    }
+    /**
+     * Holds a native capture fallback at the decision site while the recovery grace window is open, reporting the stream as recovering instead of entering the
+     * fallback cycle. Every native trigger - a relay that stopped itself on its error threshold, a stall the ladder has escalated to its last rung - describes a
+     * condition that holds on every tick once it is true. Without this read the whole cycle - the mode pre-flip, the attempt, the revert, the window sync, the
+     * warning - would run twice a second inside a window every other trigger is respecting. Nothing is lost by waiting, since neither condition is curing itself in
+     * the meantime, and the status still goes out so the display keeps advancing. The replacement primitive's own entry gate stays the guarantee beneath this: a
+     * gate here can be forgotten, that one cannot be bypassed.
+     *
+     * The status is recovering for every trigger, because a fallback being held is a recovery in progress from the display's point of view.
+     *
+     * @param entry - The stream registry entry.
+     * @param identity - The stream's native identity, narrowed by the caller.
+     * @returns True when the fallback was held, which is the caller's signal to return without entering it.
+     */
+    function deferFallbackInsideGrace(entry, identity) {
+        if (!isWithinRecoveryGrace()) {
+            return false;
+        }
+        LOG.debug("native:monitor", "Capture fallback for %s waits for the recovery grace window to close.", entry.info.storeKey);
+        emitNativeStatus(entry, identity, "recovering");
+        return true;
     }
     /**
      * Emits a status update with native-specific health classification. Populates meaningful fields (health, issue tracking, memory, clients) and zeroes video-specific
      * fields that are not applicable to native streams.
      *
      * @param entry - The stream registry entry.
+     * @param identity - The stream's native identity, narrowed by the caller so the manifest quality members are read without a second mode test.
      * @param health - The health status to report.
      */
-    function emitNativeStatus(entry, health) {
+    function emitNativeStatus(entry, identity, health) {
         if (intervalCleared) {
             return;
         }
-        const now = Date.now();
+        const now = deps.clock.now();
         const memoryBytes = getStreamMemoryUsage(entry).total;
         const channelKey = entry.info.storeKey;
-        const clientSummary = getClientSummary(streamInfo.numericStreamId);
+        const clientSummary = getClientSummary(streamInfo.numericStreamId, now);
         // Native streams have no recovery ladder, so we reuse escalationLevel purely as a UI severity encoding rather than as a recovery-level index: healthy maps to 0,
         // stalled to 1, and recovering to 2. The intended ordering is stalled < recovering because an actively-recovering stream warrants a stronger visual signal than one
         // that has merely stalled.
         const escalation = (health === "stalled") ? 1 : ((health === "recovering") ? 2 : 0);
         const status = {
             bufferingDuration: null,
-            captureCodec: entry.captureCodec,
+            captureCodec: identity.captureCodec,
+            captureResolution: null,
             channel: streamInfo.channelName,
             clientCount: clientSummary.total,
             clients: clientSummary.clients,
             currentTime: 0,
-            duration: Math.round((now - streamInfo.startTime.getTime()) / 1000),
+            duration: Math.round((now - streamInfo.startTime) / 1000),
             escalationLevel: escalation,
-            hardwareAccelerated: entry.hardwareAccelerated,
+            hardwareAccelerated: isHardwareAccelerated(entry),
             health,
             id: streamInfo.numericStreamId,
             lastIssueTime: nativeHealthState.issueTime,
@@ -319,16 +374,17 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
             lastRecoveryTime: null,
             logoUrl: channelKey ? (getChannelLogo(channelKey) ?? "") : "",
             memoryBytes,
-            nativeBandwidth: entry.nativeBandwidth,
-            nativeResolution: entry.nativeResolution,
+            nativeBandwidth: identity.nativeBandwidth,
+            nativeResolution: identity.nativeResolution,
             networkState: 0,
             pageReloadsInWindow: 0,
             readyState: 0,
             recoveryAttempts: nativeHealthState.recoveryAttempts,
             serviceName: streamInfo.serviceName,
             showName: getShowName(streamInfo.numericStreamId),
-            startTime: streamInfo.startTime.toISOString(),
-            streamingMode: entry.streamingMode,
+            sourceResolution: null,
+            startTime: new Date(streamInfo.startTime).toISOString(),
+            streamingMode: identity.mode,
             url
         };
         emitStreamHealthChanged(status);
@@ -340,39 +396,35 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
      * @param entry - The stream registry entry.
      */
     async function executeNativeL2Recovery(entry) {
-        const proxy = entry.nativeProxy;
-        if (!proxy || proxy.isStopped()) {
+        // The narrow is taken fresh here, not inherited from the caller: this runs as a fire-and-forget continuation, and a stream that has since fallen back to
+        // capture has no manifest left to refresh.
+        const identity = entry.identity;
+        if ((identity.mode !== "native") || identity.nativeProxy.isStopped()) {
             return;
         }
+        const proxy = identity.nativeProxy;
         /* The refresh probes under the identity the tune established, which the entry holds. It is null only for a pending entry whose setup has not filled it in,
          * and a stream with a running native proxy is past that point - so this answers a window that recovery does not reach rather than papering over one.
-         * Declining is the honest response either way: an identity assembled here would stamp a binding this frame cannot see, and the stall escalates to L3.
+         * Declining is the answer either way: an identity assembled here would stamp a binding this frame cannot see, and the stall escalates to L3.
          */
         const probeIdentity = entry.probeIdentity;
         if (!probeIdentity) {
             LOG.debug("native:monitor", "Skipping L2 recovery for %s: the stream has no probe-cache identity yet.", entry.info.storeKey);
             return;
         }
-        /* The refresh's page-reload strategy re-establishes the channel through the capability the stream's setup built. A pending entry that never completed
-         * setup has none, and a recovery frame cannot assemble one - the profile closure belongs to the setup path - so the honest response is the same
-         * decline the missing probe identity takes: skip L2 and let the stall escalate on the existing ladder.
-         */
-        const reestablishManifest = entry.reestablishManifest;
-        if (!reestablishManifest) {
-            LOG.debug("native:monitor", "Skipping L2 recovery for %s: the stream has no re-establishment capability.", entry.info.storeKey);
-            return;
-        }
+        // The refresh's page-reload strategy re-establishes the channel through the capability the stream's setup built. Every write that produces a native identity
+        // supplies it, which the type states, so this frame reads it rather than testing for it.
+        const reestablishManifest = identity.reestablishManifest;
         recoveryState.inProgress = true;
         LOG.debug("native:monitor", "Starting L2 recovery (page reload) for %s.", entry.info.storeKey);
         try {
             const success = await refreshNativeManifest({
                 channelName: entry.info.storeKey,
+                clock: deps.clock,
                 onFeedApplied: (metadata) => {
                     // The registry write belongs to this layer, not to the native one: recovery already holds the entry, so a refresh that binds a different rung of the
                     // service's ladder is recorded here as the stream's current quality.
-                    entry.captureCodec = metadata.codec;
-                    entry.nativeBandwidth = metadata.bandwidth;
-                    entry.nativeResolution = metadata.resolution;
+                    applyNativeQualityRefresh(entry, metadata);
                 },
                 page: currentPage,
                 probeIdentity,
@@ -383,7 +435,7 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
             });
             if (success) {
                 // Reset staleness tracking so the monitor gives the refreshed stream time to produce segments.
-                nativeHealthState.lastSegmentAdvanceTime = Date.now();
+                nativeHealthState.lastSegmentAdvanceTime = deps.clock.now();
             }
         }
         finally {
@@ -394,68 +446,127 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
      * L3 recovery for native streams: falls back to capture mode via tab replacement. Stops the native proxy, creates a fresh page with capture pipeline, and switches
      * the stream to capture mode. The existing tab replacement infrastructure handles page creation, capture initialization, segmenter creation, and registry updates.
      *
+     * The relay keeps producing throughout the attempt and is stopped only on the exits that hand the stream to something else, so a fallback that cannot establish
+     * its capture leaves the stream exactly as it found it rather than stranded between two modes.
+     *
      * If the proxy's onError fires concurrently (from the poll loop hitting its failure threshold), terminateStream runs before this async function gets a chance to
-     * execute. By the time L3 runs, the stream is already terminated and executeTabReplacement returns null, which we handle as a failed outcome.
+     * execute. By the time L3 runs, the stream is already terminated and executeTabReplacement reports the stop.
      *
      * @param entry - The stream registry entry.
      */
     async function executeNativeL3Fallback(entry) {
-        if (!onTabReplacement) {
-            LOG.warn("Capture fallback not available for %s: no tab replacement handler.", entry.info.storeKey);
+        // The whole identity this fallback is leaving, held in one local. The narrow is taken fresh here because a narrowing does not cross a call, and the failed
+        // arm restores this same object rather than reconstructing it member by member.
+        const previousIdentity = entry.identity;
+        if (previousIdentity.mode !== "native") {
+            return;
+        }
+        if (!canReplaceTab()) {
+            LOG.warn("Capture fallback not available for %s: %s.", entry.info.storeKey, tabReplacementUnavailableReason());
             onCircuitBreak();
             return;
         }
         LOG.debug("native:monitor", "Starting L3 fallback (capture mode) for %s.", entry.info.storeKey);
-        // Stop the native proxy before tab replacement closes the page. The proxy may still be polling and would encounter errors when the page navigates away.
-        if (entry.nativeProxy) {
-            entry.nativeProxy.stop();
-            entry.nativeProxy = null;
-        }
+        /* Declare capture mode before the replacement rather than after it. The window-visibility policy reads the registry, and createPageWithCapture syncs the window
+         * at the top of establishment - so an entry still marked native there would let the policy minimize the window under a capture that is being acquired. Every
+         * outcome below either keeps this or reverts it, so the entry never rests on a mode it is not in.
+         *
+         * The proxy is deliberately left running behind that declaration, right through the attempt. The replacement builds its capture on a new page and does not
+         * touch the old one until the swap, so there is nothing for a polling proxy to trip over, and a fallback that fails hands back a stream that never stopped
+         * relaying. Its token-refresh timer keeps running too: a refresh landing mid-window is ordinary native operation, and the registry's quality write skips it
+         * because the entry is holding a capture identity for the duration.
+         */
+        entry.identity = makePendingCaptureIdentity();
         // Use the existing tab replacement infrastructure. It sets recoveryState.inProgress = true internally and clears it in finalizeTabReplacement. It creates a new
-        // page with capture, navigates, sets up playback, creates a segmenter, and updates the registry entry (the page and the new capture session, with the segmenter
-        // attached to it).
+        // page with capture, navigates, sets up playback, creates a segmenter, and swaps the registry entry over to the new page and capture session.
         const outcome = await executeTabReplacement("native fallback to capture");
-        // The monitor stopped while tab replacement was in flight (the stream terminated). Nothing was applied and there is nothing to switch to, so return without
-        // mutating the entry or clearing the probe cache. This branch is explicit because the chain below ends in a catch-all else that would otherwise log a false
-        // "fallback failed" for a stop that is not a failure.
-        if (outcome.outcome === "stopped") {
-            return;
-        }
-        if (outcome.outcome === "success") {
-            // Tab replacement succeeded. Update the registry to reflect capture mode. The tab replacement handler already set the page and the new capture session (with
-            // its segmenter attached) on the registry entry. We just need to update the streaming mode and clear audio state.
-            entry.streamingMode = "capture";
-            // Clear separate audio state from the native proxy. Without this, hasAudio remains true and the HLS handler continues serving the master playlist (referencing
-            // video.m3u8 and audio.m3u8) instead of the capture segmenter's variant playlist. Clients that cached the master playlist structure would request stale audio
-            // and video variant playlists pointing to segments that are no longer being updated.
-            entry.hls.hasAudio = false;
-            entry.hls.audioPlaylist = "";
-            entry.hls.audioSegments.clear();
-            entry.hls.audioSegmentBytes = 0;
-            entry.hls.videoPlaylist = "";
-            // Release the relay's initialization segments. They belong to a source this stream no longer consumes, and the memory report reads their byte counter with
-            // no mode gate, so state left here would be counted for the rest of the stream's life. The nativeContainer label needs no matching reset: every consumer
-            // reads it behind the streaming-mode check the line above just flipped, exactly as the sibling native quality fields work.
-            clearNativeInitState(entry.id);
-            // Clear the probe cache so subsequent tunes to this channel don't re-attempt native streaming.
-            clearProbeCache(entry.info.storeKey);
-            LOG.info("Switched to capture mode for %s: native streaming failed.", entry.info.storeKey);
-            // The monitor's next tick will see streamingMode === "capture" and run the normal video element monitoring path. The state reset from
-            // applyTabReplacementSuccess (called by executeTabReplacement) already initialized all capture-mode monitor variables.
-        }
-        else if (outcome.outcome === "terminated") {
-            // Circuit breaker tripped during tab replacement. Stream is being terminated.
-            LOG.warn("Capture fallback failed for %s: circuit breaker tripped.", entry.info.storeKey);
+        /* An exhaustive switch rather than a chain, so a future outcome cannot be absorbed silently into a catch-all. No rejection handling wraps the await above:
+         * executeTabReplacement converts every throw into an outcome in its own catch, so there is no rejection to arm for.
+         */
+        switch (outcome.outcome) {
+            case "success": {
+                /* The handler set the page and the new capture session (with its segmenter attached) on the entry, and capture mode was declared before the replacement,
+                 * so what remains is the state the native path left behind.
+                 *
+                 * Clear separate audio state from the native proxy. Without this, hasAudio remains true and the HLS handler continues serving the master playlist
+                 * (referencing video.m3u8 and audio.m3u8) instead of the capture segmenter's variant playlist. Clients that cached the master playlist structure would
+                 * request stale audio and video variant playlists pointing to segments that are no longer being updated.
+                 */
+                entry.hls.hasAudio = false;
+                entry.hls.audioPlaylist = "";
+                entry.hls.audioSegments.clear();
+                entry.hls.audioSegmentBytes = 0;
+                entry.hls.videoPlaylist = "";
+                // Release the relay's initialization segments. They belong to a source this stream no longer consumes, and the memory report reads their byte counter with
+                // no mode gate, so state left here would be counted for the rest of the stream's life. The nativeContainer label needs no matching reset: it lives on the
+                // native identity this entry no longer holds.
+                clearNativeInitState(entry.id);
+                // Clear the probe cache so subsequent tunes to this channel don't re-attempt native streaming.
+                clearProbeCache(entry.info.storeKey);
+                /* Re-derive the codec facts from the capture decision. The identity the handler wrote carried forward what the pre-swap identity held, which on this path
+                 * is the pending shape the pre-flip installed - and before that, the label read off the service's manifest, which describes a feed this stream is no
+                 * longer consuming. The status display would otherwise report that stale label for the rest of the stream's life. This is the one sanctioned within-variant
+                 * spread: the capture session and the page the handler installed are left exactly as they are.
+                 */
+                if (isCaptureIdentity(entry)) {
+                    entry.identity = { ...entry.identity, captureCodec: deps.getEffectiveCaptureCodec().toUpperCase(), hardwareAccelerated: deps.isCaptureHardwareAccelerated() };
+                }
+                LOG.info("Switched to capture mode for %s: native streaming failed.", entry.info.storeKey);
+                // The monitor's next tick sees a capture identity and runs the normal video element monitoring path. The state reset from applyTabReplacementSuccess
+                // (called by executeTabReplacement) already initialized all capture-mode monitor variables.
+                break;
+            }
+            case "failed": {
+                /* The replacement did not take, but the stream continues un-terminated - and because nothing was disposed before the swap, what it continues on is the
+                 * native relay it has been running all along. Restoring the held identity whole hands back the same live proxy, and the window sync lets the presentation
+                 * settle now that no capture is being attempted.
+                 *
+                 * The restore is correct in both entry conditions. A proxy that is still healthy simply resumes. A proxy that had already stopped itself on its error
+                 * threshold re-triggers this fallback on a later tick - deliberately: the grace window throttles each cycle and the circuit breaker bounds the count, so a
+                 * native stream whose relay died and whose capture fallback keeps failing escalates to termination rather than resting in a silent limbo.
+                 */
+                entry.identity = previousIdentity;
+                void deps.syncWindowVisibility();
+                LOG.warn("Capture fallback failed for %s: tab replacement unsuccessful.", entry.info.storeKey);
+                break;
+            }
+            case "deferred": {
+                /* The replacement was declined before it started because the previous recovery's window is still open. Nothing was attempted, so the revert is the same one
+                 * the failed arm performs and the narration is a breadcrumb rather than a warning.
+                 *
+                 * No live native path reaches this arm: every native trigger holds its fallback at the decision site while the window is open, and nothing runs between
+                 * that read and the primitive's own that could open a window. The arm stays because the outcome union is shared with the capture triggers and the switch
+                 * is exhaustive by design.
+                 */
+                entry.identity = previousIdentity;
+                void deps.syncWindowVisibility();
+                LOG.debug("native:monitor", "Capture fallback for %s deferred inside the recovery grace window.", entry.info.storeKey);
+                break;
+            }
+            case "stopped": {
+                // The monitor stopped while the replacement was in flight, which means the stream terminated. Termination disposed what the registry held - the pending
+                // capture identity, which holds nothing - so the proxy is this frame's to release.
+                break;
+            }
+            case "terminated": {
+                // The circuit breaker tripped during the replacement and terminated the stream synchronously, again while the registry held the pending identity, so
+                // nothing else can reach the proxy.
+                LOG.warn("Capture fallback failed for %s: circuit breaker tripped.", entry.info.storeKey);
+                break;
+            }
         }
-        else {
-            // Tab replacement failed but stream wasn't terminated. The circuit breaker will handle it on the next failure.
-            LOG.warn("Capture fallback failed for %s: tab replacement unsuccessful.", entry.info.storeKey);
+        /* One stop site owns the whole leak matrix. The two arms that put the held identity back are the two that hand the proxy on to a stream that is still using
+         * it; every other exit is the end of this proxy's life - the capture pipeline has taken over, or the stream is gone and took nothing with it - and an
+         * unstopped proxy would go on polling and refreshing forever.
+         */
+        if ((outcome.outcome !== "failed") && (outcome.outcome !== "deferred")) {
+            previousIdentity.nativeProxy.stop();
         }
     }
     // Helper to mark a discontinuity in the HLS playlist after recovery events that disrupt the video source. The segmenter flushes its current fragment buffer and sets
     // a pending discontinuity flag so the next segment boundary includes an #EXT-X-DISCONTINUITY tag. This tells HLS clients to flush their decoder state.
     const markStreamDiscontinuity = () => {
-        getStream(streamInfo.numericStreamId)?.captureSession?.segmenter?.markDiscontinuity();
+        getStreamSegmenter(getStream(streamInfo.numericStreamId))?.markDiscontinuity();
     };
     /**
      * Computes the health status classification based on current monitor state.
@@ -480,24 +591,33 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
         if (intervalCleared) {
             return;
         }
-        const now = Date.now();
+        const now = deps.clock.now();
         // Get current memory usage from the stream's HLS segment buffers.
         const entry = getStream(streamInfo.numericStreamId);
         const memoryBytes = entry ? getStreamMemoryUsage(entry).total : 0;
         // Get the channel key from the registry entry for logo lookup.
         const channelKey = entry?.info.storeKey ?? "";
         // Get current client counts and type breakdown for this stream.
-        const clientSummary = getClientSummary(streamInfo.numericStreamId);
+        const clientSummary = getClientSummary(streamInfo.numericStreamId, now);
+        // An entry that is gone projects as the capture defaults, which is the same shape the flat wire carries for a stream whose setup has not filled it in yet.
+        const identity = entry?.identity;
+        const nativeIdentity = (identity?.mode === "native") ? identity : null;
+        // The two capture-only sizes are null for a native entry: the entry's mode is the contract, not the builder.
+        const captureStream = identity?.mode !== "native";
+        const sourceResolution = (captureStream && lastVideoState && (lastVideoState.videoWidth > 0) && (lastVideoState.videoHeight > 0)) ?
+            formatResolution(lastVideoState.videoWidth, lastVideoState.videoHeight) : null;
+        const captureResolution = captureStream ? formatResolution(presetViewport.width, presetViewport.height) : null;
         const status = {
             bufferingDuration: bufferingStartTime ? Math.round((now - bufferingStartTime) / 1000) : null,
-            captureCodec: entry?.captureCodec ?? null,
+            captureCodec: identity?.captureCodec ?? null,
+            captureResolution,
             channel: streamInfo.channelName,
             clientCount: clientSummary.total,
             clients: clientSummary.clients,
             currentTime: lastVideoState?.time ?? 0,
-            duration: Math.round((now - streamInfo.startTime.getTime()) / 1000),
+            duration: Math.round((now - streamInfo.startTime) / 1000),
             escalationLevel: recoveryState.escalationLevel,
-            hardwareAccelerated: entry?.hardwareAccelerated ?? false,
+            hardwareAccelerated: entry ? isHardwareAccelerated(entry) : false,
             health: computeHealthStatus(),
             id: streamInfo.numericStreamId,
             lastIssueTime,
@@ -505,16 +625,17 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
             lastRecoveryTime: recoveryState.lastRecoveryTime > 0 ? recoveryState.lastRecoveryTime : null,
             logoUrl: channelKey ? (getChannelLogo(channelKey) ?? "") : "",
             memoryBytes,
-            nativeBandwidth: entry?.nativeBandwidth ?? 0,
-            nativeResolution: entry?.nativeResolution ?? null,
+            nativeBandwidth: nativeIdentity?.nativeBandwidth ?? 0,
+            nativeResolution: nativeIdentity?.nativeResolution ?? null,
             networkState: lastVideoState?.networkState ?? 0,
             pageReloadsInWindow: pageReloadTimestamps.length,
             readyState: lastVideoState?.readyState ?? 0,
             recoveryAttempts: recoveryState.totalAttempts,
             serviceName: streamInfo.serviceName,
             showName: getShowName(streamInfo.numericStreamId),
-            startTime: streamInfo.startTime.toISOString(),
-            streamingMode: entry?.streamingMode ?? "capture",
+            sourceResolution,
+            startTime: new Date(streamInfo.startTime).toISOString(),
+            streamingMode: identity?.mode ?? "capture",
             url
         };
         emitStreamHealthChanged(status);
@@ -537,8 +658,8 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
         segmentState.productionStalled = false;
         segmentState.consecutiveTinySegments = 0;
         segmentState.wasInTinyState = false;
-        segmentState.lastCheckedIndex = getStream(streamInfo.numericStreamId)?.captureSession?.segmenter?.getSegmentIndex() ?? 0;
-        segmentState.lastSegmentAdvanceTime = Date.now();
+        segmentState.lastCheckedIndex = getStreamSegmenter(getStream(streamInfo.numericStreamId))?.getSegmentIndex() ?? 0;
+        segmentState.lastSegmentAdvanceTime = deps.clock.now();
     }
     /**
      * Resets all failure/retry counters to zero. Called after successful tab replacement or page navigation to give the stream a fresh start.
@@ -552,11 +673,13 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
         videoNotFoundCount = 0;
     }
     /**
-     * Resets resolution monitoring state. Called when resolution reaches expected levels or after any recovery action that restarts ABR negotiation.
+     * Resets the resolution monitoring a recovery action makes stale: the degraded-reading count, the grace window, and the ladder step. Deliberately not the peak
+     * record - the source's rendition ladder does not change with a reload or a tab replacement, and the record's accepted flag is what keeps an unrelated recovery
+     * from re-running the resolution ladder inside one degraded episode.
      */
     function resetResolutionState() {
         resolutionState.consecutiveDegradedReadings = 0;
-        resolutionState.graceEnd = Date.now() + RESOLUTION_GRACE_PERIOD;
+        resolutionState.graceEnd = deps.clock.now() + RESOLUTION_GRACE_PERIOD;
         resolutionState.recoveryAttempt = 0;
     }
     /**
@@ -565,12 +688,12 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
      * @returns True if a page reload is allowed and the timestamp has been recorded, false if the rate limit has been reached.
      */
     function isPageReloadAllowed() {
-        const reloadWindow = Date.now() - CONFIG.playback.pageReloadWindow;
+        const reloadWindow = deps.clock.now() - CONFIG.playback.pageReloadWindow;
         pageReloadTimestamps = pageReloadTimestamps.filter((ts) => ts > reloadWindow);
         if (pageReloadTimestamps.length >= CONFIG.playback.maxPageReloads) {
             return false;
         }
-        pageReloadTimestamps.push(Date.now());
+        pageReloadTimestamps.push(deps.clock.now());
         return true;
     }
     /**
@@ -581,13 +704,22 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
         recoveryState.sourceReloadAttempted = false;
     }
     /**
-     * Sets the recovery grace period and re-minimize flag after a recovery action. The grace period prevents the monitor from immediately detecting new issues while the
-     * recovery action takes effect.
+     * Sets the recovery grace period after a recovery action. The grace period prevents the monitor from immediately detecting new issues while the recovery action
+     * takes effect.
      * @param level - The recovery level (1-3) to determine grace period duration.
      */
     function setRecoveryGracePeriod(level) {
-        pendingReMinimize = true;
-        recoveryState.graceUntil = Date.now() + (recoveryGracePeriods[level] ?? 0);
+        recoveryState.graceUntil = deps.clock.now() + (recoveryGracePeriods[level] ?? 0);
+    }
+    /**
+     * Reports whether the monitor is inside the post-recovery grace window. One state, read here by every consumer that has to honour it: the tick computes the
+     * value it threads into the health checks from this, and the triggers that sit outside that thread - the tiny-segment gate, the unresponsive-tab gate, the
+     * native fallback triggers through deferFallbackInsideGrace, and the replacement primitive's own entry gate - call it directly. A second way of asking the
+     * same question is how a trigger ends up escalating inside a window every other trigger is respecting.
+     * @returns True while the grace window from the last recovery action is still open.
+     */
+    function isWithinRecoveryGrace() {
+        return deps.clock.now() < recoveryState.graceUntil;
     }
     /**
      * Stops the monitoring interval. Pairs the two operations that must always happen together: setting intervalCleared so any in-flight async tick short-circuits at
@@ -597,7 +729,7 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
      */
     function stopMonitoring() {
         intervalCleared = true;
-        clearInterval(interval);
+        interval[Symbol.dispose]();
     }
     /**
      * Reports whether the monitor stopped while a recovery action was awaiting, and releases the recovery flag when it did. A recovery await can resume after
@@ -628,7 +760,7 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
         if (intervalCleared) {
             return { outcome: "stopped" };
         }
-        const cbResult = checkCircuitBreaker(circuitBreaker, Date.now());
+        const cbResult = checkCircuitBreaker(circuitBreaker, deps.clock.now());
         if (cbResult.shouldTrip) {
             LOG.error("Recovery exhausted (%s) - terminating stream.", context);
             stopMonitoring();
@@ -645,11 +777,12 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
     function applyTabReplacementSuccess(result) {
         currentPage = result.page;
         currentContext = result.context;
-        const duration = formatRecoveryDuration(metrics.currentRecoveryStartTime ?? Date.now());
+        const settledAt = deps.clock.now();
+        const duration = formatRecoveryDuration(metrics.currentRecoveryStartTime ?? settledAt, settledAt);
         LOG.info("Recovered in %s via %s.", duration, RECOVERY_METHODS.tabReplacement);
-        recordRecoverySuccess(metrics, RECOVERY_METHODS.tabReplacement);
+        recordRecoverySuccess(metrics, RECOVERY_METHODS.tabReplacement, settledAt);
         // Full state reset for fresh tab.
-        lastPageNavigationTime = Date.now();
+        lastPageNavigationTime = deps.clock.now();
         resetRecoveryCounters();
         resetEscalationState();
         resetSegmentMonitoringState();
@@ -659,7 +792,8 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
     }
     /**
      * Handles tab replacement failure after all retry attempts are exhausted. Clears stale recovery metrics (preventing ghost "Recovered" logs from the
-     * deferred-success check), runs the circuit breaker, and detects zombie streams where the old page was destroyed but no replacement was created.
+     * deferred-success check), arms the grace window that throttles the next attempt while one can still start, runs the circuit breaker, and catches the one state
+     * that still strands a stream.
      * @param context - Description of the failure for circuit breaker logging.
      * @returns The tab replacement outcome (failed or terminated).
      */
@@ -673,11 +807,27 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
         // Clear stale recovery metrics so the deferred-success check does not falsely log "Recovered" from leftover state set by recordRecoveryAttempt.
         metrics.currentRecoveryStartTime = null;
         metrics.currentRecoveryMethod = null;
-        LOG.warn("Tab replacement unsuccessful after retry - stream will be terminated.");
+        LOG.warn("Tab replacement was unsuccessful. The stream continues on its existing capture.");
+        /* Arm the grace window on the way out, the same window a success arms. A failed replacement leaves the stream running on its old pipeline, still exhibiting
+         * whatever condition triggered the attempt - so without this the very next tick re-satisfies that condition and fires again, and a persistently degraded
+         * stream spends its life in a replacement loop. With it, the cadence is one real attempt per window (ten seconds at this level, from the monitor's grace
+         * table), each true failure counted by the circuit breaker, ending in termination when the breaker's threshold trips. Bounded escalation rather than a tight
+         * loop, and no log line per suppressed tick.
+         *
+         * The arming reads whether a replacement can still start, because on a browser that can start none there is no replacement loop here to throttle: every
+         * trigger reaches its no-replacement arm rather than the handler. Holding the arms that terminate for a window holds every other recording's re-tune behind
+         * this stream, because the relaunch that cures the browser waits on the last stream's end. A failure that itself marked the browser lands the mark before the
+         * exhaustion settles, so the read here sees it.
+         */
+        if (canReplaceTab()) {
+            setRecoveryGracePeriod(3);
+        }
         const failureOutcome = handleTabReplacementFailure(context);
-        // If the circuit breaker did not trip but the old page is gone (handler destroyed it before createPageWithCapture failed), the stream is unrecoverable. The
-        // next monitor tick would silently clear the interval via currentPage.isClosed() with no termination log, no status emission, and no cleanup - creating a
-        // zombie entry in the registry. Terminate explicitly instead.
+        /* The safety net for the one state that still strands a stream: termination raced the exhaustion and took the page while this settled. A replacement that
+         * simply failed leaves the old page open and serving, so this does not fire for it - that stream continues on its existing capture with the breaker counting,
+         * which is the designed outcome. When the page really is gone, the next tick would silently clear the interval via currentPage.isClosed() with no termination
+         * log, no status emission, and no cleanup, leaving a zombie entry in the registry. Terminate explicitly instead.
+         */
         if ((failureOutcome.outcome === "failed") && currentPage.isClosed()) {
             LOG.error("Tab replacement failed and the original page is no longer available - terminating stream.");
             stopMonitoring();
@@ -688,27 +838,38 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
     }
     /**
      * Executes tab replacement recovery with full error handling. This unified helper handles all tab replacement triggers (tiny segments, stalled capture, unresponsive
-     * tab) consistently, including metrics recording, success/failure logging, circuit breaker checks, and state resets.
+     * tab, resolution degradation, native fallback) consistently, including metrics recording, success/failure logging, circuit breaker checks, and state resets.
+     *
+     * The handler builds the replacement capture before disposing anything: it creates a fresh page, acquires its capture, and tunes it while the existing pipeline
+     * keeps producing, and only then swaps in one synchronous frame. So a failed attempt costs the stream nothing - the old capture is still running and still
+     * serving the recording - and the single retry below is a second chance rather than the last one. The retry re-reads continuity from the still-live old
+     * segmenter, and its own fresh resources are discarded on failure the same way the first attempt's were.
      *
-     * On failure, retries onTabReplacement once before giving up. The handler destroys old resources (capture, segmenter, FFmpeg, page) before calling
-     * createPageWithCapture, so a retry is the only chance to save the stream when the first attempt fails. All handler cleanup steps are safe to call more than
-     * once on retry: rawCaptureStream.destroyed guard, segmenter stop() checks state.stopped, FFmpeg kill() checks ffmpeg.killed, page close checks
-     * !oldPage.isClosed(), and unregisterManagedPage is a no-op on repeat.
+     * Every entry runs through the grace check below, which is what keeps a persistently degraded stream from spending its life re-attempting.
      * @param issueType - Description of what triggered the replacement (for logging and UI display).
      * @returns The tab replacement outcome.
      */
     async function executeTabReplacement(issueType) {
-        // Guard: caller should ensure onTabReplacement exists, but TypeScript needs explicit narrowing.
-        if (!onTabReplacement) {
+        // Guard: the caller has already consulted canReplaceTab, but TypeScript needs the explicit narrowing for the awaited calls below.
+        if (!onTabReplacement || !canReplaceTab()) {
             return { outcome: "failed" };
         }
+        /* The throttle, enforced at the one place every trigger passes through. Individual triggers consult the grace window in their own gates so their warnings and
+         * side effects stay quiet too, but a gate can be forgotten and a new trigger can be added, whereas this cannot be bypassed by construction. It sits ahead of
+         * every piece of bookkeeping - before the attempt metric, before the recovery flags, before the handler runs - so a deferral costs nothing and is
+         * indistinguishable from the attempt never having been asked for.
+         */
+        if (isWithinRecoveryGrace()) {
+            LOG.debug("recovery:tab", "Deferring the %s tab replacement: the previous recovery's grace window is still open.", issueType);
+            return { outcome: "deferred" };
+        }
         recoveryState.inProgress = true;
         recoveryState.totalAttempts++;
-        recoveryState.lastRecoveryTime = Date.now();
+        recoveryState.lastRecoveryTime = deps.clock.now();
         lastIssueType = issueType;
-        lastIssueTime = Date.now();
-        const tabRecoveryElapsed = startTimer();
-        recordRecoveryAttempt(metrics, RECOVERY_METHODS.tabReplacement);
+        lastIssueTime = deps.clock.now();
+        const tabRecoveryElapsed = startTimer(deps.clock);
+        recordRecoveryAttempt(metrics, RECOVERY_METHODS.tabReplacement, deps.clock.now());
         try {
             let result = await onTabReplacement();
             // First attempt failed - retry once. See the safe-to-retry notes in the JSDoc above.
@@ -735,7 +896,7 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
         }
         catch (error) {
             // Unexpected error (not from onTabReplacement - those are caught internally by the handler in hls.ts and return null). Guard against registry corruption,
-            // getStream failures, or other unexpected errors.
+            // capture-acquisition failures, or other unexpected errors.
             LOG.debug("recovery:tab", "Tab replacement attempt 1/2 failed: %s. Retrying...", formatError(error));
             try {
                 const retryResult = await onTabReplacement();
@@ -769,14 +930,14 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
      * @returns Recovery result with the new context if successful.
      */
     async function performPageNavigationRecovery() {
-        const navRecoveryElapsed = startTimer();
+        const navRecoveryElapsed = startTimer(deps.clock);
         // Track page count before navigation to detect unexpected new tabs (popups, ads).
         const browser = currentPage.browser();
         const pageCountBefore = (await browser.pages()).length;
         try {
             // Use tuneToChannel to reinitialize playback. It is the tune this recovery path owns, and it runs the phases stream setup ran - navigation, channel
             // selection, video detection, click-to-play, playback - so a recovered stream comes up the way a fresh one did.
-            const { context: newContext } = await tuneToChannel(currentPage, url, profile);
+            const { context: newContext } = await tuneToChannel(currentPage, url, profile, deps.clock);
             // Check for unexpected new tabs created during tuning.
             const pageCountAfter = (await browser.pages()).length;
             if (pageCountAfter > pageCountBefore) {
@@ -848,7 +1009,7 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
         if (videoNotFoundCount === 2) {
             LOG.debug("recovery:context", "Re-searching frames for video element.");
             try {
-                const newContext = await findVideoContext(currentPage, profile);
+                const newContext = await findVideoContext(currentPage, profile, deps.clock);
                 const validationState = await validateVideoElement(newContext, selectorType);
                 if (validationState.found) {
                     LOG.info("Video found in different context after re-search. readyState=%s.", validationState.readyState);
@@ -889,9 +1050,8 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
         recoveryState.escalationLevel = 3;
         recoveryState.lastRecoveryTime = now;
         recoveryState.totalAttempts++;
-        pendingReMinimize = true;
         recoveryState.inProgress = true;
-        recordRecoveryAttempt(metrics, RECOVERY_METHODS.pageNavigation);
+        recordRecoveryAttempt(metrics, RECOVERY_METHODS.pageNavigation, deps.clock.now());
         // Check page reload limit before attempting recovery.
         if (!isPageReloadAllowed()) {
             LOG.error("Page navigation rate limit reached (%s in %s minutes) - cannot recover without video element.", CONFIG.playback.maxPageReloads, Math.round(CONFIG.playback.pageReloadWindow / 60000));
@@ -912,10 +1072,11 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
         setRecoveryGracePeriod(3);
         if (recoveryResult.success && recoveryResult.newContext) {
             currentContext = recoveryResult.newContext;
-            const duration = formatRecoveryDuration(metrics.currentRecoveryStartTime ?? now);
+            const settledAt = deps.clock.now();
+            const duration = formatRecoveryDuration(metrics.currentRecoveryStartTime ?? settledAt, settledAt);
             LOG.info("Recovered in %s via %s.", duration, RECOVERY_METHODS.pageNavigation);
-            recordRecoverySuccess(metrics, RECOVERY_METHODS.pageNavigation);
-            lastPageNavigationTime = Date.now();
+            recordRecoverySuccess(metrics, RECOVERY_METHODS.pageNavigation, settledAt);
+            lastPageNavigationTime = deps.clock.now();
             resetRecoveryCounters();
             resetEscalationState();
             resetSegmentMonitoringState();
@@ -948,7 +1109,7 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
             segmentState.waitStartTime ??= now;
             // Check if segments are flowing by comparing current index to pre-recovery index.
             const entry = getStream(streamInfo.numericStreamId);
-            const currentIndex = entry?.captureSession?.segmenter?.getSegmentIndex() ?? null;
+            const currentIndex = getStreamSegmenter(entry)?.getSegmentIndex() ?? null;
             if ((currentIndex !== null) && (currentIndex > segmentState.preRecoveryIndex)) {
                 // Segments are flowing - recovery actually succeeded. Clear tracking state.
                 segmentState.preRecoveryIndex = null;
@@ -963,7 +1124,7 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
         }
         // Continuous segment size monitoring. Runs on every healthy interval to detect spontaneous capture pipeline death.
         const sizeCheckEntry = getStream(streamInfo.numericStreamId);
-        const currentSegmentIndex = sizeCheckEntry?.captureSession?.segmenter?.getSegmentIndex() ?? 0;
+        const currentSegmentIndex = getStreamSegmenter(sizeCheckEntry)?.getSegmentIndex() ?? 0;
         if ((currentSegmentIndex > segmentState.lastCheckedIndex) && sizeCheckEntry) {
             // A new segment was produced. Update the staleness tracker and check its size.
             segmentState.lastSegmentAdvanceTime = now;
@@ -977,14 +1138,21 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
                 const hasVideo = getLastSegmentHasVideo(sizeCheckEntry);
                 const effectiveThreshold = (hasVideo === false) ? TINY_SEGMENT_COUNT_TRIGGER : providerTinySegmentThreshold;
                 LOG.debug("recovery:tracks", "Below-threshold segment: %d bytes, hasVideo=%s, consecutive=%d, threshold=%d.", segmentSize, String(hasVideo), segmentState.consecutiveTinySegments, effectiveThreshold);
-                if (segmentState.consecutiveTinySegments >= effectiveThreshold) {
+                /* Act on sustained undersized segments, but not inside the post-recovery grace window. The grace term is what keeps a stream that a replacement did not
+                 * cure from re-escalating every two seconds: a fresh capture needs its window to start producing real segments, and a stream still emitting tiny ones
+                 * when the window closes will satisfy this again immediately. Suppressing the whole branch - the warning and the circuit-breaker fallback alongside the
+                 * replacement - is deliberate, and mirrors what the staleness branch below has always done with its own grace term. The counter keeps advancing
+                 * meanwhile, so the evidence is not lost, only the reaction is deferred.
+                 */
+                if ((segmentState.consecutiveTinySegments >= effectiveThreshold) && !withinRecoveryGrace) {
                     LOG.warn("Detected %d consecutive undersized segments (%dKB) - capture pipeline may have stalled.", segmentState.consecutiveTinySegments, Math.round(segmentSize / 1024));
-                    // Trigger tab replacement if available, otherwise let circuit breaker handle it via segmentState.productionStalled.
-                    if (onTabReplacement && !recoveryState.inProgress) {
+                    // Replace the tab when a replacement can start, and otherwise raise the stalled-production flag. The recovery action reads that flag on this same tick
+                    // and terminates the stream, because no replacement can be started and the in-page ladder cannot revive a dead capture.
+                    if (canReplaceTab() && !recoveryState.inProgress) {
                         await executeTabReplacement("tiny segments");
                         return true;
                     }
-                    else if (!onTabReplacement) {
+                    else if (!canReplaceTab()) {
                         segmentState.productionStalled = true;
                     }
                 }
@@ -1012,20 +1180,21 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
              * after tab replacement while the new capture pipeline is initializing).
              */
             LOG.warn("No new segments produced for %ss - capture pipeline may have stalled.", SEGMENT_STALENESS_TIMEOUT / 1000);
-            if (onTabReplacement && !recoveryState.inProgress) {
+            if (canReplaceTab() && !recoveryState.inProgress) {
                 await executeTabReplacement("segment staleness");
                 return true;
             }
-            else if (!onTabReplacement) {
+            else if (!canReplaceTab()) {
                 segmentState.productionStalled = true;
             }
         }
         return false;
     }
     /**
-     * Monitors video resolution against the configured viewport and triggers recovery for sustained ABR degradation. Uses a two-step escalation: page reload (forces ABR
-     * restart), then tab replacement (fresh page with new network connections). Accepts the resolution after both attempts to avoid infinite loops on legitimately
-     * low-resolution content. Also detects and logs resolution restoration after successful recovery.
+     * Monitors video resolution against the best resolution the stream has delivered and triggers recovery for sustained ABR degradation. Uses a two-step escalation:
+     * page reload (forces ABR restart), then tab replacement (fresh page with new network connections). Acceptance after both attempts is recorded on the peak record
+     * and ends with the episode, so the ladder runs at most once per level the source has demonstrated rather than looping on content that is simply low-resolution.
+     * Also detects and logs resolution restoration after successful recovery.
      *
      * @param now - Current timestamp for timing calculations.
      * @param state - Current video state with intrinsic resolution.
@@ -1038,12 +1207,34 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
         if (!isProgressing || state.paused || state.error || state.ended || withinRecoveryGrace || (state.videoWidth === 0) || (state.videoHeight === 0)) {
             return false;
         }
-        const widthRatio = state.videoWidth / presetViewport.width;
-        const heightRatio = state.videoHeight / presetViewport.height;
-        const isDegraded = (widthRatio < RESOLUTION_RATIO_THRESHOLD) || (heightRatio < RESOLUTION_RATIO_THRESHOLD);
-        if (isDegraded && (now >= resolutionState.graceEnd)) {
+        const reading = { height: state.videoHeight, width: state.videoWidth };
+        const peak = updateResolutionPeak({ peak: resolutionState.peak, reading });
+        resolutionState.peak = peak;
+        const isDegraded = isResolutionDegraded({ peak, reading, threshold: RESOLUTION_RATIO_THRESHOLD });
+        /* The picture is back at or near its peak: the episode is over, whatever the ladder had reached. Say so once, then clear every trace of the episode - the
+         * accepted flag included - so a later drop starts a fresh ladder. The method the message names is read from the ladder step, which an unrelated recovery may
+         * have zeroed while the acceptance stood, so the sentence stays truthful in every case.
+         */
+        if (!isDegraded) {
+            if (peak.accepted || (resolutionState.recoveryAttempt > 0)) {
+                const method = (resolutionState.recoveryAttempt === 1) ? "page reload" :
+                    ((resolutionState.recoveryAttempt === 2) ? "tab replacement" : "an unrelated recovery");
+                const verb = describeResolutionOutcome({ peak, reading });
+                LOG.info("Video resolution %s to %s\u00d7%s after %s.", verb, String(state.videoWidth), String(state.videoHeight), method);
+                resolutionState.consecutiveDegradedReadings = 0;
+                resolutionState.graceEnd = 0;
+                resolutionState.peak = { ...peak, accepted: false };
+                resolutionState.recoveryAttempt = 0;
+            }
+            return false;
+        }
+        // A ladder that already ran to acceptance at this peak does not run again inside the same episode: the source has shown nothing better since.
+        if (peak.accepted) {
+            return false;
+        }
+        if (now >= resolutionState.graceEnd) {
             resolutionState.consecutiveDegradedReadings++;
-            LOG.debug("recovery:resolution", "Video resolution: %s\u00d7%s (viewport: %s\u00d7%s, ratio: %s%%\u00d7%s%%, consecutive: %s/%s).", String(state.videoWidth), String(state.videoHeight), String(presetViewport.width), String(presetViewport.height), String(Math.round(widthRatio * 100)), String(Math.round(heightRatio * 100)), String(resolutionState.consecutiveDegradedReadings), String(RESOLUTION_DEGRADED_COUNT_THRESHOLD));
+            LOG.debug("recovery:resolution", "Video resolution: %s\u00d7%s (peak: %s\u00d7%s, area: %s%%, consecutive: %s/%s).", String(state.videoWidth), String(state.videoHeight), String(peak.width), String(peak.height), String(Math.round(100 * resolutionAreaRatio({ peak, reading }))), String(resolutionState.consecutiveDegradedReadings), String(RESOLUTION_DEGRADED_COUNT_THRESHOLD));
         }
         else {
             resolutionState.consecutiveDegradedReadings = 0;
@@ -1052,7 +1243,7 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
         // (RESOLUTION_DEGRADED_COUNT_THRESHOLD consecutive readings) to let transient ABR dips self-heal.
         if ((resolutionState.consecutiveDegradedReadings >= RESOLUTION_DEGRADED_COUNT_THRESHOLD) && (resolutionState.recoveryAttempt === 0)) {
             const degradedDuration = resolutionState.consecutiveDegradedReadings * 2;
-            LOG.warn("Video resolution has been degraded for %ss (%s\u00d7%s in %s\u00d7%s viewport). Attempting recovery via %s.", String(degradedDuration), String(state.videoWidth), String(state.videoHeight), String(presetViewport.width), String(presetViewport.height), RECOVERY_METHODS.pageNavigation);
+            LOG.warn("Video resolution has been degraded for %ss (%s\u00d7%s against a %s\u00d7%s peak). Attempting recovery via %s.", String(degradedDuration), String(state.videoWidth), String(state.videoHeight), String(peak.width), String(peak.height), RECOVERY_METHODS.pageNavigation);
             recoveryState.inProgress = true;
             if (!isPageReloadAllowed()) {
                 LOG.warn("Resolution recovery deferred - page navigation rate limit reached (%s in %s minutes).", CONFIG.playback.maxPageReloads, Math.round(CONFIG.playback.pageReloadWindow / 60000));
@@ -1062,7 +1253,6 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
                 emitStatusUpdate();
                 return true;
             }
-            pendingReMinimize = true;
             const recoveryResult = await performPageNavigationRecovery();
             // Same post-await stop check as the other navigation sites: a resumption after the monitor stopped applies neither the grace windows nor the ratchet step
             // below, since both would be bookkeeping for a stream that is gone.
@@ -1080,7 +1270,7 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
             resolutionState.graceEnd = now + RESOLUTION_GRACE_PERIOD;
             if (recoveryResult.success && recoveryResult.newContext) {
                 currentContext = recoveryResult.newContext;
-                lastPageNavigationTime = Date.now();
+                lastPageNavigationTime = deps.clock.now();
                 // Reset the general-recovery state a successful reload made stale, composed for this site. Deliberately NOT resetResolutionState() (which the proactive-reload
                 // sibling calls): that zeroes the recoveryAttempt ratchet set to 1 just above, collapsing the two-step resolution ladder into an endless step-1 loop. And
                 // deliberately WITH resetEscalationState() (which the sibling omits): the sibling's caller guarantees a zero escalation level, but this path can run mid-cooldown
@@ -1098,7 +1288,7 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
         }
         // Escalation step 2: tab replacement. Creates a fresh page with new capture pipeline and network connections.
         if ((resolutionState.consecutiveDegradedReadings >= RESOLUTION_DEGRADED_COUNT_THRESHOLD) && (resolutionState.recoveryAttempt === 1)) {
-            if (onTabReplacement) {
+            if (canReplaceTab()) {
                 const degradedDuration = resolutionState.consecutiveDegradedReadings * 2;
                 LOG.warn("Video resolution is still degraded after %ss (%s\u00d7%s). Attempting recovery via %s.", String(degradedDuration), String(state.videoWidth), String(state.videoHeight), RECOVERY_METHODS.tabReplacement);
                 await executeTabReplacement("resolution degraded");
@@ -1110,21 +1300,13 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
             // Tab replacement not available - skip directly to acceptance.
             resolutionState.recoveryAttempt = 2;
         }
-        // Acceptance: resolution still degraded after both recovery attempts. Log once and stop retrying.
+        /* Acceptance: still degraded after both recovery attempts. Log once and record the acceptance on the peak record, which is what holds the ladder for the rest
+         * of this episode. The ladder step stays at 2 so the eventual restoration names the tab replacement, and the reading count is zeroed so no further step fires.
+         */
         if ((resolutionState.consecutiveDegradedReadings >= RESOLUTION_DEGRADED_COUNT_THRESHOLD) && (resolutionState.recoveryAttempt === 2)) {
-            LOG.warn("Video resolution remains degraded (%s\u00d7%s in %s\u00d7%s viewport) after recovery attempts. The stream will continue at reduced quality.", String(state.videoWidth), String(state.videoHeight), String(presetViewport.width), String(presetViewport.height));
-            resolutionState.recoveryAttempt = 3;
-        }
-        // Resolution is good: clear tracking state so future degradation starts fresh. Use "restored" when resolution matches the viewport, "improved" when it's
-        // above the degradation threshold but below the viewport. Include the recovery method so this single message tells the complete story.
-        if (!isDegraded && (resolutionState.recoveryAttempt > 0)) {
-            const isFullQuality = (state.videoWidth >= presetViewport.width) && (state.videoHeight >= presetViewport.height);
-            const verb = isFullQuality ? "restored" : "improved";
-            const method = (resolutionState.recoveryAttempt === 1) ? "page reload" : "tab replacement";
-            LOG.info("Video resolution %s to %s\u00d7%s after %s.", verb, String(state.videoWidth), String(state.videoHeight), method);
+            LOG.warn("Video resolution remains degraded (%s\u00d7%s against a %s\u00d7%s peak) after recovery attempts. The stream will continue at reduced quality.", String(state.videoWidth), String(state.videoHeight), String(peak.width), String(peak.height));
             resolutionState.consecutiveDegradedReadings = 0;
-            resolutionState.recoveryAttempt = 0;
-            resolutionState.graceEnd = 0;
+            resolutionState.peak = { ...peak, accepted: true };
         }
         return false;
     }
@@ -1158,10 +1340,9 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
         // yield. If the site eventually cuts the stream, normal error recovery handles it.
         if (!isPageReloadAllowed()) {
             LOG.warn("Proactive reload deferred - page navigation rate limit reached (%s in %s minutes).", CONFIG.playback.maxPageReloads, Math.round(CONFIG.playback.pageReloadWindow / 60000));
-            // Set a grace period to prevent this deferral from re-triggering every 2 seconds while the rate limit remains in effect. We set recoveryState.graceUntil
-            // directly rather than calling setRecoveryGracePeriod() because no recovery action was performed - the window state is unchanged and pendingReMinimize
-            // should not be set.
-            recoveryState.graceUntil = now + recoveryGracePeriods[3];
+            // Set a grace period so this deferral does not re-trigger every 2 seconds while the rate limit remains in effect. Level 3 is the bound a page navigation
+            // would have taken, which is the action being deferred.
+            setRecoveryGracePeriod(3);
             recoveryState.inProgress = false;
             emitStatusUpdate();
             return true;
@@ -1176,7 +1357,7 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
         setRecoveryGracePeriod(3);
         if (recoveryResult.success && recoveryResult.newContext) {
             currentContext = recoveryResult.newContext;
-            lastPageNavigationTime = Date.now();
+            lastPageNavigationTime = deps.clock.now();
             LOG.info("Proactive reload completed successfully.");
             resetRecoveryCounters();
             resetSegmentMonitoringState();
@@ -1205,17 +1386,26 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
      * @returns True if the tick should exit (circuit breaker tripped or tab replacement triggered), false to continue.
      */
     async function executeRecoveryAction(now, state, isProgressing, isBuffering) {
-        // Segment production stall handling. When segments stopped flowing after L2/L3 recovery, the capture pipeline is dead and normal recovery won't help. Skip the
-        // escalation ladder and go directly to tab replacement if available.
-        if (segmentState.productionStalled && onTabReplacement) {
-            LOG.warn("Capture pipeline still stalled - escalating to %s.", RECOVERY_METHODS.tabReplacement);
-            await executeTabReplacement("capture pipeline stalled");
+        // Post-await stop check, covering every exit below it. The tick awaited getVideoState before calling this; a tick that resumed after the monitor stopped must
+        // trip nothing and attempt nothing, because the accounting, the log, the replacement, and the termination would all describe a stream that has already ended.
+        // Return terminal so the tick exits without further work.
+        if (intervalCleared) {
             return true;
         }
-        // Post-await stop check for the breaker branch below. The tick awaited getVideoState before calling this; a tick that resumed after the monitor stopped must not
-        // trip the breaker, because the accounting, the log, and the termination would all describe a stream that has already ended. Return terminal so the tick exits
-        // without further work.
-        if (intervalCleared) {
+        /* Segment production stall handling. The capture pipeline is dead and the in-page ladder cannot revive a capture, so a replacement is the one cure. When none
+         * can start, the stream is unrecoverable: every rung the ladder would run spends an attempt and part of the breaker's window on a stream it cannot save, while
+         * holding open the relaunch that would cure a marked browser. So the stream terminates through the breaker at once, which is the judgment the unresponsive-tab
+         * branch already makes.
+         */
+        if (segmentState.productionStalled) {
+            if (canReplaceTab()) {
+                LOG.warn("Capture pipeline still stalled - escalating to %s.", RECOVERY_METHODS.tabReplacement);
+                await executeTabReplacement("capture pipeline stalled");
+                return true;
+            }
+            LOG.error("Capture pipeline stalled and tab replacement is unavailable (%s) - terminating stream.", tabReplacementUnavailableReason());
+            stopMonitoring();
+            onCircuitBreak();
             return true;
         }
         // Check circuit breaker for too many failures.
@@ -1239,7 +1429,6 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
         recoveryState.escalationLevel = nextLevel;
         recoveryState.lastRecoveryTime = now;
         recoveryState.totalAttempts++;
-        pendingReMinimize = true;
         // Get recovery method name for logging and metrics.
         const recoveryMethod = getRecoveryMethod(recoveryState.escalationLevel);
         // Store issue type and time for UI display.
@@ -1254,19 +1443,18 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
             const issueDesc = getIssueDescription(issueCategory);
             LOG.warn("Playback %s - recovering via %s.", issueDesc, recoveryMethod);
         }
-        recordRecoveryAttempt(metrics, recoveryMethod);
+        recordRecoveryAttempt(metrics, recoveryMethod, deps.clock.now());
         // For L2/L3 recovery, record the current segment index so we can verify segments are flowing after recovery completes.
         if (recoveryState.escalationLevel >= 2) {
             const entry = getStream(streamInfo.numericStreamId);
-            segmentState.preRecoveryIndex = entry?.captureSession?.segmenter?.getSegmentIndex() ?? null;
+            segmentState.preRecoveryIndex = getStreamSegmenter(entry)?.getSegmentIndex() ?? null;
             segmentState.waitStartTime = null;
-            segmentState.productionStalled = false;
         }
         recoveryState.inProgress = true;
         try {
             // Levels 1-2: In-page recovery via ensurePlayback().
             if (recoveryState.escalationLevel <= 2) {
-                await ensurePlayback(currentPage, currentContext, profile, { recoveryLevel: recoveryState.escalationLevel, skipNativeFullscreen: true });
+                await ensurePlayback(currentPage, currentContext, profile, { clock: deps.clock, recoveryLevel: recoveryState.escalationLevel, skipNativeFullscreen: true });
                 // The stream can terminate while ensurePlayback runs. A resumption after the monitor stopped applies none of the settlement below - the source-reload
                 // mark, the discontinuity, the grace window, the resolution reset. Returning true is what makes the caller exit the tick immediately.
                 if (abandonRecoveryIfStopped()) {
@@ -1305,10 +1493,11 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
                         setRecoveryGracePeriod(3);
                         if (recoveryResult.success && recoveryResult.newContext) {
                             currentContext = recoveryResult.newContext;
-                            const duration = formatRecoveryDuration(metrics.currentRecoveryStartTime ?? now);
+                            const settledAt = deps.clock.now();
+                            const duration = formatRecoveryDuration(metrics.currentRecoveryStartTime ?? settledAt, settledAt);
                             LOG.info("Recovered in %s via %s.", duration, RECOVERY_METHODS.pageNavigation);
-                            recordRecoverySuccess(metrics, RECOVERY_METHODS.pageNavigation);
-                            lastPageNavigationTime = Date.now();
+                            recordRecoverySuccess(metrics, RECOVERY_METHODS.pageNavigation, settledAt);
+                            lastPageNavigationTime = deps.clock.now();
                             resetRecoveryCounters();
                             resetEscalationState();
                             resetSegmentMonitoringState();
@@ -1357,11 +1546,11 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
      * 2. tickInProgress, so a firing that lands while the previous body is still running skips instead of stacking a second body on the same counters.
      * 3. recoveryState.inProgress. On the capture path this covers the window a recovery await holds open inside a tick body; on the native path it is the only
      *    guard there is, since a native recovery is launched fire-and-forget and outlives the tick that started it.
-     * 4. currentPage.isClosed(), for page termination outside of recovery. It must come after the recovery check: during tab replacement the old page is
-     *    deliberately closed while the handler creates a new one, so testing isClosed() first would clear the interval mid-recovery and stop status updates
-     *    permanently.
+     * 4. currentPage.isClosed(), for page termination outside of recovery. It must come after the recovery check: the page reference this monitor holds is the one
+     *    a replacement is about to retire, and the swap closes it, so a tick landing between the close and applyTabReplacementSuccess's re-point would read the
+     *    closed page and clear the interval mid-recovery, stopping status updates permanently.
      */
-    const interval = setInterval(() => {
+    const interval = deps.clock.schedule(() => {
         // Stop monitoring if cleanup was requested.
         if (intervalCleared) {
             stopMonitoring();
@@ -1384,6 +1573,24 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
             stopMonitoring();
             return;
         }
+        /* The catch-all for capture composition, on the one path every live capture stream's tick passes through - static captures included, which is why it precedes
+         * the static-capture return below. Chrome composes the capture of a selected tab from the window's fitted presentation, and re-issuing the page's own declared
+         * metrics moves the composition back to the emulated surface; firing it on a cadence means any disturbance, from any cause known or unknown, is corrected
+         * within about a minute rather than lasting for the recording. The registry is read again here rather than reusing the native check below, which sits on the
+         * far side of that return. The command uses currentPage, the reference tab replacement updates, and the stream context is re-established because an interval
+         * callback does not inherit it - so a rejection logs under this stream's own prefix.
+         */
+        reaffirmTickCounter++;
+        if (((reaffirmTickCounter % SURFACE_REAFFIRM_TICK_INTERVAL) === 0) && (getStream(streamInfo.numericStreamId)?.identity.mode !== "native")) {
+            void runWithStreamContext(streamContext, async () => {
+                try {
+                    await reaffirmCaptureSurface(currentPage);
+                }
+                catch (error) {
+                    LOG.debug("browser:lifecycle", "Could not re-affirm the capture surface: %s.", formatError(error));
+                }
+            });
+        }
         // For static capture profiles (e.g., staticPage), there is no video element to monitor. Skip all video health checks and just emit a status update.
         if (profile.staticCapture) {
             emitStatusUpdate();
@@ -1392,15 +1599,15 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
         // For native streaming mode, monitor segment delivery health instead of video element state. We check the registry on each tick rather than caching the mode at
         // startup because the streaming mode is set after the monitor starts (native streaming is attempted after setupStream returns).
         const nativeEntry = getStream(streamInfo.numericStreamId);
-        if (nativeEntry?.streamingMode === "native") {
-            // Re-establish stream context for this interval tick before running the native health check. AsyncLocalStorage context is lost when entering setInterval
-            // callbacks, so without this wrapper the native path's non-debug warnings would emit without the stream-ID prefix. This mirrors the capture-mode branch below.
+        if (nativeEntry?.identity.mode === "native") {
+            // Re-establish stream context for this interval tick before running the native health check. AsyncLocalStorage context is lost when entering the callback
+            // timer, so without this wrapper the native path's non-debug warnings would emit without the stream-ID prefix. This mirrors the capture-mode branch below.
             dispatchSerializedTick(() => runWithStreamContext(streamContext, async () => {
                 checkNativeStreamHealth(nativeEntry);
             }));
             return;
         }
-        // Re-establish stream context for this interval tick. AsyncLocalStorage context is lost when entering setInterval callbacks.
+        // Re-establish stream context for this interval tick. AsyncLocalStorage context is lost when entering the callback timer.
         dispatchSerializedTick(() => runWithStreamContext(streamContext, async () => {
             try {
                 // Early exit if the stream's abort signal has been triggered. This prevents wasted work when the stream is being terminated.
@@ -1410,7 +1617,7 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
                     return;
                 }
                 // Capture current timestamp for all timing calculations in this check cycle.
-                const now = Date.now();
+                const now = deps.clock.now();
                 // Gather current video state for analysis. The getVideoState helper encapsulates video element selection and returns all properties needed for health analysis.
                 // We catch frame detachment errors specifically to handle context invalidation differently from normal "video not found" cases.
                 let stateInfo = null;
@@ -1418,7 +1625,7 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
                 try {
                     // A read issued while a timeout streak is open is a confirmation probe, so it carries the short bound. With no streak open the read takes the evaluate
                     // wrapper's default, which is the bound that detects a hung tab in the first place.
-                    stateInfo = await getVideoState(currentContext, selectorType, (consecutiveTimeouts > 0) ? UNRESPONSIVE_PROBE_TIMEOUT : undefined);
+                    stateInfo = await getVideoState(currentContext, selectorType, { clock: deps.clock, timeoutMs: (consecutiveTimeouts > 0) ? UNRESPONSIVE_PROBE_TIMEOUT : undefined });
                 }
                 catch (stateError) {
                     // Classify through the shared page-death predicate: the world the read ran in is gone, so the video may simply live in a context we no longer hold.
@@ -1437,7 +1644,7 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
                 if (contextInvalidated) {
                     LOG.debug("recovery:context", "Re-searching for video after context invalidation.");
                     try {
-                        const newContext = await findVideoContext(currentPage, profile);
+                        const newContext = await findVideoContext(currentPage, profile, deps.clock);
                         const validationState = await validateVideoElement(newContext, selectorType);
                         if (validationState.found) {
                             LOG.info("Video found in new context after detachment. readyState=%s.", validationState.readyState);
@@ -1493,19 +1700,11 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
                 // Check if we're within the buffering grace period (recently started buffering and haven't exceeded the threshold).
                 const withinBufferingGrace = isBuffering && bufferingStartTime && ((now - bufferingStartTime) < CONFIG.playback.bufferingGracePeriod);
                 // Check if we're within the recovery grace period (recently performed a recovery action and waiting for it to take effect).
-                const withinRecoveryGrace = now < recoveryState.graceUntil;
+                const withinRecoveryGrace = isWithinRecoveryGrace();
                 // Segment production monitoring: post-recovery verification and continuous size/staleness checks.
                 if (await monitorSegmentHealth(now, withinRecoveryGrace)) {
                     return;
                 }
-                /* Re-minimize check. After recovery, the browser window may have been un-minimized by fullscreen actions. As soon as the stream is healthy (progressing without
-                 * issues), we re-minimize to reduce GPU usage.
-                 */
-                if (pendingReMinimize && isProgressing && !state.paused && !state.error && !state.ended) {
-                    LOG.debug("recovery:general", "Re-minimizing browser window after successful recovery.");
-                    pendingReMinimize = false;
-                    await minimizeWindow(currentPage);
-                }
                 /* Fullscreen reinforcement. Some streaming sites (notably Hulu) revert the video to a mini-player or PiP layout in response to browser state changes such as
                  * window minimization or visibility events. Because the video continues playing normally in the smaller frame, no existing recovery condition is triggered - the
                  * health monitor sees healthy, progressing playback while the captured frame shows a small video in the corner of the viewport. We verify that the video fills
@@ -1582,9 +1781,10 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
                 if (isProgressing && !state.paused && !state.ended && !state.error) {
                     // If a recovery was pending confirmation (L1/L2), log success now that we have healthy playback.
                     if ((metrics.currentRecoveryStartTime !== null) && (metrics.currentRecoveryMethod !== null)) {
-                        const duration = formatRecoveryDuration(metrics.currentRecoveryStartTime);
+                        const settledAt = deps.clock.now();
+                        const duration = formatRecoveryDuration(metrics.currentRecoveryStartTime, settledAt);
                         LOG.info("Recovered in %s via %s.", duration, metrics.currentRecoveryMethod);
-                        recordRecoverySuccess(metrics, metrics.currentRecoveryMethod);
+                        recordRecoverySuccess(metrics, metrics.currentRecoveryMethod, settledAt);
                     }
                     const healthyDuration = now - recoveryState.lastRecoveryTime;
                     if ((recoveryState.escalationLevel > 0) && (healthyDuration > CONFIG.playback.sustainedPlaybackRequired)) {
@@ -1628,11 +1828,24 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
                     LOG.warn("Monitor check timed out (%s consecutive). Tab may be unresponsive.", consecutiveTimeouts);
                     // Update issue state so SSE clients can show the degraded state.
                     lastIssueType = "tab timing out";
-                    lastIssueTime = Date.now();
-                    // After 3 consecutive timeouts, attempt tab replacement if the callback is available.
-                    if ((consecutiveTimeouts >= 3) && onTabReplacement) {
-                        LOG.warn("Tab unresponsive - recovering via %s.", RECOVERY_METHODS.tabReplacement);
-                        await executeTabReplacement("tab unresponsive");
+                    lastIssueTime = deps.clock.now();
+                    /* After 3 consecutive timeouts the tab has stopped answering and only a replacement can save the stream. When one cannot be started, the stream is
+                     * unrecoverable: the ladder has nothing left to try, and leaving it in the registry would hold open the very relaunch that would cure a marked browser.
+                     * So the stream terminates through the breaker, exactly as the zombie case in handleExhaustedTabReplacement does.
+                     *
+                     * None of that runs inside the post-recovery grace window. A tab that has just been replaced is entitled to its settling time, and evaluate calls
+                     * against a page mid-establishment time out for reasons that are not a wedged tab - so escalating here would spend an attempt, or terminate a stream,
+                     * on evidence the window exists to discount. The timeout tally keeps climbing, so a genuinely wedged tab is acted on the moment the window closes.
+                     */
+                    if ((consecutiveTimeouts >= 3) && !isWithinRecoveryGrace()) {
+                        if (canReplaceTab()) {
+                            LOG.warn("Tab unresponsive - recovering via %s.", RECOVERY_METHODS.tabReplacement);
+                            await executeTabReplacement("tab unresponsive");
+                            return;
+                        }
+                        LOG.error("Tab unresponsive and tab replacement is unavailable (%s) - terminating stream.", tabReplacementUnavailableReason());
+                        stopMonitoring();
+                        onCircuitBreak();
                         return;
                     }
                     // Emit status so SSE clients see current duration/memory even during timeout degradation (when consecutiveTimeouts < 3).
@@ -1657,7 +1870,7 @@ export function monitorPlaybackHealth(page, context, profile, url, streamId, str
             // Log errors that escape the inner try/catch. In normal operation we should not reach here - if we do, there's a bug to investigate.
             LOG.warn("Monitor tick error escaped inner try/catch: %s.", formatError(outerError));
         }));
-    }, CONFIG.playback.monitorInterval);
+    }, CONFIG.playback.monitorInterval, { repeat: true });
     /* The monitor's teardown: mark the interval cleared (so any in-flight async tick short-circuits) and clear it. Self-contained - it owns only the interval. Defined
      * as a const so it is exposed as both dispose() and [Symbol.dispose].
      */