@camstack/addon-pipeline-orchestrator 1.1.21 → 1.1.22

package/dist/index.js

@@ -15703,7 +15703,17 @@ var AgentAddonConfigSchema = object({
 });
 var AgentPipelineSettingsSchema = object({
 	addonDefaults: record(string(), AgentAddonConfigSchema).readonly(),
-	maxCameras: number().int().nonnegative().nullable().default(null)
+	maxCameras: number().int().nonnegative().nullable().default(null),
+	/** Per-node detection weight (relative share for the quota balancer). */
+	detectWeight: number().positive().optional(),
+	/** Node is eligible to run the detection pipeline (decode + inference). */
+	detect: boolean().optional(),
+	/** Node is eligible to host decoder sessions. */
+	decode: boolean().optional(),
+	/** Node is eligible to run audio-analyzer sessions. */
+	audio: boolean().optional(),
+	/** Node is eligible to be the ingest / source-owner (serve the restream). */
+	ingest: boolean().optional()
 });
 var CameraPipelineForAgentSchema = object({
 	steps: array(PipelineStepInputSchema).readonly(),
@@ -16137,6 +16147,38 @@ var pipelineOrchestratorCapability = {
 			kind: "mutation",
 			auth: "admin"
 		}),
+		/**
+		* Set a node's detection WEIGHT (relative share for the quota balancer).
+		* `null` clears it (back to the implicit weight 1). Unpinned cameras
+		* distribute proportionally to weight; `maxCameras` still clamps on top.
+		*/
+		setAgentDetectWeight: method(object({
+			agentNodeId: string(),
+			detectWeight: number().positive().nullable()
+		}), object({ success: literal(true) }), {
+			kind: "mutation",
+			auth: "admin"
+		}),
+		/**
+		* Set one node's placement CAPABILITIES — the per-node record that
+		* replaced the four flat orchestrator lists (`enabledNodes`,
+		* `enabledDecoderNodes`, `enabledAudioNodes`, `remoteSourcingNodes`).
+		* Each flag is optional in the patch: omit a flag to leave it unchanged,
+		* pass `null` to reset it to the node default (`hub` → capable, every
+		* other node → not). Detection/decode/audio eligibility is derived from
+		* these flags across the cluster; changing them re-derives the enabled
+		* sets and reconciles dispatch immediately.
+		*/
+		setAgentCapabilities: method(object({
+			agentNodeId: string(),
+			detect: boolean().nullable().optional(),
+			decode: boolean().nullable().optional(),
+			audio: boolean().nullable().optional(),
+			ingest: boolean().nullable().optional()
+		}), object({ success: literal(true) }), {
+			kind: "mutation",
+			auth: "admin"
+		}),
 		/** Read one camera's settings. Null when never touched (inherits agent defaults fully). */
 		getCameraSettings: method(object({ deviceId: number() }), CameraPipelineSettingsSchema.nullable()),
 		/** Set or clear the 3-state toggle for one (camera, addonId). Pass `enabled: null` to clear and revert to agent default. */
@@ -22043,6 +22085,18 @@ Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"pipelineOrchestrator.setAgentCapabilities": {
+		capName: "pipeline-orchestrator",
+		capScope: "system",
+		addonId: null,
+		access: "create"
+	},
+	"pipelineOrchestrator.setAgentDetectWeight": {
+		capName: "pipeline-orchestrator",
+		capScope: "system",
+		addonId: null,
+		access: "create"
+	},
 	"pipelineOrchestrator.setAgentMaxCameras": {
 		capName: "pipeline-orchestrator",
 		capScope: "system",
@@ -24186,6 +24240,23 @@ function computeCapacityScore(load) {
 	return load.attachedCameras * Math.max(load.avgInferenceFps, 0) + Math.max(load.queueDepthTotal, 0);
 }
 /**
+* Node detection weight, defaulting to 1 when absent/invalid. A higher weight
+* makes a node preferred proportionally more (see {@link BalancerInput.weights}).
+*/
+function nodeWeight(nodeId, weights) {
+	const w = weights?.[nodeId];
+	return w !== void 0 && w > 0 ? w : 1;
+}
+/**
+* Weight-adjusted capacity score — the value the balancer minimises. Dividing
+* the raw capacity score by the node's weight makes a heavier node accumulate
+* proportionally more load before it loses preference, yielding weight-
+* proportional distribution while still preferring drained/idle nodes.
+*/
+function weightedScore(load, weights) {
+	return computeCapacityScore(load) / nodeWeight(load.nodeId, weights);
+}
+/**
 * Returns true when the node has remaining capacity.
 * A node is eligible iff `cap` is unlimited (null/absent/<=0) OR
 * its `attachedCameras` count is strictly less than the cap.
@@ -24251,8 +24322,9 @@ function balance(input) {
 	};
 	const best = eligible.map((node) => ({
 		node,
-		score: computeCapacityScore(node)
-	})).toSorted((a, b) => a.score - b.score)[0];
+		score: computeCapacityScore(node),
+		sortKey: weightedScore(node, input.weights)
+	})).toSorted((a, b) => a.sortKey - b.sortKey || a.node.nodeId.localeCompare(b.node.nodeId))[0];
 	return {
 		kind: "assigned",
 		agentNodeId: best.node.nodeId,
@@ -24354,7 +24426,12 @@ var StoredAgentAddonConfigSchema = object({
 });
 var StoredAgentPipelineSettingsSchema = object({
 	addonDefaults: record(string(), StoredAgentAddonConfigSchema).readonly(),
-	maxCameras: number().int().nonnegative().nullable().default(null)
+	maxCameras: number().int().nonnegative().nullable().default(null),
+	detectWeight: number().positive().optional(),
+	detect: boolean().optional(),
+	decode: boolean().optional(),
+	audio: boolean().optional(),
+	ingest: boolean().optional()
 });
 var AgentSettingsMapSchema = record(string(), StoredAgentPipelineSettingsSchema);
 var StoredCameraStepOverridePatchSchema = object({
@@ -24893,6 +24970,13 @@ var OrchestratorDiagnosticsSchema = object({
 	knownRunnerNodes: array(string()),
 	cachedAgentLoadNodeIds: array(string()),
 	enabledNodes: array(string()),
+	enabledDecoderNodes: array(string()),
+	enabledAudioNodes: array(string()),
+	clusterRoles: object({
+		ingestNode: string(),
+		recordingNode: string(),
+		audioNode: string()
+	}),
 	assignedDeviceCount: number().int().min(0),
 	cameraConfigCount: number().int().min(0),
 	activeDetectionCount: number().int().min(0)
@@ -25009,36 +25093,48 @@ var PipelineOrchestratorAddon = class PipelineOrchestratorAddon extends BaseAddo
 	failoverPolicy = { ...DEFAULT_FAILOVER_POLICY };
 	/**
 	* Hub-wide allow-list of node ids eligible to run the detection
-	* pipeline. Driven by the `enabledNodes` multiselect in the addon
-	* schema. Hydrated from the schema default (`['hub']`) on first
-	* boot; every other node must be explicitly added by the operator.
-	* The list is a strict whitelist — disabled nodes stay connected
-	* for other capabilities (metrics, logs, cluster-wide events) but
-	* never receive camera assignments.
+	* pipeline. DERIVED (placement-model redesign) from the per-node
+	* capability store (`agentSettings[node].detect`) — no longer a flat
+	* `enabledNodes` multiselect. Recomputed by {@link refreshNodeCapabilities}
+	* on boot and on every capability write. The list is a strict whitelist —
+	* disabled nodes stay connected for other capabilities (metrics, logs,
+	* cluster-wide events) but never receive camera assignments.
 	*/
 	enabledNodes = ["hub"];
 	/**
 	* Hub-wide allow-list of node ids eligible to run decoder sessions.
-	* Driven by the `enabledDecoderNodes` multiselect in the addon schema.
+	* DERIVED from the per-node capability store (`agentSettings[node].decode`).
 	* Defaults to `['hub']` — the hub always has a decoder available.
 	*/
 	enabledDecoderNodes = ["hub"];
 	/**
-	* Phase-2 rollout knob (P2d): nodes allowed to run the REMOTE-SOURCE leg —
-	* dial a camera's source-owner restream over the LAN and decode it locally.
-	* Driven by the `remoteSourcingNodes` multiselect in the addon schema.
-	* Default EMPTY = Phase-2 transport OFF: source ownership stays unmodeled
-	* and every behavior (eligibility, assignment, attach payload) is
-	* bit-identical to pre-Phase-2. See `source-owner.ts`.
+	* Nodes allowed to run the REMOTE-SOURCE leg — dial a camera's source-owner
+	* restream over the LAN and decode it locally. Held for the source-owner
+	* plumbing (`source-owner.ts`) but currently ALWAYS EMPTY: the cross-node
+	* frame transport is a separate activation phase (placement-model §9 P1).
+	* With this empty, `resolveSourceOwner` returns `undefined` and every
+	* `selectRunnerFrameSource` emits `local-broker` — bit-identical to
+	* pre-Phase-2 behavior.
 	*/
 	remoteSourcingNodes = [];
 	/**
 	* Hub-wide allow-list of node ids eligible to run audio-analyzer sessions.
-	* Driven by the `enabledAudioNodes` multiselect in the addon schema.
+	* DERIVED from the per-node capability store (`agentSettings[node].audio`).
 	* Defaults to `['hub']`.
 	*/
 	enabledAudioNodes = ["hub"];
 	/**
+	* Cluster-wide singleton role assignments (placement-model §6). Each role
+	* is the ONE node that serves it for every camera. Driven by the
+	* `ingestNode` / `recordingNode` / `audioNode` node-selects in the addon
+	* global schema; defaults to the hub for all three.
+	*/
+	clusterRoles = {
+		ingestNode: "hub",
+		recordingNode: "hub",
+		audioNode: "hub"
+	};
+	/**
 	* Full global settings snapshot kept in memory so synchronous cap methods
 	* (e.g. `getGlobalOrchestrationSettings`) can resolve without awaiting the
 	* backing store. Refreshed in `initialize` and `onConfigChange`.
@@ -25107,6 +25203,8 @@ var PipelineOrchestratorAddon = class PipelineOrchestratorAddon extends BaseAddo
 	loadShedState = /* @__PURE__ */ new Map();
 	/** Timer for the auto-resume sweep. */
 	loadShedResumeTimer = null;
+	/** Per-camera guard so repeated low-fps snapshots don't stack relocate/pause. */
+	shedInFlight = /* @__PURE__ */ new Set();
 	/** Pending `scheduleReconcile` debounce timer. */
 	reconcileTimer = null;
 	/** True while `reconcileDispatch` is awaiting the RPC round-trip. */
@@ -25131,6 +25229,7 @@ var PipelineOrchestratorAddon = class PipelineOrchestratorAddon extends BaseAddo
 			const stored = await this.resolveGlobalStore();
 			this.globalSettings = { ...stored };
 			this.applyRuntimeSettings(this.globalSettings);
+			await this.refreshNodeCapabilities();
 		} catch (err) {
 			const msg = errMsg(err);
 			this.ctx.logger.warn("orchestrator settings load failed — using defaults", { meta: { error: msg } });
@@ -25546,6 +25645,9 @@ var PipelineOrchestratorAddon = class PipelineOrchestratorAddon extends BaseAddo
 			knownRunnerNodes: [...this.knownRunnerNodes].toSorted(),
 			cachedAgentLoadNodeIds: [...this.cachedAgentLoad.keys()].toSorted(),
 			enabledNodes: [...this.enabledNodes],
+			enabledDecoderNodes: [...this.enabledDecoderNodes],
+			enabledAudioNodes: [...this.enabledAudioNodes],
+			clusterRoles: { ...this.clusterRoles },
 			assignedDeviceCount: this.assignments.size,
 			cameraConfigCount: this.cameraConfigs.size,
 			activeDetectionCount: this.activeDetections.size
@@ -25670,6 +25772,7 @@ var PipelineOrchestratorAddon = class PipelineOrchestratorAddon extends BaseAddo
 			nodes: await this.collectAgentLoad({ onlyEnabled: true }),
 			preferredAgent,
 			nodeCaps: await this.buildNodeCaps(),
+			weights: await this.buildNodeWeights(),
 			eligibleNodes: this.detectionEligibleNodes(runnerConfig.deviceId)
 		});
 		if (!decision) throw new Error(`dispatchCamera: no runner available for ${runnerConfig.deviceId}`);
@@ -25786,6 +25889,7 @@ var PipelineOrchestratorAddon = class PipelineOrchestratorAddon extends BaseAddo
 				nodes: await this.collectAgentLoad({ onlyEnabled: true }),
 				preferredAgent: null,
 				nodeCaps: await this.buildNodeCaps(),
+				weights: await this.buildNodeWeights(),
 				eligibleNodes: this.detectionEligibleNodes(input.deviceId)
 			});
 			if (!decision) this.ctx.logger.warn("unassignPipeline: no runner available, leaving unassigned", { tags: { deviceId: input.deviceId } });
@@ -25834,6 +25938,7 @@ var PipelineOrchestratorAddon = class PipelineOrchestratorAddon extends BaseAddo
 		if (!this.ctx) throw new Error("PipelineOrchestrator: rebalance called before initialize");
 		const loads = await this.collectAgentLoad({ onlyEnabled: true });
 		const nodeCaps = await this.buildNodeCaps();
+		const nodeWeights = await this.buildNodeWeights();
 		const attachedDelta = /* @__PURE__ */ new Map();
 		const bumpAttached = (nodeId, by) => {
 			attachedDelta.set(nodeId, (attachedDelta.get(nodeId) ?? 0) + by);
@@ -25855,6 +25960,7 @@ var PipelineOrchestratorAddon = class PipelineOrchestratorAddon extends BaseAddo
 				nodes: talliedLoads(),
 				preferredAgent,
 				nodeCaps,
+				weights: nodeWeights,
 				eligibleNodes: this.detectionEligibleNodes(deviceId)
 			});
 			if (!decision) continue;
@@ -26310,6 +26416,18 @@ var PipelineOrchestratorAddon = class PipelineOrchestratorAddon extends BaseAddo
 		for (const [nodeId, settings] of Object.entries(blob)) caps[nodeId] = settings.maxCameras ?? null;
 		return caps;
 	}
+	/**
+	* Build a per-node detection WEIGHT map from the persisted agent settings —
+	* the sibling of {@link buildNodeCaps}. Nodes without a stored `detectWeight`
+	* are simply absent (the balancer treats absent as weight 1). Passed to every
+	* `balance()` call so unpinned cameras distribute proportionally to weight.
+	*/
+	async buildNodeWeights() {
+		const blob = await this.agentSettingsState.get();
+		const weights = {};
+		for (const [nodeId, settings] of Object.entries(blob)) if (typeof settings.detectWeight === "number" && settings.detectWeight > 0) weights[nodeId] = settings.detectWeight;
+		return weights;
+	}
 	async readAudioNodePin(deviceId) {
 		if (!this.ctx?.settings) return null;
 		try {
@@ -26458,6 +26576,7 @@ var PipelineOrchestratorAddon = class PipelineOrchestratorAddon extends BaseAddo
 				nodes: loads,
 				preferredAgent: null,
 				nodeCaps: await this.buildNodeCaps(),
+				weights: await this.buildNodeWeights(),
 				eligibleNodes: this.detectionEligibleNodes(deviceId)
 			});
 			if (!decision) {
@@ -27185,6 +27304,7 @@ var PipelineOrchestratorAddon = class PipelineOrchestratorAddon extends BaseAddo
 		};
 		const { [input.agentNodeId]: _drop, ...rest } = all;
 		await this.agentSettingsState.set(rest);
+		await this.refreshNodeCapabilities();
 		this.ctx.logger.info("agentSettings entry removed", { tags: { nodeId: input.agentNodeId } });
 		return {
 			success: true,
@@ -27208,6 +27328,68 @@ var PipelineOrchestratorAddon = class PipelineOrchestratorAddon extends BaseAddo
 		this.schedulePendingRetry();
 		return { success: true };
 	}
+	async setAgentDetectWeight(input) {
+		const existing = (await this.readAgentSettingsMap())[input.agentNodeId];
+		const weight = input.detectWeight ?? 1;
+		const next = existing ? {
+			...existing,
+			detectWeight: weight
+		} : {
+			addonDefaults: {},
+			maxCameras: null,
+			detectWeight: weight
+		};
+		await this.writeAgentSettings(input.agentNodeId, next);
+		this.ctx.logger.info("agentSettings.detectWeight updated", {
+			tags: { nodeId: input.agentNodeId },
+			meta: { detectWeight: weight ?? null }
+		});
+		this.rebalance().catch((err) => {
+			this.ctx.logger.warn("setAgentDetectWeight: rebalance failed", { meta: { error: err instanceof Error ? err.message : String(err) } });
+		});
+		return { success: true };
+	}
+	/**
+	* Set one node's placement capabilities — the per-node record that replaced
+	* the four flat orchestrator lists. Each flag is a tri-state patch: omit to
+	* leave unchanged, `null` to reset to the node default (persisted as an
+	* absent flag), `true`/`false` to force. After persisting, re-derive the
+	* enabled-node sets and reconcile dispatch so the change takes effect
+	* immediately (reuses the existing balancer / retry, no custom logic).
+	*/
+	async setAgentCapabilities(input) {
+		const existing = (await this.readAgentSettingsMap())[input.agentNodeId] ?? {
+			addonDefaults: {},
+			maxCameras: null
+		};
+		const apply = (key) => {
+			const patch = input[key];
+			if (patch === void 0) return existing[key];
+			if (patch === null) return void 0;
+			return patch;
+		};
+		const next = {
+			...existing,
+			detect: apply("detect"),
+			decode: apply("decode"),
+			audio: apply("audio"),
+			ingest: apply("ingest")
+		};
+		await this.writeAgentSettings(input.agentNodeId, next);
+		this.ctx.logger.info("agentSettings.capabilities updated", {
+			tags: { nodeId: input.agentNodeId },
+			meta: {
+				detect: next.detect,
+				decode: next.decode,
+				audio: next.audio,
+				ingest: next.ingest
+			}
+		});
+		await this.refreshNodeCapabilities();
+		this.knownRunnerNodes.add(input.agentNodeId);
+		this.schedulePendingRetry();
+		return { success: true };
+	}
 	async getCameraSettings(input) {
 		return (await this.readCameraSettingsMap())[String(input.deviceId)] ?? null;
 	}
@@ -27573,7 +27755,8 @@ var PipelineOrchestratorAddon = class PipelineOrchestratorAddon extends BaseAddo
 		const all = await this.readAgentSettingsMap();
 		const existing = all[nodeId];
 		all[nodeId] = {
-			addonDefaults: settings.addonDefaults,
+			...existing,
+			...settings,
 			maxCameras: settings.maxCameras !== void 0 ? settings.maxCameras ?? null : existing?.maxCameras ?? null
 		};
 		await this.agentSettingsState.set(all);
@@ -27856,45 +28039,37 @@ var PipelineOrchestratorAddon = class PipelineOrchestratorAddon extends BaseAddo
 		const rand = Math.random().toString(36).slice(2, 8);
 		return `tpl_${Date.now().toString(36).slice(-6)}${rand}`;
 	}
-	/** Build the addon-level schema (cluster-wide tunables: balancer + failover). */
+	/** Build the addon-level schema (cluster roles + balancer + failover). */
 	globalSettingsSchema() {
 		return this.schema({ sections: [
 			{
 				id: "cluster",
-				title: "Cluster",
+				title: "Cluster Roles",
 				tab: "pipeline",
-				description: "Which cluster nodes are eligible to run the detection pipeline. Strict whitelist: an empty list disables dispatch everywhere. Fresh installs default to ['hub']. Video detection additionally requires the node to be frame-source capable (Enabled Decoder Nodes) until cross-node frame transport ships.",
+				description: "Cluster-wide singleton roles: the single node that serves each role for every camera. Per-node detection/decode/audio CAPABILITIES + weights + camera caps are edited in the per-node capability table (agent settings), not here.",
 				fields: [
 					{
-						key: "enabledNodes",
-						type: "node-multiselect",
-						label: "Enabled Detection Nodes",
-						description: "Only the selected nodes are passed to the load balancer. Disabled nodes remain connected for other capabilities (metrics, logs, cluster-wide events) but will never receive camera assignments.",
-						default: ["hub"],
+						key: "ingestNode",
+						type: "node-select",
+						label: "Ingest Node",
+						description: "The node that connects every camera and serves the compressed restream. Defaults to the hub. (Arbitrary ingest ≠ hub is a later phase; kept here so the role is modeled.)",
+						default: "hub",
 						showOffline: true
 					},
 					{
-						key: "enabledDecoderNodes",
-						type: "node-multiselect",
-						label: "Enabled Decoder Nodes",
-						description: "Nodes eligible to run decoder sessions.",
-						default: ["hub"],
+						key: "recordingNode",
+						type: "node-select",
+						label: "Recording Node",
+						description: "The node that records every camera (passthrough copy to its storage location). Defaults to the hub.",
+						default: "hub",
 						showOffline: true
 					},
 					{
-						key: "remoteSourcingNodes",
-						type: "node-multiselect",
-						label: "Remote Frame-Sourcing Nodes",
-						description: "Cross-node detection rollout (Phase 2): nodes allowed to pull a camera's compressed restream from its source-owner (the hub) and decode it locally for detection. Empty (default) = off — detection stays co-located with the frame source. A node must ALSO be in Enabled Decoder Nodes to qualify.",
-						default: [],
-						showOffline: true
-					},
-					{
-						key: "enabledAudioNodes",
-						type: "node-multiselect",
-						label: "Enabled Audio Nodes",
-						description: "Nodes eligible to run audio-analyzer sessions. Disabled nodes remain connected for other capabilities but will never receive audio assignments.",
-						default: ["hub"],
+						key: "audioNode",
+						type: "node-select",
+						label: "Audio Node",
+						description: "The node that runs all audio analysis. Defaults to the hub. Must be an audio-capable node.",
+						default: "hub",
 						showOffline: true
 					}
 				]
@@ -28397,16 +28572,58 @@ var PipelineOrchestratorAddon = class PipelineOrchestratorAddon extends BaseAddo
 			pinnedOnDisconnect: config["pinnedOnDisconnect"] === "unpin-and-migrate" ? "unpin-and-migrate" : "leave-pinned",
 			onReconnect: config["onReconnect"] === "rebalance" ? "rebalance" : "restore"
 		};
-		const rawEnabled = config["enabledNodes"];
-		this.enabledNodes = rawEnabled === void 0 ? ["hub"] : Array.isArray(rawEnabled) ? rawEnabled.filter((v) => typeof v === "string" && !v.includes("/")) : [];
-		const rawEnabledDecoder = config["enabledDecoderNodes"];
-		this.enabledDecoderNodes = rawEnabledDecoder === void 0 ? ["hub"] : Array.isArray(rawEnabledDecoder) ? rawEnabledDecoder.filter((v) => typeof v === "string" && !v.includes("/")) : ["hub"];
-		const rawEnabledAudio = config["enabledAudioNodes"];
-		this.enabledAudioNodes = rawEnabledAudio === void 0 ? ["hub"] : Array.isArray(rawEnabledAudio) ? rawEnabledAudio.filter((v) => typeof v === "string" && !v.includes("/")) : ["hub"];
-		const rawRemoteSourcing = config["remoteSourcingNodes"];
-		this.remoteSourcingNodes = Array.isArray(rawRemoteSourcing) ? rawRemoteSourcing.filter((v) => typeof v === "string" && !v.includes("/")) : [];
+		const readRole = (key) => {
+			const raw = config[key];
+			return typeof raw === "string" && raw.length > 0 && !raw.includes("/") ? raw : "hub";
+		};
+		this.clusterRoles = {
+			ingestNode: readRole("ingestNode"),
+			recordingNode: readRole("recordingNode"),
+			audioNode: readRole("audioNode")
+		};
 		this.schedulePendingRetry();
 	}
+	/**
+	* Default placement capability for a node when its stored flag is unset:
+	* the hub is capable of every role out of the box; every other node must be
+	* explicitly enabled. This reproduces the classic `['hub']` defaults of the
+	* four removed flat lists against an empty capability store.
+	*/
+	static nodeCapabilityDefault(nodeId) {
+		return nodeId === "hub";
+	}
+	/**
+	* Recompute the derived enabled-node sets (`enabledNodes` /
+	* `enabledDecoderNodes` / `enabledAudioNodes`) from the per-node capability
+	* store. A node is eligible for a concern iff its stored flag is `true`, or
+	* the flag is unset AND the node defaults capable ({@link nodeCapabilityDefault}).
+	* Forked child nodeIds (`hub/classifier`) are never dispatchable and are
+	* excluded. `hub` is always considered even when absent from the store, so a
+	* fresh install keeps the hub-only cluster working.
+	*/
+	async refreshNodeCapabilities() {
+		let blob = {};
+		try {
+			blob = await this.agentSettingsState.get();
+		} catch (err) {
+			this.ctx.logger.warn("refreshNodeCapabilities: agent settings read failed", { meta: { error: errMsg(err) } });
+		}
+		const nodeIds = new Set(["hub"]);
+		for (const nodeId of Object.keys(blob)) if (typeof nodeId === "string" && nodeId.length > 0 && !nodeId.includes("/")) nodeIds.add(nodeId);
+		const detect = [];
+		const decode = [];
+		const audio = [];
+		const capable = (flag, nodeId) => typeof flag === "boolean" ? flag : PipelineOrchestratorAddon.nodeCapabilityDefault(nodeId);
+		for (const nodeId of nodeIds) {
+			const settings = blob[nodeId];
+			if (capable(settings?.detect, nodeId)) detect.push(nodeId);
+			if (capable(settings?.decode, nodeId)) decode.push(nodeId);
+			if (capable(settings?.audio, nodeId)) audio.push(nodeId);
+		}
+		this.enabledNodes = detect.toSorted();
+		this.enabledDecoderNodes = decode.toSorted();
+		this.enabledAudioNodes = audio.toSorted();
+	}
 	get api() {
 		return this.ctx.api ?? null;
 	}
@@ -29003,7 +29220,9 @@ var PipelineOrchestratorAddon = class PipelineOrchestratorAddon extends BaseAddo
 			});
 			return;
 		}
-		this.ctx.logger.warn("Load management: pausing camera detection (sustained low fps)", {
+		if (this.shedInFlight.has(deviceId)) return;
+		this.shedInFlight.add(deviceId);
+		this.ctx.logger.warn("Load management: sustained low fps — relocating or pausing", {
 			tags: { deviceId },
 			meta: {
 				actualFps: metrics.actualFps,
@@ -29012,7 +29231,28 @@ var PipelineOrchestratorAddon = class PipelineOrchestratorAddon extends BaseAddo
 				windowMs
 			}
 		});
-		state.pausedAt = now;
+		this.shedOrRelocate(deviceId, state).finally(() => this.shedInFlight.delete(deviceId));
+	}
+	/**
+	* Cluster-wide load-shed action: relocate the sustained-slow camera to a
+	* less-loaded node if the balancer (ceiling + weight aware) finds one,
+	* otherwise pause it. Reuses `balance()` / `attachOn` / `detachOn` — no custom
+	* placement logic.
+	*/
+	async shedOrRelocate(deviceId, state) {
+		if (state.pausedAt !== null) return;
+		if (await this.tryClusterRelocate(deviceId).catch((err) => {
+			this.ctx.logger.warn("Load management: cluster relocate failed", {
+				tags: { deviceId },
+				meta: { error: errMsg(err) }
+			});
+			return false;
+		})) {
+			state.lowSinceTs = null;
+			return;
+		}
+		this.ctx.logger.warn("Load management: pausing camera detection (no spare cluster capacity)", { tags: { deviceId } });
+		state.pausedAt = Date.now();
 		state.lowSinceTs = null;
 		this.pipelineWatchdog?.unregister(deviceId);
 		this.ctx.api?.pipelineRunner.detachCamera.mutate({ deviceId }).catch((err) => {
@@ -29023,6 +29263,51 @@ var PipelineOrchestratorAddon = class PipelineOrchestratorAddon extends BaseAddo
 		});
 		this.ensureLoadShedResumeTimer();
 	}
+	/**
+	* Try to move a sustained-slow camera to a less-loaded node CLUSTER-WIDE.
+	* Runs the same `balance()` the dispatcher uses (per-node ceiling + weight +
+	* frame-source eligibility); the camera's current node counts it in its own
+	* load, so a genuinely less-loaded node with spare capacity wins. Returns
+	* `true` iff the camera was moved to a DIFFERENT node. A manually pinned
+	* camera never relocates. Reuses `detachOn`/`attachOn`/`recordAssignment`.
+	*/
+	async tryClusterRelocate(deviceId) {
+		const current = this.assignments.get(deviceId);
+		const cached = this.cameraConfigs.get(deviceId);
+		if (!current || !cached) return false;
+		const currentNode = current.agentNodeId;
+		if (await this.readPipelinePin(deviceId)) return false;
+		const decision = balance({
+			nodes: await this.collectAgentLoad({ onlyEnabled: true }),
+			preferredAgent: null,
+			nodeCaps: await this.buildNodeCaps(),
+			weights: await this.buildNodeWeights(),
+			eligibleNodes: this.detectionEligibleNodes(deviceId)
+		});
+		if (!decision || decision.kind !== "assigned") return false;
+		const target = decision.agentNodeId;
+		if (target === currentNode) return false;
+		await this.detachOn(currentNode, deviceId).catch((err) => {
+			this.ctx.logger.debug("Load management: relocate detach-old failed", {
+				tags: { deviceId },
+				meta: {
+					from: currentNode,
+					error: errMsg(err)
+				}
+			});
+		});
+		await this.attachOn(target, cached);
+		this.recordAssignment(deviceId, target, "rebalance", false);
+		this.ctx.logger.info("Load management: relocated camera to spare-capacity node (cluster-wide)", {
+			tags: { deviceId },
+			meta: {
+				from: currentNode,
+				to: target,
+				score: decision.score
+			}
+		});
+		return true;
+	}
 	/** Base cooldown before first auto-resume attempt. */
 	static LOAD_SHED_BASE_COOLDOWN_MS = 3e4;
 	/** Maximum backoff cap. */