@camstack/addon-pipeline 1.2.317 → 1.2.321

package/dist/{default-detection-model-CILrD3sC.mjs → default-detection-model-DBqAX4cL.mjs}

@@ -1,4 +1,5 @@
-import { G as audioKindId, Yt as stepModelRunsOnFormat, _t as hfModelUrl, f as COCO_80_LABELS, i as AUDIO_MACRO_LABELS, p as COCO_TO_MACRO, vt as inferModelProvider, y as DEVICE_BACKEND_TO_FORMAT } from "./dist-3isAnyIX.mjs";
+import { G as audioKindId, Yt as stepModelRunsOnFormat, _t as hfModelUrl, f as COCO_80_LABELS, i as AUDIO_MACRO_LABELS, p as COCO_TO_MACRO, vt as inferModelProvider, y as DEVICE_BACKEND_TO_FORMAT } from "./dist-CTLBxswm.mjs";
+import { t as isWorkerReply } from "./worker-protocol-D_NzPcnh.mjs";
 import { randomUUID } from "node:crypto";
 //#region src/detection-pipeline/registry/effective-confidence.ts
 /** The default in force: the model's own floor, else the step's. */
@@ -2239,6 +2240,836 @@ function resolveFrameViewGeometry(sourceWidthInput, sourceHeightInput, spec) {
 	};
 }
 //#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;
+/**
+* The longest a planned teardown keeps a session's worker alive so the frames
+* it already handed out can be read (D652).
+*
+* What is being waited for is the REST of a frame's trip through the runner —
+* semaphore wait + inference + result — for frames that were admitted before
+* the detach. Measured on the live hub 2026-09-26 over one hour of
+* `pipeline stats` (2 254 per-camera 10 s windows): the WORST enqueue→emit in a
+* window was ≤1 000 ms in 96.7% of windows and ≤1 500 ms in 98.0%; going to
+* 5 000 ms buys only another 0.9%, and that tail is the inference-pool GPU hang,
+* which no wait here can rescue. The cost of waiting is one idle worker (its
+* decode already stopped by `drain`) for at most this long, per detach.
+*
+* A frame still held when this expires is not dropped silently: the
+* coordinator logs the count, tagged with the camera, and then kills.
+*/
+var SESSION_DECODE_DRAIN_BOUND_MS = 1500;
+/**
+* The miss reason for a native crop requested after its session's teardown.
+* Only crops already SENT when the drain began are waited for (D652); a later
+* one would ask a worker that is about to be killed.
+*/
+var NATIVE_CROP_REFUSED_DRAINING = "session draining — crop requested after teardown";
+/**
+* The refusal for a `toBuffer` asked for once the worker has been told to exit
+* (D656). A read during a DRAIN is served — that is what the drain is for — but
+* after the kill no reply can come, and a raw rejection read as a worker fault.
+*/
+var TO_BUFFER_REFUSED_KILLED = "session killed — read requested after the worker was told to exit";
+/** The refusal for a `toBuffer` the worker is no longer there to answer. */
+var TO_BUFFER_REFUSED_EXITED = "worker already exited";
+/** A read the session declined to send, by name — never a worker fault. */
+var SessionDecodeReadRefusedError = class extends Error {
+	reason;
+	frameId;
+	constructor(reason, frameId) {
+		super(`session-decode-coordinator: ${reason} (frameId=${frameId})`);
+		this.reason = reason;
+		this.frameId = frameId;
+		this.name = "SessionDecodeReadRefusedError";
+	}
+};
+/**
+* How often the cold-start wait REPORTS that it is still waiting. Task 0
+* live-measured cold-start (restream dial + hwaccel context + keyframe wait) at
+* 5-8s, so this must tolerate a slow-but-healthy start.
+*
+* It is no longer the point at which the session is abandoned — see
+* {@link DEFAULT_FIRST_FRAME_MAX_WAIT_MS}.
+*/
+var DEFAULT_FIRST_FRAME_TIMEOUT_MS = 2e4;
+/**
+* Hard ceiling on the TOTAL wait for the FIRST frame of a dial.
+*
+* The first decodable frame is not a fixed cost: it is one IDR interval plus
+* every GOP the decoder has to discard. Measured on device 618 (2560x1440
+* h264, `Invalid NAL unit` / `corrupt decoded frame` in its bitstream), dial →
+* first decoded frame over the broker's own muted restream was 1.8 / 6.5 / 7.0
+* / 7.2 / 9.2 / 10.0 / 10.8 / 12.9 / 14.9 / 20.0 / 30.3 / >40 s across 12
+* trials — against a healthy 587's 2.0 s ± 0.02.
+*
+* **The "8.0 s IDR interval" this used to attribute 618's spread to was wrong,
+* and is corrected here rather than deleted** (2026-08-28): a stated number
+* nobody re-derived reads as verification, and this one was used to argue that
+* 618 was an encoder outlier. The fleet runs 100-frame GOPs at 25 fps — a
+* **4 000 ms** IDR interval — and two independent readings of 6 h of live logs
+* agree with the operator rather than with this docblock. First, the join-burst
+* span logged on `restream prime (lat-probe)` is the time since the last IDR,
+* uniform in `[0, IDR]` and censored at `PRIME_MAX_SPAN_MS`: its median is
+* ~1 000 ms on eleven cameras, which is what `uniform[0, 4000]` conditioned on
+* `≤2000` predicts. Second, `detectionIntentServed` over detection dials puts
+* the SERVED fraction at 44-61 % on the bulk of the fleet, i.e. the ~50 %
+* `P(span > 2000)` a 4 000 ms interval implies. 618 measures 51 %, which is the
+* fleet norm. The genuine long-GOP outlier is **637** at 30 % served (⇒ ~6.7 s).
+*
+* So the spread is not this camera's encoder. It is D57's fixed 2 000 ms bound
+* withholding the join burst WHOLE on roughly half of every 4 s-GOP camera's
+* dials — see `join-burst-bound.ts`, which states the arithmetic, and
+* `docs/architecture/load-ledger.md` (2026-08-28) for the measurement.
+*
+* Abandoning at 20 s was therefore not a timeout, it was a coin flip, and the
+* recovery made it worse: ending the session RE-DIALS, which throws the
+* accumulated wait away and re-pays the RTSP setup + probe from zero, and two
+* ends inside 60 s DETACH the camera. That loop cost 618 25.9% of its assigned
+* decode airtime in one day (325 of 1257 ten-second windows delivered nothing).
+*
+* The wait is bounded instead of deadlined: the worker keeps the outstanding
+* `pull` latched, so re-arming costs nothing but the wait, and the ceiling is
+* what stops a genuinely dead input from holding a spawn permit forever.
+*/
+var DEFAULT_FIRST_FRAME_MAX_WAIT_MS = 45e3;
+/** 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));
+}
+/**
+* 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;
+	deviceId;
+	firstFrameTimeoutMs;
+	frameTimeoutMs;
+	firstFrameMaxWaitMs;
+	hooks;
+	pendingPull = null;
+	pendingToBuffers = /* @__PURE__ */ new Map();
+	/** Outstanding `nativeCrop` requests, keyed by the monotonic `requestId`. */
+	pendingNativeCrops = /* @__PURE__ */ new Map();
+	nextNativeCropId = 1;
+	exited = false;
+	/** Set by teardown() — the session is ending, whether or not it drains first. */
+	stopRequested = false;
+	/** Set when `kill()` is sent, so handleExit can tell an intentional stop from a death. */
+	killSent = false;
+	/**
+	* A SIGKILL already went out — an `'immediate'` teardown from the pump
+	* (D666) and the generator's later `finally` both escalate; one kill is enough.
+	*/
+	sigkillSent = false;
+	/**
+	* Images yielded and not yet closed that a CONSUMER still holds — queued,
+	* in flight, or being read. Each dies with the worker and somebody was going
+	* to read it first. This is what a drain waits on.
+	*/
+	consumerImages = 0;
+	/**
+	* Images yielded and not yet closed that only a RETENTION holder keeps —
+	* parked for a read that may come later (the on-demand JPEG fallback, D656).
+	* They die with the worker too, but nobody reads them inside any bound worth
+	* holding a worker for, so a drain does NOT wait on them.
+	*/
+	retainedImages = 0;
+	/** Armed while a drain waits; its expiry kills with frames still held. */
+	drainTimer = null;
+	sigkillTimer = null;
+	pullTimeoutTimer = null;
+	firstFrameReceived = false;
+	/** `Date.now()` of the FIRST `pull` — the origin of the cold-start ceiling. */
+	firstPullAt = 0;
+	constructor(child, logger, deviceId, firstFrameTimeoutMs, frameTimeoutMs, firstFrameMaxWaitMs, hooks) {
+		this.child = child;
+		this.logger = logger;
+		this.deviceId = deviceId;
+		this.firstFrameTimeoutMs = firstFrameTimeoutMs;
+		this.frameTimeoutMs = frameTimeoutMs;
+		this.firstFrameMaxWaitMs = firstFrameMaxWaitMs;
+		this.hooks = hooks;
+		this.child.on("message", (m) => this.handleMessage(m));
+		this.child.on("exit", (m) => this.handleExit(toWorkerExitInfo(m)));
+	}
+	start(source, opts, lease) {
+		this.trySend({
+			kind: "start",
+			source,
+			opts,
+			lease
+		});
+	}
+	/**
+	* 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" });
+		if (this.firstPullAt === 0) this.firstPullAt = Date.now();
+		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(new SessionDecodeReadRefusedError(TO_BUFFER_REFUSED_EXITED, frameId));
+		if (this.killSent) return Promise.reject(new SessionDecodeReadRefusedError(TO_BUFFER_REFUSED_KILLED, frameId));
+		return new Promise((resolve, reject) => {
+			const waiter = {
+				resolve,
+				reject
+			};
+			this.queueToBufferWaiter(frameId, waiter);
+			try {
+				this.child.send({
+					kind: "toBuffer",
+					frameId,
+					opts
+				});
+			} catch (err) {
+				this.removeToBufferWaiter(frameId, waiter);
+				reject(toError(err));
+			}
+		});
+	}
+	/**
+	* Send `nativeCrop` for `frameId` and resolve with the crop result, or `null`
+	* on any miss (frame aged out, worker error, or worker already exited). Never
+	* rejects — native crops are strictly best-effort with a free fallback.
+	*/
+	requestNativeCrop(frameId, bbox, maxWidth) {
+		if (this.exited) return Promise.resolve({ kind: "miss" });
+		if (this.stopRequested) return Promise.resolve({
+			kind: "miss",
+			workerReason: NATIVE_CROP_REFUSED_DRAINING
+		});
+		const requestId = this.nextNativeCropId++;
+		return new Promise((resolve) => {
+			this.pendingNativeCrops.set(requestId, { resolve });
+			try {
+				this.child.send({
+					kind: "nativeCrop",
+					requestId,
+					frameId,
+					bbox,
+					...maxWidth !== void 0 ? { maxWidth } : {}
+				});
+			} catch {
+				this.pendingNativeCrops.delete(requestId);
+				resolve({ kind: "miss" });
+				this.settleDrainIfDone();
+			}
+		});
+	}
+	/**
+	* The runner has this frame's detections: cut one native subject tile per box
+	* and END the hold on `frameId`. Fire and forget (no reply) so the encode can
+	* never delay the runner; a dropped message costs only the tiles.
+	*
+	* An EMPTY box list is still sent — it is how a frame that detected nothing
+	* releases its hold, and that is the common case.
+	*/
+	cutTiles(frameId, bboxes) {
+		if (this.exited) return;
+		this.trySend({
+			kind: "cutTiles",
+			frameId,
+			bboxes
+		});
+	}
+	/**
+	* Prompt-release the worker's RAM native-frame hold for `frameId`. Fire and
+	* forget (no reply): the hold is also bounded by a frame count, so a dropped
+	* release only defers reclaim. No-op once the worker has exited.
+	*/
+	releaseLease(frameId) {
+		if (this.exited) return;
+		this.trySend({
+			kind: "releaseNativeLease",
+			frameId
+		});
+	}
+	/**
+	* Tell the worker `frameId` reached inference, so its native lease is worth
+	* keeping. Fire and forget, no reply. Ordering matters and is free here: the
+	* caller runs in the same turn that consumed the frame, and the pull that
+	* decides this frame's admission is issued after that turn returns.
+	*/
+	markInferred(frameId) {
+		if (this.exited) return;
+		this.trySend({
+			kind: "markInferred",
+			frameId
+		});
+	}
+	/** A yielded image the consumer now holds — see {@link consumerImages}. */
+	noteImageOpened() {
+		this.consumerImages += 1;
+	}
+	/**
+	* An open image moved between a consumer and a retention-only holder
+	* (D656). Losing its last consumer may complete a waiting drain.
+	*/
+	noteImageHolder(pendingConsumer) {
+		if (pendingConsumer) {
+			this.retainedImages = Math.max(0, this.retainedImages - 1);
+			this.consumerImages += 1;
+			return;
+		}
+		this.consumerImages = Math.max(0, this.consumerImages - 1);
+		this.retainedImages += 1;
+		this.settleDrainIfDone();
+	}
+	/** A yielded image was closed; a waiting drain may now be done. */
+	noteImageClosed(pendingConsumer) {
+		if (pendingConsumer) this.consumerImages = Math.max(0, this.consumerImages - 1);
+		else this.retainedImages = Math.max(0, this.retainedImages - 1);
+		this.settleDrainIfDone();
+	}
+	/**
+	* End the session.
+	*
+	* `'drain'` with frames still held: tell the worker to stop decoding (it
+	* keeps every frame it holds), and kill only once every yielded image has
+	* been closed and every read answered — or when
+	* {@link SESSION_DECODE_DRAIN_BOUND_MS} expires, which is logged. Nothing
+	* held: `stop` + SIGTERM now. `'immediate'`: SIGKILL now.
+	*
+	* A SECOND call that says `'immediate'` while a drain is in progress
+	* ESCALATES (D652): addon shutdown lands on sessions already draining from
+	* a detach, and the runner exits right after — a drain it does not wait for
+	* is an orphaned worker holding its GPU pool. Any other repeat is ignored.
+	*/
+	teardown(mode) {
+		if (this.stopRequested) {
+			if (mode === "immediate") this.escalateToImmediate();
+			return;
+		}
+		this.stopRequested = true;
+		this.clearPullTimeout();
+		if (this.exited) return;
+		if (mode === "drain" && this.unsettledCount() > 0) {
+			this.trySend({ kind: "drain" });
+			this.drainTimer = setTimeout(() => this.handleDrainBoundExpired(), SESSION_DECODE_DRAIN_BOUND_MS);
+			this.drainTimer.unref?.();
+			return;
+		}
+		this.killNow(mode);
+	}
+	/** The drain (or a SIGTERM still waiting on its fallback) gives way to SIGKILL now. */
+	escalateToImmediate() {
+		if (this.exited || this.sigkillSent) return;
+		if (this.drainTimer !== null) {
+			clearTimeout(this.drainTimer);
+			this.drainTimer = null;
+		}
+		if (!this.killSent) {
+			this.killNow("immediate");
+			return;
+		}
+		if (this.sigkillTimer !== null) {
+			clearTimeout(this.sigkillTimer);
+			this.sigkillTimer = null;
+		}
+		this.tryKill("SIGKILL");
+	}
+	/**
+	* Frames a CONSUMER still holds, reads still waiting on the worker, and
+	* native crops already REQUESTED. A crop asked for before the teardown
+	* request is waited for; one asked for after it is refused by name — post-analysis's
+	* ordinary crop arrives 2.2–9.9 s after the frame, past any bound worth
+	* holding a worker for, and is served from subject tiles that die with the
+	* worker either way.
+	*
+	* A frame only PARKED for such a late read ({@link retainedImages}) is not
+	* counted, for the same reason (D656): counting it made nearly every
+	* teardown wait the full bound for frames nobody was going to read. Its read,
+	* once STARTED, is a pending read like any other and is waited for.
+	*/
+	unsettledCount() {
+		return this.consumerImages + this.pendingReadCount() + this.pendingNativeCrops.size;
+	}
+	/** What the session still holds, per category — every drain line carries it. */
+	heldCounts() {
+		return {
+			consumerFrames: this.consumerImages,
+			retainedFrames: this.retainedImages,
+			pendingReads: this.pendingReadCount(),
+			pendingCrops: this.pendingNativeCrops.size
+		};
+	}
+	pendingReadCount() {
+		let n = 0;
+		for (const waiters of this.pendingToBuffers.values()) n += waiters.length;
+		return n;
+	}
+	settleDrainIfDone() {
+		if (this.drainTimer === null || this.unsettledCount() > 0) return;
+		clearTimeout(this.drainTimer);
+		this.drainTimer = null;
+		this.killNow("drain");
+	}
+	/**
+	* The drain ran out of time with frames still held. Those frames die with
+	* the worker; that is a branch that DROPS work (D391), so it says how many,
+	* on which camera.
+	*/
+	handleDrainBoundExpired() {
+		this.drainTimer = null;
+		if (this.exited) return;
+		this.logger.warn("session-decode-coordinator: drain bound expired — killing the worker with frames still held", {
+			tags: { deviceId: this.deviceId },
+			meta: {
+				...this.heldCounts(),
+				boundMs: SESSION_DECODE_DRAIN_BOUND_MS
+			}
+		});
+		this.killNow("drain");
+	}
+	/**
+	* `stop`, then the kill — unless already exited.
+	*
+	* `'drain'`: SIGTERM, so the child flushes its last lines (`bounded-exit.ts`),
+	* and a SIGKILL fallback. `'immediate'`: SIGKILL outright. Since D652 gave the
+	* child a SIGTERM handler, SIGTERM is no longer instant death: a worker
+	* blocked in a native call (a VAAPI hang) never runs the handler, and the
+	* fallback was an `unref`'d timer the exiting parent did not wait for — so
+	* on shutdown that worker was orphaned with its GPU pool. The fallback timer
+	* is now ref'd: it exists only for a drain while the parent is alive (a
+	* shutdown escalates to SIGKILL and clears it), and a timer that keeps the
+	* process up for at most one second is the price of a kill that lands.
+	*/
+	killNow(mode) {
+		if (this.killSent) return;
+		this.killSent = true;
+		if (this.retainedImages > 0) this.logger.debug("session-decode-coordinator: retained frames die with the worker", {
+			tags: { deviceId: this.deviceId },
+			meta: {
+				mode,
+				...this.heldCounts()
+			}
+		});
+		this.trySend({ kind: "stop" });
+		if (mode === "immediate") {
+			this.tryKill("SIGKILL");
+			return;
+		}
+		this.tryKill(void 0);
+		if (this.exited) return;
+		this.sigkillTimer = setTimeout(() => {
+			this.sigkillTimer = null;
+			if (this.exited) return;
+			this.logger.warn("session-decode-coordinator: child did not exit within SIGKILL fallback window — forcing", {
+				tags: { deviceId: this.deviceId },
+				meta: { fallbackMs: SIGKILL_FALLBACK_MS }
+			});
+			this.tryKill("SIGKILL");
+		}, SIGKILL_FALLBACK_MS);
+	}
+	handleMessage(raw) {
+		if (!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 "nativeCropResult":
+				this.settleNativeCrop(raw.requestId, {
+					kind: "crop",
+					crop: {
+						bytes: raw.bytes,
+						width: raw.width,
+						height: raw.height,
+						...raw.source ? { source: raw.source } : {}
+					}
+				});
+				return;
+			case "nativeCropMiss":
+				if (raw.reason !== void 0) this.logger.debug("session-decode: native crop miss", { meta: {
+					requestId: raw.requestId,
+					reason: raw.reason
+				} });
+				this.settleNativeCrop(raw.requestId, {
+					kind: "miss",
+					...raw.reason !== void 0 ? { workerReason: raw.reason } : {}
+				});
+				return;
+			case "ready": return;
+			case "error":
+				this.settleError(raw.message, raw.frameId);
+				return;
+			case "log":
+				this.logger[raw.level](raw.message);
+				return;
+			case "dialTiming":
+				this.hooks.onDialTiming?.({
+					hwContextMs: raw.hwContextMs,
+					demuxerOpenMs: raw.demuxerOpenMs,
+					decoderCreateMs: raw.decoderCreateMs,
+					firstDecodeMs: raw.firstDecodeMs,
+					streamInfoProbed: raw.streamInfoProbed
+				});
+				return;
+			case "preRollSettled":
+				this.hooks.onPreRollSettled?.({
+					read: raw.read,
+					released: raw.released,
+					lostByReason: raw.lostByReason,
+					unsettled: raw.unsettled
+				});
+				return;
+			case "preRollReport":
+				this.hooks.onPreRollReport?.({
+					offered: raw.offered,
+					inferred: raw.inferred,
+					dropped: raw.dropped,
+					droppedByReason: raw.droppedByReason,
+					strideMs: raw.strideMs,
+					subsampled: raw.subsampled,
+					spanMs: raw.spanMs,
+					budgetFrames: raw.budgetFrames
+				});
+				return;
+		}
+	}
+	handleExit(info) {
+		if (!this.exited) this.hooks.onWorkerExit?.();
+		if (!this.killSent && !this.exited && info?.killedByRunner === true) this.logger.debug("session-decode worker ended by the runner shutdown kill", {
+			tags: { deviceId: this.deviceId },
+			meta: {
+				code: info.code,
+				signal: info.signal
+			}
+		});
+		else if (!this.killSent && !this.exited) this.logger.warn(this.stopRequested ? "session-decode worker exited unexpectedly while draining" : "session-decode worker exited unexpectedly", {
+			tags: { deviceId: this.deviceId },
+			meta: {
+				code: info?.code ?? null,
+				signal: info?.signal ?? null,
+				...this.stopRequested ? this.heldCounts() : {}
+			}
+		});
+		this.exited = true;
+		if (this.drainTimer) {
+			clearTimeout(this.drainTimer);
+			this.drainTimer = null;
+		}
+		if (this.sigkillTimer) {
+			clearTimeout(this.sigkillTimer);
+			this.sigkillTimer = null;
+		}
+		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();
+		for (const waiter of this.pendingNativeCrops.values()) waiter.resolve({ kind: "miss" });
+		this.pendingNativeCrops.clear();
+	}
+	/** Settle the `nativeCrop` waiter for `requestId` (dropping unknown/stale ids). */
+	settleNativeCrop(requestId, attempt) {
+		const waiter = this.pendingNativeCrops.get(requestId);
+		if (!waiter) return;
+		this.pendingNativeCrops.delete(requestId);
+		waiter.resolve(attempt);
+		this.settleDrainIfDone();
+	}
+	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
+	* has not produced a frame and has not exited.
+	*
+	* BEFORE the first frame this is not yet a failure. The worker latches the
+	* outstanding `pull` (`decode-worker-child.handlePull` sets `pendingPull` and
+	* delivers on the next decoded frame), so re-arming the timer costs nothing
+	* but the wait and the session keeps the dial, the RTSP setup and the probe
+	* it has already paid for. Only the {@link firstFrameMaxWaitMs} ceiling ends
+	* it — see that constant for the measurement that set it.
+	*
+	* AFTER the first frame the deadline is unchanged: a steady stream that stops
+	* is a hung decode, and ending 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}.
+	*
+	* Every line here carries `tags: { deviceId }` and a `reason`, because
+	* "detaching" a camera is the loudest dropped work in this path and an
+	* operator has to be able to answer "why did 618 stop" from the logs alone.
+	*/
+	handlePullTimeout(timeoutMs) {
+		this.pullTimeoutTimer = null;
+		const waiter = this.pendingPull;
+		if (!waiter) return;
+		const waitedMs = this.firstPullAt === 0 ? timeoutMs : Date.now() - this.firstPullAt;
+		if (!this.firstFrameReceived && waitedMs < this.firstFrameMaxWaitMs) {
+			this.logger.warn("session-decode-coordinator: still waiting for its first decodable frame — holding the dial", {
+				tags: { deviceId: this.deviceId },
+				meta: {
+					waitedMs,
+					reportEveryMs: timeoutMs,
+					maxWaitMs: this.firstFrameMaxWaitMs,
+					hint: "long IDR interval or a discarded GOP looks exactly like this"
+				}
+			});
+			this.armPullTimeout();
+			return;
+		}
+		this.pendingPull = null;
+		const reason = this.firstFrameReceived ? "stalled-after-first-frame" : "no-first-frame";
+		this.logger.warn(this.firstFrameReceived ? "session-decode-coordinator: gave up waiting for the next frame — ending session" : "session-decode-coordinator: gave up waiting for the first decodable frame — ending session", {
+			tags: { deviceId: this.deviceId },
+			meta: {
+				reason,
+				waitedMs,
+				timeoutMs,
+				...this.firstFrameReceived ? {} : { maxWaitMs: this.firstFrameMaxWaitMs }
+			}
+		});
+		waiter.resolve({ kind: "ended" });
+	}
+	/**
+	* Arm the next round-trip deadline. Before the first frame the timer is
+	* clamped to what is LEFT of the ceiling, so the give-up lands exactly on
+	* {@link firstFrameMaxWaitMs} instead of on the next report boundary past it
+	* — otherwise a 45 s ceiling reported every 20 s would really give up at 60 s.
+	*/
+	armPullTimeout() {
+		const timeoutMs = this.firstFrameReceived ? this.frameTimeoutMs : Math.max(1, Math.min(this.firstFrameTimeoutMs, this.firstFrameMaxWaitMs - (this.firstPullAt === 0 ? 0 : Date.now() - this.firstPullAt)));
+		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);
+		this.settleDrainIfDone();
+	}
+	/**
+	* `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);
+				this.settleDrainIfDone();
+				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();
+		this.settleDrainIfDone();
+	}
+	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);
+			if (signal === "SIGKILL") this.sigkillSent = true;
+		} catch (err) {
+			this.logger.warn("session-decode-coordinator: kill() on child failed", {
+				tags: { deviceId: this.deviceId },
+				meta: {
+					signal,
+					err: toError(err).message
+				}
+			});
+		}
+	}
+};
+/** Build the {@link FrameImage} adapter for one `frame` reply. */
+function buildFrameImage(session, reply) {
+	let closed = false;
+	let pendingConsumer = true;
+	session.noteImageOpened();
+	return {
+		width: reply.width,
+		height: reply.height,
+		format: reply.format,
+		frameId: reply.frameId,
+		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);
+		},
+		nativeCrop: (bbox, maxWidth) => session.requestNativeCrop(reply.frameId, bbox, maxWidth),
+		cutTiles: (bboxes) => session.cutTiles(reply.frameId, bboxes),
+		releaseNativeLease: () => session.releaseLease(reply.frameId),
+		markInferred: () => session.markInferred(reply.frameId),
+		setPendingConsumer: (pending) => {
+			if (closed || pending === pendingConsumer) return;
+			pendingConsumer = pending;
+			session.noteImageHolder(pending);
+		},
+		close: () => {
+			if (closed) return;
+			closed = true;
+			session.noteImageClosed(pendingConsumer);
+		}
+	};
+}
+/**
+* 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
+* (bounded drain, then `stop` + `kill()` + SIGKILL fallback) in every exit
+* path via `finally`.
+*/
+function createSessionDecodeCoordinator(deps) {
+	const firstFrameTimeoutMs = deps.firstFrameTimeoutMs ?? DEFAULT_FIRST_FRAME_TIMEOUT_MS;
+	const frameTimeoutMs = deps.frameTimeoutMs ?? DEFAULT_FRAME_TIMEOUT_MS;
+	const firstFrameMaxWaitMs = Math.max(deps.firstFrameMaxWaitMs ?? DEFAULT_FIRST_FRAME_MAX_WAIT_MS, firstFrameTimeoutMs);
+	return { async *generateVideoFrames(source, opts) {
+		const session = new SessionDecodeSession(deps.fork(source), deps.logger, source.deviceId, firstFrameTimeoutMs, frameTimeoutMs, firstFrameMaxWaitMs, {
+			...deps.onDialTiming ? { onDialTiming: deps.onDialTiming } : {},
+			...deps.onPreRollReport ? { onPreRollReport: deps.onPreRollReport } : {},
+			...deps.onPreRollSettled ? { onPreRollSettled: deps.onPreRollSettled } : {},
+			...deps.onWorkerExit ? { onWorkerExit: deps.onWorkerExit } : {}
+		});
+		session.start(source, opts, deps.lease());
+		deps.onSessionTeardown?.((mode) => session.teardown(mode));
+		let failed = false;
+		try {
+			while (true) {
+				const outcome = await session.pullNext();
+				if (outcome.kind === "ended") return;
+				const { reply } = outcome;
+				yield {
+					timestamp: reply.timestamp,
+					image: buildFrameImage(session, reply),
+					...reply.capturedAt !== void 0 ? { capturedAt: reply.capturedAt } : {},
+					...reply.preRoll === true ? { preRoll: true } : {}
+				};
+			}
+		} catch (err) {
+			failed = true;
+			throw err;
+		} finally {
+			session.teardown(failed ? "immediate" : deps.teardownMode?.() ?? "drain");
+		}
+	} };
+}
+//#endregion
+//#region src/session-decode/session-decode-read-gone.ts
+/**
+* A session-decode `toBuffer` the worker will never answer (D656).
+*
+* Named refusals after teardown (`SessionDecodeReadRefusedError`) and the
+* in-flight waiter rejection when the child exits mid-read. Live Mac bursts
+* (frameId 1–8 at session end) used to surface these as `runInference failed`.
+*/
+function isSessionDecodeReadGone(err) {
+	if (err instanceof SessionDecodeReadRefusedError) return true;
+	const msg = err instanceof Error ? err.message : String(err);
+	return msg.includes("worker already exited") || msg.includes("session killed — read requested after the worker was told to exit") || msg.includes("worker exited before toBuffer reply") || msg.includes("local frameRef miss:");
+}
+//#endregion
 //#region src/session-decode/local-frame-registry.ts
 var DEFAULT_MAX_FRAMES = 24;
 var DEFAULT_MAX_BYTES = 512 * 1024 * 1024;
@@ -2392,18 +3223,26 @@ var LocalFrameRegistry = class {
 		};
 		this.touch(entry);
 		const geometry = resolveFrameViewGeometry(entry.image.width, entry.image.height, spec);
-		return {
-			kind: "view",
-			data: await entry.image.toBuffer({
-				crop: geometry.sourceCrop,
-				resize: geometry.output,
-				format: spec.format
-			}),
-			width: geometry.output.width,
-			height: geometry.output.height,
-			format: spec.format,
-			geometry
-		};
+		try {
+			return {
+				kind: "view",
+				data: await entry.image.toBuffer({
+					crop: geometry.sourceCrop,
+					resize: geometry.output,
+					format: spec.format
+				}),
+				width: geometry.output.width,
+				height: geometry.output.height,
+				format: spec.format,
+				geometry
+			};
+		} catch (err) {
+			if (isSessionDecodeReadGone(err)) return {
+				kind: "miss",
+				reason: "stale-ref"
+			};
+			throw err;
+		}
 	}
 	/** Oldest owner-only / queued entry (`refs === 1`). Consumer leases (`refs > 1`) stay. */
 	findOwnerOnlyVictim() {
@@ -2850,4 +3689,4 @@ function resolveDefaultDetectionModel(backend, device, format, getStepDef = getS
 	return getDefaultModelForFormatFromDef(def, format);
 }
 //#endregion
-export { resolveModelForFormat as _, buildSubtreeCanRun as a, resolveModelDefaultConfidence as b, macroGateVerdict as c, resolveFrameViewGeometry as d, ALL_PIPELINE_STEPS as f, getStepDefinition as g, getStep as h, mergeCustomModels as i, rootObjectGate as l, getDefaultModelForFormat as m, resolveDefaultDetectionModel as n, placeDetailStep as o, ALL_STEPS as p, CustomModelCatalog as r, stepsForElectedPool as s, OBJECT_DETECTION_STEP_ID as t, localFrameRegistry as u, RETIRED_MODEL_IDS as v, landmarkPrecisionVerdict as y };
+export { resolveModelDefaultConfidence as S, getStep as _, buildSubtreeCanRun as a, RETIRED_MODEL_IDS as b, macroGateVerdict as c, isSessionDecodeReadGone as d, createSessionDecodeCoordinator as f, getDefaultModelForFormat as g, ALL_STEPS as h, mergeCustomModels as i, rootObjectGate as l, ALL_PIPELINE_STEPS as m, resolveDefaultDetectionModel as n, placeDetailStep as o, resolveFrameViewGeometry as p, CustomModelCatalog as r, stepsForElectedPool as s, OBJECT_DETECTION_STEP_ID as t, localFrameRegistry as u, getStepDefinition as v, landmarkPrecisionVerdict as x, resolveModelForFormat as y };