prismcast 1.12.0 → 1.13.0

package/dist/streaming/hls.js

@@ -1,10 +1,10 @@
-import { LOG, formatError, runWithStreamContext, startTimer } from "../utils/index.js";
+import { LOG, formatError, formatResolutionLabel, runWithStreamContext, startTimer } from "../utils/index.js";
 import { StreamSetupError, createPageWithCapture, generateStreamId, reestablishChannelManifest, setupStream, validateStreamUrl } from "./setup.js";
+import { applyNativeQualityRefresh, cancelPrerollTimer, createHLSState, getAllStreams, getNextStreamId, getStream, getStreamCount, isCaptureIdentity, makePendingCaptureIdentity, registerStream, updateLastAccess } from "./registry.js";
 import { buildProbeCacheStamp, clearProbeCache } from "../native/probe.js";
-import { cancelPrerollTimer, createHLSState, getAllStreams, getNextStreamId, getStream, getStreamCount, registerStream, updateLastAccess } from "./registry.js";
 import { createInitialStreamStatus, emitStreamAdded } from "./statusEmitter.js";
 import { deleteResumeData, getResumeSegmentIndex, peekResumeData } from "./hlsResume.js";
-import { emitCurrentSystemStatus, isLoginModeActive, unregisterManagedPage } from "../browser/index.js";
+import { emitCurrentSystemStatus, isLoginModeActive, syncWindowVisibility, unregisterManagedPage } from "../browser/index.js";
 import { generatePrerollPlaylist, getPrerollCodec, getPrerollSegmentCount, isPrerollReady } from "./preroll.js";
 import { getAllChannels, getChannelLogo, isPredefinedChannelDisabled } from "../config/userChannels.js";
 import { getAudioPlaylist, getAudioSegment, getInitSegment, getNamedInitSegment, getPlaylist, getSegment, getVideoPlaylist, waitForPlaylist } from "./hlsSegments.js";
@@ -19,6 +19,7 @@ import { createHash } from "node:crypto";
 import { getProviderBySlug } from "../browser/channelSelection.js";
 import { registerClient } from "./clients.js";
 import { suppressPageAudio } from "../browser/video.js";
+import { systemClock } from "homebridge-plugin-utils";
 import { triggerShowNameUpdate } from "./showInfo.js";
 /* This module handles HLS (HTTP Live Streaming) output using fMP4 (fragmented MP4) segments. HLS mode uses MP4/AAC capture from puppeteer-stream, which is then
  * segmented natively without any external dependencies. The stream initialization flow has three phases:
@@ -46,6 +47,9 @@ import { triggerShowNameUpdate } from "./showInfo.js";
 // content directly. This ensures fast-tuning services (native HLS at 2-3s, most capture services at 4-7s) never see preroll, while slow services (Xfinity/Cox at
 // 13-15s) get preroll content after the delay to prevent HTTP timeouts.
 const PREROLL_DELAY_MS = 9000;
+// How long a playlist request waits for a playlist to exist, in milliseconds. It bounds the window between a pending entry's registration and the first playlist
+// from either the preroll timer or the segmenter, so a setup that hangs without ever failing cannot hold a client request open indefinitely.
+const PLAYLIST_WAIT_MS = 30000;
 /**
  * Builds the onError/onStop callbacks for createFMP4Segmenter. Both callbacks share the same termination chain (skip-if-already-terminating guard, log error,
  * terminate stream, emit current system status); the only differences between callsites are the log-message and termination-reason suffixes used to mark the
@@ -137,10 +141,45 @@ export function sendValidationError(validation, res) {
         res.status(validation.statusCode).send(validation.body);
     }
 }
+/**
+ * Describes a stream setup failure as the status and message the client is answered with. A StreamSetupError carries its own status and user-facing text, which is
+ * the meaning the setup path assigned to the failure; anything else is unexpected and the client learns nothing beyond a 500.
+ * @param error - The error a setup path produced.
+ * @returns The status and message this failure answers with.
+ */
+export function describeSetupFailure(error) {
+    if (error instanceof StreamSetupError) {
+        return { statusCode: error.statusCode, userMessage: error.userMessage };
+    }
+    return { statusCode: 500, userMessage: "Internal server error." };
+}
+/**
+ * Sends a described setup failure to the client. Every streaming route answers a setup failure through here, so one failure means one response shape no matter
+ * which route the client arrived on.
+ *
+ * A 503 carries both back-off headers on every route: Channels DVR reads Retry-After and waits instead of retrying in a tight loop, and an HDHomeRun client reads
+ * X-HDHomeRun-Error to tell a busy tuner apart from a broken one. A response whose headers are already flushed can carry no status at all, so it is ended and the
+ * client sees the connection close.
+ *
+ * Logging stays with the callers: each route describes its own failure in its own words and at its own level.
+ * @param failure - The described failure, from describeSetupFailure or from a literal the caller composed.
+ * @param res - Express response object.
+ */
+export function sendSetupFailure(failure, res) {
+    if (res.headersSent) {
+        res.end();
+        return;
+    }
+    if (failure.statusCode === 503) {
+        res.setHeader("Retry-After", "10");
+        res.setHeader("X-HDHomeRun-Error", "All Tuners In Use");
+    }
+    res.status(failure.statusCode).send(failure.userMessage);
+}
 // Capacity Reservation.
 /**
  * Pure predicate for the concurrent-stream capacity decision. Returns true when a new stream may be admitted given the current active count and the configured
- * limit. Extracted as a standalone function so the boundary arithmetic is pinned by a unit test without driving a browser. The count passed in must be the count
+ * limit. Extracted as a standalone function so the boundary arithmetic is asserted by a unit test without driving a browser. The count passed in must be the count
  * BEFORE the new stream's pending entry is registered, so the new stream is naturally excluded from its own capacity check; admitting the final slot
  * (active === maxConcurrent - 1) returns true.
  * @param activeCount - Number of streams currently registered, excluding the stream being admitted.
@@ -203,11 +242,10 @@ export async function ensureChannelStream(channelName, req, res) {
         // Reserve a capacity slot before registering the pending entry. The pending entry occupies a registry slot the instant it is registered, so the capacity
         // decision must happen here - while the new stream is still excluded from the count - to avoid a later self-counting check rejecting it after the client has
         // already received a preroll playlist. reserveStreamSlot is the single source of truth for this decision and reclaims an idle stream when at the limit. On
-        // failure we send a proper 503 here, before any registration or preroll response.
+        // failure we answer here, before any registration or preroll response, through the shared responder that writes the back-off headers for every route.
         if (!reserveStreamSlot()) {
-            res.setHeader("Retry-After", "10");
-            res.setHeader("X-HDHomeRun-Error", "All Tuners In Use");
-            res.status(503).send("Maximum concurrent streams (" + String(CONFIG.streaming.maxConcurrentStreams) + ") reached. Try again later.");
+            const refusal = "Maximum concurrent streams (" + String(CONFIG.streaming.maxConcurrentStreams) + ") reached. Try again later.";
+            sendSetupFailure({ statusCode: 503, userMessage: refusal }, res);
             return null;
         }
         const clientAddress = req.ip ?? req.socket.remoteAddress ?? null;
@@ -262,6 +300,8 @@ export async function handleHLSPlaylist(req, res) {
  * @param res - Express response object.
  */
 export function handleHLSSegment(req, res) {
+    // The serve instant, read once at this request boundary and used for whichever access stamp the branch below writes.
+    const now = systemClock.now();
     const channelName = req.params.name;
     const segmentName = req.params.segment;
     if (!channelName || !segmentName) {
@@ -280,7 +320,7 @@ export function handleHLSSegment(req, res) {
             res.status(404).send("Init segment not found.");
             return;
         }
-        updateLastAccess(streamId);
+        updateLastAccess(streamId, now);
         sendSegment(initSegment, "init.mp4", res);
         return;
     }
@@ -292,7 +332,7 @@ export function handleHLSSegment(req, res) {
         res.status(404).send("Segment not found.");
         return;
     }
-    updateLastAccess(streamId);
+    updateLastAccess(streamId, now);
     sendSegment(segment, segmentName, res);
 }
 /**
@@ -305,6 +345,8 @@ export function handleHLSSegment(req, res) {
  * @param res - Express response object.
  */
 export function handleHLSVariantPlaylist(req, res) {
+    // The serve instant, read once at this request boundary.
+    const now = systemClock.now();
     const channelName = req.params.name;
     // Extract the playlist filename from the URL path. The route is registered as two explicit paths (/video.m3u8 and /audio.m3u8) rather than a parameterized route,
     // so there is no :playlist param to read.
@@ -330,7 +372,7 @@ export function handleHLSVariantPlaylist(req, res) {
         res.status(404).send("Playlist not found.");
         return;
     }
-    updateLastAccess(streamId);
+    updateLastAccess(streamId, now);
     sendPlaylist(playlist, res);
 }
 // Ad-Hoc Streaming.
@@ -393,15 +435,11 @@ export async function handlePlayStream(req, res) {
         }
     }
     catch (error) {
-        if (error instanceof StreamSetupError) {
-            if (error.statusCode === 503) {
-                res.setHeader("Retry-After", "10");
-            }
-            res.status(error.statusCode).send(error.userMessage);
-            return;
+        // A StreamSetupError is an expected refusal whose message is already meant for the client, so only an unexpected failure earns an error log here.
+        if (!(error instanceof StreamSetupError)) {
+            LOG.error("Unexpected error during ad-hoc stream setup: %s.", formatError(error));
         }
-        LOG.error("Unexpected error during ad-hoc stream setup: %s.", formatError(error));
-        res.status(500).send("Internal server error.");
+        sendSetupFailure(describeSetupFailure(error), res);
         return;
     }
     res.redirect(302, "/hls/" + channelName + "/stream.m3u8");
@@ -411,7 +449,8 @@ export async function handlePlayStream(req, res) {
  * Sends the playlist for a stream. With the deferred preroll timer, the playlist may not be available immediately after stream registration - it arrives when either
  * the timer fires (seeding preroll) or the segmenter produces real content, whichever comes first. This function awaits the playlistReady promise to handle that
  * window. For the blocking fallback path (no FFmpeg / no preroll), the playlist is guaranteed to exist because initializeStream blocks until the segmenter produces
- * it. Returns 404 only if the stream was terminated or the playlist wait timed out.
+ * it. A stream whose setup failed answers with that failure's status, so the client learns the tune was refused; a stream terminated for any other reason, or a
+ * wait that timed out, answers 404.
  * @param streamId - The numeric stream ID.
  * @param clientAddress - Client address for tracking.
  * @param res - Express response object.
@@ -419,26 +458,40 @@ export async function handlePlayStream(req, res) {
 async function sendPlaylistResponse(streamId, clientAddress, res) {
     let playlist = getPlaylist(streamId);
     // The playlist may not be populated yet if the deferred preroll timer hasn't fired and the segmenter hasn't produced content. Wait for the playlistReady promise
-    // which resolves when either source provides a playlist. The 30-second timeout covers pathological cases like setup hanging.
+    // which resolves when either source provides a playlist. The bounded wait covers pathological cases like setup hanging.
     if (!playlist) {
-        const ready = await waitForPlaylist(streamId, 30000);
+        /* The reference a failed setup's status is read through, taken before the wait rather than after it. A setup failure records its status on this entry and then
+         * leaves the registry in the same synchronous run that wakes this wait, so a lookup on the far side would find nothing where the reference taken here still
+         * reaches the entry object.
+         */
+        const waiting = getStream(streamId);
+        const ready = await waitForPlaylist(streamId, PLAYLIST_WAIT_MS);
         if (ready) {
             playlist = getPlaylist(streamId);
         }
+        // A refused tune answers with the refusal's own status, which is what tells Channels DVR to back off - a 404 carries no back-off and invites an immediate
+        // retry of a stream that is not coming.
+        if (!playlist && waiting?.hls.setupFailure) {
+            sendSetupFailure(waiting.hls.setupFailure, res);
+            return;
+        }
     }
     if (!playlist) {
         res.status(404).send("Stream not found.");
         return;
     }
-    updateLastAccess(streamId);
-    registerClient(streamId, clientAddress, "hls");
+    // The serve instant, so the stream's access stamp and the client's last-seen both carry the moment the response is served.
+    const now = systemClock.now();
+    updateLastAccess(streamId, now);
+    registerClient(streamId, clientAddress, "hls", now);
     // When still serving preroll, regenerate the progressive playlist on each poll so the sliding window advances based on elapsed wall-clock time. This simulates a
     // live stream - the client sees new segments appear on each poll and keeps playing without stalling. Once real content arrives, hasRealPlaylist becomes true and
     // the segmenter's playlist takes over.
     const stream = getStream(streamId);
     if (stream && !stream.hls.hasRealPlaylist) {
-        if (stream.hls.prerollBaseUrl && stream.hls.prerollCodec && stream.hls.prerollStartTime) {
-            playlist = generatePrerollPlaylist(stream.hls.prerollBaseUrl, stream.hls.prerollCodec, stream.hls.resumeSegmentIndex, stream.hls.prerollStartTime);
+        if (stream.hls.prerollBaseUrl && stream.hls.prerollCodec && (stream.hls.prerollStartTime !== null)) {
+            playlist = generatePrerollPlaylist({ baseUrl: stream.hls.prerollBaseUrl, codec: stream.hls.prerollCodec, now,
+                prerollStartTime: stream.hls.prerollStartTime, startingSequence: stream.hls.resumeSegmentIndex });
         }
         LOG.debug("streaming:preroll", "Serving preroll playlist for stream %d.", streamId);
     }
@@ -471,8 +524,6 @@ function sendSegment(data, segmentName, res) {
     res.send(data);
 }
 // Stream Lifecycle.
-// Maps vertical resolution heights to standard display labels. Used by formatNativeQuality() to convert "1920x1080" -> "1080p".
-const RESOLUTION_LABELS = { "1080": "1080p", "2160": "4K", "360": "360p", "480": "480p", "720": "720p" };
 /**
  * Formats the native HLS quality string for the "Streaming..." log line. Combines codec, bandwidth (as Mbps), and resolution (as standard label like "1080p")
  * into a compact suffix. Returns an empty string when no values are available, or a comma-prefixed string like ", H264 12.1Mbps 1080p" for inclusion in the log.
@@ -490,28 +541,79 @@ function formatNativeQuality(bandwidth, codec, resolution) {
         parts.push((bandwidth / 1000000).toFixed(1) + "Mbps");
     }
     if (resolution) {
-        // Map the vertical resolution to a standard label. Parse the height from "WIDTHxHEIGHT" format.
-        const height = resolution.split("x")[1];
-        parts.push((height ? RESOLUTION_LABELS[height] : undefined) ?? resolution);
+        parts.push(formatResolutionLabel(resolution));
     }
     if (parts.length === 0) {
         return "";
     }
     return ", " + parts.join(" ");
 }
+const defaultTabReplacementDeps = { createPageWithCapture, unregisterManagedPage };
 /**
- * Creates a tab replacement handler for recovery from unresponsive browser tabs. When the monitor detects 3+ consecutive evaluate timeouts, it calls this handler to:
- * 1. Stop the current segmenter and FFmpeg process
- * 2. Close the unresponsive page
- * 3. Create a fresh page with new capture
- * 4. Create a new segmenter piped to the new capture
- * 5. Update the registry with the new resources
- * 6. Return the new page and context for the monitor to continue
+ * Swaps a freshly established capture pipeline in for the one a stream is running on. This is deliberately a plain, non-async function: everything below runs in
+ * a single synchronous frame, so no tick, client request, monitor pass, or termination can interleave between the old pipeline's disposal and the new one's
+ * installation. Two segmenters therefore never write one HLS state, the registry never holds two pipelines, and the monitor's post-replacement state reset -
+ * which reads the registry's segmenter immediately after this returns - is reading the new pipeline by construction rather than by timing.
+ *
+ * Keeping it a separate function rather than a block inside the handler is what protects that: an await added here is a syntax error rather than a review catch.
+ *
+ * The continuity read lives here, at the swap, and not at the top of the replacement. The old segmenter keeps producing throughout the minute or more the
+ * replacement page spends navigating and tuning, so its segment index, track timestamps, and session statistics all advance across that window - a read taken
+ * before the tune would seed the new segmenter with a stale sequence and rewind the playlist.
+ * @param options - The entry, the fresh pipeline, the outgoing page, and the encoder facts carried forward.
+ */
+function spliceReplacementCapture(options) {
+    const { captureResult, channelName, deps, entry, numericStreamId, oldCaptureCodec, oldHardwareAccelerated, oldPage, streamId } = options;
+    // Read the outgoing segmenter's continuity at the last possible instant, then tear its pipeline down. The CaptureSession kills the FFmpeg child first (which
+    // silences that pipeline's stream listeners for good), then destroys the capture stream - which MUST happen before the old page closes, so chrome.tabCapture
+    // releases and a later acquisition does not fail with "Cannot capture a tab with an active stream" - then stops the segmenter. The session is null on the
+    // capture-pending identity a native fallback arrives with, which is why the read is guarded.
+    const oldSession = (entry.identity.mode === "capture") ? entry.identity.captureSession : null;
+    const continuity = oldSession?.segmenter?.getContinuitySnapshot();
+    if (oldSession) {
+        LOG.debug("recovery:tab", "Disposing the outgoing capture pipeline at the swap.");
+        oldSession.dispose();
+    }
+    // Release the outgoing page. It has been serving the stream up to this instant, so the close is what ends it.
+    if (oldPage) {
+        deps.unregisterManagedPage(oldPage);
+        if (!oldPage.isClosed()) {
+            LOG.debug("recovery:tab", "Closing the outgoing page for stream %s.", streamId);
+            oldPage.close().catch((error) => {
+                LOG.debug("recovery:tab", "Page close error during tab replacement: %s.", formatError(error));
+            });
+        }
+    }
+    // Build the new segmenter on the continuity just read, and mark its first segment with a discontinuity tag so clients flush decoder state. The tag is
+    // suppressed automatically when the new init segment turns out byte-identical to the old one.
+    const newSegmenter = createFMP4Segmenter({
+        ...buildSegmenterTerminationHandlers(numericStreamId, channelName, { logSuffix: "after tab replacement", reasonSuffix: "after recovery" }),
+        ...(continuity ? { continuity } : {}),
+        pendingDiscontinuity: true,
+        streamId: numericStreamId
+    });
+    // Wire the new segmenter into the new capture session (attachSegmenter pipes the session's capture output into it), then re-point the entry at the new
+    // pipeline and page. The identity is a pure literal because this is a within-mode replacement of the whole value, not a refresh of part of one.
+    captureResult.captureSession.attachSegmenter(newSegmenter);
+    entry.identity = { captureCodec: oldCaptureCodec, captureSession: captureResult.captureSession, hardwareAccelerated: oldHardwareAccelerated, mode: "capture" };
+    entry.page = captureResult.page;
+}
+/**
+ * Creates a tab replacement handler for recovery from unresponsive browser tabs. The replacement builds before it tears down:
+ *
+ * 1. Create a fresh page and acquire its capture, and tune it, while the existing pipeline keeps producing segments for the client
+ * 2. If anything fails before the swap, discard the fresh page and capture and leave the existing pipeline untouched - a logged recovery miss, not a lost recording
+ * 3. Otherwise swap in one synchronous frame: read the old segmenter's continuity, dispose the old pipeline, close the old page, splice the new one in
+ * 4. Return the new page and context for the monitor to continue on
+ *
+ * Because nothing is disposed until the swap, the monitor's single retry re-reads continuity from the still-live old segmenter on its second attempt, and a
+ * stream whose replacement keeps failing keeps serving its recording while the circuit breaker counts.
  *
- * The handler preserves existing HLS segments and marks a discontinuity so clients know the stream parameters may have changed.
+ * The handler preserves existing HLS segments and marks a discontinuity so clients know the stream parameters may have changed. The cost of the overlap is a
+ * second capture and encoder running for the length of the tune, which the CPU and GPU carry.
  *
- * Note: This handler is only invoked for capture-mode streams. Native-mode streams bypass video element monitoring entirely (the monitor early-returns for native
- * streams), so evaluate timeouts that trigger tab replacement cannot occur.
+ * Note: This handler is only invoked for capture-mode streams, plus the native fallback that has already declared a pending capture identity. Native-mode
+ * streams bypass video element monitoring entirely, so evaluate timeouts that trigger tab replacement cannot occur on one.
  *
  * @param numericStreamId - The stream's numeric ID for registry lookups.
  * @param streamId - The stream's string ID for logging.
@@ -520,9 +622,11 @@ function formatNativeQuality(bandwidth, codec, resolution) {
  * @param profile - The site profile for video handling.
  * @param metadataComment - Optional comment to embed in FFmpeg output metadata.
  * @param onCircuitBreak - Callback for circuit breaker trips during replacement.
+ * @param deps - The injected establishment collaborators; defaults to defaultTabReplacementDeps. Threaded so a test drives the real handler - its phase tracking,
+ *               its discard path, and the swap itself - against a substituted establishment rather than a live Chrome.
  * @returns A handler function that performs tab replacement, or null if the stream no longer exists.
  */
-function createTabReplacementHandler(numericStreamId, streamId, channelName, url, profile, metadataComment, onCircuitBreak) {
+export function createTabReplacementHandler(numericStreamId, streamId, channelName, url, profile, metadataComment, onCircuitBreak, deps = defaultTabReplacementDeps) {
     return async () => {
         const tabElapsed = startTimer();
         // Get the current stream entry.
@@ -531,41 +635,32 @@ function createTabReplacementHandler(numericStreamId, streamId, channelName, url
             LOG.debug("recovery:tab", "Tab replacement requested but stream %s no longer exists.", streamId);
             return null;
         }
-        // Get the current init segment, segment index, and per-track timestamps from the old segmenter before stopping it. The init segment enables discontinuity
-        // suppression when codec parameters are unchanged, the segment index allows the new segmenter to continue numbering, and the track timestamps ensure monotonic
-        // baseMediaDecodeTime across capture restarts.
-        const oldSegmenter = stream.captureSession?.segmenter;
-        const currentInitSegment = oldSegmenter?.getInitSegment();
-        const currentInitVersion = oldSegmenter?.getInitVersion() ?? 0;
-        const currentSegmentIndex = oldSegmenter?.getSegmentIndex() ?? 0;
-        const currentSessionStats = oldSegmenter?.getSessionStats();
-        const currentTrackTimestamps = oldSegmenter?.getTrackTimestamps();
-        // Dispose the OLD capture pipeline. The CaptureSession kills the FFmpeg child first (setting its shuttingDown flag before the capture stream's EOF can reach
-        // FFmpeg's stdin), then destroys the capture stream (which MUST happen before the old page is closed below, so chrome.tabCapture releases the capture and the
-        // new getStream() does not hang with "Cannot capture a tab with an active stream"), then stops the segmenter. The new pipeline is constructed fresh further down.
-        if (stream.captureSession) {
-            LOG.debug("recovery:tab", "Disposing old capture pipeline for tab replacement.");
-            stream.captureSession.dispose();
-        }
-        // Close the current page. The page may be null for pending entries whose async setup has not yet completed.
-        const oldPage = stream.page;
-        if (oldPage) {
-            unregisterManagedPage(oldPage);
-            if (!oldPage.isClosed()) {
-                LOG.debug("recovery:tab", "Closing unresponsive page for tab replacement.");
-                oldPage.close().catch((error) => {
-                    LOG.debug("recovery:tab", "Page close error during tab replacement: %s.", formatError(error));
-                });
-            }
-        }
-        LOG.debug("timing:tab", "Old tab cleanup complete. (+%sms)", tabElapsed());
-        // Create a new page with capture.
+        /* The encoder facts the replacement carries forward, read now off the identity that is still serving the stream. A replacement changes the page, not the
+         * codec decision, so this is the only source for them: the fresh capture result carries no codec or acceleration of its own.
+         */
+        const oldCaptureCodec = isCaptureIdentity(stream) ? stream.identity.captureCodec : null;
+        const oldHardwareAccelerated = isCaptureIdentity(stream) && stream.identity.hardwareAccelerated;
+        /* Where this attempt stands, from the perspective of the fresh pipeline's own FFmpeg error callback. One tri-state rather than a pair of flags, so "failed
+         * and committed at once" is not something the code can express. It is held on a small record because the callback and the frame awaiting establishment both
+         * have to see the same value across an await, which a captured local does not give the reader or the compiler.
+         *
+         * The phase is local to a single attempt, moves at most once, and is never reset: the monitor's retry runs this function again and gets a fresh one. While
+         * the attempt is pending, an FFmpeg fault belongs to a pipeline that is not the stream yet, so it must not reach the circuit breaker - the stream it would
+         * terminate is the one still running happily on the old page. Once the swap has committed, the new pipeline IS the stream and a fault is treated exactly as
+         * it always has been.
+         */
+        const attempt = { phase: "pending" };
+        // Create the replacement page and acquire its capture, with the existing pipeline still producing throughout.
         let captureResult;
         try {
-            captureResult = await createPageWithCapture({
+            captureResult = await deps.createPageWithCapture({
                 comment: metadataComment,
-                numericStreamId,
                 onFFmpegError: (error) => {
+                    if (attempt.phase !== "committed") {
+                        LOG.warn("The replacement capture's FFmpeg failed before it took over: %s. The existing capture continues.", formatError(error));
+                        attempt.phase = "failed";
+                        return;
+                    }
                     LOG.error("FFmpeg error during tab replacement recovery: %s.", formatError(error));
                     onCircuitBreak();
                 },
@@ -576,42 +671,32 @@ function createTabReplacementHandler(numericStreamId, streamId, channelName, url
             });
         }
         catch (error) {
-            LOG.warn("Failed to create new page during tab replacement: %s.", formatError(error));
+            LOG.warn("Could not establish a replacement capture for this stream: %s. The existing capture continues.", formatError(error));
             return null;
         }
         LOG.debug("timing:tab", "New page with capture created. (+%sms)", tabElapsed());
-        // Re-check the stream before adopting the fresh resources. The awaited createPageWithCapture above yields the event loop, so the stream can terminate mid-await;
-        // the entry writes below would then attach the new page and capture session to an entry that termination already disposed, orphaning both. Tear the fresh resources
-        // down in the same order the old-pipeline teardown above uses - dispose the capture session first so chrome.tabCapture releases cleanly, then unregister the
-        // managed page, then close it - and abandon the replacement.
-        if (!getStream(numericStreamId)) {
+        /* Re-check before committing. The awaited establishment above yields the event loop for the length of a tune, so two things can have happened meanwhile: the
+         * stream can have terminated - in which case termination found exactly one pipeline in the registry, the old one, and disposed it - or the fresh pipeline's
+         * own FFmpeg can have failed, which the swap-aware callback recorded. Either way the fresh page and capture are discarded in the teardown order every other
+         * site uses (dispose the session first so chrome.tabCapture releases cleanly, then unregister the managed page, then close it) and the stream is left exactly
+         * as it was. A discarded session's FFmpeg is killed by that dispose, which is what keeps the discard silent.
+         */
+        const entry = getStream(numericStreamId);
+        if (!entry || (attempt.phase === "failed")) {
             captureResult.captureSession.dispose();
-            unregisterManagedPage(captureResult.page);
+            deps.unregisterManagedPage(captureResult.page);
             if (!captureResult.page.isClosed()) {
                 captureResult.page.close().catch((error) => {
                     LOG.debug("recovery:tab", "Page close error during aborted tab replacement: %s.", formatError(error));
                 });
             }
-            LOG.debug("recovery:tab", "Stream %s terminated during tab replacement - discarded the fresh page and capture session.", streamId);
+            LOG.debug("recovery:tab", "Abandoned the tab replacement for stream %s - discarded the fresh page and capture session.", streamId);
             return null;
         }
-        // Create a new segmenter for the new capture stream. Continue from the current segment index for playlist continuity, pass the per-track timestamp counters
-        // for monotonic baseMediaDecodeTime, and mark the first segment with a discontinuity tag so clients know the stream parameters may have changed.
-        const newSegmenter = createFMP4Segmenter({
-            initialTrackTimestamps: currentTrackTimestamps,
-            ...buildSegmenterTerminationHandlers(numericStreamId, channelName, { logSuffix: "after tab replacement", reasonSuffix: "after recovery" }),
-            pendingDiscontinuity: true,
-            previousInitSegment: currentInitSegment,
-            priorSessionStats: currentSessionStats,
-            startingInitVersion: currentInitVersion,
-            startingSegmentIndex: currentSegmentIndex,
-            streamId: numericStreamId
-        });
-        // Wire the new segmenter into the new capture session (attachSegmenter pipes the session's capture output into it), then install the session and page on the
-        // registry entry.
-        captureResult.captureSession.attachSegmenter(newSegmenter);
-        stream.captureSession = captureResult.captureSession;
-        stream.page = captureResult.page;
+        // The swap, and the commit that follows it in the same synchronous frame. Nothing separates the two, so the error callback can never observe a stream whose
+        // registry entry has moved on while the attempt still reads as pending.
+        spliceReplacementCapture({ captureResult, channelName, deps, entry, numericStreamId, oldCaptureCodec, oldHardwareAccelerated, oldPage: entry.page, streamId });
+        attempt.phase = "committed";
         LOG.info("Tab replacement complete. New capture started with segment continuity.");
         LOG.debug("timing:tab", "Tab replacement complete. Total: %sms.", tabElapsed());
         return {
@@ -667,6 +752,8 @@ export async function initializeStream(options) {
  * @returns The allocated stream IDs.
  */
 function registerPendingStream(channelName, channel, clientAddress, req, codec) {
+    // The registration instant, read once at this composition point and used for the resume-index read, the entry's start time, and the preroll timer's arming.
+    const now = systemClock.now();
     const numericStreamId = getNextStreamId();
     const streamIdStr = generateStreamId(channelName, channel.url);
     // Derive the base URL from the request for absolute preroll segment URLs.
@@ -675,16 +762,16 @@ function registerPendingStream(channelName, channel, clientAddress, req, codec)
     const host = forwardedHost ? (forwardedHost.split(",")[0] ?? "").trim() : req.get("host");
     const fallbackHost = CONFIG.server.host + ":" + String(CONFIG.server.port);
     const baseUrl = protocol + "://" + (host ?? fallbackHost);
-    // Create HLS state with a deferred preroll timer. The timer fires after PREROLL_DELAY_MS - if stream setup hasn't completed by then, preroll is seeded and the
-    // playlist response is unblocked. For resume streams, the preroll's MEDIA-SEQUENCE is offset by the saved segment index so it continues from the prior session's
-    // sequence range. The timer is disarmed through cancelPrerollTimer() once real content arrives or preroll state is otherwise invalidated, so it cannot fire against
-    // state that has moved on.
+    // Create HLS state with a deferred preroll timer - a one-shot on the system clock whose handle the single disarm point disposes. The timer fires after
+    // PREROLL_DELAY_MS - if stream setup hasn't completed by then, preroll is seeded and the playlist response is unblocked. For resume streams, the preroll's
+    // MEDIA-SEQUENCE is offset by the saved segment index so it continues from the prior session's sequence range. The timer is disarmed through
+    // cancelPrerollTimer() once real content arrives or preroll state is otherwise invalidated, so it cannot fire against state that has moved on.
     const hls = createHLSState();
     // Snapshot the resume segment index once at registration. Both the preroll timer callback and completeStreamSetup() use this single snapshot, eliminating the TTL
     // race that would occur if each read the resume map independently at different times.
-    hls.resumeSegmentIndex = getResumeSegmentIndex(channelName) ?? 0;
+    hls.resumeSegmentIndex = getResumeSegmentIndex(channelName, now) ?? 0;
     // Capture the stream start time at registration. This timestamp is used for the registry's startTime field (stream age display, etc.).
-    const streamStartTime = new Date();
+    const streamStartTime = now;
     if (isPrerollReady(codec)) {
         // Set preroll metadata immediately at registration so the segmenter and native proxy can read it regardless of whether the deferred timer has fired. The segment
         // count, codec, and base URL are structural properties of the preroll system - they determine segment index offsets, codec-aware URL paths, and composite playlist
@@ -693,11 +780,12 @@ function registerPendingStream(channelName, channel, clientAddress, req, codec)
         hls.prerollBaseUrl = baseUrl;
         hls.prerollCodec = codec;
         hls.prerollSegmentCount = getPrerollSegmentCount(codec);
-        hls.prerollTimer = setTimeout(() => {
+        hls.prerollTimer = systemClock.schedule(() => {
             // Record the preroll start time and seed the initial progressive playlist. On subsequent polls, sendPlaylistResponse() regenerates the playlist with an
-            // advancing window based on elapsed time from this start time, simulating a live stream.
-            hls.prerollStartTime = new Date();
-            hls.playlist = generatePrerollPlaylist(baseUrl, codec, hls.resumeSegmentIndex, hls.prerollStartTime);
+            // advancing window based on elapsed time from this start time, simulating a live stream. The reveal at the fire instant is the initial window.
+            const firedAt = systemClock.now();
+            hls.prerollStartTime = firedAt;
+            hls.playlist = generatePrerollPlaylist({ baseUrl, codec, now: firedAt, prerollStartTime: firedAt, startingSequence: hls.resumeSegmentIndex });
             hls.signalPlaylistReady();
         }, PREROLL_DELAY_MS);
     }
@@ -713,46 +801,51 @@ function registerPendingStream(channelName, channel, clientAddress, req, codec)
  */
 function createPendingEntry(options) {
     const { channel, channelName, hls, numericStreamId, streamIdStr, url } = options;
+    // The registration instant, read once so the access stamp and the entry's start time agree when the caller supplied no start of its own.
+    const now = systemClock.now();
     registerStream({
-        captureCodec: null,
-        captureSession: null,
         channelName: channel?.name ?? null,
         clientAddress: options.clientAddress ?? null,
-        hardwareAccelerated: false,
         hls,
         id: numericStreamId,
+        identity: makePendingCaptureIdentity(),
         info: {
-            lastPlaylistRequest: Date.now(),
+            lastPlaylistRequest: now,
             storeKey: channelName
         },
         monitor: null,
         mpegTsClientCount: 0,
-        nativeBandwidth: 0,
-        nativeContainer: null,
-        nativeProxy: null,
-        nativeResolution: null,
         page: null,
         preTuned: options.preTuned ?? false,
         probeIdentity: null,
         profile: null,
-        reestablishManifest: null,
-        startTime: options.streamStartTime ?? new Date(),
+        startTime: options.streamStartTime ?? now,
         streamIdStr,
-        streamingMode: "capture",
         url
     });
     setChannelStreamId(channelName, numericStreamId);
 }
 /**
- * Handles stream setup failure by marking channel health, terminating the pending entry, and optionally logging the error. The blocking path (initializeStream) skips
- * logging because it re-throws for callers to handle. The non-blocking path (ensureChannelStream .catch) logs because there is no outer handler.
+ * Handles stream setup failure by recording the failure's status on the pending entry, marking channel health, terminating the entry, and optionally logging the
+ * error. The blocking path (initializeStream) skips logging because it re-throws for callers to handle. The non-blocking path (ensureChannelStream .catch) logs
+ * because there is no outer handler.
+ *
+ * Exported for unit-test coverage of the ordering the recorded status depends on. Production callers reach this only through the setup paths above, never directly.
  * @param numericStreamId - The pending entry's numeric stream ID.
  * @param channelName - The channel key for health tracking and termination.
  * @param channel - The channel definition, or undefined for ad-hoc streams (no health tracking).
  * @param error - The error that caused the failure.
  * @param logError - Whether to log the error. False when the caller will re-throw (blocking path), true when fire-and-forget (non-blocking path).
  */
-function handleSetupFailure(numericStreamId, channelName, channel, error, logError = true) {
+export function handleSetupFailure(numericStreamId, channelName, channel, error, logError = true) {
+    /* Record what this failure answers with before anything tears the entry down. terminateStream unregisters the entry in the same synchronous run in which it
+     * wakes every request waiting on this stream, so a request that resumes afterward finds nothing in the registry to read - the status has to be on the entry
+     * object by then. A waiting request holds its own reference to that object, taken before its wait, and reads the status through it.
+     */
+    const entry = getStream(numericStreamId);
+    if (entry) {
+        entry.hls.setupFailure = describeSetupFailure(error);
+    }
     // Mark channel health as failed. Only for predefined channels (channel is defined). Ad-hoc URL streams have no persistent channel identity.
     if (channel) {
         const failVariantKey = resolveServiceKey(channelName);
@@ -821,9 +914,7 @@ async function startNativeProxy(setup, numericStreamId, channelName, url, mpegTs
             if (!refreshed) {
                 return;
             }
-            refreshed.captureCodec = metadata.codec;
-            refreshed.nativeBandwidth = metadata.bandwidth;
-            refreshed.nativeResolution = metadata.resolution;
+            applyNativeQualityRefresh(refreshed, metadata);
         },
         page: setup.page,
         prerollCodec: pendingForNative?.hls.prerollCodec ?? "h264",
@@ -857,7 +948,6 @@ async function startNativeProxy(setup, numericStreamId, channelName, url, mpegTs
     // registration, so nulling the fields silences only sendPlaylistResponse's per-poll regeneration, not the one-shot overwrite the callback would still perform when
     // it fires. Disarming here completes the invalidation. One residual is inherent to preroll-for-hasAudio: if the native tune already exceeded PREROLL_DELAY_MS the
     // timer has already fired, so the nulled fields freeze the already-written preroll playlist until the proxy's first real content arrives - bounded, not a stall.
-    currentStream.captureSession = null;
     currentStream.hls.hasAudio = nativeResult.hasAudio;
     if (nativeResult.hasAudio) {
         cancelPrerollTimer(currentStream.hls);
@@ -865,14 +955,19 @@ async function startNativeProxy(setup, numericStreamId, channelName, url, mpegTs
         currentStream.hls.prerollCodec = null;
         currentStream.hls.prerollSegmentCount = 0;
     }
-    currentStream.captureCodec = nativeResult.codec;
-    currentStream.hardwareAccelerated = false;
-    currentStream.nativeBandwidth = nativeResult.bandwidth;
-    currentStream.nativeContainer = nativeResult.container;
-    currentStream.nativeProxy = nativeResult.proxy;
-    currentStream.nativeResolution = nativeResult.resolution;
-    currentStream.reestablishManifest = reestablishManifest;
-    currentStream.streamingMode = "native";
+    // The mode flip is one whole-identity replacement written as a pure literal, so the capture pipeline this stream no longer has cannot survive the transition.
+    currentStream.identity = {
+        captureCodec: nativeResult.codec,
+        mode: "native",
+        nativeBandwidth: nativeResult.bandwidth,
+        nativeContainer: nativeResult.container,
+        nativeProxy: nativeResult.proxy,
+        nativeResolution: nativeResult.resolution,
+        reestablishManifest
+    };
+    // The capture that was reading the compositor has ended, so this stream has no further claim on the window. Fire-and-forget: a native stream does not depend on
+    // the window at all, and the executor is serialized, so nothing here waits on a presentation change.
+    void syncWindowVisibility();
     // Start the native proxy. Init readiness is conditional on the container. An MPEG-TS source carries its own PAT/PMT codec configuration in every segment and
     // has no separate init to wait for, so readiness is signaled here and MPEG-TS clients are released immediately rather than blocking on waitForInitSegment()
     // until it times out. An fMP4 source does have an init, and the store signals readiness when the video track's first one lands - video because the consumer
@@ -888,6 +983,30 @@ async function startNativeProxy(setup, numericStreamId, channelName, url, mpegTs
     LOG.debug("native:coordinator", "Capture pipeline stopped for %s. Native proxy active.", channelName);
     return { codec: nativeResult.codec, quality: formatNativeQuality(nativeResult.bandwidth, nativeResult.codec, nativeResult.resolution) };
 }
+/**
+ * Derives what a segmenter continues from, which on a fresh stream is nothing at all. A resume carries the prior session's timestamps and init version, and its
+ * init segment only when no preroll window precedes it - the preroll init differs from the real one, so a byte match there would suppress a discontinuity the
+ * boundary genuinely needs. Session statistics are deliberately absent: a resume from disk has none, and inventing an empty set would tell the segmenter a live
+ * prior session is continuing and count a tab replacement that never happened. The starting index accounts for both the resume offset and the preroll segment
+ * range whenever either contributes one.
+ *
+ * Each member is present only when this resume genuinely carries it, because the segmenter reads presence rather than value: an absent member and a member set
+ * to an empty or zero stand-in mean different things to it.
+ *
+ * @param options - The resume record and the preroll accounting to derive from.
+ * @returns The continuity the segmenter is constructed with.
+ */
+export function buildResumeContinuity(options) {
+    const { baseSegmentIndex, prerollSegmentCount, resumeData } = options;
+    return {
+        ...(resumeData ? {
+            initialTrackTimestamps: resumeData.trackTimestamps,
+            ...((prerollSegmentCount === 0) ? { previousInitSegment: resumeData.initSegment } : {}),
+            startingInitVersion: resumeData.initVersion
+        } : {}),
+        ...((resumeData || (prerollSegmentCount > 0)) ? { startingSegmentIndex: baseSegmentIndex + prerollSegmentCount } : {})
+    };
+}
 /**
  * Creates the fMP4 segmenter for capture mode streams. Reads resume data, creates the segmenter with preroll and resume configuration, and attaches it to the
  * capture session (which pipes the session's capture output into it). Resume data is consumed only after the segmenter is successfully attached to a non-disposed
@@ -895,37 +1014,30 @@ async function startNativeProxy(setup, numericStreamId, channelName, url, mpegTs
  * @param setup - The stream setup result from setupStream().
  * @param numericStreamId - The stream's numeric ID.
  * @param channelName - The channel key for resume data and logging.
+ * @param now - The instant the resume data's TTL is measured against.
  * @returns True if the segmenter was attached, false if the stream was terminated during setup (the session was already disposed).
  */
-function createCaptureSegmenter(setup, numericStreamId, channelName) {
+function createCaptureSegmenter(setup, numericStreamId, channelName, now) {
     // Peek at resume data from a previous shutdown without consuming it. The data is consumed (deleted) only after the segmenter is successfully created and
     // stored in the registry. This ensures resume data survives if segmenter creation fails - the next stream start retries with the same resume state instead
     // of losing it and causing an HLS sequence reset.
-    const resumeData = peekResumeData(channelName);
+    const resumeData = peekResumeData(channelName, now);
     const currentStream = getStream(numericStreamId);
     const prerollSegmentCount = currentStream?.hls.prerollSegmentCount ?? 0;
     // When preroll is active, use the snapshotted resume index (stored on HLS state at registration) so the segmenter's starting index is guaranteed to match
     // the preroll playlist's MEDIA-SEQUENCE offset. When preroll is inactive, use the resume data directly - no preroll playlist to be consistent with.
     const baseSegmentIndex = (prerollSegmentCount > 0) ? (currentStream?.hls.resumeSegmentIndex ?? 0) : (resumeData?.segmentIndex ?? 0);
-    // Create the fMP4 segmenter. The starting segment index accounts for both the resume offset and the preroll segment range. When preroll is active, the
-    // segmenter includes preroll entries in its sliding window via the compositor. The pending discontinuity at the preroll-to-real boundary is always needed -
-    // previousInitSegment is only passed without preroll, because the preroll init segment differs from the real init and the discontinuity must not be
-    // suppressed by an init-match comparison against the prior session.
+    const continuity = buildResumeContinuity({ baseSegmentIndex, prerollSegmentCount, resumeData });
+    // Create the fMP4 segmenter. When preroll is active, it includes preroll entries in its sliding window via the compositor, and the pending discontinuity at the
+    // preroll-to-real boundary is always needed.
     const segmenter = createFMP4Segmenter({
-        ...(resumeData ? {
-            initialTrackTimestamps: resumeData.trackTimestamps,
-            ...((prerollSegmentCount === 0) ? { previousInitSegment: resumeData.initSegment } : {}),
-            startingInitVersion: resumeData.initVersion
-        } : {}),
+        continuity,
         ...((prerollSegmentCount > 0) ? {
             prerollBaseUrl: currentStream?.hls.prerollBaseUrl ?? null,
             prerollCodec: currentStream?.hls.prerollCodec ?? "h264",
             prerollSegmentCount
         } : {}),
-        ...((resumeData || (prerollSegmentCount > 0)) ? {
-            pendingDiscontinuity: true,
-            startingSegmentIndex: baseSegmentIndex + prerollSegmentCount
-        } : {}),
+        ...((resumeData || (prerollSegmentCount > 0)) ? { pendingDiscontinuity: true } : {}),
         ...buildSegmenterTerminationHandlers(numericStreamId, channelName),
         streamId: numericStreamId
     });
@@ -964,7 +1076,7 @@ async function completeStreamSetup(options) {
      * stamp assembled from a frame holding only part of the binding would silently describe a different stream than the one the tune reaches.
      *
      * The effective profile is the query override when one was supplied, otherwise the stored profile: an overridden tune reaches a different stream than the
-     * stored profile would, so the stamp honestly differs and an entry cached under the stored profile re-probes once under the override rather than answering
+     * stored profile would, so the stamp differs and an entry cached under the stored profile re-probes once under the override rather than answering
      * for a page it never described.
      */
     const probeIdentity = {
@@ -1010,6 +1122,8 @@ async function completeStreamSetup(options) {
         streamId: streamIdStr,
         url
     }, onCircuitBreak);
+    // The tune-complete instant, read once here so the resume data's TTL check and the tune-time line below measure against the same moment.
+    const now = systemClock.now();
     // Fill in the pending registry entry with the real browser state. The entry was registered in Phase 1 (registerPendingStream or initializeStream).
     const stream = getStream(numericStreamId);
     if (!stream) {
@@ -1019,7 +1133,9 @@ async function completeStreamSetup(options) {
         });
         return null;
     }
-    stream.captureSession = setup.captureSession;
+    // Setup produced the capture pipeline the entry was registered without. The identity is still the pending capture shape at this point - the native upgrade runs
+    // later in this same function - so the write installs the pipeline and leaves the encoder facts to the completion write further down.
+    stream.identity = { ...makePendingCaptureIdentity(), captureSession: setup.captureSession };
     stream.monitor = setup.monitor;
     stream.page = setup.page;
     stream.probeIdentity = setup.probeIdentity;
@@ -1045,7 +1161,7 @@ async function completeStreamSetup(options) {
         }
         // If native streaming was not viable or not attempted, create the fMP4 segmenter for capture mode.
         if (streamingMode === "capture") {
-            if (!createCaptureSegmenter(setup, numericStreamId, channelName)) {
+            if (!createCaptureSegmenter(setup, numericStreamId, channelName, now)) {
                 return null;
             }
         }
@@ -1057,7 +1173,7 @@ async function completeStreamSetup(options) {
         const captureMode = (streamingMode === "native") ? ("native HLS" + nativeQuality) :
             (CONFIG.streaming.captureMode === "ffmpeg" ? "FFmpeg [" + ffmpegCodec + "]" : "Native fMP4");
         const displayName = channel?.name ?? url;
-        const tuneTime = ((Date.now() - setup.startTime.getTime()) / 1000).toFixed(1);
+        const tuneTime = ((now - setup.startTime) / 1000).toFixed(1);
         LOG.info("Streaming %s: %s, %s, %s. Tuned in %ss%s.", displayName, setup.serviceName, setup.profileName, captureMode, tuneTime, setup.directTune ? " (direct)" : "");
         // Mark channel health as successful. Only for predefined channels (channel is defined). Ad-hoc URL streams have no persistent channel identity. Domain
         // auth is conditionally skipped when the provider module defines validateTune and the tuned channel does not prove paid access (e.g., Sling Freestream).
@@ -1069,14 +1185,14 @@ async function completeStreamSetup(options) {
             const markAuth = !provider?.validateTune || provider.validateTune(channel.channelSelector ?? channelName);
             markChannelSuccess(channelName, successAuthDomain, markAuth);
         }
-        // Update the registry entry with codec and hardware acceleration state, then emit the stream added event for the dashboard. Native streams set their codec
-        // and quality fields earlier (when the native proxy is created), so only capture mode needs updating here.
+        // Record the codec and hardware acceleration this stream settled on, then emit the stream added event for the dashboard. The registry write is capture-only:
+        // a native upgrade already wrote its manifest-derived codec into the native identity, and hardware acceleration is a capture fact the status projection
+        // answers false for on a native stream. The two DTO values below are computed for both modes because the wire shape stays flat.
         const streamCodec = (streamingMode === "native") ? nativeCodec : effectiveCodec.toUpperCase();
         const hwAccelerated = (streamingMode !== "native") && captureHwAccel;
         const currentEntry = getStream(numericStreamId);
-        if (currentEntry) {
-            currentEntry.captureCodec = streamCodec;
-            currentEntry.hardwareAccelerated = hwAccelerated;
+        if (currentEntry && isCaptureIdentity(currentEntry)) {
+            currentEntry.identity = { ...currentEntry.identity, captureCodec: streamCodec, hardwareAccelerated: hwAccelerated };
         }
         emitStreamAdded(createInitialStreamStatus({
             captureCodec: streamCodec,
@@ -1114,16 +1230,11 @@ async function startHLSStream(channelName, url, req, res, channel) {
         return await initializeStream({ channel, channelName, clientAddress, profileOverride, url });
     }
     catch (error) {
-        if (error instanceof StreamSetupError) {
-            if (error.statusCode === 503) {
-                res.setHeader("Retry-After", "10");
-                res.setHeader("X-HDHomeRun-Error", "All Tuners In Use");
-            }
-            res.status(error.statusCode).send(error.userMessage);
-            return null;
+        // A StreamSetupError is an expected refusal whose message is already meant for the client, so only an unexpected failure earns an error log here.
+        if (!(error instanceof StreamSetupError)) {
+            LOG.error("Unexpected error during HLS stream setup: %s.", formatError(error));
         }
-        LOG.error("Unexpected error during HLS stream setup: %s.", formatError(error));
-        res.status(500).send("Internal server error.");
+        sendSetupFailure(describeSetupFailure(error), res);
         return null;
     }
 }
@@ -1132,10 +1243,10 @@ async function startHLSStream(channelName, url, req, res, channel) {
  * Returns all streams that have exceeded the idle timeout and have no active MPEG-TS clients. Pretuned streams are excluded - they have no clients by design and
  * the pretune module manages their lifecycle via a safety timeout. The result is sorted by last access time (oldest first) so callers can efficiently pick the
  * longest-idle stream for reclamation.
+ * @param now - The instant each stream's idle window is measured against.
  * @returns Idle streams sorted by last access time ascending (oldest first).
  */
-function getIdleStreams() {
-    const now = Date.now();
+function getIdleStreams(now) {
     return getAllStreams()
         .filter((stream) => !stream.preTuned && (stream.mpegTsClientCount === 0) && ((now - stream.info.lastPlaylistRequest) >= CONFIG.hls.idleTimeout))
         .sort((a, b) => a.info.lastPlaylistRequest - b.info.lastPlaylistRequest);
@@ -1144,7 +1255,7 @@ function getIdleStreams() {
  * Checks for idle streams and terminates them. Called periodically by the idle detection interval.
  */
 export function cleanupIdleStreams() {
-    const idle = getIdleStreams();
+    const idle = getIdleStreams(systemClock.now());
     for (const stream of idle) {
         terminateStream(stream.id, stream.info.storeKey, "no active clients");
     }
@@ -1159,7 +1270,7 @@ export function cleanupIdleStreams() {
  * @returns True if a stream was reclaimed, false if no idle streams exist.
  */
 function reclaimIdleStream() {
-    const idle = getIdleStreams();
+    const idle = getIdleStreams(systemClock.now());
     if (idle.length === 0) {
         return false;
     }