feat(recording): prioritize channels for authenticated Twitch slot with anonymous handoff

[Serph91P]

Goal

Follow-up to backend modernization #826: let users configure a Twitch authentication priority per channel in channel settings. The highest-priority eligible recording should use the available authenticated Twitch slot, even if a lower-priority recording already owns it. Other recordings should continue anonymously with H.264 where Twitch permits anonymous playback.

This is a new feature on top of the backend rework, not a request to reopen or extend its already completed implementation PR. Issue creation does not authorize implementation or production rollout.

Motivation and observed behavior

On the deployed 2.15.1 build, the configured total upstream budget is 5, but only one authenticated upstream is allowed. While Bonjwa was recording through that slot, starting Giantwaffle failed with authenticated_budget_exhausted instead of using anonymous playback.

A separate observed lifecycle defect left a completed recording's lease ACTIVE with a continuing heartbeat after its child process had exited. Safe slot scheduling must not rely on that stale ownership. These are StreamVault coordination limits, not a claim that Twitch universally permits exactly one authenticated connection.

User-facing behavior

• Add a persisted Twitch authentication priority setting per channel. Proposed ordering: higher integer wins; default 0 gives all existing channels equal priority. Validate and document the supported range.
• Prefer the highest-priority currently recording, auth-eligible channel for the available authenticated recording slot. Missing/invalid credentials must not prevent otherwise playable anonymous recordings.
• A lower-priority newcomer starts anonymously instead of failing solely because the authenticated slot is occupied.
• When a higher-priority channel starts, transfer the slot from the lower-priority recording and continue the displaced recording anonymously, subject to playback availability.
• When the owner ends, promote the highest-priority eligible active recording. Re-evaluate on saved priority changes as well as recording start/stop/recovery.
• Equal priority keeps the current owner to prevent churn; when there is no owner, use a stable, documented tie-breaker.
• Show actual mode (authenticated / anonymous), configured priority, pending handoff and actionable failure reasons. Do not describe a slot conflict as an offline streamer.

Example: Bonjwa has priority 0 and is already recording authenticated. HandOfBlood with priority 100 starts. HandOfBlood receives the authenticated slot; Bonjwa continues anonymously in H.264. Giantwaffle with priority 0 may also record anonymously, within the total upstream budget.

Scheduling and handoff requirements

• Centralize the decision behind the RecordingManager/upstream coordinator rather than duplicating it in manual-start, EventSub, rotation and recovery paths.
• Preserve the authenticated and total upstream budgets. Do not simply raise the auth limit. A transition must account for any temporary process overlap, including when the total budget is full.
• Persist/fence ownership using the existing coordination model. Competing starts, priority edits, cancellation, shutdown and restart recovery must not allocate two authenticated owners or leave orphan subprocesses/heartbeats.
• Use a bounded, serialized handoff: prepare the anonymous continuation, stop and reap the displaced authenticated child, release/fence its slot, and admit the new owner. Define failure/rollback behavior for each stage. Never hold a database lock across unbounded network or subprocess waits.
• A change of Twitch authentication or codec may require restarting Streamlink at a segment boundary. Do not promise gapless switching. Preserve existing media and recording identity, handle codec changes safely in segments/post-processing, and report any handoff gap or partial recording truthfully.
• On normal completion and every failure/cancellation path, stop the owner's heartbeat and release the corresponding lease. A completed recording without a live child must not occupy the slot indefinitely.
• Limit retries and rescheduling churn. A failing high-priority stream must not repeatedly interrupt working lower-priority recordings.
• Recording priorities must not silently preempt unrelated live playback sessions. Specify arbitration with existing live-playback ownership and recovery purposes, and return an explicit waiting/conflict reason where that owner cannot safely be displaced.

Anonymous playback and safety boundaries

• Reuse the explicit anonymous H.264 mode and token validation/fallback work from fix(recording): fall back to anonymous H.264 when Twitch authentication is invalid #834 / fix(recording): validate Twitch auth and fall back to anonymous H.264 #836. This issue extends scheduling for a busy valid-auth slot; it must not duplicate or weaken that implementation.
• Anonymous means no Twitch authorization header or inherited authenticated config. Preserve proxy/direct routing, selected quality where available, and all recording safety settings.
• Authentication priority is a preference, not permission to bypass subscriber-only or other access restrictions. Anonymous availability and equivalent quality are not guaranteed.
• If the displaced stream cannot continue anonymously, the default must not silently terminate a protected recording. Keep the current owner, let the newcomer record anonymously if possible, and report that the requested handoff is blocked. Any future interrupt-existing-recording override requires an explicit user policy.
• Keep credentials out of commands exposed to the UI, logs, events and test artifacts. Settings mutations retain the existing authorization policy.

Acceptance criteria and verification

• Persisted per-channel priority round-trips through backend API and channel settings UI; existing channel data receives a compatible default via a tested migration.
• A occupied by a lower-priority authenticated recording, then higher-priority B starts: B becomes authenticated and A continues anonymously where available, without exceeding either budget.
• A second lower/equal-priority recording starts anonymously without authenticated_budget_exhausted becoming a generic recording failure.
• Owner completion, an offline highest-priority channel, priority edits, missing/rejected tokens, unavailable anonymous playback and total-budget exhaustion produce deterministic, documented outcomes.
• EventSub and manual starts use the same policy. Concurrent starts/recovery/rotation and cross-instance ownership are covered by integration tests.
• Handoff startup failure, subprocess cleanup failure, cancellation and restart cannot leak an auth slot, duplicate a recording, overwrite media or leave a heartbeat attached to a completed recording.
• Frontend tests cover saving priority and displaying effective mode, blocked handoff and partial-recording warnings. Backend tests exercise the scheduler through its public seam using RED/GREEN regressions.
• Run applicable CI-equivalent backend, migration, frontend and security gates. A separately authorized runtime canary must verify actual growing media for both the promoted authenticated and displaced anonymous recordings; a successful start response alone is insufficient.

Related work and scope

• Parent: refactor: modularize and modernize the backend architecture #826, backend modernization and RecordingManager lifecycle.
• Coordinate Twitch upstreams across Recording, Live playback and recovery #783: existing upstream coordination and budgets.
• fix(recording): fall back to anonymous H.264 when Twitch authentication is invalid #834 / fix(recording): validate Twitch auth and fall back to anonymous H.264 #836: invalid-token validation and anonymous H.264 fallback.
• Frontend UX, mobile/PWA and performance overhaul #828: coordinate the channel-settings UI with the frontend overhaul; avoid competing implementations of the same controls.
• No live-container patch, production restart, release, deployment or increase in authenticated concurrency is part of this issue-creation request.