@camstack/addon-pipeline 1.2.136 → 1.2.138

package/dist/stream-broker/index.mjs

@@ -1,23 +1,24 @@
 import { r as __toESM } from "../chunk-DnnnRqeS.mjs";
-import { $ as logChannelsCapability, $t as EventCategory, At as DeviceFeature, C as RATE_CONTROL_RELAXED, Ct as AUDIO_PRESETS, D as RingBuffer, Dt as isSoftwareDecode, Et as invocationFromEncodeProfile, F as createHwAccelCache, Ft as makeProfileBrokerId, G as egressTranscodeSharingKey, Gt as discriminatedUnion, Ht as _enum, I as createLogChannelsProvider, It as makeSourceBrokerId, Jt as number, K as egressTransportFromRequest, Lt as nodePin, Mt as createEvent, N as batteryCapability, Ot as BaseAddon, P as cameraStreamsCapability, Pt as isEvent, Qt as union, R as declareLogChannel, St as errMsg, Tt as buildFfmpegArgs$1, Ut as array, V as deriveBatteryPresence, Wt as boolean, Xt as record, Yt as object, Zt as string, g as EncodeProfileSchema, i as BatteryStatusSchema, jt as DeviceType, k as addonWidgetsSourceCapability, kt as CAM_PROFILE_ORDER, mt as resolveEgressDecodeHwAccel, qt as literal, tt as maskUrlCredentials, w as RATE_CONTROL_TIGHT, wt as Fmp4BoxSplitter, xt as webrtcSessionCapability, yt as streamBrokerCapability, zt as parseProfileBrokerId } from "../dist-C1dXLLQq.mjs";
+import { $ as loadContributionCapability, $t as string, At as BaseAddon, C as RATE_CONTROL_RELAXED, Ct as errMsg, D as RingBuffer, Dt as invocationFromEncodeProfile, Et as buildFfmpegArgs$1, F as createHwAccelCache, G as egressTranscodeSharingKey, Gt as array, I as createLogChannelsProvider, It as isEvent, K as egressTransportFromRequest, Kt as boolean, Lt as makeProfileBrokerId, Mt as DeviceFeature, N as batteryCapability, Nt as DeviceType, Ot as isSoftwareDecode, P as cameraStreamsCapability, Pt as createEvent, Qt as record, R as declareLogChannel, Rt as makeSourceBrokerId, St as webrtcSessionCapability, V as deriveBatteryPresence, Vt as parseProfileBrokerId, Wt as _enum, Xt as number, Yt as literal, Zt as object, bt as streamBrokerCapability, en as union, et as logChannelsCapability, g as EncodeProfileSchema, ht as resolveEgressDecodeHwAccel, i as BatteryStatusSchema, jt as CAM_PROFILE_ORDER, k as addonWidgetsSourceCapability, kt as BOOT_RECOVERY_BACKOFF_MS, nt as maskUrlCredentials, qt as discriminatedUnion, tn as EventCategory, w as RATE_CONTROL_TIGHT, wt as AUDIO_PRESETS, zt as nodePin } from "../dist-CmEYRK7G.mjs";
+import { i as NO_COST_CLAIM, n as Fmp4FragmentChild, r as Fmp4FragmentPlane, t as ChildCostRegistry } from "../node-J07GBWT3.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 { i as require_mp4box_all, n as demuxSegmentPreferJs, r as runFfmpegOnce, t as demuxSegmentFullJs } from "../segment-demux-js-njRO85gd.mjs";
+import { i as require_mp4box_all, n as demuxSegmentPreferJs, r as runFfmpegOnce, t as demuxSegmentFullJs } from "../segment-demux-js-Ck9ly4bX.mjs";
 import { createRequire } from "node:module";
 import * as crypto$1 from "node:crypto";
 import crypto, { createHash, randomBytes, randomUUID } from "node:crypto";
-import { spawn } from "node:child_process";
-import { fileURLToPath, pathToFileURL } from "node:url";
+import * as fs from "node:fs";
+import { existsSync } from "node:fs";
 import * as path$1 from "node:path";
 import { join } from "node:path";
+import { spawn } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import * as os from "node:os";
 import { networkInterfaces, tmpdir } from "node:os";
-import * as fs from "node:fs";
-import { existsSync } from "node:fs";
 import * as net$1 from "node:net";
 import net from "node:net";
-import { readFile } from "node:fs/promises";
 import { createSocket } from "node:dgram";
 import { Socket } from "net";
 import { once } from "events";
@@ -1261,6 +1262,9 @@ var FfmpegPushReader = class {
 	spawnFn;
 	callbacks;
 	logLabel;
+	claimCost;
+	/** The claim for the child currently running, if any. */
+	costClaim = NO_COST_CLAIM;
 	child = null;
 	demux = null;
 	audioCodec;
@@ -1278,6 +1282,7 @@ var FfmpegPushReader = class {
 		this.spawnFn = options.spawnFn ?? spawn;
 		this.callbacks = callbacks;
 		this.logLabel = logLabel;
+		this.claimCost = options.claimCost;
 	}
 	/** Spawn ffmpeg and pipe its MPEG-TS stdout into the demux. */
 	connect() {
@@ -1299,6 +1304,7 @@ var FfmpegPushReader = class {
 			return;
 		}
 		this.child = child;
+		this.costClaim = this.claimCost?.(child.pid) ?? NO_COST_CLAIM;
 		child.stdin?.on("error", () => {});
 		child.stdout?.on("data", (chunk) => demux.push(chunk));
 		child.stderr?.on("data", (chunk) => this.appendStderr(chunk));
@@ -1392,6 +1398,8 @@ var FfmpegPushReader = class {
 	fireTeardown() {
 		if (this.toreDown) return;
 		this.toreDown = true;
+		this.costClaim.release();
+		this.costClaim = NO_COST_CLAIM;
 		this.callbacks.onTeardown?.();
 	}
 	/** SIGTERM, then SIGKILL if the child has not actually exited (gate on exit
@@ -2234,6 +2242,20 @@ function appendAudioMediaBlock(videoSdp, audioBlock) {
 	return `${videoSdp.replace(/[\r\n]+$/, "")}\r\n${audioBlock}\r\n`;
 }
 //#endregion
+//#region src/stream-broker/rtsp/join-burst-admission.ts
+/**
+* Decide whether this session may take this burst.
+*
+* Pure and total: no clock, no logger, no restreamer state. The restreamer maps
+* the result onto its counters and its `continue`.
+*/
+function admitJoinBurst(input) {
+	if (input.muted && !input.detectionIntent) return !input.fromRing || input.spanMs > input.liveEdgeMaxSpanMs ? "live-edge" : "none";
+	if (!input.detectionIntent && input.spanMs > input.bound.maxSpanMs) return "span";
+	if (input.packets > input.bound.maxPackets) return "packets";
+	return "none";
+}
+//#endregion
 //#region src/stream-broker/rtsp/rtsp-types.ts
 /** RTSP method constants. */
 var RTSP_METHODS = [
@@ -2860,8 +2882,6 @@ var RtspRestreamer = class {
 		if (ready.length === 0) return;
 		const preRollPlans = /* @__PURE__ */ new Map();
 		const bound = this.currentPrimeBound();
-		const overSpan = spanMs > bound.maxSpanMs;
-		const overPackets = primePackets.length > bound.maxPackets;
 		/**
 		* Resolve (and memoize) the plan for one intent.
 		*
@@ -2927,14 +2947,18 @@ var RtspRestreamer = class {
 					continue;
 				}
 			}
-			if (session.isMuted() && !detectionIntent) {
-				if (!fromRing || spanMs > LIVE_EDGE_MAX_SPAN_MS) {
-					this.dropsWithheldMutedLiveEdge++;
-					withheld++;
-					continue;
-				}
-			} else if (overSpan || overPackets) {
-				if (overSpan) this.dropsWithheldSpan++;
+			const withhold = admitJoinBurst({
+				muted: session.isMuted(),
+				detectionIntent,
+				fromRing,
+				spanMs,
+				packets: primePackets.length,
+				bound,
+				liveEdgeMaxSpanMs: LIVE_EDGE_MAX_SPAN_MS
+			});
+			if (withhold !== "none") {
+				if (withhold === "live-edge") this.dropsWithheldMutedLiveEdge++;
+				else if (withhold === "span") this.dropsWithheldSpan++;
 				else this.dropsWithheldPackets++;
 				withheld++;
 				continue;
@@ -4120,6 +4144,90 @@ function buildAudioCodecCapApi(api) {
 		flushEncode: (input) => router.flushEncode.mutate(input)
 	};
 }
+//#endregion
+//#region src/stream-broker/stream-broker/catalog-pull-backoff.ts
+/**
+* CATALOG-PULL BACKOFF — how often the broker asks a camera whose
+* `stream-catalog` pull keeps failing.
+*
+* ## What this exists to stop
+*
+* 2026-08-25, device 3629 ("Videocamera porta retro", Reolink). Its Baichuan
+* session expired under a socket that stayed open, so every
+* `stream-catalog.getCatalog` answered `buildVideoStreamOptions failed …
+* responseCode 400`. The reconcile poll asked again 30 s later. And again. For
+* 35 minutes, ~70 identical failures, each one a login attempt, a 10 s timeout
+* budget and a `debug` line nobody was reading.
+*
+* The fleet was never at risk from that camera — `reconcileAllCatalogs` fans
+* out with `Promise.allSettled` and `reconcileDeviceCatalogNow` catches its own
+* pull, so exactly one device was omitted (that isolation is frozen by
+* `scripts/check-catalog-per-device-isolation.ts`). What was wrong is that the
+* omission was invisible and the retry was a flat 30 s hammer that could not
+* have recovered anyway.
+*
+* ## The shape
+*
+* The ladder is {@link BOOT_RECOVERY_BACKOFF_MS} — the repo's ONE retry
+* schedule for work that can fail for reasons that pass: two cheap attempts
+* (15 s, 60 s) for a blip, then the long tail (5 m → 90 m) for a camera that
+* is genuinely gone.
+*
+* ## The one place this DIVERGES from boot recovery, and why
+*
+* The boot ladder ENDS: it runs out and manual re-arm is the only path. This
+* one CLAMPS at the last rung and keeps asking every 90 minutes forever.
+*
+* Boot recovery can end because a human is present — a node that just booted
+* wrong is a node someone is looking at. A camera whose session expired at
+* 03:00 has nobody. The reconcile poll is the ONLY thing that will ever ask it
+* again: no event fires when a camera silently starts working, and a device
+* that never re-enters the catalog is a device with no broker, no recording
+* and no detection, permanently. Ending the chain would convert a transient
+* session expiry into a permanent outage — precisely the failure it is meant
+* to bound. A 90-minute floor is not a spin: it is ~16 pulls a day for one
+* broken camera, against 2 880 before this.
+*/
+/**
+* The rung the ladder settles on. Read off the shared schedule rather than
+* written down twice; the literal only keeps the expression total for a
+* hypothetically empty ladder, and is not the clamp.
+*/
+var LAST_RUNG_MS = BOOT_RECOVERY_BACKOFF_MS[BOOT_RECOVERY_BACKOFF_MS.length - 1] ?? 90 * 6e4;
+/**
+* Delay before the next poll-driven attempt, given how many pulls in a row
+* have now failed (1 = the first failure).
+*
+* Clamped at the last rung rather than exhausted — see the module doc.
+*/
+function catalogPullRetryDelayMs(consecutiveFailures) {
+	return BOOT_RECOVERY_BACKOFF_MS[Math.max(consecutiveFailures, 1) - 1] ?? LAST_RUNG_MS;
+}
+/**
+* Advance the failure memory after one more failed pull.
+*
+* @param previous state before this failure, or `undefined` for the first one
+* @param nowMs wall clock at the moment of the failure
+*/
+function nextCatalogPullFailureState(previous, nowMs) {
+	const consecutiveFailures = (previous?.consecutiveFailures ?? 0) + 1;
+	return {
+		consecutiveFailures,
+		nextAttemptAtMs: nowMs + catalogPullRetryDelayMs(consecutiveFailures)
+	};
+}
+/**
+* May a POLL-driven pull run for this device right now?
+*
+* Only the poll is gated. An event-driven reconcile (device registered,
+* stream params changed) is EVIDENCE that something moved and always
+* attempts — a backoff that ignores new information is just a slower way of
+* being wrong.
+*/
+function mayAttemptPolledCatalogPull(state, nowMs) {
+	if (state === void 0) return true;
+	return nowMs >= state.nextAttemptAtMs;
+}
 /**
 * Minimum gap between two re-dials of the same device. A re-dial costs a
 * ~2 s video interruption on every source of the camera; at the 30 s
@@ -4559,506 +4667,6 @@ function pushDimension(into, constraint, requested, known) {
 		reason: `source ${known} > requested ${requested}`
 	});
 }
-/**
-* Fmp4FragmentPlane — a SUBSCRIBABLE fragmented-MP4 plane, fed by one
-* {@link import('./fmp4-box-splitter.js').Fmp4BoxSplitter}.
-*
-* ## Why a plane and not a callback
-*
-* The operator's requirement for HKSV was explicit: the live fMP4 source built
-* for it must be **dual-use**, so a HomeKit-triggered recording also lands in
-* CamStack as an additional videoclip source alongside the recorder and the NC
-* clip ring — *one fragmenter, two consumers; do not build an HKSV-only pipe*
-* (`docs/roadmap.md` item 4b). A single-callback pipe makes the second consumer
-* a second ffmpeg child of the same camera. So this is the same shape the
-* broker's other multi-consumer surfaces already have
-* (`AudioChunkPlane`, the push packet plane): N independent subscriptions over
-* one producer.
-*
-* **Nothing consumes it yet.** Phase 4 brings the HKSV delegate and phase 4b the
-* clip source; both are named here so the seam is not re-invented, and neither
-* is built.
-*
-* ## The init segment is RETAINED
-*
-* A subscriber that attaches mid-stream — the clip consumer joining an already
-* running HKSV session, which is the whole dual-use case — receives the
-* retained `ftyp`+`moov` as its first packet and then live fragments. Without
-* retention its fragments are undecodable and the failure looks like a codec
-* problem.
-*
-* ## A slow subscriber is CLOSED, never silently gapped
-*
-* `AudioChunkPlane` drops its oldest chunk on overflow, which for audio costs a
-* click. An fMP4 stream with a hole is not a shorter clip, it is a corrupt one:
-* `moof` sequence numbers jump, the consumer's demuxer desynchronises, and HKSV
-* shows a clip that fails to play with nothing anywhere saying why. So a
-* subscription whose queue overflows is ENDED with a reason, loudly, and the
-* other subscriptions are untouched.
-*
-* ## The PREBUFFER (phase 3)
-*
-* HKSV asks for context BEFORE the trigger — `CameraRecordingOptions.prebufferLength`
-* is a HAP-mandated minimum of 4000 ms — and a subscriber that attaches at the
-* motion edge has none. So the plane optionally retains the last few fragments
-* and replays them to a subscriber that asks for them.
-*
-* Three things this ring gets right, each of which is a measured fact rather
-* than a preference (see [D84](../../../../docs/decisions/adr-0084.md)):
-*
-*  - **It is bounded by TIME *and* BYTES.** On the live fleet a 720p copy
-*    fragment is ~255 KB and a 4K one is ~6.35 MB — a 25× spread over the same
-*    window. A time-only bound is a per-camera RAM figure nobody can predict.
-*  - **The window is measured on ARRIVAL, not parsed from `tfdt`.** The
-*    splitter deliberately never computes a fragment's duration (a second
-*    opinion about a fact the muxer owns), and a prebuffer cares about how long
-*    ago the bytes turned up, which is exactly what arrival time answers.
-*  - **A replay is not backlog.** A subscriber taking N retained fragments gets
-*    its queue capacity raised by N for them, because closing a subscriber as a
-*    slow consumer for the prebuffer it explicitly asked for would be the
-*    stupidest possible failure — and, with `DEFAULT_QUEUE_CAPACITY` of 4 and a
-*    ring of 4, the guaranteed one.
-*
-* ## `isLast`
-*
-* hap-nodejs requires the delegate to mark exactly one `RecordingPacket` with
-* `isLast` — a generator that finishes without it produces the twelve-second
-* timeout loop [D50](../../../../../docs/decisions/adr-0050.md) deleted. The
-* plane therefore computes it at DELIVERY time: a packet is last when the plane
-* has ended and nothing remains queued behind it. A subscription that ends
-* having delivered NOTHING says so through {@link Fmp4Subscription.delivered};
-* the future delegate must not open an HDS stream it cannot feed.
-*/
-var DEFAULT_QUEUE_CAPACITY = 4;
-var Fmp4FragmentPlane = class {
-	logger;
-	prebuffer;
-	now;
-	subscriptions = /* @__PURE__ */ new Map();
-	/** The last init unit seen, handed to every later subscriber. */
-	retainedInit = null;
-	ended = false;
-	/** Oldest first. Empty unless {@link Fmp4PrebufferOptions} was supplied. */
-	ring = [];
-	ringBytes = 0;
-	constructor(logger, prebuffer, now = Date.now) {
-		this.logger = logger;
-		this.prebuffer = prebuffer;
-		this.now = now;
-	}
-	get subscriberCount() {
-		return this.subscriptions.size;
-	}
-	/** True once {@link end} has been called — no further units are accepted. */
-	get isEnded() {
-		return this.ended;
-	}
-	/** What the prebuffer ring holds right now. All zeroes when disabled. */
-	prebufferStats() {
-		const oldest = this.ring[0];
-		return {
-			fragments: this.ring.length,
-			bytes: this.ringBytes,
-			spanMs: oldest === void 0 ? 0 : this.now() - oldest.arrivedAt
-		};
-	}
-	subscribe(input) {
-		const replay = input.withPrebuffer === true ? this.trimmedRing() : [];
-		const requested = Math.max(1, input.queueCapacity ?? DEFAULT_QUEUE_CAPACITY);
-		const sub = {
-			id: `fmp4-${randomUUID()}`,
-			tag: input.tag,
-			subscribedAt: this.now(),
-			capacity: requested + replay.length,
-			queue: [],
-			delivered: 0,
-			closedReason: null,
-			wake: null,
-			iterating: false
-		};
-		this.subscriptions.set(sub.id, sub);
-		if (this.retainedInit !== null) this.enqueue(sub, this.retainedInit);
-		for (const retained of replay) this.enqueue(sub, retained.unit);
-		if (this.ended) this.closeSubscription(sub, "ended");
-		this.logger?.info("fmp4 plane: subscribed", { meta: {
-			subscriptionId: sub.id,
-			tag: sub.tag,
-			hasRetainedInit: this.retainedInit !== null,
-			prebufferFragments: replay.length,
-			prebufferBytes: replay.reduce((n, r) => n + r.unit.data.length, 0)
-		} });
-		return this.facade(sub);
-	}
-	/**
-	* Fan one splitter unit out. An `init` REPLACES the retained one — ffmpeg
-	* emits exactly one per child, and a second means the child was respawned, in
-	* which case the old one describes a stream that no longer exists.
-	*/
-	publish(unit) {
-		if (this.ended) return;
-		if (unit.kind === "init") {
-			this.retainedInit = unit;
-			this.ring.length = 0;
-			this.ringBytes = 0;
-		} else this.retain(unit);
-		for (const sub of this.subscriptions.values()) {
-			if (sub.closedReason !== null) continue;
-			this.enqueue(sub, unit);
-		}
-	}
-	/**
-	* The producer stopped. Every subscriber drains what it holds; its final
-	* packet carries `isLast`, and its generator then completes.
-	*/
-	end(reason = "producer ended") {
-		if (this.ended) return;
-		this.ended = true;
-		this.logger?.info("fmp4 plane: ended", { meta: {
-			reason,
-			subscribers: this.subscriptions.size
-		} });
-		for (const sub of this.subscriptions.values()) if (sub.closedReason === null) this.closeSubscription(sub, "ended");
-	}
-	listSubscribers() {
-		return [...this.subscriptions.values()].map((s) => ({
-			tag: s.tag,
-			subscribedAt: s.subscribedAt,
-			delivered: s.delivered,
-			closedReason: s.closedReason
-		}));
-	}
-	/** End and forget everything. Idempotent. */
-	dispose() {
-		this.end("disposed");
-		this.subscriptions.clear();
-		this.retainedInit = null;
-		this.ring.length = 0;
-		this.ringBytes = 0;
-	}
-	/**
-	* Add one fragment to the ring and evict from the front until BOTH bounds
-	* hold. Eviction is oldest-first, which is the one place in this file where
-	* dropping is correct: the ring is context, not stream — nobody is mid-decode
-	* on it, and a subscriber only ever receives a contiguous tail of it.
-	*/
-	retain(unit) {
-		const prebuffer = this.prebuffer;
-		if (prebuffer === void 0) return;
-		const arrivedAt = this.now();
-		this.ring.push({
-			unit,
-			arrivedAt
-		});
-		this.ringBytes += unit.data.length;
-		const cutoff = arrivedAt - prebuffer.windowMs;
-		while (this.ring.length > 0) {
-			const oldest = this.ring[0];
-			if (oldest === void 0) break;
-			const tooOld = oldest.arrivedAt < cutoff;
-			const tooBig = this.ringBytes > prebuffer.maxBytes;
-			if (!tooOld && !tooBig || this.ring.length === 1) break;
-			this.ring.shift();
-			this.ringBytes -= oldest.unit.data.length;
-		}
-	}
-	/**
-	* The ring as a subscriber should receive it — window applied AT SUBSCRIBE
-	* time, not only at publish time. A camera that went quiet keeps its last
-	* fragment in the ring indefinitely (see the never-evict-the-newest rule),
-	* and replaying a 40-second-old fragment as "prebuffer" would put stale video
-	* at the head of a clip iOS presents as the moment of the event.
-	*/
-	trimmedRing() {
-		const prebuffer = this.prebuffer;
-		if (prebuffer === void 0) return [];
-		const cutoff = this.now() - prebuffer.windowMs;
-		return this.ring.filter((r) => r.arrivedAt >= cutoff);
-	}
-	enqueue(sub, unit) {
-		if (sub.queue.length >= sub.capacity) {
-			this.logger?.warn("fmp4 plane: subscriber fell behind — CLOSING it rather than gapping it", { meta: {
-				subscriptionId: sub.id,
-				tag: sub.tag,
-				capacity: sub.capacity,
-				delivered: sub.delivered
-			} });
-			this.closeSubscription(sub, "slow-consumer");
-			return;
-		}
-		sub.queue.push({
-			kind: unit.kind,
-			data: unit.data,
-			sequence: unit.sequence,
-			isLast: false
-		});
-		this.wake(sub);
-	}
-	closeSubscription(sub, reason) {
-		if (sub.closedReason !== null) return;
-		sub.closedReason = reason;
-		if (reason === "slow-consumer") sub.queue.length = 0;
-		this.wake(sub);
-	}
-	wake(sub) {
-		const resume = sub.wake;
-		sub.wake = null;
-		resume?.();
-	}
-	facade(sub) {
-		const plane = this;
-		return {
-			id: sub.id,
-			tag: sub.tag,
-			get delivered() {
-				return sub.delivered;
-			},
-			get closedReason() {
-				return sub.closedReason;
-			},
-			packets: () => plane.iterate(sub),
-			release: () => {
-				plane.closeSubscription(sub, "released");
-				plane.subscriptions.delete(sub.id);
-			}
-		};
-	}
-	async *iterate(sub) {
-		if (sub.iterating) throw new Error(`fmp4 plane: subscription ${sub.tag} is already being consumed — take a second subscription`);
-		sub.iterating = true;
-		for (;;) {
-			const next = sub.queue.shift();
-			if (next === void 0) {
-				if (sub.closedReason !== null) return;
-				await new Promise((resolve) => {
-					sub.wake = resolve;
-				});
-				continue;
-			}
-			const isLast = sub.closedReason === "ended" && sub.queue.length === 0;
-			sub.delivered += 1;
-			yield {
-				...next,
-				isLast
-			};
-			if (isLast) return;
-		}
-	}
-};
-var DEFAULT_FIRST_UNIT_TIMEOUT_MS = 12e3;
-/** Heartbeat cadence — ~2 minutes of 4 s fragments. */
-var FRAGMENT_LOG_EVERY = 30;
-var Fmp4FragmentChild = class {
-	deps;
-	args;
-	child = null;
-	splitter = new Fmp4BoxSplitter();
-	stopped = false;
-	unitsOut = 0;
-	activeHwAccel = null;
-	constructor(deps, args) {
-		this.deps = deps;
-		this.args = args;
-	}
-	/** Spawn, and resolve once the INIT segment has been cut out of stdout. */
-	async start() {
-		const requested = this.args.invocation.decodeHwAccel;
-		this.activeHwAccel = requested;
-		try {
-			await this.spawnAttempt(requested);
-			return;
-		} catch (err) {
-			if (this.stopped) throw err;
-			if (requested === null || isSoftwareDecode(requested)) throw err;
-			this.deps.logger.warn("fmp4 fragment child: hardware decode produced NO fragment — retrying in SOFTWARE", {
-				tags: { deviceId: this.args.deviceId },
-				meta: {
-					sourceId: this.args.sourceId,
-					decodeHwAccel: requested,
-					error: errMsg(err)
-				}
-			});
-			this.killChild();
-			this.splitter = new Fmp4BoxSplitter();
-			this.activeHwAccel = null;
-			await this.spawnAttempt(null);
-		}
-	}
-	/** The backend the child ACTUALLY ran with — `null` for software. */
-	activeDecodeHwAccel() {
-		const value = this.activeHwAccel;
-		return value === null || value === "none" || value === "copy" ? null : value;
-	}
-	/** Kill ffmpeg and end the plane. Idempotent. */
-	async stop() {
-		if (this.stopped) return;
-		this.stopped = true;
-		this.killChild();
-		this.args.plane.end("the fragment child stopped");
-	}
-	spawnAttempt(decodeHwAccel) {
-		const args = buildFfmpegArgs$1({
-			...this.args.invocation,
-			decodeHwAccel,
-			sink: {
-				kind: "stdout",
-				container: "mp4",
-				fragmentMs: this.args.fragmentMs
-			}
-		});
-		this.deps.logger.info("fmp4 fragment child: spawning ffmpeg", {
-			tags: { deviceId: this.args.deviceId },
-			meta: {
-				sourceId: this.args.sourceId,
-				fragmentMs: this.args.fragmentMs,
-				decodeHwAccel: decodeHwAccel ?? "software",
-				argv: args.join(" ")
-			}
-		});
-		return new Promise((resolve, reject) => {
-			const child = this.deps.spawnFn(this.deps.ffmpegBinaryPath, args, { stdio: [
-				"ignore",
-				"pipe",
-				"pipe"
-			] });
-			this.child = child;
-			let settled = false;
-			/**
-			* This attempt FAILED. Set before the kill, because SIGTERM makes the
-			* child exit and that exit must not be reported as a death: the retry —
-			* or the caller's rejection — already owns what happens next. Without it
-			* the timeout path ends the plane the software retry is about to fill,
-			* and the consumer sees a stream that stopped for no reason. A "which
-			* spawn is current" counter does NOT cover this: the retry has not been
-			* spawned when the kill's exit arrives.
-			*/
-			let failed = false;
-			/**
-			* This attempt is still the live producer: it has not failed (a failure
-			* hands ownership to the retry, or to the caller's rejection) and nothing
-			* has stopped the child. Those two cover every way an attempt stops being
-			* current — `start` only respawns after a rejection.
-			*/
-			const isCurrent = () => !this.stopped && !failed;
-			const timeoutMs = this.deps.firstUnitTimeoutMs ?? DEFAULT_FIRST_UNIT_TIMEOUT_MS;
-			const settle = (fail) => {
-				if (settled) return;
-				settled = true;
-				clearTimeout(timer);
-				if (fail) {
-					failed = true;
-					reject(fail);
-				} else resolve();
-			};
-			const timer = setTimeout(() => {
-				settle(/* @__PURE__ */ new Error(`fmp4 fragment child: no fragment within ${timeoutMs}ms`));
-				this.killChild();
-			}, timeoutMs);
-			timer.unref?.();
-			child.stdout?.on("data", (chunk) => {
-				for (const unit of this.splitter.push(chunk)) {
-					this.unitsOut += 1;
-					this.args.plane.publish(unit);
-					if (unit.kind === "init") {
-						this.deps.logger.info("fmp4 fragment child: INIT segment cut", {
-							tags: { deviceId: this.args.deviceId },
-							meta: {
-								sourceId: this.args.sourceId,
-								bytes: unit.data.length
-							}
-						});
-						settle();
-					} else if (this.unitsOut % FRAGMENT_LOG_EVERY === 0) this.deps.logger.info("fmp4 fragment child: fragments still flowing", {
-						tags: { deviceId: this.args.deviceId },
-						meta: {
-							sourceId: this.args.sourceId,
-							unitsOut: this.unitsOut,
-							bytes: unit.data.length,
-							subscribers: this.args.plane.subscriberCount
-						}
-					});
-				}
-				const fault = this.splitter.fault;
-				if (fault !== null) this.onFault(fault, settled, isCurrent(), settle);
-			});
-			child.stderr?.setEncoding("utf8");
-			child.stderr?.on("data", (line) => {
-				this.deps.logger.debug("fmp4 fragment child ffmpeg", {
-					tags: { deviceId: this.args.deviceId },
-					meta: {
-						sourceId: this.args.sourceId,
-						line: line.trim()
-					}
-				});
-			});
-			child.once("error", (err) => {
-				if (!settled) {
-					settle(err);
-					return;
-				}
-				if (!isCurrent()) return;
-				this.args.plane.end("the fragment child errored");
-				this.deps.onChildExit?.(err);
-			});
-			child.once("exit", (code, signal) => {
-				if (!settled) {
-					settle(/* @__PURE__ */ new Error(`fmp4 fragment child: ffmpeg exited before any fragment (code=${code} signal=${signal})`));
-					return;
-				}
-				if (!isCurrent()) return;
-				const error = /* @__PURE__ */ new Error(`fmp4 fragment child: ffmpeg exited while live (code=${code} signal=${signal})`);
-				this.deps.logger.warn("fmp4 fragment child: ffmpeg exited while live", {
-					tags: { deviceId: this.args.deviceId },
-					meta: {
-						sourceId: this.args.sourceId,
-						code,
-						signal,
-						unitsOut: this.unitsOut
-					}
-				});
-				this.args.plane.end("the fragment child exited");
-				this.deps.onChildExit?.(error);
-			});
-		});
-	}
-	/**
-	* The byte stream stopped being splittable. Not recoverable — the splitter
-	* cannot resynchronise mid-box — so the child is a corpse and every consumer
-	* has to be told, loudly, with the reason.
-	*/
-	onFault(reason, wasLive, current, settle) {
-		const error = /* @__PURE__ */ new Error(`fmp4 fragment child: ${reason}`);
-		this.deps.logger.error("fmp4 fragment child: the ffmpeg output stopped parsing as fMP4", {
-			tags: { deviceId: this.args.deviceId },
-			meta: {
-				sourceId: this.args.sourceId,
-				unitsOut: this.unitsOut,
-				interstitial: this.splitter.discardedInterstitialTypes,
-				reason
-			}
-		});
-		this.killChild();
-		settle(error);
-		if (wasLive && current) {
-			this.args.plane.end("the fragment child produced unsplittable output");
-			this.deps.onChildExit?.(error);
-		}
-	}
-	killChild() {
-		const child = this.child;
-		this.child = null;
-		if (child && !child.killed) try {
-			child.kill("SIGTERM");
-		} catch (err) {
-			this.deps.logger.warn("fmp4 fragment child: kill error", {
-				tags: { deviceId: this.args.deviceId },
-				meta: {
-					sourceId: this.args.sourceId,
-					error: errMsg(err)
-				}
-			});
-		}
-	}
-};
 //#endregion
 //#region src/stream-broker/stream-broker/rtsp-host.ts
 /**
@@ -5263,6 +4871,7 @@ var TranscodeEgress = class {
 			] });
 			this.child = child;
 			this.startedAtMs = Date.now();
+			const costClaim = this.deps.claimCost?.(child.pid) ?? NO_COST_CLAIM;
 			let settled = false;
 			const timeoutMs = this.deps.firstDataTimeoutMs ?? DEFAULT_FIRST_DATA_TIMEOUT_MS;
 			const timer = setTimeout(() => {
@@ -5299,12 +4908,14 @@ var TranscodeEgress = class {
 				} });
 			});
 			child.once("error", (err) => {
+				costClaim.release();
 				if (settled) return;
 				settled = true;
 				clearTimeout(timer);
 				reject(err);
 			});
 			child.once("exit", (code, signal) => {
+				costClaim.release();
 				if (settled) {
 					if (this.stopped) return;
 					const error = /* @__PURE__ */ new Error(`transcode egress: ffmpeg exited while live (code=${code} signal=${signal})`);
@@ -5865,7 +5476,13 @@ var EgressTranscodeManager = class {
 			ffmpegBinaryPath: this.opts.ffmpegConfig().binaryPath,
 			spawnFn: this.opts.spawnFn ?? spawn,
 			acquireChannel: () => channel,
-			...spec.onDied ? { onChildExit: spec.onDied } : {}
+			...spec.onDied ? { onChildExit: spec.onDied } : {},
+			claimCost: (pid) => this.opts.costRegistry?.claim({
+				role: "transcode",
+				deviceId: spec.deviceId,
+				unit: spec.brokerId,
+				pid
+			}) ?? NO_COST_CLAIM
 		}, {
 			brokerId: spec.brokerId,
 			targetCodec: spec.targetCodec,
@@ -11371,6 +10988,14 @@ var StreamBroker = class StreamBroker {
 	* and a line without the tag cannot be grouped to answer it.
 	*/
 	numericDeviceId;
+	/**
+	* Where this broker records the ffmpeg ingest it spawns, so the stream-broker
+	* addon reports its OWN per-camera cost through `load-contribution` instead
+	* of leaving an observer to join a pid against a camera. Null until the
+	* manager injects it; a broker without one still streams, and its ffmpeg is
+	* simply unclaimed in the node's process snapshot.
+	*/
+	costRegistry = null;
 	_status = "idle";
 	source;
 	/**
@@ -11904,6 +11529,30 @@ var StreamBroker = class StreamBroker {
 		this.ffmpegBinaryPath = binaryPath;
 	}
 	/**
+	* Inject the addon's child-cost registry. Injected rather than constructed
+	* here because the registry is per-ADDON-PROCESS (it is what the addon's
+	* `load-contribution` provider reads) while a broker is per-camera.
+	*/
+	setCostRegistry(registry) {
+		this.costRegistry = registry;
+	}
+	/**
+	* Claim one ffmpeg ingest generation for this camera, or nothing when the
+	* camera cannot be named. Never a placeholder device id: an unnamed
+	* per-camera claim is indistinguishable from a shared cost and would quietly
+	* turn one camera's ffmpeg into everybody's.
+	*/
+	claimIngestCost(pid) {
+		const deviceId = this.numericDeviceId;
+		if (this.costRegistry === null || deviceId === void 0) return NO_COST_CLAIM;
+		return this.costRegistry.claim({
+			role: "streaming",
+			deviceId,
+			unit: this.deviceId,
+			pid
+		});
+	}
+	/**
 	* Inject a manager-owned closure that derives the current
 	* `StreamSource` from the live cam-stream registry. Every dial
 	* attempt (initial start, scheduled reconnect, demand-driven resume)
@@ -13519,7 +13168,8 @@ var StreamBroker = class StreamBroker {
 		const reader = new FfmpegSourceReader({
 			ffmpegPath: this.ffmpegBinaryPath,
 			args,
-			...this.logger ? { logger: this.logger.child("ffmpeg-source") } : {}
+			...this.logger ? { logger: this.logger.child("ffmpeg-source") } : {},
+			claimCost: (pid) => this.claimIngestCost(pid)
 		}, {
 			onVideoCodec: (codec) => {
 				this.detectedCodec = codec;
@@ -15092,6 +14742,13 @@ var StreamBrokerManager = class StreamBrokerManager {
 	deviceOverridePersister = null;
 	profileMapPersister = null;
 	deviceCatalogOperations = /* @__PURE__ */ new Map();
+	/**
+	* Devices whose `stream-catalog` pull is currently failing, and when the
+	* POLL may ask again. Absent = healthy; an entry is deleted the moment a
+	* pull succeeds. See `catalog-pull-backoff.ts` for the ladder and for the
+	* outage that put it here.
+	*/
+	catalogPullFailures = /* @__PURE__ */ new Map();
 	eventBus = null;
 	/**
 	* Per-broker stream health flag set by the watchdog. `undefined`
@@ -15297,6 +14954,8 @@ var StreamBrokerManager = class StreamBrokerManager {
 	* that reclaims a refcount whose holder died without releasing.
 	*/
 	egressTranscodeManager = null;
+	/** See {@link StreamBrokerManager.setCostRegistry}. */
+	costRegistry = null;
 	/**
 	* Test/injection seam for the egress primitive's child. Production leaves it
 	* null and `EgressTranscodeManager` builds a real `TranscodeEgress` /
@@ -15339,6 +14998,15 @@ var StreamBrokerManager = class StreamBrokerManager {
 		this.rtspProvider = new RtspRestreamProviderImpl(this.rtspServer, logger.child("rtsp-restream"));
 	}
 	/**
+	* The addon's child-cost registry, threaded down to every broker and to the
+	* egress transcode manager so each spawn site claims its OWN child. Injected
+	* (not constructed) because it is per-addon-process and is what the addon's
+	* `load-contribution` provider reads.
+	*/
+	setCostRegistry(registry) {
+		this.costRegistry = registry;
+	}
+	/**
 	* Lazily create the transcode manager wired with closures rather than
 	* direct refs so it only sees the surface it needs.
 	*/
@@ -15406,6 +15074,7 @@ var StreamBrokerManager = class StreamBrokerManager {
 					return entry ? { url: entry.url } : null;
 				},
 				ffmpegConfig: () => this.ffmpegConfig,
+				...this.costRegistry === null ? {} : { costRegistry: this.costRegistry },
 				resolveDecodeHwAccel: (deviceId, override) => this.resolveEgressHwAccel(deviceId, override),
 				acquireChannel: (brokerId) => {
 					const restreamer = new RtspRestreamer(brokerId);
@@ -16631,26 +16300,54 @@ var StreamBrokerManager = class StreamBrokerManager {
 	/**
 	* Pull one camera's `stream-catalog` and reconcile its cam-streams: upsert
 	* every descriptor, retract any cam-stream no longer in the catalog. A pull
-	* that throws (provider mid-restart, no `stream-catalog` cap) is skipped —
-	* the poll retries. An EMPTY catalog is also skipped rather than tearing
-	* down (a provider probe can transiently return none); genuine removal flows
-	* through the device-unregistered path.
+	* that throws (provider mid-restart, no `stream-catalog` cap, a camera whose
+	* session died) omits THIS DEVICE ONLY — it is logged at `warn` with the
+	* device's id and re-asked on the `catalog-pull-backoff.ts` ladder. An EMPTY
+	* catalog is also skipped rather than tearing down (a provider probe can
+	* transiently return none); genuine removal flows through the
+	* device-unregistered path.
+	*
+	* `trigger` decides whether the backoff applies — see
+	* {@link CatalogReconcileTrigger}. It defaults to `'event'` (always attempt)
+	* so only the caller that actually repeats forever pays the throttle.
 	*/
-	async reconcileDeviceCatalog(deviceId) {
-		await this.runDeviceCatalogOperation(deviceId, () => this.reconcileDeviceCatalogNow(deviceId));
+	async reconcileDeviceCatalog(deviceId, trigger = "event") {
+		await this.runDeviceCatalogOperation(deviceId, () => this.reconcileDeviceCatalogNow(deviceId, trigger));
 	}
-	async reconcileDeviceCatalogNow(deviceId) {
+	async reconcileDeviceCatalogNow(deviceId, trigger) {
 		if (!this.api) return;
+		const failure = this.catalogPullFailures.get(deviceId);
+		if (trigger === "poll" && !mayAttemptPolledCatalogPull(failure, Date.now())) {
+			this.logger.debug("reconcileDeviceCatalog: skipped — device is on catalog-pull backoff", {
+				tags: { deviceId },
+				meta: {
+					consecutiveFailures: failure?.consecutiveFailures ?? 0,
+					nextAttemptInMs: Math.max(0, (failure?.nextAttemptAtMs ?? 0) - Date.now())
+				}
+			});
+			return;
+		}
 		let descriptors;
 		try {
 			descriptors = await this.withCatalogTimeout(this.api.streamCatalog.getCatalog.query({ deviceId }), deviceId) ?? [];
 		} catch (err) {
-			this.logger.debug("reconcileDeviceCatalog: stream-catalog pull failed — will retry", {
+			const next = nextCatalogPullFailureState(this.catalogPullFailures.get(deviceId), Date.now());
+			this.catalogPullFailures.set(deviceId, next);
+			this.logger.warn("stream-catalog pull failed — device omitted from this catalog reconcile", {
 				tags: { deviceId },
-				meta: { error: errMsg(err) }
+				meta: {
+					trigger,
+					consecutiveFailures: next.consecutiveFailures,
+					retryInMs: catalogPullRetryDelayMs(next.consecutiveFailures),
+					error: errMsg(err)
+				}
 			});
 			return;
 		}
+		if (this.catalogPullFailures.delete(deviceId)) this.logger.info("stream-catalog pull recovered — device is back in the catalog", {
+			tags: { deviceId },
+			meta: { descriptors: descriptors.length }
+		});
 		if (descriptors.length === 0) return;
 		const keep = new Set(descriptors.map((d) => d.camStreamId));
 		await this.publishCatalog(deviceId, descriptors);
@@ -16685,10 +16382,11 @@ var StreamBrokerManager = class StreamBrokerManager {
 			await this.releaseDisabledDeviceBrokers(d.id, firstSeen);
 		} else this.disabledDevices.delete(d.id);
 		const live = cameras.filter((d) => !d.disabled);
-		await Promise.allSettled(live.map((d) => this.reconcileDeviceCatalog(d.id)));
+		await Promise.allSettled(live.map((d) => this.reconcileDeviceCatalog(d.id, "poll")));
 		await Promise.allSettled(live.map((d) => this.reconcileDeviceAudioPlane(d.id)));
 		const liveIds = new Set(live.map((d) => d.id));
 		for (const deviceId of [...this.audioPlaneState.keys()]) if (!liveIds.has(deviceId)) this.audioPlaneState.delete(deviceId);
+		for (const deviceId of [...this.catalogPullFailures.keys()]) if (!liveIds.has(deviceId)) this.catalogPullFailures.delete(deviceId);
 	}
 	/**
 	* ONE device's audio-plane reconcile pass. See `audio-plane-reconcile.ts`
@@ -16830,6 +16528,7 @@ var StreamBrokerManager = class StreamBrokerManager {
 		await this.runDeviceCatalogOperation(deviceId, () => this.retractDeviceNow(deviceId, opts));
 	}
 	async retractDeviceNow(deviceId, opts) {
+		this.catalogPullFailures.delete(deviceId);
 		const existing = this.cameraStreams.get(deviceId);
 		if (existing) for (const camStreamId of Array.from(existing.keys())) await this.retractCameraStream({
 			deviceId,
@@ -19056,6 +18755,7 @@ var StreamBrokerManager = class StreamBrokerManager {
 		const broker = new StreamBroker(brokerId, this.buildDecoderCapApi(deviceId), brokerLogger, buildAudioCodecCapApi(this.api), this.localNodeId);
 		broker.setRestreamUrlResolver(() => this.rtspProvider.getEntry(brokerId)?.mutedUrl ?? null);
 		broker.setFfmpegBinaryPath(this.ffmpegConfig.binaryPath);
+		if (this.costRegistry !== null) broker.setCostRegistry(this.costRegistry);
 		this.applyPreBufferConfig(broker, deviceId, camStreamId);
 		this.applyAudioMuteConfig(broker, deviceId);
 		this.applyJoinBurstBound(broker, deviceId, camStreamId);
@@ -29502,6 +29202,12 @@ var StreamBrokerAddon = class extends BaseAddon {
 	*  diagnostic timer never keeps a runner from exiting. */
 	logChannels = null;
 	/**
+	* The ffmpeg children this addon started, claimed at their spawn sites and
+	* released at their exits. One registry per PROCESS: it dies with the
+	* process, which is correct — those children were this process's children.
+	*/
+	costRegistry = new ChildCostRegistry();
+	/**
 	* Snapshot-equality cache for the broker-metrics emit. Each
 	* broker emits a stats snapshot every BROKER_METRICS_SNAPSHOT_-
 	* INTERVAL_MS; for an idle broker (status=streaming, fps=0,
@@ -29587,11 +29293,16 @@ var StreamBrokerAddon = class extends BaseAddon {
 			capability: logChannelsCapability,
 			provider: this.logChannels
 		};
+		const loadContributionRegistration = {
+			capability: loadContributionCapability,
+			provider: { list: () => this.costRegistry.contributions() }
+		};
 		this.loopStallMonitor = new EventLoopStallMonitor({ onStall: (stallMs) => {
 			this.ctx?.logger?.warn?.("event-loop stall — every session in this process froze", { meta: { stallMs } });
 		} });
 		this.loopStallMonitor.start();
 		this.brokerManager = new StreamBrokerManager(void 0, this.ctx.logger);
+		this.brokerManager.setCostRegistry(this.costRegistry);
 		this.brokerManager.setDefaultPreBufferSec(this.config.defaultPreBufferSec);
 		this.brokerManager.setDefaultJoinBurstMaxSpanMs(this.config.joinBurstMaxSpanMs);
 		this.brokerManager.setDefaultPreRollMs(this.config.preRollMs);
@@ -29944,7 +29655,8 @@ var StreamBrokerAddon = class extends BaseAddon {
 				capability: addonWidgetsSourceCapability,
 				provider: widgetsProvider
 			},
-			logChannelsRegistration
+			logChannelsRegistration,
+			loadContributionRegistration
 		];
 	}
 	async onShutdown() {