prismcast 1.13.0 → 1.14.0

package/dist/app.js

@@ -2,14 +2,14 @@
  *
  * app.ts: Express application builder for PrismCast.
  */
-import { CONFIG, displayConfiguration, initializeConfiguration, persistCoercedConfig, validateConfiguration } from "./config/index.js";
-import { LOG, boundedWait, claim, createMorganStream, formatError, formatTimestamp, getCurrentPattern, getPackageVersion, isDebugLogging, release, resolveFFmpegPath, setConsoleLogging, startUpdateChecking, stopUpdateChecking } from "./utils/index.js";
-import { closeBrowser, ensureDataDirectory, getCurrentBrowser, killStaleChrome, prepareExtension, setGracefulShutdown, setLoginModeEndObserver, startBrowserRestartChecking, startStalePageCleanup, stopBrowserRestartChecking, stopStalePageCleanup, syncWindowVisibility } from "./browser/index.js";
+import { CONFIG, displayConfiguration, initializeConfiguration, validateConfiguration } from "./config/index.js";
+import { LOG, assertNever, boundedWait, claim, createMorganStream, formatError, formatTimestamp, getCurrentPattern, getPackageVersion, handleRequestError, isDebugLogging, release, resolveFFmpegPath, setConsoleLogging, startUpdateChecking, stopUpdateChecking } from "./utils/index.js";
+import { closeBrowser, ensureDataDirectory, getCurrentBrowser, isGracefulShutdown, killStaleChrome, setGracefulShutdown, setLoginModeEndObserver, startBrowserRestartChecking, startStalePageCleanup, stopBrowserRestartChecking, stopStalePageCleanup, syncWindowVisibility } from "./browser/index.js";
 import { ensureAllMigrated, snapshotAllForRelease } from "./config/persistence.js";
 import { flushHealthStateNow, loadHealthState } from "./config/health.js";
 import { getAllStreams, isCaptureIdentity } from "./streaming/registry.js";
 import { getDebugEnv, getLogFilePath, getServerPidFilePath } from "./config/paths.js";
-import { initializeFileLogger, shutdownFileLogger } from "./utils/fileLogger.js";
+import { initializeFileLogger, setMaxLogSize, shutdownFileLogger } from "./utils/fileLogger.js";
 import { loadResumeState, saveResumeState } from "./streaming/hlsResume.js";
 import { revalidateDomainAuth, stopPrecaching } from "./browser/precaching.js";
 import { startHdhrServer, stopHdhrServer } from "./hdhr/index.js";
@@ -25,6 +25,7 @@ import { initializeUserProfiles } from "./config/userProfiles.js";
 import { installHealthBridge } from "./routes/config/channels/healthBridge.js";
 import { loadProviderLineups } from "./config/providerLineups.js";
 import morgan from "morgan";
+import { registerConfigChangeHandler } from "./config/reactivity.js";
 import { runConsistencyProbeAtStartup } from "./config/consistencyProbe.js";
 import { setupRoutes } from "./routes/index.js";
 import { systemClock } from "homebridge-plugin-utils";
@@ -43,8 +44,8 @@ let server = null;
 // shutdown, exactly as the file logger's drain bound does for a wedged filesystem operation.
 const SERVER_CLOSE_BOUND_MS = 5000;
 /* The background-service teardown stack. Each long-lived background service (stale-page sweep, browser-restart watchdog, idle cleanup, show-info/pretune polling,
- * update check) registers its stop here at the moment it starts in startServer(); graceful shutdown disposes the stack wholesale, so a future service cannot be
- * started without also being torn down. An AsyncDisposableStack is used (rather than the synchronous DisposableStack) so the teardown awaits each registered stop -
+ * update check) registers its stop here at the moment it starts in startBackgroundServices(); graceful shutdown disposes the stack wholesale, so a future service cannot
+ * be started without also being torn down. An AsyncDisposableStack is used (rather than the synchronous DisposableStack) so the teardown awaits each registered stop -
  * today's registered stops are all synchronous, but a future service whose stop must complete (e.g. flushing to disk) would be silently fire-and-forgotten by a
  * sync stack.
  */
@@ -72,10 +73,45 @@ function stopIdleCleanup() {
         idleCleanupInterval = null;
     }
 }
-/* When the process receives a termination signal, we close all active streams and the browser before exiting. This ensures resources are released cleanly.
+/**
+ * Closes the main HTTP server, graceful shutdown's step for the listener the boot's tail bound. Connections are destroyed first because the status and log SSE
+ * streams (routes/streams.ts and routes/logs.ts) hold their sockets open with a heartbeat, and the close waits on every one of them; the CDP proxy's WebSocket
+ * clients have already closed themselves with 1001 in response to the browser disconnect shutdown awaits before this step. An in-flight request ends with the
+ * process, because the exit follows immediately. The server reference is taken and cleared before the close, so a close that runs again finds no server.
+ * @param clock - The clock the close bound runs on, the system clock in production and a test clock in a row that crosses the bound.
+ * @returns A promise that resolves once the server closes or its bound lapses, and at once when no server is bound.
  */
+export async function closeMainServer(clock = systemClock) {
+    const current = server;
+    server = null;
+    if (!current) {
+        return;
+    }
+    // The outer catch keeps a close that throws from rejecting, because shutdown runs unawaited from its signal handler and a rejection here would skip the exit
+    // the shutdown ends with.
+    try {
+        const { promise: closed, resolve } = Promise.withResolvers();
+        current.close((error) => {
+            if (error) {
+                LOG.error("The HTTP server reported an error while closing during shutdown.", { error: formatError(error) });
+            }
+            else {
+                LOG.info("HTTP server closed successfully.");
+            }
+            resolve(true);
+        });
+        current.closeAllConnections();
+        if ((await boundedWait(closed, SERVER_CLOSE_BOUND_MS, { clock })) === null) {
+            LOG.warn("The HTTP server did not close within its bound, so the shutdown continues.", { boundMs: SERVER_CLOSE_BOUND_MS });
+        }
+    }
+    catch (error) {
+        LOG.error("The HTTP server could not be closed during shutdown.", { error: formatError(error) });
+    }
+}
 /**
- * Sets up signal handlers for graceful shutdown. When SIGINT or SIGTERM is received, we close all streams, the browser, and the HTTP server before exiting.
+ * Sets up signal handlers for graceful shutdown. When SIGHUP, SIGINT or SIGTERM is received, we close all active streams, the browser and the HTTP server before
+ * exiting, so every resource is released cleanly.
  */
 function setupGracefulShutdown() {
     let shutdownInProgress = false;
@@ -89,12 +125,14 @@ function setupGracefulShutdown() {
         // Set the graceful shutdown flag early so that page close errors are suppressed during stream termination.
         setGracefulShutdown(true);
         // Tear down the background services. HDHR is torn down first and awaited so its HTTP and UDP sockets fully release before the rest of shutdown proceeds. The
-        // long-lived pollers are disposed wholesale via the AsyncDisposableStack they registered on at startup. The browser-launch-scoped precache cycle is cancelled
-        // separately - its graceful-shutdown guard has already neutralized it via setGracefulShutdown above, and this clears the pending timer.
+        // long-lived pollers are disposed wholesale via the AsyncDisposableStack they registered on at startup. The precache scheduler, whose cycles browser launches
+        // and saves request rather than the boot starting them, is cancelled separately - its graceful-shutdown guard has already neutralized it via
+        // setGracefulShutdown above, and this clears its pending timers.
         await stopHdhrServer();
         await backgroundServices?.disposeAsync();
         stopPrecaching();
-        // Terminate all streams. terminateStream() handles all cleanup including page closure and registry removal.
+        // Terminate all streams. terminateStream() runs every per-stream cleanup except the page close, which it skips during graceful shutdown because
+        // closeBrowser() below closes every page.
         const streams = getAllStreams();
         // Collect resume state from active streams before termination destroys the segmenters. Each entry captures sequence numbers and timestamps so the next startup
         // can seed from them, preventing HLS sequence resets that confuse Channels DVR. The segment index is decremented by one so the resumed playlist still includes
@@ -106,6 +144,7 @@ function setupGracefulShutdown() {
             if (stream.info.storeKey && segmenter) {
                 resumeEntries.push({
                     channelName: stream.info.storeKey,
+                    discontinuityCount: segmenter.getDiscontinuityCount(),
                     initSegment: segmenter.getInitSegment(),
                     initVersion: segmenter.getInitVersion(),
                     segmentIndex: Math.max(0, segmenter.getSegmentIndex() - 1),
@@ -123,32 +162,8 @@ function setupGracefulShutdown() {
         await closeBrowser();
         // Release the server instance slot so the next startup does not see a stale identity file.
         releaseInstanceSlot();
-        /* Close the HTTP server. The close is awaited so its own line lands while the file logger is still open, which the shutdown below ends. Connections are
-         * destroyed first because the status and log SSE streams (routes/streams.ts and routes/logs.ts) hold their sockets open with a heartbeat, and the close
-         * waits on every one of them; the CDP proxy's WebSocket clients have already closed themselves with 1001 in response to the browser disconnect above. An
-         * in-flight request ends with the process either way, because the exit follows immediately.
-         */
-        try {
-            if (server) {
-                const { promise: closed, resolve } = Promise.withResolvers();
-                server.close((error) => {
-                    if (error) {
-                        LOG.error("Error closing server during shutdown: %s.", formatError(error));
-                    }
-                    else {
-                        LOG.info("HTTP server closed successfully.");
-                    }
-                    resolve(true);
-                });
-                server.closeAllConnections();
-                if ((await boundedWait(closed, SERVER_CLOSE_BOUND_MS)) === null) {
-                    LOG.warn("The HTTP server did not close within %sms. Continuing the shutdown.", SERVER_CLOSE_BOUND_MS);
-                }
-            }
-        }
-        catch (error) {
-            LOG.error("Error closing server during shutdown: %s.", formatError(error));
-        }
+        // Close the HTTP server, awaited so its own line lands while the file logger is still open, which the step after it ends.
+        await closeMainServer();
         // Shut down file logger if in use. Awaited because shutdown drains the outstanding write chain before its final synchronous flush, and the process exit below
         // would otherwise cut that drain short.
         if (!usingConsoleLogging) {
@@ -156,6 +171,11 @@ function setupGracefulShutdown() {
         }
         process.exit(0);
     }
+    // A hangup asks the process to end as surely as an interrupt or a termination does, when the terminal or the session that started PrismCast goes away, and its
+    // default action would end the process without this teardown or the exit handler, so it runs the same shutdown.
+    process.on("SIGHUP", () => {
+        void shutdown();
+    });
     process.on("SIGINT", () => {
         void shutdown();
     });
@@ -183,8 +203,8 @@ const FILTERED_SKIP_PATTERNS = ["/logs", "/health", "/favicon", "/logo.png", "/l
 // Streaming and management endpoints, always logged in filtered mode because they mark what the server is actually doing.
 const FILTERED_IMPORTANT_PATTERNS = ["/stream", "/streams", "/config", "/playlist", "/debug"];
 /**
- * Records a request's arrival time. Registered ahead of the logger so both readers of the elapsed time measure from the moment the request reached the app rather
- * than from whenever the logger happened to see it.
+ * Records a request's arrival time. The request logger's middleware calls it as a request arrives, before handing the request to morgan, so every reader of the
+ * elapsed time measures from the request's arrival rather than from whenever morgan happened to see it.
  * @param req - The incoming request.
  * @param _res - The response, unused.
  * @param next - The next middleware in the chain.
@@ -261,26 +281,74 @@ export function skipInFilteredMode(request) {
     // Skip successful requests to the root landing page, and log everything else.
     return request.url === "/";
 }
+/**
+ * Decides whether the request log skips a request at the given level: "none" skips every request, "all" logs every one, and "errors" and "filtered" apply their
+ * own rules. The switch is exhaustive, and no running level reaches its default arm, because every configuration the server builds corrects a level it does not
+ * recognize.
+ * @param options - The level in force, the elapsed milliseconds (null when unstamped), whether a Retry-After header is present, the response status, and the
+ *   request URL.
+ * @returns True when the request should not be logged.
+ */
+export function skipRequestLog(options) {
+    switch (options.level) {
+        case "all": {
+            return false;
+        }
+        case "errors": {
+            return skipInErrorsMode(options);
+        }
+        case "filtered": {
+            return skipInFilteredMode(options);
+        }
+        case "none": {
+            return true;
+        }
+        default: {
+            assertNever(options.level);
+        }
+    }
+}
 /* The token is defined once for the process, at module load. morgan's token registry is global to the module, so registering inside the app builder would re-register
  * on every build - harmless today because the definition is constant, but a registration whose count tracks how often the app is assembled is the kind of coupling
  * that only shows up once a second build carries different state.
  */
 morgan.token("elapsed", elapsedMillis);
-/* The buildApp function creates and configures the Express application with all middleware and routes. This is separated from the server startup to allow for
- * testing and flexibility in deployment.
+// The request log line. Its elapsed token reads the arrival stamp stampRequestStart records.
+const REQUEST_LOG_FORMAT = ":method :url from :remote-addr responded :status in :elapsed ms.";
+/**
+ * Builds the request logger: one morgan logger behind one middleware, each reading the configured HTTP log level per request, so a saved level applies from the
+ * next request. Whether a request is observed is decided when it arrives: under "none" the middleware hands it on at once, at the cost of one property read, and
+ * the request is never stamped or seen by morgan. Whether an observed request is logged is decided by the level in force when it finishes, because morgan makes
+ * its skip decision as the response completes. So a long-lived stream that arrived under "none" is never logged, and one that arrived under another level is
+ * judged by the level in force at its close.
+ * @param stream - The stream morgan writes each line to.
+ * @returns The request-logging middleware.
  */
+export function createRequestLogger(stream) {
+    const logger = morgan(REQUEST_LOG_FORMAT, {
+        skip: (req, res) => skipRequestLog({
+            elapsedMs: elapsedMillisValue(req),
+            hasRetryAfter: res.getHeader("Retry-After") !== undefined,
+            level: CONFIG.logging.httpLogLevel,
+            statusCode: res.statusCode,
+            url: req.originalUrl || req.url
+        }),
+        stream
+    });
+    return (req, res, next) => {
+        if (CONFIG.logging.httpLogLevel === "none") {
+            next();
+            return;
+        }
+        stampRequestStart(req, res, () => { logger(req, res, next); });
+    };
+}
 /**
- * Creates and configures the Express application with all middleware and routes.
+ * Creates and configures the Express application with all middleware and routes. It is a step of its own, so the boot's tail takes it as an injected step and a
+ * test substitutes a stub for it.
  * @returns The configured Express application.
  */
-async function buildApp() {
-    try {
-        await prepareExtension();
-    }
-    catch (error) {
-        LOG.error("Cannot build app without extension: %s.", formatError(error));
-        throw error;
-    }
+function buildApp() {
     const app = express();
     // Trust proxy headers (X-Forwarded-Proto, X-Forwarded-Host) so that req.protocol and req.hostname reflect what the client actually used when accessing through
     // a reverse proxy. This ensures playlist URLs match the client's connection.
@@ -298,55 +366,20 @@ async function buildApp() {
     // Add body parsing middleware for form submissions (configuration page).
     app.use(express.urlencoded({ extended: true }));
     app.use(express.json());
-    // Configure Morgan for HTTP request logging based on httpLogLevel configuration. Morgan output goes through morganStream which handles timestamp formatting
-    // consistently for both console and file logging modes.
-    if (CONFIG.logging.httpLogLevel !== "none") {
-        const morganFormat = ":method :url from :remote-addr responded :status in :elapsed ms.";
-        const morganStream = createMorganStream();
-        // Stamp each request's arrival before morgan sees it, so the elapsed token and the filtered mode's slow-request rule read the same start time.
-        app.use(stampRequestStart);
-        if (CONFIG.logging.httpLogLevel === "errors") {
-            // Log requests with 4xx or 5xx status codes, but skip 404s for common browser asset requests.
-            app.use(morgan(morganFormat, {
-                skip: (req, res) => skipInErrorsMode({
-                    hasRetryAfter: res.getHeader("Retry-After") !== undefined,
-                    statusCode: res.statusCode,
-                    url: req.originalUrl || req.url
-                }),
-                stream: morganStream
-            }));
-        }
-        else if (CONFIG.logging.httpLogLevel === "filtered") {
-            // Log important requests while skipping high-frequency polling endpoints. We always log errors, slow requests, and critical endpoints.
-            app.use(morgan(morganFormat, {
-                skip: (req, res) => skipInFilteredMode({
-                    elapsedMs: elapsedMillisValue(req),
-                    statusCode: res.statusCode,
-                    url: req.originalUrl || req.url
-                }),
-                stream: morganStream
-            }));
-        }
-        else {
-            // Log all requests.
-            app.use(morgan(morganFormat, { stream: morganStream }));
-        }
-    }
+    // Log HTTP requests at the configured level, which the logger reads per request. Its output goes through the morgan stream adapter, which formats timestamps
+    // the same way in console and file logging modes.
+    app.use(createRequestLogger(createMorganStream()));
     // Set up all HTTP endpoints.
     setupRoutes(app);
-    // Global error handler. Express error handlers require 4 parameters even if unused.
-    app.use((err, _req, res, _next) => {
-        LOG.error("Unhandled error in request: %s.", formatError(err));
-        if (!res.headersSent) {
-            res.status(500).send("Internal server error");
-        }
-    });
+    // The request error handler goes last, so it receives what every route above raises.
+    app.use(handleRequestError);
     return app;
 }
 /* PrismCast instance guard. Only one server instance should run at a time - a second instance would launch a competing Chrome process, bind to the same port,
- * and corrupt shared state. The guard delegates to the runtime-identity primitive in utils/runtimeIdentity.ts, which composes PID liveness with the current
- * boot session ID to classify the on-disk identity file. Stale records from reboots, container restarts, crashes, and ungraceful shutdowns are recovered
- * transparently: the next claim() overwrites them. A held-live record (same boot, alive PID) is the only state that rejects a startup.
+ * and corrupt shared state. The guard delegates to the runtime-identity primitive in utils/runtimeIdentity.ts, which composes PID liveness, the current boot
+ * session ID and the writer's command-line fingerprint to classify the on-disk identity file. Stale records from reboots, container restarts, crashes, and
+ * ungraceful shutdowns are recovered transparently: the next claim() overwrites them. A held-live record (same boot, alive PID, and that PID not proven by its
+ * command-line fingerprint to be another program) is the only state that rejects a startup.
  *
  * Ownership is verified structurally inside release(): the function reads the on-disk record and only removes the file when its PID matches this process's
  * PID. The file content is itself the source of truth, so a rejected duplicate startup's exit handler cannot accidentally delete the legitimate holder's file.
@@ -417,12 +450,123 @@ async function listenMainServer(app) {
     });
     return promise;
 }
-/* The startServer function initializes and starts the HTTP server. It validates configuration, cleans up stale processes, warms up the browser, and starts the
- * Express application.
+/**
+ * Applies a saved log size limit to the open log file. The composition root owns the handler because it wires the file logger, and the file logger, a utility
+ * the configuration layer builds on, cannot import that layer back. The limit comes from the candidate, because the reconcile commits CONFIG only after its
+ * handlers run. The size check is started rather than awaited: the save needs only the limit, which the setter assigns before its first await, so a save never
+ * waits on log-file I/O.
+ * @param _changes - The change to the log size limit; the candidate carries the limit, so the handler reads that instead.
+ * @param next - The candidate running configuration.
+ * @returns No rejections.
  */
+export async function applyLogSizeChanges(_changes, next) {
+    void setMaxLogSize(next.logging.maxSize);
+    return [];
+}
+// Module-load side effect: register the handler once per process, as every config-change handler registers, so it is in place before the first save can reach
+// the reconcile.
+registerConfigChangeHandler("logging.maxSize", applyLogSizeChanges);
+// The boot's tail.
 /**
- * Initializes and starts the HTTP server. Before accepting connections, we validate configuration, clean up stale Chrome processes, and warm up the browser
- * instance.
+ * Starts the background services, each on the teardown stack graceful shutdown disposes. The boot's tail calls it through its injected steps, so a test records
+ * its place in the boot's order without starting a real service.
+ */
+function startBackgroundServices() {
+    // Start the background services and register each one's stop on an AsyncDisposableStack the moment it starts, so graceful shutdown can dispose them all wholesale
+    // and a future service cannot be started without also being torn down. These are order-independent background loops/timers, so LIFO disposal order is immaterial.
+    // HDHR is intentionally not a member (it is torn down first in shutdown so its sockets release before the rest), and the precache scheduler stays off the stack
+    // as well: browser launches and saves request its cycles, and shutdown stops it separately.
+    backgroundServices = new AsyncDisposableStack();
+    startStalePageCleanup();
+    backgroundServices.defer(stopStalePageCleanup);
+    startBrowserRestartChecking();
+    backgroundServices.defer(stopBrowserRestartChecking);
+    startIdleCleanup();
+    backgroundServices.defer(stopIdleCleanup);
+    startShowInfoPolling();
+    backgroundServices.defer(stopShowInfoPolling);
+    startPretunePolling();
+    backgroundServices.defer(stopPretunePolling);
+    startUpdateChecking(getPackageVersion());
+    backgroundServices.defer(stopUpdateChecking);
+}
+export const defaultBootServicesDeps = {
+    attachCdpUpgradeHandler,
+    buildApp,
+    isGracefulShutdown,
+    listenMainServer,
+    startBackgroundServices,
+    startHdhrServer
+};
+/**
+ * Reports whether shutdown has begun, logging the skip line when it has. It reads the graceful-shutdown state the browser module holds, which the signal handler
+ * sets before its first await and nothing in production clears, and keeps no flag of its own. Each caller returns when it answers true, so the line logs at most
+ * once per boot.
+ *
+ * Shutdown never waits on the boot, so the boot reaches a check only while shutdown is still awaiting its own steps, and where the signal lands decides what the boot has
+ * armed. A signal before setupGracefulShutdown(), the data directory creation included, meets no handler of ours, and the platform's default
+ * action ends the process with nothing armed. A signal during the release boot coordinator, the configuration load, the logger, the FFmpeg check,
+ * the stores or the consistency probe runs shutdown while the stack and the listener are absent, so its disposal and its close have nothing to
+ * act on, and with no browser to wait for, its exit ends the boot before the first check. A signal during the browser warm-up makes shutdown's
+ * closeBrowser() supersede the launch in flight: the launch rejects when it settles, the warm-up rethrows, and the entry's catch, finding shutdown begun, leaves the exit
+ * to shutdown, whose own exit usually comes first because the launch has seconds of work left, so the boot reaches no check whichever exit lands first. A signal during
+ * the preroll or the window sync finds a ready browser, so shutdown waits for Chrome's exit, within the browser module's BROWSER_TEARDOWN_DRAIN_BOUND_MS; the window sync
+ * returns at once when shutdown has begun, so a boot whose preroll finishes inside that wait reaches the first check, which stops it before the stack is armed, and a
+ * boot whose preroll outlasts the wait is ended by the exit. The build is synchronous and a bind on an address crosses no event-loop turn, so between arming the stack
+ * and starting HDHomeRun the one await a signal can land in is a hostname host's lookup during the bind: shutdown reads the listener only after its own awaits, so the
+ * bind completes and shutdown closes the listener, and the check after the bind stops the boot before HDHomeRun starts. A signal during the HDHomeRun start lets
+ * shutdown's stop run before the start finishes binding, and the sockets it binds last until the exit. A signal after the boot finished meets no check and shutdown
+ * tears everything down; a repeated signal is absorbed by the handler's own guard; and a process restart discards the state, so the next boot starts with it unset.
+ * @param deps - The boot's steps, whose shutdown reader the check calls.
+ * @returns True when shutdown has begun, so the caller arms nothing further.
+ */
+function shutdownBegan(deps) {
+    if (!deps.isGracefulShutdown()) {
+        return false;
+    }
+    LOG.info("Shutdown began during startup, so the remaining startup steps are skipped.");
+    return true;
+}
+/**
+ * Arms what the server runs for the life of the process, in order: the background services, the Express application and its listener, the CDP upgrade handler,
+ * and HDHomeRun emulation. The signal handlers are installed well before the boot reaches this point, so a signal can run shutdown against a background stack, a
+ * listener and an HDHomeRun surface that do not exist yet, and a boot that armed them afterwards would leave them running in a process that is shutting down. The
+ * boot therefore reads the shutdown state before it arms the stack, and again after the bind, the await a later arming step follows, and arms nothing once
+ * shutdown has begun. The check after the bind decides only where that await yields to the event loop - a hostname host's lookup - and elsewhere the first check
+ * decides. The limit is an await already in flight when the signal lands: it completes, and the process exit at the end of shutdown ends whatever it started.
+ * @param deps - The boot's steps: the real ones in production, and recording stubs in a test.
+ * @returns A promise that resolves once the boot's tail completes or stops for a shutdown, and rejects when the build or the bind fails.
+ */
+export async function startBootServices(deps = defaultBootServicesDeps) {
+    if (shutdownBegan(deps)) {
+        return;
+    }
+    deps.startBackgroundServices();
+    // Build and start Express application.
+    try {
+        const app = deps.buildApp();
+        // Bind the main HTTP server, detecting bind success or failure through explicit events rather than the unreliable listen callback. A bind failure throws out
+        // of here so the catch below surfaces it and the process exits cleanly rather than lingering with no HTTP surface.
+        server = await deps.listenMainServer(app);
+        // Attach the CDP proxy upgrade handler once the underlying http.Server exists. The handler is gated on the `cdp` debug category at request time, so it sits
+        // dormant until the user enables CDP via /debug. We attach unconditionally so the toggle takes effect without requiring a restart.
+        deps.attachCdpUpgradeHandler(server);
+    }
+    catch (error) {
+        // Covers both a buildApp failure and a listenMainServer bind failure; the latter already logged the precise, operator-actionable line before rejecting.
+        LOG.error("Failed to build or start the HTTP server: %s.", formatError(error));
+        throw error;
+    }
+    if (shutdownBegan(deps)) {
+        return;
+    }
+    // Start HDHomeRun emulation server if enabled. This runs independently of the main server and handles EADDRINUSE gracefully without affecting PrismCast's
+    // primary functionality.
+    await deps.startHdhrServer();
+}
+/**
+ * Initializes the server and starts it: we validate configuration, clean up stale Chrome processes and warm up the browser instance, then hand the rest of the
+ * boot to startBootServices, which arms the background services, builds the Express application and binds its listener, and starts HDHomeRun emulation.
  * @param parsedArgs - Parsed command-line arguments containing flags and override values.
  */
 export async function startServer(parsedArgs) {
@@ -456,6 +600,18 @@ export async function startServer(parsedArgs) {
             cliOverrides[configPath] = parsedArgs[argKey];
         }
     }
+    /* Claim the server instance slot before the boot touches anything a running instance owns: the stores the release coordinator snapshots and migrates, the
+     * configuration file the configuration load corrects, the Chrome profile and the port. Without the claim first, a second start against a data directory a live
+     * instance holds writes those stores before its claim refuses it, and a newer release started beside an older one migrates the older one's files out from
+     * under it. The claim depends on nothing the configuration produces, since the data directory's path is fixed before the server starts, so it can stand this
+     * early. The directory is created first because the identity file lives there, and creating it also removes the artifacts retired releases left behind,
+     * which no release since their retirement writes. The signal handlers follow the claim directly, so the boot never holds the slot without the shutdown that
+     * releases it on a signal; shutdown skips each surface the boot has not built yet. A failure later in the boot, the coordinator's or the configuration's
+     * included, exits through the exit handler, whose releaseInstanceSlot() removes the identity file only when this process wrote it.
+     */
+    await ensureDataDirectory();
+    claimInstanceSlot();
+    setupGracefulShutdown();
     // Release boot coordinator: snapshot every persistence-managed file before any reads or migrations run, then apply any pending schema migrations across all
     // stores. Both operations are safe to run more than once within a release (snapshots skip when the labeled copy already exists; ensureMigrated skips when the
     // file is at the current schema version). Running them up front guarantees a restore point exists for every file at the start of every release boot, even if a
@@ -473,10 +629,6 @@ export async function startServer(parsedArgs) {
     try {
         await initializeConfiguration(cliOverrides);
         validateConfiguration();
-        // Write any startup capture coercion back to disk so the on-disk state matches the coerced live CONFIG. This keeps a config file that holds an unsupported
-        // capture value (native mode) from staying divergent forever, which would otherwise make the reload-validation path reject every later save on the phantom
-        // capture diff. A no-op unless validateConfiguration actually coerced something.
-        await persistCoercedConfig();
         await initializeUserProfiles();
         validateProfiles();
     }
@@ -484,13 +636,6 @@ export async function startServer(parsedArgs) {
         LOG.error(formatError(error));
         process.exit(1);
     }
-    setupGracefulShutdown();
-    // Ensure the data directory exists before any operations that depend on it.
-    await ensureDataDirectory();
-    // Claim the server instance slot before launching Chrome or binding the port. This must come after ensureDataDirectory() since the identity file lives there.
-    // claimInstanceSlot() exits with a precise diagnostic when a live holder is detected; on success the identity file holds our PID and boot session ID. If
-    // startup subsequently fails, the exit handler calls releaseInstanceSlot() to remove the stale file.
-    claimInstanceSlot();
     // Initialize file logger if not using console logging. Initialization follows configuration loading, which resolves the log file path and the size cap, and
     // ensureDataDirectory(), which creates the parent directory. Every line logged before this point is held by the logger and written by its first flush, so
     // the startup messages above are under no ordering constraint.
@@ -512,16 +657,15 @@ export async function startServer(parsedArgs) {
             LOG.info("Debug logging enabled for all categories.");
         }
     }
-    // Check FFmpeg availability if using FFmpeg capture mode. This must be after file logger initialization so the log message is captured.
-    if (CONFIG.streaming.captureMode === "ffmpeg") {
-        const ffmpegPath = await resolveFFmpegPath();
-        if (!ffmpegPath) {
-            LOG.error("FFmpeg is not available. FFmpeg capture mode requires FFmpeg to be installed and in the system PATH.");
-            LOG.error("Either install FFmpeg or change the capture mode to 'native' in the configuration.");
-            process.exit(1);
-        }
-        LOG.info("Using FFmpeg at: %s.", ffmpegPath);
+    // Check FFmpeg availability on every boot, because FFmpeg capture is always in effect: the configuration corrects any other capture mode as it is built. This
+    // must be after file logger initialization so the log message is captured.
+    const ffmpegPath = await resolveFFmpegPath();
+    if (!ffmpegPath) {
+        LOG.error("FFmpeg is not available. FFmpeg capture mode requires FFmpeg to be installed and in the system PATH.");
+        LOG.error("Install FFmpeg and start PrismCast again.");
+        process.exit(1);
     }
+    LOG.info("Using FFmpeg at: %s.", ffmpegPath);
     // Load user channels from channels.json in the data directory if it exists.
     await initializeUserChannels();
     // Load persisted health state (channel health + domain auth) from health.json.
@@ -536,8 +680,8 @@ export async function startServer(parsedArgs) {
     // can clear the flag without waiting for the next precache cycle. Composition-root wiring - login.ts stays free of discovery knowledge, and revalidateDomainAuth
     // never rejects, so voiding the promise is safe.
     setLoginModeEndObserver((url) => void revalidateDomainAuth(url));
-    // Run the cross-store consistency probe now that every store is loaded. Validates foreign-key-style rules spanning multiple stores (service selections, variant
-    // canonicalKey targets, domain profile mappings, service tag filter) and auto-fixes warnings where safe. Errors do not block startup.
+    // Run the cross-store consistency probe now that every store is loaded. It logs each foreign-key-style inconsistency spanning multiple stores that an operator
+    // must act on, such as a variant whose canonical is missing, and changes nothing. Errors do not block startup.
     await runConsistencyProbeAtStartup();
     // Load HLS resume state from the previous shutdown. This seeds sequence numbers so streams resume forward instead of resetting to 0.
     loadResumeState(systemClock.now());
@@ -560,40 +704,29 @@ export async function startServer(parsedArgs) {
     // GPU probe wants an environment representative of the one capture runs in and the capture probe acquires a real capture, both of which want the window as the
     // launch left it.
     await syncWindowVisibility();
-    // Start the background services and register each one's stop on an AsyncDisposableStack the moment it starts, so graceful shutdown can dispose them all wholesale
-    // and a future service cannot be started without also being torn down. These are order-independent background loops/timers, so LIFO disposal order is immaterial.
-    // HDHR is intentionally not a member (it is torn down first in shutdown so its sockets release before the rest), and the browser-launch-scoped precache cycle is
-    // started elsewhere and stopped separately.
-    backgroundServices = new AsyncDisposableStack();
-    startStalePageCleanup();
-    backgroundServices.defer(stopStalePageCleanup);
-    startBrowserRestartChecking();
-    backgroundServices.defer(stopBrowserRestartChecking);
-    startIdleCleanup();
-    backgroundServices.defer(stopIdleCleanup);
-    startShowInfoPolling();
-    backgroundServices.defer(stopShowInfoPolling);
-    startPretunePolling();
-    backgroundServices.defer(stopPretunePolling);
-    startUpdateChecking(getPackageVersion());
-    backgroundServices.defer(stopUpdateChecking);
-    // Build and start Express application.
-    try {
-        const app = await buildApp();
-        // Bind the main HTTP server, detecting bind success or failure through explicit events rather than the unreliable listen callback. A bind failure throws out
-        // of here so the catch below surfaces it and the process exits cleanly rather than lingering with no HTTP surface.
-        server = await listenMainServer(app);
-        // Attach the CDP proxy upgrade handler once the underlying http.Server exists. The handler is gated on the `cdp` debug category at request time, so it sits
-        // dormant until the user enables CDP via /debug. We attach unconditionally so the toggle takes effect without requiring a restart.
-        attachCdpUpgradeHandler(server);
-    }
-    catch (error) {
-        // Covers both a buildApp failure and a listenMainServer bind failure; the latter already logged the precise, operator-actionable line before rejecting.
-        LOG.error("Failed to build or start the HTTP server: %s.", formatError(error));
-        throw error;
+    // The boot's tail arms what runs for the life of the process: the background services, the HTTP server and HDHomeRun emulation.
+    await startBootServices();
+}
+export const defaultStartupFailureDeps = {
+    exit: (code) => {
+        process.exit(code);
+    },
+    isGracefulShutdown
+};
+/**
+ * Ends a startup that failed, the entry point's catch for startServer. A failure that lands once shutdown has begun is one shutdown caused, such as the browser
+ * warm-up's launch that shutdown superseded, so it is shutdown's to end: shutdown owns the exit, and a second exit racing it here would cut its drain short with the
+ * wrong code, so the handler logs the superseded startup and leaves the exit to it. The entry point's unhandled-rejection handler reads the same state for the
+ * same reason. Any other failure is fatal, and the process exits with a failure code so a process manager sees it.
+ * @param error - The error startServer rejected with.
+ * @param deps - The shutdown reader and the exit: the real ones in production, and recording stubs in a test.
+ */
+export function handleStartupFailure(error, deps = defaultStartupFailureDeps) {
+    if (deps.isGracefulShutdown()) {
+        LOG.info("Startup was superseded by shutdown, so the process exits through shutdown.");
+        return;
     }
-    // Start HDHomeRun emulation server if enabled. This runs independently of the main server and handles EADDRINUSE gracefully without affecting PrismCast's
-    // primary functionality.
-    await startHdhrServer();
+    LOG.error("Fatal startup error occurred.", { error: formatError(error) });
+    deps.exit(1);
 }
 //# sourceMappingURL=app.js.map