@camstack/addon-pipeline 1.2.268 → 1.2.269

package/dist/stream-broker/index.js

@@ -3,12 +3,12 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 const require_chunk = require("../chunk-emK7D4bc.js");
-const require_dist = require("../dist-C7CvyImc.js");
-const require_node = require("../node-CjN6Vze9.js");
+const require_dist = require("../dist-CkNVb7Zh.js");
+const require_node = require("../node-CqC8R84-.js");
 const require_restream_intent = require("../restream-intent-7uDNqMKs.js");
 const require_remote_restream = require("../remote-restream-CO36Sr30.js");
 const require_retire_root_keys = require("../retire-root-keys-Csb8z2f3.js");
-const require_segment_demux_js = require("../segment-demux-js-bfaGjVqq.js");
+const require_segment_demux_js = require("../segment-demux-js-Bu-_Q7Um.js");
 let node_os = require("node:os");
 node_os = require_chunk.__toESM(node_os);
 let node_crypto = require("node:crypto");
@@ -495,6 +495,8 @@ function logBannerArgs(level) {
 }
 //#endregion
 //#region src/shared/ffmpeg-decode-args.ts
+/** Default DRM render node used for the VA-API / QSV hardware decode path. */
+var DEFAULT_VAAPI_RENDER_DEVICE = "/dev/dri/renderD128";
 /**
 * Canonical decode-hwaccel preference order for the ffmpeg-subprocess decoder.
 *
@@ -5281,6 +5283,26 @@ function decideAudioPlaneAction(observation, state, nowMs) {
 * "Device creation failed: -12 … Cannot allocate memory". Every egress child
 * therefore spends ~3 s dying before its own software retry rescues it.
 *
+* ## CORRECTION (2026-09-18): that `-12` was not a resource condition
+*
+* The two runners were not competing for a device — they were running
+* DIFFERENT BINARIES. The decoder addon reached a capable ffmpeg; the broker
+* reached the downloaded static build, which has no VAAPI compiled in at all
+* (`hwaccels: vdpau`). `-12` is what fftools prints when
+* `av_hwdevice_ctx_alloc` returns NULL because the type is not in the build:
+* the NAME parses, so the request looks valid and the device simply cannot
+* exist. It READS as a shortage and is a property of the binary (D536).
+*
+* That is why it "recurred forever on a hub where it has never once
+* succeeded": there was nothing to recover. The fix is upstream of this file —
+* `TranscodePipelineManager` now asks the binary (`ffmpeg -hwaccels`) and
+* refuses a backend it does not carry, so this quarantine never sees that
+* class of failure again.
+*
+* Everything below still stands for what remains: a backend the binary HAS and
+* the device still refuses. That one is a genuine runtime condition and can
+* clear, which is exactly why this is a quarantine and not a tombstone.
+*
 * That was already reported — `EgressTranscodeManager.onDecodeHwAccelFailed`
 * poisoned the broker's 60 s `egressHwAccelCache`. The memo is the wrong shape
 * for the verdict: it exists to avoid a per-session cross-process
@@ -5292,10 +5314,11 @@ function decideAudioPlaneAction(observation, state, nowMs) {
 *
 * ## Why this is a quarantine and not a tombstone
 *
-* A permanent verdict is wrong for the failure that is actually observed:
-* ENOMEM on device creation is a RESOURCE condition, and a resource condition
-* can clear (the operator gives the container more of the device, another
-* process releases it). A process that decided "never again" at 03:00 would
+* A permanent verdict is wrong for the failure this file is now left with:
+* a device that exists in the build and still refuses is a RESOURCE condition,
+* and a resource condition can clear (the operator gives the container more of
+* the device, another process releases it). The build-property case — the one
+* that produced the measurements above — no longer reaches here at all. A process that decided "never again" at 03:00 would
 * still be decoding in software at noon with a working accelerator, and nothing
 * would ever say so.
 *
@@ -5433,36 +5456,54 @@ function classifyDecodeHwAccel(setting) {
 function toAudioSidecarCodec(audio) {
 	return audio === "aac" || audio === "opus" || audio === "pcmu" ? audio : null;
 }
-var KNOWN_ENCODERS = new Set([
-	"libx264",
-	"libx265",
-	"h264_videotoolbox",
-	"hevc_videotoolbox",
-	"h264_vaapi",
-	"hevc_vaapi",
-	"h264_qsv",
-	"hevc_qsv",
-	"h264_nvenc",
-	"hevc_nvenc",
-	"h264_amf",
-	"hevc_amf"
-]);
-/** Type guard — an encoder id the shared builder knows how to emit. */
-function isKnownEncoder(value) {
-	return KNOWN_ENCODERS.has(value);
-}
 /**
-* Pick the video encoder, honouring the `hwAccel` preference. `'none'`/`'copy'`
-* force the software ENCODER too, so a software-decode preference yields a
-* fully software — and therefore maximally compatible — transcode. An encoder
-* the shared builder does not know falls back to software rather than being
-* passed through unchecked.
-*/
-function pickVideoEncoder(target, encoders, hwAccel) {
-	const software = target === "H264" ? "libx264" : "libx265";
-	if (hwAccel === "none" || hwAccel === "copy" || !encoders) return software;
-	const picked = target === "H264" ? encoders.defaultH264 : encoders.defaultH265;
-	return isKnownEncoder(picked) ? picked : software;
+* Choose the video encoder — separately from the DECODE preference, which is
+* the whole point.
+*
+* {@link pickVideoEncoder} folded the two together: `hwAccel: 'copy'` meant
+* "software everything". But `copy` is this fleet's decode DEFAULT for a real
+* reason — hardware decode hard-fails on a fragile HEVC source — and it was
+* quietly deciding the encoder as well. On a hub with a working Intel iGPU
+* that put every egress and derived transcode on `libx264`, spending cores
+* this box does not have, while the GPU idled. A software decode can feed a
+* hardware encoder (`hwupload` is exactly that), and the encode is where the
+* CPU goes.
+*
+* Three things can send it back to the CPU, and each is NAMED so the caller
+* can say which — a silent software transcode is the thing this exists to end:
+*
+* - `operator-forced-software` — someone asked for `none`. Honoured.
+* - `no-hardware-on-node` — the hwaccel resolver offers nothing.
+* - `binary-lacks-encoder` — the node has the hardware and THIS ffmpeg cannot
+*   use it. That is a build property, not a resource condition (D536).
+*
+* An UNKNOWN encoder list (`null`, a probe that failed) is not a "no": we
+* could not ask, so the hardware encoder is still attempted and ffmpeg's own
+* failure is the answer. Reading "unknown" as "unsupported" would keep a
+* capable node in software forever on one bad probe.
+*/
+function chooseVideoEncoder(input) {
+	const software = input.target === "H264" ? "libx264" : "libx265";
+	const fallback = (reason) => ({
+		encoder: software,
+		hwEncodeDevice: null,
+		softwareReason: reason
+	});
+	if (input.hwAccelSetting === "none") return fallback("operator-forced-software");
+	const backend = input.backend === null ? null : input.backend.toLowerCase();
+	if (backend === null) return fallback("no-hardware-on-node");
+	const ids = ENCODER_IDS_BY_BACKEND[backend];
+	if (!ids) return fallback("no-hardware-on-node");
+	const encoder = input.target === "H264" ? ids.h264 : ids.h265;
+	if (input.binaryEncoders !== null && !input.binaryEncoders.has(encoder)) return fallback("binary-lacks-encoder");
+	return {
+		encoder,
+		hwEncodeDevice: backend === "vaapi" ? {
+			kind: "vaapi",
+			renderNode: input.renderNode
+		} : null,
+		softwareReason: null
+	};
 }
 /**
 * The h264/hevc hardware ENCODER ids for a decode-hwaccel backend name — a
@@ -5495,24 +5536,6 @@ var ENCODER_IDS_BY_BACKEND = {
 	}
 };
 /**
-* Build the {@link HardwareEncoders} default pair for THIS node's decode
-* backend, resolved LOCALLY from `ctx.kernel.hwaccel` — WITHOUT probing
-* `ffmpeg -encoders` through the `platform-probe` singleton, whose per-node
-* `nodePin` does not survive a forked agent child's link chain (it answers with
-* the HUB's encoders). Returns `null` for software / an unmapped backend.
-*/
-function localHardwareEncoders(backend) {
-	if (backend === null) return null;
-	const ids = ENCODER_IDS_BY_BACKEND[backend.toLowerCase()];
-	if (!ids) return null;
-	return {
-		encoders: [],
-		defaultH264: ids.h264,
-		defaultH265: ids.h265,
-		probedAt: Date.now()
-	};
-}
-/**
 * Translate the broker's transcode request into the shared
 * {@link FfmpegInvocation}. Emits no arguments itself — `buildFfmpegArgs` from
 * `@camstack/types` does that, and it is the only thing that may.
@@ -5526,6 +5549,7 @@ function brokerTranscodeInvocation(inv) {
 	return {
 		logLevel: "warning",
 		decodeHwAccel: inv.decodeHwAccel,
+		...inv.hwEncodeDevice ? { hwEncodeDevice: inv.hwEncodeDevice } : {},
 		input: {
 			url: inv.sourceUrl,
 			rtspTransport: "tcp"
@@ -16280,6 +16304,9 @@ var TranscodePipelineManager = class {
 	/** In-flight transcode starts, keyed by pipeline key — single-flight the
 	*  async egress start so concurrent acquires share one egress. */
 	pending = /* @__PURE__ */ new Map();
+	/** What the ffmpeg at a path can do, asked once. `null` = could not ask. */
+	binaryCapabilities = /* @__PURE__ */ new Map();
+	probeFfmpeg;
 	logger;
 	hwaccel;
 	cameraStreamLookup;
@@ -16299,6 +16326,7 @@ var TranscodePipelineManager = class {
 		this.resolveProfileSource = opts.resolveProfileSource ?? null;
 		this.releaseGraceMs = opts.releaseGraceMs ?? 5e3;
 		this.ffmpegConfig = opts.ffmpegConfig ?? (() => DEFAULT_FFMPEG_CONFIG);
+		this.probeFfmpeg = opts.probeFfmpeg ?? require_node.probeFfmpegBinary;
 		this.resolveStreamHwAccel = opts.resolveStreamHwAccel ?? null;
 		this.spawnFn = opts.spawnFn ?? node_child_process.spawn;
 		this.acquireChannel = opts.acquireChannel ?? null;
@@ -16371,8 +16399,33 @@ var TranscodePipelineManager = class {
 		if (!this.acquireChannel) throw new Error("getStreamWithCodec: transcode egress not wired (acquireChannel missing)");
 		const cfg = this.ffmpegConfig();
 		const effectiveHwAccel = this.effectiveHwAccelSetting(opts.deviceId, opts.camStreamId, cfg.hwAccel);
-		const encoders = await this.resolveHardwareEncoders();
-		const encoder = pickVideoEncoder(opts.targetCodec, encoders, effectiveHwAccel);
+		const choice = chooseVideoEncoder({
+			target: opts.targetCodec,
+			backend: await this.resolveHardwareBackend(),
+			binaryEncoders: await this.resolveBinaryEncoders(cfg.binaryPath),
+			hwAccelSetting: effectiveHwAccel,
+			renderNode: DEFAULT_VAAPI_RENDER_DEVICE
+		});
+		const encoder = choice.encoder;
+		if (choice.softwareReason !== null) this.logger.error("transcode is running on the CPU — a software encode is work the hardware was supposed to do", {
+			tags: { deviceId: opts.deviceId },
+			meta: {
+				reason: choice.softwareReason,
+				encoder,
+				camStreamId: opts.camStreamId,
+				targetCodec: opts.targetCodec,
+				hwAccelSetting: effectiveHwAccel,
+				ffmpeg: cfg.binaryPath
+			}
+		});
+		else this.logger.info("transcode encodes on the GPU", {
+			tags: { deviceId: opts.deviceId },
+			meta: {
+				encoder,
+				camStreamId: opts.camStreamId,
+				device: choice.hwEncodeDevice?.renderNode
+			}
+		});
 		const decodeHwAccel = await this.resolveDecodeHwAccel(effectiveHwAccel);
 		const sourceUrl = this.resolveSourceUrl(opts.deviceId, opts.camStreamId);
 		const brokerId = `transcode:${opts.deviceId}:${(0, node_crypto.randomUUID)().slice(0, 8)}`;
@@ -16389,6 +16442,7 @@ var TranscodePipelineManager = class {
 				sourceUrl,
 				targetCodec: opts.targetCodec,
 				encoder,
+				hwEncodeDevice: choice.hwEncodeDevice,
 				decodeHwAccel,
 				scale: opts.scale,
 				audio: opts.audio,
@@ -16519,16 +16573,59 @@ var TranscodePipelineManager = class {
 	* ranked above qsv (qsv is broken on the Intel stack) so an Intel node
 	* transcodes with `h264_vaapi`.
 	*/
-	async resolveHardwareEncoders() {
+	/**
+	* The node's hardware backend name (`vaapi`, `qsv`, `videotoolbox`, …), or
+	* `null`. Resolved LOCALLY from `ctx.kernel.hwaccel` for the reason the
+	* sibling method's docblock gives: the `platform-probe` singleton answers
+	* with the HUB's hardware on a forked agent child.
+	*/
+	async resolveHardwareBackend() {
 		if (!this.hwaccel) return null;
 		try {
-			return localHardwareEncoders(rankDecodeHwAccels((await this.hwaccel.resolve(null)).preferred, [])[0] ?? null);
+			return rankDecodeHwAccels((await this.hwaccel.resolve(null)).preferred, [])[0] ?? null;
 		} catch (err) {
-			this.logger.warn("local hardware-encoder resolve failed — software encode fallback", { meta: { error: require_dist.errMsg(err) } });
+			this.logger.warn("local hardware resolve failed — the encoder falls back to software", { meta: { error: require_dist.errMsg(err) } });
 			return null;
 		}
 	}
 	/**
+	* What THIS ffmpeg can encode with, asked of the binary once and latched.
+	*
+	* `null` means we could not ask, which is not the same as "it cannot" — see
+	* {@link chooseVideoEncoder}. Keyed by binary PATH, so an operator who
+	* repoints `binaryPath` gets a fresh answer without a restart.
+	*/
+	async resolveBinaryEncoders(binaryPath) {
+		const caps = await this.resolveBinaryCapabilities(binaryPath);
+		return caps === null || caps.encoders.size === 0 ? null : caps.encoders;
+	}
+	/**
+	* What the ffmpeg at this path reports about itself, asked once and latched
+	* per PATH — so an operator who repoints `binaryPath` gets a fresh answer
+	* without a restart.
+	*
+	* A probe that answers nothing is `null`: "we could not ask" must never be
+	* read as "it cannot", or one bad probe pins a capable node in software.
+	*/
+	async resolveBinaryCapabilities(binaryPath) {
+		const cached = this.binaryCapabilities.get(binaryPath);
+		if (cached !== void 0) return await cached;
+		const probing = this.probeFfmpeg(binaryPath).then((caps) => {
+			if (caps.encoders.size === 0 && caps.hwaccels.size === 0) {
+				this.logger.warn("ffmpeg answered nothing about itself — hardware is attempted anyway, and its own failure is the answer", { meta: { ffmpeg: binaryPath } });
+				return null;
+			}
+			this.logger.info("ffmpeg capabilities probed for transcoding", { meta: {
+				ffmpeg: binaryPath,
+				version: caps.version,
+				hwaccels: [...caps.hwaccels].join(",") || "none"
+			} });
+			return caps;
+		});
+		this.binaryCapabilities.set(binaryPath, probing);
+		return await probing;
+	}
+	/**
 	* Resolve the effective decode `hwaccel` setting for a (deviceId, camStreamId)
 	* source. Precedence: per-source-stream override > global `ffmpeg.hwAccel`.
 	* The global default itself is `'copy'` (software) out of the box.
@@ -16562,7 +16659,18 @@ var TranscodePipelineManager = class {
 	async resolveSpecificDecodeHwAccel(prefer) {
 		if (!this.hwaccel) return null;
 		try {
-			return rankDecodeHwAccels((await this.hwaccel.resolve(prefer)).preferred, [])[0] ?? null;
+			const backend = rankDecodeHwAccels((await this.hwaccel.resolve(prefer)).preferred, [])[0] ?? null;
+			if (backend === null) return null;
+			const caps = await this.resolveBinaryCapabilities(this.ffmpegConfig().binaryPath);
+			if (caps !== null && !caps.hwaccels.has(backend)) {
+				this.logger.warn("this ffmpeg has no such decode backend compiled in — decoding in software instead of dying on a device that cannot exist", { meta: {
+					backend,
+					ffmpeg: this.ffmpegConfig().binaryPath,
+					hwaccels: [...caps.hwaccels].join(",") || "none"
+				} });
+				return null;
+			}
+			return backend;
 		} catch (err) {
 			this.logger.warn("local decode hw-accel resolve failed — software decode fallback", { meta: { error: require_dist.errMsg(err) } });
 			return null;
@@ -18128,6 +18236,20 @@ var StreamBrokerManager = class StreamBrokerManager {
 			if (!parsed) return null;
 			return findProfileForStream(this.assignments.get(parsed.deviceId)?.map ?? {}, parsed.camStreamId);
 		}, this.remoteBrokerTiers));
+		server.setStreamOriginResolver((brokerId) => {
+			if (this.remoteBrokerAdapters.has(brokerId)) return {
+				ingestNodeId: this.cachedIngestOwnerNodeId,
+				ingestIsRemote: true
+			};
+			if (this.localNodeId === null) return {
+				ingestNodeId: null,
+				ingestIsRemote: null
+			};
+			return {
+				ingestNodeId: this.localNodeId,
+				ingestIsRemote: false
+			};
+		});
 		server.setEgressTranscodeProvider({
 			acquire: (request) => this.acquireEgressTranscode(request),
 			release: (input) => this.releaseEgressTranscode(input)
@@ -23442,6 +23564,18 @@ var AdaptiveSession = class AdaptiveSession {
 			transcodeToBaseline: this.transcodeToBaseline
 		});
 	}
+	/**
+	* The codec off the SOURCE. Read-only, for the stream-debug overlay: an
+	* operator staring at a frozen picture needs to know whether this hub is
+	* re-encoding for them, and `needsTranscode` alone does not say WHAT from.
+	*/
+	get debugSourceCodec() {
+		return this.sourceCodec;
+	}
+	/** The codec this client's SDP answer settled on. See `debugSourceCodec`. */
+	get debugNegotiatedCodec() {
+		return this.negotiatedCodec;
+	}
 	_firstKeyFrame;
 	/**
 	* Last seen SPS and PPS NALs. Many cameras send SPS/PPS only once
@@ -26246,6 +26380,85 @@ var AdaptiveController = class {
 		this.healthySince = now;
 	}
 };
+//#endregion
+//#region src/stream-broker/webrtc/session-debug.ts
+/** `<deviceId>/<camStreamId>` → the camStreamId, or null when it is not one. */
+function camStreamIdOf(brokerId) {
+	const slash = brokerId.indexOf("/");
+	if (slash <= 0) return null;
+	const tail = brokerId.slice(slash + 1);
+	return tail.length > 0 ? tail : null;
+}
+/**
+* Native (the camera's own encode) vs derived (a rung this hub BUILT).
+* `unknown` when the brokerId does not parse — a guess here would tell an
+* operator the hub is transcoding when it is not, or the reverse.
+*/
+function sourceKindOf(camStreamId) {
+	if (camStreamId === null) return "unknown";
+	return camStreamId.startsWith("derived:") ? "derived" : "native";
+}
+var DEAD = {
+	alive: false,
+	brokerId: null,
+	camStreamId: null,
+	sourceKind: "unknown",
+	adaptive: false,
+	servedTier: null,
+	ingestNodeId: null,
+	ingestIsRemote: null,
+	sourceCodec: null,
+	negotiatedCodec: null,
+	egressLeg: "unknown",
+	brokerStatus: null,
+	brokerCodec: null,
+	brokerBitrateKbps: null,
+	brokerInputFps: null,
+	brokerUptimeMs: null,
+	rtpPacketsSent: null,
+	trackMode: null,
+	lastDecision: null,
+	tierFailures: [],
+	upgradeCount: null
+};
+function projectSessionDebug(input) {
+	const { session } = input;
+	if (session === null) return {
+		...DEAD,
+		sessionId: input.sessionId,
+		observedAt: input.observedAt
+	};
+	const camStreamId = camStreamIdOf(session.brokerId);
+	const stats = input.brokerStats;
+	return {
+		sessionId: input.sessionId,
+		alive: true,
+		observedAt: input.observedAt,
+		brokerId: session.brokerId,
+		camStreamId,
+		sourceKind: sourceKindOf(camStreamId),
+		adaptive: session.adaptive,
+		servedTier: input.servedTier,
+		ingestNodeId: input.origin?.ingestNodeId ?? null,
+		ingestIsRemote: input.origin?.ingestIsRemote ?? null,
+		sourceCodec: session.sourceCodec,
+		negotiatedCodec: session.negotiatedCodec,
+		egressLeg: session.needsTranscode ? "transcode" : "copy",
+		brokerStatus: stats?.status ?? null,
+		brokerCodec: stats?.codec !== void 0 && stats.codec.length > 0 ? stats.codec : null,
+		brokerBitrateKbps: stats?.bitrateKbps ?? null,
+		brokerInputFps: stats?.inputFps ?? null,
+		brokerUptimeMs: stats?.uptimeMs ?? null,
+		rtpPacketsSent: session.rtpPacketsSent,
+		trackMode: session.trackMode,
+		lastDecision: input.ladder?.lastDecision ?? null,
+		tierFailures: (input.ladder?.failures ?? []).map(([tier, failures]) => ({
+			tier,
+			failures
+		})),
+		upgradeCount: input.ladder?.upgradeCount ?? null
+	};
+}
 var PLAYBACK_PROFILE_FALLBACK_ORDER = [
 	"high",
 	"mid",
@@ -30605,6 +30818,29 @@ var BrokerWebrtcServer = class {
 	* close.
 	*/
 	adaptiveIntent = /* @__PURE__ */ new Map();
+	/**
+	* sessionId → the ladder's LAST move, and the numbers it rested on.
+	*
+	* Kept on the SERVER and not on the `SessionEntry` for the same reason
+	* `adaptiveIntent` is: a tier switch is a close-and-recreate re-offer, so
+	* the entry that made the decision is gone by the time anybody asks — which
+	* is exactly the moment an operator opens the debug overlay. Cleared on
+	* close, in `cleanupSession`.
+	*
+	* A snapshot, deliberately, not a re-read of the controller: the decision
+	* was made on a window that has since moved on, and a recomputed "current"
+	* loss ratio answers a different question than "what made it move".
+	* Absent until the ladder actually moves — a ladder that has never moved
+	* reports `null`, which is NOT the same fact as a `healthy` move with a
+	* 0 loss ratio (D393).
+	*/
+	lastLadderDecision = /* @__PURE__ */ new Map();
+	/**
+	* 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.
+	*/
+	streamOriginResolver = null;
 	stopped = false;
 	constructor(options) {
 		this.logger = options.logger;
@@ -31555,6 +31791,7 @@ var BrokerWebrtcServer = class {
 			closes.push(entry.session.close().catch(() => {}));
 		}
 		await Promise.all(closes);
+		this.lastLadderDecision.clear();
 		this.brokers.clear();
 		this.logger.info("WebRTC server stopped");
 	}
@@ -31570,6 +31807,92 @@ var BrokerWebrtcServer = class {
 			alive: entry !== void 0
 		};
 	}
+	/** Injected by the manager: brokerId → where its media is ingested. */
+	setStreamOriginResolver(resolver) {
+		this.streamOriginResolver = resolver;
+	}
+	/**
+	* The SERVER half of the stream-debug overlay for one session — the rung
+	* `auto` actually resolved to, why the ladder last moved, where the media
+	* is ingested, and whether the egress leg copies or re-encodes.
+	*
+	* Read-only and allocation-light: polled at ~1 Hz by ONE overlay while it
+	* is open. Shaping lives in the pure `projectSessionDebug`; this method
+	* only gathers.
+	*/
+	getSessionDebug(sessionId, now) {
+		const entry = this.sessions.get(sessionId);
+		if (entry === void 0) return projectSessionDebug({
+			sessionId,
+			observedAt: now,
+			session: null,
+			servedTier: null,
+			origin: null,
+			brokerStats: null,
+			ladder: null
+		});
+		const controller = entry.adaptiveController;
+		const decision = this.lastLadderDecision.get(sessionId) ?? null;
+		const ladder = controller !== void 0 ? {
+			lastDecision: decision,
+			failures: [...controller.failureCounts],
+			upgradeCount: controller.successfulUpgradeCount
+		} : decision !== null ? {
+			lastDecision: decision,
+			failures: [],
+			upgradeCount: 0
+		} : null;
+		let brokerStats = null;
+		try {
+			brokerStats = this.brokers.get(entry.brokerId)?.getStats() ?? null;
+		} catch {
+			brokerStats = null;
+		}
+		return projectSessionDebug({
+			sessionId,
+			observedAt: now,
+			session: {
+				brokerId: entry.brokerId,
+				adaptive: controller !== void 0,
+				sourceCodec: entry.session.debugSourceCodec,
+				negotiatedCodec: entry.session.debugNegotiatedCodec,
+				needsTranscode: entry.session.needsTranscode,
+				rtpPacketsSent: entry.session.rtpPacketsSentTotal,
+				trackMode: entry.timeline?.currentMode ?? "live"
+			},
+			servedTier: this.profileTierResolver?.(entry.brokerId) ?? null,
+			origin: this.streamOriginResolver?.(entry.brokerId) ?? null,
+			brokerStats,
+			ladder
+		});
+	}
+	/**
+	* Bound the ladder-decision memory. Entries survive a session teardown on
+	* purpose (the re-offer keeps the id), so nothing else would ever evict the
+	* one left behind by a client that disconnected mid-switch. Insertion order
+	* is eviction order.
+	*/
+	pruneLadderDecisions() {
+		const MAX_REMEMBERED_DECISIONS = 64;
+		while (this.lastLadderDecision.size > MAX_REMEMBERED_DECISIONS) {
+			const oldest = this.lastLadderDecision.keys().next();
+			if (oldest.done === true) break;
+			this.lastLadderDecision.delete(oldest.value);
+		}
+	}
+	/** Snapshot the ladder's move so the overlay can name it later. */
+	recordLadderDecision(sessionId, decision, tier, forcedTranscodeDown) {
+		this.lastLadderDecision.set(sessionId, {
+			cause: decision.cause,
+			tier,
+			forcedTranscodeDown,
+			lossRatio: decision.lossRatio,
+			clientKbps: decision.stall.clientKbps,
+			stalledForMs: decision.stall.stalledForMs,
+			serverSending: decision.stall.serverSending,
+			at: Date.now()
+		});
+	}
 	/**
 	* Wire an {@link AdaptiveController} to a freshly-created adaptive session.
 	* The controller is fed loss from two sources — RTCP Receiver Reports
@@ -31594,9 +31917,11 @@ var BrokerWebrtcServer = class {
 			priorUpgradeCount,
 			config: ADAPTIVE_CONFIG,
 			onSwitchTier: (tier, decision) => {
+				this.recordLadderDecision(sessionId, decision, tier, false);
 				this.switchSessionTier(entry, deviceId, tier, sessionId, false, decision);
 			},
 			onReduceMtu: (decision) => {
+				this.recordLadderDecision(sessionId, decision, null, false);
 				entry.session.setRepacketizerMtu(AdaptiveSession.ADAPTIVE_LOW_MTU);
 				this.logger.info("adaptive: reducing repacketizer MTU", {
 					tags: { deviceId },
@@ -31613,6 +31938,7 @@ var BrokerWebrtcServer = class {
 				});
 			},
 			onTranscodeDown: (decision) => {
+				this.recordLadderDecision(sessionId, decision, "low", true);
 				this.switchSessionTier(entry, deviceId, "low", sessionId, true, decision);
 			}
 		});
@@ -31718,6 +32044,7 @@ var BrokerWebrtcServer = class {
 		}
 		if (!brokerStillServed && !this.stopped) this.brokerLinger.hold(entry.brokerId);
 		this.adaptiveIntent.delete(sessionId);
+		this.pruneLadderDecisions();
 		if (entry.adaptiveTimer) clearInterval(entry.adaptiveTimer);
 		if (entry.attributionTimer) clearTimeout(entry.attributionTimer);
 		entry.attributionTagged = true;
@@ -32365,6 +32692,16 @@ var WebrtcSessionProvider = class WebrtcSessionProvider {
 	async getSessionState(input) {
 		return this.webrtcServer.getSessionRenegotiationState(input.sessionId);
 	}
+	/**
+	* The SERVER half of the stream-debug overlay. Thin facade — the gathering
+	* lives in the WebRTC server and the shaping in the pure
+	* `projectSessionDebug`. `deviceId` is not used to look the session up
+	* (session ids are already unique); it is part of the device-scoped cap's
+	* signature and identifies the camera for the route.
+	*/
+	async getSessionDebug(input) {
+		return this.webrtcServer.getSessionDebug(input.sessionId, Date.now());
+	}
 };
 //#endregion
 //#region src/stream-broker/event-loop-stall-monitor.ts