@camstack/addon-pipeline 1.1.55 → 1.1.57

package/dist/pipeline-runner/index.mjs

@@ -1,12 +1,11 @@
-import { $ as boolean, D as nodePin, H as createEvent, I as errMsg, K as makeSourceBrokerId, L as BaseAddon, Q as array, V as EventCategory, Z as _enum, _ as customAction, it as object, k as pipelineRunnerCapability, ot as string, rt as number, tt as lazy, y as defineCustomActions } from "../dist-RWGGPwVx.mjs";
-import { n as isRemoteRestream, r as profileForStreamId, t as RemoteSourcePlane } from "../remote-source-plane-DU0aRSPv.mjs";
+import { $ as boolean, D as nodePin, H as createEvent, I as errMsg, L as BaseAddon, Q as array, V as EventCategory, Z as _enum, _ as customAction, it as object, k as pipelineRunnerCapability, ot as string, rt as number, tt as lazy, y as defineCustomActions } from "../dist-CL531uVA.mjs";
+import { n as profileForStreamId, t as isRemoteRestream } from "../remote-restream-BeHi78PZ.mjs";
 import { t as resolveHubHostname } from "../hub-hostname-cCknRYKj.mjs";
 import { t as isWorkerReply } from "../worker-protocol-CyVJTZEO.mjs";
-import { a as getStepDefinition } from "../step-definitions-CP9kVSml.mjs";
-import { DecoderFrameRingSink, FrameRingReaderCache, unlinkSegment } from "@camstack/shm-ring";
+import { a as getStepDefinition } from "../step-definitions-1d3_vQ6S.mjs";
 import { fork } from "node:child_process";
 import { fileURLToPath } from "node:url";
-import { readdirSync } from "node:fs";
+import sharp from "sharp";
 //#region src/pipeline-runner/bench-actions.ts
 /**
 * Synthetic-bench custom actions for pipeline-runner.
@@ -101,329 +100,6 @@ var pipelineRunnerBenchActions = defineCustomActions({
 	runSyntheticBench: customAction(RunSyntheticBenchInputSchema, RunSyntheticBenchResultSchema, { kind: "mutation" })
 });
 //#endregion
-//#region src/pipeline-runner/foreign-handle-throttle.ts
-var ForeignHandleThrottle = class {
-	minFetchIntervalMs;
-	warnIntervalMs;
-	lastFetchStartedAt = Number.NEGATIVE_INFINITY;
-	inFlight = false;
-	lastWarnAt;
-	_foreignHandles = 0;
-	_remoteFetches = 0;
-	_remoteFailures = 0;
-	_dropped = 0;
-	constructor(options = {}) {
-		const maxRemoteFps = options.maxRemoteFps ?? 1;
-		this.minFetchIntervalMs = maxRemoteFps > 0 ? 1e3 / maxRemoteFps : Number.POSITIVE_INFINITY;
-		this.warnIntervalMs = options.warnIntervalMs ?? 6e4;
-	}
-	/**
-	* Decide whether the current foreign handle should trigger a remote fetch.
-	* `'fetch'` only when no fetch is in flight AND at least `1000/maxRemoteFps`
-	* ms have elapsed since the last fetch started; otherwise `'drop'`.
-	*/
-	plan(now) {
-		this._foreignHandles += 1;
-		const rateOpen = now - this.lastFetchStartedAt >= this.minFetchIntervalMs;
-		if (this.inFlight || !rateOpen) {
-			this._dropped += 1;
-			return "drop";
-		}
-		return "fetch";
-	}
-	/** Mark a remote fetch as begun (arms single-flight + the rate window). */
-	noteFetchStart(now) {
-		this.inFlight = true;
-		this.lastFetchStartedAt = now;
-		this._remoteFetches += 1;
-	}
-	/** Mark the in-flight remote fetch as finished; records a failure outcome. */
-	noteFetchEnd(result = "ok") {
-		this.inFlight = false;
-		if (result === "failed") this._remoteFailures += 1;
-	}
-	/** `true` at most once per `warnIntervalMs`; stamps the window when it fires. */
-	shouldWarn(now) {
-		if (this.lastWarnAt !== void 0 && now - this.lastWarnAt < this.warnIntervalMs) return false;
-		this.lastWarnAt = now;
-		return true;
-	}
-	get counters() {
-		return {
-			foreignHandles: this._foreignHandles,
-			remoteFetches: this._remoteFetches,
-			remoteFailures: this._remoteFailures,
-			dropped: this._dropped
-		};
-	}
-};
-//#endregion
-//#region src/pipeline-runner/resolve-polled-frame.ts
-async function resolvePolledFrame(handle, deps) {
-	const { ownNodeId, readers, throttle, getRemoteFrame, logger, tag } = deps;
-	if (handle.nodeId === ownNodeId) return readers.read(handle);
-	const now = Date.now();
-	const decision = throttle.plan(now);
-	if (throttle.shouldWarn(now)) logger.warn("frame poller: foreign handle — decoder session is on another node; using bounded decoder.getFrame fallback", { meta: {
-		tag,
-		producerNode: handle.nodeId,
-		ownNodeId,
-		...throttle.counters
-	} });
-	if (decision === "drop") return null;
-	throttle.noteFetchStart(now);
-	try {
-		const remote = await getRemoteFrame(handle);
-		throttle.noteFetchEnd("ok");
-		return remote;
-	} catch (err) {
-		throttle.noteFetchEnd("failed");
-		logger.debug("frame poller: remote getFrame failed", { meta: {
-			tag,
-			producerNode: handle.nodeId,
-			error: errMsg(err)
-		} });
-		return null;
-	}
-}
-//#endregion
-//#region src/pipeline-runner/frame-handle-poller.ts
-/**
-* `FrameHandlePoller` — the consumer-side poll loop of the shared-memory frame
-* plane (Phase 5 / D9).
-*
-* Replaces the live-object `IStreamBroker.onDecodedFrame(cb)` callback path.
-* A consumer (motion, detection):
-*
-*   1. `subscribeFrames({ brokerId, format, maxFps, tag })` over tRPC — the
-*      broker spins up a `frameSink: 'shm'` decoder session for that format
-*      and returns a `subscriptionId`;
-*   2. polls `pullFrameHandles({ subscriptionId, maxCount })` at the cadence
-*      `maxFps` implies, draining zero-pixel `FrameHandle`s;
-*   3. feeds each handle to a `FrameRingReaderCache` which opens the named shm
-*      segment and reads the pixels back zero-copy;
-*   4. on teardown, `unsubscribeFrames` + closes the cached readers.
-*
-* The loop tolerates an initially-empty stream — `pullFrameHandles` returns
-* `[]` until the broker has a source, and a recycled ring slot yields a `null`
-* pixel read (a dropped frame, the correct latest-wins behaviour).
-*
-* Foreign-handle path: a `FrameHandle` carries the `nodeId` of the node whose
-* shared memory holds its segment. A LOCAL handle is read back zero-copy; a
-* FOREIGN handle (produced on another node — e.g. a camera decoded on the hub
-* whose detection was placed on an agent) cannot be `shm_open`ed here. Reading
-* it unconditionally floods `openSegment failed shm_open ENOENT` at frame rate,
-* so the poll delegates every handle to `resolvePolledFrame`, which gates on
-* `handle.nodeId`: local → shm read; foreign → a BOUNDED, single-flight
-* `getRemoteFrame` (`decoder.getFrame`) fallback (≤ `maxRemoteFps`) plus a
-* rate-limited WARN naming the topology mismatch. `ownNodeId` + `getRemoteFrame`
-* are REQUIRED options — every in-repo call site supplies them, so there is no
-* silent default that re-creates the unconditional read.
-*
-* Boot-race tolerance: the broker for a given camStream may not be registered
-* yet when a consumer attempts to subscribe (the pipeline-runner spawns before
-* provider addons publish their cameraStreams). `subscribeFrames` retries with
-* exponential backoff (capped at `MAX_SUBSCRIBE_RETRY_BACKOFF_MS`) until it
-* succeeds or the returned teardown closure is invoked. The closure always
-* resolves to a function, even when the broker is missing; the function
-* cancels pending retries and releases any subscription acquired in flight.
-*/
-/** How many handles to drain per poll — a small burst absorbs jitter. */
-var PULL_MAX_COUNT = 4;
-/** Floor on the poll period so a 0/absurd `maxFps` can't busy-spin. */
-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;
-/**
-* Subscribe-retry backoff ceiling. 5 s is fast enough to recover within a
-* single roster refresh of the consuming UI and slow enough that a
-* misconfigured camStream costs ~12 op/min, not 50/s.
-*/
-var MAX_SUBSCRIBE_RETRY_BACKOFF_MS = 5e3;
-/**
-* The default source: the broker's shm plane over tRPC — today's path. The
-* methods return the underlying client promises DIRECTLY (no async wrapper)
-* so the poller's scheduling is microtask-identical to the pre-seam code.
-*/
-function brokerFrameHandleSource(api, brokerId) {
-	return {
-		subscribe: (input) => api.streamBroker.subscribeFrames.mutate({
-			brokerId,
-			format: input.format,
-			maxFps: input.maxFps,
-			tag: input.tag
-		}),
-		pullHandles: (input) => api.streamBroker.pullFrameHandles.query({
-			subscriptionId: input.subscriptionId,
-			maxCount: input.maxCount
-		}),
-		unsubscribe: (input) => api.streamBroker.unsubscribeFrames.mutate({ subscriptionId: input.subscriptionId }).then(() => void 0)
-	};
-}
-/**
-* Subscribe to a broker's shm frame stream and start the poll loop. Always
-* resolves to a teardown closure — when the broker is not yet registered the
-* closure cancels the ongoing retry loop; when polling is active it stops the
-* loop, releases the broker subscription, and closes every shm segment the
-* reader cache opened.
-*/
-async function startFrameHandlePoller(options) {
-	const lifecycle = {
-		stopped: false,
-		retryTimer: void 0,
-		activeTeardown: null
-	};
-	const teardown = () => {
-		if (lifecycle.stopped) return;
-		lifecycle.stopped = true;
-		if (lifecycle.retryTimer) {
-			clearTimeout(lifecycle.retryTimer);
-			lifecycle.retryTimer = void 0;
-		}
-		lifecycle.activeTeardown?.();
-	};
-	subscribeWithRetry(options, lifecycle);
-	return teardown;
-}
-/**
-* Run the subscribe → poll handshake with exponential backoff on subscribe
-* failures. Resolves once the subscription is acquired (and the poll loop has
-* been started) or once `lifecycle.stopped` flips, whichever comes first.
-*/
-async function subscribeWithRetry(options, lifecycle) {
-	const { api, brokerId, format, maxFps, tag, logger } = options;
-	const source = options.source ?? brokerFrameHandleSource(api, brokerId);
-	let backoffMs = INITIAL_SUBSCRIBE_RETRY_BACKOFF_MS;
-	let attempt = 0;
-	while (!lifecycle.stopped) {
-		attempt += 1;
-		try {
-			const result = await source.subscribe({
-				format,
-				maxFps,
-				tag
-			});
-			if (lifecycle.stopped) {
-				await source.unsubscribe({ subscriptionId: result.subscriptionId }).catch((err) => {
-					logger.warn("frame-handle poller: late unsubscribe failed", { meta: {
-						brokerId,
-						subscriptionId: result.subscriptionId,
-						error: errMsg(err)
-					} });
-				});
-				return;
-			}
-			lifecycle.activeTeardown = startPolling(options, source, result.subscriptionId, result.maxFps, lifecycle);
-			return;
-		} catch (err) {
-			if (lifecycle.stopped) return;
-			if (attempt === 1) logger.warn("frame-handle poller: subscribeFrames failed, retrying", { meta: {
-				brokerId,
-				format,
-				tag,
-				error: errMsg(err),
-				nextRetryInMs: backoffMs
-			} });
-			else logger.debug("frame-handle poller: subscribeFrames still failing", { meta: {
-				brokerId,
-				format,
-				tag,
-				attempt,
-				error: errMsg(err),
-				nextRetryInMs: backoffMs
-			} });
-			await sleep(backoffMs, lifecycle);
-			backoffMs = Math.min(MAX_SUBSCRIBE_RETRY_BACKOFF_MS, backoffMs * 2);
-		}
-	}
-}
-/**
-* Sleep `ms` milliseconds, but resolve early when `lifecycle.stopped` flips so
-* a teardown during a retry pause doesn't have to wait out the full backoff.
-*/
-function sleep(ms, lifecycle) {
-	return new Promise((resolve) => {
-		lifecycle.retryTimer = setTimeout(() => {
-			lifecycle.retryTimer = void 0;
-			resolve();
-		}, ms);
-	});
-}
-/**
-* Run the steady-state poll loop for a successfully-acquired subscription.
-* Returns the teardown closure that stops the loop and releases the
-* subscription.
-*/
-function startPolling(options, source, subscriptionId, resolvedMaxFps, lifecycle) {
-	const { brokerId, onFrame, logger, ownNodeId, getRemoteFrame, tag } = options;
-	const readers = new FrameRingReaderCache(logger);
-	const throttle = new ForeignHandleThrottle();
-	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;
-		try {
-			const handles = await source.pullHandles({
-				subscriptionId,
-				maxCount: PULL_MAX_COUNT
-			});
-			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,
-					throttle,
-					getRemoteFrame,
-					logger,
-					tag
-				});
-				if (frame) {
-					onFrame(frame, handle);
-					break;
-				}
-			}
-		} catch (err) {
-			logger.warn("frame-handle poller: pullFrameHandles failed", { meta: {
-				brokerId,
-				subscriptionId,
-				error: errMsg(err)
-			} });
-		}
-		if (!lifecycle.stopped) timer = setTimeout(() => void tick(), pollIntervalMs);
-	};
-	tick();
-	return () => {
-		if (timer) {
-			clearTimeout(timer);
-			timer = void 0;
-		}
-		readers.close();
-		source.unsubscribe({ subscriptionId }).catch((err) => {
-			logger.warn("frame-handle poller: unsubscribe failed", { meta: {
-				brokerId,
-				subscriptionId,
-				error: errMsg(err)
-			} });
-		});
-	};
-}
-//#endregion
 //#region src/pipeline-runner/frame-governor.ts
 var FrameGovernor = class {
 	config;
@@ -1391,8 +1067,13 @@ function wrapChild(child) {
 			child.send(msg, () => void 0);
 		},
 		on: (ev, cb) => {
-			if (ev === "exit") child.on("exit", () => cb(void 0));
-			else child.on("message", (m) => cb(m));
+			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));
 		},
 		kill: (signal) => {
 			if (signal === void 0) {
@@ -1455,137 +1136,141 @@ function startGuardedSessionDecode(deps) {
 		if (release) release();
 	};
 }
-//#endregion
-//#region src/session-decode/retention-sink.ts
-/**
-* Session-decode frame retention ring (Shape-2, Slice 1).
-*
-* The default detection path is **session-decode** (`useSessionDecode` true):
-* a per-session forked decode worker hands the runner decoded rgb pixels over
-* IPC — the frames never touch shared memory, so the emitted
-* `PipelineInferenceResult` carried NO `FrameHandle`, and hub-side post-analysis
-* (which gates ALL event/face/track crop media on a present handle) produced no
-* media. This ring restores that: every decoded detection frame is copied into
-* a short shared-memory retention ring on the runner's node, and the resulting
-* `FrameHandle` rides the inference-result event so post-analysis can resolve
-* the exact frame zero-copy and cut crops from it.
-*
-* ## Why a distinct prefix (`csr.`)
-*
-* The decoder addon runs `purgeOrphanSegments('csf.')` at startup and unlinks
-* EVERY `csf.*` segment on the node. A retention ring under the `csf.` prefix
-* would be reclaimed out from under a live session on every decoder redeploy.
-* The retention ring therefore uses its own prefix `csr.` and its own startup
-* orphan purge (`shm-retention-purge.ts`).
-*
-* ## Sizing
-*
-* Retention is ring depth: `slots ≈ detectionFps × retainSeconds`. At the
-* Slice-1 ≤640-wide detection geometry a slot is ~0.69 MB, so the 32 MB default
-* budget yields ~46 latest-wins slots (~4.6 s @10 fps). Budget is per active
-* session; the sink is armed lazily on the first rgb frame and destroyed on
-* session teardown, so idle cameras hold no shared memory.
-*/
-/** Segment name prefix for session-decode retention rings — isolated from the
-* decoder's `csf.` orphan purge so a decoder redeploy never reclaims a live
-* retention ring. */
-var RETENTION_SEGMENT_PREFIX = "csr.";
-/** {@link RETAIN_BUDGET_MB} in bytes. */
-var RETAIN_BUDGET_BYTES = (() => {
+/** {@link RETAINED_FRAME_BUDGET_MB} in bytes. */
+var RETAINED_FRAME_BUDGET_BYTES = (() => {
 	const raw = Number(process.env["CAMSTACK_SESSION_RETAIN_MB"]);
 	return Number.isFinite(raw) && raw > 0 ? Math.floor(raw) : 32;
 })() * 1024 * 1024;
-/**
-* Create a session-decode retention ring for one device. The underlying
-* shared-memory segment is created lazily on the first rgb frame.
-*/
-function createSessionRetentionSink(options) {
-	const { deviceId, nodeId, logger } = options;
-	const sink = new DecoderFrameRingSink({
-		seed: `retain:${deviceId}`,
-		logger,
-		nodeId,
-		segmentPrefix: RETENTION_SEGMENT_PREFIX,
-		budgetBytes: RETAIN_BUDGET_BYTES
-	});
-	return {
-		write(frame) {
-			if (frame.format !== "rgb") return null;
-			return sink.writeFrame(frame.data, {
-				width: frame.width,
-				height: frame.height,
-				format: frame.format,
-				pts: performance.now(),
-				byteLength: frame.data.byteLength
-			});
-		},
-		destroy() {
-			sink.destroy();
-		},
-		get currentSegmentName() {
-			return sink.currentSegmentName;
-		}
-	};
+/** Opaque RAM-key prefix stamped into a retained frame's `FrameHandle.shmId`. */
+var RETAINED_FRAME_KEY_PREFIX = "ram:";
+/** A retention frame is uniquely identified by its key + slot + committed seq. */
+function keyOf(handle) {
+	return `${handle.shmId}#${handle.slot}#${handle.seq}`;
 }
-//#endregion
-//#region src/pipeline-runner/shm-retention-purge.ts
 /**
-* Startup reclamation of orphaned session-decode retention segments.
-*
-* The retention ring (`retention-sink.ts`) writes decoded detection frames into
-* named `/dev/shm` segments under the `csr.` prefix and unlinks each on graceful
-* session teardown. When the runner process dies ungracefully (SIGBUS, OOM-kill,
-* SIGKILL during redeploy) that teardown never runs and the segment is orphaned.
-* Across crashes/redeploys these accumulate until `/dev/shm` fills, at which
-* point the next `mmap` write faults with an uncatchable SIGBUS.
-*
-* This is the retention-ring analogue of the decoder addon's
-* `purgeOrphanSegments('csf.')`: a fresh pipeline-runner owns no live sessions,
-* so every pre-existing `csr.*` segment is by definition an orphan from a dead
-* instance. It MUST use the `csr.` prefix (never `csf.`): the decoder purge owns
-* `csf.` and unlinking a live retention ring would break media mid-session.
-*
-* `shm_unlink` only removes the name — a consumer still holding a mapping keeps
-* reading valid memory until it closes (POSIX deferred reclaim + the ring
-* seqlock), so unlinking is safe even if a stale reader is momentarily attached.
-*
-* POSIX-only: segments surface as files under `/dev/shm` on Linux. On platforms
-* without that directory (Windows, macOS) the scan finds nothing — no-op.
-*/
-/** Default tmpfs directory where POSIX shared-memory segments appear on Linux. */
-var DEFAULT_SHM_DIR = "/dev/shm";
-/**
-* Unlink every session-decode retention segment whose name starts with
-* `prefix`. Intended to run ONCE at pipeline-runner startup, before any session
-* is created, to reclaim segments orphaned by a previously-crashed instance. A
-* per-file unlink failure is swallowed so one stuck segment cannot block
-* reclaiming the rest.
+* Node-level RAM store of retained rgb detection frames, keyed by
+* `FrameHandle` identity. Latest-wins with a byte budget.
 */
-function purgeOrphanSegments(prefix, options = {}) {
-	const dir = options.dir ?? DEFAULT_SHM_DIR;
-	const unlink = options.unlink ?? unlinkSegment;
-	let entries;
-	try {
-		entries = readdirSync(dir);
-	} catch {
-		return {
-			scanned: 0,
-			removed: 0,
-			names: []
+var RetainedFrameStore = class RetainedFrameStore {
+	nodeId;
+	budgetBytes;
+	/** Insertion-ordered (Map) → oldest is `keys().next()`. */
+	entries = /* @__PURE__ */ new Map();
+	bytes = 0;
+	seq = 0;
+	/** Ring width used only to spread the `slot` field; the map key is authoritative. */
+	static SLOT_SPREAD = 1024;
+	constructor(options) {
+		this.nodeId = options.nodeId;
+		this.budgetBytes = options.budgetBytes ?? RETAINED_FRAME_BUDGET_BYTES;
+	}
+	/** Number of retained frames (tests / metrics). */
+	get size() {
+		return this.entries.size;
+	}
+	/** Total retained bytes (tests / metrics). */
+	get retainedBytes() {
+		return this.bytes;
+	}
+	/**
+	* Retain one decoded rgb frame and return its `FrameHandle`. Returns `null`
+	* for a non-rgb frame (motion gray is never retained — post-analysis crops
+	* from the rgb frame). The frame buffer is retained by reference: the
+	* decode-worker IPC delivers a fresh Buffer per frame, so no defensive copy
+	* is needed.
+	*/
+	write(deviceId, frame) {
+		if (frame.format !== "rgb") return null;
+		const seq = ++this.seq;
+		const byteLength = frame.data.byteLength;
+		const handle = {
+			shmId: `${RETAINED_FRAME_KEY_PREFIX}${this.nodeId}:${deviceId}`,
+			slot: seq % RetainedFrameStore.SLOT_SPREAD,
+			seq,
+			width: frame.width,
+			height: frame.height,
+			format: "rgb",
+			pts: performance.now(),
+			byteLength,
+			nodeId: this.nodeId,
+			slotCount: RetainedFrameStore.SLOT_SPREAD
 		};
+		this.entries.set(keyOf(handle), frame);
+		this.bytes += byteLength;
+		this.evictToBudget();
+		return handle;
 	}
-	const names = [];
-	for (const name of entries) {
-		if (!name.startsWith(prefix)) continue;
-		try {
-			unlink(name);
-			names.push(name);
-		} catch {}
+	/** The retained frame for `handle`, or `null` if never retained / already evicted. */
+	getFrame(handle) {
+		return this.entries.get(keyOf(handle)) ?? null;
+	}
+	/**
+	* Crop (and optionally downscale) the retained rgb frame for `handle` to the
+	* normalized `bbox`. A full-frame `bbox` ({x:0,y:0,w:1,h:1}) with no
+	* `maxWidth` returns the whole frame. Returns `null` when the frame is no
+	* longer retained. Nearest-neighbour scale — this is the best-effort
+	* post-analysis fallback path; native-resolution ROI crops come from the
+	* decode worker's surface (`getNativeCrop`), not here.
+	*/
+	crop(handle, bbox, maxWidth) {
+		const frame = this.entries.get(keyOf(handle));
+		if (!frame || frame.format !== "rgb") return null;
+		return cropRgb(frame, bbox, maxWidth);
+	}
+	/** Drop every retained frame (node/addon shutdown). */
+	clear() {
+		this.entries.clear();
+		this.bytes = 0;
+	}
+	/** Evict oldest frames until the retained bytes fit the budget (keep ≥1). */
+	evictToBudget() {
+		while (this.bytes > this.budgetBytes && this.entries.size > 1) {
+			const oldest = this.entries.keys().next().value;
+			if (oldest === void 0) break;
+			const evicted = this.entries.get(oldest);
+			this.entries.delete(oldest);
+			if (evicted) this.bytes -= evicted.data.byteLength;
+		}
+		if (this.bytes < 0) this.bytes = 0;
+	}
+};
+/**
+* Nearest-neighbour crop + optional downscale of a packed RGB24 frame to a
+* normalized `bbox`. Exported for unit coverage. Clamps the bbox into the frame
+* and never allocates more than the output size.
+*/
+function cropRgb(frame, bbox, maxWidth) {
+	const srcW = frame.width;
+	const srcH = frame.height;
+	const nx = Math.min(Math.max(bbox.x, 0), 1);
+	const ny = Math.min(Math.max(bbox.y, 0), 1);
+	const nw = Math.min(Math.max(bbox.w, 0), 1 - nx);
+	const nh = Math.min(Math.max(bbox.h, 0), 1 - ny);
+	const cropX = Math.floor(nx * srcW);
+	const cropY = Math.floor(ny * srcH);
+	const cropW = Math.max(1, Math.round(nw * srcW));
+	const cropH = Math.max(1, Math.round(nh * srcH));
+	const clampedW = Math.min(cropW, srcW - cropX);
+	const clampedH = Math.min(cropH, srcH - cropY);
+	const outW = maxWidth && maxWidth > 0 && maxWidth < clampedW ? maxWidth : clampedW;
+	const outH = outW === clampedW ? clampedH : Math.max(1, Math.round(outW * clampedH / clampedW));
+	const src = frame.data;
+	const out = Buffer.allocUnsafe(outW * outH * 3);
+	for (let oy = 0; oy < outH; oy += 1) {
+		const srcRow = (cropY + Math.min(clampedH - 1, Math.floor(oy * clampedH / outH))) * srcW * 3;
+		const outRow = oy * outW * 3;
+		for (let ox = 0; ox < outW; ox += 1) {
+			const s = srcRow + (cropX + Math.min(clampedW - 1, Math.floor(ox * clampedW / outW))) * 3;
+			const o = outRow + ox * 3;
+			out[o] = src[s];
+			out[o + 1] = src[s + 1];
+			out[o + 2] = src[s + 2];
+		}
 	}
 	return {
-		scanned: entries.length,
-		removed: names.length,
-		names
+		bytes: out,
+		width: outW,
+		height: outH
 	};
 }
 //#endregion
@@ -1600,6 +1285,11 @@ var SIGKILL_FALLBACK_MS = 1e3;
 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;
+/** Narrow an 'exit' payload to {@link WorkerExitInfo} (fakes may emit undefined). */
+function toWorkerExitInfo(v) {
+	const isInfo = (x) => typeof x === "object" && x !== null && "code" in x && "signal" in x;
+	return isInfo(v) ? v : void 0;
+}
 function toError(err) {
 	return err instanceof Error ? err : new Error(String(err));
 }
@@ -1620,6 +1310,8 @@ var SessionDecodeSession = class {
 	pendingNativeCrops = /* @__PURE__ */ new Map();
 	nextNativeCropId = 1;
 	exited = false;
+	/** Set by teardown() so handleExit can tell an intentional stop from a death. */
+	stopRequested = false;
 	sigkillTimer = null;
 	pullTimeoutTimer = null;
 	firstFrameReceived = false;
@@ -1629,7 +1321,7 @@ var SessionDecodeSession = class {
 		this.firstFrameTimeoutMs = firstFrameTimeoutMs;
 		this.frameTimeoutMs = frameTimeoutMs;
 		this.child.on("message", (m) => this.handleMessage(m));
-		this.child.on("exit", () => this.handleExit());
+		this.child.on("exit", (m) => this.handleExit(toWorkerExitInfo(m)));
 	}
 	start(source, opts) {
 		this.trySend({
@@ -1721,6 +1413,7 @@ var SessionDecodeSession = class {
 	}
 	/** Teardown: `stop`, `kill()`, arm the SIGKILL fallback unless already exited. */
 	teardown() {
+		this.stopRequested = true;
 		this.clearPullTimeout();
 		this.trySend({ kind: "stop" });
 		this.tryKill(void 0);
@@ -1766,7 +1459,11 @@ var SessionDecodeSession = class {
 				return;
 		}
 	}
-	handleExit() {
+	handleExit(info) {
+		if (!this.stopRequested && !this.exited) this.logger.warn("session-decode worker exited unexpectedly", { meta: {
+			code: info?.code ?? null,
+			signal: info?.signal ?? null
+		} });
 		this.exited = true;
 		if (this.sigkillTimer) {
 			clearTimeout(this.sigkillTimer);
@@ -1963,19 +1660,6 @@ function createSessionDecodeCoordinator(deps) {
 //#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
@@ -2093,6 +1777,7 @@ function startSessionDecodePump(deps) {
 			});
 		} finally {
 			releaseSpawnSlotOnce();
+			if (!stopped) deps.onEnded?.();
 		}
 	};
 	pump();
@@ -2206,10 +1891,13 @@ function denormalizeRect(rect, frameWidth, frameHeight) {
 * Walk `steps` (the attach config's tree) collecting every ENABLED step
 * whose catalog definition's `inputClasses` includes `parentClassName` —
 * these become the subtree's roots. A matched step's own nested `children`
-* ride along UNCHANGED (transitively included: `face-detection` pulls
+* ride along UNCHANGED here (transitively included: `face-detection` pulls
 * `face-embedding`, `plate-detection` pulls `plate-ocr`) — recursion stops
 * at a match rather than also searching inside it for further matches.
-* `filter`, when given, keeps only matches whose `addonId` is in the list.
+* `filter`, when given, keeps only the TOP-LEVEL matches whose `addonId` is
+* in the list — it does NOT prune a match's descendants. Strict per-`steps`
+* pruning of the descendant chain happens later in {@link runDetailSubtree}
+* (see {@link pruneChildStepsToRequested}); this function only selects roots.
 */
 function findMatchingDetailSteps(steps, parentClassName, lookupStepDefinition, filter) {
 	const matches = [];
@@ -2227,6 +1915,26 @@ function findMatchingDetailSteps(steps, parentClassName, lookupStepDefinition, f
 	walk(steps);
 	return matches;
 }
+/**
+* Prune a matched step's descendant tree to the caller's requested `steps`
+* set: keep a child ONLY when its `addonId` is in `requested`, recursing into
+* every kept child. Pure — returns a new step, never mutates the input.
+*
+* Applied ONLY on the DETAIL plane (see {@link runDetailSubtree}); the
+* per-frame executor path is untouched. This is what makes the dispatcher's
+* `steps` array authoritative: `['face-detection']` runs the detector geometry
+* ALONE (the `face-embedding` child is dropped — no ArcFace inference), while
+* `['face-detection','face-embedding']` keeps the child and reproduces the
+* full detect→embed chain exactly.
+*/
+function pruneChildStepsToRequested(step, requested) {
+	if (!step.children || step.children.length === 0) return step;
+	const children = step.children.filter((child) => requested.includes(child.addonId)).map((child) => pruneChildStepsToRequested(child, requested));
+	return {
+		...step,
+		children
+	};
+}
 /** Map a detection's CROP-pixel bbox back to FRAME-space pixels. */
 function mapBboxToFrameSpace(bbox, crop) {
 	const scaleX = crop.frameSpace.w / crop.width;
@@ -2286,10 +1994,21 @@ async function resolveCrop(deps, input) {
 * step's chain against it, and map every result bbox back to frame space.
 * Returns `null` when the camera isn't attached, no configured child
 * matches `input.parent.className`, or no crop source resolves.
+*
+* STRICT `steps` semantics: when the caller names an explicit `input.steps`
+* set, each matched root's descendant chain is pruned to exactly those ids
+* (see {@link pruneChildStepsToRequested}) — `resolveChildSteps`/`filter`
+* only selects TOP-LEVEL roots, so without this a matched `face-detection`
+* would always drag its `face-embedding` child along regardless of what was
+* asked for. When `input.steps` is omitted, the full configured chain runs
+* (today's behavior). This is the knob the dispatcher uses to run a periodic
+* geometry-only face refresh (`['face-detection']`) without re-running ArcFace.
 */
 async function runDetailSubtree(deps, input) {
-	const steps = deps.resolveChildSteps(input.deviceId, input.parent.className, input.steps);
-	if (!steps || steps.length === 0) return null;
+	const matched = deps.resolveChildSteps(input.deviceId, input.parent.className, input.steps);
+	if (!matched || matched.length === 0) return null;
+	const requested = input.steps;
+	const steps = requested === void 0 ? matched : matched.map((step) => pruneChildStepsToRequested(step, requested));
 	const crop = await resolveCrop(deps, input);
 	if (!crop) return null;
 	const details = [];
@@ -2307,7 +2026,6 @@ var DEFAULT_CONFIG = {
 	maxConcurrentInferences: 16,
 	targetLoadPercent: 80,
 	minThrottledFps: 1,
-	useSessionDecode: true,
 	maxConcurrentDecodeSpawns: 3
 };
 /**
@@ -2323,6 +2041,11 @@ var DEFAULT_CONFIG = {
 * cameras produced when every gate open/close forked and killed a worker.
 * Mirrors Scrypted's decode-fork ~15s idle-timeout.
 */
+/** JPEG quality for the runner→executor detection-frame hop. q82 keeps
+*  detector-relevant detail (source is h264 anyway) at ~10-15× less payload
+*  than raw RGB — the hop transits the hub main process (UDS child↔child
+*  routing), which OOM'd under raw frames. */
+var DETECTION_HOP_JPEG_QUALITY = 82;
 var DETECTION_KEEPWARM_MS = 15e3;
 /**
 * Occupancy-burst safety timeout (both the dial path and the analyzer-tap
@@ -2341,6 +2064,14 @@ var OCCUPANCY_BURST_SAFETY_TIMEOUT_MS = 8e3;
 * to have been teed within this window before it will route to the tap path.
 */
 var MOTION_FRESHNESS_WINDOW_MS = 5e3;
+/** Delay before re-dialing a detection decode whose worker died unexpectedly. */
+var DETECTION_REDIAL_DELAY_MS = 2e3;
+/**
+* Two unexpected decode deaths within this window → stop re-dialing and detach
+* (the orchestrator re-dispatches on the next motion signal). Bounds the loop
+* when the camera/source itself is broken.
+*/
+var DETECTION_REDIAL_GIVEUP_WINDOW_MS = 6e4;
 /**
 * Pure decision helper: returns `true` when a dynamic frame-diff analyzer
 * subscription should be opened for an onboard-motion camera.
@@ -2604,6 +2335,15 @@ var PipelineRunnerAddon = class extends BaseAddon {
 	* to the detection-frame crop). See {@link NativeCropRegistry}.
 	*/
 	nativeCropRegistry = new NativeCropRegistry();
+	/**
+	* Node-level RAM store of retained rgb detection frames, keyed by the
+	* `FrameHandle` that rides the inference-result event (shm-ring removal
+	* 2026-07-16 — replaces the `csr.` shm retention ring). Backs the
+	* FULL-FRAME branch of `getNativeCrop` so hub-side post-analysis resolves a
+	* frame's pixels over tRPC (routed by `handle.nodeId`) with no `/dev/shm`.
+	* Initialised in {@link onInitialize} once `nodeId` is known.
+	*/
+	retainedFrames = null;
 	attached = /* @__PURE__ */ new Map();
 	nodeId = "unknown";
 	metricsSnapshotTimer = null;
@@ -2640,7 +2380,6 @@ var PipelineRunnerAddon = class extends BaseAddon {
 	* payloads (`local-broker` / absent) — the map stays empty and every code
 	* path is identical to pre-Phase-2. Torn down on detach / shutdown.
 	*/
-	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 →
@@ -2700,8 +2439,8 @@ var PipelineRunnerAddon = class extends BaseAddon {
 	occupancyMaxConcurrent = 3;
 	/**
 	* TAP-based occupancy bursts in flight, keyed by deviceId (Task 10). See
-	* {@link OccupancyTapState}. A device has an entry here XOR is dialing via
-	* `startFrameHandlePoller` in `runOccupancyBurst` — never both; the choice
+	* {@link OccupancyTapState}. A device has an entry here XOR is dialing a
+	* session-decode burst in `runOccupancyBurst` — never both; the choice
 	* is made once at burst start based on `attachment.motionUnsubscribe`.
 	*/
 	occupancyTaps = /* @__PURE__ */ new Map();
@@ -2721,16 +2460,10 @@ var PipelineRunnerAddon = class extends BaseAddon {
 	async onInitialize() {
 		const raw = this.ctx.kernel.localNodeId ?? this.ctx.id;
 		this.nodeId = raw.includes("/") ? raw.split("/")[0] : raw;
-		try {
-			const purged = purgeOrphanSegments(RETENTION_SEGMENT_PREFIX);
-			if (purged.removed > 0) this.ctx.logger.info("session-decode retention: reclaimed orphaned shm segments", { meta: {
-				removed: purged.removed,
-				scanned: purged.scanned,
-				prefix: RETENTION_SEGMENT_PREFIX
-			} });
-		} catch (err) {
-			this.ctx.logger.warn("session-decode retention: orphan purge failed", { meta: { error: err instanceof Error ? err.message : String(err) } });
-		}
+		this.retainedFrames = new RetainedFrameStore({
+			nodeId: this.nodeId,
+			logger: this.ctx.logger.child("retained-frames")
+		});
 		this.runner = new PipelineRunner({
 			maxQueueDepth: this.config.maxQueueDepth,
 			maxConcurrentInferences: this.config.maxConcurrentInferences,
@@ -2803,9 +2536,6 @@ var PipelineRunnerAddon = class extends BaseAddon {
 		}
 		this.lastAnalyzerDetected.clear();
 		for (const deviceId of [...this.onboardAnalyzerTeardownTimers.keys(), ...this.onboardAnalyzerSubs.keys()]) this.clearOnboardAnalyzer(deviceId);
-		const remotePlanes = [...this.remotePlanes.values()];
-		this.remotePlanes.clear();
-		await Promise.all(remotePlanes.map((plane) => plane.dispose().catch(() => {})));
 		if (this.runner) {
 			this.runner.stop();
 			this.runner = null;
@@ -2820,6 +2550,9 @@ var PipelineRunnerAddon = class extends BaseAddon {
 		}
 		this.attached.clear();
 		this.lastMotionFrameAt.clear();
+		this.nativeCropRegistry.clear();
+		this.retainedFrames?.clear();
+		this.retainedFrames = null;
 	}
 	async cacheBenchFrame(input) {
 		const sharp = (await import("sharp")).default;
@@ -3210,13 +2943,23 @@ var PipelineRunnerAddon = class extends BaseAddon {
 	* worker downloads ONLY the ROI — a full native frame never travels the wire.
 	*/
 	async getNativeCrop(input) {
-		const requester = this.nativeCropRegistry.get(input.handle);
-		if (!requester) return null;
-		const result = await requester(input.bbox, input.maxWidth);
-		return result ? {
-			bytes: result.bytes,
-			width: result.width,
-			height: result.height
+		const b = input.bbox;
+		if (!(b.x <= .001 && b.y <= .001 && b.w >= .999 && b.h >= .999)) {
+			const requester = this.nativeCropRegistry.get(input.handle);
+			if (requester) {
+				const result = await requester(input.bbox, input.maxWidth);
+				if (result) return {
+					bytes: result.bytes,
+					width: result.width,
+					height: result.height
+				};
+			}
+		}
+		const crop = this.retainedFrames?.crop(input.handle, input.bbox, input.maxWidth);
+		return crop ? {
+			bytes: crop.bytes,
+			width: crop.width,
+			height: crop.height
 		} : null;
 	}
 	/**
@@ -3291,6 +3034,52 @@ var PipelineRunnerAddon = class extends BaseAddon {
 			return null;
 		}
 	}
+	/** Last unexpected detection-decode end per device — bounds the re-dial. */
+	lastDecodeUnexpectedEndAt = /* @__PURE__ */ new Map();
+	/**
+	* The detection decode pump ended WITHOUT a teardown (worker death /
+	* generator error) while the camera may still be attached. Previously this
+	* zombied the session — phase stayed `active`, frames stopped, and nothing
+	* re-dialed (the pre-fix Channel-closed runner crash used to mask it by
+	* respawning the whole runner). Recovery, bounded:
+	*  - first death: clean up the dead subscription and re-dial once (2s);
+	*  - second death within 60s: give up re-dialing and DETACH — the
+	*    orchestrator re-dispatches cleanly on the next motion/occupancy signal
+	*    (the same recovery path validated manually on device 592).
+	*/
+	handleDetectionDecodeEnded(deviceId) {
+		const attachment = this.attached.get(deviceId);
+		if (!attachment) return;
+		const log = this.ctx.logger.withTags({ deviceId });
+		attachment.detectionUnsubscribe?.();
+		attachment.detectionUnsubscribe = null;
+		if (attachment.detectionKeepWarmTimer !== null) {
+			clearTimeout(attachment.detectionKeepWarmTimer);
+			attachment.detectionKeepWarmTimer = null;
+			log.warn("detection decode worker died while kept warm — next open re-forks cold");
+			return;
+		}
+		const now = Date.now();
+		const last = this.lastDecodeUnexpectedEndAt.get(deviceId) ?? 0;
+		this.lastDecodeUnexpectedEndAt.set(deviceId, now);
+		if (now - last < DETECTION_REDIAL_GIVEUP_WINDOW_MS) {
+			log.warn("detection decode died twice within the re-dial window — detaching for orchestrator re-dispatch");
+			this.detachInternal(deviceId);
+			return;
+		}
+		log.warn("detection decode ended unexpectedly while attached — re-dialing once");
+		setTimeout(() => {
+			const still = this.attached.get(deviceId);
+			if (!still || still.detectionUnsubscribe !== null) return;
+			this.subscribeDetectionFrames(still.config).then((unsub) => {
+				if (!this.attached.has(deviceId)) {
+					unsub?.();
+					return;
+				}
+				still.detectionUnsubscribe = unsub;
+			});
+		}, DETECTION_REDIAL_DELAY_MS).unref?.();
+	}
 	detachInternal(deviceId) {
 		const attachment = this.attached.get(deviceId);
 		if (!attachment) return;
@@ -3302,16 +3091,7 @@ var PipelineRunnerAddon = class extends BaseAddon {
 		attachment.motionUnsubscribe?.();
 		attachment.detectionUnsubscribe?.();
 		this.lastMotionFrameAt.delete(deviceId);
-		const remotePlane = this.remotePlanes.get(deviceId);
-		if (remotePlane) {
-			this.remotePlanes.delete(deviceId);
-			remotePlane.dispose().catch((err) => {
-				this.ctx?.logger.debug("remote-source plane dispose failed on detach", {
-					tags: { deviceId },
-					meta: { error: errMsg(err) }
-				});
-			});
-		}
+		this.lastDecodeUnexpectedEndAt.delete(deviceId);
 		this.attached.delete(deviceId);
 		this.lastMotionAt.delete(deviceId);
 		this.lastEmittedCameraMetrics.delete(deviceId);
@@ -3429,65 +3209,6 @@ var PipelineRunnerAddon = class extends BaseAddon {
 		return [...this.attached.keys()];
 	}
 	/**
-	* Cross-node frame fetch for FOREIGN handles (segment on another node). Wired
-	* into every `startFrameHandlePoller` call so `resolvePolledFrame` can take
-	* the bounded `decoder.getFrame` fallback instead of an unmappable local shm
-	* read. The `nodeId` selector routes the call to the producing node (the
-	* cap's `nodeIdMode: 'routing'` default; agent→hub via `$hub-cap-fwd`). The
-	* wire schema returns `data: Uint8Array`; downstream inference expects a Node
-	* `Buffer`, so we adapt it here exactly as post-analysis does.
-	*/
-	async getRemoteFrame(handle) {
-		const api = this.ctx.api;
-		if (!api) return null;
-		const remote = await api.decoder.getFrame.query({
-			handle,
-			nodeId: handle.nodeId
-		});
-		if (!remote) return null;
-		return {
-			data: Buffer.from(remote.data),
-			width: remote.width,
-			height: remote.height,
-			format: remote.format,
-			timestamp: remote.timestamp
-		};
-	}
-	/**
-	* The remote-source leg for a camera, or `null` for today's co-located
-	* broker path (P2d). Created lazily on the FIRST subscription of a
-	* `remote-restream` camera and shared by its motion + detection pollers;
-	* `detachInternal` / `onShutdown` dispose it. With rollout OFF every
-	* attach payload is `local-broker` (or absent) → always `null` → the
-	* subscribe paths below are byte-identical to pre-Phase-2.
-	*/
-	remoteSourceFor(config) {
-		const frameSource = config.frameSource;
-		if (!isRemoteRestream(frameSource)) return null;
-		const existing = this.remotePlanes.get(config.deviceId);
-		if (existing) return existing;
-		const api = this.ctx.api;
-		if (!api) return null;
-		const hostname = resolveOwnerRestreamHost(frameSource, process.env["CAMSTACK_HUB_URL"]);
-		const plane = new RemoteSourcePlane({
-			api,
-			logger: this.ctx.logger,
-			deviceId: config.deviceId,
-			ownNodeId: this.nodeId,
-			ownerNodeId: frameSource.ownerNodeId,
-			hostname
-		});
-		this.ctx.logger.info("remote-source leg armed for camera", {
-			tags: { deviceId: config.deviceId },
-			meta: {
-				ownerNodeId: frameSource.ownerNodeId,
-				hostname: hostname ?? "(unresolved — acquires will fail until set)"
-			}
-		});
-		this.remotePlanes.set(config.deviceId, plane);
-		return plane;
-	}
-	/**
 	* Thin delegator to the module-level {@link acquireSessionDecodeRestreamFrom}
 	* (see its doc for the acquire behavior) — supplies this addon's `ctx.logger`.
 	* Kept as a method so the two call sites need no change.
@@ -3589,11 +3310,7 @@ var PipelineRunnerAddon = class extends BaseAddon {
 		const runner = this.runner;
 		const log = this.ctx.logger.withTags({ deviceId: config.deviceId });
 		if (!runner) return () => {};
-		const retentionSink = createSessionRetentionSink({
-			deviceId: config.deviceId,
-			nodeId: this.nodeId,
-			logger: log
-		});
+		const retainedFrames = this.retainedFrames;
 		const teardown = startGuardedSessionDecode({
 			logger: log,
 			acquire: () => this.acquireSessionDecodeRestream(api, config.deviceId, config.detectionStreamId, `session-decode:detect:${config.deviceId}`, resolveSessionDecodeHostname(config, process.env["CAMSTACK_HUB_URL"]), resolveSessionDecodeOwnerNodeId(config)),
@@ -3611,8 +3328,9 @@ var PipelineRunnerAddon = class extends BaseAddon {
 						format: "rgb"
 					},
 					acquireSpawnSlot: this.buildDecodeSpawnAcquire(log, "detect"),
+					onEnded: () => this.handleDetectionDecodeEnded(config.deviceId),
 					onDecodedFrame: (frame, nativeCrop) => {
-						const handle = retentionSink.write(frame) ?? void 0;
+						const handle = retainedFrames?.write(config.deviceId, frame) ?? void 0;
 						if (handle && nativeCrop) this.nativeCropRegistry.register(handle, nativeCrop);
 						this.enqueueSharedDetectionFrame(config.deviceId, frame, handle);
 					}
@@ -3621,7 +3339,6 @@ var PipelineRunnerAddon = class extends BaseAddon {
 		});
 		return () => {
 			teardown();
-			retentionSink.destroy();
 		};
 	}
 	/**
@@ -3687,30 +3404,8 @@ var PipelineRunnerAddon = class extends 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, config.motionFps);
-			return this.startMotionSessionDecode(config, api);
-		}
-		const src = resolveMotionFrameSource(config, opts?.sharedWithDetection === true);
-		const shared = src.shared;
-		const streamId = src.streamId;
-		const remote = this.remoteSourceFor(config);
-		return startFrameHandlePoller({
-			api,
-			brokerId: makeSourceBrokerId(config.deviceId, streamId),
-			format: src.format,
-			maxFps: config.motionFps,
-			tag: shared ? "motion-shared" : "motion",
-			logger: log,
-			ownNodeId: this.nodeId,
-			getRemoteFrame: (handle) => this.getRemoteFrame(handle),
-			...remote ? { source: remote.makeSource(streamId) } : {},
-			onFrame: shared ? (frame) => {
-				runner.enqueueMotionFrame(config.deviceId, rgbFrameToGrayFrame(frame), void 0);
-			} : (frame, handle) => {
-				runner.enqueueMotionFrame(config.deviceId, frame, handle);
-			}
-		});
+		if (resolveMotionFrameSource(config, opts?.sharedWithDetection === true).shared) return this.registerSharedMotionSink(config.deviceId, config.motionFps);
+		return this.startMotionSessionDecode(config, api);
 	}
 	handleDetectionStreamChange(deviceId, action) {
 		const attachment = this.attached.get(deviceId);
@@ -3798,24 +3493,9 @@ var PipelineRunnerAddon = class extends 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,
-			brokerId: makeSourceBrokerId(config.deviceId, config.detectionStreamId),
-			format: "rgb",
-			maxFps: config.detectionFps,
-			tag: "detection",
-			logger: log,
-			ownNodeId: this.nodeId,
-			getRemoteFrame: (handle) => this.getRemoteFrame(handle),
-			...remote ? { source: remote.makeSource(config.detectionStreamId) } : {},
-			onFrame: (frame, handle) => {
-				runner.enqueueDetectionFrame(config.deviceId, frame, handle);
-			}
-		});
+		return this.startDetectionSessionDecode(config, api);
 	}
-	async runInference(deviceId, frame, handle) {
+	async runInference(deviceId, frame, _handle) {
 		if (!this.ctx) return null;
 		const log = this.ctx.logger.withTags({ deviceId });
 		const api = this.ctx.api;
@@ -3829,11 +3509,20 @@ var PipelineRunnerAddon = class extends BaseAddon {
 			return null;
 		}
 		if (steps.length === 0) return null;
-		const useHandle = handle !== void 0 && handle.nodeId === this.nodeId && handle.width === frame.width && handle.height === frame.height;
+		let image;
+		if (frame.format === "rgb") try {
+			image = await sharp(frame.data, { raw: {
+				width: frame.width,
+				height: frame.height,
+				channels: 3
+			} }).jpeg({ quality: DETECTION_HOP_JPEG_QUALITY }).toBuffer();
+		} catch (err) {
+			log.debug("runInference: frame JPEG encode failed — falling back to raw pixels", { meta: { error: errMsg(err) } });
+		}
 		try {
 			return await api.pipelineExecutor.runPipeline.mutate({
 				steps: [...steps],
-				...useHandle ? { frameHandle: handle } : { frame },
+				...image !== void 0 ? { image } : { frame },
 				deviceId,
 				plane: "frame"
 			});
@@ -3857,10 +3546,9 @@ var PipelineRunnerAddon = class extends BaseAddon {
 				log.warn("runMotionAnalysis: this.ctx.api not available");
 				return;
 			}
-			const useHandle = handle !== void 0 && handle.nodeId === this.nodeId;
 			const result = await api.motionDetection.analyze.mutate({
 				deviceId,
-				...useHandle ? { frameHandle: handle } : { frame: toFrameInput(frame) }
+				frame: toFrameInput(frame)
 			});
 			if (!result) return;
 			const detected = result.regions.length > 0;
@@ -4078,9 +3766,9 @@ var PipelineRunnerAddon = class extends BaseAddon {
 		await this.runOccupancyDial(deviceId, frames, attachment, runner, api, log, false);
 	}
 	/**
-	* Dial-path occupancy burst: subscribes a fresh main-stream decode session
-	* via `startFrameHandlePoller` and collects `frames` handles (or times out
-	* at {@link OCCUPANCY_BURST_SAFETY_TIMEOUT_MS}). Called either directly
+	* Dial-path occupancy burst: spins up a fresh per-session decode worker
+	* (session-decode) over the main stream and collects `frames` decoded frames
+	* (or times out at {@link OCCUPANCY_BURST_SAFETY_TIMEOUT_MS}). Called either directly
 	* from `runOccupancyBurst` (no live/fresh motion tap available,
 	* `alreadyInFlight: false`) or as the Task 10 hardening #2 fallback after
 	* a zero-collected tap (`alreadyInFlight: true` — the tap already claimed
@@ -4089,6 +3777,7 @@ var PipelineRunnerAddon = class extends BaseAddon {
 	*/
 	async runOccupancyDial(deviceId, frames, attachment, runner, api, log, alreadyInFlight) {
 		const config = attachment.config;
+		const retainedFrames = this.retainedFrames;
 		if (!alreadyInFlight) {
 			this.occupancyBurstInFlight.add(deviceId);
 			this.occupancyBurstFound.delete(deviceId);
@@ -4098,37 +3787,35 @@ var PipelineRunnerAddon = class extends BaseAddon {
 			fallback: alreadyInFlight
 		} });
 		let count = 0;
-		let unsubscribe = null;
-		let unsubbed = false;
 		let settled = false;
-		const doUnsub = () => {
-			if (!unsubbed && unsubscribe) {
-				unsubbed = true;
-				unsubscribe();
-			}
-		};
+		let teardown = null;
 		const cleanup = () => {
 			if (settled) return;
 			settled = true;
-			doUnsub();
+			teardown?.();
 			this.finishOccupancyBurst(deviceId, log, count);
 		};
 		const safetyTimer = setTimeout(() => {
 			log.debug("occupancy re-check: safety timeout reached", { meta: { collected: count } });
 			cleanup();
 		}, OCCUPANCY_BURST_SAFETY_TIMEOUT_MS);
-		try {
-			unsubscribe = await startFrameHandlePoller({
-				api,
-				brokerId: makeSourceBrokerId(config.deviceId, config.detectionStreamId),
-				format: "rgb",
-				maxFps: config.detectionFps,
-				tag: "occupancy",
+		teardown = startGuardedSessionDecode({
+			logger: log,
+			acquire: () => this.acquireSessionDecodeRestream(api, config.deviceId, config.detectionStreamId, `session-decode:occupancy:${config.deviceId}`, resolveSessionDecodeHostname(config, process.env["CAMSTACK_HUB_URL"]), resolveSessionDecodeOwnerNodeId(config)),
+			startPump: (source) => startSessionDecodePump({
+				fork: forkDecodeWorker,
 				logger: log,
-				ownNodeId: this.nodeId,
-				getRemoteFrame: (handle) => this.getRemoteFrame(handle),
-				onFrame: (frame, handle) => {
+				source,
+				opts: {
+					fps: config.detectionFps,
+					format: "rgb"
+				},
+				acquireSpawnSlot: this.buildDecodeSpawnAcquire(log, "occupancy"),
+				onEnded: () => cleanup(),
+				onDecodedFrame: (frame, nativeCrop) => {
 					if (settled) return;
+					const handle = retainedFrames?.write(config.deviceId, frame) ?? void 0;
+					if (handle && nativeCrop) this.nativeCropRegistry.register(handle, nativeCrop);
 					runner.enqueueOccupancyFrame(deviceId, frame, handle);
 					count++;
 					if (count >= frames) {
@@ -4136,17 +3823,11 @@ var PipelineRunnerAddon = class extends BaseAddon {
 						cleanup();
 					}
 				}
-			});
-		} catch (err) {
-			clearTimeout(safetyTimer);
-			this.occupancyBurstInFlight.delete(deviceId);
-			this.occupancyBurstFound.delete(deviceId);
-			log.debug("occupancy re-check: poller start failed", { meta: { error: errMsg(err) } });
-			return;
-		}
+			})
+		});
 		if (settled) {
 			clearTimeout(safetyTimer);
-			doUnsub();
+			teardown();
 		}
 	}
 	emitInferenceResult(deviceId, frame, result, handle) {
@@ -4280,14 +3961,6 @@ var PipelineRunnerAddon = class extends BaseAddon {
 					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",
@@ -4310,7 +3983,6 @@ var PipelineRunnerAddon = class extends BaseAddon {
 			maxConcurrentInferences: this.config.maxConcurrentInferences,
 			targetLoadPercent: this.config.targetLoadPercent,
 			minThrottledFps: this.config.minThrottledFps,
-			useSessionDecode: this.config.useSessionDecode,
 			maxConcurrentDecodeSpawns: this.config.maxConcurrentDecodeSpawns
 		} });
 	}