@camstack/addon-pipeline 1.2.102 → 1.2.104

package/dist/stream-broker/index.mjs

@@ -1,6 +1,7 @@
 import { r as __toESM, t as __commonJSMin } from "../chunk-DnnnRqeS.mjs";
-import { A as batteryCapability, At as array, B as egressTranscodeSharingKey, Bt as EventCategory, Ct as makeSourceBrokerId, E as addonWidgetsSourceCapability, Et as parseProfileBrokerId, Ft as number, I as deriveBatteryPresence, It as object, K as maskUrlCredentials, Lt as record, M as createHwAccelCache, Mt as discriminatedUnion, Pt as literal, Rt as string, St as makeProfileBrokerId, V as egressTransportFromRequest, _t as DeviceFeature, b as RATE_CONTROL_RELAXED, ct as webrtcSessionCapability, dt as Fmp4BoxSplitter, ft as buildFfmpegArgs$1, gt as CAM_PROFILE_ORDER, ht as BaseAddon, i as BatteryStatusSchema, j as cameraStreamsCapability, jt as boolean, kt as _enum, lt as errMsg, mt as isSoftwareDecode, ot as streamBrokerCapability, p as EncodeProfileSchema, pt as invocationFromEncodeProfile, tt as resolveEgressDecodeHwAccel, ut as AUDIO_PRESETS, vt as DeviceType, w as RingBuffer, wt as nodePin, x as RATE_CONTROL_TIGHT, xt as isEvent, yt as createEvent, zt as union } from "../dist-Ccmt3fGJ.mjs";
-import { n as profileForStreamId, r as parseRestreamPath } from "../remote-restream-Ci7RXNGb.mjs";
+import { Bt as record, D as addonWidgetsSourceCapability, Dt as nodePin, Et as makeSourceBrokerId, Ft as discriminatedUnion, H as egressTransportFromRequest, Ht as union, L as deriveBatteryPresence, Lt as literal, M as cameraStreamsCapability, Mt as _enum, N as createHwAccelCache, Nt as array, Pt as boolean, Rt as number, S as RATE_CONTROL_TIGHT, St as createEvent, T as RingBuffer, Tt as makeProfileBrokerId, Ut as EventCategory, V as egressTranscodeSharingKey, Vt as string, _t as isSoftwareDecode, bt as DeviceFeature, dt as webrtcSessionCapability, ft as errMsg, gt as invocationFromEncodeProfile, ht as buildFfmpegArgs$1, i as BatteryStatusSchema, it as resolveEgressDecodeHwAccel, j as batteryCapability, kt as parseProfileBrokerId, lt as streamBrokerCapability, m as EncodeProfileSchema, mt as Fmp4BoxSplitter, pt as AUDIO_PRESETS, q as maskUrlCredentials, vt as BaseAddon, wt as isEvent, x as RATE_CONTROL_RELAXED, xt as DeviceType, yt as CAM_PROFILE_ORDER, zt as object } from "../dist-D9sltFoR.mjs";
+import { t as parseRestreamPath } from "../restream-intent-B4BXZra7.mjs";
+import { n as profileForStreamId } from "../remote-restream-BeHi78PZ.mjs";
 import { n as RowMapStore, t as retireRootKeys } from "../retire-root-keys-DMolfhsP.mjs";
 import { createRequire } from "node:module";
 import * as crypto$1 from "node:crypto";
@@ -1428,6 +1429,35 @@ var TS_COPYABLE_AUDIO_CODECS = new Set(["aac"]);
 * neither gopFrames nor fps. Matches BASE_LIVE_EGRESS_PROFILE's intent.
 */
 var DERIVED_DEFAULT_GOP_FRAMES = 25;
+/**
+* No B-frames, ever, unless the profile asks for them by name.
+*
+* A derived stream's carrier is MPEG-TS → {@link MpegTsDemux} → the broker →
+* RTP (an RTSP restream to the recorder, a WebRTC leg to a viewer). Every hop
+* has to carry the reorder delay and RTP has no field for it at all — so
+* reordering costs latency on the whole chain and buys compression nobody
+* asked for at 640x360.
+*/
+var DERIVED_DEFAULT_BF = 0;
+/**
+* The encode preset and tune the carrier pins when the profile names neither.
+*
+* `veryfast` + `zerolatency` is `BASE_LIVE_EGRESS_PROFILE`'s pairing, and it is
+* the pairing that removes x264's lookahead: `preset medium` carries
+* `rc-lookahead=40`, which at 25 fps is 1.6 SECONDS the encoder holds before it
+* emits anything. See this module's `withCarrierDefaults` for the measurement.
+*/
+var DERIVED_DEFAULT_PRESET = "veryfast";
+var DERIVED_DEFAULT_TUNE = "zerolatency";
+/**
+* The bit density a derived tier is capped at, expressed as the shared
+* live-egress profile it is scaled from: `BASE_LIVE_EGRESS_PROFILE` spends
+* 2500 kbps on 1280x720 at 25 fps. Scaling that per pixel-per-second gives
+* 625 kbps at 640x360@25 — and a 10 s segment of 625 kbps is ~780 KB, half of
+* the scrub's 1.5 MB whole-segment ceiling (D163).
+*/
+var DERIVED_BITRATE_REFERENCE_KBPS = 2500;
+var DERIVED_BITRATE_REFERENCE_PIXELS_PER_SECOND = 1280 * 720 * 25;
 var DERIVED_AAC_RECODE = {
 	codec: "aac",
 	channels: 1
@@ -1481,12 +1511,66 @@ function resolveDerivedAudio(profileAudio, sourceAudioCodec) {
 *   own — the MPEG-TS carrier, not the operator, decides whether the source
 *   track can be copied.
 */
+/**
+* The rate ceiling for a geometry, or `undefined` when the profile named no
+* geometry to scale by (there is then nothing to derive a number from, and a
+* guessed cap on an unknown resolution is worse than none).
+*/
+function derivedBitrateCeilingKbps(video) {
+	const { width, height } = video;
+	if (width === void 0 || height === void 0) return void 0;
+	const pixelsPerSecond = width * height * (video.fps ?? DERIVED_DEFAULT_GOP_FRAMES);
+	return Math.round(DERIVED_BITRATE_REFERENCE_KBPS * pixelsPerSecond / DERIVED_BITRATE_REFERENCE_PIXELS_PER_SECOND);
+}
+/**
+* Fill the encode knobs the CARRIER owns, leaving every one the profile names
+* untouched. Same rule as the audio decision above: an operator states intent,
+* the carrier states what its own hops can survive.
+*
+* - **GOP.** x264's own default is keyint=250 — TEN seconds at the fleet's
+*   25 fps. Measured live (camera dispensa, 2026-08-19): 1 I-frame in 250 on a
+*   recorded low segment, and a WebRTC viewer joining mid-GOP decoded
+*   reference-less P-frames for up to 10 s — the smear artifacts on every live
+*   open of a derived tier, grid tiles included.
+*
+* - **B-frames, preset, tune.** Measured live (camera 1438, 2026-08-20) by
+*   reading the camera's burnt-in OSD out of RECORDED segments and comparing
+*   it against the wall clock the recorder named the file with. Same camera,
+*   so the same OSD clock; mid-roll samples only, because the first segment of
+*   a triggered roll carries pre-roll and is older than its own name:
+*
+*     native `high` (-c:v copy):  -1s  -1s  -1s  -2s
+*     derived `low` (transcode):  -3s  -3s  -3s  -3s
+*
+*   ~2 s, and it is the encoder holding frames back: `preset medium` carries
+*   `rc-lookahead=40` (1.6 s at 25 fps) on top of `bframes=3` with b-adapt and
+*   b-pyramid. The recorder stamps a segment with the wall clock at WRITE
+*   time, so all of it becomes a MISLABEL: seeking a derived tier to an
+*   event's timestamp lands ~2 s past the event while the native tier of the
+*   same camera lands on it.
+*
+* - **Bitrate.** A CEILING (`-maxrate`, no `-b:v` — see `buildRateControlArgs`,
+*   whose default rate control is `cap`), because a derived tier is RECORDED
+*   and the scrub reads a `low` segment whole only while it is under 1.5 MB
+*   (D163). Uncapped CRF has no relationship to that ceiling: 1438/low
+*   measured 537–941 kbps at 640x360@25 against 142 kbps for camera 615's
+*   NATIVE low at the identical geometry, peaking at 1.19 MB in a 10 s
+*   segment. Quiet scenes still spend less than the cap.
+*/
+function withCarrierDefaults(video) {
+	const bitrateKbps = video.bitrateKbps ?? derivedBitrateCeilingKbps(video);
+	return {
+		...video,
+		gopFrames: video.gopFrames ?? video.fps ?? DERIVED_DEFAULT_GOP_FRAMES,
+		bf: video.bf ?? DERIVED_DEFAULT_BF,
+		preset: video.preset ?? DERIVED_DEFAULT_PRESET,
+		tune: video.tune ?? DERIVED_DEFAULT_TUNE,
+		...bitrateKbps !== void 0 ? { bitrateKbps } : {}
+	};
+}
 function buildDerivedTranscodeArgs(input) {
 	const audio = resolveDerivedAudio(input.profile.audio, input.sourceAudioCodec);
-	const video = input.profile.video.gopFrames !== void 0 ? input.profile.video : {
-		...input.profile.video,
-		gopFrames: input.profile.video.fps ?? DERIVED_DEFAULT_GOP_FRAMES
-	};
+	const video = withCarrierDefaults(input.profile.video);
 	return {
 		args: buildFfmpegArgs$1(invocationFromEncodeProfile({
 			profile: {
@@ -1552,11 +1636,34 @@ var NOTHING = {
 	ageMs: 0,
 	gopsBack: 0
 };
-/** A configured pre-roll in ms, or `0` when the input carries no instruction. */
-function usablePreRoll(value) {
+/**
+* A configured pre-roll in ms, or `0` when the input carries no instruction.
+*
+* `maxMs` is the ceiling of the WINDOW being resolved: detection's
+* ({@link PRE_ROLL_MAX_MS}) bounds a decoder's drain, recording's
+* ({@link RECORDING_PRE_ROLL_MAX_MS}) bounds the recorder's keep gate. One
+* clamp for both so a new window cannot arrive with its own rounding rules.
+*/
+function clampPreRoll(value, maxMs) {
 	if (value === void 0) return 0;
 	if (!Number.isFinite(value) || value <= 0) return 0;
-	return Math.min(PRE_ROLL_MAX_MS, Math.max(250, value));
+	return Math.min(maxMs, Math.max(250, value));
+}
+/**
+* {@link clampPreRoll} at the WIDEST ceiling any window in this system may
+* carry.
+*
+* Used by the three functions that operate on a window ALREADY resolved by
+* `resolvePreRollMs` / `resolveRecordingPreRollMs` — the selection, the packet
+* ceiling and the span bound. Clamping those at the DETECTION ceiling was
+* correct while there was one window and became a silent 6 s truncation of
+* every recording burst the moment there were two: the selector would refuse
+* the keyframe the recorder asked for, and the span bound would withhold the
+* burst for being as wide as the operator configured — D192's failure, one
+* layer down.
+*/
+function usablePreRoll(value) {
+	return clampPreRoll(value, RECORDING_PRE_ROLL_MAX_MS);
 }
 /**
 * Choose the keyframe access unit a pre-roll burst starts at.
@@ -1594,6 +1701,104 @@ function selectPreRollStart(marks, preRollMs) {
 	};
 }
 /**
+* Ceiling for the RECORDING window.
+*
+* Wider than {@link PRE_ROLL_MAX_MS} because the two windows are bounded by
+* different things. Detection's ceiling is the backlog a decoder must drain
+* before it reaches the live edge — media the analyser pays for frame by frame.
+* A recorder drains nothing: ffmpeg copies the burst to disk. What bounds THIS
+* number is the recorder's retroactive keep window (`preBufferSec`), because
+* footage the broker hands the writer from before that bound is deleted by the
+* keep gate the moment it finalizes — the divergence D191/D192 exist to forbid.
+* `packages/addon-pipeline/src/recorder/addon/__tests__/band-decision.spec.ts`
+* fails if this is ever raised past the shipped keep window.
+*/
+var RECORDING_PRE_ROLL_MAX_MS = 15e3;
+/**
+* Shipped RECORDING pre-roll on a mains camera. Operator decision, 2026-08-20.
+*
+* Unlike detection's, this one ships ON. The audit of the same day measured the
+* reason: on camera 1438 the footage began AFTER the motion in 60 % of
+* episodes, because the writer is spawned at the trigger and ffmpeg's first
+* frame is at best the live edge. A recording feature whose media starts after
+* the event is not a tuning question.
+*/
+var DEFAULT_RECORDING_PRE_ROLL_MS = 1e4;
+/**
+* Budget when the broker has not measured a bitrate for this stream yet — the
+* historical flat cap, kept verbatim as the honest "we do not know".
+*
+* `bitrateKbps` is 0 for the first stats window after every dial and after
+* every reset, so this is the value in force exactly while the ring is filling
+* for the first time.
+*/
+var PRE_ROLL_UNKNOWN_BITRATE_BYTES = 8 * 1024 * 1024;
+/**
+* Absolute per-stream ceiling on retained pre-roll history.
+*
+* The bitrate-derived budget is what the window COSTS; this is the most any one
+* stream may spend regardless. 32 MiB is 4x the flat cap it replaces and covers
+* 15 s of a 16 Mbps stream with headroom; past it the operator has configured a
+* window this node cannot afford on that camera, and the broker says so rather
+* than delivering silently less (D192).
+*/
+var PRE_ROLL_ABSOLUTE_MAX_BYTES = 32 * 1024 * 1024;
+/**
+* Headroom over the OBSERVED mean bitrate.
+*
+* `BrokerStatsSchema.bitrateKbps` is a mean over the stats window; a GOP
+* carrying an IDR plus a scene change is well above it. Budgeting at exactly
+* the mean would drop the oldest GOP on every busy second, so the window would
+* be the one the operator asked for only while nothing moved — which is the
+* opposite of when it is needed.
+*/
+var PRE_ROLL_BITRATE_HEADROOM = 1.5;
+/**
+* The byte budget for the history a `windowMs` pre-roll needs on a stream
+* observed at `observedKbps`.
+*
+* Replaces a FLAT 8 MiB cap. That constant was a promise the feature could not
+* keep in either direction: above ~6.5 Mbps it silently truncated the window
+* (a 4K main stream asked for 10 s and got 6), and below it, it authorised a
+* doorbell at 512 kbps to hold 8 MiB — 16x what its own window weighs.
+*/
+function preRollBudgetBytes(windowMs, observedKbps) {
+	if (!Number.isFinite(windowMs) || windowMs <= 0) return {
+		bytes: 0,
+		clamped: false
+	};
+	if (!Number.isFinite(observedKbps) || observedKbps <= 0) return {
+		bytes: PRE_ROLL_UNKNOWN_BITRATE_BYTES,
+		clamped: false
+	};
+	const raw = Math.round(windowMs * observedKbps * PRE_ROLL_BITRATE_HEADROOM / 8);
+	if (raw > 33554432) return {
+		bytes: PRE_ROLL_ABSOLUTE_MAX_BYTES,
+		clamped: true
+	};
+	return {
+		bytes: raw,
+		clamped: false
+	};
+}
+/**
+* The RECORDING window a broker retains and serves to a `/recording` dial.
+*
+* Precedence: stream override -> battery / terminal relay (0) -> cluster
+* default -> {@link DEFAULT_RECORDING_PRE_ROLL_MS}. An override wins over the
+* battery rule on purpose: the rule is a DEFAULT about where retention is
+* wasted, and an operator who typed a number for that stream has answered the
+* question the default was guessing at.
+*/
+function resolveRecordingPreRollMs(input) {
+	const override = clampPreRoll(input.overrides?.[input.camStreamId], RECORDING_PRE_ROLL_MAX_MS);
+	if (override > 0) return override;
+	if (input.batteryOperated === true) return 0;
+	if (input.terminalRelay === true) return 0;
+	if (input.clusterMs === void 0) return DEFAULT_RECORDING_PRE_ROLL_MS;
+	return clampPreRoll(input.clusterMs, RECORDING_PRE_ROLL_MAX_MS);
+}
+/**
 * Combine the cluster default and the per-camera-stream override into the one
 * pre-roll a broker applies. Precedence: stream override → cluster default →
 * OFF. Each layer is validated independently, so a bad override falls back to a
@@ -1604,10 +1809,10 @@ function selectPreRollStart(marks, preRollMs) {
 * coincide on every unconfigured stream.
 */
 function resolvePreRollMs(input) {
-	const override = usablePreRoll(input.overrides?.[input.camStreamId]);
+	const override = clampPreRoll(input.overrides?.[input.camStreamId], PRE_ROLL_MAX_MS);
 	if (override > 0) return override;
 	if (input.terminalRelay === true) return 0;
-	return usablePreRoll(input.clusterMs);
+	return clampPreRoll(input.clusterMs, PRE_ROLL_MAX_MS);
 }
 /**
 * The packet ceiling for a burst carrying `preRollMs` of pre-roll.
@@ -2277,8 +2482,13 @@ var RtspRestreamer = class {
 	* A second supplier and not a widening of {@link rtpPreBufferSupplier},
 	* because the two feed different populations: that one is also the WebRTC
 	* bootstrap and every ordinary RTSP join, and handing them history is the
-	* D57 failure. Only a session that declared the detection intent on its dial
-	* path is served from this one.
+	* D57 failure. Only a session that DECLARED an intent on its dial path is
+	* served from this one.
+	*
+	* Takes the intent, because the two windows are two numbers (D193): a
+	* detection dial drains its backlog frame by frame and a recorder copies it
+	* to disk, so the operator sets them apart. One supplier keyed by intent, and
+	* not two suppliers, so a third intent cannot arrive with its own wiring.
 	*
 	* Pulled per join for the same reason as the bound: a broker outlives the
 	* setting.
@@ -2572,36 +2782,74 @@ var RtspRestreamer = class {
 			if (this.sessions.get(sessionId)?.isPlaying()) ready.push(sessionId);
 		}
 		if (ready.length === 0) return;
-		const preRoll = this.preRollSupplier?.();
-		const preRollPackets = fromRing && preRoll && preRoll.preRollMs > 0 && preRoll.packets.length > primePackets.length ? preRoll.packets.map((data) => ({
-			data,
-			marker: (data[1] & 128) !== 0
-		})) : [];
-		const preRollActive = preRollPackets.length > 0;
-		const preRollSpanMs = preRollActive ? (preRollPackets[preRollPackets.length - 1].data.readUInt32BE(4) - preRollPackets[0].data.readUInt32BE(4) | 0) / 90 : 0;
+		const preRollPlans = /* @__PURE__ */ new Map();
 		const bound = this.currentPrimeBound();
 		const overSpan = spanMs > bound.maxSpanMs;
 		const overPackets = primePackets.length > bound.maxPackets;
-		const preRollBound = preRollActive ? preRollSpanBound(bound, preRoll?.preRollMs ?? 0) : bound;
-		const preRollOverBound = preRollActive ? preRollSpanMs > preRollBound.maxSpanMs || preRollPackets.length > preRollBound.maxPackets : false;
+		/**
+		* Resolve (and memoize) the plan for one intent.
+		*
+		* The bound a PRE-ROLL burst is held to is D57's, widened to the pre-roll
+		* the operator configured FOR THAT INTENT, with the packet ceiling scaled
+		* by the same factor so the defensive backstop stays a rate. A window WIDER
+		* than that is still withheld — the selector cannot produce one, but a long
+		* current GOP or a supplier bug can, and D57's remedy (join clean at the
+		* next live keyframe) is the right one for a burst nobody asked for.
+		*/
+		const planFor = (intent) => {
+			const cached = preRollPlans.get(intent);
+			if (cached) return cached;
+			const burst = this.preRollSupplier?.(intent);
+			const window = fromRing && burst && burst.preRollMs > 0 ? burst.packets() : [];
+			const packets = window.length > primePackets.length ? window.map((data) => ({
+				data,
+				marker: (data[1] & 128) !== 0
+			})) : [];
+			const windowSpanMs = packets.length > 0 ? (packets[packets.length - 1].data.readUInt32BE(4) - packets[0].data.readUInt32BE(4) | 0) / 90 : 0;
+			const windowBound = packets.length > 0 ? preRollSpanBound(bound, burst?.preRollMs ?? 0) : bound;
+			const plan = {
+				packets,
+				active: packets.length > 0,
+				configuredMs: burst?.preRollMs ?? 0,
+				spanMs: windowSpanMs,
+				overBound: packets.length > 0 && (windowSpanMs > windowBound.maxSpanMs || packets.length > windowBound.maxPackets)
+			};
+			preRollPlans.set(intent, plan);
+			return plan;
+		};
 		const served = [];
-		const servedPreRoll = /* @__PURE__ */ new Set();
+		const servedPreRoll = /* @__PURE__ */ new Map();
 		let withheld = 0;
 		let detectionIntentServed = 0;
 		for (const sessionId of ready) {
 			const session = this.sessions.get(sessionId);
 			if (!session) continue;
 			const detectionIntent = session.isDetectionIntent();
-			if (detectionIntent && preRollActive) {
-				if (preRollOverBound) {
-					this.dropsWithheldSpan++;
-					withheld++;
+			const preRollIntent = session.preRollIntent();
+			if (preRollIntent !== null) {
+				const plan = planFor(preRollIntent);
+				if (plan.active) {
+					if (plan.overBound) {
+						this.dropsWithheldSpan++;
+						withheld++;
+						continue;
+					}
+					servedPreRoll.set(sessionId, preRollIntent);
+					served.push(sessionId);
+					this.logger?.info("restream pre-roll served", {
+						tags: { deviceId: this.deviceId },
+						meta: {
+							streamName: this.streamName,
+							sessionId,
+							intent: preRollIntent,
+							consumer: session.getUserAgent() ?? "unknown",
+							configuredMs: plan.configuredMs,
+							spanMs: Math.round(plan.spanMs),
+							packets: plan.packets.length
+						}
+					});
 					continue;
 				}
-				detectionIntentServed++;
-				servedPreRoll.add(sessionId);
-				served.push(sessionId);
-				continue;
 			}
 			if (session.isMuted() && !detectionIntent) {
 				if (!fromRing || spanMs > LIVE_EDGE_MAX_SPAN_MS) {
@@ -2620,6 +2868,11 @@ var RtspRestreamer = class {
 		}
 		if (withheld > 0) this.reportDrops(false);
 		if (served.length === 0) return;
+		/** Media actually delivered to this intent, or `-1` when none joined. */
+		const servedSpanMs = (intent) => {
+			const plan = preRollPlans.get(intent);
+			return plan === void 0 ? -1 : Math.round(plan.spanMs);
+		};
 		this.logger?.info("restream prime (lat-probe)", {
 			tags: { deviceId: this.deviceId },
 			meta: {
@@ -2632,9 +2885,10 @@ var RtspRestreamer = class {
 				boundPackets: bound.maxPackets,
 				withheld,
 				detectionIntentServed,
-				preRollMs: preRoll?.preRollMs ?? 0,
-				preRollSpanMs: preRollActive ? Math.round(preRollSpanMs) : 0,
-				preRollPackets: preRollPackets.length,
+				detectionPreRollMs: this.preRollSupplier?.("detection").preRollMs ?? 0,
+				recordingPreRollMs: this.preRollSupplier?.("recording").preRollMs ?? 0,
+				detectionPreRollSpanMs: servedSpanMs("detection"),
+				recordingPreRollSpanMs: servedSpanMs("recording"),
 				preRollServed: servedPreRoll.size
 			}
 		});
@@ -2643,14 +2897,16 @@ var RtspRestreamer = class {
 			prime: true,
 			keyframeAuStart: false
 		}));
-		const preRollItems = servedPreRoll.size > 0 ? preRollPackets.map((packet) => ({
+		const preRollItems = /* @__PURE__ */ new Map();
+		for (const intent of new Set(servedPreRoll.values())) preRollItems.set(intent, (preRollPlans.get(intent)?.packets ?? []).map((packet) => ({
 			packet,
 			prime: true,
 			keyframeAuStart: false
-		})) : [];
+		})));
 		for (const sessionId of served) {
 			this.pendingKeyframe.delete(sessionId);
-			this.startPrimeReplay(sessionId, servedPreRoll.has(sessionId) ? preRollItems : items);
+			const intent = servedPreRoll.get(sessionId);
+			this.startPrimeReplay(sessionId, intent ? preRollItems.get(intent) ?? items : items, intent ?? null);
 		}
 	}
 	/**
@@ -2663,7 +2919,7 @@ var RtspRestreamer = class {
 	* session that went away — aborts the whole replay rather than punching holes
 	* in the GOP: the session is left latched and rejoins at the next keyframe AU.
 	*/
-	startPrimeReplay(sessionId, items) {
+	startPrimeReplay(sessionId, items, preRollIntent) {
 		const replay = new PacedRtpReplay((item) => {
 			const session = this.sessions.get(sessionId);
 			if (!session) {
@@ -2679,6 +2935,20 @@ var RtspRestreamer = class {
 			return false;
 		}, (stats) => {
 			this.activeReplays.delete(sessionId);
+			if (preRollIntent !== null) this.logger?.info("restream pre-roll replay done", {
+				tags: { deviceId: this.deviceId },
+				meta: {
+					streamName: this.streamName,
+					sessionId,
+					intent: preRollIntent,
+					consumer: this.sessions.get(sessionId)?.getUserAgent() ?? "unknown",
+					packets: stats.packets,
+					sent: stats.sent,
+					aborted: stats.aborted,
+					enqueuedLive: stats.enqueuedLive,
+					durationMs: stats.durationMs
+				}
+			});
 			this.logger?.debug("restream prime drained", {
 				tags: { deviceId: this.deviceId },
 				meta: {
@@ -3027,6 +3297,17 @@ var RtspSession = class {
 		return this.muted;
 	}
 	/**
+	* The `User-Agent` this client put on its first request, or `null`.
+	*
+	* The ONLY identity that crosses from a consumer process into this session.
+	* The restreamer prints it beside the pre-roll window it serves, which is how
+	* a burst the broker measured can be tied to the file the consumer wrote —
+	* `sessionId` is minted here and appears in no consumer's logs.
+	*/
+	getUserAgent() {
+		return this.userAgent;
+	}
+	/**
 	* True only for a session that dialed the DETECTION path
 	* (`DETECTION_MUTED_PATH_SUFFIX`). Read by
 	* `RtspRestreamer.servePendingSessionsRtp` to exempt this session from the
@@ -3037,6 +3318,28 @@ var RtspSession = class {
 		return this.intent === "detection";
 	}
 	/**
+	* Does this session get the PRE-ROLL window instead of the current GOP?
+	*
+	* Both declared intents do, for the same reason: they attach after the edge
+	* they need to see. Separate from {@link isDetectionIntent} because that one
+	* also lifts the live-edge withhold, which is a MUTED-consumer rule and must
+	* not be lifted for anyone else.
+	*/
+	wantsPreRoll() {
+		return this.preRollIntent() !== null;
+	}
+	/**
+	* WHICH pre-roll window this session gets, or `null` when it declared no
+	* intent and takes the ordinary current-GOP join burst.
+	*
+	* The two windows are two numbers (D193), so the restreamer needs the intent
+	* and not just the bit: a recorder handed detection's window would carry the
+	* pre-roll of a feature it is not, and on this fleet detection's is 0.
+	*/
+	preRollIntent() {
+		return this.intent === "detection" || this.intent === "recording" ? this.intent : null;
+	}
+	/**
 	* Diagnostic snapshot consumed by `StreamBroker.listClients` (Phase 10).
 	* Gives operators the information needed to identify a specific RTSP
 	* session: where it's coming from, whether it's active, when it
@@ -11026,6 +11329,8 @@ var StreamBroker = class StreamBroker {
 	* isn't useful. 500 ms is wider than the worst-case fan-out delay.
 	*/
 	lastRefreshRequestAt = 0;
+	/** When {@link kickReconnect} last acted, for its own throttle. */
+	lastKickAt = 0;
 	/** Detected or configured codec — persists across reconnects */
 	detectedCodec;
 	/**
@@ -11163,6 +11468,58 @@ var StreamBroker = class StreamBroker {
 	*/
 	static FIRST_VIDEO_TIMEOUT_MS = 8e3;
 	/**
+	* The first-video deadline for a dial that FOLLOWED a lazy materialize.
+	*
+	* 8 s was sized against Chrome's ~15 s ICE-disconnect: detect a stuck stream
+	* before the viewer's browser gives up. That reasoning holds for a source
+	* that is already open and has stalled. It is exactly wrong for a COLD open
+	* behind a lazy publisher.
+	*
+	* Measured on the wyze bridge (devices 3838/3836, 2026-08-20): a successful
+	* open costs **12.4 s** — `WyzeRfc4571Server` waits for the first keyframe
+	* with a 10 s ceiling, on top of ~2 s of DTLS handshake. At 8 s the watchdog
+	* tore down a connection that was two seconds from delivering, and the cost
+	* of that teardown is not "try again quickly": the bridge closes its P2P
+	* server 30 s after the last client, so the next dial repays the whole cold
+	* open. Chrome had given up either way; the only thing the short deadline
+	* changed was whether the NEXT viewer paid for it again too.
+	*
+	* 20 s covers the measured open with margin and still fires well inside the
+	* activity watchdog's own recovery path for a connection that is genuinely
+	* dead.
+	*/
+	static LAZY_MATERIALIZE_FIRST_VIDEO_TIMEOUT_MS = 2e4;
+	/**
+	* How long after a lazy materialize was REQUESTED a dial still counts as
+	* "this one is the cold open we asked for". Past it the source is an
+	* ordinary open and takes the ordinary deadline.
+	*/
+	static MATERIALIZE_RECENT_MS = 3e4;
+	/**
+	* Poll cadence while a lazy publisher is materializing its upstream.
+	*
+	* The exponential backoff is the right shape for a source that is FAILING
+	* and the wrong one for a source that is being built: the publisher answers
+	* in ~12 s, and 1-2-4-8-16 s means the broker learns about it at 16 — up to
+	* 4 s of pure quantisation on every wyze cold open. Waiting at a flat 1 s
+	* costs one cheap re-resolve per second against a bounded deadline.
+	*/
+	static MATERIALIZE_POLL_MS = 1e3;
+	/**
+	* Bound on the flat-poll wait. Past it the materialize is not slow, it has
+	* failed, and the ordinary exponential backoff is the right answer again.
+	* Sized at the measured open (12.4 s) plus room for one retry inside the
+	* publisher.
+	*/
+	static MATERIALIZE_WAIT_MS = 2e4;
+	/**
+	* When the current lazy materialize was first requested, or `0` when none is
+	* outstanding. Drives BOTH the flat poll above and the extended first-video
+	* deadline — one fact, read in two places, so a materialize cannot be "in
+	* progress" for the dial loop and "not happening" for the watchdog.
+	*/
+	materializeRequestedAt = 0;
+	/**
 	* Rolling source-RTP activity watchdog. Distinct from the first-video
 	* watchdog: this one ARMS at DIAL time (so a connection that opens the
 	* loopback TCP but never delivers media is still detected) and RESETS on
@@ -11334,7 +11691,21 @@ var StreamBroker = class StreamBroker {
 	* then behaves exactly as it did before pre-roll existed. Resolved per stream
 	* by `resolvePreRollMs` and pushed by the manager.
 	*/
-	preRollMs = 0;
+	detectionPreRollMs = 0;
+	/**
+	* Media time (ms) of history a RECORDING dial (`/recording`) is handed — the
+	* `events`-band recorder's ffmpeg, which is spawned AT the trigger and whose
+	* first frame is otherwise at best the live edge.
+	*
+	* A SECOND number, not a wider first one (D193). The two windows are set by
+	* the operator for different reasons and cost different things: detection's
+	* is a backlog a decoder must drain, recording's is bytes copied to disk.
+	* Raising one to serve the other would change every detection dial on the
+	* fleet to buy a recorder ten seconds — the coupling the 2026-08-20 census
+	* named before anything was turned on. Resolved by `resolveRecordingPreRollMs`
+	* and pushed by the manager.
+	*/
+	recordingPreRollMs = 0;
 	/**
 	* Effective join-burst bound for this stream's RTSP restream — the cluster
 	* default, or this camera stream's override. Applies to the RESTREAM
@@ -11348,20 +11719,9 @@ var StreamBroker = class StreamBroker {
 	*  long-GOP high-bitrate stream) drops the bootstrap rather than balloon
 	*  memory — late joiners fall back to waiting for the next keyframe. */
 	static RTP_RING_MAX_BYTES = 24 * 1024 * 1024;
-	/**
-	* Byte budget for the EXTRA history pre-roll retains, over and above the
-	* current GOP.
-	*
-	* Its own budget rather than a share of {@link RTP_RING_MAX_BYTES} because
-	* the two failures are different: reaching the ring cap calls
-	* `resetRtpPreBuffer`, which drops the join bootstrap of EVERY consumer —
-	* WebRTC viewers included — for as long as the condition holds. A pre-roll
-	* that pushed a 4K stream into that state would be a knob for one camera's
-	* detection quietly degrading everybody else's picture. Over this budget the
-	* OLDEST retained GOP is dropped whole (never a tail cut), so the window
-	* stays decodable and simply carries less history than asked for.
-	*/
-	static PRE_ROLL_MAX_BYTES = 8 * 1024 * 1024;
+	/** Last budget printed by {@link reportPreRollClamp}, so the line fires on a
+	*  TRANSITION rather than on every keyframe. */
+	preRollClampLogged = false;
 	/** Stream stats tracking */
 	totalBytes = 0;
 	bytesInWindow = 0;
@@ -11401,10 +11761,13 @@ var StreamBroker = class StreamBroker {
 		if (logger) this.rtspRestreamer.setLogger(logger.child("rtsp"));
 		this.rtspRestreamer.setRtpPreBufferSupplier(() => this.getRtpPreBuffer());
 		this.rtspRestreamer.setPrimeBoundSupplier(() => this.joinBurstBound);
-		this.rtspRestreamer.setPreRollSupplier(() => ({
-			packets: this.getRtpPreRollBuffer(),
-			preRollMs: this.preRollMs
-		}));
+		this.rtspRestreamer.setPreRollSupplier((intent) => {
+			const windowMs = intent === "recording" ? this.recordingPreRollMs : this.detectionPreRollMs;
+			return {
+				packets: () => this.getRtpPreRollBuffer(windowMs),
+				preRollMs: windowMs
+			};
+		});
 		this.preBuffer = new EncodedRingBuffer(StreamBroker.DEFAULT_PRE_BUFFER_SEC);
 		this.decoderSeedBuffer = new EncodedRingBuffer(StreamBroker.DECODER_SEED_BUFFER_SEC);
 		this.audioChunkPlane = new AudioChunkPlane(logger?.child("audio-chunk-plane"));
@@ -11552,6 +11915,9 @@ var StreamBroker = class StreamBroker {
 		if (this.manualStop || this.stopping || !this.source) return;
 		if (!this.hasDemand()) return;
 		if (!this.reconnectTimer) return;
+		const nowMs = Date.now();
+		if (nowMs - this.lastKickAt < INITIAL_RECONNECT_DELAY_MS) return;
+		this.lastKickAt = nowMs;
 		clearTimeout(this.reconnectTimer);
 		this.reconnectTimer = void 0;
 		this.reconnectDelayMs = INITIAL_RECONNECT_DELAY_MS;
@@ -12416,16 +12782,61 @@ var StreamBroker = class StreamBroker {
 	* freshly-armed decoder, and a 6 s retention cannot serve a 6 s pre-roll plus
 	* the GOP that carries it.
 	*/
-	setPreRollMs(ms) {
+	setDetectionPreRollMs(ms) {
 		const next = Number.isFinite(ms) && ms > 0 ? ms : 0;
-		if (next === this.preRollMs) return;
-		this.preRollMs = next;
+		if (next === this.detectionPreRollMs) return;
+		this.detectionPreRollMs = next;
 		const seedSec = Math.max(StreamBroker.DECODER_SEED_BUFFER_SEC, Math.ceil(next / 1e3) + 2);
 		this.decoderSeedBuffer.setDuration(seedSec);
 	}
-	/** The pre-roll in force for this stream (ms). `0` = off. */
-	getPreRollMs() {
-		return this.preRollMs;
+	/**
+	* Configure how much history a RECORDING dial is handed.
+	*
+	* Touches the RETENTION (through {@link getPreRollRetentionMs}) and nothing
+	* else: no decoder seed, no change to what any other consumer is served.
+	*/
+	setRecordingPreRollMs(ms) {
+		const next = Number.isFinite(ms) && ms > 0 ? ms : 0;
+		this.recordingPreRollMs = next;
+	}
+	/** The DETECTION pre-roll in force for this stream (ms). `0` = off. */
+	getDetectionPreRollMs() {
+		return this.detectionPreRollMs;
+	}
+	/** The RECORDING pre-roll in force for this stream (ms). `0` = off. */
+	getRecordingPreRollMs() {
+		return this.recordingPreRollMs;
+	}
+	/**
+	* How far back the ring is kept: the WIDER of the two windows.
+	*
+	* One retention serves both because the bytes are the same bytes — the ring
+	* is cut per intent at read time ({@link getRtpPreRollBuffer}), so a 10 s
+	* recording window does not hand a detection dial 10 s of backlog. Retaining
+	* per intent would be two rings of the same packets.
+	*/
+	getPreRollRetentionMs() {
+		return Math.max(this.detectionPreRollMs, this.recordingPreRollMs);
+	}
+	/**
+	* Byte budget for the EXTRA history pre-roll retains, over and above the
+	* current GOP — derived from the window in force and this stream's OBSERVED
+	* bitrate.
+	*
+	* Its own budget rather than a share of {@link RTP_RING_MAX_BYTES} because
+	* the two failures are different: reaching the ring cap calls
+	* `resetRtpPreBuffer`, which drops the join bootstrap of EVERY consumer —
+	* WebRTC viewers included — for as long as the condition holds. A pre-roll
+	* that pushed a 4K stream into that state would be a knob for one camera's
+	* detection quietly degrading everybody else's picture. Over this budget the
+	* OLDEST retained GOP is dropped whole (never a tail cut), so the window
+	* stays decodable and simply carries less history than asked for.
+	*
+	* It replaced a FLAT 8 MiB constant, which was a promise this feature could
+	* not keep in either direction — see {@link preRollBudgetBytes}.
+	*/
+	getPreRollBudget() {
+		return preRollBudgetBytes(this.getPreRollRetentionMs(), this.bitrateKbps);
 	}
 	/**
 	* The seed replayed into a freshly-armed PUSH-mode decoder session.
@@ -12439,7 +12850,7 @@ var StreamBroker = class StreamBroker {
 	* both, so a fix to the boundary cannot land on only one plane.
 	*/
 	getDecoderSeedPackets() {
-		if (this.preRollMs <= 0) return this.decoderSeedBuffer.getPackets();
+		if (this.detectionPreRollMs <= 0) return this.decoderSeedBuffer.getPackets();
 		const all = this.decoderSeedBuffer.getAllPackets();
 		if (all.length === 0) return [];
 		const newestPts = all[all.length - 1].pts;
@@ -12451,7 +12862,7 @@ var StreamBroker = class StreamBroker {
 				ageMs: newestPts - packet.pts
 			});
 		}
-		const selection = selectPreRollStart(marks, this.preRollMs);
+		const selection = selectPreRollStart(marks, this.detectionPreRollMs);
 		return selection.startIndex < 0 ? [] : all.slice(selection.startIndex);
 	}
 	/** Retained keyframe AUs as ages in ms of media time behind `newestTs`. */
@@ -12473,14 +12884,18 @@ var StreamBroker = class StreamBroker {
 	trimRtpRingToPreRollWindow() {
 		if (this.rtpRingKeyframeMarks.length === 0 || this.rtpRing.length === 0) return;
 		const newestTs = this.rtpRing[this.rtpRing.length - 1].readUInt32BE(4);
-		let cut = selectPreRollStart(this.rtpPreRollMarks(newestTs), this.preRollMs).startIndex;
+		const marks = this.rtpPreRollMarks(newestTs);
+		const retentionMs = this.getPreRollRetentionMs();
+		let cut = selectPreRollStart(marks, retentionMs).startIndex;
 		if (cut < 0) return;
-		if (this.preRollMs > 0) {
+		if (retentionMs > 0) {
+			const budget = this.getPreRollBudget();
+			this.reportPreRollClamp(budget, retentionMs);
 			const historyEnd = this.rtpRingKeyframeMarks[this.rtpRingKeyframeMarks.length - 1].index;
 			let retained = 0;
 			for (let i = cut; i < historyEnd; i++) retained += this.rtpRing[i].length;
 			let markIdx = this.rtpRingKeyframeMarks.findIndex((m) => m.index === cut);
-			while (retained > StreamBroker.PRE_ROLL_MAX_BYTES && markIdx >= 0 && markIdx < this.rtpRingKeyframeMarks.length - 1) {
+			while (retained > budget.bytes && markIdx >= 0 && markIdx < this.rtpRingKeyframeMarks.length - 1) {
 				const nextCut = this.rtpRingKeyframeMarks[markIdx + 1].index;
 				for (let i = cut; i < nextCut; i++) retained -= this.rtpRing[i].length;
 				cut = nextCut;
@@ -12517,13 +12932,37 @@ var StreamBroker = class StreamBroker {
 	* when motion fired retained nothing, and the honest outcome there is the
 	* Stage 0 burst rather than a pretend one.
 	*/
-	getRtpPreRollBuffer() {
+	getRtpPreRollBuffer(windowMs) {
 		if (!this.rtpRingHasKeyframe) return [];
-		if (this.preRollMs <= 0 || this.rtpRing.length === 0) return this.getRtpPreBuffer();
+		if (windowMs <= 0 || this.rtpRing.length === 0) return this.getRtpPreBuffer();
 		const newestTs = this.rtpRing[this.rtpRing.length - 1].readUInt32BE(4);
-		const selection = selectPreRollStart(this.rtpPreRollMarks(newestTs), this.preRollMs);
+		const selection = selectPreRollStart(this.rtpPreRollMarks(newestTs), windowMs);
 		return selection.startIndex < 0 ? [] : this.rtpRing.slice(selection.startIndex);
 	}
+	/**
+	* Say it, ONCE per transition, when the absolute ceiling truncates the window
+	* the operator configured.
+	*
+	* A clamp nobody prints is indistinguishable from a camera that was simply
+	* not warm long enough, and the two call for opposite actions (buy the RAM
+	* back vs wait). The flat 8 MiB cap this replaced clamped SILENTLY, which is
+	* how "10 s" could mean 6 s on a 4K stream for as long as it did.
+	*/
+	reportPreRollClamp(budget, retentionMs) {
+		if (budget.clamped === this.preRollClampLogged) return;
+		this.preRollClampLogged = budget.clamped;
+		if (!budget.clamped) return;
+		this.logger?.warn("pre-roll budget clamped — the window will carry less than configured", {
+			tags: { deviceId: this.numericDeviceId },
+			meta: {
+				retentionMs,
+				detectionPreRollMs: this.detectionPreRollMs,
+				recordingPreRollMs: this.recordingPreRollMs,
+				bitrateKbps: this.bitrateKbps,
+				budgetBytes: budget.bytes
+			}
+		});
+	}
 	getSourceType() {
 		return this.source?.type ?? null;
 	}
@@ -12630,7 +13069,9 @@ var StreamBroker = class StreamBroker {
 	getFirstVideoWatchdogStatus() {
 		return {
 			armed: this.firstVideoWatchdog !== void 0,
-			videoRtpSeen: this.videoRtpSeen
+			videoRtpSeen: this.videoRtpSeen,
+			timeoutMs: this.firstVideoTimeoutMs(),
+			materializeRequestedAt: this.materializeRequestedAt
 		};
 	}
 	/**
@@ -13093,6 +13534,7 @@ var StreamBroker = class StreamBroker {
 				this.nextDialAllowedAt = 0;
 				this.stopErrorPlaceholder();
 				this.cancelFirstVideoWatchdog();
+				this.materializeRequestedAt = 0;
 				this.kickRtpActivityWatchdog();
 				this.videoRtpSeen++;
 				if (this.videoRtpSeen === 1 || this.videoRtpSeen === 50) this.logger?.info("video: rtp packet received", { meta: {
@@ -13419,10 +13861,12 @@ var StreamBroker = class StreamBroker {
 	armFirstVideoWatchdog() {
 		if (this.firstVideoWatchdog) return;
 		if (this.manualStop || this.stopping) return;
+		const timeoutMs = this.firstVideoTimeoutMs();
 		this.firstVideoWatchdog = setTimeout(() => {
 			this.firstVideoWatchdog = void 0;
 			if (this.manualStop || this.stopping) return;
 			if (this.videoRtpSeen > 0) {
+				this.materializeRequestedAt = 0;
 				this.logger?.info("first-video watchdog: video flowing — standing down", {
 					tags: { deviceId: this.numericDeviceId },
 					meta: {
@@ -13435,7 +13879,7 @@ var StreamBroker = class StreamBroker {
 			this.logger?.warn("first-video watchdog: no video RTP after source connect — forcing reconnect", {
 				tags: { deviceId: this.numericDeviceId },
 				meta: {
-					timeoutMs: StreamBroker.FIRST_VIDEO_TIMEOUT_MS,
+					timeoutMs,
 					...this.sourceMetaForLog()
 				}
 			});
@@ -13446,7 +13890,19 @@ var StreamBroker = class StreamBroker {
 			this.lastRefreshRequestAt = 0;
 			if (this.source?.type === "rfc4571") this.notifySourceRefresh();
 			this.scheduleReconnect();
-		}, StreamBroker.FIRST_VIDEO_TIMEOUT_MS);
+		}, timeoutMs);
+	}
+	/**
+	* The first-video deadline for the dial being armed.
+	*
+	* Extended for a dial that FOLLOWED a lazy materialize we asked for — see
+	* {@link LAZY_MATERIALIZE_FIRST_VIDEO_TIMEOUT_MS}. It reads the SAME fact the
+	* dial loop uses (`materializeRequestedAt`), so a cold open cannot be "in
+	* progress" for one and "not happening" for the other.
+	*/
+	firstVideoTimeoutMs() {
+		if (this.materializeRequestedAt === 0) return StreamBroker.FIRST_VIDEO_TIMEOUT_MS;
+		return Date.now() - this.materializeRequestedAt < StreamBroker.MATERIALIZE_RECENT_MS ? StreamBroker.LAZY_MATERIALIZE_FIRST_VIDEO_TIMEOUT_MS : StreamBroker.FIRST_VIDEO_TIMEOUT_MS;
 	}
 	/** Cancel the first-video watchdog. Idempotent. */
 	cancelFirstVideoWatchdog() {
@@ -13651,12 +14107,29 @@ var StreamBroker = class StreamBroker {
 	startRfc4571Reader(source) {
 		this.logger?.info("starting RFC 4571 reader");
 		if (typeof source.url === "string" && source.url.startsWith("lazy:rfc4571:")) {
-			this.logger?.info("rfc4571: lazy URL — requesting publisher to materialize upstream", { meta: { url: source.url } });
+			const nowMs = Date.now();
+			if (this.materializeRequestedAt === 0) this.materializeRequestedAt = nowMs;
+			const waitedMs = nowMs - this.materializeRequestedAt;
+			const withinDeadline = waitedMs < StreamBroker.MATERIALIZE_WAIT_MS;
+			if (withinDeadline) this.reconnectDelayMs = StreamBroker.MATERIALIZE_POLL_MS;
+			this.logger?.info("rfc4571: lazy URL — requesting publisher to materialize upstream", {
+				tags: { deviceId: this.numericDeviceId },
+				meta: {
+					url: source.url,
+					waitedMs,
+					schedule: withinDeadline ? "materialize-poll" : "backoff",
+					nextDelayMs: this.reconnectDelayMs
+				}
+			});
 			this._status = "error";
 			this.notifySourceRefresh();
 			this.scheduleReconnect();
 			return;
 		}
+		if (this.materializeRequestedAt > 0) this.logger?.info("rfc4571: publisher materialized — dialling the real upstream", {
+			tags: { deviceId: this.numericDeviceId },
+			meta: { materializeMs: Date.now() - this.materializeRequestedAt }
+		});
 		const sdp = typeof source.metadata?.["sdp"] === "string" ? source.metadata["sdp"] : null;
 		if (!sdp) {
 			this.logger?.warn("rfc4571: source missing metadata.sdp — requesting publisher refresh");
@@ -14658,6 +15131,13 @@ var StreamBrokerManager = class StreamBrokerManager {
 	* bytes on the ingest node, so it is turned on per camera that needs it.
 	*/
 	defaultPreRollMs = 0;
+	/**
+	* Cluster-wide default RECORDING pre-roll (ms). `undefined` until the addon
+	* pushes its config — which is a different fact from `0` and must stay so:
+	* `0` is an operator turning the feature OFF, `undefined` is a boot that has
+	* not read the setting yet and takes `DEFAULT_RECORDING_PRE_ROLL_MS`.
+	*/
+	defaultRecordingPreRollMs = void 0;
 	webrtcServer = null;
 	/**
 	* brokerId → the remote-encoded adapter backing a non-owned camera's WebRTC
@@ -15302,12 +15782,31 @@ var StreamBrokerManager = class StreamBrokerManager {
 	* decision); an explicit per-stream override still reaches it.
 	*/
 	applyPreRoll(broker, deviceId, camStreamId) {
-		broker.setPreRollMs(resolvePreRollMs({
+		const terminalRelay = this.cameraStreams.get(deviceId)?.get(camStreamId)?.kind === "pull-http";
+		broker.setDetectionPreRollMs(resolvePreRollMs({
 			camStreamId,
 			clusterMs: this.defaultPreRollMs,
 			overrides: this.deviceOverrides.get(deviceId)?.preRollMs,
-			terminalRelay: this.cameraStreams.get(deviceId)?.get(camStreamId)?.kind === "pull-http"
+			terminalRelay
 		}));
+		broker.setRecordingPreRollMs(resolveRecordingPreRollMs({
+			camStreamId,
+			clusterMs: this.defaultRecordingPreRollMs,
+			terminalRelay,
+			batteryOperated: this.deviceHasFeature(deviceId, DeviceFeature.BatteryOperated)
+		}));
+	}
+	/**
+	* Set the cluster-wide default RECORDING pre-roll and push it into every live
+	* broker — same reasoning as detection's: a broker outlives its setting.
+	*/
+	setDefaultRecordingPreRollMs(ms) {
+		this.defaultRecordingPreRollMs = ms;
+		for (const [brokerId, broker] of this.brokers) {
+			const parsed = parseBrokerId(brokerId);
+			if (!parsed) continue;
+			this.applyPreRoll(broker, parsed.deviceId, parsed.camStreamId);
+		}
 	}
 	setEventBus(bus) {
 		this.eventBus = bus;
@@ -15896,7 +16395,7 @@ var StreamBrokerManager = class StreamBrokerManager {
 			return { success: true };
 		}
 		const existing = this.upsertSourceCameraStream(deviceId, input);
-		const urlRefreshed = existing !== void 0 && input.url !== void 0 && existing.url !== input.url;
+		existing !== void 0 && input.url !== void 0 && (existing.url, input.url);
 		const wasAlreadyAssigned = (PUSH_KINDS.has(kind) ? findProfileForStream(this.assignments.get(deviceId)?.map ?? {}, camStreamId) : null) !== null && existing !== void 0;
 		await this.reconcileAutoAssignment(deviceId, "publish", existing === void 0);
 		if (wasAlreadyAssigned) {
@@ -15904,7 +16403,7 @@ var StreamBrokerManager = class StreamBrokerManager {
 			if (finalProfile !== null) this.emitCamStreamDemand(deviceId, camStreamId, finalProfile);
 		}
 		await this.ensureBroker(deviceId, camStreamId);
-		if (urlRefreshed) this.brokers.get(brokerIdFor(deviceId, camStreamId))?.kickReconnect();
+		this.brokers.get(brokerIdFor(deviceId, camStreamId))?.kickReconnect();
 		const justRegisteredBrokerId = brokerIdFor(deviceId, camStreamId);
 		const pending = this.pendingDerivedStreams.get(justRegisteredBrokerId);
 		if (pending) {
@@ -17765,7 +18264,7 @@ var StreamBrokerManager = class StreamBrokerManager {
 				else delete pr[camStreamId];
 				nextOverride.preRollMs = pr;
 				const broker = this.brokers.get(brokerIdFor(deviceId, camStreamId));
-				if (broker) broker.setPreRollMs(resolvePreRollMs({
+				if (broker) broker.setDetectionPreRollMs(resolvePreRollMs({
 					camStreamId,
 					clusterMs: this.defaultPreRollMs,
 					overrides: pr,
@@ -18418,7 +18917,11 @@ var StreamBrokerManager = class StreamBrokerManager {
 		const cam = this.cameraStreams.get(deviceId)?.get(camStreamId);
 		if (!cam) return;
 		const brokerId = brokerIdFor(deviceId, camStreamId);
-		if (this.brokers.has(brokerId)) return;
+		const live = this.brokers.get(brokerId);
+		if (live) {
+			this.applyPreRoll(live, deviceId, camStreamId);
+			return;
+		}
 		const existingEnsure = this.brokerEnsures.get(brokerId);
 		if (existingEnsure) {
 			await existingEnsure;
@@ -25450,15 +25953,32 @@ var TimelineSession = class {
 	/**
 	* The profile this session will actually play, given the one asked for.
 	*
-	* A segment covering `epochMs` wins outright. Failing that the answer is the
-	* first profile the camera DEMONSTRABLY records — a gap carrying a
-	* `nearestEdgeMs` means "footage exists on this tier, just not here", which is
-	* exactly what the feeder's snap-to-nearest needs. Falling back to `requested`
-	* when nothing has footage is only correct as a last resort: the session
-	* default is `mid`, and no camera on this cluster records `mid`, so returning
-	* it for a tap into a gap left the feeder with nothing to snap to and turned a
-	* recoverable crack into `seek-no-footage` — the operator sees "no recording"
-	* on a camera that recorded seconds either side.
+	* **The requested tier wins whenever it has footage AT ALL** — a segment
+	* covering `epochMs`, or a gap carrying a `nearestEdgeMs`, which means
+	* "footage exists on this tier, just not here" and is exactly what the
+	* feeder's snap-to-nearest needs. Only a tier that records NOTHING is
+	* abandoned, and then the answer is the first tier that demonstrably does.
+	* Falling back to `requested` when nothing has footage anywhere is the last
+	* resort: the session default is `mid`, and no camera on this cluster records
+	* `mid`, so returning it for a tap into a gap left the feeder with nothing to
+	* snap to and turned a recoverable crack into `seek-no-footage` — the
+	* operator sees "no recording" on a camera that recorded seconds either side.
+	*
+	* The requested tier is checked to EXHAUSTION before any other is consulted,
+	* and that ordering is load-bearing twice over:
+	*
+	* 1. The scrub is pinned to `low` by the client, and every D163 pre-cache
+	*    behaviour is gated on `deps.profile === 'low'` by exact string equality
+	*    — the 90 s/30 s entry warm, the whole-segment read, and the 24 MB
+	*    fragment budget (2 MB for anything else). `profileSearchOrder` puts
+	*    `high` BEFORE `low`, so a momentary `low` gap used to hand the drag a
+	*    `high` feeder and silently turn all three off. The client cannot repair
+	*    that: it re-sends `setProfile` only when its own `lastSentProfile`
+	*    mirror disagrees, and the mirror never learns the server moved.
+	* 2. `seek` and `scrubCommit` route through `playAt`, so every finger-release
+	*    pays this loop. locate is a cap RPC (1-8 s on cold footage); walking the
+	*    ladder to re-confirm a pin the caller already holds is latency the
+	*    operator feels as a slow commit.
 	*/
 	async resolveProfile(requested, epochMs) {
 		const locate = this.deps.locate;
@@ -25476,7 +25996,10 @@ var TimelineSession = class {
 				continue;
 			}
 			if (loc.kind === "segment") return profile;
-			if (withFootage === null && loc.nearestEdgeMs !== null) withFootage = profile;
+			if (withFootage === null && loc.nearestEdgeMs !== null) {
+				if (profile === requested) return profile;
+				withFootage = profile;
+			}
 		}
 		return withFootage ?? requested;
 	}
@@ -35273,6 +35796,7 @@ var StreamBrokerAddon = class extends BaseAddon {
 			catalogReconcileIntervalSec: 30,
 			joinBurstMaxSpanMs: DEFAULT_PRIME_BURST_BOUND.maxSpanMs,
 			preRollMs: 0,
+			recordingPreRollMs: DEFAULT_RECORDING_PRE_ROLL_MS,
 			binaryPath: "",
 			hwaccel: "copy"
 		});
@@ -35332,6 +35856,7 @@ var StreamBrokerAddon = class extends BaseAddon {
 		this.brokerManager.setDefaultPreBufferSec(this.config.defaultPreBufferSec);
 		this.brokerManager.setDefaultJoinBurstMaxSpanMs(this.config.joinBurstMaxSpanMs);
 		this.brokerManager.setDefaultPreRollMs(this.config.preRollMs);
+		this.brokerManager.setDefaultRecordingPreRollMs(this.config.recordingPreRollMs);
 		this.brokerManager.setEventBus(this.ctx.eventBus);
 		const localNode = this.ctx.kernel.localNodeId;
 		const localNodeId = localNode ? localNode.includes("/") ? localNode.split("/")[0] : localNode : void 0;
@@ -35914,6 +36439,17 @@ var StreamBrokerAddon = class extends BaseAddon {
 					default: 0,
 					unit: "ms"
 				},
+				{
+					type: "number",
+					key: "recordingPreRollMs",
+					label: "Recording pre-roll",
+					description: "Cluster-wide default for how much video from BEFORE the trigger an event recording begins with. The recorder’s ffmpeg is spawned AT the trigger, so without this its first frame is at best the live edge — measured on one camera, the footage started after the motion in 60 % of episodes. It spends retained video in memory on whichever node ingests the camera and can only reach as far back as that stream has been warm; it never dials a camera on its own. Battery cameras and terminal (MJPEG relay) cameras take 0. Set 0 to turn it off.",
+					min: 0,
+					max: RECORDING_PRE_ROLL_MAX_MS,
+					step: 500,
+					default: DEFAULT_RECORDING_PRE_ROLL_MS,
+					unit: "ms"
+				},
 				{
 					type: "number",
 					key: "catalogReconcileIntervalSec",