@camstack/addon-pipeline 1.2.290 → 1.2.291

package/dist/stream-broker/index.mjs

@@ -1,10 +1,10 @@
 import { r as __toESM } from "../chunk-DnnnRqeS.mjs";
-import { $t as errMsg, An as literal, Dn as boolean, En as array, Fn as string, H as addonWidgetsSourceCapability, In as union, Jt as streamBrokerCapability, K as batteryCapability, Ln as EventCategory, M as RATE_CONTROL_TIGHT, Mn as object, On as discriminatedUnion, Pn as record, Pt as rankStreams, Q as declareLogChannel, Qt as webrtcSessionCapability, R as RingBuffer, Sn as parseProfileBrokerId, Tn as _enum, Vt as resolveEgressDecodeHwAccel, X as createHwAccelCache, Y as clipExportFailureOf, Z as createLogChannelsProvider, _n as isEvent, _t as loadContributionCapability, a as CLIP_BROKER_PACED_RATES, an as BOOT_RECOVERY_BACKOFF_MS, at as egressTransportFromRequest, bn as nodePin, bt as maskUrlCredentials, cn as CamProfileSchema, en as AUDIO_PRESETS, et as deriveBatteryPresence, fn as createEvent, hn as expandAudioChunkToF32le, i as BatteryStatusSchema, in as isSoftwareDecode, it as egressTranscodeSharingKey, j as RATE_CONTROL_RELAXED, jn as number, ln as DeviceFeature, nn as buildFfmpegArgs$1, o as CLIP_STILL_REASON_CODE_HEADER, on as BaseAddon, q as cameraStreamsCapability, rn as invocationFromEncodeProfile, sn as CAM_PROFILE_ORDER, un as DeviceType, vn as makeProfileBrokerId, vt as logChannelsCapability, w as G711_SCALE_CORRECTION_DB, x as EncodeProfileSchema, yn as makeSourceBrokerId } from "../dist-C4JqXCw-.mjs";
-import { i as NO_COST_CLAIM, n as Fmp4FragmentChild, o as probeFfmpegBinary, r as Fmp4FragmentPlane, t as ChildCostRegistry } from "../node-C-WfKJ6b.mjs";
+import { $t as errMsg, An as literal, Dn as boolean, En as array, Fn as string, H as addonWidgetsSourceCapability, In as union, Jt as streamBrokerCapability, K as batteryCapability, Ln as EventCategory, M as RATE_CONTROL_TIGHT, Mn as object, On as discriminatedUnion, Pn as record, Pt as rankStreams, Q as declareLogChannel, Qt as webrtcSessionCapability, R as RingBuffer, Sn as parseProfileBrokerId, Tn as _enum, Vt as resolveEgressDecodeHwAccel, X as createHwAccelCache, Y as clipExportFailureOf, Z as createLogChannelsProvider, _n as isEvent, _t as loadContributionCapability, a as CLIP_BROKER_PACED_RATES, an as BOOT_RECOVERY_BACKOFF_MS, at as egressTransportFromRequest, bn as nodePin, bt as maskUrlCredentials, cn as CamProfileSchema, en as AUDIO_PRESETS, et as deriveBatteryPresence, fn as createEvent, hn as expandAudioChunkToF32le, i as BatteryStatusSchema, in as isSoftwareDecode, it as egressTranscodeSharingKey, j as RATE_CONTROL_RELAXED, jn as number, ln as DeviceFeature, nn as buildFfmpegArgs$1, o as CLIP_STILL_REASON_CODE_HEADER, on as BaseAddon, q as cameraStreamsCapability, rn as invocationFromEncodeProfile, sn as CAM_PROFILE_ORDER, un as DeviceType, vn as makeProfileBrokerId, vt as logChannelsCapability, w as G711_SCALE_CORRECTION_DB, x as EncodeProfileSchema, yn as makeSourceBrokerId } from "../dist-Bn6BQW8q.mjs";
+import { i as NO_COST_CLAIM, n as Fmp4FragmentChild, o as probeFfmpegBinary, r as Fmp4FragmentPlane, t as ChildCostRegistry } from "../node-BN0Na3HN.mjs";
 import { a as parseRestreamPath, d as PREBUFFER_MAX_MS, f as capPreRollRequestMs, i as isLiveEdgeOnlyDial, m as resolvePrebuffer, n as NO_DECLARATION, p as prebufferRetentionMs, s as sdpVariantFor, u as withSentryIntent } from "../restream-intent-DyGmLAU9.mjs";
 import { n as profileForStreamId } from "../remote-restream-BeHi78PZ.mjs";
 import { n as RowMapStore, t as retireRootKeys } from "../retire-root-keys-DZvlso2l.mjs";
-import { a as avccSampleToAnnexB, i as require_mp4box_all, n as demuxSegmentPreferJs, o as buildKeyframeAnnexB, r as runFfmpegOnce, s as parseNalLengthSize, t as demuxSegmentFullJs } from "../segment-demux-js-4OAHyQ3t.mjs";
+import { a as avccSampleToAnnexB, i as require_mp4box_all, n as demuxSegmentPreferJs, o as buildKeyframeAnnexB, r as runFfmpegOnce, s as parseNalLengthSize, t as demuxSegmentFullJs } from "../segment-demux-js-CNPzlcyO.mjs";
 import { createRequire } from "node:module";
 import * as os from "node:os";
 import { networkInterfaces, tmpdir } from "node:os";
@@ -23177,6 +23177,246 @@ var H264Repacketizer = class {
 	}
 };
 //#endregion
+//#region src/stream-broker/webrtc/delivery-meter.ts
+/** The window the ladder judges delivery over: at least one GOP. */
+function deliveryWindowMs(idrIntervalMs, config) {
+	const gop = idrIntervalMs !== null && Number.isFinite(idrIntervalMs) && idrIntervalMs > 0 ? idrIntervalMs : 0;
+	return Math.min(config.maxWindowMs, Math.max(config.minWindowMs, gop));
+}
+/**
+* When a session's meter may start counting client reports. A session created
+* by a tier change starts after the change blackout (review I1): until the
+* client swaps its player onto the new PC (after the new stream's first
+* decode, 2–5 s), its reporter still reads the OLD PC — 0 kbps — and the
+* first report after the swap is 0 too; both fall inside the new session's
+* sends and read as a failed rung.
+*/
+function deliveryMeterStart(now, afterTierChange, waitAfterChangeMs) {
+	return afterTierChange ? now + waitAfterChangeMs : now;
+}
+/**
+* Bucket width. 100 ms, and edges round to the NEAREST boundary, so a frame is
+* put on the wrong side of a window edge only when it was sent within 50 ms of
+* it — about one frame at 25 fps. Rounding edges inward instead dropped a whole
+* IDR that sat 160 ms inside a window and read a whole rung as 1.5× delivered.
+* 32 s of history is 320 slots.
+*/
+var SEND_BUCKET_MS = 100;
+/**
+* Bytes this session sent, bucketed by time. A fixed ring: `record` is on the
+* RTP send path, so it allocates nothing.
+*/
+var SendHistory = class {
+	bytes;
+	/** The bucket index each slot currently holds; -1 = empty. */
+	ids;
+	constructor(spanMs) {
+		const slots = Math.max(1, Math.ceil(spanMs / SEND_BUCKET_MS));
+		this.bytes = new Float64Array(slots);
+		this.ids = new Float64Array(slots).fill(-1);
+	}
+	record(byteCount, now) {
+		const id = Math.floor(now / SEND_BUCKET_MS);
+		const slot = id % this.ids.length;
+		if (this.ids[slot] !== id) {
+			this.ids[slot] = id;
+			this.bytes[slot] = 0;
+		}
+		this.bytes[slot] = (this.bytes[slot] ?? 0) + byteCount;
+	}
+	bitsBetween(fromMs, toMs) {
+		const first = Math.round(fromMs / SEND_BUCKET_MS);
+		const last = Math.round(toMs / SEND_BUCKET_MS) - 1;
+		let bytes = 0;
+		for (let id = first; id <= last; id += 1) {
+			const slot = id % this.ids.length;
+			if (this.ids[slot] === id) bytes += this.bytes[slot] ?? 0;
+		}
+		return bytes * 8;
+	}
+};
+/**
+* The client's recent reports, and the ratio they imply against a
+* {@link SendHistoryReader}. One meter per adaptive session: `notBefore` is
+* the session's start, because the reports are DEVICE-scoped and a report
+* about time before this session describes the previous one (a re-offer).
+*/
+var DeliveryMeter = class {
+	config;
+	notBefore;
+	reports = [];
+	constructor(config, notBefore) {
+		this.config = config;
+		this.notBefore = notBefore;
+	}
+	/** Fold one client report. The same report read on several ticks counts once. */
+	observe(kbps, endAt) {
+		if (!Number.isFinite(kbps) || kbps < 0 || !Number.isFinite(endAt)) return;
+		if (endAt - this.config.clientSampleSpanMs < this.notBefore) return;
+		if (this.reports.some((r) => r.endAt === endAt)) return;
+		const horizon = endAt - this.config.historySpanMs;
+		this.reports = [...this.reports.filter((r) => r.endAt > horizon), {
+			kbps,
+			endAt
+		}].sort((a, b) => a.endAt - b.endAt);
+	}
+	/**
+	* Is the client reporting at all? A fresh report that does not yet cover a
+	* whole window is "not measured YET" — different from a client that sends
+	* no telemetry, and it must not be climbed on (a 10 %-delivery link would
+	* otherwise promote in the seconds before its first window closes).
+	*/
+	isReporting(now) {
+		const newest = this.reports.at(-1);
+		return newest !== void 0 && now - newest.endAt <= this.config.maxClientSampleAgeMs;
+	}
+	/**
+	* The newest report alone against the same 2 s of sends — the short window
+	* a total freeze is judged on. Null when there is none, or it is stale.
+	*/
+	evaluateNewest(history, now) {
+		const newest = this.reports.at(-1);
+		if (newest === void 0 || now - newest.endAt > this.config.maxClientSampleAgeMs) return null;
+		const span = this.config.clientSampleSpanMs;
+		return {
+			receivedKbps: newest.kbps,
+			sentKbps: history.bitsBetween(newest.endAt - span, newest.endAt) / span,
+			windowMs: span
+		};
+	}
+	/**
+	* Received vs sent over the newest reports that together cover `windowMs`,
+	* or `null` when they do not (yet) — or the newest one is stale.
+	*/
+	evaluate(history, windowMs, now) {
+		const newest = this.reports.at(-1);
+		if (newest === void 0 || now - newest.endAt > this.config.maxClientSampleAgeMs) return null;
+		const span = this.config.clientSampleSpanMs;
+		let covered = 0;
+		let receivedBits = 0;
+		let sentBits = 0;
+		for (let i = this.reports.length - 1; i >= 0 && covered < windowMs; i -= 1) {
+			const r = this.reports[i];
+			if (r === void 0 || now - (r.endAt - span) > this.config.historySpanMs) break;
+			covered += span;
+			receivedBits += r.kbps * span;
+			sentBits += history.bitsBetween(r.endAt - span, r.endAt);
+		}
+		if (covered < windowMs) return null;
+		return {
+			receivedKbps: receivedBits / covered,
+			sentKbps: sentBits / covered,
+			windowMs: covered
+		};
+	}
+};
+//#endregion
+//#region src/stream-broker/webrtc/adaptive-config.ts
+/** How often the adaptive controller re-evaluates the ladder (ms). */
+var ADAPTIVE_TICK_MS = 2e3;
+/** Ladder tuning shared by every adaptive session. */
+var ADAPTIVE_CONFIG = {
+	analyzeWindowMs: 15e3,
+	minFailPercent: .05,
+	waitAfterResetMs: 8e3,
+	upgradeHealthyMs: 4e3,
+	upgradeHealthyGrowthFactor: 3,
+	maxProgressiveUpgradeHealthyMs: 3e4,
+	minTimeBetweenChangesMs: 4e3,
+	maxUpgradeBackoffMs: 9e5,
+	stallDeliveryRatio: .25,
+	recoverDeliveryRatio: .5,
+	freezeDeliveryRatio: .1,
+	freezeMinSentKbps: 16,
+	climbDeliveryRatio: .9,
+	stallConfirmMs: 6e3,
+	waitAfterChangeMs: 8e3,
+	climbCapacityMargin: 1.2,
+	tryClimbDeliveryRatio: .95,
+	tryClimbMaxLossRatio: .01,
+	tryBackoffBaseMs: 3e4,
+	tryBackoffMaxMs: 6e5,
+	trialMs: 2e4,
+	trialMaxMs: 4e4,
+	trialRevertRatio: .9,
+	trialRevertConsecutive: 2
+};
+/** How the delivery window is built from the client's reports. */
+var ADAPTIVE_DELIVERY_CONFIG = {
+	clientSampleSpanMs: 2e3,
+	minWindowMs: 2e3,
+	maxWindowMs: 16e3,
+	maxClientSampleAgeMs: 1e4,
+	historySpanMs: 32e3
+};
+//#endregion
+//#region src/stream-broker/webrtc/climb-capacity.ts
+/** The client ladder's thresholds (`DOWNLINK_MID_MBPS`, `DOWNLINK_HIGH_MBPS`), kbps. */
+var UNMEASURED_RUNG_BAR_KBPS = {
+	low: 0,
+	mid: 2500,
+	high: 8e3
+};
+/** The kbps the next rung needs; `(1800 × 1.2)` or the client threshold. */
+function capacityBarKbps(tier, rungKbps, margin) {
+	return rungKbps !== null && rungKbps > 0 ? rungKbps * margin : UNMEASURED_RUNG_BAR_KBPS[tier];
+}
+function known(v) {
+	return v !== null && Number.isFinite(v) && v > 0;
+}
+function judgeCapacity(evidence, nextTier, nextRungKbps, margin) {
+	const neededKbps = capacityBarKbps(nextTier, nextRungKbps, margin);
+	const { rembKbps, probeKbps, probeFresh } = evidence;
+	if (known(probeKbps) && probeFresh && probeKbps >= neededKbps) return {
+		kind: "sufficient",
+		source: "probe",
+		kbps: probeKbps,
+		neededKbps
+	};
+	if (known(rembKbps) && rembKbps >= neededKbps) return {
+		kind: "sufficient",
+		source: "remb",
+		kbps: rembKbps,
+		neededKbps
+	};
+	if (known(probeKbps) && probeKbps < neededKbps) return {
+		kind: "probe-short",
+		kbps: probeKbps,
+		neededKbps
+	};
+	return {
+		kind: "none",
+		bestKbps: known(rembKbps) ? rembKbps : null,
+		neededKbps
+	};
+}
+/**
+* REMB as it can be trusted. werift stores the LAST received estimate on the
+* sender and never ages it, so a peer that stopped sending REMB (backgrounded,
+* gone) would vouch for room indefinitely (review m5). Chrome re-estimates
+* about once a second and the value moves; an estimate unchanged for
+* `staleMs` (30 000 ms — fifteen ticks) is treated as no estimate at all.
+*/
+var RembWatch = class {
+	staleMs;
+	last = null;
+	changedAt = 0;
+	constructor(staleMs) {
+		this.staleMs = staleMs;
+	}
+	read(kbps, now) {
+		if (kbps === null) {
+			this.last = null;
+			return null;
+		}
+		if (kbps !== this.last) {
+			this.last = kbps;
+			this.changedAt = now;
+		}
+		return now - this.changedAt > this.staleMs ? null : kbps;
+	}
+};
+//#endregion
 //#region src/stream-broker/webrtc/transcode-egress-leg.ts
 /**
 * The request a browser session makes. Structured only: the primitive's schema
@@ -23291,6 +23531,8 @@ function selectAudioClock(mimeType) {
 *
 * Uses werift (optional peer dependency) for server-side WebRTC.
 */
+/** A REMB unchanged this long is no estimate (`RembWatch`). */
+var REMB_STALE_MS = 3e4;
 var _werift;
 async function loadWerift() {
 	if (_werift) return _werift;
@@ -24812,6 +25054,7 @@ var AdaptiveSession = class AdaptiveSession {
 			this.maybeRebaseRtp(pkt.header.sequenceNumber, pkt.header.timestamp);
 			try {
 				this.videoSender.sendRtp(pkt);
+				this.videoSendHistory.record(pkt.payload.length, Date.now());
 				this.lastVideoRtpTs = pkt.header.timestamp >>> 0;
 				if (this.firstVideoRtpTs === null) {
 					this.firstVideoRtpTs = this.lastVideoRtpTs;
@@ -25383,6 +25626,26 @@ var AdaptiveSession = class AdaptiveSession {
 	get rtpPacketsSentTotal() {
 		return this.rtpPacketsSent;
 	}
+	/**
+	* Video RTP PAYLOAD bytes this session sent, bucketed by time — the "sent"
+	* half of the adaptive ladder's delivery ratio (D635). Payload, not wire
+	* size, because the client's `bytesReceived` excludes RTP headers.
+	*/
+	videoSendHistory = new SendHistory(ADAPTIVE_DELIVERY_CONFIG.historySpanMs);
+	get sentVideoHistory() {
+		return this.videoSendHistory;
+	}
+	/**
+	* The receiver's bandwidth estimate (REMB) in kbps, or `null` when the peer
+	* has sent none. werift stores the last REMB on the sender; `-1`/absent in
+	* the loss line means the same "no estimate", which is not "zero".
+	*/
+	receiverEstimateKbps(now) {
+		const raw = this.videoSender?.receiverEstimatedMaxBitrate;
+		return this.rembWatch.read(typeof raw === "bigint" && raw > 0n ? Number(raw) / 1e3 : null, now);
+	}
+	/** Ages the REMB werift keeps forever — see `RembWatch`. */
+	rembWatch = new RembWatch(REMB_STALE_MS);
 	rtpLogCounter = 0;
 	/** One-shot guards for the "first video/audio RTP" debug markers. */
 	firstVideoRtpLogged = false;
@@ -25705,6 +25968,7 @@ var AdaptiveSession = class AdaptiveSession {
 					} });
 				}
 				this.videoSender.sendRtp(pkt);
+				this.videoSendHistory.record(payload.length, Date.now());
 				this.rtpPacketsSent++;
 				this.logFirstVideoRtp("writeVideoNals", codec);
 				if (this.debug && (this.rtpPacketsSent === 1 || this.rtpPacketsSent % 500 === 0)) this.logger.info("RTP packets sent", { meta: {
@@ -26172,6 +26436,42 @@ var LossTracker = class {
 //#endregion
 //#region src/stream-broker/webrtc/stall-tracker.ts
 /**
+* The one place the device-scoped telemetry is judged ownable. With more than
+* one adaptive session of the device, the record may be another viewer's:
+* delivery is unknown ("no telemetry" semantics — the loss path judges) and
+* the sample says so, so the ladder refuses a try-climb on it.
+*/
+function buildStallSample(input) {
+	if (input.adaptiveSessionsOnDevice > 1) return {
+		delivery: null,
+		recent: null,
+		clientReporting: false,
+		telemetryShared: true,
+		serverSending: input.serverSending
+	};
+	return {
+		delivery: input.delivery,
+		recent: input.recent,
+		clientReporting: input.clientReporting,
+		telemetryShared: false,
+		serverSending: input.serverSending
+	};
+}
+var UNKNOWN_EVIDENCE = {
+	clientKbps: null,
+	sentKbps: null,
+	deliveryRatio: null,
+	deliveryWindowMs: null,
+	stalledForMs: 0,
+	serverSending: false
+};
+function ratioOf(delivery) {
+	if (delivery === null) return null;
+	const { receivedKbps, sentKbps } = delivery;
+	if (!Number.isFinite(receivedKbps) || !Number.isFinite(sentKbps) || sentKbps <= 0) return null;
+	return receivedKbps / sentKbps;
+}
+/**
 * Windowed "the media stopped arriving" detector. Pure state machine: no
 * clock of its own, no side effects — `observe` is the only mutator and every
 * decision is a function of the samples it was given.
@@ -26181,11 +26481,9 @@ var StallTracker = class {
 	/** When the current uninterrupted stall began; null when not stalling. */
 	stallStartedAt = null;
 	blackoutUntil = 0;
-	lastEvidence = {
-		clientKbps: null,
-		stalledForMs: 0,
-		serverSending: false
-	};
+	lastEvidence = UNKNOWN_EVIDENCE;
+	clientReporting = false;
+	telemetryShared = false;
 	constructor(config) {
 		this.config = config;
 	}
@@ -26198,38 +26496,36 @@ var StallTracker = class {
 	* Fold one evaluation into the window. Returns nothing; ask `isStalled`.
 	*
 	* Three outcomes, and the middle one is the reason this is not a simple
-	* boolean: a rate at or above `recoverKbpsFloor` CLEARS the stall, a rate
-	* below `stallKbpsFloor` starts or extends it, and anything between the two
-	* (or unknown, or with the server idle) HOLDS whatever the window already
-	* believed. Holding is what stops a borderline link from oscillating.
+	* boolean: a ratio at or above `recoverDeliveryRatio` CLEARS the stall, a
+	* ratio below `stallDeliveryRatio` with the server sending starts or extends
+	* it, and anything between the two (or unknown, or nothing sent) HOLDS
+	* whatever the window already believed.
 	*/
 	observe(sample, now) {
+		const ratio = ratioOf(sample.delivery);
+		const measured = (stalledForMs) => ({
+			clientKbps: sample.delivery?.receivedKbps ?? null,
+			sentKbps: sample.delivery?.sentKbps ?? null,
+			deliveryRatio: ratio,
+			deliveryWindowMs: sample.delivery?.windowMs ?? null,
+			stalledForMs,
+			serverSending: sample.serverSending
+		});
+		this.clientReporting = sample.clientReporting;
+		this.telemetryShared = sample.telemetryShared;
 		if (now < this.blackoutUntil) {
 			this.stallStartedAt = null;
-			this.lastEvidence = {
-				clientKbps: sample.clientKbps,
-				stalledForMs: 0,
-				serverSending: sample.serverSending
-			};
+			this.lastEvidence = measured(0);
 			return;
 		}
-		const kbps = sample.clientKbps;
-		const age = sample.clientSampleAgeMs;
-		if (!(kbps !== null && Number.isFinite(kbps) && age !== null && age <= this.config.maxClientSampleAgeMs) || kbps === null) {
-			this.lastEvidence = {
-				clientKbps: null,
-				stalledForMs: this.stalledForMs(now),
-				serverSending: sample.serverSending
-			};
-			return;
-		}
-		if (kbps >= this.config.recoverKbpsFloor) this.stallStartedAt = null;
-		else if (kbps < this.config.stallKbpsFloor && sample.serverSending) this.stallStartedAt ??= now;
-		this.lastEvidence = {
-			clientKbps: kbps,
-			stalledForMs: this.stalledForMs(now),
-			serverSending: sample.serverSending
-		};
+		const recent = sample.recent !== null && sample.recent.sentKbps >= this.config.freezeMinSentKbps ? ratioOf(sample.recent) : null;
+		const frozen = recent !== null && recent < this.config.freezeDeliveryRatio;
+		const recovered = recent !== null && recent >= this.config.recoverDeliveryRatio;
+		const starved = ratio !== null && ratio < this.config.stallDeliveryRatio && !recovered;
+		const current = recent ?? ratio;
+		if ((frozen || starved) && sample.serverSending) this.stallStartedAt ??= now;
+		else if (current !== null && current >= this.config.recoverDeliveryRatio) this.stallStartedAt = null;
+		this.lastEvidence = measured(this.stalledForMs(now));
 	}
 	stalledForMs(now) {
 		return this.stallStartedAt === null ? 0 : now - this.stallStartedAt;
@@ -26240,25 +26536,42 @@ var StallTracker = class {
 		return this.stalledForMs(now) >= this.config.stallConfirmMs;
 	}
 	/**
-	* May the ladder PROMOTE on this evaluation?
+	* May the ladder PROMOTE on this evaluation, as far as the transport knows?
 	*
-	* False when the last fresh measurement was below `recoverKbpsFloor` —
-	* either a stall building, or a link crawling along in the dead band.
-	* Promoting there spends bandwidth the session has just been shown not to
-	* have, and the loss path cannot object: a stream delivering almost nothing
-	* reports almost no loss. Same doctrine as `LossTracker.hasEvidence` — a
-	* climb needs POSITIVE evidence, not the absence of a complaint.
+	* No while a stall is building, and no while the rung we are on is not
+	* landing (nearly) whole — promoting there spends bandwidth the session has
+	* just been shown not to have, and the loss path cannot object: a stream
+	* delivering almost nothing reports almost no loss.
 	*
-	* Unknown does not block. A deployment with no client telemetry at all must
+	* Unknown refuses only while the client IS reporting — the window is simply
+	* not covered yet, and climbing then would promote a link measured at 10 %
+	* a few seconds later. A deployment with no client telemetry at all must
 	* behave exactly as it did before this tracker existed; the loss path's own
 	* `hasEvidence` is the gate there.
 	*/
-	isClimbSafe(now) {
-		if (now < this.blackoutUntil) return true;
-		if (this.stallStartedAt !== null) return false;
-		const last = this.lastEvidence.clientKbps;
-		if (last === null) return true;
-		return last >= this.config.recoverKbpsFloor;
+	climbSafety(now) {
+		if (now < this.blackoutUntil) return { safe: true };
+		if (this.stallStartedAt !== null) return {
+			safe: false,
+			reason: "stall-building"
+		};
+		const ratio = this.lastEvidence.deliveryRatio;
+		if (ratio === null) return this.clientReporting ? {
+			safe: false,
+			reason: "delivery"
+		} : { safe: true };
+		return ratio >= this.config.climbDeliveryRatio ? { safe: true } : {
+			safe: false,
+			reason: "delivery"
+		};
+	}
+	/** Was the device's client record possibly another viewer's at the last evaluation? */
+	get isTelemetryShared() {
+		return this.telemetryShared;
+	}
+	/** Was the client reporting at the last evaluation (even if not yet covering a window)? */
+	get isClientReporting() {
+		return this.clientReporting;
 	}
 	/** What the last `observe` measured — for the switch's log line. */
 	evidence(now) {
@@ -26269,9 +26582,142 @@ var StallTracker = class {
 	}
 };
 //#endregion
+//#region src/stream-broker/webrtc/rtt-stability.ts
+/** 16 s — the longest delivery window, so both halves of a try look at the same span. */
+var RTT_WINDOW_MS = 16e3;
+var MIN_SAMPLES = 3;
+var MIN_SPREAD_MS = 20;
+var SPREAD_FRACTION = .5;
+var RttWindow = class {
+	samples = [];
+	observe(rttMs, now) {
+		if (rttMs === null || !Number.isFinite(rttMs) || rttMs <= 0) return;
+		this.samples = [...this.samples.filter((s) => now - s.at <= RTT_WINDOW_MS), {
+			rttMs,
+			at: now
+		}];
+	}
+	stability(now) {
+		const recent = this.samples.filter((s) => now - s.at <= RTT_WINDOW_MS);
+		if (recent.length < MIN_SAMPLES) return "unknown";
+		const values = recent.map((s) => s.rttMs);
+		const min = Math.min(...values);
+		return Math.max(...values) - min <= Math.max(MIN_SPREAD_MS, min * SPREAD_FRACTION) ? "stable" : "unstable";
+	}
+};
+//#endregion
+//#region src/stream-broker/webrtc/try-climb.ts
+var NO_TRY_HISTORY = {
+	failures: 0,
+	notBefore: 0,
+	lastRevert: null,
+	trialFrom: null
+};
+/** Backoff after the Nth consecutive failed try: base × 2^(N−1), capped. */
+function tryBackoffMs(failures, baseMs, maxMs) {
+	if (failures <= 0) return 0;
+	return Math.min(baseMs * 2 ** (failures - 1), maxMs);
+}
+/** Watches one tried rung through its first window. Pure: fed, never reads a clock. */
+var TrialWatch = class {
+	from;
+	config;
+	startedAt = null;
+	lowStreak = 0;
+	measured = 0;
+	constructor(from, config) {
+		this.from = from;
+		this.config = config;
+	}
+	/**
+	* Start the trial over: it must be judged afresh on live media. Called when
+	* recorded playback takes the track (review m14) — time off live must never
+	* count toward keeping a rung that was never measured.
+	*/
+	restart() {
+		this.startedAt = null;
+		this.lowStreak = 0;
+		this.measured = 0;
+	}
+	judge(now, input) {
+		this.startedAt ??= now;
+		if (input.stalled || input.lossFailing) return {
+			kind: "revert",
+			deliveryRatio: input.deliveryRatio,
+			stalled: input.stalled
+		};
+		if (input.deliveryRatio !== null) {
+			this.measured += 1;
+			this.lowStreak = input.deliveryRatio < this.config.trialRevertRatio ? this.lowStreak + 1 : 0;
+			if (this.lowStreak >= this.config.trialRevertConsecutive) return {
+				kind: "revert",
+				deliveryRatio: input.deliveryRatio,
+				stalled: false
+			};
+		}
+		const forMs = now - this.startedAt;
+		const judged = this.measured >= this.config.trialRevertConsecutive || !input.clientReporting;
+		if (forMs >= this.config.trialMs && judged || forMs >= this.config.trialMaxMs) return { kind: "kept" };
+		return {
+			kind: "running",
+			forMs
+		};
+	}
+};
+/**
+* The try-climb memory per DEVICE on this broker, with a TTL (review I4).
+* The per-session intent survives only a re-offer; without this, every new
+* viewer session of a camera whose next rung keeps failing started again at
+* try #1. The trial itself (`trialFrom`) never carries to a new session.
+*/
+var DeviceTryMemory = class {
+	ttlMs;
+	entries = /* @__PURE__ */ new Map();
+	/** @param ttlMs forget a device not refreshed for this long — 600 000 ms, the backoff cap. */
+	constructor(ttlMs) {
+		this.ttlMs = ttlMs;
+	}
+	set(deviceId, carry, now) {
+		this.entries.set(deviceId, {
+			carry,
+			at: now
+		});
+	}
+	get(deviceId, now) {
+		const entry = this.entries.get(deviceId);
+		if (entry === void 0) return null;
+		if (now - entry.at > this.ttlMs) {
+			this.entries.delete(deviceId);
+			return null;
+		}
+		return {
+			...entry.carry,
+			trialFrom: null
+		};
+	}
+};
+//#endregion
 //#region src/stream-broker/webrtc/adaptive-controller.ts
 var TIER_ORDER = CAM_PROFILE_ORDER;
 /**
+* The cause as the wire (`WebrtcLadderDecision.cause`) can carry it. The wire
+* enum predates the try-climb, and widening it would make a server built
+* before it reject this broker's debug answer (the router validates output).
+* A trial revert is reported as what undelivered bytes are — `stall` when the
+* stall confirmed, else `loss` — and the climb hold carries the exact account
+* ("tried mid, reverted: delivery 0.60").
+*/
+function wireLadderCause(decision, stallConfirmMs) {
+	if (decision.cause !== "trial-revert") return { cause: decision.cause };
+	return {
+		cause: decision.stall.stalledForMs >= stallConfirmMs ? "stall" : "loss",
+		causeDetail: "trial-revert"
+	};
+}
+function positiveOrNull(v) {
+	return v !== null && Number.isFinite(v) && v > 0 ? v : null;
+}
+/**
 * 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
@@ -26285,7 +26731,16 @@ var TIER_ORDER = CAM_PROFILE_ORDER;
 *     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.
+*     failure of that tier in this session;
+*  4. the transport showing the CURRENT rung landing whole
+*     (`StallTracker.climbSafety`, a delivery ratio over one GOP — D635);
+*  5. capacity: evidence (REMB or the viewer's probe) clearing the next
+*     rung's bar confirms the climb; a MEASURED probe below it holds; with no
+*     evidence either way the ladder TRIES the rung on a clean path (delivery
+*     ≥ 0.95, loss < 1 %, RTT stable) and reverts within the rung's first
+*     window if it does not land, backing off 30 s → 10 min (D635, round 2).
+*
+* Every tick that does not promote leaves a {@link ClimbHold} naming why.
 */
 var AdaptiveController = class {
 	opts;
@@ -26306,6 +26761,16 @@ var AdaptiveController = class {
 	armed = false;
 	failures;
 	upgradeCount;
+	capacity = {
+		rembKbps: null,
+		probeKbps: null,
+		probeFresh: false
+	};
+	rtt = new RttWindow();
+	tryCarry;
+	/** Non-null while the current rung is a trial. */
+	trial;
+	hold = null;
 	constructor(opts) {
 		this.opts = opts;
 		this.tracker = new LossTracker(opts.config);
@@ -26313,6 +26778,16 @@ var AdaptiveController = class {
 		this.tier = opts.initialTier;
 		this.failures = new Map(opts.priorFailures ?? []);
 		this.upgradeCount = Math.max(0, opts.priorUpgradeCount ?? 0);
+		const carried = opts.tryClimb ?? NO_TRY_HISTORY;
+		this.tryCarry = carried.trialFrom === opts.initialTier ? {
+			...carried,
+			trialFrom: null
+		} : carried;
+		this.trial = this.tryCarry.trialFrom !== null ? new TrialWatch(this.tryCarry.trialFrom, opts.config) : null;
+	}
+	/** What the NEXT controller of this viewer session must inherit about tries. */
+	get tryClimbCarry() {
+		return this.tryCarry;
 	}
 	get currentTier() {
 		return this.tier;
@@ -26345,6 +26820,27 @@ var AdaptiveController = class {
 		this.stalls.observe(sample, now);
 	}
 	/**
+	* The capacity witnesses, kbps — `null` when unknown: the receiver's REMB
+	* (capped by what is sent, so evidence only FOR room) and the viewer's
+	* downlink probe for this session (a path measurement, evidence both ways).
+	* See `climb-capacity.ts`.
+	*/
+	onCapacity(evidence) {
+		this.capacity = {
+			rembKbps: positiveOrNull(evidence.rembKbps),
+			probeKbps: positiveOrNull(evidence.probeKbps),
+			probeFresh: evidence.probeFresh
+		};
+	}
+	/** The client's round-trip time, ms; null/0 = unknown. One of a try's conditions. */
+	onRtt(rttMs, now) {
+		this.rtt.observe(rttMs, now);
+	}
+	/** Why the ladder did not climb on the last evaluation; null = at the top, or it just moved. */
+	get climbHold() {
+		return this.hold;
+	}
+	/**
 	* Freeze the ladder for this evaluation instead of ticking it.
 	*
 	* Called while the session's track is NOT carrying the live source — D42
@@ -26365,6 +26861,8 @@ var AdaptiveController = class {
 			this.lastChangeAt = now;
 		}
 		this.healthySince = now;
+		this.trial?.restart();
+		this.setHold("suspended", now);
 		this.stalls.markChanged(now);
 	}
 	tick(now) {
@@ -26373,26 +26871,132 @@ var AdaptiveController = class {
 			this.healthySince = now;
 			this.lastChangeAt = now;
 		}
+		if (this.trial !== null && this.judgeTrial(now)) return;
 		if (this.stalls.isStalled(now)) {
 			this.healthySince = now;
+			this.hold = null;
 			this.handleFailing(now, "stall");
 			return;
 		}
 		if (this.tracker.isFailing(now)) {
 			this.healthySince = now;
+			this.hold = null;
 			this.handleFailing(now, "loss");
 			return;
 		}
-		if (!this.stalls.isClimbSafe(now)) {
+		const safety = this.stalls.climbSafety(now);
+		if (!safety.safe) {
 			this.healthySince = now;
+			this.setHold(safety.reason, now);
 			return;
 		}
 		if (!this.tracker.hasEvidence(now)) {
 			this.healthySince = now;
+			this.setHold("no-evidence", now);
 			return;
 		}
 		this.handleHealthy(now);
 	}
+	nextTier() {
+		const idx = TIER_ORDER.indexOf(this.tier);
+		return idx <= 0 ? null : TIER_ORDER[idx - 1] ?? null;
+	}
+	/**
+	* Record why this evaluation did not climb. At the top rung there is nothing
+	* to hold — except a `trial`, which names the rung being tried.
+	*/
+	setHold(code, now, extra = {}) {
+		const next = code === "trial" ? this.tier : this.nextTier();
+		if (next === null) {
+			this.hold = null;
+			return;
+		}
+		const ev = this.stalls.evidence(now);
+		const clockRunning = code === "warming" || code === "cooldown" || code === "capacity" || code === "try-unclean" || code === "try-backoff";
+		const nextTierKbps = this.opts.expectedTierKbps?.(next) ?? null;
+		this.hold = {
+			code,
+			nextTier: next,
+			deliveryRatio: ev.deliveryRatio,
+			deliveryWindowMs: ev.deliveryWindowMs,
+			climbDeliveryRatio: this.opts.config.climbDeliveryRatio,
+			capacityKbps: this.capacity.rembKbps,
+			probeKbps: this.capacity.probeKbps,
+			nextTierKbps,
+			capacityMargin: this.opts.config.climbCapacityMargin,
+			neededKbps: capacityBarKbps(next, nextTierKbps, this.opts.config.climbCapacityMargin),
+			tryBlockedBy: extra.tryBlockedBy ?? null,
+			tryDeliveryRatio: this.opts.config.tryClimbDeliveryRatio,
+			tryMaxLossRatio: this.opts.config.tryClimbMaxLossRatio,
+			retryInMs: code === "try-backoff" ? Math.max(0, this.tryCarry.notBefore - now) : null,
+			lastRevert: this.tryCarry.lastRevert,
+			trialForMs: code === "trial" ? extra.trialForMs ?? 0 : null,
+			trialMs: code === "trial" ? this.opts.config.trialMs : null,
+			healthyForMs: clockRunning ? now - this.healthySince : null,
+			requiredHealthyMs: this.requiredHealthyMs(next),
+			since: this.hold?.code === code ? this.hold.since : now
+		};
+	}
+	/**
+	* Judge the rung on trial. Returns true when this evaluation is consumed
+	* (still running, or reverted); false when the trial was just kept and the
+	* ordinary ladder takes over.
+	*/
+	judgeTrial(now) {
+		const watch = this.trial;
+		if (watch === null) return false;
+		const verdict = watch.judge(now, {
+			deliveryRatio: this.stalls.evidence(now).deliveryRatio,
+			clientReporting: this.stalls.isClientReporting,
+			stalled: this.stalls.isStalled(now),
+			lossFailing: this.tracker.isFailing(now)
+		});
+		if (verdict.kind === "running") {
+			this.healthySince = now;
+			this.setHold("trial", now, { trialForMs: verdict.forMs });
+			return true;
+		}
+		this.trial = null;
+		if (verdict.kind === "kept") {
+			this.tryCarry = NO_TRY_HISTORY;
+			this.healthySince = now;
+			return false;
+		}
+		const failures = this.tryCarry.failures + 1;
+		const tried = this.tier;
+		this.tryCarry = {
+			failures,
+			notBefore: now + tryBackoffMs(failures, this.opts.config.tryBackoffBaseMs, this.opts.config.tryBackoffMaxMs),
+			lastRevert: {
+				tier: tried,
+				deliveryRatio: verdict.deliveryRatio,
+				stalled: verdict.stalled,
+				at: now
+			},
+			trialFrom: null
+		};
+		this.hold = null;
+		this.tier = watch.from;
+		this.mtuReduced = false;
+		this.transcodeEngaged = false;
+		this.opts.onSwitchTier(watch.from, this.decisionAt(now, "trial-revert"));
+		this.commitChange(now);
+		this.healthySince = now;
+		return true;
+	}
+	/**
+	* Which clean-path condition refuses a TRY, or null when the path is clean.
+	* A client that sends no telemetry at all cannot measure delivery; there the
+	* loss path is the judge, as it was before delivery existed.
+	*/
+	tryBlocker(now) {
+		if (this.stalls.isTelemetryShared) return "shared-telemetry";
+		const ratio = this.stalls.evidence(now).deliveryRatio;
+		if (ratio === null ? this.stalls.isClientReporting : ratio < this.opts.config.tryClimbDeliveryRatio) return "delivery";
+		if (this.tracker.lossRatio() >= this.opts.config.tryClimbMaxLossRatio) return "loss";
+		if (this.rtt.stability(now) === "unstable") return "rtt";
+		return null;
+	}
 	canUpgrade(now) {
 		return now - this.lastChangeAt >= this.opts.config.minTimeBetweenChangesMs;
 	}
@@ -26413,11 +27017,12 @@ var AdaptiveController = class {
 		this.stalls.markChanged(now);
 	}
 	/** The measurement this decision rests on, snapshotted for the log line. */
-	decisionAt(now, cause) {
+	decisionAt(now, cause, trial = false) {
 		return {
 			cause,
 			lossRatio: this.tracker.lossRatio(),
-			stall: this.stalls.evidence(now)
+			stall: this.stalls.evidence(now),
+			trial
 		};
 	}
 	handleFailing(now, cause) {
@@ -26444,21 +27049,223 @@ var AdaptiveController = class {
 		}
 	}
 	handleHealthy(now) {
-		const idx = TIER_ORDER.indexOf(this.tier);
-		if (idx <= 0) return;
-		const next = TIER_ORDER[idx - 1];
-		if (now - this.healthySince < this.requiredHealthyMs(next)) return;
-		if (!this.canUpgrade(now)) return;
+		const next = this.nextTier();
+		if (next === null) {
+			this.hold = null;
+			return;
+		}
+		const capacity = judgeCapacity(this.capacity, next, this.opts.expectedTierKbps?.(next) ?? null, this.opts.config.climbCapacityMargin);
+		if (capacity.kind === "probe-short") {
+			this.setHold("capacity", now);
+			return;
+		}
+		if (capacity.kind === "none" && now < this.tryCarry.notBefore) {
+			this.setHold("try-backoff", now);
+			return;
+		}
+		if (now - this.healthySince < this.requiredHealthyMs(next)) {
+			this.setHold("warming", now);
+			return;
+		}
+		if (!this.canUpgrade(now)) {
+			this.setHold("cooldown", now);
+			return;
+		}
+		if (capacity.kind === "sufficient") {
+			this.promote(now, next, false);
+			return;
+		}
+		const blocker = this.tryBlocker(now);
+		if (blocker !== null) {
+			this.setHold("try-unclean", now, { tryBlockedBy: blocker });
+			return;
+		}
+		this.promote(now, next, true);
+	}
+	promote(now, next, trial) {
+		const from = this.tier;
+		this.hold = null;
 		this.tier = next;
 		this.mtuReduced = false;
 		this.transcodeEngaged = false;
 		this.upgradeCount += 1;
-		this.opts.onSwitchTier(next, this.decisionAt(now, "healthy"));
+		this.tryCarry = {
+			...this.tryCarry,
+			trialFrom: trial ? from : null
+		};
+		this.trial = trial ? new TrialWatch(from, this.opts.config) : null;
+		this.opts.onSwitchTier(next, this.decisionAt(now, "healthy", trial));
 		this.commitChange(now);
 		this.healthySince = now;
 	}
 };
 //#endregion
+//#region src/stream-broker/webrtc/climb-hold.ts
+/** The wire shape: the hold plus the line the broker logs. */
+function toWireClimbHold(h) {
+	return {
+		...h,
+		summary: describeClimbHold(h)
+	};
+}
+function seconds(ms) {
+	return `${(ms / 1e3).toFixed(1)}s`;
+}
+/** A rate, or "unknown" — never a fabricated 0 kbps (D393). */
+function kbps(v) {
+	return v === null ? "unknown" : `${String(Math.round(v))} kbps`;
+}
+function deliveryPart(h) {
+	if (h.deliveryRatio === null || h.deliveryWindowMs === null) return null;
+	return `delivery ${h.deliveryRatio.toFixed(2)} over ${seconds(h.deliveryWindowMs)}`;
+}
+/** `mid needs 2160 kbps (1800 × 1.2)`, or `(client threshold)` for an unmeasured rung. */
+function barPart(h) {
+	const basis = h.nextTierKbps !== null && h.nextTierKbps > 0 ? `(${String(Math.round(h.nextTierKbps))} × ${String(h.capacityMargin)})` : "(client threshold)";
+	return `${h.nextTier} needs ${kbps(h.neededKbps)} ${basis}`;
+}
+function witnesses(h) {
+	return `${h.capacityKbps === null ? "no REMB" : `REMB ${kbps(h.capacityKbps)}`}, ${h.probeKbps === null ? "no probe" : `probe ${kbps(h.probeKbps)}`}`;
+}
+function blockerPart(h) {
+	switch (h.tryBlockedBy) {
+		case "delivery": return h.deliveryRatio === null ? "delivery not measured" : `delivery ${h.deliveryRatio.toFixed(2)} < ${h.tryDeliveryRatio.toFixed(2)}`;
+		case "loss": return `loss ≥ ${String(Math.round(h.tryMaxLossRatio * 1e3) / 10)}%`;
+		case "rtt": return "RTT unstable";
+		case "shared-telemetry": return "another viewer shares this camera's telemetry";
+		case null: return "unknown";
+	}
+}
+function revertPart(h) {
+	const r = h.lastRevert;
+	if (r === null) return "a try reverted";
+	const why = r.stalled ? "stall" : r.deliveryRatio === null ? "loss" : `delivery ${r.deliveryRatio.toFixed(2)}`;
+	return `tried ${r.tier}, reverted: ${why}`;
+}
+/**
+* One line, English, numbers included — the same text the broker logs and the
+* viewer shows under its localized hold label. Every number is one the
+* controller actually used; an unknown one is said to be unknown.
+*/
+function describeClimbHold(h) {
+	const delivery = deliveryPart(h);
+	switch (h.code) {
+		case "stall-building": return `held: stall building (${delivery ?? "delivery unknown"})`;
+		case "delivery": return delivery === null ? "held: delivery not yet measured over one GOP" : `held: ${delivery} < ${h.climbDeliveryRatio.toFixed(2)}`;
+		case "no-evidence": return "held: no receiver feedback in the loss window";
+		case "warming": return `climbing: healthy ${seconds(h.healthyForMs ?? 0)} of ${seconds(h.requiredHealthyMs ?? 0)} before ${h.nextTier}`;
+		case "cooldown": return "held: too soon after the last change";
+		case "capacity": return `held: probe ${kbps(h.probeKbps)}, ${h.capacityKbps === null ? "no REMB" : `REMB ${kbps(h.capacityKbps)}`} < ${barPart(h)}`;
+		case "try-unclean": return `held: no capacity evidence for ${h.nextTier} (${witnesses(h)}); not clean enough to try: ${blockerPart(h)}`;
+		case "try-backoff": return `held: ${revertPart(h)}; next try in ${seconds(h.retryInMs ?? 0)}`;
+		case "trial": return `trying ${h.nextTier}: ${seconds(h.trialForMs ?? 0)} of ${seconds(h.trialMs ?? 0)} (reverts if it does not land)`;
+		case "suspended": return "held: recorded playback on the track (ladder suspended)";
+	}
+}
+/**
+* Which hold changes deserve a log line (review m3). A code logs when it
+* differs from the last one logged AND has not itself been logged within
+* `quietMs` — a link hovering at 0.90–0.95 delivery cycles delivery →
+* warming → try-unclean and used to write a line every 4–8 s for ever.
+* Progress (`warming`, `trial`) never logs; the switch line covers moves.
+*/
+var HoldLogGate = class {
+	quietMs;
+	last = null;
+	loggedAt = /* @__PURE__ */ new Map();
+	constructor(quietMs) {
+		this.quietMs = quietMs;
+	}
+	shouldLog(code, now) {
+		if (code === "warming" || code === "trial") return false;
+		if (code === this.last) return false;
+		const at = this.loggedAt.get(code);
+		if (at !== void 0 && now - at < this.quietMs) return false;
+		this.last = code;
+		this.loggedAt.set(code, now);
+		return true;
+	}
+};
+//#endregion
+//#region src/stream-broker/webrtc/rung-bitrate.ts
+/**
+* Shortest lifetime whose average means anything: 4 000 ms ≈ one GOP on the
+* cameras this hub serves; less than that is one IDR divided by nothing.
+*/
+var MIN_AVERAGE_UPTIME_MS = 4e3;
+function expectedRungKbps(stats) {
+	const lifetime = stats.totalBytes > 0 && stats.uptimeMs >= MIN_AVERAGE_UPTIME_MS ? Math.round(stats.totalBytes * 8 / stats.uptimeMs) : null;
+	const windowKbps = stats.status === "streaming" && stats.bitrateKbps > 0 ? stats.bitrateKbps : null;
+	if (windowKbps === null) return lifetime;
+	return lifetime === null ? windowKbps : Math.max(windowKbps, lifetime);
+}
+/** The client's probe cache TTL (`DOWNLINK_TTL_MS`): the oldest a hinted probe can be. */
+var HINT_PROBE_MAX_AGE_MS = 3e4;
+function mbpsToKbps(mbps) {
+	return mbps !== void 0 && Number.isFinite(mbps) && mbps > 0 ? mbps * 1e3 : null;
+}
+/** The probe an offer carried, dated conservatively; null when it carried none. */
+function probeFromHints(downlinkMbps, now) {
+	const kbps = mbpsToKbps(downlinkMbps);
+	return kbps === null ? null : {
+		kbps,
+		at: now - HINT_PROBE_MAX_AGE_MS
+	};
+}
+/** The probe a telemetry report carried; null when it carried none. */
+function probeFromReport(report, now) {
+	const kbps = mbpsToKbps(report.downlinkMbps);
+	if (kbps === null) return null;
+	return {
+		kbps,
+		at: now - Math.max(0, report.reportAgeMs) - Math.max(0, report.downlinkAgeMs)
+	};
+}
+/** The more recent of two probes (either may be absent). */
+function newerProbe(a, b) {
+	if (a === null) return b;
+	if (b === null) return a;
+	return b.at >= a.at ? b : a;
+}
+function isProbeFresh(probe, now) {
+	return probe !== null && now - probe.at <= 12e4;
+}
+/**
+* How long the broker keeps a device's probe at all. 600 000 ms (10 min, the
+* try-backoff cap). A SHORT probe holds a climb until a newer probe replaces
+* it — and a viewer that cannot probe (no token yet, a share link, whose token
+* is not session-grade) never supplies one, so without an end one viewer's
+* 1.2 Mbps reading would hold every such viewer of the camera on `capacity`
+* until the broker restarted (review N1).
+*/
+var PROBE_MEMORY_TTL_MS = 6e5;
+/** The newest probe per device, bounded in time and forgotten with the device's last session. */
+var DeviceProbeMemory = class {
+	ttlMs;
+	probes = /* @__PURE__ */ new Map();
+	constructor(ttlMs) {
+		this.ttlMs = ttlMs;
+	}
+	/** Keep `probe` if it is newer than what is held; an absent one changes nothing. */
+	record(deviceId, probe) {
+		const kept = newerProbe(this.probes.get(deviceId) ?? null, probe);
+		if (kept !== null) this.probes.set(deviceId, kept);
+	}
+	get(deviceId, now) {
+		const probe = this.probes.get(deviceId);
+		if (probe === void 0) return null;
+		if (now - probe.at > this.ttlMs) {
+			this.probes.delete(deviceId);
+			return null;
+		}
+		return probe;
+	}
+	/** The device's last adaptive session ended: nobody's probe speaks for the next viewer. */
+	forget(deviceId) {
+		this.probes.delete(deviceId);
+	}
+};
+//#endregion
 //#region src/stream-broker/webrtc/session-debug.ts
 /** `<deviceId>/<camStreamId>` → the camStreamId, or null when it is not one. */
 function camStreamIdOf(brokerId) {
@@ -26497,7 +27304,8 @@ var DEAD = {
 	trackMode: null,
 	lastDecision: null,
 	tierFailures: [],
-	upgradeCount: null
+	upgradeCount: null,
+	climbHold: null
 };
 function projectSessionDebug(input) {
 	const { session } = input;
@@ -26534,7 +27342,8 @@ function projectSessionDebug(input) {
 			tier,
 			failures
 		})),
-		upgradeCount: input.ladder?.upgradeCount ?? null
+		upgradeCount: input.ladder?.upgradeCount ?? null,
+		climbHold: input.ladder?.climbHold ?? null
 	};
 }
 var PLAYBACK_PROFILE_FALLBACK_ORDER = [
@@ -33511,24 +34320,13 @@ function pickAdaptiveTier(input) {
 *
 * Flow: Camera → RTSP → Broker → EncodedPacket → RTP packetization → WebRTC
 */
-/** How often the adaptive controller re-evaluates the ladder (ms). */
-var ADAPTIVE_TICK_MS = 2e3;
-/** Ladder tuning shared by every adaptive session. */
-var ADAPTIVE_CONFIG = {
-	analyzeWindowMs: 15e3,
-	minFailPercent: .05,
-	waitAfterResetMs: 8e3,
-	upgradeHealthyMs: 4e3,
-	upgradeHealthyGrowthFactor: 3,
-	maxProgressiveUpgradeHealthyMs: 3e4,
-	minTimeBetweenChangesMs: 4e3,
-	maxUpgradeBackoffMs: 9e5,
-	stallKbpsFloor: 64,
-	stallConfirmMs: 6e3,
-	recoverKbpsFloor: 128,
-	waitAfterChangeMs: 8e3,
-	maxClientSampleAgeMs: 1e4
-};
+/**
+* A hold code that has been logged stays quiet this long before it may log
+* again (`HoldLogGate`). 60 000 ms: a hovering link changes code every 4–8 s.
+*/
+var HOLD_LOG_QUIET_MS = 6e4;
+/** A failing adaptive tick logs at most once per this long, per session. */
+var TICK_FAILURE_LOG_QUIET_MS = 6e4;
 /**
 * True when `broker` is an in-process StreamBroker exposing the Opus egress
 * controls. Uses `in` narrowing + `typeof` checks (no cast) so the returned
@@ -33765,6 +34563,14 @@ var BrokerWebrtcServer = class {
 	*/
 	lastLadderDecision = /* @__PURE__ */ new Map();
 	/**
+	* Try-climb memory per DEVICE (review I4): a new viewer session of a camera
+	* whose next rung keeps failing inherits the backoff instead of starting at
+	* try #1. Forgotten after the backoff cap without a refresh.
+	*/
+	deviceTryMemory = new DeviceTryMemory(ADAPTIVE_CONFIG.tryBackoffMaxMs);
+	/** The newest viewer probe per device, from offers and telemetry (`probe-evidence.ts`). */
+	deviceProbe = new DeviceProbeMemory(PROBE_MEMORY_TTL_MS);
+	/**
 	* brokerId → where its media is ingested. Injected by the manager, which
 	* owns the ownership map; unset (or a null answer) means UNRESOLVED, and
 	* the overlay says so rather than naming the local node.
@@ -34762,7 +35568,8 @@ var BrokerWebrtcServer = class {
 		};
 		if (streamId.endsWith("/adaptive")) {
 			const initialTier = this.profileTierResolver?.(brokerId) ?? "high";
-			this.startAdaptive(entry, deviceId, initialTier, sessionId, intent?.failures, intent?.upgradeCount);
+			this.recordDeviceProbe(deviceId, probeFromHints(hints.downlinkMbps, Date.now()));
+			this.startAdaptive(entry, deviceId, initialTier, sessionId, intent);
 		}
 		return {
 			sessionId,
@@ -34880,11 +35687,13 @@ var BrokerWebrtcServer = class {
 		const ladder = controller !== void 0 ? {
 			lastDecision: decision,
 			failures: [...controller.failureCounts],
-			upgradeCount: controller.successfulUpgradeCount
+			upgradeCount: controller.successfulUpgradeCount,
+			climbHold: controller.climbHold === null ? null : toWireClimbHold(controller.climbHold)
 		} : decision !== null ? {
 			lastDecision: decision,
 			failures: [],
-			upgradeCount: 0
+			upgradeCount: 0,
+			climbHold: null
 		} : null;
 		let brokerStats = null;
 		try {
@@ -34927,7 +35736,7 @@ var BrokerWebrtcServer = class {
 	/** Snapshot the ladder's move so the overlay can name it later. */
 	recordLadderDecision(sessionId, decision, tier, forcedTranscodeDown) {
 		this.lastLadderDecision.set(sessionId, {
-			cause: decision.cause,
+			...wireLadderCause(decision, ADAPTIVE_CONFIG.stallConfirmMs),
 			tier,
 			forcedTranscodeDown,
 			lossRatio: decision.lossRatio,
@@ -34938,6 +35747,39 @@ var BrokerWebrtcServer = class {
 		});
 	}
 	/**
+	* The IDR interval the broker feeding a session measured, or null when it
+	* has measured none (a fresh broker reports 0). Sizes the delivery window.
+	*/
+	brokerIdrIntervalMs(brokerId) {
+		try {
+			const idr = this.brokers.get(brokerId)?.getStats().idrIntervalMs ?? null;
+			return idr !== null && idr > 0 ? idr : null;
+		} catch {
+			return null;
+		}
+	}
+	/**
+	* The expected bitrate of `tier` for this device, from the broker serving
+	* that rung — null when no such broker is registered here or it has
+	* measured nothing. Unknown never vetoes a climb (D315/D393).
+	*/
+	expectedTierKbps(deviceId, tier) {
+		const prefix = `${String(deviceId)}/`;
+		const candidates = [];
+		for (const [bid, broker] of this.brokers) if (bid.startsWith(prefix)) candidates.push({
+			brokerId: bid,
+			tier: this.profileTierResolver?.(bid) ?? null,
+			broker
+		});
+		const match = preferLiveAdaptiveCandidates(candidates).find((c) => c.tier === tier);
+		if (match === void 0) return null;
+		try {
+			return expectedRungKbps(match.broker.getStats());
+		} catch {
+			return null;
+		}
+	}
+	/**
 	* Wire an {@link AdaptiveController} to a freshly-created adaptive session.
 	* The controller is fed loss from two sources — RTCP Receiver Reports
 	* (`onReceiverReport`) and, when injected, the device's client-reported
@@ -34954,12 +35796,20 @@ 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, priorFailures, priorUpgradeCount) {
+	startAdaptive(entry, deviceId, initialTier, sessionId, intent) {
+		const startedAt = Date.now();
+		/** Rung bitrates, looked up at most once per tier per tick (review m12). */
+		const rungKbps = /* @__PURE__ */ new Map();
 		const controller = new AdaptiveController({
 			initialTier,
-			priorFailures,
-			priorUpgradeCount,
+			priorFailures: intent?.failures,
+			priorUpgradeCount: intent?.upgradeCount,
+			tryClimb: intent?.tryClimb ?? this.deviceTryMemory.get(deviceId, startedAt) ?? void 0,
 			config: ADAPTIVE_CONFIG,
+			expectedTierKbps: (tier) => {
+				if (!rungKbps.has(tier)) rungKbps.set(tier, this.expectedTierKbps(deviceId, tier));
+				return rungKbps.get(tier) ?? null;
+			},
 			onSwitchTier: (tier, decision) => {
 				this.recordLadderDecision(sessionId, decision, tier, false);
 				this.switchSessionTier(entry, deviceId, tier, sessionId, false, decision);
@@ -34976,6 +35826,9 @@ var BrokerWebrtcServer = class {
 						reason: decision.cause,
 						lossRatio: Number(decision.lossRatio.toFixed(4)),
 						clientKbps: decision.stall.clientKbps,
+						sentKbps: decision.stall.sentKbps,
+						deliveryRatio: decision.stall.deliveryRatio,
+						deliveryWindowMs: decision.stall.deliveryWindowMs,
 						stalledForMs: decision.stall.stalledForMs,
 						serverSending: decision.stall.serverSending
 					}
@@ -34995,14 +35848,39 @@ var BrokerWebrtcServer = class {
 		*  sending?" half of the stall verdict. */
 		let lastRtpSent = entry.session.rtpPacketsSentTotal;
 		const CLIENT_LOSS_SPAN = 1e3;
+		const meter = new DeliveryMeter(ADAPTIVE_DELIVERY_CONFIG, deliveryMeterStart(startedAt, intent !== void 0, ADAPTIVE_CONFIG.waitAfterChangeMs));
+		const holdLog = new HoldLogGate(HOLD_LOG_QUIET_MS);
+		let lastTickFailureLogAt = Number.NEGATIVE_INFINITY;
+		const logHoldChange = (now) => {
+			const hold = controller.climbHold;
+			if (hold === null || !holdLog.shouldLog(hold.code, now)) return;
+			this.logger.info("adaptive: climb held", {
+				tags: { deviceId },
+				meta: {
+					sessionId,
+					deviceId,
+					tier: controller.currentTier,
+					nextTier: hold.nextTier,
+					code: hold.code,
+					summary: describeClimbHold(hold),
+					deliveryRatio: hold.deliveryRatio,
+					deliveryWindowMs: hold.deliveryWindowMs,
+					capacityKbps: hold.capacityKbps,
+					probeKbps: hold.probeKbps,
+					nextTierKbps: hold.nextTierKbps
+				}
+			});
+		};
 		entry.adaptiveTimer = setInterval(() => {
 			if (tickInFlight) return;
 			tickInFlight = true;
 			(async () => {
 				try {
+					rungKbps.clear();
 					if (entry.timeline?.currentMode === "recorded") {
 						controller.suspend(Date.now());
 						lastRtpSent = entry.session.rtpPacketsSentTotal;
+						logHoldChange(Date.now());
 						return;
 					}
 					const client = this.clientNetworkStats ? await this.clientNetworkStats(deviceId) : null;
@@ -35010,11 +35888,15 @@ var BrokerWebrtcServer = class {
 					const rtpSent = entry.session.rtpPacketsSentTotal;
 					const serverSending = rtpSent > lastRtpSent;
 					lastRtpSent = rtpSent;
-					controller.onThroughput({
-						clientKbps: client ? client.estimatedBandwidthKbps : null,
-						clientSampleAgeMs: client ? Math.max(0, now - client.lastUpdated) : null,
-						serverSending
-					}, now);
+					this.feedAdaptive({
+						entry,
+						deviceId,
+						controller,
+						meter,
+						client,
+						serverSending,
+						now
+					});
 					const pct = client?.packetLossPercent ?? null;
 					if (pct !== null && pct !== void 0) {
 						clientHighestSequence += CLIENT_LOSS_SPAN;
@@ -35025,6 +35907,21 @@ var BrokerWebrtcServer = class {
 						}, now);
 					}
 					controller.tick(now);
+					this.deviceTryMemory.set(deviceId, controller.tryClimbCarry, now);
+					logHoldChange(now);
+				} catch (err) {
+					const now = Date.now();
+					if (now - lastTickFailureLogAt >= TICK_FAILURE_LOG_QUIET_MS) {
+						lastTickFailureLogAt = now;
+						this.logger.warn("adaptive: tick failed", {
+							tags: { deviceId },
+							meta: {
+								sessionId,
+								deviceId,
+								error: errMsg(err)
+							}
+						});
+					}
 				} finally {
 					tickInFlight = false;
 				}
@@ -35032,6 +35929,55 @@ var BrokerWebrtcServer = class {
 		}, ADAPTIVE_TICK_MS);
 	}
 	/**
+	* One evaluation's transport, capacity and RTT evidence into the controller.
+	* The device-scoped client record is used as this session's own only when
+	* this is the device's ONLY adaptive session here (review I2).
+	*/
+	feedAdaptive(feed) {
+		const { entry, deviceId, controller, meter, client, now } = feed;
+		const sessionsOnDevice = this.adaptiveSessionCount(deviceId);
+		const shared = sessionsOnDevice > 1;
+		let rttMs = null;
+		if (client) {
+			const reportAgeMs = Math.max(0, now - client.lastUpdated);
+			meter.observe(client.estimatedBandwidthKbps, client.lastUpdated);
+			if (!shared) {
+				this.recordDeviceProbe(deviceId, probeFromReport({
+					downlinkMbps: client.downlinkMbps,
+					downlinkAgeMs: client.downlinkAgeMs ?? 0,
+					reportAgeMs
+				}, now));
+				if (reportAgeMs <= ADAPTIVE_DELIVERY_CONFIG.maxClientSampleAgeMs) rttMs = client.rttMs ?? null;
+			}
+		}
+		const history = entry.session.sentVideoHistory;
+		controller.onThroughput(buildStallSample({
+			delivery: meter.evaluate(history, deliveryWindowMs(this.brokerIdrIntervalMs(entry.brokerId), ADAPTIVE_DELIVERY_CONFIG), now),
+			recent: meter.evaluateNewest(history, now),
+			clientReporting: meter.isReporting(now),
+			serverSending: feed.serverSending,
+			adaptiveSessionsOnDevice: sessionsOnDevice
+		}), now);
+		const probe = this.deviceProbe.get(deviceId, now);
+		controller.onCapacity({
+			rembKbps: entry.session.receiverEstimateKbps(now),
+			probeKbps: probe?.kbps ?? null,
+			probeFresh: isProbeFresh(probe, now)
+		});
+		controller.onRtt(rttMs, now);
+	}
+	/** Adaptive sessions of `deviceId` currently on this broker server. */
+	adaptiveSessionCount(deviceId) {
+		const prefix = `${String(deviceId)}/`;
+		let count = 0;
+		for (const s of this.sessions.values()) if (s.adaptiveController !== void 0 && s.brokerId.startsWith(prefix)) count += 1;
+		return count;
+	}
+	/** Keep the newest probe per device; an absent one changes nothing. */
+	recordDeviceProbe(deviceId, probe) {
+		this.deviceProbe.record(deviceId, probe);
+	}
+	/**
 	* Schedule an adaptive tier switch via a close-and-recreate re-offer.
 	*
 	* Records the controller's desired tier (+ forced transcode-down) in
@@ -35048,11 +35994,18 @@ var BrokerWebrtcServer = class {
 		const prev = this.adaptiveIntent.get(sessionId);
 		const failures = new Map(entry.adaptiveController?.failureCounts ?? prev?.failures);
 		const upgradeCount = entry.adaptiveController?.successfulUpgradeCount ?? prev?.upgradeCount ?? 0;
+		const tryClimb = entry.adaptiveController?.tryClimbCarry ?? prev?.tryClimb;
 		this.adaptiveIntent.set(sessionId, {
 			prefersTier: tier,
 			forceTranscodeDown: forceTranscodeDown || (prev?.forceTranscodeDown ?? false),
 			failures,
-			upgradeCount
+			upgradeCount,
+			tryClimb: tryClimb ?? {
+				failures: 0,
+				notBefore: 0,
+				lastRevert: null,
+				trialFrom: null
+			}
 		});
 		const epoch = (entry.session.pendingRenegotiation?.epoch ?? 0) + 1;
 		entry.session.pendingRenegotiation = {
@@ -35070,8 +36023,12 @@ var BrokerWebrtcServer = class {
 				failures: Object.fromEntries(failures),
 				upgradeCount,
 				reason: decision?.cause ?? "unknown",
+				trial: decision?.trial ?? false,
 				lossRatio: decision ? Number(decision.lossRatio.toFixed(4)) : null,
 				clientKbps: decision?.stall.clientKbps ?? null,
+				sentKbps: decision?.stall.sentKbps ?? null,
+				deliveryRatio: decision?.stall.deliveryRatio ?? null,
+				deliveryWindowMs: decision?.stall.deliveryWindowMs ?? null,
 				stalledForMs: decision?.stall.stalledForMs ?? null,
 				serverSending: decision?.stall.serverSending ?? null
 			}
@@ -35088,6 +36045,10 @@ var BrokerWebrtcServer = class {
 		}
 		if (!brokerStillServed && !this.stopped) this.brokerLinger.hold(entry.brokerId);
 		this.adaptiveIntent.delete(sessionId);
+		if (entry.adaptiveController !== void 0) {
+			const deviceId = deviceIdFromBrokerId(entry.brokerId);
+			if (this.adaptiveSessionCount(deviceId) === 0) this.deviceProbe.forget(deviceId);
+		}
 		this.pruneLadderDecisions();
 		if (entry.adaptiveTimer) clearInterval(entry.adaptiveTimer);
 		if (entry.attributionTimer) clearTimeout(entry.attributionTimer);
@@ -36248,7 +37209,10 @@ var StreamBrokerAddon = class extends BaseAddon {
 					return {
 						packetLossPercent: client.packetLossPercent,
 						estimatedBandwidthKbps: client.estimatedBandwidthKbps,
-						lastUpdated: client.lastUpdated
+						lastUpdated: client.lastUpdated,
+						rttMs: client.rttMs,
+						...client.downlinkMbps !== void 0 ? { downlinkMbps: client.downlinkMbps } : {},
+						...client.downlinkAgeMs !== void 0 ? { downlinkAgeMs: client.downlinkAgeMs } : {}
 					};
 				} catch {
 					return null;