@camstack/addon-pipeline 1.2.295 → 1.2.297

package/dist/pipeline-runner/index.js

@@ -3,10 +3,10 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 const require_chunk = require("../chunk-emK7D4bc.js");
-const require_dist = require("../dist-BsVcf5wO.js");
-const require_node = require("../node-UFk6I2f6.js");
-const require_default_detection_model = require("../default-detection-model-wNEISVA9.js");
-const require_worker_protocol = require("../worker-protocol-B2MfQLlu.js");
+const require_dist = require("../dist-DUqr1zyq.js");
+const require_node = require("../node-Dx6DLQ1j.js");
+const require_default_detection_model = require("../default-detection-model-B2n_SFXt.js");
+const require_worker_protocol = require("../worker-protocol-C-G8qmye.js");
 const require_hub_hostname = require("../hub-hostname-DAJXlOgV.js");
 const require_lazy_sharp = require("../lazy-sharp-BuwKlQLR.js");
 const require_restream_intent = require("../restream-intent-7uDNqMKs.js");
@@ -21,7 +21,7 @@ let node_perf_hooks = require("node:perf_hooks");
 let _camstack_system_addon_utils = require("@camstack/system/addon-utils");
 //#region src/session-decode/fork-decode-worker.ts
 /** Absolute path to the built decode-worker child entry (a vite build entry). */
-var CHILD_ENTRY_PATH = (0, node_url.fileURLToPath)(new URL("../session-decode/decode-worker-child.js", require("url").pathToFileURL(__filename).href));
+var CHILD_ENTRY_PATH = (0, node_url.fileURLToPath)(new URL("../session-decode/decode-worker-main.js", require("url").pathToFileURL(__filename).href));
 /**
 * Known kill signals the coordinator may pass, mapped to their `NodeJS.Signals`
 * literal so `ChildProcess.kill` receives a correctly-typed signal without a
@@ -42,21 +42,36 @@ var KILL_SIGNALS = {
 * every listener added out here is one somebody can forget to remove.
 */
 function wrapChild(child, onExit) {
-	child.on("error", () => void 0);
-	child.on("exit", onExit);
+	let spawned = false;
+	let exitDelivered = false;
+	const exitListeners = [];
+	const deliverExit = (info) => {
+		if (exitDelivered) return;
+		exitDelivered = true;
+		onExit();
+		for (const listener of exitListeners) listener(info);
+	};
+	child.on("spawn", () => {
+		spawned = true;
+	});
+	child.on("exit", (code, signal) => deliverExit({
+		code: code ?? null,
+		signal: signal ?? null
+	}));
+	child.on("error", () => {
+		if (!spawned) deliverExit({
+			code: null,
+			signal: null
+		});
+	});
 	return {
 		send: (msg) => {
 			if (!child.connected) return;
 			child.send(msg, () => void 0);
 		},
 		on: (ev, cb) => {
-			if (ev === "exit") {
-				const toInfo = (code, signal) => ({
-					code,
-					signal
-				});
-				child.on("exit", (code, signal) => cb(toInfo(code ?? null, signal ?? null)));
-			} else child.on("message", (m) => cb(m));
+			if (ev === "exit") exitListeners.push(cb);
+			else child.on("message", (m) => cb(m));
 		},
 		kill: (signal) => {
 			if (signal === void 0) {
@@ -257,58 +272,77 @@ var DEFAULT_ACQUIRE_RETRY_DELAYS_MS = [
 	15e3,
 	3e4
 ];
-/**
-* Guards the in-flight restream-acquire against a detach/unsubscribe race,
-* and retries an acquire that fails.
-*
-* `acquireSessionDecodeRestream` + forking the decode worker both take real
-* time (a broker round-trip, then a process fork). If the caller's teardown
-* runs while that acquire is still in flight, the closure that would release
-* the restream and stop the pump does not exist yet by the time the caller
-* stores it — a naive `await acquire(); return () => {...}` construction
-* leaks the acquired restream refcount and, once the acquire resolves, forks
-* an orphan decode worker nobody will ever stop.
-*
-* This helper returns the teardown SYNCHRONOUSLY. The acquire + pump-start
-* run in the background; an `aborted` flag recorded by the (possibly
-* already-called) teardown is checked right after each acquire resolves —
-* if set, any restream is released immediately and the pump is NEVER
-* started (no orphan worker). Otherwise the pump starts and the teardown,
-* once called, stops the pump then releases the restream.
-*
-* **A failed acquire is retried, not swallowed.** The teardown handed back
-* here is stored by the caller (as `attachment.detectionUnsubscribe`) the
-* instant this returns, so a `return` on failure left that handle permanently
-* non-null with no pump behind it: `onEnded` could never fire because nothing
-* had ever started, the camera's phase stayed `active`, and not one frame
-* arrived again. The motion path was hardened against this shape by a frame
-* freshness window (`MOTION_FRESHNESS_WINDOW_MS`); this is the detection
-* path's half.
-*/
+/** A restream release that runs once however many paths reach it. */
+function onceRelease(release) {
+	let done = false;
+	return () => {
+		if (done) return Promise.resolve();
+		done = true;
+		return release();
+	};
+}
 function startGuardedSessionDecode(deps) {
 	let aborted = false;
+	/** The mode the teardown asked for — replayed if it raced `startPump`. */
+	let abortMode = "drain";
 	let stopPump = null;
 	let release = null;
 	let retryTimer = null;
 	/** The live-worker slot held by the RUNNING session, released on teardown. */
 	let workerLease = null;
 	const delays = deps.acquireRetryDelaysMs && deps.acquireRetryDelaysMs.length > 0 ? deps.acquireRetryDelaysMs : DEFAULT_ACQUIRE_RETRY_DELAYS_MS;
-	/** Resolves after the backoff for `attempt`, or immediately once aborted. */
-	const waitBackoff = (attempt) => new Promise((resolve) => {
+	/** Ends a parked start's wait when the session is torn down. */
+	let abortWait = null;
+	/**
+	* This start's place in the ceiling queue — taken on its first refusal, kept
+	* to the end so a re-park keeps the FIFO position (D652).
+	*/
+	let waiter = null;
+	/**
+	* The start was handed a returned slot and has not yet ASKED for it. Set on
+	* a wake, cleared by the next `admitWorker` call; a start torn down while
+	* this is set passes the slot on (`SlotWaiter.leave(true)`), or nobody gets
+	* it and every other parked start waits out its full timer.
+	*/
+	let wakeInHand = false;
+	/**
+	* Resolves after the backoff for `attempt` (`'timer'`) — or, when `parked`,
+	* as soon as the node hands this start a returned slot (`'woken'`) or the
+	* session is torn down (`'torn-down'`), whichever is first. The start leaves
+	* the queue on every exit, so a torn-down start leaves no listener behind.
+	*/
+	const waitBackoff = (attempt, parked) => new Promise((resolve) => {
 		const ms = delays[Math.min(attempt, delays.length - 1)] ?? delays[delays.length - 1] ?? 2e3;
-		retryTimer = setTimeout(() => {
-			retryTimer = null;
-			resolve();
-		}, ms);
+		const done = (why) => {
+			if (retryTimer !== null) {
+				clearTimeout(retryTimer);
+				retryTimer = null;
+			}
+			parked?.cancel();
+			abortWait = null;
+			resolve(why);
+		};
+		retryTimer = setTimeout(() => done("timer"), ms);
 		retryTimer.unref?.();
+		abortWait = () => done("torn-down");
+		if (parked) parked.wait(() => done("woken"));
 	});
-	(async () => {
+	const releaseWorkerSlot = () => {
+		workerLease?.release();
+		workerLease = null;
+	};
+	const startLoop = async () => {
 		for (let attempt = 0; !aborted; attempt++) {
 			let lease = null;
 			if (deps.admitWorker) {
+				wakeInHand = false;
 				lease = deps.admitWorker();
 				if (!lease) {
-					await waitBackoff(attempt);
+					waiter ??= deps.slotWaiter?.() ?? null;
+					if (await waitBackoff(attempt, waiter) === "woken") {
+						attempt -= 1;
+						wakeInHand = true;
+					}
 					continue;
 				}
 			}
@@ -321,7 +355,7 @@ function startGuardedSessionDecode(deps) {
 					attempt: attempt + 1,
 					error: require_dist.errMsg(err)
 				} });
-				await waitBackoff(attempt);
+				await waitBackoff(attempt, null);
 				continue;
 			}
 			if (aborted) {
@@ -332,27 +366,47 @@ function startGuardedSessionDecode(deps) {
 			if (!acquired) {
 				lease?.release();
 				(attempt === 0 ? deps.logger.warn : deps.logger.debug).call(deps.logger, "session-decode: no broker profile bound yet — retrying", { meta: { attempt: attempt + 1 } });
-				await waitBackoff(attempt);
+				await waitBackoff(attempt, null);
 				continue;
 			}
 			if (attempt > 0) deps.logger.info("session-decode: acquire succeeded after retry", { meta: { attempts: attempt + 1 } });
-			release = acquired.release;
+			release = onceRelease(acquired.release);
 			workerLease = lease;
-			stopPump = deps.startPump(acquired.source);
+			try {
+				stopPump = deps.startPump(acquired.source, { onWorkerGone: releaseWorkerSlot });
+			} catch (err) {
+				releaseWorkerSlot();
+				const restream = release;
+				release = null;
+				restream?.();
+				throw err;
+			}
+			if (aborted) stopPump(abortMode);
 			return;
 		}
-	})().catch((err) => {
+	};
+	startLoop().catch((err) => {
 		deps.logger.warn("session-decode: guarded start failed", { meta: { error: require_dist.errMsg(err) } });
+	}).finally(() => {
+		waiter?.leave(wakeInHand);
+		waiter = null;
 	});
-	return () => {
+	return (mode = "drain") => {
+		if (aborted) {
+			if (mode === "immediate" && abortMode !== "immediate") {
+				abortMode = mode;
+				stopPump?.(mode);
+			}
+			return;
+		}
 		aborted = true;
+		abortMode = mode;
 		if (retryTimer !== null) {
 			clearTimeout(retryTimer);
 			retryTimer = null;
 		}
-		stopPump?.();
-		workerLease?.release();
-		workerLease = null;
+		abortWait?.();
+		stopPump?.(mode);
 		if (release) release();
 	};
 }
@@ -421,6 +475,21 @@ var LiveDecodeWorkerAdmission = class {
 	limit;
 	logger;
 	live = 0;
+	/**
+	* Starts the ceiling refused, waiting to be told a slot came back — FIFO by
+	* the start's FIRST park (D652): the key's `seq` is fixed when the start
+	* takes its {@link SlotWaiter}, so a re-park keeps the place.
+	*/
+	parked = /* @__PURE__ */ new Map();
+	nextSeq = 0;
+	/**
+	* Cameras currently refused. The refusal WARN fires on the transition into
+	* this set, not on every retry: a start woken or retried while the node is
+	* still full says so at debug (D652 — a wake must not become a WARN storm).
+	* Cleared on admit AND when a parked start leaves (`SlotWaiter.leave`): a
+	* camera torn down while refused must be news again next time (D391).
+	*/
+	refusedDevices = /* @__PURE__ */ new Set();
 	nodeBudgetMb;
 	workerFootprintMb;
 	constructor(options) {
@@ -429,6 +498,48 @@ var LiveDecodeWorkerAdmission = class {
 		this.nodeBudgetMb = positiveOrUndefined(options.nodeBudgetMb);
 		this.workerFootprintMb = positiveOrUndefined(options.workerFootprintMb);
 	}
+	/** Starts parked on a {@link SlotWaiter} right now — diagnostics and tests. */
+	get slotWaiters() {
+		return this.parked.size;
+	}
+	/**
+	* This start's place in the queue. A refused start waits on it instead of a
+	* fixed timer, so a slot freed by a draining worker's exit is taken at once
+	* (D652). Take it once per start, on the first refusal; keep it to the end.
+	*/
+	slotWaiter(deviceId) {
+		const key = {
+			seq: this.nextSeq,
+			deviceId
+		};
+		this.nextSeq += 1;
+		return {
+			wait: (listener) => {
+				this.parked.set(key, listener);
+			},
+			cancel: () => {
+				this.parked.delete(key);
+			},
+			leave: (unusedWake) => {
+				this.parked.delete(key);
+				this.refusedDevices.delete(deviceId);
+				if (unusedWake) this.wakeNext();
+			}
+		};
+	}
+	/**
+	* ONE slot, ONE wake: the longest-parked start (lowest `seq`). Waking all N
+	* produced N−1 refusals per freed slot. The woken start leaves the queue; if
+	* something else took the slot first it parks again, at the same place.
+	*/
+	wakeNext() {
+		let first;
+		for (const key of this.parked.keys()) if (first === void 0 || key.seq < first.seq) first = key;
+		if (first === void 0) return;
+		const wake = this.parked.get(first);
+		this.parked.delete(first);
+		wake?.();
+	}
 	/** Workers currently holding a slot. */
 	get inFlight() {
 		return this.live;
@@ -485,7 +596,9 @@ var LiveDecodeWorkerAdmission = class {
 	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", {
+			const firstRefusal = !this.refusedDevices.has(deviceId);
+			this.refusedDevices.add(deviceId);
+			(firstRefusal ? this.logger.warn : this.logger.debug).call(this.logger, "session-decode: REFUSED — node live decode-worker ceiling reached, will retry", {
 				tags: { deviceId },
 				meta: {
 					label,
@@ -501,6 +614,7 @@ var LiveDecodeWorkerAdmission = class {
 			return null;
 		}
 		this.live += 1;
+		this.refusedDevices.delete(deviceId);
 		this.logger.debug("session-decode: live decode-worker slot taken", {
 			tags: { deviceId },
 			meta: {
@@ -514,6 +628,7 @@ var LiveDecodeWorkerAdmission = class {
 			if (released) return;
 			released = true;
 			this.live -= 1;
+			this.wakeNext();
 		} };
 	}
 };
@@ -523,6 +638,28 @@ function positiveOrUndefined(value) {
 	return Number.isFinite(value) && value > 0 ? value : void 0;
 }
 //#endregion
+//#region src/pipeline-runner/retained-reader-hold.ts
+/**
+* Run `read` with `handle`'s parked frame held as a CONSUMER for its whole
+* duration (D656).
+*
+* `getNativeCrop` has two rungs: a native crop, then — on a miss — the retained
+* full-frame fallback. Between them nothing is in flight: the crop's reply
+* settles the worker's last pending request in the same turn, and the fallback's
+* `toBuffer` is only sent on a later microtask. A parked frame does not keep a
+* draining worker alive, so without this hold the drain killed the worker in
+* that gap and the fallback was lost. One rule instead of a timing trick: a
+* read in progress is a consumer.
+*/
+async function withRetainedReader(store, handle, read) {
+	const release = store?.holdReader(handle) ?? null;
+	try {
+		return await read();
+	} finally {
+		release?.();
+	}
+}
+//#endregion
 //#region src/session-decode/native-crop-lease-age.ts
 /**
 * THE age bound on a native crop lease (ADR-0419).
@@ -865,6 +1002,8 @@ function createRetainedContentFallback(registry, ref) {
 				timestamp: ref.timestamp,
 				...ref.capturedAt !== void 0 ? { capturedAt: ref.capturedAt } : {}
 			};
+		} catch {
+			return null;
 		} finally {
 			lease.release(reason);
 		}
@@ -1307,6 +1446,14 @@ var RetainedFrameStore = class RetainedFrameStore {
 			if (current) current.hydrating = void 0;
 		}
 	}
+	/**
+	* Hold `handle`'s parked frame as a reader until the returned release runs
+	* (D656). `null` when the handle has no un-hydrated fallback — bytes already
+	* in RAM need no worker.
+	*/
+	holdReader(handle) {
+		return this.entries.get(keyOf(handle))?.fallback?.holdReader?.() ?? null;
+	}
 	/** Drop every retained frame (node/addon shutdown). */
 	clear() {
 		for (const entry of this.entries.values()) entry.fallback?.release?.();
@@ -1450,6 +1597,48 @@ function cropRgb(frame, bbox, maxWidth) {
 /** How long to wait after `kill()` before escalating to `kill('SIGKILL')`. */
 var SIGKILL_FALLBACK_MS = 1e3;
 /**
+* The longest a planned teardown keeps a session's worker alive so the frames
+* it already handed out can be read (D652).
+*
+* What is being waited for is the REST of a frame's trip through the runner —
+* semaphore wait + inference + result — for frames that were admitted before
+* the detach. Measured on the live hub 2026-09-26 over one hour of
+* `pipeline stats` (2 254 per-camera 10 s windows): the WORST enqueue→emit in a
+* window was ≤1 000 ms in 96.7% of windows and ≤1 500 ms in 98.0%; going to
+* 5 000 ms buys only another 0.9%, and that tail is the inference-pool GPU hang,
+* which no wait here can rescue. The cost of waiting is one idle worker (its
+* decode already stopped by `drain`) for at most this long, per detach.
+*
+* A frame still held when this expires is not dropped silently: the
+* coordinator logs the count, tagged with the camera, and then kills.
+*/
+var SESSION_DECODE_DRAIN_BOUND_MS = 1500;
+/**
+* The miss reason for a native crop requested after its session's teardown.
+* Only crops already SENT when the drain began are waited for (D652); a later
+* one would ask a worker that is about to be killed.
+*/
+var NATIVE_CROP_REFUSED_DRAINING = "session draining — crop requested after teardown";
+/**
+* The refusal for a `toBuffer` asked for once the worker has been told to exit
+* (D656). A read during a DRAIN is served — that is what the drain is for — but
+* after the kill no reply can come, and a raw rejection read as a worker fault.
+*/
+var TO_BUFFER_REFUSED_KILLED = "session killed — read requested after the worker was told to exit";
+/** The refusal for a `toBuffer` the worker is no longer there to answer. */
+var TO_BUFFER_REFUSED_EXITED = "worker already exited";
+/** A read the session declined to send, by name — never a worker fault. */
+var SessionDecodeReadRefusedError = class extends Error {
+	reason;
+	frameId;
+	constructor(reason, frameId) {
+		super(`session-decode-coordinator: ${reason} (frameId=${frameId})`);
+		this.reason = reason;
+		this.frameId = frameId;
+		this.name = "SessionDecodeReadRefusedError";
+	}
+};
+/**
 * How often the cold-start wait REPORTS that it is still waiting. Task 0
 * live-measured cold-start (restream dial + hwaccel context + keyframe wait) at
 * 5-8s, so this must tolerate a slow-but-healthy start.
@@ -1521,30 +1710,45 @@ var SessionDecodeSession = class {
 	firstFrameTimeoutMs;
 	frameTimeoutMs;
 	firstFrameMaxWaitMs;
-	onDialTiming;
-	onPreRollReport;
+	hooks;
 	pendingPull = null;
 	pendingToBuffers = /* @__PURE__ */ new Map();
 	/** Outstanding `nativeCrop` requests, keyed by the monotonic `requestId`. */
 	pendingNativeCrops = /* @__PURE__ */ new Map();
 	nextNativeCropId = 1;
 	exited = false;
-	/** Set by teardown() so handleExit can tell an intentional stop from a death. */
+	/** Set by teardown() — the session is ending, whether or not it drains first. */
 	stopRequested = false;
+	/** Set when `kill()` is sent, so handleExit can tell an intentional stop from a death. */
+	killSent = false;
+	/**
+	* Images yielded and not yet closed that a CONSUMER still holds — queued,
+	* in flight, or being read. Each dies with the worker and somebody was going
+	* to read it first. This is what a drain waits on.
+	*/
+	consumerImages = 0;
+	/**
+	* Images yielded and not yet closed that only a RETENTION holder keeps —
+	* parked for a read that may come later (the on-demand JPEG fallback, D656).
+	* They die with the worker too, but nobody reads them inside any bound worth
+	* holding a worker for, so a drain does NOT wait on them.
+	*/
+	retainedImages = 0;
+	/** Armed while a drain waits; its expiry kills with frames still held. */
+	drainTimer = null;
 	sigkillTimer = null;
 	pullTimeoutTimer = null;
 	firstFrameReceived = false;
 	/** `Date.now()` of the FIRST `pull` — the origin of the cold-start ceiling. */
 	firstPullAt = 0;
-	constructor(child, logger, deviceId, firstFrameTimeoutMs, frameTimeoutMs, firstFrameMaxWaitMs, onDialTiming, onPreRollReport) {
+	constructor(child, logger, deviceId, firstFrameTimeoutMs, frameTimeoutMs, firstFrameMaxWaitMs, hooks) {
 		this.child = child;
 		this.logger = logger;
 		this.deviceId = deviceId;
 		this.firstFrameTimeoutMs = firstFrameTimeoutMs;
 		this.frameTimeoutMs = frameTimeoutMs;
 		this.firstFrameMaxWaitMs = firstFrameMaxWaitMs;
-		this.onDialTiming = onDialTiming;
-		this.onPreRollReport = onPreRollReport;
+		this.hooks = hooks;
 		this.child.on("message", (m) => this.handleMessage(m));
 		this.child.on("exit", (m) => this.handleExit(toWorkerExitInfo(m)));
 	}
@@ -1583,7 +1787,8 @@ var SessionDecodeSession = class {
 	}
 	/** Send `toBuffer` for `frameId` and resolve with the matching `buffer` reply's bytes. */
 	requestBuffer(frameId, opts) {
-		if (this.exited) return Promise.reject(/* @__PURE__ */ new Error(`session-decode-coordinator: worker already exited (frameId=${frameId})`));
+		if (this.exited) return Promise.reject(new SessionDecodeReadRefusedError(TO_BUFFER_REFUSED_EXITED, frameId));
+		if (this.killSent) return Promise.reject(new SessionDecodeReadRefusedError(TO_BUFFER_REFUSED_KILLED, frameId));
 		return new Promise((resolve, reject) => {
 			const waiter = {
 				resolve,
@@ -1609,6 +1814,10 @@ var SessionDecodeSession = class {
 	*/
 	requestNativeCrop(frameId, bbox, maxWidth) {
 		if (this.exited) return Promise.resolve({ kind: "miss" });
+		if (this.stopRequested) return Promise.resolve({
+			kind: "miss",
+			workerReason: NATIVE_CROP_REFUSED_DRAINING
+		});
 		const requestId = this.nextNativeCropId++;
 		return new Promise((resolve) => {
 			this.pendingNativeCrops.set(requestId, { resolve });
@@ -1623,6 +1832,7 @@ var SessionDecodeSession = class {
 			} catch {
 				this.pendingNativeCrops.delete(requestId);
 				resolve({ kind: "miss" });
+				this.settleDrainIfDone();
 			}
 		});
 	}
@@ -1667,20 +1877,169 @@ var SessionDecodeSession = class {
 			frameId
 		});
 	}
-	/** Teardown: `stop`, `kill()`, arm the SIGKILL fallback unless already exited. */
-	teardown() {
+	/** A yielded image the consumer now holds — see {@link consumerImages}. */
+	noteImageOpened() {
+		this.consumerImages += 1;
+	}
+	/**
+	* An open image moved between a consumer and a retention-only holder
+	* (D656). Losing its last consumer may complete a waiting drain.
+	*/
+	noteImageHolder(pendingConsumer) {
+		if (pendingConsumer) {
+			this.retainedImages = Math.max(0, this.retainedImages - 1);
+			this.consumerImages += 1;
+			return;
+		}
+		this.consumerImages = Math.max(0, this.consumerImages - 1);
+		this.retainedImages += 1;
+		this.settleDrainIfDone();
+	}
+	/** A yielded image was closed; a waiting drain may now be done. */
+	noteImageClosed(pendingConsumer) {
+		if (pendingConsumer) this.consumerImages = Math.max(0, this.consumerImages - 1);
+		else this.retainedImages = Math.max(0, this.retainedImages - 1);
+		this.settleDrainIfDone();
+	}
+	/**
+	* End the session.
+	*
+	* `'drain'` with frames still held: tell the worker to stop decoding (it
+	* keeps every frame it holds), and kill only once every yielded image has
+	* been closed and every read answered — or when
+	* {@link SESSION_DECODE_DRAIN_BOUND_MS} expires, which is logged. Nothing
+	* held: `stop` + SIGTERM now. `'immediate'`: SIGKILL now.
+	*
+	* A SECOND call that says `'immediate'` while a drain is in progress
+	* ESCALATES (D652): addon shutdown lands on sessions already draining from
+	* a detach, and the runner exits right after — a drain it does not wait for
+	* is an orphaned worker holding its GPU pool. Any other repeat is ignored.
+	*/
+	teardown(mode) {
+		if (this.stopRequested) {
+			if (mode === "immediate") this.escalateToImmediate();
+			return;
+		}
 		this.stopRequested = true;
 		this.clearPullTimeout();
+		if (this.exited) return;
+		if (mode === "drain" && this.unsettledCount() > 0) {
+			this.trySend({ kind: "drain" });
+			this.drainTimer = setTimeout(() => this.handleDrainBoundExpired(), SESSION_DECODE_DRAIN_BOUND_MS);
+			this.drainTimer.unref?.();
+			return;
+		}
+		this.killNow(mode);
+	}
+	/** The drain (or a SIGTERM still waiting on its fallback) gives way to SIGKILL now. */
+	escalateToImmediate() {
+		if (this.exited) return;
+		if (this.drainTimer !== null) {
+			clearTimeout(this.drainTimer);
+			this.drainTimer = null;
+		}
+		if (!this.killSent) {
+			this.killNow("immediate");
+			return;
+		}
+		if (this.sigkillTimer !== null) {
+			clearTimeout(this.sigkillTimer);
+			this.sigkillTimer = null;
+		}
+		this.tryKill("SIGKILL");
+	}
+	/**
+	* Frames a CONSUMER still holds, reads still waiting on the worker, and
+	* native crops already REQUESTED. A crop asked for before the teardown
+	* request is waited for; one asked for after it is refused by name — post-analysis's
+	* ordinary crop arrives 2.2–9.9 s after the frame, past any bound worth
+	* holding a worker for, and is served from subject tiles that die with the
+	* worker either way.
+	*
+	* A frame only PARKED for such a late read ({@link retainedImages}) is not
+	* counted, for the same reason (D656): counting it made nearly every
+	* teardown wait the full bound for frames nobody was going to read. Its read,
+	* once STARTED, is a pending read like any other and is waited for.
+	*/
+	unsettledCount() {
+		return this.consumerImages + this.pendingReadCount() + this.pendingNativeCrops.size;
+	}
+	/** What the session still holds, per category — every drain line carries it. */
+	heldCounts() {
+		return {
+			consumerFrames: this.consumerImages,
+			retainedFrames: this.retainedImages,
+			pendingReads: this.pendingReadCount(),
+			pendingCrops: this.pendingNativeCrops.size
+		};
+	}
+	pendingReadCount() {
+		let n = 0;
+		for (const waiters of this.pendingToBuffers.values()) n += waiters.length;
+		return n;
+	}
+	settleDrainIfDone() {
+		if (this.drainTimer === null || this.unsettledCount() > 0) return;
+		clearTimeout(this.drainTimer);
+		this.drainTimer = null;
+		this.killNow("drain");
+	}
+	/**
+	* The drain ran out of time with frames still held. Those frames die with
+	* the worker; that is a branch that DROPS work (D391), so it says how many,
+	* on which camera.
+	*/
+	handleDrainBoundExpired() {
+		this.drainTimer = null;
+		if (this.exited) return;
+		this.logger.warn("session-decode-coordinator: drain bound expired — killing the worker with frames still held", {
+			tags: { deviceId: this.deviceId },
+			meta: {
+				...this.heldCounts(),
+				boundMs: SESSION_DECODE_DRAIN_BOUND_MS
+			}
+		});
+		this.killNow("drain");
+	}
+	/**
+	* `stop`, then the kill — unless already exited.
+	*
+	* `'drain'`: SIGTERM, so the child flushes its last lines (`bounded-exit.ts`),
+	* and a SIGKILL fallback. `'immediate'`: SIGKILL outright. Since D652 gave the
+	* child a SIGTERM handler, SIGTERM is no longer instant death: a worker
+	* blocked in a native call (a VAAPI hang) never runs the handler, and the
+	* fallback was an `unref`'d timer the exiting parent did not wait for — so
+	* on shutdown that worker was orphaned with its GPU pool. The fallback timer
+	* is now ref'd: it exists only for a drain while the parent is alive (a
+	* shutdown escalates to SIGKILL and clears it), and a timer that keeps the
+	* process up for at most one second is the price of a kill that lands.
+	*/
+	killNow(mode) {
+		if (this.killSent) return;
+		this.killSent = true;
+		if (this.retainedImages > 0) this.logger.debug("session-decode-coordinator: retained frames die with the worker", {
+			tags: { deviceId: this.deviceId },
+			meta: {
+				mode,
+				...this.heldCounts()
+			}
+		});
 		this.trySend({ kind: "stop" });
+		if (mode === "immediate") {
+			this.tryKill("SIGKILL");
+			return;
+		}
 		this.tryKill(void 0);
 		if (this.exited) return;
 		this.sigkillTimer = setTimeout(() => {
 			this.sigkillTimer = null;
 			if (this.exited) return;
-			this.logger.warn("session-decode-coordinator: child did not exit within SIGKILL fallback window — forcing", { meta: { fallbackMs: SIGKILL_FALLBACK_MS } });
+			this.logger.warn("session-decode-coordinator: child did not exit within SIGKILL fallback window — forcing", {
+				tags: { deviceId: this.deviceId },
+				meta: { fallbackMs: SIGKILL_FALLBACK_MS }
+			});
 			this.tryKill("SIGKILL");
 		}, SIGKILL_FALLBACK_MS);
-		this.sigkillTimer.unref?.();
 	}
 	handleMessage(raw) {
 		if (!require_worker_protocol.isWorkerReply(raw)) {
@@ -1729,7 +2088,7 @@ var SessionDecodeSession = class {
 				this.logger[raw.level](raw.message);
 				return;
 			case "dialTiming":
-				this.onDialTiming?.({
+				this.hooks.onDialTiming?.({
 					hwContextMs: raw.hwContextMs,
 					demuxerOpenMs: raw.demuxerOpenMs,
 					decoderCreateMs: raw.decoderCreateMs,
@@ -1737,25 +2096,43 @@ var SessionDecodeSession = class {
 					streamInfoProbed: raw.streamInfoProbed
 				});
 				return;
+			case "preRollSettled":
+				this.hooks.onPreRollSettled?.({
+					read: raw.read,
+					released: raw.released,
+					lostByReason: raw.lostByReason,
+					unsettled: raw.unsettled
+				});
+				return;
 			case "preRollReport":
-				this.onPreRollReport?.({
+				this.hooks.onPreRollReport?.({
 					offered: raw.offered,
 					inferred: raw.inferred,
 					dropped: raw.dropped,
 					droppedByReason: raw.droppedByReason,
 					strideMs: raw.strideMs,
 					subsampled: raw.subsampled,
-					spanMs: raw.spanMs
+					spanMs: raw.spanMs,
+					budgetFrames: raw.budgetFrames
 				});
 				return;
 		}
 	}
 	handleExit(info) {
-		if (!this.stopRequested && !this.exited) this.logger.warn("session-decode worker exited unexpectedly", { meta: {
-			code: info?.code ?? null,
-			signal: info?.signal ?? null
-		} });
+		if (!this.exited) this.hooks.onWorkerExit?.();
+		if (!this.killSent && !this.exited) this.logger.warn(this.stopRequested ? "session-decode worker exited unexpectedly while draining" : "session-decode worker exited unexpectedly", {
+			tags: { deviceId: this.deviceId },
+			meta: {
+				code: info?.code ?? null,
+				signal: info?.signal ?? null,
+				...this.stopRequested ? this.heldCounts() : {}
+			}
+		});
 		this.exited = true;
+		if (this.drainTimer) {
+			clearTimeout(this.drainTimer);
+			this.drainTimer = null;
+		}
 		if (this.sigkillTimer) {
 			clearTimeout(this.sigkillTimer);
 			this.sigkillTimer = null;
@@ -1777,6 +2154,7 @@ var SessionDecodeSession = class {
 		if (!waiter) return;
 		this.pendingNativeCrops.delete(requestId);
 		waiter.resolve(attempt);
+		this.settleDrainIfDone();
 	}
 	settlePendingPull(outcome) {
 		const waiter = this.pendingPull;
@@ -1872,6 +2250,7 @@ var SessionDecodeSession = class {
 		const waiter = queue.shift();
 		if (queue.length === 0) this.pendingToBuffers.delete(frameId);
 		waiter?.resolve(bytes);
+		this.settleDrainIfDone();
 	}
 	/**
 	* `error` replies MAY carry a `frameId` (a `toBuffer`-scoped miss, e.g. a
@@ -1891,6 +2270,7 @@ var SessionDecodeSession = class {
 			if (queue && queue.length > 0) {
 				for (const waiter of queue) waiter.reject(err);
 				this.pendingToBuffers.delete(frameId);
+				this.settleDrainIfDone();
 				return;
 			}
 			this.logger.debug("session-decode-coordinator: dropping toBuffer error for unknown frameId", { meta: { frameId } });
@@ -1905,6 +2285,7 @@ var SessionDecodeSession = class {
 		}
 		for (const waiters of this.pendingToBuffers.values()) for (const waiter of waiters) waiter.reject(err);
 		this.pendingToBuffers.clear();
+		this.settleDrainIfDone();
 	}
 	queueToBufferWaiter(frameId, waiter) {
 		const queue = this.pendingToBuffers.get(frameId);
@@ -1942,6 +2323,8 @@ var SessionDecodeSession = class {
 /** Build the {@link FrameImage} adapter for one `frame` reply. */
 function buildFrameImage(session, reply) {
 	let closed = false;
+	let pendingConsumer = true;
+	session.noteImageOpened();
 	return {
 		width: reply.width,
 		height: reply.height,
@@ -1955,8 +2338,15 @@ function buildFrameImage(session, reply) {
 		cutTiles: (bboxes) => session.cutTiles(reply.frameId, bboxes),
 		releaseNativeLease: () => session.releaseLease(reply.frameId),
 		markInferred: () => session.markInferred(reply.frameId),
+		setPendingConsumer: (pending) => {
+			if (closed || pending === pendingConsumer) return;
+			pendingConsumer = pending;
+			session.noteImageHolder(pending);
+		},
 		close: () => {
+			if (closed) return;
 			closed = true;
+			session.noteImageClosed(pendingConsumer);
 		}
 	};
 }
@@ -1965,15 +2355,23 @@ function buildFrameImage(session, reply) {
 * `generateVideoFrames()` call, drives it with `pull`/`toBuffer` requests
 * one at a time (no pre-fetch — back-pressure is the async generator's
 * natural suspend-on-yield), and guarantees the child is torn down
-* (`stop` + `kill()` + SIGKILL fallback) in every exit path via `finally`.
+* (bounded drain, then `stop` + `kill()` + SIGKILL fallback) in every exit
+* path via `finally`.
 */
 function createSessionDecodeCoordinator(deps) {
 	const firstFrameTimeoutMs = deps.firstFrameTimeoutMs ?? DEFAULT_FIRST_FRAME_TIMEOUT_MS;
 	const frameTimeoutMs = deps.frameTimeoutMs ?? DEFAULT_FRAME_TIMEOUT_MS;
 	const firstFrameMaxWaitMs = Math.max(deps.firstFrameMaxWaitMs ?? DEFAULT_FIRST_FRAME_MAX_WAIT_MS, firstFrameTimeoutMs);
 	return { async *generateVideoFrames(source, opts) {
-		const session = new SessionDecodeSession(deps.fork(source), deps.logger, source.deviceId, firstFrameTimeoutMs, frameTimeoutMs, firstFrameMaxWaitMs, deps.onDialTiming, deps.onPreRollReport);
+		const session = new SessionDecodeSession(deps.fork(source), deps.logger, source.deviceId, firstFrameTimeoutMs, frameTimeoutMs, firstFrameMaxWaitMs, {
+			...deps.onDialTiming ? { onDialTiming: deps.onDialTiming } : {},
+			...deps.onPreRollReport ? { onPreRollReport: deps.onPreRollReport } : {},
+			...deps.onPreRollSettled ? { onPreRollSettled: deps.onPreRollSettled } : {},
+			...deps.onWorkerExit ? { onWorkerExit: deps.onWorkerExit } : {}
+		});
 		session.start(source, opts, deps.lease());
+		deps.onSessionTeardown?.((mode) => session.teardown(mode));
+		let failed = false;
 		try {
 			while (true) {
 				const outcome = await session.pullNext();
@@ -1986,8 +2384,11 @@ function createSessionDecodeCoordinator(deps) {
 					...reply.preRoll === true ? { preRoll: true } : {}
 				};
 			}
+		} catch (err) {
+			failed = true;
+			throw err;
 		} finally {
-			session.teardown();
+			session.teardown(failed ? "immediate" : deps.teardownMode?.() ?? "drain");
 		}
 	} };
 }
@@ -2031,17 +2432,39 @@ async function toDecodedFrame(frame, format, viewSpec) {
 * Start pulling frames from a per-session decode worker and feed each decoded
 * frame to `onDecodedFrame`. Returns an idempotent teardown closure that stops
 * the async generator (`it.return()`) — which triggers the coordinator's
-* `finally` → `stop` + `kill()` + 1s SIGKILL fallback → worker exit → the OS
-* reclaims the VAAPI/GPU decode pool. Fire-and-forget: the returned closure is
-* synchronous; the frame loop and generator teardown run on their own tasks.
+* `finally` → a bounded DRAIN of the frames already handed out (D652), then
+* `stop` + SIGTERM + 1s SIGKILL fallback → worker exit → the OS reclaims the
+* VAAPI/GPU decode pool. `teardown('immediate')` SIGKILLs at once (shutdown),
+* and said a second time during a drain it escalates that drain to the kill.
+* Fire-and-forget: the returned closure is synchronous; the frame loop and
+* generator teardown run on their own tasks.
 */
 function startSessionDecodePump(deps) {
 	const format = deps.opts.format ?? "rgb";
 	let dialTiming = null;
+	let teardownMode = "drain";
+	let escalateSession = null;
+	let forked = false;
+	let workerGone = false;
+	const noteWorkerGone = () => {
+		if (workerGone) return;
+		workerGone = true;
+		deps.onWorkerGone?.();
+	};
 	const iterator = createSessionDecodeCoordinator({
-		fork: deps.fork,
+		fork: (source) => {
+			const child = deps.fork(source);
+			forked = true;
+			return child;
+		},
 		lease: deps.lease,
 		logger: deps.logger,
+		teardownMode: () => teardownMode,
+		onSessionTeardown: (teardown) => {
+			escalateSession = teardown;
+		},
+		onWorkerExit: noteWorkerGone,
+		...deps.onPreRollSettled ? { onPreRollSettled: deps.onPreRollSettled } : {},
 		onDialTiming: (timing) => {
 			dialTiming = timing;
 		},
@@ -2147,13 +2570,21 @@ function startSessionDecodePump(deps) {
 			});
 		} finally {
 			releaseSpawnSlotOnce();
+			if (!forked) noteWorkerGone();
 			if (!stopped) deps.onEnded?.();
 		}
 	};
 	pump();
-	return () => {
-		if (stopped) return;
+	return (mode = "drain") => {
+		if (stopped) {
+			if (mode === "immediate" && teardownMode !== "immediate") {
+				teardownMode = "immediate";
+				escalateSession?.("immediate");
+			}
+			return;
+		}
 		stopped = true;
+		teardownMode = mode;
 		releaseSpawnSlotOnce();
 		iterator.return().catch(() => {});
 	};
@@ -3584,115 +4015,14 @@ async function runDetailSubtree(deps, input) {
 	} : void 0;
 	const details = [];
 	for (const step of steps) {
-		const deviceKey = deps.resolveStepDevice?.(input.deviceId, step);
-		const result = await deps.runPipeline([step], crop.jpeg, input.deviceId, deviceKey, nativeCropRef);
+		const placement = deps.placeStep?.(input.deviceId, step);
+		const result = await deps.runPipeline([placement?.step ?? step], crop.jpeg, input.deviceId, placement?.deviceKey, nativeCropRef);
 		if (!result) continue;
 		for (const detection of result.detections) details.push(toDetailResult(detection, step.addonId, crop));
 	}
 	return { details };
 }
 //#endregion
-//#region src/pipeline-runner/device-jump.ts
-/**
-* Step-tree device jump (same-node, phase 1) — the PURE resolution core.
-*
-* Given the camera's elected ("effective") inference device and the node's
-* enabled-device roster, decide which device ONE enrichment step should run on:
-*
-*   1. A manual `jumpDeviceKey` override wins when it names a candidate that can
-*      run the step (bypasses the auto choice; operator intent).
-*   2. Otherwise, if the effective device's format can run the step's model →
-*      NO jump (the step inherits the effective device — the common case).
-*   3. Otherwise AUTO-jump: among the node's OTHER enabled devices whose format
-*      can run the step (and that are under their `maxSessions` cap), pick the
-*      weighted-least-loaded one — mirroring the balancer's per-device core.
-*   4. If nothing on the node can run it → `no-candidate` (the caller emits the
-*      loud once-per-(camera,step) warn that replaces today's silent degrade).
-*
-* Framework-free + side-effect-free so the whole decision table is unit-testable
-* without a live runner/catalog. The `canRun(format)` predicate is injected by
-* the runner (which owns the model catalog); this module never imports it.
-*/
-/** The `ModelFormat` of a `<backend>:<device>` key, or `undefined` for an unknown backend. */
-function formatOf(deviceKey) {
-	const colon = deviceKey.indexOf(":");
-	return require_dist.DEVICE_BACKEND_TO_FORMAT[colon >= 0 ? deviceKey.slice(0, colon) : deviceKey];
-}
-/** True when the step's model has a build for `deviceKey`'s format. */
-function canRunOn(deviceKey, canRun) {
-	const format = formatOf(deviceKey);
-	return format !== void 0 && canRun(format);
-}
-/** Effective weighted load of a device (session count ÷ weight); lower = preferred. */
-function weightedLoad(d) {
-	return d.attachedCameras / (d.weight > 0 ? d.weight : 1);
-}
-/**
-* Weighted-least-loaded pick with a deterministic `deviceKey` tie-break —
-* mirrors the node/device balancer's decision core (least `load/weight`, ties
-* broken stably). `devices` is assumed non-empty.
-*/
-function pickWeightedLeastLoaded(devices) {
-	return devices.reduce((best, d) => {
-		const dScore = weightedLoad(d);
-		const bScore = weightedLoad(best);
-		if (dScore < bScore) return d;
-		if (dScore > bScore) return best;
-		return d.deviceKey < best.deviceKey ? d : best;
-	});
-}
-/**
-* Build the `canRun` predicate for ONE enrichment dispatch. The step and its
-* enabled descendants ride the SAME `runPipeline` call — one pool, one format
-* (detail-subtree contract: "its inherited children ride the same call → same
-* device") — so a format can run the dispatch only when EVERY catalog-known
-* step in the subtree ships a build for it. Gating only the subtree TOP let a
-* `face-detection` with a tflite build stay on the Coral while its
-* `face-embedding` child (no tflite build anywhere) doomed the call.
-* Unknown/custom addonIds (`getStepDef` → null) have no catalog to gate on
-* and never block. `getStepDef` is injected — this module stays catalog-free.
-*/
-function buildSubtreeCanRun(step, getStepDef) {
-	const defs = [];
-	const walk = (s) => {
-		if (s.enabled === false) return;
-		const def = getStepDef(s.addonId);
-		if (def !== null) defs.push(def);
-		for (const child of s.children ?? []) walk(child);
-	};
-	walk(step);
-	return (format) => defs.every((def) => def.models.some((m) => m.formats[format]));
-}
-/**
-* Resolve the device one enrichment step runs on. See the module header for the
-* decision table. Pure — never throws, no I/O.
-*/
-function resolveStepDevice(input) {
-	const { effectiveDeviceKey, manualJumpDeviceKey, canRun } = input;
-	if (manualJumpDeviceKey !== void 0 && manualJumpDeviceKey !== effectiveDeviceKey) {
-		const target = input.devices.find((d) => d.deviceKey === manualJumpDeviceKey);
-		if (target && canRunOn(target.deviceKey, canRun)) return {
-			kind: "jumped",
-			deviceKey: target.deviceKey,
-			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) {
@@ -3875,6 +4205,74 @@ function release(cutter) {
 	} catch {}
 }
 //#endregion
+//#region src/pipeline-runner/occupancy-burst-ledger.ts
+var OccupancyBurstLedger = class {
+	options;
+	frames = 0;
+	inferred = 0;
+	superseded = 0;
+	settled = 0;
+	closed = false;
+	completed = false;
+	boundTimer = null;
+	constructor(options) {
+		this.options = options;
+	}
+	/**
+	* Count one collected frame and hand back its settler. A frame the runner
+	* REFUSED is settled `'lost'` by the caller at once — it is a frame the
+	* verdict did not see, which is what `lost` counts.
+	*/
+	admit() {
+		this.frames += 1;
+		let done = false;
+		return (outcome) => {
+			if (done || this.completed) return;
+			done = true;
+			this.settled += 1;
+			if (outcome === "inferred") this.inferred += 1;
+			else if (outcome === "superseded") this.superseded += 1;
+			this.completeIfSettled();
+		};
+	}
+	/**
+	* No more frames will be collected (count reached, safety timeout, or the
+	* decode ended). Completes now when everything admitted has settled, else
+	* arms the bound. Idempotent.
+	*/
+	close() {
+		if (this.closed || this.completed) return;
+		this.closed = true;
+		if (this.completeIfSettled()) return;
+		this.boundTimer = setTimeout(() => {
+			this.boundTimer = null;
+			this.complete(true);
+		}, this.options.settleBoundMs);
+		this.boundTimer.unref?.();
+	}
+	completeIfSettled() {
+		if (!this.closed || this.settled < this.frames) return false;
+		this.complete(false);
+		return true;
+	}
+	complete(timedOut) {
+		if (this.completed) return;
+		this.completed = true;
+		if (this.boundTimer !== null) {
+			clearTimeout(this.boundTimer);
+			this.boundTimer = null;
+		}
+		this.options.onComplete({
+			frames: this.frames,
+			inferred: this.inferred,
+			superseded: this.superseded,
+			lost: this.frames - this.inferred - this.superseded,
+			unsettled: this.frames - this.settled,
+			timedOut
+		});
+	}
+};
+//#endregion
 //#region src/pipeline-runner/frame-lazy-metrics.ts
 function emptyFrameLazyCounters() {
 	return {
@@ -4908,7 +5306,7 @@ var ON_DEMAND_JPEG_VIEW = {
 	format: "jpeg"
 };
 function createOnDemandJpegFallback(registry, ref) {
-	const lease = registry.acquire(ref);
+	const lease = registry.acquire(ref, "retention");
 	let cached;
 	let released = false;
 	const releaseLease = (reason) => {
@@ -4948,6 +5346,11 @@ function createOnDemandJpegFallback(registry, ref) {
 		},
 		release() {
 			releaseLease("eviction");
+		},
+		holdReader() {
+			if (released || cached !== void 0) return null;
+			const reader = registry.acquire(ref);
+			return reader ? () => reader.release("success") : null;
 		}
 	};
 }
@@ -5287,41 +5690,6 @@ var FrameGovernor = class {
 };
 //#endregion
 //#region src/pipeline-runner/frame-queue.ts
-/**
-* Latest-frame-only buffer. Keeps only the most recent item, dropping all
-* older items immediately. This ensures inference always runs on the
-* freshest available frame, never accumulating a backlog regardless of
-* inference latency.
-*
-* ## Buffer ownership (Phase 5 / D9 Task 7b)
-*
-* Frames arrive from the shm frame plane via a `FrameRingReader`, whose
-* `FrameRead.pixels` is **borrowed** — a view onto the reader's reusable
-* scratch buffer, valid only until that reader's next read (see
-* `@camstack/shm-ring`'s `FrameRead` contract). Both queue consumers retain
-* the frame PAST the next read:
-*
-*   - the **motion** queue is drained by the scheduler's `tick`, not by the
-*     poller that read the frame — and the poller drains a burst of handles
-*     per poll, so even handle #2's read would clobber handle #1's pixels;
-*   - the **detection** queue is drained asynchronously after a semaphore wait
-*     and a 10s–100s ms inference.
-*
-* In both cases holding the borrowed buffer is silent corruption. So
-* `enqueue` runs the queue's injected `clone` function which copies the
-* pixels into queue-owned storage at the retention boundary. The queue is
-* latest-only (capacity 1), so this is exactly one allocation per *queued*
-* frame — bounded by the scheduler/inference cadence, NOT per *read* frame.
-* The high-frequency per-read allocation that failed the D9 perf gate is
-* eliminated; this bounded copy-on-retain is the correct cost.
-*
-* The generic parameter `T` lets the detection path queue a
-* `{ frame, handle }` entry (Task 7 — propagating the `FrameHandle`
-* through to the inference-result event), while the motion path keeps
-* queueing bare `DecodedFrame`s. Each instance provides its own
-* `clone` so the inner pixel buffer is detached at the same retention
-* boundary regardless of the wrapping entry shape.
-*/
 var FrameQueue = class {
 	maxSize;
 	latest = null;
@@ -5342,7 +5710,7 @@ var FrameQueue = class {
 	enqueue(item) {
 		if (this.latest !== null) {
 			this._droppedFrames++;
-			this.dispose?.(this.latest);
+			this.dispose?.(this.latest, "superseded");
 		}
 		this.latest = this.clone(item);
 	}
@@ -5357,8 +5725,12 @@ var FrameQueue = class {
 	get droppedFrames() {
 		return this._droppedFrames;
 	}
+	/** The queued item, without taking it. */
+	peek() {
+		return this.latest ?? void 0;
+	}
 	clear() {
-		if (this.latest !== null) this.dispose?.(this.latest);
+		if (this.latest !== null) this.dispose?.(this.latest, "cleared");
 		this.latest = null;
 	}
 };
@@ -5758,7 +6130,8 @@ function ownDetectionEntry(entry) {
 	return {
 		frame: ownFrame(entry.frame),
 		handle: entry.handle,
-		occasion: entry.occasion
+		occasion: entry.occasion,
+		...entry.onSettled ? { onSettled: entry.onSettled } : {}
 	};
 }
 /**
@@ -5900,9 +6273,10 @@ var PipelineRunner = class {
 	}
 	registerCamera(deviceId, registration) {
 		const motionQueue = new FrameQueue(this.config.maxQueueDepth, ownMotionEntry);
-		const detectionQueue = new FrameQueue(this.config.maxQueueDepth, ownDetectionEntry, (entry) => {
+		const detectionQueue = new FrameQueue(this.config.maxQueueDepth, ownDetectionEntry, (entry, reason) => {
 			if (entry.handle) this.config.releaseRetention?.(entry.handle, "drop");
 			if (entry.frame.frameRef) this.config.releaseFrameRef?.(entry.frame.frameRef, "drop");
+			entry.onSettled?.(reason === "superseded" ? "superseded" : "lost");
 		});
 		const initialPhase = registration.detectionMode === "disabled" ? "idle" : registration.detectionMode === "always-on" ? "active" : "watching";
 		const preRollQueue = new PreRollLane({
@@ -5911,6 +6285,7 @@ var PipelineRunner = class {
 			dispose: (entry) => {
 				if (entry.handle) this.config.releaseRetention?.(entry.handle, "drop");
 				if (entry.frame.frameRef) this.config.releaseFrameRef?.(entry.frame.frameRef, "drop");
+				entry.onSettled?.("lost");
 			}
 		});
 		this.logger?.info("camera registered: root detectors", {
@@ -5971,8 +6346,7 @@ var PipelineRunner = class {
 		}
 		if (state.phase === "active") this.detectionStreamHandler?.(deviceId, "unsubscribe");
 		state.motionQueue.clear();
-		state.detectionQueue.clear();
-		state.preRollQueue.clear();
+		this.discardQueuedDetectionFrames(deviceId, state, "detach");
 		this.timingSampler.clearDroppedFramesSource(deviceId);
 		this.cameras.delete(deviceId);
 		this.lastAdmittedAt.delete(deviceId);
@@ -6096,9 +6470,14 @@ var PipelineRunner = class {
 	preRollQueueDepth(deviceId) {
 		return this.cameras.get(deviceId)?.preRollQueue.size ?? 0;
 	}
-	/** Frames this camera lane REFUSED because it was full. */
+	/**
+	* Frames this camera lane REFUSED because it was full — or `null` when the
+	* camera is no longer registered and the count cannot be read (a report
+	* that lands after a detach). A failed read is `null`, never `0` (D393):
+	* zero would say "nothing refused" about a lane nobody looked at.
+	*/
 	preRollRefusedCount(deviceId) {
-		return this.cameras.get(deviceId)?.preRollQueue.refused ?? 0;
+		return this.cameras.get(deviceId)?.preRollQueue.refused ?? null;
 	}
 	/**
 	* Whether the node has a permit to spare for history right now — i.e. one
@@ -6127,7 +6506,7 @@ var PipelineRunner = class {
 	* decode worker). `runInference` already falls back to the pixel path
 	* when the handle is absent.
 	*/
-	enqueueOccupancyFrame(deviceId, frame, handle) {
+	enqueueOccupancyFrame(deviceId, frame, handle, onSettled) {
 		const state = this.cameras.get(deviceId);
 		if (!state) return false;
 		if (state.phase !== "watching") return false;
@@ -6135,7 +6514,8 @@ var PipelineRunner = class {
 		state.detectionQueue.enqueue({
 			frame,
 			handle,
-			occasion: "burst"
+			occasion: "burst",
+			...onSettled ? { onSettled } : {}
 		});
 		return true;
 	}
@@ -6343,7 +6723,7 @@ var PipelineRunner = class {
 	}
 	transitionToWatching(deviceId, state, cooldownMs) {
 		state.phase = "watching";
-		state.detectionQueue.clear();
+		this.discardQueuedDetectionFrames(deviceId, state, "session-close");
 		state.occupancyArmed = state.lastResultDetections > 0;
 		state.emptyBurstStreak = 0;
 		this.logger?.info("motion gate closed — phase=watching", {
@@ -6364,6 +6744,41 @@ var PipelineRunner = class {
 		state.lastArmedSource = null;
 		state.lastArmedRegions = void 0;
 	}
+	/**
+	* Throw away the frames still QUEUED for a camera whose session is ending.
+	*
+	* A branch that drops work says so (D391, D652). These are frames the runner
+	* admitted and will now never infer — the live queue's latest frame and, on a
+	* detach, whatever history is left in the pre-roll lane. Frames already in
+	* flight are not touched here: they finish, and the decode worker they live
+	* in drains before it is killed (`SESSION_DECODE_DRAIN_BOUND_MS`).
+	*/
+	discardQueuedDetectionFrames(deviceId, state, reason) {
+		const queued = state.detectionQueue.size;
+		const awaited = state.detectionQueue.peek()?.onSettled !== void 0 ? 1 : 0;
+		const preRoll = reason === "detach" ? state.preRollQueue.size : 0;
+		state.detectionQueue.clear();
+		if (reason === "detach") state.preRollQueue.clear();
+		if (queued + preRoll === 0) return;
+		const meta = {
+			reason,
+			queued,
+			awaited,
+			preRoll,
+			inflight: state.inflight
+		};
+		if (awaited + preRoll > 0) {
+			this.logger?.info("detection frames discarded with the session", {
+				tags: { deviceId },
+				meta
+			});
+			return;
+		}
+		this.logger?.debug("detection frames discarded with the session", {
+			tags: { deviceId },
+			meta
+		});
+	}
 	tick() {
 		this.drainMotionQueues();
 		if (this.semaphore.available <= 0) {
@@ -6451,6 +6866,7 @@ var PipelineRunner = class {
 			} catch {}
 			if (handle) this.config.releaseRetention?.(handle, frameReleaseReason);
 			if (frame.frameRef) this.config.releaseFrameRef?.(frame.frameRef, frameReleaseReason);
+			entry.onSettled?.(frameReleaseReason === "success" ? "inferred" : "lost");
 		}
 	}
 	/**
@@ -6532,6 +6948,7 @@ var PipelineRunner = class {
 			} catch {}
 			if (handle) this.config.releaseRetention?.(handle, frameReleaseReason);
 			if (frame.frameRef) this.config.releaseFrameRef?.(frame.frameRef, frameReleaseReason);
+			entry.onSettled?.(frameReleaseReason === "success" ? "inferred" : "lost");
 		}
 	}
 	/**
@@ -6779,11 +7196,14 @@ async function runStatelessStep(deps, input) {
 		return refuse(deps, input, "execution-failed", errorMessage(err));
 	}
 	if (result === null) return refuse(deps, input, "execution-failed", "the executor returned no frame result for the crop");
+	const ranModelId = result.rootModelId;
+	if (ranModelId === void 0 || ranModelId === "") return refuse(deps, input, "execution-failed", `the executor result names no model — refusing rather than assuming "${input.modelId}" ran`);
+	if (ranModelId !== input.modelId) return refuse(deps, input, "model-not-servable", `the executor ran "${ranModelId}" for a call pinned to "${input.modelId}" — its output would not be comparable with the pass`);
 	const details = result.detections.map((detection) => toDetailResult(detection, input.stepId, crop));
 	return {
 		kind: "ran",
 		nodeId: deps.nodeId,
-		modelId: input.modelId,
+		modelId: ranModelId,
 		details
 	};
 }
@@ -7075,6 +7495,19 @@ function writeRetainedDetectionFrame(store, deviceId, frame, retention) {
 */
 var OCCUPANCY_BURST_SAFETY_TIMEOUT_MS = 8e3;
 /**
+* How long a burst whose collection has ended waits for the frames it admitted
+* to be INFERRED before it reports anyway (D652).
+*
+* A burst's verdict is read off its frames' results, so it completes when they
+* settle, not when they are enqueued. This bound is only for a frame that never
+* settles. Measured on the live hub 2026-09-26, the worst enqueue→emit of a
+* 10 s window was ≤1.5 s in 98.0% of 2 254 windows and ≤5 s in 98.9%; what lies
+* beyond is the inference-pool GPU hang, which the runner's own 20 s inference
+* timeout already ends. A timed-out burst counts its unsettled frames as lost
+* and says so on its `burst complete` line.
+*/
+var OCCUPANCY_BURST_SETTLE_BOUND_MS = 5e3;
+/**
 * Freshness window for `lastMotionFrameAt` (Task 10 hardening). A non-null
 * `attachment.motionUnsubscribe` only proves a subscription handle exists —
 * NOT that frames are actually flowing (guarded-session-decode can return
@@ -7179,6 +7612,15 @@ function tryGetStepDefinition(stepId) {
 	}
 }
 /**
+* A detail-plane step: its catalog definition consumes a parent class
+* (`inputClasses` non-null). Unknown/custom addonIds are root-plane — the
+* same reading as the executor's frame-plane skip and `deriveDetailSteps`.
+*/
+function isDetailPlaneStepId(stepId) {
+	const def = tryGetStepDefinition(stepId);
+	return def !== null && def.inputClasses !== null;
+}
+/**
 * Precomputes the `detailSteps` announce (two-plane design) for a camera's
 * configured step tree: every ENABLED step whose catalog definition is a
 * detail/child step (`inputClasses !== null` — a root step like
@@ -7884,8 +8326,8 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends require_dist.BaseAdd
 			this.runner = null;
 		}
 		for (const attachment of this.attached.values()) {
-			attachment.motionUnsubscribe?.();
-			attachment.detectionUnsubscribe?.();
+			attachment.motionUnsubscribe?.("immediate");
+			attachment.detectionUnsubscribe?.("immediate");
 		}
 		for (const deviceId of [...this.parkedDetail.keys()]) this.dropParkedDetail(deviceId);
 		this.attached.clear();
@@ -8011,14 +8453,16 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends require_dist.BaseAdd
 				height: cached.height,
 				format: cached.format
 			}, pin)).frameId;
-			await api.pipelineExecutor.runPipeline.mutate({ ...buildBenchRunPipelineInput({
+			const benchModelId = (await api.pipelineExecutor.runPipeline.mutate({ ...buildBenchRunPipelineInput({
 				steps: stepsToRun,
 				frame: sharedFrame
-			}) }, pin);
+			}) }, pin)).rootModelId;
+			if (benchModelId === void 0 || benchModelId === "") throw new Error(`synthetic bench: the warmup of "${rootStep.addonId}" named no model — refusing to time an unnamed variant`);
 			const warmupCount = input.warmup ?? 1;
 			for (let w = 0; w < warmupCount; w++) await api.pipelineExecutor.inferCached.mutate({
 				stepId: rootStep.addonId,
-				frameId: poolFrameId
+				frameId: poolFrameId,
+				modelId: benchModelId
 			}, pin);
 			const wallTimings = [];
 			const inferTimings = [];
@@ -8036,7 +8480,8 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends require_dist.BaseAdd
 					const t0 = performance.now();
 					const result = await api.pipelineExecutor.inferCached.mutate({
 						stepId: rootStep.addonId,
-						frameId: poolFrameId
+						frameId: poolFrameId,
+						modelId: benchModelId
 					}, pin);
 					const wallMs = performance.now() - t0;
 					const r = result;
@@ -8711,6 +9156,10 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends require_dist.BaseAdd
 	* resolve legitimately want the lower-RES honest frame).
 	*/
 	async getNativeCrop(input) {
+		return withRetainedReader(this.retainedFrames, input.handle, () => this.resolveNativeCropBothRungs(input));
+	}
+	/** {@link getNativeCrop}'s two rungs, run under its reader hold. */
+	async resolveNativeCropBothRungs(input) {
 		const deviceId = this.nativeCropRegistry.deviceIdFor(input.handle) ?? 0;
 		const isFullFrame = input.bbox.x <= .001 && input.bbox.y <= .001 && input.bbox.w >= .999 && input.bbox.h >= .999;
 		this.frameLazy.noteOnDemandRequest({
@@ -9226,11 +9675,12 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends require_dist.BaseAdd
 	*/
 	async runDetailSubtree(input) {
 		const convention = await this.cropConvention.refresh(this.ctxIfReady?.api);
+		await this.customModels.refresh(this.ctxIfReady?.api);
 		const outcome = await runDetailSubtree({
 			resolveChildSteps: (deviceId, parentClassName, filter) => this.resolveDetailChildSteps(deviceId, parentClassName, filter),
 			getNativeCrop: (deviceId, handle, paddedBbox) => this.getNativeCropForDetail(deviceId, handle, paddedBbox),
 			runPipeline: (steps, imageJpeg, deviceId, deviceKey, nativeCropRef) => this.runDetailPipeline(steps, imageJpeg, deviceId, deviceKey, nativeCropRef),
-			resolveStepDevice: (deviceId, step) => this.resolveDetailStepDevice(deviceId, step),
+			placeStep: (deviceId, step) => this.placeDetailStepForCamera(deviceId, step),
 			resolveCropConvention: () => convention,
 			logger: this.detailSubtreeLogger()
 		}, input);
@@ -9354,6 +9804,13 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends require_dist.BaseAdd
 	* global settings, NOT from the attach config. See `crop-convention-source.ts`
 	* for why eleven attach builders make the attach config the wrong carrier.
 	*/
+	/**
+	* The custom-model registry, merged into the catalog the device jump judges
+	* (D657): a custom model with a tflite build, pinned on a Coral, runs there.
+	* Refreshed on the async boundaries (`runInference`, `runDetailSubtree`),
+	* read synchronously by the placement.
+	*/
+	customModels = new require_default_detection_model.CustomModelCatalog({ warn: (message, extras) => this.ctxIfReady?.logger.warn(message, extras) });
 	cropConvention = new CropConventionSource({ logger: {
 		info: (message, extras) => this.ctxIfReady?.logger.info(message, extras),
 		warn: (message, extras) => this.ctxIfReady?.logger.warn(message, extras)
@@ -9444,39 +9901,94 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends require_dist.BaseAdd
 		return { warn: (message, extras) => this.ctxIfReady?.logger.warn(message, extras) };
 	}
 	/**
-	* Step-tree device jump (phase 1) — pick which same-node inference device an
-	* enrichment `step` runs on. AUTO-jumps only when the camera's elected device
-	* cannot run the step's model (its format has no build); an operator
-	* `step.jumpDeviceKey` overrides. Returns the resolved `<backend>:<device>`
-	* key, or `undefined` (⇒ the runner's per-camera default pool) when there is
-	* nothing to route: no elected device, or no jump roster on the attach.
+	* Step-tree device jump — place one enrichment subtree on a same-node
+	* inference device ({@link placeDetailStep}). AUTO-jumps only when the
+	* camera's elected device cannot run the subtree (its format has no build);
+	* an operator `step.jumpDeviceKey` overrides. A jumped subtree runs with the
+	* TARGET device's provisioning carried on the roster (D650), never the
+	* elected device's. `deviceKey: undefined` ⇒ the runner's per-camera default
+	* pool (no elected device).
 	*
-	* When NO enabled device on the node can run the step, logs a LOUD warn once
-	* per (camera, step) — killing the historical SILENT per-child degrade (an
-	* `edgetpu` root would otherwise drop faces/plates/clip with no signal).
+	* Logs the jump ONCE per (camera, step, target), and — when NO enabled device
+	* on the node can run the subtree — a LOUD warn once per (camera, step).
+	*/
+	placeDetailStepForCamera(deviceId, step) {
+		const config = this.attached.get(deviceId)?.config;
+		const placement = this.placementOf(config, step, this.perDeviceAttachedCounts());
+		const decision = placement.decision;
+		if (decision?.kind === "no-candidate") this.warnStepHasNoRunnableDevice(deviceId, step.addonId, decision.deviceKey);
+		else if (decision?.kind === "jumped" && config?.deviceKey) this.logStepJumped(deviceId, config.deviceKey, decision, placement);
+		return placement;
+	}
+	/**
+	* Where one detail subtree of this camera runs — the ONE decision both the
+	* detail plane (which dispatches it) and the frame plane (which decides what
+	* the elected pool pre-warms, D657) read. Pure: nothing is logged here.
+	*/
+	placementOf(config, step, attachedByKey) {
+		return require_default_detection_model.placeDetailStep({
+			step,
+			effectiveDeviceKey: config?.deviceKey,
+			roster: config?.inferenceDevices,
+			attachedByKey,
+			getStepDef: this.customModels.stepDefinition
+		});
+	}
+	/**
+	* The tree this camera's frame-plane dispatch carries (D657): a detail
+	* subtree the placement sends to another device (or to none) is left out,
+	* so its model is never loaded on the elected pool — it loads on its
+	* target, with the target's provisioning, when the detail plane dispatches
+	* it there. Said once per (camera, elected device, set left out).
 	*/
-	resolveDetailStepDevice(deviceId, step) {
+	stepsForElectedPoolOf(deviceId, steps) {
 		const config = this.attached.get(deviceId)?.config;
-		const effectiveDeviceKey = config?.deviceKey;
-		if (!effectiveDeviceKey) return void 0;
-		const roster = config?.inferenceDevices;
-		if (!roster || roster.length < 2) return effectiveDeviceKey;
+		if (config?.deviceKey === void 0 || (config.inferenceDevices?.length ?? 0) < 2) {
+			this.noteElectedPoolDelegation(deviceId, void 0, []);
+			return steps;
+		}
 		const attachedByKey = this.perDeviceAttachedCounts();
-		const devices = roster.map((d) => ({
-			deviceKey: d.deviceKey,
-			weight: d.weight,
-			maxSessions: d.maxSessions,
-			attachedCameras: attachedByKey.get(d.deviceKey) ?? 0
-		}));
-		const canRun = buildSubtreeCanRun(step, tryGetStepDefinition);
-		const result = resolveStepDevice({
-			effectiveDeviceKey,
-			devices,
-			...step.jumpDeviceKey !== void 0 ? { manualJumpDeviceKey: step.jumpDeviceKey } : {},
-			canRun
+		const result = require_default_detection_model.stepsForElectedPool(steps, isDetailPlaneStepId, (step) => this.placementOf(config, step, attachedByKey));
+		this.noteElectedPoolDelegation(deviceId, config.deviceKey, result.delegated);
+		return result.delegated.length === 0 ? steps : result.steps;
+	}
+	/**
+	* Say once per STATE CHANGE which detail steps a camera's elected pool no
+	* longer loads: a camera moving A → B → A says so again on A.
+	*/
+	noteElectedPoolDelegation(deviceId, electedDeviceKey, delegated) {
+		const state = `${electedDeviceKey ?? ""}|${delegated.join(",")}`;
+		if (this.electedPoolDelegationState.get(deviceId) === state) return;
+		this.electedPoolDelegationState.set(deviceId, state);
+		if (delegated.length === 0) return;
+		this.ctx?.logger.info("detail steps not loaded on the elected pool — they run elsewhere", {
+			tags: { deviceId },
+			meta: {
+				electedDeviceKey: electedDeviceKey ?? null,
+				steps: [...delegated]
+			}
+		});
+	}
+	/** Per camera, the last (elected device, steps left out) state that was logged. */
+	electedPoolDelegationState = /* @__PURE__ */ new Map();
+	/** `${deviceId}:${addonId}:${target}` triples whose jump has been logged. */
+	loggedStepJumps = /* @__PURE__ */ new Set();
+	logStepJumped(deviceId, electedDeviceKey, decision, placement) {
+		const step = placement.step;
+		const key = `${deviceId}:${step.addonId}:${decision.deviceKey}`;
+		if (this.loggedStepJumps.has(key)) return;
+		this.loggedStepJumps.add(key);
+		this.ctx?.logger.info("enrichment step runs on another device of this node", {
+			tags: { deviceId },
+			meta: {
+				step: step.addonId,
+				electedDeviceKey,
+				targetDeviceKey: decision.deviceKey,
+				reason: decision.reason,
+				provisioned: placement.provisioned,
+				modelId: step.modelId ?? null
+			}
 		});
-		if (result.kind === "no-candidate") this.warnStepHasNoRunnableDevice(deviceId, step.addonId, effectiveDeviceKey);
-		return result.deviceKey;
 	}
 	/** Live attached-camera count per inference `deviceKey` on this runner. */
 	perDeviceAttachedCounts() {
@@ -9695,6 +10207,7 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends require_dist.BaseAdd
 		const warnPrefix = `${deviceId}:`;
 		for (const key of this.warnedNoJumpDevice) if (key.startsWith(warnPrefix)) this.warnedNoJumpDevice.delete(key);
 		this.attached.delete(deviceId);
+		this.electedPoolDelegationState.delete(deviceId);
 		this.lastMotionAt.delete(deviceId);
 		this.lastEmittedCameraMetrics.delete(deviceId);
 		this.retention?.forgetDevice(deviceId);
@@ -10035,6 +10548,16 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends require_dist.BaseAdd
 		if (!admission) return void 0;
 		return () => admission.admit(deviceId, label);
 	}
+	/**
+	* The start's place in the node's queue of refused starts (D652) — taken by
+	* the guarded start on its first refusal, kept until it is over. Spread into
+	* `startGuardedSessionDecode`'s deps; empty when this node runs no ceiling.
+	*/
+	liveWorkerSlotWaiter(deviceId) {
+		const admission = this.liveWorkers;
+		if (!admission) return {};
+		return { slotWaiter: () => admission.slotWaiter(deviceId) };
+	}
 	buildDecodeSpawnAcquire(log, label) {
 		return async () => {
 			const gate = this.spawnGate;
@@ -10063,8 +10586,9 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends require_dist.BaseAdd
 		const teardown = startGuardedSessionDecode({
 			logger: log,
 			admitWorker: this.buildLiveWorkerAdmit(config.deviceId, "detect"),
+			...this.liveWorkerSlotWaiter(config.deviceId),
 			acquire: () => this.acquireSessionDecodeRestream(api, config.deviceId, config.detectionStreamId, `session-decode:detect:${config.deviceId}`, resolveSessionDecodeHostname(config, process.env["CAMSTACK_HUB_URL"]), resolveSessionDecodeOwnerNodeId(config), true),
-			startPump: (source) => {
+			startPump: (source, hooks) => {
 				const dialMs = Date.now() - requestedAt;
 				const useLocalFrameRef = this.executorCoLocated() && process.env["CAMSTACK_DISABLE_LOCAL_FRAME_REF"] !== "1";
 				log.info("session-decode: detection routed through per-session decode worker (rgb)", { meta: {
@@ -10076,6 +10600,7 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends require_dist.BaseAdd
 				return startSessionDecodePump({
 					fork: this.forkDecodeWorkerWithLease,
 					lease: this.resolveSessionLeaseKnobs,
+					onWorkerGone: hooks.onWorkerGone,
 					logger: log,
 					source,
 					opts: {
@@ -10157,10 +10682,30 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends require_dist.BaseAdd
 								strideMs: report.strideMs,
 								subsampled: report.subsampled,
 								laneRefused: runner.preRollRefusedCount(config.deviceId),
-								budgetFrames: this.preRollBudgetFor(config)
+								budgetFrames: this.preRollBudgetFor(config),
+								effectiveBudgetFrames: report.budgetFrames
 							}
 						});
 					},
+					onPreRollSettled: (summary) => {
+						const lost = summary.lostByReason.evicted + summary.lostByReason.cleared + summary.lostByReason["download-failed"] + summary.lostByReason.miss;
+						const meta = {
+							streamId: config.detectionStreamId,
+							...summary,
+							lost
+						};
+						if (lost > 0 || summary.unsettled > 0) {
+							log.info("session-decode: pre-roll frames settled", {
+								tags: { deviceId: config.deviceId },
+								meta
+							});
+							return;
+						}
+						log.debug("session-decode: pre-roll frames settled", {
+							tags: { deviceId: config.deviceId },
+							meta
+						});
+					},
 					onFirstFrame: (timing) => {
 						const phaseActiveAt = this.lastMotionAt.get(config.deviceId);
 						log.info("session-decode: detection first frame", {
@@ -10204,8 +10749,8 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends require_dist.BaseAdd
 				});
 			}
 		});
-		return () => {
-			teardown();
+		return (mode) => {
+			teardown(mode);
 		};
 	}
 	/**
@@ -10226,8 +10771,9 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends require_dist.BaseAdd
 		return startGuardedSessionDecode({
 			logger: log,
 			admitWorker: this.buildLiveWorkerAdmit(config.deviceId, "motion"),
+			...this.liveWorkerSlotWaiter(config.deviceId),
 			acquire: () => this.acquireSessionDecodeRestream(api, config.deviceId, config.motionStreamId, `session-decode:motion:${config.deviceId}`, resolveSessionDecodeHostname(config, process.env["CAMSTACK_HUB_URL"]), resolveSessionDecodeOwnerNodeId(config)),
-			startPump: (source) => {
+			startPump: (source, hooks) => {
 				log.info("session-decode: motion routed through per-session decode worker (gray)", { meta: {
 					streamId: config.motionStreamId,
 					codec: source.codec
@@ -10235,6 +10781,7 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends require_dist.BaseAdd
 				return startSessionDecodePump({
 					fork: this.forkDecodeWorkerWithLease,
 					lease: this.resolveSessionLeaseKnobs,
+					onWorkerGone: hooks.onWorkerGone,
 					logger: log,
 					source,
 					opts: {
@@ -10371,6 +10918,7 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends require_dist.BaseAdd
 		}
 		const camConfig = this.attached.get(deviceId)?.config;
 		const steps = camConfig?.steps;
+		await this.customModels.refresh(api);
 		if (!steps) {
 			log.warn("runInference: no steps in attach config — skipping frame (legacy attach?)");
 			return null;
@@ -10405,6 +10953,7 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends require_dist.BaseAdd
 				});
 			}
 		}
+		dispatchSteps = this.stepsForElectedPoolOf(deviceId, dispatchSteps);
 		let image;
 		const executorCoLocated = this.executorCoLocated();
 		if (!executorCoLocated) {
@@ -10534,6 +11083,7 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends require_dist.BaseAdd
 				const cropResult = await api.pipelineExecutor.runPipeline.mutate({
 					steps: [step],
 					image: view.jpeg,
+					deviceId,
 					plane: "frame",
 					...deviceKey ? { deviceKey } : {}
 				});
@@ -10902,15 +11452,36 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends require_dist.BaseAdd
 	* found/report semantics can't drift between the two admission
 	* mechanisms.
 	*/
-	finishOccupancyBurst(deviceId, log, collected) {
+	finishOccupancyBurst(deviceId, log, summary) {
 		this.occupancyBurstInFlight.delete(deviceId);
 		const found = this.occupancyBurstFound.has(deviceId);
 		this.occupancyBurstFound.delete(deviceId);
+		if (summary.inferred === 0) {
+			log.info("occupancy re-check: burst complete — nothing inferred, no verdict", {
+				tags: { deviceId },
+				meta: {
+					...summary,
+					verdict: null
+				}
+			});
+			return;
+		}
 		this.runner?.reportOccupancyBurstOutcome(deviceId, found);
-		log.debug("occupancy re-check: burst complete", { meta: {
-			collected,
+		const meta = {
+			...summary,
 			found
-		} });
+		};
+		if (summary.lost > 0) {
+			log.info("occupancy re-check: burst complete", {
+				tags: { deviceId },
+				meta
+			});
+			return;
+		}
+		log.debug("occupancy re-check: burst complete", {
+			tags: { deviceId },
+			meta
+		});
 	}
 	/**
 	* Task 10: arm a TAP-based occupancy burst for a device whose analyzer
@@ -10946,21 +11517,30 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends require_dist.BaseAdd
 				log.debug("occupancy re-check: tap safety timeout reached", { meta: { collected } });
 				this.finishOccupancyTap(deviceId);
 			}, OCCUPANCY_BURST_SAFETY_TIMEOUT_MS);
+			const ledger = new OccupancyBurstLedger({
+				settleBoundMs: OCCUPANCY_BURST_SETTLE_BOUND_MS,
+				onComplete: resolve
+			});
 			this.occupancyTaps.set(deviceId, {
 				remaining: frames,
 				collected: 0,
 				safetyTimer,
+				ledger,
 				resolve
 			});
 		});
 	}
-	/** Idempotent: a no-op once the tap has already settled (timer fired, or the budget already drained). */
+	/**
+	* Close the tap's COLLECTION. Idempotent: a no-op once the tap has already
+	* closed (timer fired, or the budget already drained). The tap's promise
+	* resolves later, from its ledger, once the frames it admitted have settled.
+	*/
 	finishOccupancyTap(deviceId) {
 		const tap = this.occupancyTaps.get(deviceId);
 		if (!tap) return;
 		clearTimeout(tap.safetyTimer);
 		this.occupancyTaps.delete(deviceId);
-		tap.resolve(tap.collected);
+		tap.ledger.close();
 	}
 	/**
 	* Tee an arriving analyzer motion frame into occupancy-burst detection
@@ -10975,7 +11555,8 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends require_dist.BaseAdd
 	teeOccupancyTapFrame(deviceId, frame, handle) {
 		const tap = this.occupancyTaps.get(deviceId);
 		if (!tap) return;
-		this.runner?.enqueueOccupancyFrame(deviceId, frame, handle);
+		const settle = tap.ledger.admit();
+		if (!this.runner?.enqueueOccupancyFrame(deviceId, frame, handle, settle)) settle("lost");
 		tap.collected++;
 		tap.remaining--;
 		if (tap.remaining <= 0) this.finishOccupancyTap(deviceId);
@@ -10995,9 +11576,9 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends require_dist.BaseAdd
 		const lastFrameAt = this.lastMotionFrameAt.get(deviceId);
 		const motionFresh = lastFrameAt !== void 0 && Date.now() - lastFrameAt < MOTION_FRESHNESS_WINDOW_MS;
 		if (attachment.motionUnsubscribe !== null && motionFresh) {
-			const collected = await this.startOccupancyTap(deviceId, frames, log);
-			if (collected > 0) {
-				this.finishOccupancyBurst(deviceId, log, collected);
+			const summary = await this.startOccupancyTap(deviceId, frames, log);
+			if (summary.frames > 0) {
+				this.finishOccupancyBurst(deviceId, log, summary);
 				return;
 			}
 			log.debug("occupancy re-check: tap collected 0 frames, falling back to dial", { meta: { frames } });
@@ -11028,76 +11609,91 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends require_dist.BaseAdd
 			fallback: alreadyInFlight
 		} });
 		let count = 0;
+		/** Collection is over: no further frame is admitted to this burst. */
+		let admissionClosed = false;
+		/** The burst has reported its verdict (or its lack of one). */
 		let settled = false;
 		let teardown = null;
-		const cleanup = () => {
+		const cleanup = (summary) => {
 			if (settled) return;
 			settled = true;
-			teardown?.();
-			this.finishOccupancyBurst(deviceId, log, count);
+			this.finishOccupancyBurst(deviceId, log, summary);
+		};
+		const ledger = new OccupancyBurstLedger({
+			settleBoundMs: OCCUPANCY_BURST_SETTLE_BOUND_MS,
+			onComplete: cleanup
+		});
+		const closeAdmission = () => {
+			if (admissionClosed) return;
+			admissionClosed = true;
+			clearTimeout(safetyTimer);
+			teardown?.("drain");
+			ledger.close();
+		};
+		/** Offer one collected frame to the burst; `true` = the runner admitted it. */
+		const admit = (frame, handle) => {
+			const settle = ledger.admit();
+			const admitted = runner.enqueueOccupancyFrame(deviceId, frame, handle, settle);
+			if (!admitted) settle("lost");
+			count++;
+			if (count >= frames) closeAdmission();
+			return admitted;
 		};
 		const safetyTimer = setTimeout(() => {
 			log.debug("occupancy re-check: safety timeout reached", { meta: { collected: count } });
-			cleanup();
+			closeAdmission();
 		}, OCCUPANCY_BURST_SAFETY_TIMEOUT_MS);
 		teardown = startGuardedSessionDecode({
 			logger: log,
 			admitWorker: this.buildLiveWorkerAdmit(deviceId, "occupancy"),
+			...this.liveWorkerSlotWaiter(deviceId),
 			acquire: () => this.acquireSessionDecodeRestream(api, config.deviceId, config.detectionStreamId, `session-decode:occupancy:${config.deviceId}`, resolveSessionDecodeHostname(config, process.env["CAMSTACK_HUB_URL"]), resolveSessionDecodeOwnerNodeId(config)),
-			startPump: (source) => {
+			startPump: (source, hooks) => {
 				const useLocalFrameRef = this.executorCoLocated() && process.env["CAMSTACK_DISABLE_LOCAL_FRAME_REF"] !== "1";
 				return startSessionDecodePump({
 					fork: this.forkDecodeWorkerWithLease,
 					lease: this.resolveSessionLeaseKnobs,
+					onWorkerGone: hooks.onWorkerGone,
 					logger: log,
 					source,
 					opts: {
 						fps: config.detectionFps,
 						format: "rgb"
 					},
+					shouldMaterializeFrame: () => !admissionClosed,
 					...useLocalFrameRef ? {
 						frameRegistry: require_default_detection_model.localFrameRegistry,
 						inlineWhen: () => runner.detectionBackpressure(config.deviceId),
 						inlineViewSpec: SPLIT_DETECTION_VIEW,
 						onFrameRef: (frame, nativeCrop) => {
-							if (settled) return false;
+							if (admissionClosed) return false;
 							const handle = writeRetainedDetectionFrame(retainedFrames, config.deviceId, frame, this.retention);
 							if (handle && nativeCrop) {
 								this.nativeCropRegistry.register(handle, nativeCrop, config.deviceId);
 								this.bindFrameCutter(handle, nativeCrop);
 							}
-							const admitted = runner.enqueueOccupancyFrame(deviceId, frame, handle);
+							const admitted = admit(frame, handle);
 							if (admitted) nativeCrop?.markInferred();
-							count++;
-							if (count >= frames) {
-								clearTimeout(safetyTimer);
-								cleanup();
-							}
 							return admitted;
 						}
 					} : { inlineViewSpec: SPLIT_DETECTION_VIEW },
 					acquireSpawnSlot: this.buildDecodeSpawnAcquire(log, "occupancy"),
-					onEnded: () => cleanup(),
+					onEnded: () => closeAdmission(),
 					onDecodedFrame: (frame, nativeCrop) => {
-						if (settled) return;
+						if (admissionClosed) return;
 						const handle = writeRetainedDetectionFrame(retainedFrames, config.deviceId, frame, this.retention);
 						if (handle && nativeCrop) {
 							this.nativeCropRegistry.register(handle, nativeCrop, config.deviceId);
 							this.bindFrameCutter(handle, nativeCrop);
 						}
-						if (runner.enqueueOccupancyFrame(deviceId, frame, handle)) nativeCrop?.markInferred();
-						count++;
-						if (count >= frames) {
-							clearTimeout(safetyTimer);
-							cleanup();
-						}
+						if (admit(frame, handle)) nativeCrop?.markInferred();
 					}
 				});
 			}
 		});
-		if (settled) {
+		if (admissionClosed) {
 			clearTimeout(safetyTimer);
-			teardown();
+			teardown("drain");
 		}
 	}
 	emitInferenceResult(deviceId, frame, result, handle, source, occasion) {