@camstack/addon-pipeline 1.2.124 → 1.2.125

package/dist/pipeline-runner/index.js

@@ -2,11 +2,11 @@ Object.defineProperties(exports, {
 	__esModule: { value: true },
 	[Symbol.toStringTag]: { value: "Module" }
 });
-const require_dist = require("../dist-DomdkRKL.js");
-const require_event_loop_stall_monitor = require("../event-loop-stall-monitor-ChA4AQ1D.js");
-const require_worker_protocol = require("../worker-protocol-DQ5DPOFD.js");
+const require_dist = require("../dist-BZUXb5S5.js");
+const require_event_loop_stall_monitor = require("../event-loop-stall-monitor-BdArVUlx.js");
+const require_worker_protocol = require("../worker-protocol-BxkCoVjw.js");
 const require_hub_hostname = require("../hub-hostname-DAJXlOgV.js");
-const require_lazy_sharp = require("../lazy-sharp-BSeW3qY5.js");
+const require_lazy_sharp = require("../lazy-sharp-BxMwCkCA.js");
 const require_restream_intent = require("../restream-intent-Cv9x3jmu.js");
 const require_remote_restream = require("../remote-restream-CO36Sr30.js");
 let sharp = require("sharp");
@@ -201,6 +201,158 @@ function startGuardedSessionDecode(deps) {
 		if (release) release();
 	};
 }
+/**
+* RAM this node lets live decode workers commit, in MB.
+*
+* ## Why 8192, and why 6144 was wrong
+*
+* 6144 shipped first, derived from the SHIPPED lease defaults (1024 + 64 + 350
+* = 1438 MB per worker) and a 13-minute concurrency sample. Both inputs were
+* wrong for the cluster it ran on, in opposite directions:
+*
+*  - the operator here runs `budgetMb: 512`, so a worker is worst-cased at
+*    **926 MB**, not 1438 — the old count of 8 was authorising 7.4 GiB, not the
+*    11.5 GiB the defaults implied;
+*  - the sample missed the peak. Measured across the change: at ceiling 8 the
+*    cluster refused 4 sessions in 30 minutes; at the ceiling 6144 derived
+*    (6 workers at 926 MB) it refused **43 in 10 minutes**, and the hub — which
+*    had never refused once — began refusing too. Demand genuinely reaches 8.
+*
+* A refusal is self-healing but it is not free: the retry ladder means the
+* camera decodes a motion window that has moved on. Trading real coverage for a
+* RAM headroom nobody measured a need for is the wrong side of the trade.
+*
+* 8192 restores exactly the concurrency this cluster had (`floor(8192/926) = 8`)
+* while keeping what the change was actually for: the bound is RAM, so raising
+* `budgetMb` back to the shipped 1024 now DROPS the ceiling to 5 instead of
+* silently authorising 11.5 GiB, and the refusal line names the megabytes.
+*/
+var DEFAULT_NODE_DECODE_BUDGET_MB = 8192;
+/**
+* Worst-case RAM one decode worker may commit, from the lease knobs actually in
+* force. The SINGLE place the operator-facing budgets become the number the
+* ceiling is derived from — computing it anywhere else is exactly how the count
+* and the budget drifted apart.
+*
+* `override` carries only the knobs the operator SET (see
+* `native-lease-config.ts` on why "unset" includes a knob sitting at its
+* default); anything absent falls back to what the worker ships with.
+*/
+function decodeWorkerFootprintMb(override) {
+	return (override.budgetMb ?? require_dist.DEFAULT_NATIVE_LEASE_SETTINGS.budgetMb) + (override.tileBudgetMb ?? require_dist.DEFAULT_NATIVE_LEASE_SETTINGS.tileBudgetMb) + 350;
+}
+/**
+* The node's live-decode-worker budget.
+*
+* One instance per runner addon. Not a semaphore: a semaphore's contract is
+* "wait", and waiting is the thing this deliberately does not do — see
+* {@link DEFAULT_MAX_LIVE_DECODE_WORKERS}.
+*/
+var LiveDecodeWorkerAdmission = class {
+	limit;
+	logger;
+	live = 0;
+	nodeBudgetMb;
+	workerFootprintMb;
+	constructor(options) {
+		this.limit = Math.max(1, options.limit);
+		this.logger = options.logger;
+		this.nodeBudgetMb = positiveOrUndefined(options.nodeBudgetMb);
+		this.workerFootprintMb = positiveOrUndefined(options.workerFootprintMb);
+	}
+	/** Workers currently holding a slot. */
+	get inFlight() {
+		return this.live;
+	}
+	/**
+	* The ceiling actually in force: the RAM budget divided by one worker\'s worst
+	* case, clamped by the hand-set count.
+	*
+	* Never zero. A node too small for even one worker still decodes one camera —
+	* refusing every camera turns a memory bound into a total outage, and one
+	* worker is the smallest unit of "this node does its job at all".
+	*/
+	get ceiling() {
+		const fromBudget = this.budgetDerivedCeiling();
+		return fromBudget === void 0 ? this.limit : Math.max(1, Math.min(this.limit, fromBudget));
+	}
+	/** MB currently committed by the workers holding a slot. */
+	get committedMb() {
+		return this.workerFootprintMb === void 0 ? void 0 : this.live * this.workerFootprintMb;
+	}
+	budgetDerivedCeiling() {
+		if (this.nodeBudgetMb === void 0 || this.workerFootprintMb === void 0) return void 0;
+		return Math.floor(this.nodeBudgetMb / this.workerFootprintMb);
+	}
+	/**
+	* Apply a changed per-worker footprint — the operator moved `budgetMb` or
+	* `tileBudgetMb`. Like {@link resize} this never kills a running session; it
+	* only changes what the next admission is measured against.
+	*/
+	resizeFootprint(workerFootprintMb) {
+		this.workerFootprintMb = positiveOrUndefined(workerFootprintMb);
+	}
+	/** Apply a changed node decode budget. */
+	resizeBudget(nodeBudgetMb) {
+		this.nodeBudgetMb = positiveOrUndefined(nodeBudgetMb);
+	}
+	/**
+	* Apply an operator-changed ceiling.
+	*
+	* Lowering it never kills a running session — a decode worker torn down
+	* mid-motion loses the event it was started for. It only stops the next
+	* admission, so the count drains to the new ceiling as sessions end.
+	*/
+	resize(limit) {
+		this.limit = Math.max(1, limit);
+	}
+	/**
+	* Take a slot, or refuse.
+	*
+	* A refusal is a WARN and carries `tags.deviceId`, because the only useful
+	* form of this question is per-camera ("why did 617 not run when 615 did?").
+	* A branch that drops work silently reads as "it never happened".
+	*/
+	admit(deviceId, label) {
+		const ceiling = this.ceiling;
+		if (this.live >= ceiling) {
+			this.logger.warn("session-decode: REFUSED — node live decode-worker ceiling reached, will retry", {
+				tags: { deviceId },
+				meta: {
+					label,
+					live: this.live,
+					ceiling,
+					...this.committedMb === void 0 ? {} : {
+						committedMb: this.committedMb,
+						budgetMb: this.nodeBudgetMb,
+						workerFootprintMb: this.workerFootprintMb
+					}
+				}
+			});
+			return null;
+		}
+		this.live += 1;
+		this.logger.debug("session-decode: live decode-worker slot taken", {
+			tags: { deviceId },
+			meta: {
+				label,
+				live: this.live,
+				ceiling: this.ceiling
+			}
+		});
+		let released = false;
+		return { release: () => {
+			if (released) return;
+			released = true;
+			this.live -= 1;
+		} };
+	}
+};
+/** A knob that is absent, zero or nonsense derives nothing rather than a bound nobody chose. */
+function positiveOrUndefined(value) {
+	if (value === void 0) return void 0;
+	return Number.isFinite(value) && value > 0 ? value : void 0;
+}
 //#endregion
 //#region src/session-decode/native-crop-registry.ts
 /**
@@ -1713,589 +1865,171 @@ function buildBenchRunPipelineInput(req) {
 	};
 }
 //#endregion
-//#region src/pipeline-runner/frame-lazy-metrics.ts
-function emptyFrameLazyCounters() {
-	return {
-		framesDecoded: 0,
-		framesAdmitted: 0,
-		framesDroppedPixelFree: 0,
-		viewsMaterialized: 0,
-		viewsSkipped: 0,
-		workerToRunnerBytes: 0,
-		runnerToPoolRawBytes: 0,
-		runnerToPoolJpegBytes: 0,
-		onDemandFullFrameRequests: 0,
-		onDemandCropRequests: 0,
-		nativeHits: 0,
-		nativeMisses: 0,
-		tileHits: 0,
-		tileMisses: 0,
-		fallbackHits: 0,
-		fallbackMisses: 0,
-		retainedWritesAvoided: 0,
-		residentRefs: 0,
-		residentBytes: 0,
-		releases: 0,
-		evictions: 0,
-		staleMisses: 0
+//#region src/pipeline-runner/capacity/capacity-runner.ts
+/**
+* Run ONE ramp step: `cameras` independent open-loop pacers for
+* `settleMs + measureMs`, then a bounded drain of in-flight calls.
+*/
+async function runCapacityStep(opts) {
+	const cameras = Math.max(1, Math.floor(opts.cameras));
+	const intervalMs = 1e3 / Math.max(.1, opts.fpsPerCamera);
+	const start = opts.now();
+	const measureStart = start + Math.max(0, opts.settleMs);
+	const end = measureStart + Math.max(0, opts.measureMs);
+	const c = {
+		offered: 0,
+		dispatched: 0,
+		completed: 0,
+		droppedByDriver: 0,
+		shed: 0,
+		firstClassShed: 0,
+		fallbackShed: 0,
+		errors: 0,
+		aborted: false,
+		outstanding: 0,
+		e2eMsList: [],
+		inferMsList: [],
+		predictMsList: [],
+		detectionCounts: []
 	};
-}
-var FrameLazyTelemetry = class {
-	node = emptyFrameLazyCounters();
-	cameras = /* @__PURE__ */ new Map();
-	noteDecoded(deviceId) {
-		this.node.framesDecoded += 1;
-		this.camera(deviceId).framesDecoded += 1;
-	}
-	noteAdmitted(deviceId) {
-		this.node.framesAdmitted += 1;
-		this.camera(deviceId).framesAdmitted += 1;
-	}
-	noteDroppedPixelFree(deviceId) {
-		this.node.framesDroppedPixelFree += 1;
-		this.camera(deviceId).framesDroppedPixelFree += 1;
-	}
-	noteView(input) {
-		if (input.materialized) {
-			this.node.viewsMaterialized += 1;
-			this.camera(input.deviceId).viewsMaterialized += 1;
-		} else {
-			this.node.viewsSkipped += 1;
-			this.camera(input.deviceId).viewsSkipped += 1;
-		}
-		this.node.workerToRunnerBytes += input.workerToRunnerBytes;
-		this.camera(input.deviceId).workerToRunnerBytes += input.workerToRunnerBytes;
-	}
-	notePoolBytes(input) {
-		this.node.runnerToPoolRawBytes += input.raw;
-		this.node.runnerToPoolJpegBytes += input.jpeg;
-		this.camera(input.deviceId).runnerToPoolRawBytes += input.raw;
-		this.camera(input.deviceId).runnerToPoolJpegBytes += input.jpeg;
-	}
-	noteOnDemandRequest(input) {
-		if (input.kind === "full-frame") {
-			this.node.onDemandFullFrameRequests += 1;
-			this.camera(input.deviceId).onDemandFullFrameRequests += 1;
-		} else {
-			this.node.onDemandCropRequests += 1;
-			this.camera(input.deviceId).onDemandCropRequests += 1;
+	const recordOutcome = (counted, outcome, e2eMs) => {
+		if (!counted) return;
+		if (outcome.kind === "ok") {
+			c.completed += 1;
+			c.e2eMsList.push(e2eMs);
+			c.inferMsList.push(outcome.inferMs ?? 0);
+			c.predictMsList.push(outcome.predictMs ?? 0);
+			c.detectionCounts.push(outcome.detections ?? 0);
+			return;
 		}
-	}
-	noteHit(kind, deviceId) {
-		this.addHit(this.node, kind, 1);
-		this.addHit(this.camera(deviceId), kind, 1);
-	}
-	noteMiss(kind, deviceId) {
-		this.addMiss(this.node, kind, 1);
-		this.addMiss(this.camera(deviceId), kind, 1);
-	}
-	noteAvoidedWrite(deviceId) {
-		this.node.retainedWritesAvoided += 1;
-		this.camera(deviceId).retainedWritesAvoided += 1;
-	}
-	noteRelease(deviceId) {
-		this.node.releases += 1;
-		if (deviceId !== void 0) this.camera(deviceId).releases += 1;
-	}
-	noteEviction(deviceId) {
-		this.node.evictions += 1;
-		if (deviceId !== void 0) this.camera(deviceId).evictions += 1;
-	}
-	noteStale(deviceId) {
-		this.node.staleMisses += 1;
-		if (deviceId !== void 0) this.camera(deviceId).staleMisses += 1;
-	}
-	/**
-	* Node occupancy. `residentRefs` is entry count (pending + store), not
-	* outstanding registry leases.
-	*/
-	setResident(input) {
-		this.node.residentRefs = input.refs;
-		this.node.residentBytes = input.bytes;
-	}
-	setCameraResident(deviceId, input) {
-		const counters = this.camera(deviceId);
-		counters.residentRefs = input.refs;
-		counters.residentBytes = input.bytes;
-	}
-	forgetCamera(deviceId) {
-		this.cameras.delete(deviceId);
-	}
-	/**
-	* Zero occupancy for already-tracked cameras absent from `present`.
-	* Does not create or delete entries — snapshot still does not prune,
-	* and detach still goes through {@link forgetCamera}.
-	*/
-	zeroAbsentResidents(present) {
-		for (const [deviceId, counters] of this.cameras) {
-			if (present.has(deviceId)) continue;
-			counters.residentRefs = 0;
-			counters.residentBytes = 0;
+		if (outcome.kind === "shed") {
+			c.shed += 1;
+			if (outcome.shedSignal === "zero-detections-fallback") c.fallbackShed += 1;
+			else c.firstClassShed += 1;
+			return;
 		}
-	}
-	snapshot(deviceIds) {
-		return {
-			node: { ...this.node },
-			cameras: deviceIds.map((deviceId) => ({
-				deviceId,
-				...this.camera(deviceId)
-			}))
-		};
-	}
-	trackedCameraCount() {
-		return this.cameras.size;
-	}
-	camera(deviceId) {
-		const existing = this.cameras.get(deviceId);
-		if (existing) return existing;
-		const created = emptyFrameLazyCounters();
-		this.cameras.set(deviceId, created);
-		return created;
-	}
-	addHit(counters, kind, n) {
-		if (kind === "native") counters.nativeHits += n;
-		else if (kind === "tile") counters.tileHits += n;
-		else counters.fallbackHits += n;
-	}
-	addMiss(counters, kind, n) {
-		if (kind === "native") counters.nativeMisses += n;
-		else if (kind === "tile") counters.tileMisses += n;
-		else counters.fallbackMisses += n;
-	}
-};
-//#endregion
-//#region src/pipeline-runner/frame-ref-transport.ts
-/** A local ref never leaves the grouped process; inline remains rollback/split compatibility. */
-function selectExecutorFrameSource(coLocated, frameRef, inlineFrame) {
-	return coLocated && frameRef ? { frameRef } : { frame: inlineFrame };
-}
-//#endregion
-//#region src/session-decode/on-demand-jpeg-fallback.ts
-/** Single content-sized JPEG requested after a detection, never a continuous raw. */
-var ON_DEMAND_JPEG_VIEW = {
-	content: {
-		width: 640,
-		height: 640
-	},
-	fit: "contain",
-	format: "jpeg"
-};
-function createOnDemandJpegFallback(registry, ref) {
-	const lease = registry.acquire(ref);
-	let cached;
-	let released = false;
-	const releaseLease = (reason) => {
-		if (released) return;
-		released = true;
-		lease?.release(reason);
+		c.errors += 1;
 	};
-	return {
-		async materialize() {
-			if (cached !== void 0) return cached;
-			if (!lease) {
-				cached = null;
-				return null;
+	const measureMarker = opts.onMeasureStart !== void 0 && opts.settleMs > 0 ? opts.sleepUntil(measureStart).then(() => opts.onMeasureStart?.()) : (opts.onMeasureStart?.(), Promise.resolve());
+	const cameraLoop = async (cameraIndex) => {
+		const offset = cameraIndex / cameras * intervalMs;
+		let inFlight = false;
+		for (let k = 0;; k++) {
+			const tickAt = start + offset + k * intervalMs;
+			if (tickAt >= end) break;
+			if (opts.shouldStop()) {
+				c.aborted = true;
+				break;
 			}
-			try {
-				const view = await lease.resolve(ON_DEMAND_JPEG_VIEW);
-				if (view.kind !== "view" || view.format !== "jpeg" || view.data.byteLength === 0) {
-					cached = null;
-					releaseLease("drop");
-					return null;
-				}
-				cached = {
-					data: Buffer.from(view.data.buffer, view.data.byteOffset, view.data.byteLength),
-					width: view.width,
-					height: view.height,
-					format: "jpeg",
-					timestamp: ref.timestamp,
-					...ref.capturedAt !== void 0 ? { capturedAt: ref.capturedAt } : {}
-				};
-				releaseLease("success");
-				return cached;
-			} catch {
-				cached = null;
-				releaseLease("error");
-				return null;
+			if (tickAt > opts.now()) await opts.sleepUntil(tickAt);
+			if (opts.shouldStop()) {
+				c.aborted = true;
+				break;
 			}
-		},
-		release() {
-			releaseLease("eviction");
+			const counted = tickAt >= measureStart;
+			if (counted) c.offered += 1;
+			if (inFlight) {
+				if (counted) c.droppedByDriver += 1;
+				continue;
+			}
+			inFlight = true;
+			if (counted) c.dispatched += 1;
+			const t0 = opts.now();
+			c.outstanding += 1;
+			opts.dispatch(cameraIndex).then((outcome) => recordOutcome(counted, outcome, opts.now() - t0), () => {
+				if (counted) c.errors += 1;
+			}).finally(() => {
+				inFlight = false;
+				c.outstanding -= 1;
+			});
 		}
 	};
+	await Promise.all(Array.from({ length: cameras }, (_, i) => cameraLoop(i)));
+	await measureMarker;
+	const drainDeadline = opts.now() + Math.max(0, opts.drainTimeoutMs);
+	while (c.outstanding > 0 && opts.now() < drainDeadline) await opts.sleepUntil(Math.min(drainDeadline, opts.now() + 50));
+	return {
+		offered: c.offered,
+		dispatched: c.dispatched,
+		completed: c.completed,
+		droppedByDriver: c.droppedByDriver,
+		shed: c.shed,
+		firstClassShed: c.firstClassShed,
+		fallbackShed: c.fallbackShed,
+		errors: c.errors,
+		unresolvedAtDrain: c.outstanding,
+		e2eMsList: c.e2eMsList,
+		inferMsList: c.inferMsList,
+		predictMsList: c.predictMsList,
+		detectionCounts: c.detectionCounts,
+		wallMs: opts.now() - start,
+		aborted: c.aborted
+	};
 }
-//#endregion
-//#region src/pipeline-runner/on-demand-retention.ts
-var CAMSTACK_CONTINUOUS_RETAIN = "CAMSTACK_CONTINUOUS_RETAIN";
-function isContinuousRetainEnabled(env = process.env) {
-	return env[CAMSTACK_CONTINUOUS_RETAIN] === "1";
-}
-function shouldRetainDetectionFrame(input) {
-	if (!input.admitted) return false;
-	if (input.continuousRetain) return true;
-	return input.hasDetection;
+var DEFAULT_CAPACITY_SLO = {
+	dropRatioMax: .01,
+	e2eP95MsMax: 250,
+	stallsMax: 0
+};
+/** Nearest-rank percentile on an unsorted list. Returns 0 for empty input. */
+function percentile(values, p) {
+	if (values.length === 0) return 0;
+	const sorted = [...values].toSorted((a, b) => a - b);
+	return sorted[Math.min(sorted.length - 1, Math.max(0, Math.ceil(p * sorted.length) - 1))] ?? 0;
 }
-function encodeCrossNodeCrop(input) {
-	if (!input.jpeg) return null;
-	return { jpeg: input.jpeg };
+function mean(values) {
+	if (values.length === 0) return 0;
+	return values.reduce((s, v) => s + v, 0) / values.length;
 }
-function handleKey(handle) {
-	return `${handle.shmId}#${handle.slot}#${handle.seq}`;
+/**
+* Judge one step against the SLO. Pure — the whole gate is testable without
+* a clock or a node. An error or an unresolved call is never "just a drop":
+* it means something other than flow control broke, so it fails the step
+* regardless of ratio (spec §1: errors 0 tolerated).
+*/
+function evaluateCapacityStep(raw, stall, slo) {
+	const dropRatio = raw.offered > 0 ? (raw.droppedByDriver + raw.shed) / raw.offered : 0;
+	const e2eMs = {
+		p50: percentile(raw.e2eMsList, .5),
+		p95: percentile(raw.e2eMsList, .95),
+		p99: percentile(raw.e2eMsList, .99),
+		max: raw.e2eMsList.length > 0 ? Math.max(...raw.e2eMsList) : 0
+	};
+	const failReasons = [];
+	if (dropRatio > slo.dropRatioMax) failReasons.push(`dropRatio ${(dropRatio * 100).toFixed(2)}% > ${(slo.dropRatioMax * 100).toFixed(2)}%`);
+	if (e2eMs.p95 > slo.e2eP95MsMax) failReasons.push(`e2e p95 ${Math.round(e2eMs.p95)}ms > ${slo.e2eP95MsMax}ms`);
+	if (stall.count > slo.stallsMax) failReasons.push(`event-loop stalls ${stall.count} > ${slo.stallsMax} (max ${stall.maxMs}ms)`);
+	if (raw.errors > 0) failReasons.push(`errors ${raw.errors} (0 tolerated)`);
+	if (raw.unresolvedAtDrain > 0) failReasons.push(`unresolved calls at drain ${raw.unresolvedAtDrain}`);
+	return {
+		dropRatio,
+		e2eMs,
+		inferMs: {
+			avg: mean(raw.inferMsList),
+			p95: percentile(raw.inferMsList, .95)
+		},
+		predictMs: {
+			avg: mean(raw.predictMsList),
+			p95: percentile(raw.predictMsList, .95)
+		},
+		detectionsAvg: mean(raw.detectionCounts),
+		pass: failReasons.length === 0,
+		failReasons
+	};
 }
 /**
-* Pending occupancy exists only admission → inference result. A detection
-* transfers to {@link RetainedFrameStore} (authoritative late-media owner).
-* No-detection leaves zero state. Store eviction owns fallback cleanup.
+* `N_max` — the last PASSING step's camera count, or null when none passed.
+* Steps after the first failure do not resurrect the number (the spec stops
+* at the first failing step; a re-run confirms the knee, not this fold).
 */
-var OnDemandRetentionSession = class {
-	store;
-	registry;
-	telemetry;
-	continuousRetain;
-	pending = /* @__PURE__ */ new Map();
-	constructor(options) {
-		this.store = options.store;
-		this.registry = options.registry;
-		this.telemetry = options.telemetry;
-		this.continuousRetain = options.continuousRetain;
-	}
-	get pendingSize() {
-		return this.pending.size;
-	}
-	hasPending(handle) {
-		return this.pending.has(handleKey(handle));
-	}
-	admitFrame(deviceId, frame) {
-		if (this.continuousRetain) {
-			const fallback = frame.frameRef ? createRetainedContentFallback(this.registry, frame.frameRef) : void 0;
-			const handle = this.store.write(deviceId, frame, fallback) ?? void 0;
-			if (handle) this.pending.set(handleKey(handle), {
-				deviceId,
-				ref: frame.frameRef
-			});
-			this.refreshResident();
-			return handle;
-		}
-		const handle = this.store.allocateHandle(deviceId, frame) ?? void 0;
-		if (!handle) return void 0;
-		this.pending.set(handleKey(handle), {
-			deviceId,
-			ref: frame.frameRef
-		});
-		this.telemetry.noteAvoidedWrite(deviceId);
-		this.refreshResident();
-		return handle;
-	}
-	noteFrame(input) {
-		if (input.decoded) this.telemetry.noteDecoded(input.deviceId);
-		if (input.admitted) this.telemetry.noteAdmitted(input.deviceId);
-		if (input.droppedPixelFree) this.telemetry.noteDroppedPixelFree(input.deviceId);
-	}
-	noteInferenceResult(deviceId, handle, result) {
-		if (!handle) return;
-		const key = handleKey(handle);
-		const pending = this.pending.get(key);
-		this.forgetPending(key);
-		if (!shouldRetainDetectionFrame({
-			admitted: true,
-			hasDetection: (result.detections?.length ?? 0) > 0,
-			continuousRetain: this.continuousRetain
-		})) {
-			this.refreshResident();
-			return;
-		}
-		if (this.continuousRetain) {
-			this.refreshResident();
-			return;
-		}
-		if (!pending?.ref) {
-			this.refreshResident();
-			return;
-		}
-		const fallback = createOnDemandJpegFallback(this.registry, pending.ref);
-		this.store.rememberOnDemand(deviceId, handle, fallback);
-		this.refreshResident();
-	}
-	async requestMedia(handle, request) {
-		const deviceId = this.store.getDeviceId(handle) ?? this.pending.get(handleKey(handle))?.deviceId ?? 0;
-		const kind = request.kind === "full-frame" ? "full-frame" : "crop";
-		this.telemetry.noteOnDemandRequest({
-			deviceId,
-			kind
-		});
-		if (request.nativeHit) {
-			this.telemetry.noteHit("native", deviceId);
-			return {
-				tier: "native",
-				bytes: request.nativeHit.bytes,
-				width: request.nativeHit.width,
-				height: request.nativeHit.height
-			};
-		}
-		this.telemetry.noteMiss("native", deviceId);
-		if (request.tileHit) {
-			this.telemetry.noteHit("tile", deviceId);
-			return {
-				tier: "tile",
-				bytes: request.tileHit.bytes,
-				jpeg: request.tileHit.jpeg ? request.tileHit.bytes : void 0,
-				width: request.tileHit.width,
-				height: request.tileHit.height
-			};
-		}
-		this.telemetry.noteMiss("tile", deviceId);
-		if (request.recordedStillHit) return {
-			tier: "recorded-still",
-			jpeg: request.recordedStillHit.jpeg,
-			width: request.recordedStillHit.width,
-			height: request.recordedStillHit.height
-		};
-		if (!this.continuousRetain && !this.store.has(handle)) {
-			this.telemetry.noteMiss("fallback", deviceId);
-			return { tier: "miss" };
-		}
-		const view = await this.store.ensureContent(handle);
-		if (view && view.data.byteLength > 0) {
-			this.telemetry.noteHit("fallback", deviceId);
-			this.refreshResident();
-			if (view.format === "jpeg") return {
-				tier: "fallback-jpeg",
-				jpeg: view.data,
-				width: view.width,
-				height: view.height
-			};
-			return {
-				tier: "fallback-jpeg",
-				bytes: view.data,
-				width: view.width,
-				height: view.height
-			};
-		}
-		this.telemetry.noteMiss("fallback", deviceId);
-		this.telemetry.noteStale(deviceId);
-		return { tier: "miss" };
-	}
-	/**
-	* Pending cleanup. Success never invalidates a store entry already
-	* transferred for late pull. Drop/error/detach drop the store only when the
-	* handle was still pending (not yet transferred). Eviction owns transferred
-	* fallback cleanup.
-	*/
-	release(handle, reason) {
-		const key = handleKey(handle);
-		const pending = this.pending.get(key);
-		this.forgetPending(key);
-		if (reason !== "success" && pending) this.store.drop(handle);
-		this.telemetry.noteRelease(pending?.deviceId ?? this.store.getDeviceId(handle));
-		this.refreshResident();
-	}
-	forgetDevice(deviceId) {
-		for (const [key, pending] of [...this.pending]) {
-			if (pending.deviceId !== deviceId) continue;
-			this.pending.delete(key);
-		}
-		this.telemetry.forgetCamera(deviceId);
-		this.refreshResident();
-	}
-	syncResident() {
-		this.refreshResident();
-	}
-	forgetPending(key) {
-		this.pending.delete(key);
-	}
-	refreshResident() {
-		const byDevice = /* @__PURE__ */ new Map();
-		for (const pending of this.pending.values()) {
-			const cur = byDevice.get(pending.deviceId) ?? {
-				refs: 0,
-				bytes: 0
-			};
-			cur.refs += 1;
-			byDevice.set(pending.deviceId, cur);
-		}
-		for (const stats of this.store.deviceStats()) {
-			const cur = byDevice.get(stats.deviceId) ?? {
-				refs: 0,
-				bytes: 0
-			};
-			cur.refs += stats.entries;
-			cur.bytes += stats.bytes;
-			byDevice.set(stats.deviceId, cur);
-		}
-		this.telemetry.setResident({
-			refs: this.pending.size + this.store.size,
-			bytes: this.registry.estimatedBytes + this.store.retainedBytes
-		});
-		this.telemetry.zeroAbsentResidents(new Set(byDevice.keys()));
-		for (const [deviceId, stats] of byDevice) this.telemetry.setCameraResident(deviceId, stats);
-	}
-};
-//#endregion
-//#region src/pipeline-runner/capacity/capacity-runner.ts
-/**
-* Run ONE ramp step: `cameras` independent open-loop pacers for
-* `settleMs + measureMs`, then a bounded drain of in-flight calls.
-*/
-async function runCapacityStep(opts) {
-	const cameras = Math.max(1, Math.floor(opts.cameras));
-	const intervalMs = 1e3 / Math.max(.1, opts.fpsPerCamera);
-	const start = opts.now();
-	const measureStart = start + Math.max(0, opts.settleMs);
-	const end = measureStart + Math.max(0, opts.measureMs);
-	const c = {
-		offered: 0,
-		dispatched: 0,
-		completed: 0,
-		droppedByDriver: 0,
-		shed: 0,
-		firstClassShed: 0,
-		fallbackShed: 0,
-		errors: 0,
-		aborted: false,
-		outstanding: 0,
-		e2eMsList: [],
-		inferMsList: [],
-		predictMsList: [],
-		detectionCounts: []
-	};
-	const recordOutcome = (counted, outcome, e2eMs) => {
-		if (!counted) return;
-		if (outcome.kind === "ok") {
-			c.completed += 1;
-			c.e2eMsList.push(e2eMs);
-			c.inferMsList.push(outcome.inferMs ?? 0);
-			c.predictMsList.push(outcome.predictMs ?? 0);
-			c.detectionCounts.push(outcome.detections ?? 0);
-			return;
-		}
-		if (outcome.kind === "shed") {
-			c.shed += 1;
-			if (outcome.shedSignal === "zero-detections-fallback") c.fallbackShed += 1;
-			else c.firstClassShed += 1;
-			return;
-		}
-		c.errors += 1;
-	};
-	const measureMarker = opts.onMeasureStart !== void 0 && opts.settleMs > 0 ? opts.sleepUntil(measureStart).then(() => opts.onMeasureStart?.()) : (opts.onMeasureStart?.(), Promise.resolve());
-	const cameraLoop = async (cameraIndex) => {
-		const offset = cameraIndex / cameras * intervalMs;
-		let inFlight = false;
-		for (let k = 0;; k++) {
-			const tickAt = start + offset + k * intervalMs;
-			if (tickAt >= end) break;
-			if (opts.shouldStop()) {
-				c.aborted = true;
-				break;
-			}
-			if (tickAt > opts.now()) await opts.sleepUntil(tickAt);
-			if (opts.shouldStop()) {
-				c.aborted = true;
-				break;
-			}
-			const counted = tickAt >= measureStart;
-			if (counted) c.offered += 1;
-			if (inFlight) {
-				if (counted) c.droppedByDriver += 1;
-				continue;
-			}
-			inFlight = true;
-			if (counted) c.dispatched += 1;
-			const t0 = opts.now();
-			c.outstanding += 1;
-			opts.dispatch(cameraIndex).then((outcome) => recordOutcome(counted, outcome, opts.now() - t0), () => {
-				if (counted) c.errors += 1;
-			}).finally(() => {
-				inFlight = false;
-				c.outstanding -= 1;
-			});
-		}
-	};
-	await Promise.all(Array.from({ length: cameras }, (_, i) => cameraLoop(i)));
-	await measureMarker;
-	const drainDeadline = opts.now() + Math.max(0, opts.drainTimeoutMs);
-	while (c.outstanding > 0 && opts.now() < drainDeadline) await opts.sleepUntil(Math.min(drainDeadline, opts.now() + 50));
-	return {
-		offered: c.offered,
-		dispatched: c.dispatched,
-		completed: c.completed,
-		droppedByDriver: c.droppedByDriver,
-		shed: c.shed,
-		firstClassShed: c.firstClassShed,
-		fallbackShed: c.fallbackShed,
-		errors: c.errors,
-		unresolvedAtDrain: c.outstanding,
-		e2eMsList: c.e2eMsList,
-		inferMsList: c.inferMsList,
-		predictMsList: c.predictMsList,
-		detectionCounts: c.detectionCounts,
-		wallMs: opts.now() - start,
-		aborted: c.aborted
-	};
-}
-var DEFAULT_CAPACITY_SLO = {
-	dropRatioMax: .01,
-	e2eP95MsMax: 250,
-	stallsMax: 0
-};
-/** Nearest-rank percentile on an unsorted list. Returns 0 for empty input. */
-function percentile(values, p) {
-	if (values.length === 0) return 0;
-	const sorted = [...values].toSorted((a, b) => a - b);
-	return sorted[Math.min(sorted.length - 1, Math.max(0, Math.ceil(p * sorted.length) - 1))] ?? 0;
-}
-function mean(values) {
-	if (values.length === 0) return 0;
-	return values.reduce((s, v) => s + v, 0) / values.length;
-}
-/**
-* Judge one step against the SLO. Pure — the whole gate is testable without
-* a clock or a node. An error or an unresolved call is never "just a drop":
-* it means something other than flow control broke, so it fails the step
-* regardless of ratio (spec §1: errors 0 tolerated).
-*/
-function evaluateCapacityStep(raw, stall, slo) {
-	const dropRatio = raw.offered > 0 ? (raw.droppedByDriver + raw.shed) / raw.offered : 0;
-	const e2eMs = {
-		p50: percentile(raw.e2eMsList, .5),
-		p95: percentile(raw.e2eMsList, .95),
-		p99: percentile(raw.e2eMsList, .99),
-		max: raw.e2eMsList.length > 0 ? Math.max(...raw.e2eMsList) : 0
-	};
-	const failReasons = [];
-	if (dropRatio > slo.dropRatioMax) failReasons.push(`dropRatio ${(dropRatio * 100).toFixed(2)}% > ${(slo.dropRatioMax * 100).toFixed(2)}%`);
-	if (e2eMs.p95 > slo.e2eP95MsMax) failReasons.push(`e2e p95 ${Math.round(e2eMs.p95)}ms > ${slo.e2eP95MsMax}ms`);
-	if (stall.count > slo.stallsMax) failReasons.push(`event-loop stalls ${stall.count} > ${slo.stallsMax} (max ${stall.maxMs}ms)`);
-	if (raw.errors > 0) failReasons.push(`errors ${raw.errors} (0 tolerated)`);
-	if (raw.unresolvedAtDrain > 0) failReasons.push(`unresolved calls at drain ${raw.unresolvedAtDrain}`);
-	return {
-		dropRatio,
-		e2eMs,
-		inferMs: {
-			avg: mean(raw.inferMsList),
-			p95: percentile(raw.inferMsList, .95)
-		},
-		predictMs: {
-			avg: mean(raw.predictMsList),
-			p95: percentile(raw.predictMsList, .95)
-		},
-		detectionsAvg: mean(raw.detectionCounts),
-		pass: failReasons.length === 0,
-		failReasons
-	};
-}
-/**
-* `N_max` — the last PASSING step's camera count, or null when none passed.
-* Steps after the first failure do not resurrect the number (the spec stops
-* at the first failing step; a re-run confirms the knee, not this fold).
-*/
-function computeNMax(steps) {
-	let nMax = null;
-	for (const step of steps) {
-		if (!step.pass) return {
-			nMax,
-			failedStep: step.cameras
-		};
-		nMax = step.cameras;
+function computeNMax(steps) {
+	let nMax = null;
+	for (const step of steps) {
+		if (!step.pass) return {
+			nMax,
+			failedStep: step.cameras
+		};
+		nMax = step.cameras;
 	}
 	return {
 		nMax,
@@ -2970,40 +2704,197 @@ function resolveStepDevice(input) {
 			reason: "manual"
 		};
 	}
-	if (canRunOn(effectiveDeviceKey, canRun)) return {
-		kind: "no-jump",
-		deviceKey: effectiveDeviceKey
-	};
-	const runnable = input.devices.filter((d) => d.deviceKey !== effectiveDeviceKey && (d.maxSessions === null || d.attachedCameras < d.maxSessions) && canRunOn(d.deviceKey, canRun));
-	if (runnable.length === 0) return {
-		kind: "no-candidate",
-		deviceKey: effectiveDeviceKey
-	};
-	return {
-		kind: "jumped",
-		deviceKey: pickWeightedLeastLoaded(runnable).deviceKey,
-		reason: "auto"
-	};
-}
-//#endregion
-//#region src/pipeline-runner/device-load.ts
-/** The backend prefix of a `<backend>:<device>` key (bare `cpu` → `cpu`). */
-function backendOf(deviceKey) {
-	const colon = deviceKey.indexOf(":");
-	return colon >= 0 ? deviceKey.slice(0, colon) : deviceKey;
-}
-function summarizeDeviceLoad(attachedDeviceKeys) {
-	const counts = /* @__PURE__ */ new Map();
-	for (const key of attachedDeviceKeys) {
-		if (!key) continue;
-		counts.set(key, (counts.get(key) ?? 0) + 1);
+	if (canRunOn(effectiveDeviceKey, canRun)) return {
+		kind: "no-jump",
+		deviceKey: effectiveDeviceKey
+	};
+	const runnable = input.devices.filter((d) => d.deviceKey !== effectiveDeviceKey && (d.maxSessions === null || d.attachedCameras < d.maxSessions) && canRunOn(d.deviceKey, canRun));
+	if (runnable.length === 0) return {
+		kind: "no-candidate",
+		deviceKey: effectiveDeviceKey
+	};
+	return {
+		kind: "jumped",
+		deviceKey: pickWeightedLeastLoaded(runnable).deviceKey,
+		reason: "auto"
+	};
+}
+//#endregion
+//#region src/pipeline-runner/device-load.ts
+/** The backend prefix of a `<backend>:<device>` key (bare `cpu` → `cpu`). */
+function backendOf(deviceKey) {
+	const colon = deviceKey.indexOf(":");
+	return colon >= 0 ? deviceKey.slice(0, colon) : deviceKey;
+}
+function summarizeDeviceLoad(attachedDeviceKeys) {
+	const counts = /* @__PURE__ */ new Map();
+	for (const key of attachedDeviceKeys) {
+		if (!key) continue;
+		counts.set(key, (counts.get(key) ?? 0) + 1);
+	}
+	return Array.from(counts.entries()).map(([deviceKey, attachedCameras]) => ({
+		deviceKey,
+		backend: backendOf(deviceKey),
+		attachedCameras,
+		queueDepthTotal: 0
+	})).toSorted((a, b) => a.deviceKey.localeCompare(b.deviceKey));
+}
+//#endregion
+//#region src/pipeline-runner/frame-lazy-metrics.ts
+function emptyFrameLazyCounters() {
+	return {
+		framesDecoded: 0,
+		framesAdmitted: 0,
+		framesDroppedPixelFree: 0,
+		viewsMaterialized: 0,
+		viewsSkipped: 0,
+		workerToRunnerBytes: 0,
+		runnerToPoolRawBytes: 0,
+		runnerToPoolJpegBytes: 0,
+		onDemandFullFrameRequests: 0,
+		onDemandCropRequests: 0,
+		nativeHits: 0,
+		nativeMisses: 0,
+		tileHits: 0,
+		tileMisses: 0,
+		fallbackHits: 0,
+		fallbackMisses: 0,
+		retainedWritesAvoided: 0,
+		residentRefs: 0,
+		residentBytes: 0,
+		releases: 0,
+		evictions: 0,
+		staleMisses: 0
+	};
+}
+var FrameLazyTelemetry = class {
+	node = emptyFrameLazyCounters();
+	cameras = /* @__PURE__ */ new Map();
+	noteDecoded(deviceId) {
+		this.node.framesDecoded += 1;
+		this.camera(deviceId).framesDecoded += 1;
+	}
+	noteAdmitted(deviceId) {
+		this.node.framesAdmitted += 1;
+		this.camera(deviceId).framesAdmitted += 1;
+	}
+	noteDroppedPixelFree(deviceId) {
+		this.node.framesDroppedPixelFree += 1;
+		this.camera(deviceId).framesDroppedPixelFree += 1;
+	}
+	noteView(input) {
+		if (input.materialized) {
+			this.node.viewsMaterialized += 1;
+			this.camera(input.deviceId).viewsMaterialized += 1;
+		} else {
+			this.node.viewsSkipped += 1;
+			this.camera(input.deviceId).viewsSkipped += 1;
+		}
+		this.node.workerToRunnerBytes += input.workerToRunnerBytes;
+		this.camera(input.deviceId).workerToRunnerBytes += input.workerToRunnerBytes;
+	}
+	notePoolBytes(input) {
+		this.node.runnerToPoolRawBytes += input.raw;
+		this.node.runnerToPoolJpegBytes += input.jpeg;
+		this.camera(input.deviceId).runnerToPoolRawBytes += input.raw;
+		this.camera(input.deviceId).runnerToPoolJpegBytes += input.jpeg;
+	}
+	noteOnDemandRequest(input) {
+		if (input.kind === "full-frame") {
+			this.node.onDemandFullFrameRequests += 1;
+			this.camera(input.deviceId).onDemandFullFrameRequests += 1;
+		} else {
+			this.node.onDemandCropRequests += 1;
+			this.camera(input.deviceId).onDemandCropRequests += 1;
+		}
+	}
+	noteHit(kind, deviceId) {
+		this.addHit(this.node, kind, 1);
+		this.addHit(this.camera(deviceId), kind, 1);
+	}
+	noteMiss(kind, deviceId) {
+		this.addMiss(this.node, kind, 1);
+		this.addMiss(this.camera(deviceId), kind, 1);
+	}
+	noteAvoidedWrite(deviceId) {
+		this.node.retainedWritesAvoided += 1;
+		this.camera(deviceId).retainedWritesAvoided += 1;
+	}
+	noteRelease(deviceId) {
+		this.node.releases += 1;
+		if (deviceId !== void 0) this.camera(deviceId).releases += 1;
+	}
+	noteEviction(deviceId) {
+		this.node.evictions += 1;
+		if (deviceId !== void 0) this.camera(deviceId).evictions += 1;
+	}
+	noteStale(deviceId) {
+		this.node.staleMisses += 1;
+		if (deviceId !== void 0) this.camera(deviceId).staleMisses += 1;
+	}
+	/**
+	* Node occupancy. `residentRefs` is entry count (pending + store), not
+	* outstanding registry leases.
+	*/
+	setResident(input) {
+		this.node.residentRefs = input.refs;
+		this.node.residentBytes = input.bytes;
+	}
+	setCameraResident(deviceId, input) {
+		const counters = this.camera(deviceId);
+		counters.residentRefs = input.refs;
+		counters.residentBytes = input.bytes;
+	}
+	forgetCamera(deviceId) {
+		this.cameras.delete(deviceId);
+	}
+	/**
+	* Zero occupancy for already-tracked cameras absent from `present`.
+	* Does not create or delete entries — snapshot still does not prune,
+	* and detach still goes through {@link forgetCamera}.
+	*/
+	zeroAbsentResidents(present) {
+		for (const [deviceId, counters] of this.cameras) {
+			if (present.has(deviceId)) continue;
+			counters.residentRefs = 0;
+			counters.residentBytes = 0;
+		}
+	}
+	snapshot(deviceIds) {
+		return {
+			node: { ...this.node },
+			cameras: deviceIds.map((deviceId) => ({
+				deviceId,
+				...this.camera(deviceId)
+			}))
+		};
+	}
+	trackedCameraCount() {
+		return this.cameras.size;
+	}
+	camera(deviceId) {
+		const existing = this.cameras.get(deviceId);
+		if (existing) return existing;
+		const created = emptyFrameLazyCounters();
+		this.cameras.set(deviceId, created);
+		return created;
 	}
-	return Array.from(counts.entries()).map(([deviceKey, attachedCameras]) => ({
-		deviceKey,
-		backend: backendOf(deviceKey),
-		attachedCameras,
-		queueDepthTotal: 0
-	})).toSorted((a, b) => a.deviceKey.localeCompare(b.deviceKey));
+	addHit(counters, kind, n) {
+		if (kind === "native") counters.nativeHits += n;
+		else if (kind === "tile") counters.tileHits += n;
+		else counters.fallbackHits += n;
+	}
+	addMiss(counters, kind, n) {
+		if (kind === "native") counters.nativeMisses += n;
+		else if (kind === "tile") counters.tileMisses += n;
+		else counters.fallbackMisses += n;
+	}
+};
+//#endregion
+//#region src/pipeline-runner/frame-ref-transport.ts
+/** A local ref never leaves the grouped process; inline remains rollback/split compatibility. */
+function selectExecutorFrameSource(coLocated, frameRef, inlineFrame) {
+	return coLocated && frameRef ? { frameRef } : { frame: inlineFrame };
 }
 //#endregion
 //#region src/pipeline-runner/hardware-capabilities.ts
@@ -3157,81 +3048,470 @@ var INITIAL_STATE = {
 	burstRemaining: 0,
 	burstNextAt: 0
 };
-var NO_RUN = {
-	run: false,
-	reason: null
+var NO_RUN = {
+	run: false,
+	reason: null
+};
+var MotionSettleGovernor = class {
+	config;
+	state = /* @__PURE__ */ new Map();
+	constructor(config = DEFAULT_MOTION_SETTLE_CONFIG) {
+		this.config = config;
+	}
+	/**
+	* Decide whether `package-detection` runs for this device this frame, and
+	* advance the per-device state immutably. Never throws.
+	*/
+	evaluate(sample) {
+		const prev = this.state.get(sample.deviceId) ?? INITIAL_STATE;
+		const lastMotionAt = sample.motionInZone ? sample.now : prev.lastMotionAt;
+		const armed = sample.motionInZone ? true : prev.armed;
+		const settleReady = armed && !sample.motionInZone && lastMotionAt !== null && sample.now - lastMotionAt >= this.config.settleMs;
+		const pollReady = sample.now - prev.lastRunAt >= this.config.pollIntervalMs;
+		if (settleReady) {
+			this.state.set(sample.deviceId, {
+				lastMotionAt,
+				armed: false,
+				lastRunAt: sample.now,
+				burstRemaining: Math.max(0, this.config.burstCount - 1),
+				burstNextAt: sample.now + this.config.burstIntervalMs
+			});
+			return {
+				run: true,
+				reason: "settle"
+			};
+		}
+		if (prev.burstRemaining > 0 && sample.now >= prev.burstNextAt) {
+			this.state.set(sample.deviceId, {
+				lastMotionAt,
+				armed,
+				lastRunAt: sample.now,
+				burstRemaining: prev.burstRemaining - 1,
+				burstNextAt: sample.now + this.config.burstIntervalMs
+			});
+			return {
+				run: true,
+				reason: "burst"
+			};
+		}
+		if (pollReady) {
+			this.state.set(sample.deviceId, {
+				lastMotionAt,
+				armed,
+				lastRunAt: sample.now,
+				burstRemaining: prev.burstRemaining,
+				burstNextAt: prev.burstNextAt
+			});
+			return {
+				run: true,
+				reason: "poll"
+			};
+		}
+		this.state.set(sample.deviceId, {
+			lastMotionAt,
+			armed,
+			lastRunAt: prev.lastRunAt,
+			burstRemaining: prev.burstRemaining,
+			burstNextAt: prev.burstNextAt
+		});
+		return NO_RUN;
+	}
+	/** Drop a device's state (call on detach / step-disable) to avoid a leak. */
+	forget(deviceId) {
+		this.state.delete(deviceId);
+	}
+	/** Clear all state (e.g. runner teardown). */
+	reset() {
+		this.state.clear();
+	}
+};
+//#endregion
+//#region src/pipeline-runner/native-crop-tier.ts
+/**
+* Pure tier decision for `getNativeCrop`. A native HIT always resolves to the
+* native surface. On a native MISS, only a full-frame request falls back to the
+* ≤640 RAM store; an ROI miss is reported as `miss` (no quality masquerade).
+*/
+function resolveNativeCropSource(isFullFrame, nativeHit) {
+	if (nativeHit) return "native";
+	return isFullFrame ? "ram-fullframe" : "miss";
+}
+/**
+* Runtime hit kind for telemetry. A worker tile is native-resolution quality
+* (public wire `tier` stays `native`) but must not increment `nativeHits`.
+*/
+function resolveNativeCropHitKind(source) {
+	return source === "tile" ? "tile" : "native";
+}
+//#endregion
+//#region src/pipeline-runner/native-lease-settings-source.ts
+/**
+* Where the runner gets the cluster-wide native-frame LEASE knobs.
+*
+* ## Why a settings read and not the attach config
+*
+* Identical reasoning to `crop-convention-source.ts`, and worth restating
+* because the temptation is the same: `RunnerCameraConfig` is the obvious
+* orchestrator→runner channel and it is the wrong one. Eleven call sites build
+* one; a cluster-wide constant threaded through eleven builders eventually
+* reaches ten of them, and the cameras attached by the forgotten builder just
+* quietly run a different lease window. Instead the runner reads the OWNER
+* addon's global settings directly, hub-routed by `AddonCallGateway`, so an
+* agent runner transparently reads the hub-central store with no placement
+* branching.
+*
+* ## Deliberately NOT node-scoped
+*
+* The read passes no `nodeId`. With one, `addon-settings` would project that
+* node's scoped value and two nodes could hold different lease windows for the
+* same camera — so whether a stored crop is native pixels or the ≤640 fallback
+* would depend on where the balancer happened to place it, which is invisible
+* from the stored media.
+*
+* ## What it hands out
+*
+* A {@link NativeLeaseSettingsOverride} — only the knobs the operator SET. The
+* decode worker resolves the rest (env var, then the shipped default); see
+* `session-decode/native-lease-config.ts` for the precedence. Handing out a
+* fully-resolved triple here would erase the "operator set nothing" state and
+* with it the env-var escape hatch.
+*/
+/**
+* The addon whose GLOBAL settings own the knobs. `pipeline-orchestrator` is
+* hub-resident and neutral — the same owner as the detail-crop convention and
+* the per-node decoder-backend selector.
+*/
+var NATIVE_LEASE_OWNER_ADDON_ID = "pipeline-orchestrator";
+/**
+* Whether two overrides name the same knobs with the same values.
+*
+* **Every knob has to appear here.** This is the equality that decides whether
+* a re-read is ADOPTED at all: a knob missing from the comparison is read from
+* the hub, judged identical, and discarded, so the operator's change never
+* reaches a decode worker and nothing anywhere says so. `admission` shipped
+* missing from this list and did exactly that — the setting was stored, the
+* hub served it, the runner fetched it, and every worker kept spawning with the
+* old value.
+*/
+function sameOverride(a, b) {
+	return a.holdFrames === b.holdFrames && a.budgetMb === b.budgetMb && a.activityMs === b.activityMs && a.admission === b.admission && a.tileBudgetMb === b.tileBudgetMb;
+}
+/**
+* TTL-cached read of the cluster native-lease knobs.
+*
+* {@link current} is synchronous because the fork that consumes it is;
+* {@link refresh} is what talks to the hub, and the runner awaits it on the
+* path that precedes a decode-worker spawn.
+*/
+var NativeLeaseSettingsSource = class {
+	override = {};
+	lastReadAtMs = Number.NEGATIVE_INFINITY;
+	inFlight = null;
+	logger;
+	now;
+	ttlMs;
+	constructor(options) {
+		this.logger = options.logger;
+		this.now = options.now ?? (() => Date.now());
+		this.ttlMs = options.ttlMs ?? 3e4;
+	}
+	/** The operator's overrides as last read — `{}` until a read lands. */
+	current() {
+		return this.override;
+	}
+	/**
+	* Re-read if the cached value has expired. Concurrent callers share one
+	* in-flight read; a failure keeps the LAST KNOWN value rather than reverting
+	* to `{}`, because a revert would silently hand the next-spawned workers a
+	* different RAM profile than the ones already running.
+	*/
+	async refresh(api) {
+		if (api === void 0) return this.override;
+		if (this.now() - this.lastReadAtMs < this.ttlMs) return this.override;
+		this.inFlight ??= this.read(api).finally(() => {
+			this.inFlight = null;
+		});
+		await this.inFlight;
+		return this.override;
+	}
+	async read(api) {
+		try {
+			const next = require_dist.pickNativeLeaseOverride(await api.addonSettings.getGlobalSettings.query({ addonId: NATIVE_LEASE_OWNER_ADDON_ID }));
+			this.lastReadAtMs = this.now();
+			if (sameOverride(next, this.override)) return;
+			this.logger.info("native lease settings changed — applies to NEW decode sessions", { meta: {
+				from: { ...this.override },
+				to: { ...next }
+			} });
+			this.override = next;
+		} catch (err) {
+			this.logger.warn("native lease settings read failed — keeping the last known value", { meta: {
+				owner: NATIVE_LEASE_OWNER_ADDON_ID,
+				inUse: { ...this.override },
+				error: err instanceof Error ? err.message : String(err)
+			} });
+		}
+	}
+};
+//#endregion
+//#region src/session-decode/on-demand-jpeg-fallback.ts
+/** Single content-sized JPEG requested after a detection, never a continuous raw. */
+var ON_DEMAND_JPEG_VIEW = {
+	content: {
+		width: 640,
+		height: 640
+	},
+	fit: "contain",
+	format: "jpeg"
 };
-var MotionSettleGovernor = class {
-	config;
-	state = /* @__PURE__ */ new Map();
-	constructor(config = DEFAULT_MOTION_SETTLE_CONFIG) {
-		this.config = config;
+function createOnDemandJpegFallback(registry, ref) {
+	const lease = registry.acquire(ref);
+	let cached;
+	let released = false;
+	const releaseLease = (reason) => {
+		if (released) return;
+		released = true;
+		lease?.release(reason);
+	};
+	return {
+		async materialize() {
+			if (cached !== void 0) return cached;
+			if (!lease) {
+				cached = null;
+				return null;
+			}
+			try {
+				const view = await lease.resolve(ON_DEMAND_JPEG_VIEW);
+				if (view.kind !== "view" || view.format !== "jpeg" || view.data.byteLength === 0) {
+					cached = null;
+					releaseLease("drop");
+					return null;
+				}
+				cached = {
+					data: Buffer.from(view.data.buffer, view.data.byteOffset, view.data.byteLength),
+					width: view.width,
+					height: view.height,
+					format: "jpeg",
+					timestamp: ref.timestamp,
+					...ref.capturedAt !== void 0 ? { capturedAt: ref.capturedAt } : {}
+				};
+				releaseLease("success");
+				return cached;
+			} catch {
+				cached = null;
+				releaseLease("error");
+				return null;
+			}
+		},
+		release() {
+			releaseLease("eviction");
+		}
+	};
+}
+//#endregion
+//#region src/pipeline-runner/on-demand-retention.ts
+var CAMSTACK_CONTINUOUS_RETAIN = "CAMSTACK_CONTINUOUS_RETAIN";
+function isContinuousRetainEnabled(env = process.env) {
+	return env[CAMSTACK_CONTINUOUS_RETAIN] === "1";
+}
+function shouldRetainDetectionFrame(input) {
+	if (!input.admitted) return false;
+	if (input.continuousRetain) return true;
+	return input.hasDetection;
+}
+function encodeCrossNodeCrop(input) {
+	if (!input.jpeg) return null;
+	return { jpeg: input.jpeg };
+}
+function handleKey(handle) {
+	return `${handle.shmId}#${handle.slot}#${handle.seq}`;
+}
+/**
+* Pending occupancy exists only admission → inference result. A detection
+* transfers to {@link RetainedFrameStore} (authoritative late-media owner).
+* No-detection leaves zero state. Store eviction owns fallback cleanup.
+*/
+var OnDemandRetentionSession = class {
+	store;
+	registry;
+	telemetry;
+	continuousRetain;
+	pending = /* @__PURE__ */ new Map();
+	constructor(options) {
+		this.store = options.store;
+		this.registry = options.registry;
+		this.telemetry = options.telemetry;
+		this.continuousRetain = options.continuousRetain;
 	}
-	/**
-	* Decide whether `package-detection` runs for this device this frame, and
-	* advance the per-device state immutably. Never throws.
-	*/
-	evaluate(sample) {
-		const prev = this.state.get(sample.deviceId) ?? INITIAL_STATE;
-		const lastMotionAt = sample.motionInZone ? sample.now : prev.lastMotionAt;
-		const armed = sample.motionInZone ? true : prev.armed;
-		const settleReady = armed && !sample.motionInZone && lastMotionAt !== null && sample.now - lastMotionAt >= this.config.settleMs;
-		const pollReady = sample.now - prev.lastRunAt >= this.config.pollIntervalMs;
-		if (settleReady) {
-			this.state.set(sample.deviceId, {
-				lastMotionAt,
-				armed: false,
-				lastRunAt: sample.now,
-				burstRemaining: Math.max(0, this.config.burstCount - 1),
-				burstNextAt: sample.now + this.config.burstIntervalMs
+	get pendingSize() {
+		return this.pending.size;
+	}
+	hasPending(handle) {
+		return this.pending.has(handleKey(handle));
+	}
+	admitFrame(deviceId, frame) {
+		if (this.continuousRetain) {
+			const fallback = frame.frameRef ? createRetainedContentFallback(this.registry, frame.frameRef) : void 0;
+			const handle = this.store.write(deviceId, frame, fallback) ?? void 0;
+			if (handle) this.pending.set(handleKey(handle), {
+				deviceId,
+				ref: frame.frameRef
 			});
+			this.refreshResident();
+			return handle;
+		}
+		const handle = this.store.allocateHandle(deviceId, frame) ?? void 0;
+		if (!handle) return void 0;
+		this.pending.set(handleKey(handle), {
+			deviceId,
+			ref: frame.frameRef
+		});
+		this.telemetry.noteAvoidedWrite(deviceId);
+		this.refreshResident();
+		return handle;
+	}
+	noteFrame(input) {
+		if (input.decoded) this.telemetry.noteDecoded(input.deviceId);
+		if (input.admitted) this.telemetry.noteAdmitted(input.deviceId);
+		if (input.droppedPixelFree) this.telemetry.noteDroppedPixelFree(input.deviceId);
+	}
+	noteInferenceResult(deviceId, handle, result) {
+		if (!handle) return;
+		const key = handleKey(handle);
+		const pending = this.pending.get(key);
+		this.forgetPending(key);
+		if (!shouldRetainDetectionFrame({
+			admitted: true,
+			hasDetection: (result.detections?.length ?? 0) > 0,
+			continuousRetain: this.continuousRetain
+		})) {
+			this.refreshResident();
+			return;
+		}
+		if (this.continuousRetain) {
+			this.refreshResident();
+			return;
+		}
+		if (!pending?.ref) {
+			this.refreshResident();
+			return;
+		}
+		const fallback = createOnDemandJpegFallback(this.registry, pending.ref);
+		this.store.rememberOnDemand(deviceId, handle, fallback);
+		this.refreshResident();
+	}
+	async requestMedia(handle, request) {
+		const deviceId = this.store.getDeviceId(handle) ?? this.pending.get(handleKey(handle))?.deviceId ?? 0;
+		const kind = request.kind === "full-frame" ? "full-frame" : "crop";
+		this.telemetry.noteOnDemandRequest({
+			deviceId,
+			kind
+		});
+		if (request.nativeHit) {
+			this.telemetry.noteHit("native", deviceId);
 			return {
-				run: true,
-				reason: "settle"
+				tier: "native",
+				bytes: request.nativeHit.bytes,
+				width: request.nativeHit.width,
+				height: request.nativeHit.height
 			};
 		}
-		if (prev.burstRemaining > 0 && sample.now >= prev.burstNextAt) {
-			this.state.set(sample.deviceId, {
-				lastMotionAt,
-				armed,
-				lastRunAt: sample.now,
-				burstRemaining: prev.burstRemaining - 1,
-				burstNextAt: sample.now + this.config.burstIntervalMs
-			});
+		this.telemetry.noteMiss("native", deviceId);
+		if (request.tileHit) {
+			this.telemetry.noteHit("tile", deviceId);
 			return {
-				run: true,
-				reason: "burst"
+				tier: "tile",
+				bytes: request.tileHit.bytes,
+				jpeg: request.tileHit.jpeg ? request.tileHit.bytes : void 0,
+				width: request.tileHit.width,
+				height: request.tileHit.height
+			};
+		}
+		this.telemetry.noteMiss("tile", deviceId);
+		if (request.recordedStillHit) return {
+			tier: "recorded-still",
+			jpeg: request.recordedStillHit.jpeg,
+			width: request.recordedStillHit.width,
+			height: request.recordedStillHit.height
+		};
+		if (!this.continuousRetain && !this.store.has(handle)) {
+			this.telemetry.noteMiss("fallback", deviceId);
+			return { tier: "miss" };
+		}
+		const view = await this.store.ensureContent(handle);
+		if (view && view.data.byteLength > 0) {
+			this.telemetry.noteHit("fallback", deviceId);
+			this.refreshResident();
+			if (view.format === "jpeg") return {
+				tier: "fallback-jpeg",
+				jpeg: view.data,
+				width: view.width,
+				height: view.height
+			};
+			return {
+				tier: "fallback-jpeg",
+				bytes: view.data,
+				width: view.width,
+				height: view.height
+			};
+		}
+		this.telemetry.noteMiss("fallback", deviceId);
+		this.telemetry.noteStale(deviceId);
+		return { tier: "miss" };
+	}
+	/**
+	* Pending cleanup. Success never invalidates a store entry already
+	* transferred for late pull. Drop/error/detach drop the store only when the
+	* handle was still pending (not yet transferred). Eviction owns transferred
+	* fallback cleanup.
+	*/
+	release(handle, reason) {
+		const key = handleKey(handle);
+		const pending = this.pending.get(key);
+		this.forgetPending(key);
+		if (reason !== "success" && pending) this.store.drop(handle);
+		this.telemetry.noteRelease(pending?.deviceId ?? this.store.getDeviceId(handle));
+		this.refreshResident();
+	}
+	forgetDevice(deviceId) {
+		for (const [key, pending] of [...this.pending]) {
+			if (pending.deviceId !== deviceId) continue;
+			this.pending.delete(key);
+		}
+		this.telemetry.forgetCamera(deviceId);
+		this.refreshResident();
+	}
+	syncResident() {
+		this.refreshResident();
+	}
+	forgetPending(key) {
+		this.pending.delete(key);
+	}
+	refreshResident() {
+		const byDevice = /* @__PURE__ */ new Map();
+		for (const pending of this.pending.values()) {
+			const cur = byDevice.get(pending.deviceId) ?? {
+				refs: 0,
+				bytes: 0
 			};
+			cur.refs += 1;
+			byDevice.set(pending.deviceId, cur);
 		}
-		if (pollReady) {
-			this.state.set(sample.deviceId, {
-				lastMotionAt,
-				armed,
-				lastRunAt: sample.now,
-				burstRemaining: prev.burstRemaining,
-				burstNextAt: prev.burstNextAt
-			});
-			return {
-				run: true,
-				reason: "poll"
+		for (const stats of this.store.deviceStats()) {
+			const cur = byDevice.get(stats.deviceId) ?? {
+				refs: 0,
+				bytes: 0
 			};
+			cur.refs += stats.entries;
+			cur.bytes += stats.bytes;
+			byDevice.set(stats.deviceId, cur);
 		}
-		this.state.set(sample.deviceId, {
-			lastMotionAt,
-			armed,
-			lastRunAt: prev.lastRunAt,
-			burstRemaining: prev.burstRemaining,
-			burstNextAt: prev.burstNextAt
+		this.telemetry.setResident({
+			refs: this.pending.size + this.store.size,
+			bytes: this.registry.estimatedBytes + this.store.retainedBytes
 		});
-		return NO_RUN;
-	}
-	/** Drop a device's state (call on detach / step-disable) to avoid a leak. */
-	forget(deviceId) {
-		this.state.delete(deviceId);
-	}
-	/** Clear all state (e.g. runner teardown). */
-	reset() {
-		this.state.clear();
+		this.telemetry.zeroAbsentResidents(new Set(byDevice.keys()));
+		for (const [deviceId, stats] of byDevice) this.telemetry.setCameraResident(deviceId, stats);
 	}
 };
 //#endregion
@@ -3319,134 +3599,6 @@ function packageZoneUnion(polygons) {
 	};
 }
 //#endregion
-//#region src/pipeline-runner/native-crop-tier.ts
-/**
-* Pure tier decision for `getNativeCrop`. A native HIT always resolves to the
-* native surface. On a native MISS, only a full-frame request falls back to the
-* ≤640 RAM store; an ROI miss is reported as `miss` (no quality masquerade).
-*/
-function resolveNativeCropSource(isFullFrame, nativeHit) {
-	if (nativeHit) return "native";
-	return isFullFrame ? "ram-fullframe" : "miss";
-}
-/**
-* Runtime hit kind for telemetry. A worker tile is native-resolution quality
-* (public wire `tier` stays `native`) but must not increment `nativeHits`.
-*/
-function resolveNativeCropHitKind(source) {
-	return source === "tile" ? "tile" : "native";
-}
-//#endregion
-//#region src/pipeline-runner/native-lease-settings-source.ts
-/**
-* Where the runner gets the cluster-wide native-frame LEASE knobs.
-*
-* ## Why a settings read and not the attach config
-*
-* Identical reasoning to `crop-convention-source.ts`, and worth restating
-* because the temptation is the same: `RunnerCameraConfig` is the obvious
-* orchestrator→runner channel and it is the wrong one. Eleven call sites build
-* one; a cluster-wide constant threaded through eleven builders eventually
-* reaches ten of them, and the cameras attached by the forgotten builder just
-* quietly run a different lease window. Instead the runner reads the OWNER
-* addon's global settings directly, hub-routed by `AddonCallGateway`, so an
-* agent runner transparently reads the hub-central store with no placement
-* branching.
-*
-* ## Deliberately NOT node-scoped
-*
-* The read passes no `nodeId`. With one, `addon-settings` would project that
-* node's scoped value and two nodes could hold different lease windows for the
-* same camera — so whether a stored crop is native pixels or the ≤640 fallback
-* would depend on where the balancer happened to place it, which is invisible
-* from the stored media.
-*
-* ## What it hands out
-*
-* A {@link NativeLeaseSettingsOverride} — only the knobs the operator SET. The
-* decode worker resolves the rest (env var, then the shipped default); see
-* `session-decode/native-lease-config.ts` for the precedence. Handing out a
-* fully-resolved triple here would erase the "operator set nothing" state and
-* with it the env-var escape hatch.
-*/
-/**
-* The addon whose GLOBAL settings own the knobs. `pipeline-orchestrator` is
-* hub-resident and neutral — the same owner as the detail-crop convention and
-* the per-node decoder-backend selector.
-*/
-var NATIVE_LEASE_OWNER_ADDON_ID = "pipeline-orchestrator";
-/**
-* Whether two overrides name the same knobs with the same values.
-*
-* **Every knob has to appear here.** This is the equality that decides whether
-* a re-read is ADOPTED at all: a knob missing from the comparison is read from
-* the hub, judged identical, and discarded, so the operator's change never
-* reaches a decode worker and nothing anywhere says so. `admission` shipped
-* missing from this list and did exactly that — the setting was stored, the
-* hub served it, the runner fetched it, and every worker kept spawning with the
-* old value.
-*/
-function sameOverride(a, b) {
-	return a.holdFrames === b.holdFrames && a.budgetMb === b.budgetMb && a.activityMs === b.activityMs && a.admission === b.admission && a.tileBudgetMb === b.tileBudgetMb;
-}
-/**
-* TTL-cached read of the cluster native-lease knobs.
-*
-* {@link current} is synchronous because the fork that consumes it is;
-* {@link refresh} is what talks to the hub, and the runner awaits it on the
-* path that precedes a decode-worker spawn.
-*/
-var NativeLeaseSettingsSource = class {
-	override = {};
-	lastReadAtMs = Number.NEGATIVE_INFINITY;
-	inFlight = null;
-	logger;
-	now;
-	ttlMs;
-	constructor(options) {
-		this.logger = options.logger;
-		this.now = options.now ?? (() => Date.now());
-		this.ttlMs = options.ttlMs ?? 3e4;
-	}
-	/** The operator's overrides as last read — `{}` until a read lands. */
-	current() {
-		return this.override;
-	}
-	/**
-	* Re-read if the cached value has expired. Concurrent callers share one
-	* in-flight read; a failure keeps the LAST KNOWN value rather than reverting
-	* to `{}`, because a revert would silently hand the next-spawned workers a
-	* different RAM profile than the ones already running.
-	*/
-	async refresh(api) {
-		if (api === void 0) return this.override;
-		if (this.now() - this.lastReadAtMs < this.ttlMs) return this.override;
-		this.inFlight ??= this.read(api).finally(() => {
-			this.inFlight = null;
-		});
-		await this.inFlight;
-		return this.override;
-	}
-	async read(api) {
-		try {
-			const next = require_dist.pickNativeLeaseOverride(await api.addonSettings.getGlobalSettings.query({ addonId: NATIVE_LEASE_OWNER_ADDON_ID }));
-			this.lastReadAtMs = this.now();
-			if (sameOverride(next, this.override)) return;
-			this.logger.info("native lease settings changed — applies to NEW decode sessions", { meta: {
-				from: { ...this.override },
-				to: { ...next }
-			} });
-			this.override = next;
-		} catch (err) {
-			this.logger.warn("native lease settings read failed — keeping the last known value", { meta: {
-				owner: NATIVE_LEASE_OWNER_ADDON_ID,
-				inUse: { ...this.override },
-				error: err instanceof Error ? err.message : String(err)
-			} });
-		}
-	}
-};
-//#endregion
 //#region src/pipeline-runner/frame-governor.ts
 var FrameGovernor = class {
 	config;
@@ -4610,76 +4762,6 @@ var PipelineRunner = class {
 	}
 };
 //#endregion
-//#region src/session-decode/live-worker-admission.ts
-/**
-* The node's live-decode-worker budget.
-*
-* One instance per runner addon. Not a semaphore: a semaphore's contract is
-* "wait", and waiting is the thing this deliberately does not do — see
-* {@link DEFAULT_MAX_LIVE_DECODE_WORKERS}.
-*/
-var LiveDecodeWorkerAdmission = class {
-	limit;
-	logger;
-	live = 0;
-	constructor(options) {
-		this.limit = Math.max(1, options.limit);
-		this.logger = options.logger;
-	}
-	/** Workers currently holding a slot. */
-	get inFlight() {
-		return this.live;
-	}
-	get ceiling() {
-		return this.limit;
-	}
-	/**
-	* Apply an operator-changed ceiling.
-	*
-	* Lowering it never kills a running session — a decode worker torn down
-	* mid-motion loses the event it was started for. It only stops the next
-	* admission, so the count drains to the new ceiling as sessions end.
-	*/
-	resize(limit) {
-		this.limit = Math.max(1, limit);
-	}
-	/**
-	* Take a slot, or refuse.
-	*
-	* A refusal is a WARN and carries `tags.deviceId`, because the only useful
-	* form of this question is per-camera ("why did 617 not run when 615 did?").
-	* A branch that drops work silently reads as "it never happened".
-	*/
-	admit(deviceId, label) {
-		if (this.live >= this.limit) {
-			this.logger.warn("session-decode: REFUSED — node live decode-worker ceiling reached, will retry", {
-				tags: { deviceId },
-				meta: {
-					label,
-					live: this.live,
-					ceiling: this.limit
-				}
-			});
-			return null;
-		}
-		this.live += 1;
-		this.logger.debug("session-decode: live decode-worker slot taken", {
-			tags: { deviceId },
-			meta: {
-				label,
-				live: this.live,
-				ceiling: this.limit
-			}
-		});
-		let released = false;
-		return { release: () => {
-			if (released) return;
-			released = true;
-			this.live -= 1;
-		} };
-	}
-};
-//#endregion
 //#region src/pipeline-runner/stateless-step.ts
 function modelServability(step, modelId, format) {
 	const entry = step.models.find((m) => m.id === modelId);
@@ -4819,7 +4901,8 @@ var DEFAULT_CONFIG = {
 	targetLoadPercent: 80,
 	minThrottledFps: 1,
 	maxConcurrentDecodeSpawns: 3,
-	maxLiveDecodeWorkers: 8
+	maxLiveDecodeWorkers: 8,
+	nodeDecodeBudgetMb: DEFAULT_NODE_DECODE_BUDGET_MB
 };
 /**
 * Camera attachment record kept by the runner addon. Holds the original
@@ -5382,7 +5465,9 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends require_dist.BaseAdd
 		this.spawnGate = new Semaphore(Math.max(1, this.config.maxConcurrentDecodeSpawns));
 		this.liveWorkers = new LiveDecodeWorkerAdmission({
 			limit: this.config.maxLiveDecodeWorkers,
-			logger: this.ctx.logger
+			logger: this.ctx.logger,
+			nodeBudgetMb: this.config.nodeDecodeBudgetMb,
+			workerFootprintMb: decodeWorkerFootprintMb(this.nativeLease.current())
 		});
 		this.runner.timingSampler.setLogger(this.ctx.logger.child("timing"));
 		this.runner.onDetectionStreamChange((deviceId, action) => {
@@ -6586,6 +6671,7 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends require_dist.BaseAdd
 	*/
 	async refreshNativeLeaseSettings() {
 		await this.nativeLease.refresh(this.ctxIfReady?.api);
+		this.liveWorkers?.resizeFootprint(decodeWorkerFootprintMb(this.nativeLease.current()));
 	}
 	/** A warn sink that survives a not-yet-ready ctx (boot-order dispatches). */
 	detailSubtreeLogger() {
@@ -8055,12 +8141,23 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends require_dist.BaseAdd
 					type: "slider",
 					key: "maxLiveDecodeWorkers",
 					label: "Max live decode workers",
-					description: "Hard ceiling on decode workers ALIVE at once on this node (~320 MB of RAM each). Unlike the spawn gate above, which only limits how fast workers START, this limits how many EXIST. A camera that does not fit is REFUSED and logged, then retried automatically as soon as a slot frees — it is never queued, because a queued live session would decode a moment that has already passed. Raise it if the node has RAM to spare; lower it if the host is memory-constrained.",
+					description: "Upper CLAMP on decode workers ALIVE at once on this node. The bound that normally decides is the RAM budget below — the ceiling in force is whichever of the two is smaller. Unlike the spawn gate above, which only limits how fast workers START, this limits how many EXIST. A camera that does not fit is REFUSED and logged, then retried automatically as soon as a slot frees — it is never queued, because a queued live session would decode a moment that has already passed.",
 					min: 1,
 					max: 32,
 					step: 1,
 					default: DEFAULT_CONFIG.maxLiveDecodeWorkers,
 					showValue: true
+				},
+				{
+					type: "slider",
+					key: "nodeDecodeBudgetMb",
+					label: "Decode worker RAM budget (MB)",
+					description: "RAM this node lets live decode workers commit. The number of workers admitted is derived from it: budget divided by one worker's worst case, which is the lease budget + tile budget + ~350 MB of baseline. Measured on this cluster a worker plateaus at 650-860 MB within ten seconds of spawning, so at the shipped lease knobs the default admits 4 — the observed peak. Raising the lease budget per worker therefore LOWERS how many run at once, instead of silently authorising more memory.",
+					min: 1024,
+					max: 32768,
+					step: 512,
+					default: DEFAULT_CONFIG.nodeDecodeBudgetMb,
+					showValue: true
 				}
 			]
 		}] });
@@ -8069,13 +8166,17 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends require_dist.BaseAdd
 		this.runner?.updateLimits(this.config);
 		this.spawnGate?.resize(Math.max(1, this.config.maxConcurrentDecodeSpawns));
 		this.liveWorkers?.resize(this.config.maxLiveDecodeWorkers);
+		this.liveWorkers?.resizeBudget(this.config.nodeDecodeBudgetMb);
 		this.ctx.logger.info("pipeline-runner tuning updated", { meta: {
 			maxQueueDepth: this.config.maxQueueDepth,
 			maxConcurrentInferences: this.config.maxConcurrentInferences,
 			targetLoadPercent: this.config.targetLoadPercent,
 			minThrottledFps: this.config.minThrottledFps,
 			maxConcurrentDecodeSpawns: this.config.maxConcurrentDecodeSpawns,
-			maxLiveDecodeWorkers: this.config.maxLiveDecodeWorkers
+			maxLiveDecodeWorkers: this.config.maxLiveDecodeWorkers,
+			nodeDecodeBudgetMb: this.config.nodeDecodeBudgetMb,
+			decodeCeilingInForce: this.liveWorkers?.ceiling,
+			decodeWorkerFootprintMb: decodeWorkerFootprintMb(this.nativeLease.current())
 		} });
 	}
 };