@camstack/addon-pipeline 1.2.295 → 1.2.296

package/dist/pipeline-runner/index.mjs

@@ -1,7 +1,7 @@
-import { An as lazy, D as MOTION_CLOSE_AFTER_MS, Dn as array, En as _enum, In as string, Mn as number, Mt as pickNativeLeaseOverride, Nn as object, O as NativeLeaseAdmissionSchema, On as boolean, Pt as pipelineRunnerCapability, Rn as EventCategory, en as errMsg, h as DEFAULT_DETAIL_CROP_CONVENTION, hn as defineCustomActions, i as BackgroundRunRegistry, jn as literal, jt as pickDetailCropConvention, k as NativeLeaseSettingsSchema, mn as customAction, nt as deriveDetailCropRect, pn as createEvent, pt as failureContributionCapability, sn as BaseAddon, v as DEFAULT_NATIVE_LEASE_SETTINGS, vt as loadContributionCapability, w as FailureCounters, xn as nodePin, y as DEVICE_BACKEND_TO_FORMAT } from "../dist-CuxSNLKW.mjs";
-import { i as NO_COST_CLAIM, t as ChildCostRegistry } from "../node-Cqb1QiXk.mjs";
-import { a as localFrameRegistry, d as getStepDefinition, i as rootObjectGate, o as resolveFrameViewGeometry, p as RETIRED_MODEL_IDS, r as macroGateVerdict } from "../default-detection-model-CAUBVbgK.mjs";
-import { t as isWorkerReply } from "../worker-protocol-C_W-P_g-.mjs";
+import { D as MOTION_CLOSE_AFTER_MS, Dn as _enum, Ft as pipelineRunnerCapability, Ln as string, Mn as literal, Nn as number, Nt as pickNativeLeaseOverride, O as NativeLeaseAdmissionSchema, On as array, Pn as object, Sn as nodePin, cn as BaseAddon, gn as defineCustomActions, h as DEFAULT_DETAIL_CROP_CONVENTION, hn as customAction, i as BackgroundRunRegistry, jn as lazy, jt as pickDetailCropConvention, k as NativeLeaseSettingsSchema, kn as boolean, mn as createEvent, nt as deriveDetailCropRect, pt as failureContributionCapability, tn as errMsg, v as DEFAULT_NATIVE_LEASE_SETTINGS, vt as loadContributionCapability, w as FailureCounters, y as DEVICE_BACKEND_TO_FORMAT, zn as EventCategory } from "../dist-CCd0Q3nr.mjs";
+import { i as NO_COST_CLAIM, t as ChildCostRegistry } from "../node-DgMSXSWP.mjs";
+import { a as localFrameRegistry, d as getStepDefinition, i as rootObjectGate, o as resolveFrameViewGeometry, p as RETIRED_MODEL_IDS, r as macroGateVerdict } from "../default-detection-model-Co578D8C.mjs";
+import { t as isWorkerReply } from "../worker-protocol-D_NzPcnh.mjs";
 import { t as resolveHubHostname } from "../hub-hostname-cCknRYKj.mjs";
 import { t as getSharp } from "../lazy-sharp-DXsqwpph.mjs";
 import { c as withDetectionIntent, o as preRollRequestOf, t as DETECTION_PRE_ROLL_REQUEST_MS } from "../restream-intent-DyGmLAU9.mjs";
@@ -14,7 +14,7 @@ import { PerformanceObserver } from "node:perf_hooks";
 import { attributeStall } from "@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 = fileURLToPath(new URL("../session-decode/decode-worker-child.js", import.meta.url));
+var CHILD_ENTRY_PATH = fileURLToPath(new URL("../session-decode/decode-worker-main.js", import.meta.url));
 /**
 * Known kill signals the coordinator may pass, mapped to their `NodeJS.Signals`
 * literal so `ChildProcess.kill` receives a correctly-typed signal without a
@@ -35,21 +35,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) {
@@ -250,58 +265,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;
 				}
 			}
@@ -314,7 +348,7 @@ function startGuardedSessionDecode(deps) {
 					attempt: attempt + 1,
 					error: errMsg(err)
 				} });
-				await waitBackoff(attempt);
+				await waitBackoff(attempt, null);
 				continue;
 			}
 			if (aborted) {
@@ -325,27 +359,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: 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();
 	};
 }
@@ -414,6 +468,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) {
@@ -422,6 +491,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;
@@ -478,7 +589,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,
@@ -494,6 +607,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: {
@@ -507,6 +621,7 @@ var LiveDecodeWorkerAdmission = class {
 			if (released) return;
 			released = true;
 			this.live -= 1;
+			this.wakeNext();
 		} };
 	}
 };
@@ -1443,6 +1558,29 @@ 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";
+/**
 * 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.
@@ -1514,30 +1652,38 @@ 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 to the consumer and not yet closed. Each is a frame the
+	* consumer still holds a reference to — queued, in flight, or being read —
+	* and each dies with the worker. This is what a drain waits on.
+	*/
+	openImages = 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)));
 	}
@@ -1602,6 +1748,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 });
@@ -1616,6 +1766,7 @@ var SessionDecodeSession = class {
 			} catch {
 				this.pendingNativeCrops.delete(requestId);
 				resolve({ kind: "miss" });
+				this.settleDrainIfDone();
 			}
 		});
 	}
@@ -1660,20 +1811,135 @@ var SessionDecodeSession = class {
 			frameId
 		});
 	}
-	/** Teardown: `stop`, `kill()`, arm the SIGKILL fallback unless already exited. */
-	teardown() {
+	/** A yielded image the consumer now holds — see {@link openImages}. */
+	noteImageOpened() {
+		this.openImages += 1;
+	}
+	/** The consumer let go of a yielded image; a waiting drain may now be done. */
+	noteImageClosed() {
+		this.openImages = Math.max(0, this.openImages - 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 the 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.
+	*/
+	unsettledCount() {
+		return this.openImages + this.pendingReadCount() + 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: {
+				unsettledFrames: this.openImages,
+				pendingReads: this.pendingReadCount(),
+				pendingCrops: this.pendingNativeCrops.size,
+				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;
 		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 (!isWorkerReply(raw)) {
@@ -1722,7 +1988,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,
@@ -1730,25 +1996,46 @@ 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 ? {
+					unsettledFrames: this.openImages,
+					pendingReads: this.pendingReadCount()
+				} : {}
+			}
+		});
 		this.exited = true;
+		if (this.drainTimer) {
+			clearTimeout(this.drainTimer);
+			this.drainTimer = null;
+		}
 		if (this.sigkillTimer) {
 			clearTimeout(this.sigkillTimer);
 			this.sigkillTimer = null;
@@ -1770,6 +2057,7 @@ var SessionDecodeSession = class {
 		if (!waiter) return;
 		this.pendingNativeCrops.delete(requestId);
 		waiter.resolve(attempt);
+		this.settleDrainIfDone();
 	}
 	settlePendingPull(outcome) {
 		const waiter = this.pendingPull;
@@ -1865,6 +2153,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
@@ -1884,6 +2173,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 } });
@@ -1898,6 +2188,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);
@@ -1935,6 +2226,7 @@ var SessionDecodeSession = class {
 /** Build the {@link FrameImage} adapter for one `frame` reply. */
 function buildFrameImage(session, reply) {
 	let closed = false;
+	session.noteImageOpened();
 	return {
 		width: reply.width,
 		height: reply.height,
@@ -1949,7 +2241,9 @@ function buildFrameImage(session, reply) {
 		releaseNativeLease: () => session.releaseLease(reply.frameId),
 		markInferred: () => session.markInferred(reply.frameId),
 		close: () => {
+			if (closed) return;
 			closed = true;
+			session.noteImageClosed();
 		}
 	};
 }
@@ -1958,15 +2252,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();
@@ -1979,8 +2281,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");
 		}
 	} };
 }
@@ -2024,17 +2329,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;
 		},
@@ -2140,13 +2467,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(() => {});
 	};
@@ -3576,8 +3911,8 @@ 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));
 	}
@@ -3684,6 +4019,72 @@ function resolveStepDevice(input) {
 		reason: "auto"
 	};
 }
+/**
+* Re-provision a jumped subtree for its TARGET device (D650): every step's
+* `modelId` / `settings` are REPLACED by the target's entry — the orchestrator
+* computed it as what the step would carry had the camera been elected onto
+* that device (its per-(node,device) base with the camera's override for it).
+* A step absent from the map runs with neither, i.e. the target format's
+* default model. The elected device's provisioning never follows a step across:
+* it was chosen for a format this subtree does not run on.
+*/
+function provisionSubtreeForDevice(step, provisioning) {
+	const own = provisioning[step.addonId];
+	const { modelId: _electedModelId, settings: _electedSettings, ...rest } = step;
+	return {
+		...rest,
+		...own?.modelId !== void 0 ? { modelId: own.modelId } : {},
+		...own?.settings !== void 0 ? { settings: own.settings } : {},
+		...step.children !== void 0 ? { children: step.children.map((c) => provisionSubtreeForDevice(c, provisioning)) } : {}
+	};
+}
+/**
+* Place ONE detail subtree (D650): which same-node device runs it
+* ({@link resolveStepDevice}) and, when it jumps, the provisioning it runs
+* with there ({@link provisionSubtreeForDevice}). Pure — the caller logs.
+*
+* A roster entry without `steps` came from an orchestrator that predates D650:
+* the step keeps what it was sent with, as it did before.
+*/
+function placeDetailStep(input) {
+	const { step, effectiveDeviceKey, roster } = input;
+	if (!effectiveDeviceKey) return {
+		deviceKey: void 0,
+		step,
+		decision: null,
+		provisioned: false
+	};
+	if (!roster || roster.length < 2) return {
+		deviceKey: effectiveDeviceKey,
+		step,
+		decision: null,
+		provisioned: false
+	};
+	const decision = resolveStepDevice({
+		effectiveDeviceKey,
+		devices: roster.map((d) => ({
+			deviceKey: d.deviceKey,
+			weight: d.weight,
+			maxSessions: d.maxSessions,
+			attachedCameras: input.attachedByKey.get(d.deviceKey) ?? 0
+		})),
+		...step.jumpDeviceKey !== void 0 ? { manualJumpDeviceKey: step.jumpDeviceKey } : {},
+		canRun: buildSubtreeCanRun(step, input.getStepDef)
+	});
+	if (decision.kind !== "jumped") return {
+		deviceKey: decision.deviceKey,
+		step,
+		decision,
+		provisioned: false
+	};
+	const provisioning = roster.find((d) => d.deviceKey === decision.deviceKey)?.steps;
+	return {
+		deviceKey: decision.deviceKey,
+		step: provisioning === void 0 ? step : provisionSubtreeForDevice(step, provisioning),
+		decision,
+		provisioned: provisioning !== void 0
+	};
+}
 //#endregion
 //#region src/pipeline-runner/device-load.ts
 /** The backend prefix of a `<backend>:<device>` key (bare `cpu` → `cpu`). */
@@ -3867,6 +4268,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 {
@@ -5279,41 +5748,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;
@@ -5334,7 +5768,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);
 	}
@@ -5349,8 +5783,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;
 	}
 };
@@ -5750,7 +6188,8 @@ function ownDetectionEntry(entry) {
 	return {
 		frame: ownFrame(entry.frame),
 		handle: entry.handle,
-		occasion: entry.occasion
+		occasion: entry.occasion,
+		...entry.onSettled ? { onSettled: entry.onSettled } : {}
 	};
 }
 /**
@@ -5892,9 +6331,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({
@@ -5903,6 +6343,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", {
@@ -5963,8 +6404,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);
@@ -6088,9 +6528,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
@@ -6119,7 +6564,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;
@@ -6127,7 +6572,8 @@ var PipelineRunner = class {
 		state.detectionQueue.enqueue({
 			frame,
 			handle,
-			occasion: "burst"
+			occasion: "burst",
+			...onSettled ? { onSettled } : {}
 		});
 		return true;
 	}
@@ -6335,7 +6781,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", {
@@ -6356,6 +6802,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) {
@@ -6443,6 +6924,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");
 		}
 	}
 	/**
@@ -6524,6 +7006,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");
 		}
 	}
 	/**
@@ -7067,6 +7550,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
@@ -7876,8 +8372,8 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends BaseAddon {
 			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();
@@ -9222,7 +9718,7 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends BaseAddon {
 			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);
@@ -9436,39 +9932,49 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends BaseAddon {
 		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).
 	*/
-	resolveDetailStepDevice(deviceId, step) {
+	placeDetailStepForCamera(deviceId, step) {
 		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;
-		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 placement = placeDetailStep({
+			step,
+			effectiveDeviceKey: config?.deviceKey,
+			roster: config?.inferenceDevices,
+			attachedByKey: this.perDeviceAttachedCounts(),
+			getStepDef: tryGetStepDefinition
+		});
+		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;
+	}
+	/** `${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() {
@@ -10027,6 +10533,16 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends BaseAddon {
 		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;
@@ -10055,8 +10571,9 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends BaseAddon {
 		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: {
@@ -10068,6 +10585,7 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends BaseAddon {
 				return startSessionDecodePump({
 					fork: this.forkDecodeWorkerWithLease,
 					lease: this.resolveSessionLeaseKnobs,
+					onWorkerGone: hooks.onWorkerGone,
 					logger: log,
 					source,
 					opts: {
@@ -10149,10 +10667,30 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends BaseAddon {
 								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", {
@@ -10196,8 +10734,8 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends BaseAddon {
 				});
 			}
 		});
-		return () => {
-			teardown();
+		return (mode) => {
+			teardown(mode);
 		};
 	}
 	/**
@@ -10218,8 +10756,9 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends BaseAddon {
 		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
@@ -10227,6 +10766,7 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends BaseAddon {
 				return startSessionDecodePump({
 					fork: this.forkDecodeWorkerWithLease,
 					lease: this.resolveSessionLeaseKnobs,
+					onWorkerGone: hooks.onWorkerGone,
 					logger: log,
 					source,
 					opts: {
@@ -10894,15 +11434,36 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends BaseAddon {
 	* 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
@@ -10938,21 +11499,30 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends BaseAddon {
 				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
@@ -10967,7 +11537,8 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends BaseAddon {
 	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);
@@ -10987,9 +11558,9 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends BaseAddon {
 		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 } });
@@ -11020,76 +11591,91 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends BaseAddon {
 			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: 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) {