@camstack/addon-pipeline 1.2.38 → 1.2.39

package/dist/stream-broker/index.mjs

@@ -1,12 +1,12 @@
 import { n as __require, r as __toESM, t as __commonJSMin } from "../chunk-DnnnRqeS.mjs";
-import { B as errMsg, G as createEvent, H as CAM_PROFILE_ORDER, J as makeProfileBrokerId, L as streamBrokerCapability, Q as parseProfileBrokerId, U as DeviceFeature, V as BaseAddon, W as DeviceType, X as nodePin, Y as makeSourceBrokerId, ct as object, dt as union, ft as EventCategory, g as addonWidgetsSourceCapability, it as discriminatedUnion, k as maskUrlCredentials, l as EncodeProfileSchema, lt as record, m as RingBuffer, nt as array, ot as literal, q as isEvent, rt as boolean, st as number, tt as _enum, ut as string, y as cameraStreamsCapability, z as webrtcSessionCapability } from "../dist-Du7_SNiR.mjs";
+import { B as errMsg, G as createEvent, H as CAM_PROFILE_ORDER, J as makeProfileBrokerId, L as streamBrokerCapability, Q as parseProfileBrokerId, U as DeviceFeature, V as BaseAddon, W as DeviceType, X as nodePin, Y as makeSourceBrokerId, ct as object, dt as union, ft as EventCategory, g as addonWidgetsSourceCapability, it as discriminatedUnion, k as maskUrlCredentials, l as EncodeProfileSchema, lt as record, m as RingBuffer, nt as array, ot as literal, q as isEvent, rt as boolean, st as number, tt as _enum, ut as string, y as cameraStreamsCapability, z as webrtcSessionCapability } from "../dist-COgGdFMv.mjs";
 import { n as profileForStreamId } from "../remote-restream-BeHi78PZ.mjs";
 import { n as createFileDataPlaneHandler } from "../model-download-service-Cp9f4dk6-CwUb5v3Y.mjs";
 import { createRequire } from "node:module";
-import * as os from "node:os";
-import { networkInterfaces, tmpdir } from "node:os";
 import { spawn } from "node:child_process";
 import { pathToFileURL } from "node:url";
+import * as os from "node:os";
+import { networkInterfaces, tmpdir } from "node:os";
 import * as fs from "node:fs";
 import * as path$1 from "node:path";
 import path, { join } from "node:path";
@@ -3030,6 +3030,22 @@ var AdaptiveSession = class AdaptiveSession {
 	/** Broker source-RTP pre-buffer accessor + one-shot replay guard. */
 	rtpBootstrap;
 	rtpBootstrapDone = false;
+	/**
+	* Answered-but-silent guard. The answer deliberately returns WITHOUT
+	* awaiting source bring-up (bare trickle answer, background dial); the
+	* failure shape that buys is a connected client staring at a black player
+	* because the source never delivered. `sourceMediaSeen` flips on the FIRST
+	* evidence of source media reaching this session — a source RTP packet
+	* (`forwardSourceRtpVideo`, even before DTLS lets it transmit) or a video
+	* NAL write (`writeVideoNals`, the AnnexB + transcode egress) — and the
+	* watchdog armed at feed start warns ONCE if the budget elapses first.
+	*/
+	sourceMediaSeen = false;
+	sourceSilenceTimer = null;
+	/** Budget between "feeding started" (post-answer, post-DTLS) and the first
+	*  source media. Chosen above a healthy cold dial's worst case (~2–3 s) and
+	*  below the point a viewer gives up. */
+	static SOURCE_SILENT_AFTER_ANSWER_MS = 5e3;
 	/** In-flight paced pre-buffer replay (instant-start bootstrap or PLI
 	*  recovery). While active, live source-RTP packets are enqueued behind
 	*  the replay tail to preserve packet order. Aborted on close/rebind. */
@@ -3495,8 +3511,10 @@ var AdaptiveSession = class AdaptiveSession {
 	* compatible answer. This avoids werift transceiver direction issues.
 	*/
 	async handleOffer(clientOffer, opts) {
+		const negotiateStart = Date.now();
 		const { werift, pcOptions } = await this.buildPcOptions();
 		this.pc = new werift.RTCPeerConnection(pcOptions);
+		const pcSetupMs = Date.now() - negotiateStart;
 		this.wireControlChannel();
 		this.pc.iceConnectionStateChange.subscribe((state) => {
 			this.logger.info("ICE state", { meta: {
@@ -3529,7 +3547,9 @@ var AdaptiveSession = class AdaptiveSession {
 				sdpMLineIndex: c.sdpMLineIndex ?? null
 			});
 		});
+		const mdnsStart = Date.now();
 		const resolvedOfferSdp = await resolveMdnsCandidatesInSdp(clientOffer.sdp, this.logger, `session:${this.sessionId}`);
+		const mdnsMs = Date.now() - mdnsStart;
 		const offerCandidates = resolvedOfferSdp.split("\n").map((l) => l.trim()).filter((l) => l.startsWith("a=candidate:"));
 		if (this.debug) this.logger.info("client offer REMOTE ICE candidates", { meta: {
 			phase: "session",
@@ -3540,7 +3560,9 @@ var AdaptiveSession = class AdaptiveSession {
 			candidates: offerCandidates
 		} });
 		const remoteDesc = new werift.RTCSessionDescription(resolvedOfferSdp, clientOffer.type);
+		const setRemoteStart = Date.now();
 		await this.pc.setRemoteDescription(remoteDesc);
+		const setRemoteMs = Date.now() - setRemoteStart;
 		const transceivers = this.pc.getTransceivers();
 		for (const t of transceivers) {
 			const kind = t.receiver?.track?.kind ?? t.kind;
@@ -3589,7 +3611,9 @@ var AdaptiveSession = class AdaptiveSession {
 			const audioTransceiver = this.pc.addTransceiver(this.audioTrack, { direction: "sendonly" });
 			this.audioSender = audioTransceiver.sender;
 		}
+		const createAnswerStart = Date.now();
 		const answerDesc = await this.pc.createAnswer();
+		const createAnswerMs = Date.now() - createAnswerStart;
 		let finalSdp;
 		if (opts?.nonTrickle === true) {
 			await this.pc.setLocalDescription(answerDesc).catch((e) => {
@@ -3617,9 +3641,15 @@ var AdaptiveSession = class AdaptiveSession {
 		this.logger.info("Codec negotiated (client-offer)", { meta: {
 			phase: "session",
 			sessionId: this.sessionId,
+			deviceId: this.deviceId,
 			source: this.sourceCodec,
 			negotiated: this.negotiatedCodec,
-			needsTranscode: this.needsTranscode
+			needsTranscode: this.needsTranscode,
+			negotiateMs: Date.now() - negotiateStart,
+			pcSetupMs,
+			mdnsMs,
+			setRemoteMs,
+			createAnswerMs
 		} });
 		if (this.debug) this.logger.info("Codec negotiation detail (client-offer)", { meta: {
 			phase: "session",
@@ -3769,6 +3799,10 @@ var AdaptiveSession = class AdaptiveSession {
 			clearInterval(this.statsTimer);
 			this.statsTimer = null;
 		}
+		if (this.sourceSilenceTimer) {
+			clearTimeout(this.sourceSilenceTimer);
+			this.sourceSilenceTimer = null;
+		}
 		if (this.feedAbort) {
 			this.feedAbort.abort();
 			this.feedAbort = null;
@@ -3866,6 +3900,7 @@ var AdaptiveSession = class AdaptiveSession {
 	*/
 	forwardSourceRtpVideo(rtpData) {
 		if (this.closed) return;
+		this.sourceMediaSeen = true;
 		const codec = this.negotiatedCodec;
 		if (codec !== "H265" && codec !== "H264") return;
 		if (!this.videoSender || !_werift) return;
@@ -3877,6 +3912,12 @@ var AdaptiveSession = class AdaptiveSession {
 				this.startPacedRtpReplay(bootstrap, codec, "replayed source-RTP pre-buffer (instant start)");
 				return;
 			}
+			this.logger.warn("instant-start pre-buffer empty — viewer waits for the next source IDR", { meta: {
+				phase: "session",
+				sessionId: this.sessionId,
+				deviceId: this.deviceId,
+				codec
+			} });
 		}
 		if (this.activeRtpReplay?.active && this.activeRtpReplay.enqueue(rtpData)) return;
 		this.sendSourceRtpPacket(rtpData, codec);
@@ -4069,6 +4110,27 @@ var AdaptiveSession = class AdaptiveSession {
 		} });
 		this.writeVideoNals(this.lastKeyframeNals, this.sendRtpTimestamp(), this.negotiatedCodec);
 	}
+	/**
+	* Arm the answered-but-silent watchdog: if no source media has reached
+	* this session `SOURCE_SILENT_AFTER_ANSWER_MS` after feeding started, one
+	* named WARN fires. Idempotent; disarmed by `close()`. Public so the guard
+	* is testable without standing up werift.
+	*/
+	armSourceSilenceWatchdog() {
+		if (this.sourceSilenceTimer || this.closed) return;
+		this.sourceSilenceTimer = setTimeout(() => {
+			this.sourceSilenceTimer = null;
+			if (this.closed || this.sourceMediaSeen) return;
+			this.logger.warn("answered but NO source media reached the session — source dial stalled or camera silent", { meta: {
+				phase: "session",
+				sessionId: this.sessionId,
+				deviceId: this.deviceId,
+				budgetMs: AdaptiveSession.SOURCE_SILENT_AFTER_ANSWER_MS,
+				needsTranscode: this.needsTranscode
+			} });
+		}, AdaptiveSession.SOURCE_SILENT_AFTER_ANSWER_MS);
+		this.sourceSilenceTimer.unref?.();
+	}
 	startFeedingFrames() {
 		this.feedAbort = new AbortController();
 		const { signal } = this.feedAbort;
@@ -4078,6 +4140,7 @@ var AdaptiveSession = class AdaptiveSession {
 			dtls: this.videoSender?.dtlsTransport?.state ?? "unknown",
 			needsTranscode: this.needsTranscode
 		} });
+		this.armSourceSilenceWatchdog();
 		if (this.needsTranscode) this.startTranscodeFeed(signal);
 		else this.startDirectFeed(signal);
 	}
@@ -4653,6 +4716,7 @@ var AdaptiveSession = class AdaptiveSession {
 		});
 	}
 	writeVideoNals(nals, rtpTs, codec) {
+		this.sourceMediaSeen = true;
 		if (!this.videoSender || !_werift) {
 			if (this.rtpLogCounter === 0) {
 				this.logger.warn("writeVideoNals: no sender", { meta: {
@@ -9730,6 +9794,21 @@ var DecoderSessionProxy = class {
 		this.api = api;
 		this.sessionId = sessionId;
 	}
+	/**
+	* Guarantee an empty drain cannot re-poll faster than `POLL_WAIT_MS`,
+	* regardless of the peer. A WELL-BEHAVED decoder blocks server-side for
+	* `waitMs` (await-notify long-poll), so `elapsedMs >= POLL_WAIT_MS` and this
+	* is a no-op. But the loop's liveness must NOT depend on peer courtesy: a
+	* peer that resolves `[]` instantly — the dormant `decoder-nodeav.pullHandles`
+	* stub, an old decoder that predates `waitMs`, a test fake — would otherwise
+	* turn `startPolling`/`startHandlePolling` into a ZERO-YIELD microtask spin
+	* that pins the CPU, starves every timer in the process, and allocates until
+	* the heap dies (observed: a 4 GB OOM in under 15 s).
+	*/
+	async paceEmptyDrain(drainStartedAt) {
+		const remainderMs = POLL_WAIT_MS - (Date.now() - drainStartedAt);
+		if (remainderMs > 0) await new Promise((resolve) => setTimeout(resolve, remainderMs));
+	}
 	async pushPacket(packet) {
 		await this.api.pushPacket({
 			sessionId: this.sessionId,
@@ -9745,12 +9824,14 @@ var DecoderSessionProxy = class {
 	async startPolling(onFrame) {
 		this.polling = true;
 		while (this.polling) {
+			const drainStartedAt = Date.now();
 			const frames = await this.api.pullFrames({
 				sessionId: this.sessionId,
 				maxCount: 4,
 				waitMs: POLL_WAIT_MS
 			});
 			for (const frame of frames) onFrame(frame);
+			if (frames.length === 0 && this.polling) await this.paceEmptyDrain(drainStartedAt);
 		}
 	}
 	/**
@@ -9768,12 +9849,14 @@ var DecoderSessionProxy = class {
 	async startHandlePolling(onHandle) {
 		this.polling = true;
 		while (this.polling) try {
+			const drainStartedAt = Date.now();
 			const handles = await this.api.pullHandles({
 				sessionId: this.sessionId,
 				maxCount: 4,
 				waitMs: POLL_WAIT_MS
 			});
 			for (const handle of handles) onHandle(handle);
+			if (handles.length === 0 && this.polling) await this.paceEmptyDrain(drainStartedAt);
 		} catch (err) {
 			this.polling = false;
 			const msg = err instanceof Error ? err.message : String(err);
@@ -17779,6 +17862,71 @@ function withSourceResolution(consumerDefault, probedSource) {
 	};
 }
 //#endregion
+//#region src/stream-broker/webrtc/broker-linger-registry.ts
+/** Matches the observed reopen gaps (1–2 min) with headroom; well under the
+*  "operator walked away" scale where warmth would be waste. */
+var DEFAULT_LINGER_MS = 3 * 6e4;
+var BrokerLingerRegistry = class {
+	lingerMs;
+	subscribe;
+	holds = /* @__PURE__ */ new Map();
+	constructor(options) {
+		this.lingerMs = options.lingerMs ?? DEFAULT_LINGER_MS;
+		this.subscribe = options.subscribe;
+	}
+	/**
+	* Start (or restart) the linger window for a broker that just lost its
+	* last session. Re-holding an already-held broker re-arms the timer
+	* without stacking a second ghost subscription.
+	*/
+	hold(brokerId) {
+		const existing = this.holds.get(brokerId);
+		if (existing) {
+			clearTimeout(existing.timer);
+			existing.timer = this.armTimer(brokerId);
+			return;
+		}
+		const unsubscribe = this.subscribe(brokerId);
+		if (unsubscribe === null) return;
+		this.holds.set(brokerId, {
+			unsubscribe,
+			timer: this.armTimer(brokerId)
+		});
+	}
+	/** Release the hold NOW — a new session attached, the real subscription
+	*  carries the demand from here. No-op when nothing is held. */
+	cancel(brokerId) {
+		const hold = this.holds.get(brokerId);
+		if (!hold) return;
+		clearTimeout(hold.timer);
+		this.holds.delete(brokerId);
+		this.release(hold);
+	}
+	/** Release every hold (server shutdown). */
+	stop() {
+		for (const [brokerId, hold] of this.holds) {
+			clearTimeout(hold.timer);
+			this.holds.delete(brokerId);
+			this.release(hold);
+		}
+	}
+	armTimer(brokerId) {
+		const timer = setTimeout(() => {
+			const hold = this.holds.get(brokerId);
+			if (!hold) return;
+			this.holds.delete(brokerId);
+			this.release(hold);
+		}, this.lingerMs);
+		timer.unref?.();
+		return timer;
+	}
+	release(hold) {
+		try {
+			hold.unsubscribe();
+		} catch {}
+	}
+};
+//#endregion
 //#region src/stream-broker/webrtc/loss-tracker.ts
 /** Delta between two RTCP extended (32-bit) highest-sequence values, with
 *  32-bit wraparound handling. */
@@ -17827,6 +17975,24 @@ var LossTracker = class {
 		if (now < this.resetUntil) return false;
 		return this.lossRatio() > this.config.minFailPercent;
 	}
+	/**
+	* True when the window holds enough recent receiver feedback for a
+	* "healthy" verdict to MEAN anything.
+	*
+	* `lossRatio()` returns 0 with fewer than two in-window samples, so
+	* `isFailing` is false for a session that has produced NO feedback at all —
+	* a link so bad that RTCP never arrives reads identically to a perfect one.
+	* A downgrade may act on that (0 loss ⇒ don't downgrade, which is safe); an
+	* UPGRADE must not, because it spends bandwidth the session has never been
+	* shown to have. Silence is not health.
+	*/
+	hasEvidence(now) {
+		if (now < this.resetUntil) return false;
+		const cutoff = now - this.config.analyzeWindowMs;
+		let inWindow = 0;
+		for (const s of this.samples) if (s.time > cutoff) inWindow += 1;
+		return inWindow >= 2;
+	}
 };
 //#endregion
 //#region src/stream-broker/webrtc/adaptive-controller.ts
@@ -17835,8 +18001,17 @@ var TIER_ORDER = CAM_PROFILE_ORDER;
 * Ladder state machine for an adaptive WebRTC session. Fed loss samples
 * (RTCP RR or client-reported) via `onLoss`; `tick` evaluates the ladder.
 * Downgrade order: tier high→mid→low, then MTU reduction at low, then
-* transcode-down. Upgrade one tier after sustained health + hysteresis.
-* Side effects run through injected callbacks (testable without werift).
+* transcode-down. Side effects run through injected callbacks (testable
+* without werift).
+*
+* An UPGRADE requires all three of:
+*  1. the session clock — measured from the FIRST tick, not from the unix
+*     epoch — showing `upgradeHealthyMs` without a failing verdict;
+*  2. actual receiver feedback in the window (`LossTracker.hasEvidence`) —
+*     a session that has produced no RTCP at all is not "healthy", it is
+*     silent, and climbing on silence spends bandwidth never shown to exist;
+*  3. the target tier's re-attempt backoff, which doubles per measured
+*     failure of that tier in this session.
 */
 var AdaptiveController = class {
 	opts;
@@ -17846,27 +18021,86 @@ var AdaptiveController = class {
 	transcodeEngaged = false;
 	lastChangeAt = 0;
 	healthySince = 0;
+	/**
+	* Whether the session clock has been armed by the first evaluation. The
+	* clock is `Date.now()`, so leaving `healthySince` / `lastChangeAt` at 0
+	* would read as "healthy since 1970" and hand out a free upgrade on the
+	* very first tick, before a single loss sample had been seen. A boolean
+	* (not a `startedAt === 0` sentinel) because 0 is a legitimate clock value.
+	*/
+	armed = false;
+	failures;
 	constructor(opts) {
 		this.opts = opts;
 		this.tracker = new LossTracker(opts.config);
 		this.tier = opts.initialTier;
+		this.failures = new Map(opts.priorFailures ?? []);
 	}
 	get currentTier() {
 		return this.tier;
 	}
+	/**
+	* Per-tier measured-failure counts, INCLUDING those inherited from earlier
+	* rungs of the same viewer session. The server snapshots this into the
+	* adaptive intent so the session's next controller inherits it.
+	*/
+	get failureCounts() {
+		return this.failures;
+	}
 	onLoss(sample, now) {
 		this.tracker.track(sample, now);
 	}
+	/**
+	* Freeze the ladder for this evaluation instead of ticking it.
+	*
+	* Called while the session's track is NOT carrying the live source — D42
+	* put recorded playback and scrub on the same track with a moving source
+	* pointer, and in those modes the live feed is gated, so receiver feedback
+	* measures the recorded feeder, not the camera tier. Acting on it is
+	* incoherent in both directions: a downgrade cannot shrink a file, an
+	* upgrade cannot enlarge one, and EITHER destroys the feeder (a tier switch
+	* is a close-and-recreate re-offer) — dropping the viewer back to live at
+	* the wrong moment with nothing to restore the pointer.
+	*
+	* Holds the climb clock so time spent in recorded modes can never
+	* accumulate into an upgrade on the return to live.
+	*/
+	suspend(now) {
+		if (!this.armed) {
+			this.armed = true;
+			this.lastChangeAt = now;
+		}
+		this.healthySince = now;
+	}
 	tick(now) {
+		if (!this.armed) {
+			this.armed = true;
+			this.healthySince = now;
+			this.lastChangeAt = now;
+		}
 		if (this.tracker.isFailing(now)) {
 			this.healthySince = now;
 			this.handleFailing(now);
 			return;
 		}
+		if (!this.tracker.hasEvidence(now)) {
+			this.healthySince = now;
+			return;
+		}
 		this.handleHealthy(now);
 	}
 	canUpgrade(now) {
-		return now - this.lastChangeAt >= this.opts.config.minTimeBetweenChangesMs || this.lastChangeAt === 0;
+		return now - this.lastChangeAt >= this.opts.config.minTimeBetweenChangesMs;
+	}
+	/**
+	* How long the link must read healthy before `tier` may be re-attempted.
+	* Doubles per measured failure of that tier in this session, capped at
+	* `maxUpgradeBackoffMs`.
+	*/
+	requiredHealthyMs(tier) {
+		const failures = this.failures.get(tier) ?? 0;
+		if (failures <= 0) return this.opts.config.upgradeHealthyMs;
+		return Math.min(this.opts.config.upgradeHealthyMs * 2 ** failures, this.opts.config.maxUpgradeBackoffMs);
 	}
 	commitChange(now) {
 		this.lastChangeAt = now;
@@ -17875,6 +18109,8 @@ var AdaptiveController = class {
 	handleFailing(now) {
 		const idx = TIER_ORDER.indexOf(this.tier);
 		if (idx < TIER_ORDER.length - 1) {
+			const failed = this.tier;
+			this.failures.set(failed, (this.failures.get(failed) ?? 0) + 1);
 			this.tier = TIER_ORDER[idx + 1];
 			this.opts.onSwitchTier(this.tier);
 			this.commitChange(now);
@@ -17893,17 +18129,17 @@ var AdaptiveController = class {
 		}
 	}
 	handleHealthy(now) {
-		if (now - this.healthySince < this.opts.config.upgradeHealthyMs) return;
-		if (!this.canUpgrade(now)) return;
 		const idx = TIER_ORDER.indexOf(this.tier);
-		if (idx > 0) {
-			this.tier = TIER_ORDER[idx - 1];
-			this.mtuReduced = false;
-			this.transcodeEngaged = false;
-			this.opts.onSwitchTier(this.tier);
-			this.commitChange(now);
-			this.healthySince = now;
-		}
+		if (idx <= 0) return;
+		const next = TIER_ORDER[idx - 1];
+		if (now - this.healthySince < this.requiredHealthyMs(next)) return;
+		if (!this.canUpgrade(now)) return;
+		this.tier = next;
+		this.mtuReduced = false;
+		this.transcodeEngaged = false;
+		this.opts.onSwitchTier(next);
+		this.commitChange(now);
+		this.healthySince = now;
 	}
 };
 //#endregion
@@ -17928,6 +18164,7 @@ var ControlMessageSchema = discriminatedUnion("t", [
 		t: literal("scrubTo"),
 		epoch: number()
 	}),
+	object({ t: literal("scrubAck") }),
 	object({
 		t: literal("setRate"),
 		rate: number().min(0).max(4)
@@ -18101,6 +18338,74 @@ var SCRUB_CACHE_MAX = 8;
 * sustained direction, so a jittery/reversing drag never wastes the slot.
 */
 var SCRUB_PREFETCH_DIR_THRESHOLD = 2;
+/**
+* Max forward TARGET delta (ms of timeline, between consecutive drag targets)
+* that SWEEPS predicted frames instead of jumping. A steady forward drag is
+* playback with a moving target: once a keyframe decoded, the predicted frames
+* after it decode in sequence at a fraction of an IDR's bytes — that is the
+* continuous flow. Beyond this window (a fling), or backwards, a jump to an
+* independently-decodable keyframe is cheaper than the burst; and because a
+* thin pipe slows the ack-gated ticks down, per-tick deltas GROW under
+* congestion, so degradation to jump-only is emergent, and visible per push
+* (`mode` on every scrub-feeder:pushed line).
+*/
+var SCRUB_SWEEP_WINDOW_MS = 4e3;
+/**
+* Receiver-credit cap for scrub pushes: at most this many keyframes may be
+* OUTSTANDING (pushed onto the track but not yet acknowledged as RENDERED by
+* the viewer via `scrubAck`). The coalescing window above shapes the INPUT; on
+* a thin pipe it is not backpressure — pushing a ~45 KB keyframe every 60 ms
+* floods a link that delivers one every 500 ms, RTP drops, and nothing paints.
+* Backpressure is the receiver's: a push spends a credit, a rendered frame
+* restores one, and with zero credit the newest target PARKS on
+* `scrubPendingEpochMs` until an ack arrives — a timer never releases work.
+*/
+var SCRUB_CREDIT_CAP = 2;
+/**
+* How far a `gap` locate may be SNAPPED onto real footage.
+*
+* A snap is a CORRECTION — the playhead landed a moment outside coverage and
+* the operator plainly means the footage beside it — not a SEARCH for wherever
+* footage happens to exist. The distinction is not cosmetic, because the index
+* that answers `locate` cannot tell "there is no footage here" apart from "I
+* have not walked this far back yet": it is rebuilt by walking the archive on
+* every recorder start, and that walk takes minutes.
+*
+* Production 2026-08-02: the recorder had restarted 9 minutes earlier, so
+* `locate` answered `gap` for the whole timeline with a `nearestEdgeMs` 6
+* minutes to 23 HOURS away. Unbounded snapping turned every seek and every drag
+* tick into a segment read against the addon that was busy re-walking, each one
+* blew the 8 s budget, and both surfaces died. Bounded, all of those answer
+* `gap` for free — exactly as they did before snapping existed.
+*
+* 120 s covers the real cases by a wide margin: an inter-segment crack is
+* 11–17 ms, and the dead band between two recording bands measured 48 s. Beyond
+* that the server is answering a question the viewer did not ask; the viewer
+* holds the coverage ranges and can offer "jump to nearest footage" as an
+* action instead.
+*/
+var SNAP_MAX_DISTANCE_MS = 12e4;
+/**
+* Decide where a `gap` locate should snap: forward to the next footage edge,
+* else backward onto the last ms of the footage behind (`prevEndMs − 1`, which
+* also hops the 11–17 ms inter-segment cracks). Rejects a candidate further than
+* {@link SNAP_MAX_DISTANCE_MS} so a partially-walked index cannot teleport the
+* cursor — and so rejecting costs NO segment I/O at all.
+*/
+function resolveSnapTarget(loc, requestedMs) {
+	const snapMs = loc.nearestEdgeMs ?? (typeof loc.prevEndMs === "number" ? loc.prevEndMs - 1 : null);
+	if (snapMs === null) return { kind: "none" };
+	const distanceMs = Math.abs(snapMs - requestedMs);
+	if (distanceMs > SNAP_MAX_DISTANCE_MS) return {
+		kind: "too-far",
+		snapMs,
+		distanceMs
+	};
+	return {
+		kind: "snap",
+		snapMs
+	};
+}
 var RecordedFeeder = class {
 	deps;
 	clock = new MonotonicClock();
@@ -18143,6 +18448,16 @@ var RecordedFeeder = class {
 	*/
 	scrubbing = false;
 	scrubToken = 0;
+	/** Remaining receiver credit for scrub pushes — see {@link SCRUB_CREDIT_CAP}. */
+	scrubCredit = SCRUB_CREDIT_CAP;
+	/**
+	* Frames still unrendered, per outstanding PUSH, oldest first. A jump enqueues
+	* `1`; a sweep enqueues however many predicted frames it put on the wire. Each
+	* `scrubAck` settles one frame off the head, and the credit that push spent
+	* comes back only when the head reaches zero — so a sweep cannot be refunded
+	* once per frame for the single credit it cost.
+	*/
+	scrubOutstanding = [];
 	/** The newest un-processed drag target (null when the tick cycle has drained). */
 	scrubPendingEpochMs = null;
 	/**
@@ -18173,6 +18488,15 @@ var RecordedFeeder = class {
 	* sign of `(newTarget − this)` is the drag direction that steers prefetch.
 	*/
 	scrubPrevTarget = null;
+	/** The last AU actually pushed this drag — the sweep-continuity cursor
+	*  (which fragment, and how deep into its AU list). Null until a jump lands. */
+	scrubCursor = null;
+	/** Per-drag mode accounting for the `scrub-feeder:drag-end` summary. */
+	scrubJumps = 0;
+	scrubSweeps = 0;
+	scrubAusPushed = 0;
+	/** Once-per-drag guard: a dead-zone drag ticks fast; one line says it all. */
+	scrubNoFootageLogged = false;
 	/**
 	* Signed run-length of consecutive same-direction `scrubTo` deltas (+ forward,
 	* − backward). A prefetch commits only once `|run| ≥ SCRUB_PREFETCH_DIR_THRESHOLD`;
@@ -18210,9 +18534,19 @@ var RecordedFeeder = class {
 	async seek(epochMs) {
 		const token = ++this.seekToken;
 		if (this.scrubbing) {
+			this.deps.onLog?.("scrub-feeder:drag-end", {
+				jumps: this.scrubJumps,
+				sweeps: this.scrubSweeps,
+				aus: this.scrubAusPushed
+			});
 			this.scrubbing = false;
 			this.scrubToken++;
 			this.scrubSegment = null;
+			this.scrubCursor = null;
+			this.scrubJumps = 0;
+			this.scrubSweeps = 0;
+			this.scrubAusPushed = 0;
+			this.scrubOutstanding = [];
 			this.scrubCache.clear();
 			this.scrubPrevTarget = null;
 			this.scrubDirRun = 0;
@@ -18223,29 +18557,67 @@ var RecordedFeeder = class {
 		}
 		this.advanceToken++;
 		this.inFlightSeekEpochMs = epochMs;
+		let snapInfo = null;
 		try {
 			this.deps.onState("loading");
 			if (this.clockHasAdvanced) {
 				this.clock.markDiscontinuity(SEEK_DISCONTINUITY_MS);
 				this.audioClock.markDiscontinuity(SEEK_DISCONTINUITY_MS);
 			}
-			const loc = await this.withTimeout(this.deps.locate({
+			let loc = await this.withTimeout(this.deps.locate({
 				deviceId: this.deps.deviceId,
 				profile: this.deps.profile,
 				epochMs
 			}));
 			if (this.disposed || token !== this.seekToken) return;
+			let landMs = epochMs;
 			if (loc.kind === "gap") {
-				this.currentSegment = null;
-				this.lastFedVideoIdx = -1;
-				this.stopPositionReports();
-				this.deps.onState("gap");
-				return;
+				const decision = resolveSnapTarget(loc, epochMs);
+				if (decision.kind !== "snap") {
+					if (decision.kind === "too-far") this.deps.onLog?.("recorded:snap-too-far", {
+						requestedMs: epochMs,
+						nearestMs: decision.snapMs,
+						distanceMs: decision.distanceMs
+					});
+					else this.deps.onLog?.("recorded:seek-no-footage", { requestedMs: epochMs });
+					this.currentSegment = null;
+					this.lastFedVideoIdx = -1;
+					this.stopPositionReports();
+					this.deps.onState("gap");
+					return;
+				}
+				const snapped = await this.withTimeout(this.deps.locate({
+					deviceId: this.deps.deviceId,
+					profile: this.deps.profile,
+					epochMs: decision.snapMs
+				}));
+				if (this.disposed || token !== this.seekToken) return;
+				if (snapped.kind !== "segment") {
+					this.deps.onLog?.("recorded:seek-no-footage", {
+						requestedMs: epochMs,
+						snappedMs: decision.snapMs
+					});
+					this.currentSegment = null;
+					this.lastFedVideoIdx = -1;
+					this.stopPositionReports();
+					this.deps.onState("gap");
+					return;
+				}
+				this.deps.onLog?.("recorded:seek-snapped", {
+					requestedMs: epochMs,
+					snappedMs: decision.snapMs
+				});
+				loc = snapped;
+				landMs = decision.snapMs;
+				snapInfo = {
+					requestedMs: epochMs,
+					snappedMs: decision.snapMs
+				};
 			}
 			this.cursorMs = loc.startMs;
 			const loaded = await this.loadAus(loc.startMs, this.rate !== 0);
 			if (this.disposed || token !== this.seekToken || loaded === null) return;
-			this.feedPrefix(loc, loaded.video, epochMs);
+			this.feedPrefix(loc, loaded.video, landMs);
 			if (this.rate === 0) {
 				this.deps.onState("paused");
 				this.deps.onPosition(this.cursorMs);
@@ -18265,9 +18637,20 @@ var RecordedFeeder = class {
 				},
 				resumeAfterPtsMs: lastFedAu ? lastFedAu.ptsMs : null
 			});
-		} catch {
+		} catch (err) {
 			if (!this.disposed && token === this.seekToken) {
 				this.stopPositionReports();
+				if (snapInfo !== null) {
+					this.deps.onLog?.("recorded:seek-snap-load-failed", {
+						requestedMs: snapInfo.requestedMs,
+						snappedMs: snapInfo.snappedMs,
+						error: errMsg(err)
+					});
+					this.currentSegment = null;
+					this.lastFedVideoIdx = -1;
+					this.deps.onState("gap");
+					return;
+				}
 				this.deps.onState("error");
 			}
 		} finally {
@@ -18322,8 +18705,15 @@ var RecordedFeeder = class {
 		this.scrubToken++;
 		this.scrubPendingEpochMs = null;
 		this.scrubSegment = null;
+		this.scrubCredit = SCRUB_CREDIT_CAP;
 		this.scrubPrevTarget = null;
 		this.scrubDirRun = 0;
+		this.scrubCursor = null;
+		this.scrubJumps = 0;
+		this.scrubSweeps = 0;
+		this.scrubAusPushed = 0;
+		this.scrubNoFootageLogged = false;
+		this.scrubOutstanding = [];
 		if (this.scrubTimer) {
 			clearTimeout(this.scrubTimer);
 			this.scrubTimer = null;
@@ -18343,6 +18733,24 @@ var RecordedFeeder = class {
 		if (this.scrubTimer === null) this.scrubTimer = setTimeout(() => void this.scrubTick(), 0);
 	}
 	/**
+	* Receiver credit: the viewer RENDERED a scrub frame. Restores one push
+	* credit (capped — over-acking never banks a burst) and, when a target sat
+	* parked on an exhausted budget, resumes the tick. This — not any timer — is
+	* what paces scrub pushes to what the link actually delivers.
+	*/
+	scrubAck() {
+		if (this.disposed) return;
+		const head = this.scrubOutstanding[0];
+		if (head === void 0) return;
+		if (head > 1) {
+			this.scrubOutstanding[0] = head - 1;
+			return;
+		}
+		this.scrubOutstanding.shift();
+		this.scrubCredit = Math.min(SCRUB_CREDIT_CAP, this.scrubCredit + 1);
+		if (this.scrubbing && this.scrubPendingEpochMs !== null && this.scrubTimer === null) this.scrubTimer = setTimeout(() => void this.scrubTick(), 0);
+	}
+	/**
 	* One coalesced feeder-scrub push. Captures the newest pending target + the
 	* current mode generation, resolves the covering fragment (reusing the memo'd
 	* one when the target stays inside it), picks the nearest keyframe ≤ the
@@ -18353,25 +18761,68 @@ var RecordedFeeder = class {
 	*/
 	async scrubTick() {
 		const gen = this.scrubToken;
+		if (this.disposed || !this.scrubbing || gen !== this.scrubToken) {
+			this.scrubTimer = null;
+			return;
+		}
+		if (this.scrubCredit <= 0) {
+			this.scrubTimer = null;
+			this.deps.onLog?.("scrub-feeder:parked", { pendingEpochMs: this.scrubPendingEpochMs });
+			return;
+		}
 		const target = this.scrubPendingEpochMs;
 		this.scrubPendingEpochMs = null;
-		if (this.disposed || !this.scrubbing || gen !== this.scrubToken || target === null) {
+		if (target === null) {
 			this.scrubTimer = null;
 			return;
 		}
 		try {
-			const loc = await this.withTimeout(this.deps.locate({
+			let loc = await this.withTimeout(this.deps.locate({
 				deviceId: this.deps.deviceId,
 				profile: this.deps.profile,
 				epochMs: target
 			}));
 			if (this.disposed || !this.scrubbing || gen !== this.scrubToken) return;
-			if (loc.kind === "gap") return;
+			let effTarget = target;
+			if (loc.kind === "gap") {
+				const decision = resolveSnapTarget(loc, target);
+				if (decision.kind !== "snap") {
+					if (!this.scrubNoFootageLogged) {
+						this.scrubNoFootageLogged = true;
+						if (decision.kind === "too-far") this.deps.onLog?.("scrub-feeder:snap-too-far", {
+							epochMs: target,
+							nearestMs: decision.snapMs,
+							distanceMs: decision.distanceMs
+						});
+						else this.deps.onLog?.("scrub-feeder:no-footage", { epochMs: target });
+					}
+					return;
+				}
+				const snapped = await this.withTimeout(this.deps.locate({
+					deviceId: this.deps.deviceId,
+					profile: this.deps.profile,
+					epochMs: decision.snapMs
+				}));
+				if (this.disposed || !this.scrubbing || gen !== this.scrubToken) return;
+				if (snapped.kind !== "segment") {
+					if (!this.scrubNoFootageLogged) {
+						this.scrubNoFootageLogged = true;
+						this.deps.onLog?.("scrub-feeder:no-footage", { epochMs: target });
+					}
+					return;
+				}
+				this.deps.onLog?.("scrub-feeder:snapped", {
+					requestedMs: target,
+					snappedMs: decision.snapMs
+				});
+				loc = snapped;
+				effTarget = decision.snapMs;
+			}
 			let seg = this.scrubSegment;
 			if (!seg || seg.startMs !== loc.startMs) {
 				seg = this.scrubCacheGet(loc.startMs);
 				if (!seg) {
-					const loaded = await this.loadAus(loc.startMs, false, true);
+					const loaded = await this.loadAus(loc.startMs, false);
 					if (this.disposed || !this.scrubbing || gen !== this.scrubToken || loaded === null) return;
 					seg = {
 						startMs: loc.startMs,
@@ -18382,26 +18833,80 @@ var RecordedFeeder = class {
 				}
 				this.scrubSegment = seg;
 			}
-			const au = seg.aus[this.pickScrubKeyframe(seg, target)];
-			if (!au) return;
-			if (this.clockHasAdvanced) this.clock.markDiscontinuity(SEEK_DISCONTINUITY_MS);
-			this.deps.sink.pushAccessUnit(au.data, this.clock.stamp(au.ptsMs), au.codec);
+			const prevTarget = this.scrubPrevTarget;
+			const cursor = this.scrubCursor;
+			const targetIdx = this.pickScrubIndex(seg, effTarget, false);
+			const forwardDelta = prevTarget === null ? null : effTarget - prevTarget;
+			const withinWindow = forwardDelta !== null && forwardDelta > 0 && forwardDelta <= SCRUB_SWEEP_WINDOW_MS;
+			const sameFragment = cursor !== null && cursor.fragStartMs === seg.startMs;
+			const adjacentForward = cursor !== null && seg.startMs === cursor.fragStartMs + cursor.fragDurMs;
+			let aus;
+			let firstIdx;
+			let mode;
+			let crossesFragment = false;
+			if (withinWindow && sameFragment && cursor !== null && targetIdx > cursor.idx) {
+				mode = "sweep";
+				firstIdx = cursor.idx + 1;
+				aus = seg.aus.slice(firstIdx, targetIdx + 1);
+			} else if (withinWindow && adjacentForward) {
+				mode = "sweep";
+				firstIdx = 0;
+				aus = seg.aus.slice(0, targetIdx + 1);
+				crossesFragment = true;
+			} else {
+				mode = "jump";
+				firstIdx = this.pickScrubIndex(seg, effTarget, true);
+				const kf = seg.aus[firstIdx];
+				aus = kf === void 0 ? [] : [kf];
+			}
+			const lastAu = aus[aus.length - 1];
+			if (lastAu === void 0) {
+				this.deps.onPosition(this.clampIntoSegment(seg, effTarget));
+				this.scrubPrevTarget = effTarget;
+				return;
+			}
+			if (mode === "jump" && this.clockHasAdvanced) this.clock.markDiscontinuity(SEEK_DISCONTINUITY_MS);
+			else if (crossesFragment && this.clockHasAdvanced) this.clock.markSeek();
+			for (const au of aus) this.deps.sink.pushAccessUnit(au.data, this.clock.stamp(au.ptsMs), au.codec);
+			this.scrubOutstanding.push(aus.length);
+			this.scrubCredit -= 1;
 			this.clockHasAdvanced = true;
-			this.deps.onPosition(this.clampIntoSegment(seg, target));
-			this.maybeScrubPrefetch(seg, target, gen);
-		} catch {} finally {
-			if (gen !== this.scrubToken) {} else if (!this.disposed && this.scrubbing && this.scrubPendingEpochMs !== null) this.scrubTimer = setTimeout(() => void this.scrubTick(), SCRUB_COALESCE_MS);
+			if (mode === "jump") this.scrubJumps += 1;
+			else this.scrubSweeps += 1;
+			this.scrubAusPushed += aus.length;
+			this.scrubCursor = {
+				fragStartMs: seg.startMs,
+				fragDurMs: seg.durMs,
+				idx: firstIdx + aus.length - 1
+			};
+			this.deps.onLog?.("scrub-feeder:pushed", {
+				epochMs: effTarget,
+				mode,
+				aus: aus.length,
+				codec: lastAu.codec,
+				bytes: lastAu.data.length,
+				creditLeft: this.scrubCredit
+			});
+			this.deps.onPosition(this.clampIntoSegment(seg, effTarget));
+			this.maybeScrubPrefetch(seg, effTarget, gen);
+		} catch (err) {
+			this.deps.onLog?.("scrub-feeder:tick-failed", {
+				epochMs: target,
+				error: err instanceof Error ? err.message : String(err)
+			});
+		} finally {
+			if (gen !== this.scrubToken) {} else if (!this.disposed && this.scrubbing && this.scrubPendingEpochMs !== null && this.scrubCredit > 0) this.scrubTimer = setTimeout(() => void this.scrubTick(), SCRUB_COALESCE_MS);
 			else this.scrubTimer = null;
 		}
 	}
 	/**
-	* Index of the nearest keyframe at-or-before the drag target within `seg`
+	* Index of the nearest AU at-or-before the drag target within `seg`
 	* (default 0 — the fragment's params-fused IDR, which the demux contract
-	* guarantees). Scans the access units whose PTS offset is ≤ the target offset
-	* and returns the LAST keyframe among them, so the pushed frame is standalone-
-	* decodable yet as close to the target as the GOP structure allows.
+	* guarantees). `keyframesOnly` restricts the pick to sync frames — the JUMP
+	* mode, whose pushed frame must be standalone-decodable; sweep mode picks
+	* ANY frame, which is what makes the flow frame-granular.
 	*/
-	pickScrubKeyframe(seg, target) {
+	pickScrubIndex(seg, target, keyframesOnly) {
 		const first = seg.aus[0];
 		if (!first) return 0;
 		const offsetMs = target - seg.startMs;
@@ -18410,7 +18915,7 @@ var RecordedFeeder = class {
 			const au = seg.aus[i];
 			if (!au) continue;
 			if (au.ptsMs - first.ptsMs > offsetMs) break;
-			if (au.keyframe) idx = i;
+			if (!keyframesOnly || au.keyframe) idx = i;
 		}
 		return idx;
 	}
@@ -18481,7 +18986,7 @@ var RecordedFeeder = class {
 			if (this.disposed || !this.scrubbing || gen !== this.scrubToken) return;
 			if (loc.kind !== "segment") return;
 			if (this.scrubCache.has(loc.startMs)) return;
-			const loaded = await this.loadAus(loc.startMs, false, true);
+			const loaded = await this.loadAus(loc.startMs, false);
 			if (this.disposed || !this.scrubbing || gen !== this.scrubToken || loaded === null) return;
 			this.scrubCachePut({
 				startMs: loc.startMs,
@@ -18831,10 +19336,8 @@ var RecordedFeeder = class {
 	*  access units. Keyed on `seekToken` so a fresh seek aborts an in-flight load
 	*  (latest-wins). Returns null on abort. Audio demux failures yield [] (audio
 	*  never blocks video). `wantAudio: false` skips the audio transcode entirely
-	*  (paused scrubs would throw it away). `useScrubDemux: true` selects the
-	*  keyframe-only scrub demux (`deps.demuxScrub`, falling back to `deps.demux`
-	*  when absent — flag-off byte-identity). */
-	async loadAus(startMs, wantAudio = true, useScrubDemux = false) {
+	*  (paused scrubs would throw it away). */
+	async loadAus(startMs, wantAudio = true) {
 		const token = this.seekToken;
 		const bytes = await this.withTimeout(this.deps.readBytes({
 			deviceId: this.deps.deviceId,
@@ -18842,8 +19345,7 @@ var RecordedFeeder = class {
 			startMs
 		}));
 		if (this.disposed || token !== this.seekToken) return null;
-		const demux = useScrubDemux && this.deps.demuxScrub ? this.deps.demuxScrub : this.deps.demux;
-		const video = await this.withTimeout(demux(bytes));
+		const video = await this.withTimeout(this.deps.demux(bytes));
 		if (this.disposed || token !== this.seekToken) return null;
 		let audio = [];
 		if (wantAudio && this.deps.demuxAudio && this.resolveAudioPush() !== void 0) {
@@ -18889,6 +19391,11 @@ var RecordedFeeder = class {
 	}
 	/** Stop everything: invalidate in-flight work and tear down the position timer. */
 	dispose() {
+		if (this.scrubbing) this.deps.onLog?.("scrub-feeder:drag-end", {
+			jumps: this.scrubJumps,
+			sweeps: this.scrubSweeps,
+			aus: this.scrubAusPushed
+		});
 		this.disposed = true;
 		this.seekToken++;
 		this.advanceToken++;
@@ -18898,6 +19405,12 @@ var RecordedFeeder = class {
 		this.scrubCache.clear();
 		this.scrubPrevTarget = null;
 		this.scrubDirRun = 0;
+		this.scrubCursor = null;
+		this.scrubJumps = 0;
+		this.scrubSweeps = 0;
+		this.scrubAusPushed = 0;
+		this.scrubNoFootageLogged = false;
+		this.scrubOutstanding = [];
 		if (this.scrubTimer) {
 			clearTimeout(this.scrubTimer);
 			this.scrubTimer = null;
@@ -18925,6 +19438,16 @@ var TimelineSession = class {
 		this.deps = deps;
 		deps.session.setLiveFeedGate(false);
 	}
+	/**
+	* Which source the track is currently carrying. Read by the broker's
+	* adaptive ladder, which must NOT act while the pointer is off live: a tier
+	* switch is a close-and-recreate re-offer, and that disposes this
+	* coordinator — the viewer silently lands back on live at the wrong moment
+	* with no code path to restore the pointer.
+	*/
+	get currentMode() {
+		return this.mode;
+	}
 	async handleControl(msg) {
 		switch (msg.t) {
 			case "playRecorded":
@@ -18941,6 +19464,9 @@ var TimelineSession = class {
 			case "scrubTo":
 				if (this.mode === "recorded") this.feeder?.scrubTo(msg.epoch);
 				break;
+			case "scrubAck":
+				if (this.mode === "recorded") this.feeder?.scrubAck();
+				break;
 			case "setRate":
 				this.feeder?.setRate(msg.rate);
 				break;
@@ -18948,6 +19474,7 @@ var TimelineSession = class {
 				if (this.mode === "recorded") this.feeder?.stepFrame(msg.dir);
 				break;
 			case "setProfile":
+				if (msg.profile === this.profile) break;
 				this.profile = msg.profile;
 				if (this.mode === "recorded") this.enterRecorded();
 				break;
@@ -25662,25 +26189,6 @@ async function extractSamples(segment, segmentStartMs) {
 		samples: collected
 	} : null;
 }
-/**
-* Demux a recorded LOW `.m4s` segment and return its sync samples plus the
-* WebCodecs decoder config, or null if the segment carries no video / no
-* decodable keyframe. `segmentStartMs` anchors keyframe timestamps to absolute
-* epoch ms; the first sample's cts is the zero reference.
-*/
-async function extractKeyframes(segment, segmentStartMs) {
-	const extracted = await extractSamples(segment, segmentStartMs);
-	if (!extracted) return null;
-	const keyframes = extracted.samples.filter((s) => s.isSync).map((s) => ({
-		ts: s.ts,
-		data: s.data
-	}));
-	return keyframes.length > 0 ? {
-		codec: extracted.codec,
-		description: extracted.description,
-		keyframes
-	} : null;
-}
 //#endregion
 //#region src/stream-broker/recorded/avcc-annexb.ts
 /**
@@ -26184,33 +26692,6 @@ var SEGMENT_DEMUX_FFMPEG_ARGS = [
 	"pipe:1"
 ];
 /**
-* ffmpeg arguments for the SCRUB keyframe-only demux: same crash-isolated
-* `-c:v copy` mpegts remux as {@link SEGMENT_DEMUX_FFMPEG_ARGS}, but `-frames:v 1`
-* stops after the FIRST output access unit — a recorded fragment is a single
-* IDR-led GOP, so frame 1 is the params-fused keyframe the scrub sub-mode needs
-* (it never renders a delta frame). This reliably yields exactly the IDR with
-* its VPS/SPS/PPS fused, whereas input-side `-discard nokey` is a no-op over the
-* `pipe:0` fragmented-mp4 demuxer (empirically kept 39/40 packets). Exported for
-* the spec.
-*/
-var SEGMENT_DEMUX_SCRUB_FFMPEG_ARGS = [
-	"-hide_banner",
-	"-loglevel",
-	"error",
-	"-i",
-	"pipe:0",
-	"-map",
-	"0:v:0",
-	"-frames:v",
-	"1",
-	"-c:v",
-	"copy",
-	"-an",
-	"-f",
-	"mpegts",
-	"pipe:1"
-];
-/**
 * Demux a self-contained H.264 or H.265 `.m4s` fragment into ordered Annex-B
 * access units.
 *
@@ -26236,113 +26717,35 @@ async function demuxSegmentToAnnexB(bytes, ffmpegPath = "ffmpeg") {
 		codec
 	}));
 }
-/**
-* Keyframe-only demux for the feeder-scrub sub-mode: remux with `-frames:v 1`
-* (single-GOP fragment ⇒ the one IDR) and return ONLY keyframe access units.
-* The scrub path never renders delta frames — it always pushes the nearest
-* keyframe ≤ the drag target — so extracting only the IDR keeps the per-session
-* scrub fragment cache tiny (one AU/fragment instead of the full ~40) with no
-* loss of scrub fidelity.
-*
-* Wall time per fragment is dominated by the ffmpeg subprocess spawn, so this is
-* NOT meaningfully faster per fragment than {@link demuxSegmentToAnnexB}; the
-* frequency win comes from the feeder's fragment cache + direction-aware
-* prefetch (which eliminate / overlap the demux), for which this compact
-* keyframe-only payload is the cache unit.
-*
-* Defensive parse-side filter: keeps `keyframe` AUs, falling back to the first
-* AU (the demux contract's params-fused IDR) if none were flagged, so the result
-* is keyframes-only yet never empty for a valid fragment.
-*
-* @param bytes - The full `.m4s` fragment (one moov + one IDR-led GOP).
-* @param ffmpegPath - ffmpeg binary path (defaults to PATH `ffmpeg`).
-*/
-async function demuxSegmentKeyframesToAnnexB(bytes, ffmpegPath = "ffmpeg") {
-	const { codec, accessUnits } = demuxMpegTsToAnnexB(await runFfmpegOnce({
-		ffmpegPath,
-		args: SEGMENT_DEMUX_SCRUB_FFMPEG_ARGS,
-		input: bytes
-	}));
-	const mapped = accessUnits.map((au) => ({
-		data: au.data,
-		ptsMs: au.ptsMs,
-		keyframe: au.keyframe,
-		codec
-	}));
-	const keyframes = mapped.filter((au) => au.keyframe);
-	return keyframes.length > 0 ? keyframes : mapped.slice(0, 1);
-}
 //#endregion
 //#region src/stream-broker/recorded/segment-demux-js.ts
 /**
 * segment-demux-js — PURE-JS in-process demux for recorded playback.
 *
-* Two flavours, both replacing a per-fragment ffmpeg spawn with an mp4box parse:
-*   - {@link demuxSegmentKeyframesJs} / {@link demuxSegmentKeyframesPreferJs} —
-*     KEYFRAME-only, for the feeder-scrub sub-mode.
-*   - {@link demuxSegmentFullJs} / {@link demuxSegmentPreferJs} — FULL playback
-*     (every access unit, sync + delta), the drop-in for `RecordedFeederDeps.demux`.
+* {@link demuxSegmentFullJs} / {@link demuxSegmentPreferJs} — FULL playback
+* (every access unit, sync + delta), the drop-in for `RecordedFeederDeps.demux`.
+* Both playback AND scrub demux through this since sweep mode (the scrub train
+* pushes predicted frames, so the whole GOP is needed either way).
 *
-* Replaces the per-fragment ffmpeg spawn ({@link demuxSegmentKeyframesToAnnexB},
-* a ~140 ms subprocess floor) with an in-process mp4box parse. A recorded `.m4s`
+* Replaces the per-fragment ffmpeg spawn (a ~140 ms subprocess floor) with an
+* in-process mp4box parse. A recorded `.m4s`
 * is a self-contained fragment (`+frag_keyframe+empty_moov+default_base_moof`)
 * carrying its own `moov`, so its `avcC`/`hvcC` parameter sets and its sync
 * sample(s) are all in the bytes we already hold — no init segment to fetch.
 *
-* Flow: reuse {@link extractKeyframes} (the proven mp4box sync-sample demux the
-* recorder scrub module already ships — box parsing is NOT duplicated here) to get
-* the codec `description` + length-prefixed sync samples, then
-* {@link buildKeyframeAnnexB} converts each to a standalone-decodable Annex-B
-* access unit with the parameter sets fused on. The result matches the
-* {@link AccessUnit} contract the ffmpeg path produces: `codec` H264|H265,
-* `keyframe:true`, and `ptsMs` segment-relative (offset from the first sync
-* sample — the only thing the feeder reads, via `au.ptsMs - first.ptsMs`).
-*
-* Anchoring `extractKeyframes(bytes, 0)` makes the first sync sample's `ts` = 0,
-* so `ptsMs` is a plain segment-relative offset in ms, exactly like the ffmpeg
-* demux's PES-derived deltas — `clampIntoSegment`/position reporting are
-* unaffected.
+* Flow: {@link extractSamples} (the proven mp4box demux the recorder scrub
+* module already ships — box parsing is NOT duplicated here) yields the codec
+* `description` + length-prefixed samples; sync samples are fused with their
+* parameter sets ({@link buildKeyframeAnnexB}), delta samples converted plain
+* ({@link avccSampleToAnnexB}). `ptsMs` is segment-relative (anchored to 0 at
+* the first sample), exactly like the ffmpeg demux's PES-derived deltas —
+* `clampIntoSegment`/position reporting are unaffected.
 */
 /** True for a WebCodecs codec string that is HEVC (`hvc1.`/`hev1.`), else H.264. */
 function isHevcCodec(codec) {
 	return /^h[ev][vc]1\./i.test(codec);
 }
 /**
-* Pure-JS keyframe-only demux of one self-contained `.m4s` fragment. Returns the
-* fragment's sync-sample access unit(s) as params-fused Annex-B, or `null` if
-* mp4box found no video / no decodable keyframe (caller falls back to ffmpeg).
-* Throws only on a genuinely malformed decoder config / sample — the wrapper
-* ({@link demuxSegmentKeyframesPreferJs}) turns that into an ffmpeg fallback.
-*/
-async function demuxSegmentKeyframesJs(bytes) {
-	const extracted = await extractKeyframes(bytes, 0);
-	if (!extracted || extracted.keyframes.length === 0) return null;
-	const isHevc = isHevcCodec(extracted.codec);
-	const codec = isHevc ? "H265" : "H264";
-	return extracted.keyframes.slice(0, 1).map((k) => ({
-		data: buildKeyframeAnnexB(k.data, extracted.description, isHevc),
-		ptsMs: k.ts,
-		keyframe: true,
-		codec
-	}));
-}
-/**
-* Feeder-scrub demux: try the pure-JS keyframe extractor first, fall back to the
-* ffmpeg spawn ({@link demuxSegmentKeyframesToAnnexB}) if the JS parse yields no
-* keyframe or throws on malformed bytes. Preserves the exact {@link AccessUnit}
-* contract either way, so it is a drop-in for `RecordedFeederDeps.demuxScrub`.
-*/
-async function demuxSegmentKeyframesPreferJs(bytes, opts = {}) {
-	try {
-		const js = await demuxSegmentKeyframesJs(bytes);
-		if (js && js.length > 0) return js;
-		opts.onFfmpegFallback?.("mp4box parse found no keyframe");
-	} catch (err) {
-		opts.onFfmpegFallback?.(`mp4box parse threw: ${String(err)}`);
-	}
-	return demuxSegmentKeyframesToAnnexB(bytes, opts.ffmpegPath);
-}
-/**
 * Pure-JS FULL-playback demux of one self-contained `.m4s` fragment: return
 * EVERY access unit (sync + delta) as params-fused Annex-B with segment-relative
 * `ptsMs`, matching the {@link AccessUnit} contract of {@link demuxSegmentToAnnexB}
@@ -26651,7 +27054,8 @@ var ADAPTIVE_CONFIG = {
 	minFailPercent: .05,
 	waitAfterResetMs: 8e3,
 	upgradeHealthyMs: 6e4,
-	minTimeBetweenChangesMs: 6e4
+	minTimeBetweenChangesMs: 6e4,
+	maxUpgradeBackoffMs: 9e5
 };
 /**
 * True when `broker` is an in-process StreamBroker exposing the Opus egress
@@ -26837,6 +27241,24 @@ var BrokerWebrtcServer = class {
 	/** brokerId → IStreamBroker reference. Set by the broker manager on registration. */
 	brokers = /* @__PURE__ */ new Map();
 	/**
+	* Post-session warmth: when the LAST WebRTC session on a broker closes, a
+	* ghost subscription keeps the source dialed and its RTP ring warm for the
+	* linger window, so the dominant remote pattern — reopen within minutes —
+	* reconnects with an instant-start GOP replay instead of re-paying the
+	* cold dial + next-IDR wait. `kind:'warmup'` reuses the existing consumer
+	* attribution enum; the label answers "who keeps cam X warm?" in the
+	* operator widget.
+	*/
+	brokerLinger = new BrokerLingerRegistry({ subscribe: (brokerId) => {
+		const broker = this.brokers.get(brokerId);
+		if (!broker) return null;
+		return broker.onEncodedData(() => {}, {
+			kind: "warmup",
+			label: "webrtc-linger",
+			media: "both"
+		});
+	} });
+	/**
 	* Resolves a brokerId to its current profile tier (`CamProfile`)
 	* via the manager's `assignments` map, or `null` for brokers that
 	* are only kept alive by a manual activation. Injected by the
@@ -26999,16 +27421,20 @@ var BrokerWebrtcServer = class {
 	* RTC controller / Alexa handler closes the session the same way.
 	*/
 	async handleOffer(streamId, clientOfferSdp, hints = {}, opts = {}) {
+		const offerStart = Date.now();
 		const setup = await this.setupSessionForBroker(streamId, hints, {
 			...opts,
 			clientOfferSdp
 		});
+		const setupMs = Date.now() - offerStart;
 		try {
 			if (opts.relayOnly === true) setup.session.setForceRelayOnly(true);
+			const negotiateStart = Date.now();
 			const answer = await setup.session.handleOffer({
 				sdp: clientOfferSdp,
 				type: "offer"
 			}, { nonTrickle: opts.nonTrickle === true });
+			const negotiateMs = Date.now() - negotiateStart;
 			setup.sessionLogger.info("WebRTC session created (client-offer)", { meta: {
 				sessionId: setup.sessionId,
 				deviceId: setup.deviceId,
@@ -27016,7 +27442,11 @@ var BrokerWebrtcServer = class {
 				iceServers: setup.iceServerCount,
 				codec: setup.sessionCodec,
 				useRtpRepacketizer: setup.useRtpRepacketizer,
-				relayOnly: opts.relayOnly === true
+				relayOnly: opts.relayOnly === true,
+				setupMs,
+				negotiateMs,
+				totalMs: Date.now() - offerStart,
+				...setup.setupTimings
 			} });
 			return {
 				sessionId: setup.sessionId,
@@ -27043,6 +27473,11 @@ var BrokerWebrtcServer = class {
 	*/
 	async setupSessionForBroker(streamId, hints, opts) {
 		if (this.stopped) throw new Error("Server stopped");
+		const setupStart = Date.now();
+		let ensureTierMs = 0;
+		let warmUpMs = 0;
+		let iceResolveMs = 0;
+		let hwAccelMs = 0;
 		const isAdaptiveStream = streamId.endsWith("/adaptive");
 		const intent = isAdaptiveStream && opts.sessionId !== void 0 ? this.adaptiveIntent.get(opts.sessionId) : void 0;
 		const resolveHints = intent !== void 0 ? {
@@ -27052,10 +27487,13 @@ var BrokerWebrtcServer = class {
 		if (isAdaptiveStream) {
 			const adaptiveDeviceId = deviceIdFromBrokerId(streamId);
 			const desiredTier = resolveHints.prefersTier === "high" || resolveHints.prefersTier === "mid" || resolveHints.prefersTier === "low" ? resolveHints.prefersTier : "high";
+			const ensureTierStart = Date.now();
 			try {
 				await this.ensureAdaptiveTierBroker?.(adaptiveDeviceId, desiredTier);
 			} catch (err) {
 				throw new Error(`Failed to ensure remote adaptive-tier broker for stream "${streamId}" (tier: ${desiredTier}): ${errMsg(err)}`);
+			} finally {
+				ensureTierMs = Date.now() - ensureTierStart;
 			}
 		}
 		const brokerId = this.resolveBrokerId(streamId, resolveHints);
@@ -27077,6 +27515,7 @@ var BrokerWebrtcServer = class {
 				kind: "warmup",
 				media: "both"
 			});
+			const warmUpStart = Date.now();
 			await new Promise((resolve) => {
 				const timer = setTimeout(() => {
 					sessionLogger.warn("broker SDP wait timed out — falling back to default codec", { meta: {
@@ -27092,9 +27531,11 @@ var BrokerWebrtcServer = class {
 					resolve();
 				});
 			});
+			warmUpMs = Date.now() - warmUpStart;
 			sessionLogger.info("broker warm-up complete", { meta: {
 				brokerId,
-				detectedCodec: broker.getStats().codec ?? null
+				detectedCodec: broker.getStats().codec ?? null,
+				waitedMs: warmUpMs
 			} });
 		}
 		const brokerCodec = broker.getStats().codec ?? "h264";
@@ -27278,6 +27719,7 @@ var BrokerWebrtcServer = class {
 			}
 		}, annexbAttribution);
 		warmUpUnsubscribe?.();
+		this.brokerLinger.cancel(brokerId);
 		const preBuffer = broker.getPreBuffer();
 		const preParamNals = stickyParamSets ? [Buffer.from(stickyParamSets)] : pendingParamNals.length > 0 ? pendingParamNals.map((b) => Buffer.from(b)) : [];
 		for (const pkt of preBuffer) if (pkt.type === "video") {
@@ -27304,7 +27746,9 @@ var BrokerWebrtcServer = class {
 				}
 			});
 		}
+		const iceResolveStart = Date.now();
 		const allIceServers = await this.resolveIceServers();
+		iceResolveMs = Date.now() - iceResolveStart;
 		const iceServers = opts.disableTurn === true ? allIceServers.map((entry) => {
 			const stunOnly = (Array.isArray(entry.urls) ? entry.urls : [entry.urls]).filter((u) => !u.startsWith("turn:") && !u.startsWith("turns:"));
 			if (stunOnly.length === 0) return null;
@@ -27329,13 +27773,16 @@ var BrokerWebrtcServer = class {
 			sourceProfileLevelId,
 			offeredProfileLevelIds
 		} });
+		const hwAccelStart = Date.now();
+		const transcodeDecodeHwAccel = await this.getTranscodeDecodeHwAccel();
+		hwAccelMs = Date.now() - hwAccelStart;
 		session = new AdaptiveSession({
 			sessionId,
 			source,
 			sourceCodec: sessionCodec,
 			transcodeToBaseline,
 			transcodeProfile: effectiveTranscodeProfile,
-			transcodeDecodeHwAccel: await this.getTranscodeDecodeHwAccel(),
+			transcodeDecodeHwAccel,
 			resolveTranscodeSourceUrl: () => this.sourceRestreamUrlResolver?.(brokerId) ?? null,
 			iceConfig: {
 				iceServers,
@@ -27447,7 +27894,6 @@ var BrokerWebrtcServer = class {
 		const locateRecorded = this.locateRecordedSegment;
 		const readRecorded = this.readRecordedSegmentBytes;
 		const resolveFfmpeg = this.resolveFfmpegPath;
-		let scrubJsFallbackLogged = false;
 		let fullJsFallbackLogged = false;
 		let audioOpusFallbackLogged = false;
 		if (locateRecorded && readRecorded) {
@@ -27475,19 +27921,6 @@ var BrokerWebrtcServer = class {
 								} });
 							}
 						}),
-						demuxScrub: (b) => demuxSegmentKeyframesPreferJs(b, {
-							ffmpegPath: resolveFfmpeg?.(),
-							onFfmpegFallback: (reason) => {
-								if (scrubJsFallbackLogged) return;
-								scrubJsFallbackLogged = true;
-								sessionLogger.warn("recorded scrub: JS keyframe demux failed — ffmpeg fallback (once/session)", { meta: {
-									sessionId,
-									deviceId,
-									profile,
-									reason
-								} });
-							}
-						}),
 						demuxAudio: opusSession ? async (b) => {
 							return (await demuxSegmentAudioOpusPreferJs(b, {
 								ffmpegPath: resolveFfmpeg?.(),
@@ -27523,10 +27956,17 @@ var BrokerWebrtcServer = class {
 							} });
 							timeline._emitState(s);
 						},
-						onPosition: (epochMs) => timeline._emitPosition(epochMs)
+						onPosition: (epochMs) => timeline._emitPosition(epochMs),
+						onLog: (msg, data) => sessionLogger.info(msg, { meta: {
+							sessionId,
+							deviceId,
+							profile,
+							...data
+						} })
 					});
 				}
 			});
+			entry.timeline = timeline;
 			sessionLogger.info("recorded: TimelineSession wired (control accessors present)", { meta: {
 				sessionId,
 				deviceId
@@ -27576,7 +28016,7 @@ var BrokerWebrtcServer = class {
 		};
 		if (streamId.endsWith("/adaptive")) {
 			const initialTier = this.profileTierResolver?.(brokerId) ?? "high";
-			this.startAdaptive(entry, deviceId, initialTier, sessionId);
+			this.startAdaptive(entry, deviceId, initialTier, sessionId, intent?.failures);
 		}
 		return {
 			sessionId,
@@ -27586,7 +28026,14 @@ var BrokerWebrtcServer = class {
 			brokerId,
 			sessionCodec,
 			useRtpRepacketizer,
-			iceServerCount: iceServers.length
+			iceServerCount: iceServers.length,
+			setupTimings: {
+				setupTotalMs: Date.now() - setupStart,
+				ensureTierMs,
+				warmUpMs,
+				iceResolveMs,
+				hwAccelMs
+			}
 		};
 	}
 	async handleAnswer(sessionId, sdpAnswer) {
@@ -27636,6 +28083,7 @@ var BrokerWebrtcServer = class {
 	async stop() {
 		if (this.stopped) return;
 		this.stopped = true;
+		this.brokerLinger.stop();
 		const closes = [];
 		for (const [sid, entry] of this.sessions) {
 			this.cleanupSession(sid);
@@ -27670,9 +28118,10 @@ var BrokerWebrtcServer = class {
 	* whichever produces the higher loss ratio across its window. The async
 	* poll is guarded against overlapping ticks via `tickInFlight`.
 	*/
-	startAdaptive(entry, deviceId, initialTier, sessionId) {
+	startAdaptive(entry, deviceId, initialTier, sessionId, priorFailures) {
 		const controller = new AdaptiveController({
 			initialTier,
+			priorFailures,
 			config: ADAPTIVE_CONFIG,
 			onSwitchTier: (tier) => {
 				this.switchSessionTier(entry, deviceId, tier, sessionId);
@@ -27692,6 +28141,10 @@ var BrokerWebrtcServer = class {
 			tickInFlight = true;
 			(async () => {
 				try {
+					if (entry.timeline?.currentMode === "recorded") {
+						controller.suspend(Date.now());
+						return;
+					}
 					const pct = this.clientLossPct ? await this.clientLossPct(deviceId) : null;
 					const now = Date.now();
 					if (pct !== null && pct !== void 0 && pct > 0) {
@@ -27723,9 +28176,11 @@ var BrokerWebrtcServer = class {
 	*/
 	switchSessionTier(entry, deviceId, tier, sessionId, forceTranscodeDown = false) {
 		const prev = this.adaptiveIntent.get(sessionId);
+		const failures = new Map(entry.adaptiveController?.failureCounts ?? prev?.failures);
 		this.adaptiveIntent.set(sessionId, {
 			prefersTier: tier,
-			forceTranscodeDown: forceTranscodeDown || (prev?.forceTranscodeDown ?? false)
+			forceTranscodeDown: forceTranscodeDown || (prev?.forceTranscodeDown ?? false),
+			failures
 		});
 		const epoch = (entry.session.pendingRenegotiation?.epoch ?? 0) + 1;
 		entry.session.pendingRenegotiation = {
@@ -27739,7 +28194,8 @@ var BrokerWebrtcServer = class {
 				deviceId,
 				tier,
 				forceTranscodeDown,
-				epoch
+				epoch,
+				failures: Object.fromEntries(failures)
 			}
 		});
 	}
@@ -27747,6 +28203,12 @@ var BrokerWebrtcServer = class {
 		const entry = this.sessions.get(sessionId);
 		if (!entry) return;
 		this.sessions.delete(sessionId);
+		let brokerStillServed = false;
+		for (const other of this.sessions.values()) if (other.brokerId === entry.brokerId) {
+			brokerStillServed = true;
+			break;
+		}
+		if (!brokerStillServed && !this.stopped) this.brokerLinger.hold(entry.brokerId);
 		this.adaptiveIntent.delete(sessionId);
 		if (entry.adaptiveTimer) clearInterval(entry.adaptiveTimer);
 		if (entry.attributionTimer) clearTimeout(entry.attributionTimer);
@@ -28330,6 +28792,42 @@ var WebrtcSessionProvider = class WebrtcSessionProvider {
 	}
 };
 //#endregion
+//#region src/stream-broker/event-loop-stall-monitor.ts
+var DEFAULT_INTERVAL_MS = 100;
+var DEFAULT_THRESHOLD_MS = 250;
+var EventLoopStallMonitor = class {
+	intervalMs;
+	thresholdMs;
+	now;
+	onStall;
+	timer = null;
+	lastTickAt = 0;
+	constructor(options) {
+		this.intervalMs = options.intervalMs ?? DEFAULT_INTERVAL_MS;
+		this.thresholdMs = options.thresholdMs ?? DEFAULT_THRESHOLD_MS;
+		this.now = options.now ?? (() => Date.now());
+		this.onStall = options.onStall;
+	}
+	start() {
+		if (this.timer) return;
+		this.lastTickAt = this.now();
+		this.timer = setInterval(() => {
+			const at = this.now();
+			const lateMs = at - this.lastTickAt - this.intervalMs;
+			this.lastTickAt = at;
+			if (lateMs >= this.thresholdMs) try {
+				this.onStall(lateMs);
+			} catch {}
+		}, this.intervalMs);
+		this.timer.unref?.();
+	}
+	stop() {
+		if (!this.timer) return;
+		clearInterval(this.timer);
+		this.timer = null;
+	}
+};
+//#endregion
 //#region src/stream-broker/addon.ts
 /**
 * Hydrate the persisted RTSP restream state (`rtspTokens` / `rtspEnabled`)
@@ -28422,6 +28920,8 @@ var StreamBrokerAddon = class extends BaseAddon {
 	webrtcServer = null;
 	/** Handle for the embed SPA data-plane listener (disposed on shutdown). */
 	embedDataPlane = null;
+	/** Names this process's event-loop stalls — see onInitialize. */
+	loopStallMonitor = null;
 	/**
 	* Snapshot-equality cache for the broker-metrics emit. Each
 	* broker emits a stats snapshot every BROKER_METRICS_SNAPSHOT_-
@@ -28522,6 +29022,10 @@ var StreamBrokerAddon = class extends BaseAddon {
 		}
 	}
 	async onInitialize() {
+		this.loopStallMonitor = new EventLoopStallMonitor({ onStall: (stallMs) => {
+			this.ctx?.logger?.warn?.("event-loop stall — every session in this process froze", { meta: { stallMs } });
+		} });
+		this.loopStallMonitor.start();
 		this.brokerManager = new StreamBrokerManager(void 0, this.ctx.logger);
 		this.brokerManager.setDefaultPreBufferSec(this.config.defaultPreBufferSec);
 		this.brokerManager.setEventBus(this.ctx.eventBus);
@@ -28864,6 +29368,8 @@ var StreamBrokerAddon = class extends BaseAddon {
 		];
 	}
 	async onShutdown() {
+		this.loopStallMonitor?.stop();
+		this.loopStallMonitor = null;
 		this.flushProbeSnapshots(Date.now(), true);
 		if (this.metricsSnapshotTimer) {
 			clearInterval(this.metricsSnapshotTimer);