@camstack/addon-pipeline 1.1.39 → 1.1.40

package/dist/pipeline-runner/index.js

@@ -2,10 +2,13 @@ Object.defineProperties(exports, {
 	__esModule: { value: true },
 	[Symbol.toStringTag]: { value: "Module" }
 });
-const require_dist = require("../dist-DbGdZ8Nr.js");
-const require_frame_handle_plane = require("../frame-handle-plane-B7jMIZc2.js");
+const require_dist = require("../dist-BJTPkJFw.js");
+const require_frame_handle_plane = require("../frame-handle-plane-BP8YV4sF.js");
 const require_hub_hostname = require("../hub-hostname-DAJXlOgV.js");
+const require_worker_protocol = require("../worker-protocol-BCfO8gUF.js");
 let _camstack_shm_ring = require("@camstack/shm-ring");
+let node_child_process = require("node:child_process");
+let node_url = require("node:url");
 //#region src/pipeline-runner/bench-actions.ts
 /**
 * Synthetic-bench custom actions for pipeline-runner.
@@ -233,6 +236,19 @@ var PULL_MAX_COUNT = 4;
 var MIN_POLL_INTERVAL_MS = 20;
 /** Poll period when the broker reports a non-positive cadence hint. */
 var FALLBACK_POLL_INTERVAL_MS = 200;
+/**
+* Ceiling on the poll period — we never poll SLOWER than this even when the
+* subscriber's `maxFps` implies a longer interval (e.g. detection at 10 fps →
+* 100 ms). A decoded frame otherwise sits in the ring up to a full poll period
+* before it is picked, and that wait lands directly in `frameAge` (the analyzed
+* frame's staleness). Polling faster grabs the freshest frame sooner; because
+* the loop reads ONLY the newest handle per tick and the decoder emits at its
+* own rate, the extra ticks that find no new frame are near-free (an empty
+* `pullHandles` + no pixel read), so this lowers latency without a proportional
+* read-cost increase. `maxFps` still bounds the DELIVERED rate downstream via
+* the latest-wins queue — this only decouples poll cadence from it.
+*/
+var MAX_POLL_INTERVAL_MS = 50;
 /** First subscribe-retry delay, doubled on every subsequent failure. */
 var INITIAL_SUBSCRIBE_RETRY_BACKOFF_MS = 250;
 /**
@@ -359,7 +375,7 @@ function startPolling(options, source, subscriptionId, resolvedMaxFps, lifecycle
 	const { brokerId, onFrame, logger, ownNodeId, getRemoteFrame, tag } = options;
 	const readers = new _camstack_shm_ring.FrameRingReaderCache(logger);
 	const throttle = new ForeignHandleThrottle();
-	const pollIntervalMs = resolvedMaxFps > 0 ? Math.max(MIN_POLL_INTERVAL_MS, Math.round(1e3 / resolvedMaxFps)) : FALLBACK_POLL_INTERVAL_MS;
+	const pollIntervalMs = Math.min(MAX_POLL_INTERVAL_MS, resolvedMaxFps > 0 ? Math.max(MIN_POLL_INTERVAL_MS, Math.round(1e3 / resolvedMaxFps)) : FALLBACK_POLL_INTERVAL_MS);
 	let timer;
 	const tick = async () => {
 		if (lifecycle.stopped) return;
@@ -368,8 +384,9 @@ function startPolling(options, source, subscriptionId, resolvedMaxFps, lifecycle
 				subscriptionId,
 				maxCount: PULL_MAX_COUNT
 			});
-			for (const handle of handles) {
+			for (let i = handles.length - 1; i >= 0; i -= 1) {
 				if (lifecycle.stopped) break;
+				const handle = handles[i];
 				const frame = await resolvePolledFrame(handle, {
 					ownNodeId,
 					readers,
@@ -378,7 +395,10 @@ function startPolling(options, source, subscriptionId, resolvedMaxFps, lifecycle
 					logger,
 					tag
 				});
-				if (frame) onFrame(frame, handle);
+				if (frame) {
+					onFrame(frame, handle);
+					break;
+				}
 			}
 		} catch (err) {
 			logger.warn("frame-handle poller: pullFrameHandles failed", { meta: {
@@ -1074,12 +1094,13 @@ var PipelineRunner = class {
 			motionCooldownTimer: null,
 			lastArmedSource: null,
 			lastArmedRegions: void 0,
-			occupancyTimer: null
+			occupancyTimer: null,
+			motionInFlight: false
 		};
 		this.cameras.set(deviceId, state);
 		this.timingSampler.setDroppedFramesSource(deviceId, () => detectionQueue.droppedFrames);
 		if (registration.detectionMode === "on-motion") this.defaultRoundRobinKeys.push(deviceId);
-		if (registration.detectionMode === "on-motion" && (registration.occupancyRecheckSec ?? 0) > 0) state.occupancyTimer = setInterval(() => {
+		if (registration.detectionMode === "on-motion" && registration.occupancyRecheckEnabled === true && (registration.occupancyRecheckSec ?? 0) > 0) state.occupancyTimer = setInterval(() => {
 			if (state.phase === "watching") this.config.onOccupancyRecheck?.(deviceId, registration.occupancyRecheckFrames ?? 4);
 		}, (registration.occupancyRecheckSec ?? 0) * 1e3);
 		if (initialPhase === "active") {
@@ -1304,9 +1325,15 @@ var PipelineRunner = class {
 		this.processWithSemaphore(deviceId, entry, frameInput, state, "detection");
 	}
 	drainMotionQueues() {
-		for (const [deviceId, state] of this.cameras) while (state.motionQueue.size > 0) {
+		for (const [deviceId, state] of this.cameras) {
+			if (state.motionInFlight) continue;
+			if (state.motionQueue.size === 0) continue;
 			const entry = state.motionQueue.dequeue();
-			if (entry) this.config.analyzeMotion(deviceId, entry.frame, entry.handle);
+			if (!entry) continue;
+			state.motionInFlight = true;
+			Promise.resolve(this.config.analyzeMotion(deviceId, entry.frame, entry.handle)).catch(() => {}).finally(() => {
+				state.motionInFlight = false;
+			});
 		}
 	}
 	async processWithSemaphore(deviceId, entry, frameInput, state, streamType) {
@@ -1375,12 +1402,568 @@ var PipelineRunner = class {
 	}
 };
 //#endregion
+//#region src/session-decode/fork-decode-worker.ts
+/**
+* Real `fork` implementation for the session-decode coordinator — Epic C P1,
+* Task 4.
+*
+* Spawns the decode-worker child (`decode-worker-child.ts`, Task 2) as a
+* dedicated `child_process.fork` and adapts the returned `ChildProcess` to the
+* coordinator's minimal {@link ForkedChildLike} contract WITHOUT any cast —
+* an explicit forwarding wrapper, so a wider Node `ChildProcess` signature
+* never has to structurally satisfy the narrower interface.
+*
+* `serialization: 'advanced'` is MANDATORY: Node's default 'json' IPC
+* base64-serialises the `buffer` reply's `Uint8Array`, breaking the "raw
+* bytes, not base64" contract the coordinator + `worker-protocol.ts`'s
+* `value.bytes instanceof Uint8Array` guard both depend on. Advanced (V8
+* structured-clone) preserves the typed array on the wire.
+*
+* The child entry is resolved relative to THIS module's built location. Both
+* this module and `pipeline-runner/index.ts` bundle into the SAME entry
+* (`dist/pipeline-runner/index.js`, `manualChunks: () => null`), so
+* `import.meta.url` here is that file's URL and the sibling child lands at
+* `dist/session-decode/decode-worker-child.js` (its own vite build entry).
+*/
+/** 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));
+/**
+* Known kill signals the coordinator may pass, mapped to their `NodeJS.Signals`
+* literal so `ChildProcess.kill` receives a correctly-typed signal without a
+* cast. The coordinator only ever sends the default (undefined → SIGTERM) and
+* the SIGKILL fallback; anything unrecognised degrades to a plain `kill()`.
+*/
+var KILL_SIGNALS = {
+	SIGKILL: "SIGKILL",
+	SIGTERM: "SIGTERM"
+};
+/** Adapt a Node {@link ChildProcess} to the coordinator's {@link ForkedChildLike}. */
+function wrapChild(child) {
+	return {
+		send: (msg) => {
+			child.send(msg);
+		},
+		on: (ev, cb) => {
+			if (ev === "exit") child.on("exit", () => cb(void 0));
+			else child.on("message", (m) => cb(m));
+		},
+		kill: (signal) => {
+			if (signal === void 0) {
+				child.kill();
+				return;
+			}
+			const mapped = KILL_SIGNALS[signal];
+			if (mapped) child.kill(mapped);
+			else child.kill();
+		}
+	};
+}
+/**
+* Fork one decode-worker child. `source` is part of the coordinator's fork
+* signature (it forwards the same source in the subsequent `start` message);
+* the child entry itself is source-independent, so it is not consumed here.
+*/
+function forkDecodeWorker(_source) {
+	return wrapChild((0, node_child_process.fork)(CHILD_ENTRY_PATH, [], { serialization: "advanced" }));
+}
+//#endregion
+//#region src/session-decode/guarded-session-decode.ts
+/**
+* Guards the in-flight restream-acquire against a detach/unsubscribe race.
+*
+* `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 the acquire resolves —
+* if set, the 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.
+*/
+function startGuardedSessionDecode(deps) {
+	let aborted = false;
+	let stopPump = null;
+	let release = null;
+	(async () => {
+		const acquired = await deps.acquire();
+		if (!acquired) return;
+		if (aborted) {
+			acquired.release();
+			return;
+		}
+		release = acquired.release;
+		stopPump = deps.startPump(acquired.source);
+	})().catch((err) => {
+		deps.logger.warn("session-decode: guarded start failed", { meta: { error: require_dist.errMsg(err) } });
+	});
+	return () => {
+		aborted = true;
+		stopPump?.();
+		if (release) release();
+	};
+}
+//#endregion
+//#region src/session-decode/session-decode-coordinator.ts
+/** How long to wait after `kill()` before escalating to `kill('SIGKILL')`. */
+var SIGKILL_FALLBACK_MS = 1e3;
+/**
+* Default timeout for the `pull` round-trip preceding the FIRST delivered
+* frame. Task 0 live-measured cold-start (restream dial + hwaccel context +
+* keyframe wait) at 5-8s, so this must tolerate a slow-but-healthy start.
+*/
+var DEFAULT_FIRST_FRAME_TIMEOUT_MS = 2e4;
+/** Default timeout for every `pull` round-trip AFTER the first frame arrives. */
+var DEFAULT_FRAME_TIMEOUT_MS = 1e4;
+function toError(err) {
+	return err instanceof Error ? err : new Error(String(err));
+}
+/**
+* Per-session mutable state + the message-handling logic that adapts the
+* child's `WorkerReply` stream into resolved/rejected waiter promises. One
+* instance is created per `generateVideoFrames()` call (i.e. per forked
+* child) — never shared across sessions.
+*/
+var SessionDecodeSession = class {
+	child;
+	logger;
+	firstFrameTimeoutMs;
+	frameTimeoutMs;
+	pendingPull = null;
+	pendingToBuffers = /* @__PURE__ */ new Map();
+	exited = false;
+	sigkillTimer = null;
+	pullTimeoutTimer = null;
+	firstFrameReceived = false;
+	constructor(child, logger, firstFrameTimeoutMs, frameTimeoutMs) {
+		this.child = child;
+		this.logger = logger;
+		this.firstFrameTimeoutMs = firstFrameTimeoutMs;
+		this.frameTimeoutMs = frameTimeoutMs;
+		this.child.on("message", (m) => this.handleMessage(m));
+		this.child.on("exit", () => this.handleExit());
+	}
+	start(source, opts) {
+		this.trySend({
+			kind: "start",
+			source,
+			opts
+		});
+	}
+	/**
+	* Send `pull` and resolve with the next `frame` or `ended` reply. Arms a
+	* bounded liveness timeout for the round-trip: if the child stops
+	* producing frames WITHOUT exiting, the timeout settles this pull as
+	* `ended` so the caller's async generator resumes, runs its `finally`,
+	* and tears the child down — see {@link handlePullTimeout}.
+	*/
+	pullNext() {
+		if (this.exited) return Promise.resolve({ kind: "ended" });
+		return new Promise((resolve, reject) => {
+			this.pendingPull = {
+				resolve,
+				reject
+			};
+			this.armPullTimeout();
+			try {
+				this.child.send({ kind: "pull" });
+			} catch (err) {
+				this.clearPullTimeout();
+				this.pendingPull = null;
+				reject(toError(err));
+			}
+		});
+	}
+	/** 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})`));
+		return new Promise((resolve, reject) => {
+			const waiter = {
+				resolve,
+				reject
+			};
+			this.queueToBufferWaiter(frameId, waiter);
+			try {
+				this.child.send({
+					kind: "toBuffer",
+					frameId,
+					opts
+				});
+			} catch (err) {
+				this.removeToBufferWaiter(frameId, waiter);
+				reject(toError(err));
+			}
+		});
+	}
+	/** Teardown: `stop`, `kill()`, arm the SIGKILL fallback unless already exited. */
+	teardown() {
+		this.clearPullTimeout();
+		this.trySend({ kind: "stop" });
+		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.tryKill("SIGKILL");
+		}, SIGKILL_FALLBACK_MS);
+		this.sigkillTimer.unref?.();
+	}
+	handleMessage(raw) {
+		if (!require_worker_protocol.isWorkerReply(raw)) {
+			this.logger.warn("session-decode-coordinator: dropping malformed worker reply", { meta: { raw } });
+			return;
+		}
+		switch (raw.kind) {
+			case "frame":
+				this.settlePendingPull({
+					kind: "frame",
+					reply: raw
+				});
+				return;
+			case "ended":
+				this.settlePendingPull({ kind: "ended" });
+				return;
+			case "buffer":
+				this.settleToBuffer(raw.frameId, raw.bytes);
+				return;
+			case "error":
+				this.settleError(raw.message, raw.frameId);
+				return;
+		}
+	}
+	handleExit() {
+		this.exited = true;
+		if (this.sigkillTimer) {
+			clearTimeout(this.sigkillTimer);
+			this.sigkillTimer = null;
+		}
+		this.clearPullTimeout();
+		if (this.pendingPull) {
+			const waiter = this.pendingPull;
+			this.pendingPull = null;
+			waiter.resolve({ kind: "ended" });
+		}
+		for (const waiters of this.pendingToBuffers.values()) for (const waiter of waiters) waiter.reject(/* @__PURE__ */ new Error("session-decode-coordinator: worker exited before toBuffer reply"));
+		this.pendingToBuffers.clear();
+	}
+	settlePendingPull(outcome) {
+		const waiter = this.pendingPull;
+		if (!waiter) {
+			this.logger.debug("session-decode-coordinator: dropping unsolicited pull-shaped reply", { meta: { outcomeKind: outcome.kind } });
+			return;
+		}
+		this.pendingPull = null;
+		this.clearPullTimeout();
+		if (outcome.kind === "frame") this.firstFrameReceived = true;
+		waiter.resolve(outcome);
+	}
+	/**
+	* Fires when a `pull` round-trip outlives its liveness timeout — the child
+	* stopped producing frames WITHOUT exiting (a hung decode). Settles the
+	* outstanding pull as `ended` (not a throw) so the consumer's async
+	* generator resumes cleanly, runs its `finally`, and tears the child down
+	* via {@link teardown} — which sends `stop`, `kill()`s, and arms the 1s
+	* SIGKILL fallback.
+	*/
+	handlePullTimeout(timeoutMs) {
+		this.pullTimeoutTimer = null;
+		const waiter = this.pendingPull;
+		if (!waiter) return;
+		this.pendingPull = null;
+		this.logger.warn(`session-decode-coordinator: decode worker produced no frame within ${timeoutMs}ms — ending session`, { meta: {
+			timeoutMs,
+			firstFrameReceived: this.firstFrameReceived
+		} });
+		waiter.resolve({ kind: "ended" });
+	}
+	armPullTimeout() {
+		const timeoutMs = this.firstFrameReceived ? this.frameTimeoutMs : this.firstFrameTimeoutMs;
+		this.pullTimeoutTimer = setTimeout(() => this.handlePullTimeout(timeoutMs), timeoutMs);
+		this.pullTimeoutTimer.unref?.();
+	}
+	clearPullTimeout() {
+		if (this.pullTimeoutTimer) {
+			clearTimeout(this.pullTimeoutTimer);
+			this.pullTimeoutTimer = null;
+		}
+	}
+	/**
+	* Correlate by `frameId`: a `buffer` reply only ever settles waiters queued
+	* under the SAME frameId — a late reply for a stale/superseded frame that
+	* nobody is (still) awaiting is dropped, never mistakenly resolves a
+	* different, newer frame's waiter.
+	*/
+	settleToBuffer(frameId, bytes) {
+		const queue = this.pendingToBuffers.get(frameId);
+		if (!queue || queue.length === 0) {
+			this.logger.debug("session-decode-coordinator: dropping stale/unknown buffer reply", { meta: { frameId } });
+			return;
+		}
+		const waiter = queue.shift();
+		if (queue.length === 0) this.pendingToBuffers.delete(frameId);
+		waiter?.resolve(bytes);
+	}
+	/**
+	* `error` replies MAY carry a `frameId` (a `toBuffer`-scoped miss, e.g. a
+	* stale/unknown frameId or a scale failure in `decode-worker-child.ts`) —
+	* those fail ONLY that frame's `toBuffer` waiter(s) so the pull stays alive
+	* and the generator keeps running (P2/I1: a single dropped frame must not
+	* tear the whole session down). An error WITHOUT a `frameId` is a
+	* session-level failure (decode-loop crash, dial error) and keeps the
+	* original fatal behavior: fail the outstanding `pull` first (the more
+	* common source), else fail every outstanding `toBuffer` waiter rather than
+	* silently dropping the error and leaving a caller hanging forever.
+	*/
+	settleError(message, frameId) {
+		const err = /* @__PURE__ */ new Error(`session-decode-coordinator: worker error — ${message}`);
+		if (frameId !== void 0) {
+			const queue = this.pendingToBuffers.get(frameId);
+			if (queue && queue.length > 0) {
+				for (const waiter of queue) waiter.reject(err);
+				this.pendingToBuffers.delete(frameId);
+				return;
+			}
+			this.logger.debug("session-decode-coordinator: dropping toBuffer error for unknown frameId", { meta: { frameId } });
+			return;
+		}
+		if (this.pendingPull) {
+			const waiter = this.pendingPull;
+			this.pendingPull = null;
+			this.clearPullTimeout();
+			waiter.reject(err);
+			return;
+		}
+		for (const waiters of this.pendingToBuffers.values()) for (const waiter of waiters) waiter.reject(err);
+		this.pendingToBuffers.clear();
+	}
+	queueToBufferWaiter(frameId, waiter) {
+		const queue = this.pendingToBuffers.get(frameId);
+		if (queue) queue.push(waiter);
+		else this.pendingToBuffers.set(frameId, [waiter]);
+	}
+	removeToBufferWaiter(frameId, waiter) {
+		const queue = this.pendingToBuffers.get(frameId);
+		if (!queue) return;
+		const idx = queue.indexOf(waiter);
+		if (idx >= 0) queue.splice(idx, 1);
+		if (queue.length === 0) this.pendingToBuffers.delete(frameId);
+	}
+	trySend(msg) {
+		try {
+			this.child.send(msg);
+		} catch (err) {
+			this.logger.warn("session-decode-coordinator: send to child failed", { meta: {
+				requestKind: msg.kind,
+				err: toError(err).message
+			} });
+		}
+	}
+	tryKill(signal) {
+		try {
+			this.child.kill(signal);
+		} catch (err) {
+			this.logger.warn("session-decode-coordinator: kill() on child failed", { meta: {
+				signal,
+				err: toError(err).message
+			} });
+		}
+	}
+};
+/** Build the {@link FrameImage} adapter for one `frame` reply. */
+function buildFrameImage(session, reply) {
+	let closed = false;
+	return {
+		width: reply.width,
+		height: reply.height,
+		format: reply.format,
+		toBuffer: async (opts) => {
+			if (closed) throw new Error(`session-decode-coordinator: toBuffer() called on a closed frame (frameId=${reply.frameId})`);
+			return session.requestBuffer(reply.frameId, opts);
+		},
+		close: () => {
+			closed = true;
+		}
+	};
+}
+/**
+* Create the `VideoFrameGenerator` adapter: forks one decode-worker child per
+* `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`.
+*/
+function createSessionDecodeCoordinator(deps) {
+	const firstFrameTimeoutMs = deps.firstFrameTimeoutMs ?? DEFAULT_FIRST_FRAME_TIMEOUT_MS;
+	const frameTimeoutMs = deps.frameTimeoutMs ?? DEFAULT_FRAME_TIMEOUT_MS;
+	return { async *generateVideoFrames(source, opts) {
+		const session = new SessionDecodeSession(deps.fork(source), deps.logger, firstFrameTimeoutMs, frameTimeoutMs);
+		session.start(source, opts);
+		try {
+			while (true) {
+				const outcome = await session.pullNext();
+				if (outcome.kind === "ended") return;
+				const { reply } = outcome;
+				yield {
+					timestamp: reply.timestamp,
+					image: buildFrameImage(session, reply)
+				};
+			}
+		} finally {
+			session.teardown();
+		}
+	} };
+}
+//#endregion
+//#region src/session-decode/session-decode-pump.ts
+/**
+* Pure gate: does this runner route camera decode through a per-session
+* decode worker (Epic C) instead of the shm frame-handle poller? This is now
+* a RUNNER-LEVEL setting (the pipeline-runner addon's own config,
+* `this.config.useSessionDecode`) rather than a per-camera one — every
+* camera attached to this node shares the same decode path. DEFAULT TRUE:
+* the caller passes the runner's own `useSessionDecode` config value;
+* an operator unchecks it (node-wide) to fall back to the shared shm
+* frame-handle poller for every camera on this node.
+*/
+function shouldUseSessionDecode(enabled) {
+	return enabled === true;
+}
+/**
+* Detection working width cap — mirrors the shm decoder's
+* `initScaler` (`nodeav-decoder-session.ts`: `maxW = floor(640 / scale)`,
+* `scale = 1` default). The worker decodes full source resolution (e.g. a 4K
+* `native:main` stream); without this downscale `toBuffer` would ship a full
+* 3840×2160 rgb frame (~24 MB) over IPC per pull, which the detection path
+* cannot keep up with. Aspect ratio is preserved. A source already ≤ this
+* width (e.g. the small `native:sub` motion stream) is passed through
+* unscaled, exactly as the shm scaler's `min(srcW, maxW)` no-ops.
+*/
+var WORKING_MAX_WIDTH = 640;
+/** Aspect-preserving cap to {@link WORKING_MAX_WIDTH}; `undefined` when no downscale is needed. */
+function resolveWorkingResize(width, height) {
+	if (width <= WORKING_MAX_WIDTH || width <= 0) return void 0;
+	const outWidth = WORKING_MAX_WIDTH;
+	return {
+		width: outWidth,
+		height: Math.round(outWidth * height / width)
+	};
+}
+/**
+* Build a {@link DecodedFrame} from one pulled {@link VideoFrame}. Downscales to
+* the detection working width (see {@link resolveWorkingResize}) so the ROI
+* scaler ships a small frame instead of the full source resolution.
+* `capturedAt` is set to `Date.now()` so downstream frameAge metrics diff
+* against the wall clock (mirrors the shm-ring source, which stamps commit
+* time) — this is what lets Step 5 MEASURE session-decode frameAge vs the
+* shm-ring cameras.
+*/
+async function toDecodedFrame(frame, format) {
+	const resize = resolveWorkingResize(frame.image.width, frame.image.height);
+	const bytes = await frame.image.toBuffer({
+		format,
+		...resize ? { resize } : {}
+	});
+	return {
+		data: Buffer.from(bytes),
+		width: resize?.width ?? frame.image.width,
+		height: resize?.height ?? frame.image.height,
+		format,
+		timestamp: frame.timestamp,
+		capturedAt: Date.now()
+	};
+}
+/**
+* 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.
+*/
+function startSessionDecodePump(deps) {
+	const format = deps.opts.format ?? "rgb";
+	const iterator = createSessionDecodeCoordinator({
+		fork: deps.fork,
+		logger: deps.logger,
+		...deps.firstFrameTimeoutMs !== void 0 ? { firstFrameTimeoutMs: deps.firstFrameTimeoutMs } : {},
+		...deps.frameTimeoutMs !== void 0 ? { frameTimeoutMs: deps.frameTimeoutMs } : {}
+	}).generateVideoFrames(deps.source, deps.opts);
+	let stopped = false;
+	let releaseSpawnSlot = null;
+	let spawnSlotReleased = false;
+	const releaseSpawnSlotOnce = () => {
+		if (spawnSlotReleased) return;
+		const release = releaseSpawnSlot;
+		if (!release) return;
+		spawnSlotReleased = true;
+		releaseSpawnSlot = null;
+		release();
+	};
+	const pump = async () => {
+		try {
+			if (deps.acquireSpawnSlot) {
+				releaseSpawnSlot = await deps.acquireSpawnSlot();
+				if (stopped) {
+					releaseSpawnSlotOnce();
+					return;
+				}
+			}
+			let firstFrameSeen = false;
+			for await (const frame of iterator) {
+				if (!firstFrameSeen) {
+					firstFrameSeen = true;
+					releaseSpawnSlotOnce();
+				}
+				if (stopped) {
+					frame.image.close();
+					break;
+				}
+				try {
+					const decoded = await toDecodedFrame(frame, format);
+					deps.onDecodedFrame(decoded);
+				} catch (err) {
+					deps.logger.debug("session-decode pump: skipped a frame (decode/consume error)", { meta: {
+						deviceId: deps.source.deviceId,
+						format,
+						error: require_dist.errMsg(err)
+					} });
+				} finally {
+					frame.image.close();
+				}
+			}
+		} catch (err) {
+			deps.logger.warn("session-decode pump: frame loop ended with error", { meta: {
+				deviceId: deps.source.deviceId,
+				format,
+				error: require_dist.errMsg(err)
+			} });
+		} finally {
+			releaseSpawnSlotOnce();
+		}
+	};
+	pump();
+	return () => {
+		if (stopped) return;
+		stopped = true;
+		releaseSpawnSlotOnce();
+		iterator.return().catch(() => {});
+	};
+}
+//#endregion
 //#region src/pipeline-runner/index.ts
 var DEFAULT_CONFIG = {
 	maxQueueDepth: 30,
 	maxConcurrentInferences: 16,
 	targetLoadPercent: 80,
-	minThrottledFps: 1
+	minThrottledFps: 1,
+	useSessionDecode: true,
+	maxConcurrentDecodeSpawns: 3
 };
 /**
 * Pure decision helper: returns `true` when a dynamic frame-diff analyzer
@@ -1458,6 +2041,19 @@ function resolveMotionFrameSource(config, sharedWithDetection) {
 	};
 }
 /**
+* The owner hostname a session-decode worker must dial to reach this camera's
+* compressed restream. `undefined` (→ the broker returns a `127.0.0.1` URL,
+* correct for a node-local co-located worker) unless the camera's source is a
+* cross-node remote-restream, in which case the owner host is resolved exactly
+* as `remoteSourceFor`/`RemoteSourcePlane` do. Pure so the decision is
+* unit-testable without the addon/broker.
+*/
+function resolveSessionDecodeHostname(config, hubUrl) {
+	const frameSource = config.frameSource;
+	if (!isRemoteRestream(frameSource)) return void 0;
+	return require_hub_hostname.resolveHubHostname(frameSource.hubHostnameOverride, hubUrl);
+}
+/**
 * Interval for periodic metric snapshot emission. ~1 Hz strikes the
 * balance between UI freshness (overlay phase / fps numbers feel live)
 * and bus traffic (one snapshot per attached camera + one per node
@@ -1474,6 +2070,15 @@ var METRICS_SNAPSHOT_INTERVAL_MS = 1e3;
 var METRICS_HEARTBEAT_MS = 3e4;
 var PipelineRunnerAddon = class extends require_dist.BaseAddon {
 	runner = null;
+	/**
+	* Per-runner (per-node) decode-worker SPAWN-CONCURRENCY GATE (P5). A single
+	* counting semaphore every session-decode fork (detection + motion, all
+	* cameras on this node) passes through, sized to
+	* `config.maxConcurrentDecodeSpawns`. Bounds a synchronized multi-camera
+	* motion burst to N concurrent forks instead of stampeding the shared iGPU.
+	* `resize()`d live in `onConfigChanged`. Null until `onInitialize`.
+	*/
+	spawnGate = null;
 	attached = /* @__PURE__ */ new Map();
 	nodeId = "unknown";
 	metricsSnapshotTimer = null;
@@ -1512,6 +2117,14 @@ var PipelineRunnerAddon = class extends require_dist.BaseAddon {
 	*/
 	remotePlanes = /* @__PURE__ */ new Map();
 	/**
+	* Devices whose motion currently rides the detection session-decode worker
+	* (P4 co-active sharing) instead of a dedicated motion worker. Membership →
+	* the detection pump also enqueues a derived gray motion frame per decoded
+	* rgb (see `enqueueSharedDetectionFrame`). A pure flag-set: `enqueueMotionFrame`
+	* is device-scoped, so no per-device callback object is needed.
+	*/
+	sharedMotionSinks = /* @__PURE__ */ new Set();
+	/**
 	* Snapshot-equality cache for metrics-snapshot defer. The runner
 	* fires per-camera metrics every `METRICS_SNAPSHOT_INTERVAL_MS`;
 	* for an idle camera (no inference, queue empty, fps=0) every tick
@@ -1532,7 +2145,25 @@ var PipelineRunnerAddon = class extends require_dist.BaseAddon {
 	*/
 	benchFrameCache = /* @__PURE__ */ new Map();
 	benchFrameSweeper = null;
+	/** Per-camera single-flight: a camera never runs two occupancy bursts at once. */
 	occupancyBurstInFlight = /* @__PURE__ */ new Set();
+	/**
+	* GLOBAL occupancy admission queue. Each occupancy burst SUBSCRIBES a detection
+	* stream (rgb) which, during the `watching` phase, has no existing consumer and
+	* therefore makes the broker DIAL a fresh decoder. Without a global cap, N
+	* cameras rechecking on the same interval would spawn N parallel decoder dials
+	* (thundering herd → re-dial churn → latency). This bounds concurrent bursts to
+	* OCCUPANCY_MAX_CONCURRENT; the rest wait in the queue and drain as slots free.
+	* (A burst on an already-`active` camera reuses the live decoder — the broker's
+	* demand-gate shares one session across subscribers — so only watching-phase
+	* spawns pay the dial cost.)
+	*/
+	occupancyQueue = [];
+	occupancyQueued = /* @__PURE__ */ new Set();
+	occupancyFrames = /* @__PURE__ */ new Map();
+	occupancyActiveCount = 0;
+	/** Max concurrent occupancy bursts (decoder dials) across all cameras. */
+	occupancyMaxConcurrent = 3;
 	constructor() {
 		super({ ...DEFAULT_CONFIG });
 	}
@@ -1549,9 +2180,10 @@ var PipelineRunnerAddon = class extends require_dist.BaseAddon {
 			onPhaseChanged: (deviceId, phase, meta) => this.handlePhaseChanged(deviceId, phase, meta),
 			logger: this.ctx.logger,
 			onOccupancyRecheck: (deviceId, frames) => {
-				this.runOccupancyBurst(deviceId, frames);
+				this.enqueueOccupancyBurst(deviceId, frames);
 			}
 		});
+		this.spawnGate = new Semaphore(Math.max(1, this.config.maxConcurrentDecodeSpawns));
 		this.runner.timingSampler.setLogger(this.ctx.logger.child("timing"));
 		this.runner.onDetectionStreamChange((deviceId, action) => {
 			this.handleDetectionStreamChange(deviceId, action);
@@ -1970,6 +2602,7 @@ var PipelineRunnerAddon = class extends require_dist.BaseAddon {
 			detectionMode: config.detectionMode,
 			fps: config.detectionFps,
 			motionCooldownMs: config.motionCooldownMs,
+			occupancyRecheckEnabled: config.occupancyRecheckEnabled,
 			occupancyRecheckSec: config.occupancyRecheckSec,
 			occupancyRecheckFrames: config.occupancyRecheckFrames
 		});
@@ -2190,6 +2823,196 @@ var PipelineRunnerAddon = class extends require_dist.BaseAddon {
 		return plane;
 	}
 	/**
+	* Acquire the broker's COMPRESSED passthrough restream for one camStream and
+	* wrap it as a {@link VideoFrameSource} the decode worker can dial. Mirrors
+	* {@link RemoteSourcePlane}'s acquire: resolve the profile the camStream
+	* feeds, then `getStreamWithCodec({ video: 'copy' })` (refcounted — rides the
+	* broker's single source pull, never a second camera dial). No `hostname`:
+	* the P1 flagged camera is HUB-LOCAL, so the returned `127.0.0.1` URL is
+	* dialable from this hub-resident runner. Returns `null` (loudly logged) when
+	* no profile is bound yet — the caller opens no subscription.
+	*/
+	async acquireSessionDecodeRestream(api, deviceId, streamId, tag, hostname) {
+		const profile = profileForStreamId(await api.streamBroker.listAllProfileSlots.query(), deviceId, streamId);
+		if (profile === null) {
+			this.ctx.logger.error("session-decode: no broker profile feeds camStream — cannot acquire restream", {
+				tags: { deviceId },
+				meta: { streamId }
+			});
+			return null;
+		}
+		const rtpSource = await api.streamBroker.getStreamWithCodec.mutate({
+			deviceId,
+			video: "copy",
+			audio: "none",
+			profile,
+			tag,
+			...hostname !== void 0 ? { hostname } : {}
+		});
+		const codec = rtpSource.videoCodec === "H265" ? "h265" : "h264";
+		const source = {
+			restreamUrl: rtpSource.url,
+			deviceId,
+			codec
+		};
+		const pipelineKey = rtpSource.pipelineKey;
+		let released = false;
+		const release = async () => {
+			if (released) return;
+			released = true;
+			await api.streamBroker.releaseStreamWithCodec.mutate({ pipelineKey }).catch((err) => {
+				this.ctx.logger.debug("session-decode: releaseStreamWithCodec failed (benign on hub restart)", {
+					tags: { deviceId },
+					meta: {
+						pipelineKey,
+						error: require_dist.errMsg(err)
+					}
+				});
+			});
+		};
+		return {
+			source,
+			release
+		};
+	}
+	/**
+	* Register this device's motion to ride the detection session-decode worker
+	* (P4 co-active sharing) instead of forking a dedicated motion worker. While
+	* registered, the detection pump enqueues a derived gray motion frame per
+	* decoded rgb. Returns an idempotent teardown that unregisters it; forks
+	* nothing and holds no restream (the detection subscription owns the worker).
+	*/
+	registerSharedMotionSink(deviceId) {
+		this.sharedMotionSinks.add(deviceId);
+		this.ctxIfReady?.logger.info("session-decode: motion rides the detection worker (shared — no 2nd fork)", { tags: { deviceId } });
+		let released = false;
+		return () => {
+			if (released) return;
+			released = true;
+			this.sharedMotionSinks.delete(deviceId);
+		};
+	}
+	/**
+	* Fan a decoded detection rgb frame out to the detection queue, and — when
+	* this device's motion is riding the detection worker (P4 sharing) — also to
+	* the motion queue as a derived gray frame (`rgbFrameToGrayFrame`, luma only:
+	* no second dial, no second decode, no GPU). Mirrors the shm shared-motion
+	* seam (`subscribeMotionFrames` `shared` branch).
+	*/
+	enqueueSharedDetectionFrame(deviceId, frame) {
+		const runner = this.runner;
+		if (!runner) return;
+		runner.enqueueDetectionFrame(deviceId, frame, void 0);
+		if (this.sharedMotionSinks.has(deviceId)) runner.enqueueMotionFrame(deviceId, rgbFrameToGrayFrame(frame), void 0);
+	}
+	/**
+	* Epic C P1 detection path for a flagged camera: decode `rgb` in a
+	* per-session forked worker and feed the runner's detection queue INLINE (no
+	* `FrameHandle`), exactly like the shared shm path. Teardown stops the pump
+	* (→ worker `stop` + `kill` + SIGKILL fallback → reclaim) and releases the
+	* restream refcount.
+	*
+	* Returns the teardown SYNCHRONOUSLY (Epic C P2 I3): the restream acquire +
+	* pump-start run in the background via {@link startGuardedSessionDecode},
+	* so a detach that lands while the acquire is still in flight releases the
+	* restream immediately and never forks the decode worker — no orphan
+	* worker, no leaked refcount.
+	*/
+	/**
+	* Build the spawn-gate acquire the pump calls before forking a decode
+	* worker (P5). Logs DEFERRAL (gate saturated → this fork queues) and the
+	* subsequent proceed — no silent capping. Returns a no-op acquire when the
+	* gate is not yet initialised (pre-`onInitialize`), so the pump is never
+	* blocked by a missing gate. `label` distinguishes detect vs motion forks in
+	* the logs; the device id is already tagged on `log`.
+	*/
+	buildDecodeSpawnAcquire(log, label) {
+		return async () => {
+			const gate = this.spawnGate;
+			if (!gate) return () => {};
+			const wasDeferred = gate.available <= 0;
+			if (wasDeferred) log.info("session-decode: decode-worker spawn DEFERRED — spawn gate saturated, queuing", { meta: {
+				label,
+				cap: gate.concurrency,
+				inFlight: gate.concurrency - gate.available
+			} });
+			const release = await gate.acquire();
+			if (wasDeferred) log.info("session-decode: deferred decode-worker spawn now proceeding", { meta: { label } });
+			else log.debug("session-decode: decode-worker spawn slot acquired", { meta: {
+				label,
+				remaining: gate.available
+			} });
+			return release;
+		};
+	}
+	startDetectionSessionDecode(config, api) {
+		const runner = this.runner;
+		const log = this.ctx.logger.withTags({ deviceId: config.deviceId });
+		if (!runner) return () => {};
+		return startGuardedSessionDecode({
+			logger: log,
+			acquire: () => this.acquireSessionDecodeRestream(api, config.deviceId, config.detectionStreamId, `session-decode:detect:${config.deviceId}`, resolveSessionDecodeHostname(config, process.env["CAMSTACK_HUB_URL"])),
+			startPump: (source) => {
+				log.info("session-decode: detection routed through per-session decode worker (rgb)", { meta: {
+					streamId: config.detectionStreamId,
+					codec: source.codec
+				} });
+				return startSessionDecodePump({
+					fork: forkDecodeWorker,
+					logger: log,
+					source,
+					opts: {
+						fps: config.detectionFps,
+						format: "rgb"
+					},
+					acquireSpawnSlot: this.buildDecodeSpawnAcquire(log, "detect"),
+					onDecodedFrame: (frame) => {
+						this.enqueueSharedDetectionFrame(config.deviceId, frame);
+					}
+				});
+			}
+		});
+	}
+	/**
+	* Epic C P1 motion path for a flagged camera: a dedicated `gray` decode of
+	* the SUB stream in its OWN per-session forked worker (independent of the
+	* detection worker — two workers per flagged camera in P1; sharing one is a
+	* P2 follow-up). Feeds the motion queue INLINE (no handle). Teardown stops
+	* the pump and releases the restream refcount.
+	*
+	* Returns the teardown SYNCHRONOUSLY (Epic C P2 I3) — same
+	* {@link startGuardedSessionDecode} guard as detection: a detach during the
+	* in-flight acquire releases immediately and skips the pump/worker fork.
+	*/
+	startMotionSessionDecode(config, api) {
+		const runner = this.runner;
+		const log = this.ctx.logger.withTags({ deviceId: config.deviceId });
+		if (!runner) return () => {};
+		return startGuardedSessionDecode({
+			logger: log,
+			acquire: () => this.acquireSessionDecodeRestream(api, config.deviceId, config.motionStreamId, `session-decode:motion:${config.deviceId}`, resolveSessionDecodeHostname(config, process.env["CAMSTACK_HUB_URL"])),
+			startPump: (source) => {
+				log.info("session-decode: motion routed through per-session decode worker (gray)", { meta: {
+					streamId: config.motionStreamId,
+					codec: source.codec
+				} });
+				return startSessionDecodePump({
+					fork: forkDecodeWorker,
+					logger: log,
+					source,
+					opts: {
+						fps: config.motionFps,
+						format: "gray"
+					},
+					acquireSpawnSlot: this.buildDecodeSpawnAcquire(log, "motion"),
+					onDecodedFrame: (frame) => {
+						runner.enqueueMotionFrame(config.deviceId, frame, void 0);
+					}
+				});
+			}
+		});
+	}
+	/**
 	* Subscribe the motion analyzer to decoded frames.
 	*
 	* Two modes:
@@ -2213,6 +3036,10 @@ var PipelineRunnerAddon = class extends require_dist.BaseAddon {
 			log.warn("subscribeMotionFrames: this.ctx.api not available");
 			return null;
 		}
+		if (shouldUseSessionDecode(this.config.useSessionDecode)) {
+			if (resolveMotionFrameSource(config, opts?.sharedWithDetection === true).shared) return this.registerSharedMotionSink(config.deviceId);
+			return this.startMotionSessionDecode(config, api);
+		}
 		const src = resolveMotionFrameSource(config, opts?.sharedWithDetection === true);
 		const shared = src.shared;
 		const streamId = src.streamId;
@@ -2305,6 +3132,7 @@ var PipelineRunnerAddon = class extends require_dist.BaseAddon {
 			log.warn("subscribeDetectionFrames: this.ctx.api not available");
 			return null;
 		}
+		if (shouldUseSessionDecode(this.config.useSessionDecode)) return this.startDetectionSessionDecode(config, api);
 		const remote = this.remoteSourceFor(config);
 		return startFrameHandlePoller({
 			api,
@@ -2440,6 +3268,35 @@ var PipelineRunnerAddon = class extends require_dist.BaseAddon {
 			log.error("runMotionAnalysis failed", { meta: { error: msg } });
 		}
 	}
+	/**
+	* Admit an occupancy recheck into the global queue. Deduped per camera (one
+	* already queued or bursting is ignored; its latest frame-count wins) so a
+	* fast recheck cadence can't stack requests. Draining is bounded by
+	* `occupancyMaxConcurrent` so 25 cameras rechecking together don't spawn 25
+	* parallel decoder dials.
+	*/
+	enqueueOccupancyBurst(deviceId, frames) {
+		this.occupancyFrames.set(deviceId, frames);
+		if (this.occupancyBurstInFlight.has(deviceId) || this.occupancyQueued.has(deviceId)) return;
+		this.occupancyQueued.add(deviceId);
+		this.occupancyQueue.push(deviceId);
+		this.drainOccupancyQueue();
+	}
+	/** Start queued occupancy bursts up to the global concurrency cap. */
+	drainOccupancyQueue() {
+		while (this.occupancyActiveCount < this.occupancyMaxConcurrent && this.occupancyQueue.length > 0) {
+			const deviceId = this.occupancyQueue.shift();
+			if (deviceId === void 0) break;
+			this.occupancyQueued.delete(deviceId);
+			const frames = this.occupancyFrames.get(deviceId) ?? 4;
+			this.occupancyFrames.delete(deviceId);
+			this.occupancyActiveCount++;
+			this.runOccupancyBurst(deviceId, frames).finally(() => {
+				this.occupancyActiveCount--;
+				this.drainOccupancyQueue();
+			});
+		}
+	}
 	async runOccupancyBurst(deviceId, frames) {
 		if (this.occupancyBurstInFlight.has(deviceId)) return;
 		const attachment = this.attached.get(deviceId);
@@ -2635,21 +3492,44 @@ var PipelineRunnerAddon = class extends require_dist.BaseAddon {
 					step: 1,
 					default: DEFAULT_CONFIG.minThrottledFps,
 					showValue: true
+				},
+				{
+					type: "boolean",
+					key: "useSessionDecode",
+					style: "checkbox",
+					label: "Use per-session decode workers",
+					description: "Default decode path for every camera on this runner/node: each attached camera decodes in a disposable per-session worker process instead of the shared shm frame-handle poller, freeing the VAAPI/GPU decode pool (and any /dev/shm ring segments) as soon as it goes idle. Uncheck to fall this node back to the shared shm frame-handle poller for ALL its cameras — no per-camera override.",
+					default: DEFAULT_CONFIG.useSessionDecode
+				},
+				{
+					type: "slider",
+					key: "maxConcurrentDecodeSpawns",
+					label: "Max concurrent decode-worker spawns",
+					description: "Min floor of per-session decode-worker forks allowed to spin up CONCURRENTLY on this node. A synchronized multi-camera motion burst forks at most this many decode workers at once; the rest queue (FIFO) until an in-flight worker delivers its first frame or tears down. Keeps a burst from stampeding the shared GPU. Set >= your camera count to effectively disable the gate. Only applies when per-session decode workers are enabled.",
+					min: 1,
+					max: 16,
+					step: 1,
+					default: DEFAULT_CONFIG.maxConcurrentDecodeSpawns,
+					showValue: true
 				}
 			]
 		}] });
 	}
 	async onConfigChanged() {
 		this.runner?.updateLimits(this.config);
+		this.spawnGate?.resize(Math.max(1, this.config.maxConcurrentDecodeSpawns));
 		this.ctx.logger.info("pipeline-runner tuning updated", { meta: {
 			maxQueueDepth: this.config.maxQueueDepth,
 			maxConcurrentInferences: this.config.maxConcurrentInferences,
 			targetLoadPercent: this.config.targetLoadPercent,
-			minThrottledFps: this.config.minThrottledFps
+			minThrottledFps: this.config.minThrottledFps,
+			useSessionDecode: this.config.useSessionDecode,
+			maxConcurrentDecodeSpawns: this.config.maxConcurrentDecodeSpawns
 		} });
 	}
 };
 //#endregion
+exports.DEFAULT_CONFIG = DEFAULT_CONFIG;
 exports.FrameQueue = FrameQueue;
 exports.PipelineRunner = PipelineRunner;
 exports.PipelineTimingSampler = PipelineTimingSampler;
@@ -2657,5 +3537,6 @@ exports.Semaphore = Semaphore;
 exports.customActions = pipelineRunnerBenchActions;
 exports.default = PipelineRunnerAddon;
 exports.resolveMotionFrameSource = resolveMotionFrameSource;
+exports.resolveSessionDecodeHostname = resolveSessionDecodeHostname;
 exports.rgbFrameToGrayFrame = rgbFrameToGrayFrame;
 exports.shouldStartOnboardAnalyzer = shouldStartOnboardAnalyzer;