@camstack/addon-pipeline 1.2.65 → 1.2.68

package/dist/pipeline-runner/index.js

@@ -3,12 +3,12 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 const require_chunk = require("../chunk-emK7D4bc.js");
-const require_dist = require("../dist-DKrqeIfS.js");
-const require_event_loop_stall_monitor = require("../event-loop-stall-monitor-CnJ5JGA2.js");
-const require_worker_protocol = require("../worker-protocol-CDkbdSuM.js");
+const require_dist = require("../dist-Bv9CqUAF.js");
+const require_event_loop_stall_monitor = require("../event-loop-stall-monitor-Bz3lx_aY.js");
+const require_worker_protocol = require("../worker-protocol-D8M43suz.js");
 const require_hub_hostname = require("../hub-hostname-DAJXlOgV.js");
 const require_lazy_sharp = require("../lazy-sharp-CcYuXtsa.js");
-const require_remote_restream = require("../remote-restream-CO36Sr30.js");
+const require_remote_restream = require("../remote-restream-BYbAsgUf.js");
 let sharp = require("sharp");
 sharp = require_chunk.__toESM(sharp);
 let node_child_process = require("node:child_process");
@@ -1086,6 +1086,7 @@ function startSessionDecodePump(deps) {
 		releaseSpawnSlot = null;
 		release();
 	};
+	const pumpStartedAt = Date.now();
 	const pump = async () => {
 		try {
 			if (deps.acquireSpawnSlot) {
@@ -1095,11 +1096,16 @@ function startSessionDecodePump(deps) {
 					return;
 				}
 			}
+			const spawnGrantedAt = Date.now();
 			let firstFrameSeen = false;
 			for await (const frame of iterator) {
 				if (!firstFrameSeen) {
 					firstFrameSeen = true;
 					releaseSpawnSlotOnce();
+					deps.onFirstFrame?.({
+						spawnWaitMs: spawnGrantedAt - pumpStartedAt,
+						forkToFrameMs: Date.now() - spawnGrantedAt
+					});
 				}
 				if (stopped) {
 					frame.image.close();
@@ -4033,7 +4039,7 @@ function resolveOwnerRestreamHost(frameSource, hubUrl) {
 * thin delegator to this function — its two call sites are unchanged.
 */
 async function acquireSessionDecodeRestreamFrom(api, logger, params) {
-	const { deviceId, streamId, tag, hostname, ownerNodeId } = params;
+	const { deviceId, streamId, tag, hostname, ownerNodeId, detectionIntent } = params;
 	const pin = ownerNodeId !== void 0 ? require_dist.nodePin(ownerNodeId) : void 0;
 	const profile = require_remote_restream.profileForStreamId(await api.streamBroker.listAllProfileSlots.query(void 0, pin), deviceId, streamId);
 	if (profile === null) {
@@ -4053,7 +4059,7 @@ async function acquireSessionDecodeRestreamFrom(api, logger, params) {
 	}, pin);
 	const codec = rtpSource.videoCodec === "H265" ? "h265" : "h264";
 	const source = {
-		restreamUrl: rtpSource.url,
+		restreamUrl: detectionIntent ? require_remote_restream.withDetectionIntent(rtpSource.url) : rtpSource.url,
 		deviceId,
 		codec
 	};
@@ -4120,6 +4126,12 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends require_dist.BaseAdd
 	*/
 	retainedFrames = null;
 	attached = /* @__PURE__ */ new Map();
+	/**
+	* Detection decode workers parked across a detach, keyed by deviceId — see
+	* {@link WarmDetachedDecode}. Bounded by construction: at most one entry per
+	* camera, each self-expiring after {@link DETECTION_KEEPWARM_MS}.
+	*/
+	warmDetachedDetection = /* @__PURE__ */ new Map();
 	nodeId = "unknown";
 	metricsSnapshotTimer = null;
 	unsubMotionEvents = null;
@@ -4347,6 +4359,7 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends require_dist.BaseAdd
 			attachment.motionUnsubscribe?.();
 			attachment.detectionUnsubscribe?.();
 		}
+		for (const deviceId of [...this.warmDetachedDetection.keys()]) this.dropWarmDetectionDecode(deviceId, "shutdown");
 		this.attached.clear();
 		this.lastMotionFrameAt.clear();
 		this.nativeCropRegistry.clear();
@@ -5050,7 +5063,7 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends require_dist.BaseAdd
 		return { success: true };
 	}
 	async detachCamera(input) {
-		this.detachInternal(input.deviceId);
+		this.detachInternal(input.deviceId, true);
 		return { success: true };
 	}
 	async reportMotion(input) {
@@ -5445,7 +5458,10 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends require_dist.BaseAdd
 	*/
 	handleDetectionDecodeEnded(deviceId) {
 		const attachment = this.attached.get(deviceId);
-		if (!attachment) return;
+		if (!attachment) {
+			this.dropWarmDetectionDecode(deviceId, "worker-died-while-parked");
+			return;
+		}
 		const log = this.ctx.logger.withTags({ deviceId });
 		attachment.detectionUnsubscribe?.();
 		attachment.detectionUnsubscribe = null;
@@ -5476,7 +5492,18 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends require_dist.BaseAdd
 			});
 		}, DETECTION_REDIAL_DELAY_MS).unref?.();
 	}
-	detachInternal(deviceId) {
+	/**
+	* Tear a camera down.
+	*
+	* `keepDecodeWarm` routes the DETECTION decode through the same keep-warm
+	* grace the phase gate uses instead of killing it — see
+	* {@link WarmDetachedDecode}. Set only by the {@link detachCamera} cap entry
+	* point (the orchestrator's motion-cooldown teardown); every internal detach
+	* — an attach replacing a stale config, a decode that died twice, shutdown —
+	* is a hard one, because in each of those cases the worker is either wrong or
+	* already gone.
+	*/
+	detachInternal(deviceId, keepDecodeWarm = false) {
 		const attachment = this.attached.get(deviceId);
 		if (!attachment) return;
 		this.clearOnboardAnalyzer(deviceId);
@@ -5485,7 +5512,8 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends require_dist.BaseAdd
 			attachment.detectionKeepWarmTimer = null;
 		}
 		attachment.motionUnsubscribe?.();
-		attachment.detectionUnsubscribe?.();
+		if (keepDecodeWarm && attachment.detectionUnsubscribe !== null) this.parkWarmDetectionDecode(deviceId, attachment.config, attachment.detectionUnsubscribe);
+		else attachment.detectionUnsubscribe?.();
 		this.lastMotionFrameAt.delete(deviceId);
 		this.lastDecodeUnexpectedEndAt.delete(deviceId);
 		this.packageGovernor.forget(deviceId);
@@ -5495,7 +5523,86 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends require_dist.BaseAdd
 		this.lastMotionAt.delete(deviceId);
 		this.lastEmittedCameraMetrics.delete(deviceId);
 		this.runner?.unregisterCamera(deviceId);
-		this.ctx?.logger.info("detachCamera", { tags: { deviceId } });
+		this.ctx?.logger.info("detachCamera", {
+			tags: { deviceId },
+			meta: { decodeKeptWarm: this.warmDetachedDetection.has(deviceId) }
+		});
+	}
+	/**
+	* The decode-relevant identity of a camera's detection decode. Two configs
+	* that agree on all of it can share one worker; anything else must re-fork.
+	* Kept in ONE place so a future decode-shaping option cannot be added to the
+	* pump without the adoption check noticing.
+	*/
+	detectionDecodeIdentity(config) {
+		return {
+			streamId: config.detectionStreamId,
+			fps: config.detectionFps,
+			hostname: resolveSessionDecodeHostname(config, process.env["CAMSTACK_HUB_URL"]),
+			ownerNodeId: resolveSessionDecodeOwnerNodeId(config)
+		};
+	}
+	/**
+	* Hold a detached camera's detection decode worker for
+	* {@link DETECTION_KEEPWARM_MS} so the next motion event reuses it.
+	* Replacing an existing park releases the older worker first — two parked
+	* workers for one camera would be two live decodes and two broker leases.
+	*/
+	parkWarmDetectionDecode(deviceId, config, unsubscribe) {
+		this.dropWarmDetectionDecode(deviceId, "replaced");
+		const timer = setTimeout(() => {
+			this.warmDetachedDetection.delete(deviceId);
+			unsubscribe();
+			this.ctx?.logger.info("session-decode: warm detection decode expired — worker released", {
+				tags: { deviceId },
+				meta: { keepWarmMs: DETECTION_KEEPWARM_MS }
+			});
+		}, DETECTION_KEEPWARM_MS);
+		timer.unref?.();
+		this.warmDetachedDetection.set(deviceId, {
+			unsubscribe,
+			timer,
+			...this.detectionDecodeIdentity(config)
+		});
+	}
+	/**
+	* Adopt a parked decode worker for a camera that is attaching again, or
+	* `null` when there is nothing to adopt.
+	*
+	* A parked worker whose identity no longer matches is DROPPED here rather
+	* than left to expire: the caller is about to fork a replacement, and letting
+	* both run would double this camera's decode cost for the rest of the window.
+	*/
+	adoptWarmDetectionDecode(deviceId, config) {
+		const warm = this.warmDetachedDetection.get(deviceId);
+		if (!warm) return null;
+		const wanted = this.detectionDecodeIdentity(config);
+		if (warm.streamId !== wanted.streamId || warm.fps !== wanted.fps || warm.hostname !== wanted.hostname || warm.ownerNodeId !== wanted.ownerNodeId) {
+			this.dropWarmDetectionDecode(deviceId, "config-changed");
+			return null;
+		}
+		clearTimeout(warm.timer);
+		this.warmDetachedDetection.delete(deviceId);
+		this.ctx?.logger.info("session-decode: reusing the warm detection decode worker (no re-fork)", {
+			tags: { deviceId },
+			meta: {
+				streamId: warm.streamId,
+				fps: warm.fps
+			}
+		});
+		return warm.unsubscribe;
+	}
+	/** Release a parked worker now. `reason` names why in the log. */
+	dropWarmDetectionDecode(deviceId, reason) {
+		const warm = this.warmDetachedDetection.get(deviceId);
+		if (!warm) return;
+		clearTimeout(warm.timer);
+		this.warmDetachedDetection.delete(deviceId);
+		warm.unsubscribe();
+		this.ctx?.logger.info("session-decode: warm detection decode released", {
+			tags: { deviceId },
+			meta: { reason }
+		});
 	}
 	/**
 	* Synchronously cancel the teardown timer and call the unsubscribe
@@ -5628,14 +5735,15 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends require_dist.BaseAdd
 	* (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.
 	*/
-	async acquireSessionDecodeRestream(api, deviceId, streamId, tag, hostname, ownerNodeId) {
+	async acquireSessionDecodeRestream(api, deviceId, streamId, tag, hostname, ownerNodeId, detectionIntent) {
 		await this.refreshNativeLeaseSettings();
 		return acquireSessionDecodeRestreamFrom(api, this.ctx.logger, {
 			deviceId,
 			streamId,
 			tag,
 			hostname,
-			ownerNodeId
+			ownerNodeId,
+			...detectionIntent === true ? { detectionIntent: true } : {}
 		});
 	}
 	/**
@@ -5751,10 +5859,12 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends require_dist.BaseAdd
 		const log = this.ctx.logger.withTags({ deviceId: config.deviceId });
 		if (!runner) return () => {};
 		const retainedFrames = this.retainedFrames;
+		const requestedAt = Date.now();
 		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)),
+			acquire: () => this.acquireSessionDecodeRestream(api, config.deviceId, config.detectionStreamId, `session-decode:detect:${config.deviceId}`, resolveSessionDecodeHostname(config, process.env["CAMSTACK_HUB_URL"]), resolveSessionDecodeOwnerNodeId(config), true),
 			startPump: (source) => {
+				const dialMs = Date.now() - requestedAt;
 				log.info("session-decode: detection routed through per-session decode worker (rgb)", { meta: {
 					streamId: config.detectionStreamId,
 					codec: source.codec
@@ -5773,6 +5883,21 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends require_dist.BaseAdd
 						return reservation.detection || reservation.motion;
 					},
 					acquireSpawnSlot: this.buildDecodeSpawnAcquire(log, "detect"),
+					onFirstFrame: (timing) => {
+						const phaseActiveAt = this.lastMotionAt.get(config.deviceId);
+						log.info("session-decode: detection first frame", {
+							tags: { deviceId: config.deviceId },
+							meta: {
+								streamId: config.detectionStreamId,
+								codec: source.codec,
+								dialMs,
+								spawnWaitMs: timing.spawnWaitMs,
+								forkToFrameMs: timing.forkToFrameMs,
+								firstFrameMs: Date.now() - requestedAt,
+								...phaseActiveAt !== void 0 ? { sincePhaseActiveMs: Date.now() - phaseActiveAt } : {}
+							}
+						});
+					},
 					onEnded: () => this.handleDetectionDecodeEnded(config.deviceId),
 					onDecodedFrame: (frame, nativeCrop) => {
 						const current = reservation;
@@ -5864,6 +5989,11 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends require_dist.BaseAdd
 				attachment.detectionKeepWarmTimer = null;
 			}
 			if (attachment.detectionUnsubscribe !== null) return;
+			const adopted = this.adoptWarmDetectionDecode(deviceId, attachment.config);
+			if (adopted) {
+				attachment.detectionUnsubscribe = adopted;
+				return;
+			}
 			this.subscribeDetectionFrames(attachment.config).then((unsub) => {
 				if (!this.attached.has(deviceId)) {
 					unsub?.();

package/dist/pipeline-runner/index.mjs

@@ -1,9 +1,9 @@
-import { A as defineCustomActions, Dt as object, Et as number, G as pipelineRunnerCapability, H as pickDetailCropConvention, O as customAction, St as boolean, Tt as literal, U as pickNativeLeaseOverride, bt as _enum, et as errMsg, ht as nodePin, j as deriveDetailCropRect, jt as EventCategory, kt as string, ot as BaseAddon, s as DEFAULT_DETAIL_CROP_CONVENTION, u as DEVICE_BACKEND_TO_FORMAT, ut as createEvent, wt as lazy, xt as array } from "../dist-B9_C-QmC.mjs";
-import { c as getStepDefinition, t as attributeStall } from "../event-loop-stall-monitor-BucTbe9v.mjs";
-import { a as nativeLeaseSettingEnv, t as isWorkerReply } from "../worker-protocol-CQHY2NeB.mjs";
+import { At as string, Ct as boolean, Dt as number, Et as literal, K as pipelineRunnerCapability, M as deriveDetailCropRect, Mt as EventCategory, Ot as object, St as array, Tt as lazy, U as pickDetailCropConvention, W as pickNativeLeaseOverride, dt as createEvent, gt as nodePin, j as defineCustomActions, k as customAction, s as DEFAULT_DETAIL_CROP_CONVENTION, st as BaseAddon, tt as errMsg, u as DEVICE_BACKEND_TO_FORMAT, xt as _enum } from "../dist-CwUPxdAB.mjs";
+import { c as getStepDefinition, t as attributeStall } from "../event-loop-stall-monitor-D2dL-_bE.mjs";
+import { a as nativeLeaseSettingEnv, t as isWorkerReply } from "../worker-protocol-0uQE5Lfd.mjs";
 import { t as resolveHubHostname } from "../hub-hostname-cCknRYKj.mjs";
 import { t as getSharp } from "../lazy-sharp-B-mb8uWx.mjs";
-import { n as profileForStreamId, t as isRemoteRestream } from "../remote-restream-BeHi78PZ.mjs";
+import { i as withDetectionIntent, n as profileForStreamId, t as isRemoteRestream } from "../remote-restream-Ci7RXNGb.mjs";
 import sharp from "sharp";
 import { fork } from "node:child_process";
 import { fileURLToPath } from "node:url";
@@ -1079,6 +1079,7 @@ function startSessionDecodePump(deps) {
 		releaseSpawnSlot = null;
 		release();
 	};
+	const pumpStartedAt = Date.now();
 	const pump = async () => {
 		try {
 			if (deps.acquireSpawnSlot) {
@@ -1088,11 +1089,16 @@ function startSessionDecodePump(deps) {
 					return;
 				}
 			}
+			const spawnGrantedAt = Date.now();
 			let firstFrameSeen = false;
 			for await (const frame of iterator) {
 				if (!firstFrameSeen) {
 					firstFrameSeen = true;
 					releaseSpawnSlotOnce();
+					deps.onFirstFrame?.({
+						spawnWaitMs: spawnGrantedAt - pumpStartedAt,
+						forkToFrameMs: Date.now() - spawnGrantedAt
+					});
 				}
 				if (stopped) {
 					frame.image.close();
@@ -4025,7 +4031,7 @@ function resolveOwnerRestreamHost(frameSource, hubUrl) {
 * thin delegator to this function — its two call sites are unchanged.
 */
 async function acquireSessionDecodeRestreamFrom(api, logger, params) {
-	const { deviceId, streamId, tag, hostname, ownerNodeId } = params;
+	const { deviceId, streamId, tag, hostname, ownerNodeId, detectionIntent } = params;
 	const pin = ownerNodeId !== void 0 ? nodePin(ownerNodeId) : void 0;
 	const profile = profileForStreamId(await api.streamBroker.listAllProfileSlots.query(void 0, pin), deviceId, streamId);
 	if (profile === null) {
@@ -4045,7 +4051,7 @@ async function acquireSessionDecodeRestreamFrom(api, logger, params) {
 	}, pin);
 	const codec = rtpSource.videoCodec === "H265" ? "h265" : "h264";
 	const source = {
-		restreamUrl: rtpSource.url,
+		restreamUrl: detectionIntent ? withDetectionIntent(rtpSource.url) : rtpSource.url,
 		deviceId,
 		codec
 	};
@@ -4112,6 +4118,12 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends BaseAddon {
 	*/
 	retainedFrames = null;
 	attached = /* @__PURE__ */ new Map();
+	/**
+	* Detection decode workers parked across a detach, keyed by deviceId — see
+	* {@link WarmDetachedDecode}. Bounded by construction: at most one entry per
+	* camera, each self-expiring after {@link DETECTION_KEEPWARM_MS}.
+	*/
+	warmDetachedDetection = /* @__PURE__ */ new Map();
 	nodeId = "unknown";
 	metricsSnapshotTimer = null;
 	unsubMotionEvents = null;
@@ -4339,6 +4351,7 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends BaseAddon {
 			attachment.motionUnsubscribe?.();
 			attachment.detectionUnsubscribe?.();
 		}
+		for (const deviceId of [...this.warmDetachedDetection.keys()]) this.dropWarmDetectionDecode(deviceId, "shutdown");
 		this.attached.clear();
 		this.lastMotionFrameAt.clear();
 		this.nativeCropRegistry.clear();
@@ -5042,7 +5055,7 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends BaseAddon {
 		return { success: true };
 	}
 	async detachCamera(input) {
-		this.detachInternal(input.deviceId);
+		this.detachInternal(input.deviceId, true);
 		return { success: true };
 	}
 	async reportMotion(input) {
@@ -5437,7 +5450,10 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends BaseAddon {
 	*/
 	handleDetectionDecodeEnded(deviceId) {
 		const attachment = this.attached.get(deviceId);
-		if (!attachment) return;
+		if (!attachment) {
+			this.dropWarmDetectionDecode(deviceId, "worker-died-while-parked");
+			return;
+		}
 		const log = this.ctx.logger.withTags({ deviceId });
 		attachment.detectionUnsubscribe?.();
 		attachment.detectionUnsubscribe = null;
@@ -5468,7 +5484,18 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends BaseAddon {
 			});
 		}, DETECTION_REDIAL_DELAY_MS).unref?.();
 	}
-	detachInternal(deviceId) {
+	/**
+	* Tear a camera down.
+	*
+	* `keepDecodeWarm` routes the DETECTION decode through the same keep-warm
+	* grace the phase gate uses instead of killing it — see
+	* {@link WarmDetachedDecode}. Set only by the {@link detachCamera} cap entry
+	* point (the orchestrator's motion-cooldown teardown); every internal detach
+	* — an attach replacing a stale config, a decode that died twice, shutdown —
+	* is a hard one, because in each of those cases the worker is either wrong or
+	* already gone.
+	*/
+	detachInternal(deviceId, keepDecodeWarm = false) {
 		const attachment = this.attached.get(deviceId);
 		if (!attachment) return;
 		this.clearOnboardAnalyzer(deviceId);
@@ -5477,7 +5504,8 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends BaseAddon {
 			attachment.detectionKeepWarmTimer = null;
 		}
 		attachment.motionUnsubscribe?.();
-		attachment.detectionUnsubscribe?.();
+		if (keepDecodeWarm && attachment.detectionUnsubscribe !== null) this.parkWarmDetectionDecode(deviceId, attachment.config, attachment.detectionUnsubscribe);
+		else attachment.detectionUnsubscribe?.();
 		this.lastMotionFrameAt.delete(deviceId);
 		this.lastDecodeUnexpectedEndAt.delete(deviceId);
 		this.packageGovernor.forget(deviceId);
@@ -5487,7 +5515,86 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends BaseAddon {
 		this.lastMotionAt.delete(deviceId);
 		this.lastEmittedCameraMetrics.delete(deviceId);
 		this.runner?.unregisterCamera(deviceId);
-		this.ctx?.logger.info("detachCamera", { tags: { deviceId } });
+		this.ctx?.logger.info("detachCamera", {
+			tags: { deviceId },
+			meta: { decodeKeptWarm: this.warmDetachedDetection.has(deviceId) }
+		});
+	}
+	/**
+	* The decode-relevant identity of a camera's detection decode. Two configs
+	* that agree on all of it can share one worker; anything else must re-fork.
+	* Kept in ONE place so a future decode-shaping option cannot be added to the
+	* pump without the adoption check noticing.
+	*/
+	detectionDecodeIdentity(config) {
+		return {
+			streamId: config.detectionStreamId,
+			fps: config.detectionFps,
+			hostname: resolveSessionDecodeHostname(config, process.env["CAMSTACK_HUB_URL"]),
+			ownerNodeId: resolveSessionDecodeOwnerNodeId(config)
+		};
+	}
+	/**
+	* Hold a detached camera's detection decode worker for
+	* {@link DETECTION_KEEPWARM_MS} so the next motion event reuses it.
+	* Replacing an existing park releases the older worker first — two parked
+	* workers for one camera would be two live decodes and two broker leases.
+	*/
+	parkWarmDetectionDecode(deviceId, config, unsubscribe) {
+		this.dropWarmDetectionDecode(deviceId, "replaced");
+		const timer = setTimeout(() => {
+			this.warmDetachedDetection.delete(deviceId);
+			unsubscribe();
+			this.ctx?.logger.info("session-decode: warm detection decode expired — worker released", {
+				tags: { deviceId },
+				meta: { keepWarmMs: DETECTION_KEEPWARM_MS }
+			});
+		}, DETECTION_KEEPWARM_MS);
+		timer.unref?.();
+		this.warmDetachedDetection.set(deviceId, {
+			unsubscribe,
+			timer,
+			...this.detectionDecodeIdentity(config)
+		});
+	}
+	/**
+	* Adopt a parked decode worker for a camera that is attaching again, or
+	* `null` when there is nothing to adopt.
+	*
+	* A parked worker whose identity no longer matches is DROPPED here rather
+	* than left to expire: the caller is about to fork a replacement, and letting
+	* both run would double this camera's decode cost for the rest of the window.
+	*/
+	adoptWarmDetectionDecode(deviceId, config) {
+		const warm = this.warmDetachedDetection.get(deviceId);
+		if (!warm) return null;
+		const wanted = this.detectionDecodeIdentity(config);
+		if (warm.streamId !== wanted.streamId || warm.fps !== wanted.fps || warm.hostname !== wanted.hostname || warm.ownerNodeId !== wanted.ownerNodeId) {
+			this.dropWarmDetectionDecode(deviceId, "config-changed");
+			return null;
+		}
+		clearTimeout(warm.timer);
+		this.warmDetachedDetection.delete(deviceId);
+		this.ctx?.logger.info("session-decode: reusing the warm detection decode worker (no re-fork)", {
+			tags: { deviceId },
+			meta: {
+				streamId: warm.streamId,
+				fps: warm.fps
+			}
+		});
+		return warm.unsubscribe;
+	}
+	/** Release a parked worker now. `reason` names why in the log. */
+	dropWarmDetectionDecode(deviceId, reason) {
+		const warm = this.warmDetachedDetection.get(deviceId);
+		if (!warm) return;
+		clearTimeout(warm.timer);
+		this.warmDetachedDetection.delete(deviceId);
+		warm.unsubscribe();
+		this.ctx?.logger.info("session-decode: warm detection decode released", {
+			tags: { deviceId },
+			meta: { reason }
+		});
 	}
 	/**
 	* Synchronously cancel the teardown timer and call the unsubscribe
@@ -5620,14 +5727,15 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends BaseAddon {
 	* (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.
 	*/
-	async acquireSessionDecodeRestream(api, deviceId, streamId, tag, hostname, ownerNodeId) {
+	async acquireSessionDecodeRestream(api, deviceId, streamId, tag, hostname, ownerNodeId, detectionIntent) {
 		await this.refreshNativeLeaseSettings();
 		return acquireSessionDecodeRestreamFrom(api, this.ctx.logger, {
 			deviceId,
 			streamId,
 			tag,
 			hostname,
-			ownerNodeId
+			ownerNodeId,
+			...detectionIntent === true ? { detectionIntent: true } : {}
 		});
 	}
 	/**
@@ -5743,10 +5851,12 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends BaseAddon {
 		const log = this.ctx.logger.withTags({ deviceId: config.deviceId });
 		if (!runner) return () => {};
 		const retainedFrames = this.retainedFrames;
+		const requestedAt = Date.now();
 		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)),
+			acquire: () => this.acquireSessionDecodeRestream(api, config.deviceId, config.detectionStreamId, `session-decode:detect:${config.deviceId}`, resolveSessionDecodeHostname(config, process.env["CAMSTACK_HUB_URL"]), resolveSessionDecodeOwnerNodeId(config), true),
 			startPump: (source) => {
+				const dialMs = Date.now() - requestedAt;
 				log.info("session-decode: detection routed through per-session decode worker (rgb)", { meta: {
 					streamId: config.detectionStreamId,
 					codec: source.codec
@@ -5765,6 +5875,21 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends BaseAddon {
 						return reservation.detection || reservation.motion;
 					},
 					acquireSpawnSlot: this.buildDecodeSpawnAcquire(log, "detect"),
+					onFirstFrame: (timing) => {
+						const phaseActiveAt = this.lastMotionAt.get(config.deviceId);
+						log.info("session-decode: detection first frame", {
+							tags: { deviceId: config.deviceId },
+							meta: {
+								streamId: config.detectionStreamId,
+								codec: source.codec,
+								dialMs,
+								spawnWaitMs: timing.spawnWaitMs,
+								forkToFrameMs: timing.forkToFrameMs,
+								firstFrameMs: Date.now() - requestedAt,
+								...phaseActiveAt !== void 0 ? { sincePhaseActiveMs: Date.now() - phaseActiveAt } : {}
+							}
+						});
+					},
 					onEnded: () => this.handleDetectionDecodeEnded(config.deviceId),
 					onDecodedFrame: (frame, nativeCrop) => {
 						const current = reservation;
@@ -5856,6 +5981,11 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends BaseAddon {
 				attachment.detectionKeepWarmTimer = null;
 			}
 			if (attachment.detectionUnsubscribe !== null) return;
+			const adopted = this.adoptWarmDetectionDecode(deviceId, attachment.config);
+			if (adopted) {
+				attachment.detectionUnsubscribe = adopted;
+				return;
+			}
 			this.subscribeDetectionFrames(attachment.config).then((unsub) => {
 				if (!this.attached.has(deviceId)) {
 					unsub?.();