@camstack/addon-pipeline-orchestrator 1.2.290 → 1.2.291

package/dist/index.mjs

@@ -25005,6 +25005,105 @@ var pipelineExecutorCapability = {
 	}
 };
 /**
+* Wire shapes of the Load balancing surface (D748): the session placement
+* policy, the atomic share write, the observed placement statistics, the
+* hardware share suggestion and the stale device pins.
+*/
+/**
+* How a new detection session picks its node and device.
+*  - `least-loaded` — the historical rule: lowest `attached / weight`, a
+*    constant node order at a tie (D37). An idle node always ties at 0, so a
+*    weight only bites once a node already holds a session.
+*  - `share` — the share of PARALLEL sessions is held to the weights, and a
+*    full or drowning node yields to a free one (D748).
+*/
+var SessionPlacementPolicySchema = _enum(["least-loaded", "share"]);
+var DEFAULT_SESSION_PLACEMENT_POLICY = "least-loaded";
+/** The global-settings key the policy is stored under (orchestrator `load` section). */
+var SESSION_PLACEMENT_SETTING_KEY = "sessionPlacement";
+/** Parse a stored value; anything unknown is the default (nothing changes on deploy). */
+function parseSessionPlacementPolicy(value) {
+	const parsed = SessionPlacementPolicySchema.safeParse(value);
+	return parsed.success ? parsed.data : DEFAULT_SESSION_PLACEMENT_POLICY;
+}
+var LoadBalancingSharesInputSchema = object({
+	/** nodeId → share (> 0). A node left out keeps its weight. */
+	nodes: record(string(), number().positive()).default({}),
+	/** nodeId → deviceKey → share (> 0). A device left out keeps its weight. */
+	devices: record(string(), record(string(), number().positive())).default({})
+});
+var PlacementStatsInputSchema = object({ 
+/** Window the observed shares are averaged over (default 1 h, max 24 h). */
+windowMs: number().int().min(6e4).max(1440 * 60 * 1e3).default(3600 * 1e3) });
+var PlacementDeviceStatsSchema = object({
+	deviceKey: string(),
+	/** Sessions running on this device now. */
+	sessionsNow: number(),
+	/** Sessions started on this device inside the window. */
+	sessionsStarted: number(),
+	/** Time-weighted share of the node's parallel sessions over the window (0–1); null = no session ran. */
+	observedShare: number().nullable()
+});
+var PlacementNodeStatsSchema = object({
+	nodeId: string(),
+	sessionsNow: number(),
+	sessionsStarted: number(),
+	/** Time-weighted share of the cluster's parallel sessions over the window (0–1); null = none ran. */
+	observedShare: number().nullable(),
+	/** Most sessions this node ran at once inside the window. */
+	peakSessions: number(),
+	/** Sessions a share election handed elsewhere because this node was full or drowning. */
+	yieldsAway: number(),
+	devices: array(PlacementDeviceStatsSchema).readonly()
+});
+/** A camera's device pin that the session path cannot honour. */
+var StaleDevicePinSchema = object({
+	deviceId: number(),
+	deviceKey: string(),
+	/** `disabled` — the key exists on some node but is not enabled anywhere; `absent` — no node has it. */
+	reason: _enum(["disabled", "absent"])
+});
+var PlacementStatsSchema = object({
+	policy: SessionPlacementPolicySchema,
+	windowMs: number(),
+	/** How much of the window was actually observed (the hub keeps it in memory). */
+	observedForMs: number(),
+	sessionsNow: number(),
+	/** Most parallel sessions across the cluster inside the window. */
+	clusterPeakSessions: number(),
+	nodes: array(PlacementNodeStatsSchema).readonly(),
+	stalePins: array(StaleDevicePinSchema).readonly()
+});
+var SuggestSharesInputSchema = object({ headroom: number().min(.3).max(.5).default(.4) });
+var SuggestedDeviceShareSchema = object({
+	deviceKey: string(),
+	/** Share of the node (0–100, rounded). */
+	share: number(),
+	modelId: string().nullable(),
+	/** Inferences per second at that model, from the measured table. */
+	fps: number().nullable(),
+	measured: boolean(),
+	/** Advisory session cap: ⌊fps × (1 − headroom) / camera fps⌋. Never enforced. */
+	suggestedMaxSessions: number().nullable()
+});
+var SuggestedNodeShareSchema = object({
+	nodeId: string(),
+	/** Share of the cluster (0–100, rounded); null = node skipped (offline, unknown hardware). */
+	share: number().nullable(),
+	/** Parallel sessions the node sustains at the suggested models with the headroom kept free. */
+	capacitySessions: number(),
+	devices: array(SuggestedDeviceShareSchema).readonly(),
+	skippedReason: string().nullable()
+});
+var SuggestSharesResultSchema = object({
+	headroom: number(),
+	/** Camera detection rate the capacity is counted in (the fastest camera's fps). */
+	cameraFps: number(),
+	/** How many share → model → capacity rounds ran before the shares stopped moving (≤ 3). */
+	iterations: number(),
+	nodes: array(SuggestedNodeShareSchema).readonly()
+});
+/**
 * The wire shapes of the Best settings plan and apply (D745), used by the
 * `pipeline-orchestrator` cap. The recommender's own types
 * (`recommend.ts`, `demand.ts`) are the TS face of the same data; these
@@ -25081,7 +25180,9 @@ var DeviceDemandSchema = object({
 		"estimate",
 		"none"
 	]),
-	observedForMs: number().nullable()
+	observedForMs: number().nullable(),
+	/** How on-motion sessions were charged: per-device observation, or split by share (D748). */
+	placement: SessionPlacementPolicySchema
 });
 var DeviceModelChoiceSchema = object({
 	modelId: string(),
@@ -25153,14 +25254,24 @@ var BestSettingsWarningSchema = discriminatedUnion("kind", [
 		deviceKey: string()
 	})
 ]);
-var BestSettingsOptionsSchema = object({ 
-/** Share of each accelerator's throughput kept free (0.3–0.5). */
-headroom: number().min(.3).max(.5).default(.4) });
+var BestSettingsOptionsSchema = object({
+	/** Share of each accelerator's throughput kept free (0.3–0.5). */
+	headroom: number().min(.3).max(.5).default(.4),
+	/**
+	* What-if shares (D748): plan as if these node/device shares were stored
+	* and the policy were `share`. Absent = the stored shares under the stored
+	* policy. A what-if plan is for display; apply always re-plans from what
+	* is stored.
+	*/
+	shares: LoadBalancingSharesInputSchema.optional()
+});
 var BestSettingsPlanSchema = object({
 	/** Hash of everything the apply will write — the apply refuses a different one. */
 	planHash: string(),
 	family: literal("yolov9"),
 	headroom: number(),
+	/** Planned under what-if shares (D748): for display — apply refuses it as stale. */
+	whatIf: boolean(),
 	generatedAt: number(),
 	nodes: array(NodeRecommendationSchema).readonly(),
 	nodeChanges: array(NodeDeviceChangeSchema).readonly(),
@@ -26610,7 +26721,6 @@ var CameraStepOverridePatchSchema = object({
 	settings: record(string(), unknown()).readonly().optional()
 });
 var CameraPipelineSettingsSchema = object({
-	pinnedAgentNodeId: string().optional(),
 	stepToggles: record(string(), boolean()).optional(),
 	stepOverridesByDevice: record(string(), record(string(), record(string(), CameraStepOverridePatchSchema))).optional(),
 	pipelineByAgent: record(string(), CameraPipelineForAgentSchema).optional()
@@ -27258,18 +27368,6 @@ var pipelineOrchestratorCapability = {
 			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`).
@@ -27409,6 +27507,33 @@ var pipelineOrchestratorCapability = {
 			kind: "mutation",
 			auth: "admin"
 		}),
+		/**
+		* Load balancing (D748) — write node shares (`detectWeight`) and per-node
+		* device shares (inference-device `weight`) in ONE atomic read-modify-write
+		* of the agent settings — the only writer of node shares (the per-node
+		* `setAgentDetectWeight` it replaced raced its siblings, one RMW each).
+		* A node or device left out keeps its weight. Never changes the
+		* `sessionPlacement` policy.
+		*/
+		setLoadBalancingShares: method(LoadBalancingSharesInputSchema, object({ success: literal(true) }), {
+			kind: "mutation",
+			auth: "admin"
+		}),
+		/**
+		* Load balancing (D748) — what placement actually did: per node and
+		* device, sessions now, sessions started and the time-weighted share of
+		* PARALLEL sessions over `windowMs`; the cluster's parallel peak; yields
+		* a share election made; and every device pin the session path cannot
+		* honour. In memory on the hub — a restart starts a new window.
+		*/
+		getPlacementStats: method(PlacementStatsInputSchema, PlacementStatsSchema, { auth: "admin" }),
+		/**
+		* Load balancing (D748) — shares proportional to each node's measured
+		* capacity at the models Best settings would pick, iterated (≤ 3 rounds)
+		* until the shares stop moving; per device, an ADVISORY session cap.
+		* Writes nothing.
+		*/
+		suggestShares: method(SuggestSharesInputSchema, SuggestSharesResultSchema, { 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. */
@@ -43588,6 +43713,12 @@ Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"pipelineOrchestrator.getPlacementStats": {
+		capName: "pipeline-orchestrator",
+		capScope: "system",
+		addonId: null,
+		access: "view"
+	},
 	"pipelineOrchestrator.getReconcileFromDiskStatus": {
 		capName: "pipeline-orchestrator",
 		capScope: "system",
@@ -43678,12 +43809,6 @@ Object.freeze({
 		addonId: null,
 		access: "create"
 	},
-	"pipelineOrchestrator.setAgentDetectWeight": {
-		capName: "pipeline-orchestrator",
-		capScope: "system",
-		addonId: null,
-		access: "create"
-	},
 	"pipelineOrchestrator.setAgentInferenceDevices": {
 		capName: "pipeline-orchestrator",
 		capScope: "system",
@@ -43738,12 +43863,24 @@ Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"pipelineOrchestrator.setLoadBalancingShares": {
+		capName: "pipeline-orchestrator",
+		capScope: "system",
+		addonId: null,
+		access: "create"
+	},
 	"pipelineOrchestrator.setPipelineDevicePin": {
 		capName: "pipeline-orchestrator",
 		capScope: "system",
 		addonId: null,
 		access: "create"
 	},
+	"pipelineOrchestrator.suggestShares": {
+		capName: "pipeline-orchestrator",
+		capScope: "system",
+		addonId: null,
+		access: "view"
+	},
 	"pipelineOrchestrator.unassignAudio": {
 		capName: "pipeline-orchestrator",
 		capScope: "system",
@@ -51493,6 +51630,7 @@ function estimatedConcurrentSessions(cameraCount, options) {
 */
 function estimateDeviceDemand(input) {
 	const options = input.options ?? DEFAULT_DEMAND_OPTIONS;
+	const placement = input.shares ? "share" : "least-loaded";
 	const eligibleById = new Map(input.eligible.map((d) => [deviceId(d.nodeId, d.deviceKey), d]));
 	const peakById = new Map(input.peaks.map((p) => [deviceId(p.nodeId, p.deviceKey), p]));
 	const weightByNode = /* @__PURE__ */ new Map();
@@ -51512,19 +51650,28 @@ function estimateDeviceDemand(input) {
 	const noteMax = (key, fps) => {
 		maxFps.set(key, Math.max(maxFps.get(key) ?? 0, fps));
 	};
+	const pinNodeOf = (pin) => {
+		if (pin.nodeId !== null) return pin.nodeId;
+		const holders = input.eligible.filter((d) => d.deviceKey === pin.deviceKey);
+		return holders.length === 1 ? holders[0].nodeId : null;
+	};
+	let alwaysOnTotal = 0;
 	for (const cam of input.cameras) {
 		if (!charges(cam)) continue;
-		if (cam.devicePin !== null) {
-			const key = deviceId(cam.devicePin.nodeId, cam.devicePin.deviceKey);
+		const pinNode = cam.devicePin !== null ? pinNodeOf(cam.devicePin) : null;
+		if (cam.devicePin !== null && pinNode !== null) {
+			const key = deviceId(pinNode, cam.devicePin.deviceKey);
 			if (!eligibleById.has(key)) continue;
 			bump(pinnedFps, key, cam.fps);
 			noteMax(key, cam.fps);
 			continue;
 		}
-		if (cam.mode === "always-on" && cam.standingNodeId !== null) {
-			const nodeWeight = weightByNode.get(cam.standingNodeId) ?? 0;
+		const standing = cam.mode === "always-on" && cam.standingNodeId !== null ? cam.standingNodeId : cam.nodePinId;
+		if (standing !== null) {
+			if (cam.mode === "always-on") alwaysOnTotal += 1;
+			const nodeWeight = weightByNode.get(standing) ?? 0;
 			for (const d of input.eligible) {
-				if (d.nodeId !== cam.standingNodeId || nodeWeight <= 0) continue;
+				if (d.nodeId !== standing || nodeWeight <= 0) continue;
 				const key = deviceId(d.nodeId, d.deviceKey);
 				const share = Math.max(d.weight, 0) / nodeWeight;
 				bump(alwaysOnFps, key, cam.fps * share);
@@ -51538,13 +51685,23 @@ function estimateDeviceDemand(input) {
 	const fastestOnMotion = onMotionRates.reduce((m, r) => Math.max(m, r), 0);
 	const nodeCount = weightByNode.size;
 	const estimatedTotal = estimatedConcurrentSessions(onMotionRates.length, options);
+	const clusterPeak = input.shares?.clusterPeak ?? null;
+	const clusterObserved = clusterPeak !== null && clusterPeak.observedForMs >= 864e5;
+	const clusterSessions = clusterObserved ? Math.max(0, clusterPeak.peakSessions - alwaysOnTotal) : estimatedTotal;
+	const shareSum = [...weightByNode.keys()].reduce((sum, nodeId) => sum + Math.max(input.shares?.nodes[nodeId] ?? 0, 0), 0);
 	return input.eligible.map((d) => {
 		const key = deviceId(d.nodeId, d.deviceKey);
 		const peak = peakById.get(key) ?? (eligibleCountByNode.get(d.nodeId) === 1 ? peakById.get(deviceId(d.nodeId, "")) : void 0);
 		const alwaysOn = alwaysOnCount.get(key) ?? 0;
 		let onMotionSessions = 0;
 		let onMotionSource = "none";
-		if (onMotionRates.length > 0) if (peak !== void 0 && peak.observedForMs >= 864e5) {
+		if (onMotionRates.length > 0 && input.shares !== void 0) {
+			const nodeWeight = weightByNode.get(d.nodeId) ?? 0;
+			const nodeShare = shareSum > 0 ? Math.max(input.shares.nodes[d.nodeId] ?? 0, 0) / shareSum : 0;
+			const deviceShare = nodeWeight > 0 ? Math.max(d.weight, 0) / nodeWeight : 0;
+			onMotionSessions = Math.max(0, Math.ceil(clusterSessions * nodeShare * deviceShare - 1e-9));
+			onMotionSource = clusterObserved ? "observed-24h" : "estimate";
+		} else if (onMotionRates.length > 0) if (peak !== void 0 && peak.observedForMs >= 864e5) {
 			onMotionSessions = Math.max(0, Math.round(peak.peakSessions - alwaysOn));
 			onMotionSource = "observed-24h";
 		} else {
@@ -51562,7 +51719,8 @@ function estimateDeviceDemand(input) {
 			alwaysOnCameras: Math.round(alwaysOn * 100) / 100,
 			onMotionSessions,
 			onMotionSource,
-			observedForMs: peak?.observedForMs ?? null
+			observedForMs: input.shares !== void 0 ? clusterPeak?.observedForMs ?? null : peak?.observedForMs ?? null,
+			placement
 		};
 	}).toSorted((a, b) => a.nodeId === b.nodeId ? a.deviceKey.localeCompare(b.deviceKey) : a.nodeId.localeCompare(b.nodeId));
 }
@@ -51791,6 +51949,46 @@ function recommendNode(input) {
 		reasons: nodeReasons
 	};
 }
+/** Deficits equal up to float noise (0.7 × 2 − 1 is 0.3999…, not 0.4). */
+var DEFICIT_EPSILON = 1e-9;
+function byDeficit(a, b) {
+	const diff = b.deficit - a.deficit;
+	return (Math.abs(diff) < DEFICIT_EPSILON ? 0 : diff) || b.candidate.share - a.candidate.share || a.candidate.key.localeCompare(b.candidate.key);
+}
+function spareOf(c) {
+	return c.spare ?? Number.POSITIVE_INFINITY;
+}
+function electByShare(candidates) {
+	if (candidates.length === 0) return { kind: "none" };
+	const shareSum = candidates.reduce((s, c) => s + Math.max(c.share, 0), 0);
+	const running = candidates.reduce((s, c) => s + Math.max(c.running, 0), 0);
+	const scored = candidates.map((candidate) => ({
+		candidate,
+		deficit: (shareSum > 0 ? Math.max(candidate.share, 0) / shareSum : 1 / candidates.length) * (running + 1) - candidate.running
+	})).toSorted(byDeficit);
+	const turn = scored[0].candidate;
+	if (!turn.capped && !turn.saturated) return {
+		kind: "elected",
+		key: turn.key,
+		reason: "share"
+	};
+	const free = scored.filter((s) => !s.candidate.capped && !s.candidate.saturated).toSorted((a, b) => spareOf(b.candidate) - spareOf(a.candidate) || byDeficit(a, b));
+	const yieldReason = turn.capped ? "at-cap" : "saturated";
+	if (free.length > 0) return {
+		kind: "elected",
+		key: free[0].candidate.key,
+		reason: "yield",
+		turnKey: turn.key,
+		yieldReason
+	};
+	const uncapped = scored.find((s) => !s.candidate.capped);
+	if (uncapped === void 0) return { kind: "none" };
+	return {
+		kind: "elected",
+		key: uncapped.candidate.key,
+		reason: "share"
+	};
+}
 /**
 * THE detail-crop convention — the single derivation of the rectangle a
 * detail/enrichment step (clip-embedding, face-detection, plate-detection…)
@@ -59853,6 +60051,35 @@ function pickInferenceDevice(input) {
 	const loadByKey = new Map((input.loads ?? []).map((l) => [l.deviceKey, l]));
 	const healthyKeys = eligibleKeys.filter((k) => !isDeviceSaturated(loadByKey.get(k)));
 	const consideredKeys = pin !== null || healthyKeys.length === 0 || healthyKeys.length === eligibleKeys.length ? eligibleKeys : healthyKeys;
+	if (input.policy === "share" && pin === null) {
+		const election = electByShare(eligibleKeys.map((key) => {
+			const load = loadByKey.get(key);
+			const attached = load?.attachedCameras ?? 0;
+			const cap = input.caps?.[key];
+			const hasCap = cap !== null && cap !== void 0 && cap > 0;
+			return {
+				key,
+				share: input.eligible[key] ?? 1,
+				running: attached,
+				capped: hasCap && attached >= cap,
+				saturated: isDeviceSaturated(load),
+				...hasCap ? { spare: Math.max(0, cap - attached) } : {}
+			};
+		}));
+		if (election.kind === "none") return {
+			kind: "default-pool",
+			reason: "all-devices-at-cap",
+			eligibleKeys
+		};
+		return {
+			kind: "selected",
+			deviceKey: election.key,
+			reason: "share",
+			tieBreak: null,
+			eligibleKeys,
+			tiedKeys: [election.key]
+		};
+	}
 	const balancerInput = {
 		nodes: consideredKeys.map((k) => deviceAsLoad(k, loadByKey.get(k))),
 		preferredAgent: pin,
@@ -64176,7 +64403,6 @@ var StoredCameraPipelineForAgentSchema = object({
 	}).nullable()
 });
 var StoredCameraPipelineSettingsSchema = object({
-	pinnedAgentNodeId: string().optional(),
 	stepToggles: record(string(), boolean()).optional(),
 	stepOverridesByDevice: record(string(), record(string(), record(string(), StoredCameraStepOverridePatchSchema))).optional(),
 	stepOverridesByAgent: record(string(), record(string(), LegacyCameraStepOverridePatchSchema)).optional(),
@@ -66680,7 +66906,15 @@ var TtlMemo = class {
 //#endregion
 //#region src/detection-session-registry.ts
 var DetectionSessionRegistry = class {
+	onChange;
 	sessions = /* @__PURE__ */ new Map();
+	/**
+	* @param onChange called after every register / deregister / clear with the
+	*   running set — feeds the placement statistics (D748). Never on a no-op.
+	*/
+	constructor(onChange = () => {}) {
+		this.onChange = onChange;
+	}
 	register(deviceId, nodeId, startedAt, triggeredBy, deviceKey) {
 		const existing = this.sessions.get(deviceId);
 		if (existing?.teardownTimer) clearTimeout(existing.teardownTimer);
@@ -66693,6 +66927,7 @@ var DetectionSessionRegistry = class {
 			...deviceKey ? { deviceKey } : {}
 		};
 		this.sessions.set(deviceId, session);
+		this.onChange(this.list());
 		return session;
 	}
 	get(deviceId) {
@@ -66706,6 +66941,7 @@ var DetectionSessionRegistry = class {
 		if (!session) return void 0;
 		if (session.teardownTimer) clearTimeout(session.teardownTimer);
 		this.sessions.delete(deviceId);
+		this.onChange(this.list());
 		return session;
 	}
 	setTeardownTimer(deviceId, timer) {
@@ -66728,9 +66964,39 @@ var DetectionSessionRegistry = class {
 	}
 	clear() {
 		for (const session of this.sessions.values()) if (session.teardownTimer) clearTimeout(session.teardownTimer);
+		const hadSessions = this.sessions.size > 0;
 		this.sessions.clear();
+		if (hadSessions) this.onChange([]);
 	}
 };
+//#endregion
+//#region src/session-share-placement.ts
+function nodeSaturated(load) {
+	return load.devices.length > 0 && load.devices.every((d) => isDeviceSaturated(d));
+}
+function electNodeByShare(input) {
+	return electByShare(input.loads.filter((l) => l.nodeId.length > 0 && input.eligible.includes(l.nodeId)).map((load) => {
+		const cap = input.caps[load.nodeId];
+		const hasCap = cap !== null && cap !== void 0 && cap > 0;
+		const weight = input.weights[load.nodeId];
+		return {
+			key: load.nodeId,
+			share: weight !== void 0 && weight > 0 ? weight : 1,
+			running: input.runningByNode.get(load.nodeId) ?? 0,
+			capped: hasCap && load.attachedCameras >= cap,
+			saturated: nodeSaturated(load),
+			...hasCap ? { spare: Math.max(0, cap - load.attachedCameras) } : {}
+		};
+	}));
+}
+/** Parallel sessions per node: sessions and standing cameras, each camera once. */
+function countRunningByNode(placements) {
+	const seen = /* @__PURE__ */ new Map();
+	for (const p of placements) if (!seen.has(p.deviceId)) seen.set(p.deviceId, p.nodeId);
+	const out = /* @__PURE__ */ new Map();
+	for (const nodeId of seen.values()) out.set(nodeId, (out.get(nodeId) ?? 0) + 1);
+	return out;
+}
 /**
 * Minimum time a detection session stays open, whatever closes it.
 *
@@ -66843,7 +67109,15 @@ var SessionDispatchController = class {
 	* (not `private`) — see the class doc for the two production/test reasons
 	* `index.ts` reaches through it directly.
 	*/
-	sessionRegistry = new DetectionSessionRegistry();
+	sessionRegistry = new DetectionSessionRegistry((sessions) => this.deps.placementStats?.noteSessions(sessions.map((s) => ({
+		nodeId: s.nodeId,
+		deviceKey: s.deviceKey ?? ""
+	}))));
+	/**
+	* `deviceId|deviceKey` of device pins the session path has already said it
+	* ignored — one line per stale pin, not one per session (D748).
+	*/
+	reportedStalePins = /* @__PURE__ */ new Set();
 	/**
 	* Per-device async mutex for session dispatch/teardown critical sections —
 	* backed by the generic `KeyedAsyncLock` (mirrors the audio controller's
@@ -67304,6 +67578,76 @@ var SessionDispatchController = class {
 		});
 	}
 	/**
+	* The session's node. `least-loaded` (and any node pin, under either
+	* policy) is `balance()` exactly as before. `share` holds the node shares
+	* of PARALLEL sessions (D748): sessions now running and standing cameras
+	* count toward their node, and a node at its cap or drowning yields —
+	* logged with the reason, and counted against the node in the stats.
+	*/
+	electSessionNode(input) {
+		const balanced = () => balance({
+			nodes: input.loads,
+			preferredAgent: input.preferredAgent,
+			nodeCaps: input.nodeCaps,
+			weights: input.weights,
+			eligibleNodes: input.eligible
+		});
+		if (input.policy !== "share" || input.preferredAgent) return balanced();
+		const running = countRunningByNode([...this.sessionRegistry.list().map((s) => ({
+			deviceId: s.deviceId,
+			nodeId: s.nodeId
+		})), ...this.deps.ledger.listAssignments().map((a) => ({
+			deviceId: a.deviceId,
+			nodeId: a.agentNodeId
+		}))]);
+		const election = electNodeByShare({
+			loads: input.loads,
+			eligible: input.eligible,
+			weights: input.weights,
+			caps: input.nodeCaps,
+			runningByNode: running
+		});
+		if (election.kind === "none") return balanced();
+		if (election.reason === "yield") {
+			this.deps.placementStats?.noteYield(election.turnKey);
+			this.deps.logger.info("detection session: share turn yielded — the node had no room", {
+				tags: {
+					deviceId: input.deviceId,
+					nodeId: election.key
+				},
+				meta: {
+					turnNodeId: election.turnKey,
+					reason: election.yieldReason
+				}
+			});
+		}
+		const load = input.loads.find((l) => l.nodeId === election.key);
+		return {
+			kind: "assigned",
+			agentNodeId: election.key,
+			reason: "capacity",
+			score: load ? load.attachedCameras + load.queueDepthTotal : 0
+		};
+	}
+	/**
+	* Say ONCE that a camera's device pin names a device this node does not
+	* offer (disabled, absent): the session path ignores it, and the Load
+	* balancing tab offers to clear it. Never cleared here (D748).
+	*/
+	noteStalePin(deviceId, pinnedDeviceKey, enabledDevices) {
+		if (pinnedDeviceKey === null || pinnedDeviceKey in enabledDevices) return;
+		const key = `${deviceId}|${pinnedDeviceKey}`;
+		if (this.reportedStalePins.has(key)) return;
+		this.reportedStalePins.add(key);
+		this.deps.logger.warn("device pin ignored — the pinned device is not enabled on the elected node", {
+			tags: { deviceId },
+			meta: {
+				pin: pinnedDeviceKey,
+				enabled: Object.keys(enabledDevices).join(",")
+			}
+		});
+	}
+	/**
 	* Dispatch a session-time detection attach for an on-motion camera whose
 	* `decideSessionAction` returned `'dispatch'`. Builds a session
 	* `RunnerCameraConfig` the same way `startDetection` does, but forces
@@ -67354,12 +67698,17 @@ var SessionDispatchController = class {
 		const usableEligible = allEligible.filter((n) => this.deps.isNodeInferenceUsable(n));
 		const eligible = usableEligible.length > 0 ? usableEligible : allEligible;
 		if (usableEligible.length > 0 && usableEligible.length < allEligible.length) log.info("nodes dropped from session placement — no usable inference device", { meta: { dropped: allEligible.filter((n) => !usableEligible.includes(n)) } });
-		const decision = balance({
-			nodes: loads,
+		const nodeCaps = await this.nodeCaps.get(CLUSTER_KEY);
+		const weights = await this.nodeWeights.get(CLUSTER_KEY);
+		const policy = this.deps.sessionPlacement?.() ?? "least-loaded";
+		const decision = this.electSessionNode({
+			deviceId,
+			policy,
+			loads,
 			preferredAgent,
-			nodeCaps: await this.nodeCaps.get(CLUSTER_KEY),
-			weights: await this.nodeWeights.get(CLUSTER_KEY),
-			eligibleNodes: eligible
+			nodeCaps,
+			weights,
+			eligible
 		});
 		if (!decision || decision.kind !== "assigned") {
 			log.warn("detection session: no eligible node — will retry on next motion", { meta: { reason: decision?.kind === "pending" ? decision.reason : "no-runners-online" } });
@@ -67372,12 +67721,14 @@ var SessionDispatchController = class {
 		const targetLoad = loads.find((n) => n.nodeId === targetNodeId);
 		const deviceCaps = await this.inferenceDeviceCaps.get(targetNodeId);
 		const pinnedDeviceKey = await this.deps.readPipelineDevicePin(deviceId);
+		this.noteStalePin(deviceId, pinnedDeviceKey, enabledDevices);
 		const selection = pickInferenceDevice({
 			eligible: enabledDevices,
 			loads: targetLoad?.devices ?? [],
 			caps: deviceCaps,
-			pinnedDeviceKey,
-			rotation: this.deps.inferenceRotation
+			pinnedDeviceKey: pinnedDeviceKey !== null && pinnedDeviceKey in enabledDevices ? pinnedDeviceKey : null,
+			rotation: this.deps.inferenceRotation,
+			policy
 		});
 		const deviceKey = selectedDeviceKey(selection);
 		log.info("inference device selection", {
@@ -67465,6 +67816,7 @@ var SessionDispatchController = class {
 			attachedAt = Date.now();
 			this.deps.recordAssignment(deviceId, targetNodeId, decision.reason, decision.reason === "manual");
 			this.sessionRegistry.register(deviceId, targetNodeId, Date.now(), triggeredBy, deviceKey);
+			this.deps.placementStats?.noteStart(targetNodeId, deviceKey ?? "");
 			if (this.sessionRefusals.delete(deviceId)) log.info("detection session refusal cleared — a session opened", {
 				tags: {
 					deviceId,
@@ -68734,6 +69086,7 @@ async function buildOrchestratorControllers(deps) {
 	}, 6e4);
 	nodeStress.start();
 	const inferenceRotation = new RoundRobinInferenceDeviceRotation();
+	const readSessionPlacement = () => parseSessionPlacementPolicy(globalSettings?.[SESSION_PLACEMENT_SETTING_KEY]);
 	/**
 	* Can the watchdog's audio stage ever receive a signal for this camera?
 	* Only `absent` — POSITIVE evidence of no audio track — disarms it.
@@ -68817,6 +69170,8 @@ async function buildOrchestratorControllers(deps) {
 		getInferenceDeviceCaps: (nodeId) => deps.getInferenceDeviceCaps(nodeId),
 		readPipelineDevicePin: (deviceId) => deps.readPipelineDevicePin(deviceId),
 		inferenceRotation,
+		sessionPlacement: () => readSessionPlacement(),
+		placementStats: deps.placementStats,
 		logger: deps.ctx().logger
 	});
 	const deviceConfig = new DeviceConfigContributions({
@@ -69350,7 +69705,8 @@ async function buildOrchestratorControllers(deps) {
 		unsubAgentOffline,
 		unsubOrchestratorSubscriptions,
 		pendingRetryTimer,
-		autoRebalanceTimer
+		autoRebalanceTimer,
+		sessionPlacement: () => readSessionPlacement()
 	};
 }
 //#endregion
@@ -69395,6 +69751,20 @@ function buildGlobalSettingsSections(options) {
 			title: "Load Balancer",
 			tab: "pipeline",
 			fields: [
+				{
+					key: SESSION_PLACEMENT_SETTING_KEY,
+					type: "select",
+					label: "Session placement",
+					description: "How a new detection session picks its node and device. Least-loaded = the node with the fewest sessions per unit of weight; an idle node always wins the tie, so weights only matter once nodes are busy. Honour shares = the share of PARALLEL sessions is held to the node and device weights, and a node at its cap yields to a free one. Moving a weight slider never changes this policy.",
+					options: [{
+						value: "least-loaded",
+						label: "Least-loaded"
+					}, {
+						value: "share",
+						label: "Honour shares"
+					}],
+					default: DEFAULT_SESSION_PLACEMENT_POLICY
+				},
 				{
 					key: "fpsMinThreshold",
 					type: "slider",
@@ -69974,7 +70344,7 @@ var pipelineOrchestratorWidgets = [{
 *    settings: the attach provisions the node pin over the snapshot
 *    (`applyDeviceProvisioning`: override ?? base), so once the snapshot pin
 *    is gone the node's recommended model runs.
-*  - never: `stepToggles`, `pinnedAgentNodeId`, devices' enablement, pins of
+*  - never: `stepToggles`, devices' enablement, pins of
 *    embedding steps (cluster-scoped, changing one forces a re-index).
 */
 /** The root detector step. */
@@ -70236,6 +70606,29 @@ function boundKeysOf(catalogs) {
 	}
 	return Object.fromEntries([...byStep].map(([step, set]) => [step, [...set].toSorted()]));
 }
+/** Bounded fixed point of the hardware share suggestion (D748). */
+var SUGGEST_MAX_ROUNDS = 3;
+/** Integer shares summing to 100 (largest remainder). */
+function toPercent(weights) {
+	const total = [...weights.values()].reduce((a, b) => a + b, 0);
+	const out = /* @__PURE__ */ new Map();
+	if (total <= 0) return out;
+	const raw = [...weights].map(([k, w]) => ({
+		k,
+		exact: w / total * 100
+	}));
+	let assigned = 0;
+	for (const r of raw) {
+		out.set(r.k, Math.floor(r.exact));
+		assigned += Math.floor(r.exact);
+	}
+	const byRemainder = raw.toSorted((a, b) => b.exact - Math.floor(b.exact) - (a.exact - Math.floor(a.exact)) || a.k.localeCompare(b.k));
+	for (let i = 0; i < 100 - assigned; i++) {
+		const r = byRemainder[i % byRemainder.length];
+		out.set(r.k, (out.get(r.k) ?? 0) + 1);
+	}
+	return out;
+}
 var BestSettingsService = class {
 	deps;
 	applying = false;
@@ -70243,9 +70636,87 @@ var BestSettingsService = class {
 		this.deps = deps;
 	}
 	async plan(input) {
-		return (await this.computePlan(input.headroom)).plan;
+		return (await this.computePlan(input.headroom, input.shares)).plan;
+	}
+	/**
+	* Shares proportional to each node's capacity at the models Best settings
+	* would pick under those very shares (D748). Model and load depend on each
+	* other, so it iterates from equal shares until the rounded shares stop
+	* moving, at most {@link SUGGEST_MAX_ROUNDS} rounds. Per device it reports an
+	* ADVISORY session cap — never written, never enforced.
+	*/
+	async suggestShares(input) {
+		let shares = {
+			nodes: {},
+			devices: {}
+		};
+		let result = [];
+		let cameraFps = 10;
+		let rounds = 0;
+		for (let round = 1; round <= SUGGEST_MAX_ROUNDS; round++) {
+			rounds = round;
+			const rec = await this.recommend(input.headroom, shares);
+			cameraFps = rec.cameraFps;
+			result = this.sharesFrom(rec, input.headroom);
+			const next = {
+				nodes: Object.fromEntries(result.flatMap((n) => n.share !== null && n.share > 0 ? [[n.nodeId, n.share]] : [])),
+				devices: Object.fromEntries(result.map((n) => [n.nodeId, Object.fromEntries(n.devices.flatMap((d) => d.share > 0 ? [[d.deviceKey, d.share]] : []))]))
+			};
+			const settled = JSON.stringify(next) === JSON.stringify(shares);
+			shares = next;
+			if (settled) break;
+		}
+		return {
+			headroom: input.headroom,
+			cameraFps,
+			iterations: rounds,
+			nodes: [...result]
+		};
 	}
-	async computePlan(headroom) {
+	sharesFrom(rec, headroom) {
+		const capacityByNode = /* @__PURE__ */ new Map();
+		const perNode = rec.recommendations.map((r) => {
+			const devices = r.devices.filter((d) => d.enabled && d.available && d.chosen !== null).map((d) => {
+				const fps = d.chosen?.fps ?? 0;
+				return {
+					d,
+					fps,
+					sessions: rec.cameraFps > 0 ? Math.floor(fps * (1 - headroom) / rec.cameraFps) : 0
+				};
+			});
+			const capacity = devices.reduce((sum, x) => sum + x.sessions, 0);
+			if (!r.skipped && capacity > 0) capacityByNode.set(r.nodeId, capacity);
+			return {
+				r,
+				devices,
+				capacity
+			};
+		});
+		const nodePct = toPercent(capacityByNode);
+		return perNode.map(({ r, devices, capacity }) => {
+			const devicePct = toPercent(new Map(devices.map((x) => [x.d.deviceKey, Math.max(x.fps, 0)])));
+			return {
+				nodeId: r.nodeId,
+				share: nodePct.get(r.nodeId) ?? null,
+				capacitySessions: capacity,
+				skippedReason: r.skipped ? r.reasons[0]?.kind ?? "skipped" : capacity > 0 ? null : "no-capacity",
+				devices: devices.map((x) => ({
+					deviceKey: x.d.deviceKey,
+					share: devicePct.get(x.d.deviceKey) ?? 0,
+					modelId: x.d.chosen?.modelId ?? null,
+					fps: x.d.chosen?.fps ?? null,
+					measured: x.d.chosen?.measured ?? false,
+					suggestedMaxSessions: x.sessions
+				}))
+			};
+		});
+	}
+	/**
+	* Gather every node and recommend. `shares` (a what-if or the suggestion's
+	* round) forces share placement with those shares overlaid on the stored
+	* ones; absent, the STORED policy decides how on-motion load is charged.
+	*/
+	async recommend(headroom, shares) {
 		const nodeIds = [...new Set(["hub", ...this.deps.runnerNodeIds()])].toSorted();
 		const gathered = await Promise.all(nodeIds.map(async (nodeId) => {
 			const [devices, hardware, catalog] = await Promise.all([
@@ -70260,6 +70731,7 @@ var BestSettingsService = class {
 				catalog
 			};
 		}));
+		const deviceShare = (nodeId, key, stored) => shares?.devices[nodeId]?.[key] ?? stored;
 		const nodes = gathered.map((g) => ({
 			nodeId: g.nodeId,
 			reachable: g.devices.reachable && g.catalog !== null,
@@ -70275,18 +70747,37 @@ var BestSettingsService = class {
 		const eligible = gathered.flatMap((g) => g.devices.reachable ? g.devices.devices.filter((d) => d.enabled && d.available).map((d) => ({
 			nodeId: g.nodeId,
 			deviceKey: d.key,
-			weight: d.weight
+			weight: deviceShare(g.nodeId, d.key, d.weight)
 		})) : []);
+		const cameras = await this.deps.cameraLoads();
+		const policy = shares ? "share" : this.deps.sessionPlacement();
 		const demand = estimateDeviceDemand({
-			cameras: await this.deps.cameraLoads(),
+			cameras,
 			eligible,
-			peaks: this.deps.peaks()
+			peaks: this.deps.peaks(),
+			...policy === "share" ? { shares: {
+				nodes: {
+					...await this.deps.readNodeShares(),
+					...shares?.nodes
+				},
+				clusterPeak: this.deps.clusterPeak()
+			} } : {}
 		});
 		const recommendations = nodes.map((node) => recommendNode({
 			node,
 			demand,
 			headroom
 		}));
+		const cameraFps = cameras.reduce((m, c) => c.mode !== "disabled" && c.runsPipelineRoot ? Math.max(m, c.fps) : m, 0);
+		return {
+			gathered,
+			nodes,
+			recommendations,
+			cameraFps: cameraFps > 0 ? cameraFps : 10
+		};
+	}
+	async computePlan(headroom, shares) {
+		const { gathered, nodes, recommendations } = await this.recommend(headroom, shares);
 		const touchedNodes = new Set(recommendations.filter((r) => !r.skipped).map((r) => r.nodeId));
 		const targets = /* @__PURE__ */ new Map();
 		const formats = /* @__PURE__ */ new Map();
@@ -70348,6 +70839,7 @@ var BestSettingsService = class {
 				planHash: createHash("sha256").update(canonical({
 					version: 1,
 					headroom,
+					whatIf: shares ?? null,
 					picks: recommendations.map((r) => ({
 						nodeId: r.nodeId,
 						skipped: r.skipped,
@@ -70359,6 +70851,7 @@ var BestSettingsService = class {
 				})).digest("hex"),
 				family: "yolov9",
 				headroom,
+				whatIf: shares !== void 0,
 				generatedAt: this.deps.now(),
 				nodes: recommendations,
 				nodeChanges: [...nodeChanges],
@@ -70531,6 +71024,7 @@ var BUCKET_MS = 3600 * 1e3;
 var DevicePeakTracker = class DevicePeakTracker {
 	now;
 	series = /* @__PURE__ */ new Map();
+	cluster = null;
 	constructor(now = () => Date.now()) {
 		this.now = now;
 	}
@@ -70541,12 +71035,14 @@ var DevicePeakTracker = class DevicePeakTracker {
 	noteCensus(loads) {
 		const now = this.now();
 		const bucket = now - now % BUCKET_MS;
+		let clusterTotal = 0;
 		for (const load of loads) {
 			const rows = load.devices.length > 0 ? load.devices : [{
 				deviceKey: "",
 				attachedCameras: load.attachedCameras
 			}];
 			for (const device of rows) {
+				clusterTotal += device.attachedCameras;
 				const key = DevicePeakTracker.key(load.nodeId, device.deviceKey);
 				let s = this.series.get(key);
 				if (s === void 0) {
@@ -70560,6 +71056,26 @@ var DevicePeakTracker = class DevicePeakTracker {
 				for (const start of s.buckets.keys()) if (start + BUCKET_MS <= now - 864e5) s.buckets.delete(start);
 			}
 		}
+		if (loads.length === 0) return;
+		const c = this.cluster ?? {
+			firstSeenAt: now,
+			buckets: /* @__PURE__ */ new Map()
+		};
+		this.cluster = c;
+		c.buckets.set(bucket, Math.max(c.buckets.get(bucket) ?? 0, clusterTotal));
+		for (const start of c.buckets.keys()) if (start + BUCKET_MS <= now - 864e5) c.buckets.delete(start);
+	}
+	/** The cluster-wide parallel peak over the window, or null before any census. */
+	clusterPeak() {
+		const c = this.cluster;
+		if (c === null) return null;
+		const now = this.now();
+		let peak = 0;
+		for (const [start, value] of c.buckets) if (start + BUCKET_MS > now - 864e5) peak = Math.max(peak, value);
+		return {
+			peakSessions: peak,
+			observedForMs: now - c.firstSeenAt
+		};
 	}
 	/** Every observed device's peak over the window and how long it has been watched. */
 	peaks() {
@@ -70580,6 +71096,186 @@ var DevicePeakTracker = class DevicePeakTracker {
 	}
 };
 //#endregion
+//#region src/session-placement-stats.ts
+var RETAIN_MS = 1440 * 60 * 1e3;
+function keyOf(nodeId, deviceKey) {
+	return `${nodeId}\u0000${deviceKey}`;
+}
+function split(key) {
+	const [nodeId = "", deviceKey = ""] = key.split("\0");
+	return {
+		nodeId,
+		deviceKey
+	};
+}
+var SessionPlacementStats = class {
+	now;
+	segments = [];
+	starts = [];
+	yields = [];
+	startedAt;
+	constructor(now = () => Date.now()) {
+		this.now = now;
+		this.startedAt = now();
+	}
+	/** The running-session set changed: open a new segment with these counts. */
+	noteSessions(sessions) {
+		const counts = /* @__PURE__ */ new Map();
+		for (const s of sessions) {
+			const k = keyOf(s.nodeId, s.deviceKey);
+			counts.set(k, (counts.get(k) ?? 0) + 1);
+		}
+		this.segments.push({
+			at: this.now(),
+			counts
+		});
+		this.prune();
+	}
+	noteStart(nodeId, deviceKey) {
+		this.starts.push({
+			at: this.now(),
+			nodeId,
+			deviceKey
+		});
+		this.prune();
+	}
+	/** A share election handed `nodeId`'s turn to another node. */
+	noteYield(nodeId) {
+		this.yields.push({
+			at: this.now(),
+			nodeId
+		});
+		this.prune();
+	}
+	/** For tests: how many segments are retained. */
+	segmentCount() {
+		return this.segments.length;
+	}
+	prune() {
+		const floor = this.now() - RETAIN_MS;
+		while (this.segments.length > 1 && this.segments[1].at <= floor) this.segments.shift();
+		while (this.starts.length > 0 && this.starts[0].at < floor) this.starts.shift();
+		while (this.yields.length > 0 && this.yields[0].at < floor) this.yields.shift();
+	}
+	snapshot(windowMs) {
+		const now = this.now();
+		const from = now - windowMs;
+		const integral = /* @__PURE__ */ new Map();
+		let clusterPeak = 0;
+		for (let i = 0; i < this.segments.length; i++) {
+			const seg = this.segments[i];
+			const end = this.segments[i + 1]?.at ?? now;
+			const start = Math.max(seg.at, from);
+			if (end <= start) continue;
+			let total = 0;
+			for (const [k, n] of seg.counts) {
+				integral.set(k, (integral.get(k) ?? 0) + n * (end - start));
+				total += n;
+			}
+			clusterPeak = Math.max(clusterPeak, total);
+		}
+		const current = this.segments.at(-1)?.counts ?? /* @__PURE__ */ new Map();
+		const nodeIds = /* @__PURE__ */ new Set();
+		for (const k of [...integral.keys(), ...current.keys()]) nodeIds.add(split(k).nodeId);
+		for (const s of this.starts) if (s.at >= from) nodeIds.add(s.nodeId);
+		const clusterIntegral = [...integral.values()].reduce((a, b) => a + b, 0);
+		const nodes = [...nodeIds].toSorted().map((nodeId) => {
+			const deviceKeys = /* @__PURE__ */ new Set();
+			for (const k of [...integral.keys(), ...current.keys()]) {
+				const s = split(k);
+				if (s.nodeId === nodeId) deviceKeys.add(s.deviceKey);
+			}
+			for (const s of this.starts) if (s.at >= from && s.nodeId === nodeId) deviceKeys.add(s.deviceKey);
+			const nodeIntegral = [...deviceKeys].reduce((sum, d) => sum + (integral.get(keyOf(nodeId, d)) ?? 0), 0);
+			const devices = [...deviceKeys].toSorted().map((deviceKey) => ({
+				deviceKey,
+				sessionsNow: current.get(keyOf(nodeId, deviceKey)) ?? 0,
+				sessionsStarted: this.starts.filter((s) => s.at >= from && s.nodeId === nodeId && s.deviceKey === deviceKey).length,
+				observedShare: nodeIntegral > 0 ? (integral.get(keyOf(nodeId, deviceKey)) ?? 0) / nodeIntegral : null
+			}));
+			let peak = 0;
+			for (let i = 0; i < this.segments.length; i++) {
+				const seg = this.segments[i];
+				if ((this.segments[i + 1]?.at ?? now) <= Math.max(seg.at, from)) continue;
+				let n = 0;
+				for (const [k, c] of seg.counts) if (split(k).nodeId === nodeId) n += c;
+				peak = Math.max(peak, n);
+			}
+			return {
+				nodeId,
+				sessionsNow: devices.reduce((s, d) => s + d.sessionsNow, 0),
+				sessionsStarted: devices.reduce((s, d) => s + d.sessionsStarted, 0),
+				observedShare: clusterIntegral > 0 && nodeIntegral > 0 ? nodeIntegral / clusterIntegral : null,
+				peakSessions: peak,
+				yieldsAway: this.yields.filter((y) => y.at >= from && y.nodeId === nodeId).length,
+				devices
+			};
+		});
+		return {
+			observedForMs: Math.min(windowMs, now - this.startedAt),
+			sessionsNow: [...current.values()].reduce((a, b) => a + b, 0),
+			clusterPeakSessions: clusterPeak,
+			nodes
+		};
+	}
+};
+//#endregion
+//#region src/load-balancing-shares.ts
+function nextDevices(stored, shares, effective) {
+	let changed = false;
+	const out = { ...stored };
+	for (const [key, weight] of Object.entries(shares)) {
+		const existing = stored?.[key];
+		if (existing !== void 0) {
+			out[key] = {
+				...existing,
+				weight
+			};
+			changed = true;
+			continue;
+		}
+		const enabled = effective[key];
+		if (enabled === void 0) continue;
+		out[key] = {
+			enabled,
+			weight
+		};
+		changed = true;
+	}
+	return changed ? out : stored;
+}
+function applyLoadBalancingShares(prev, write) {
+	const next = { ...prev };
+	const nodeIds = new Set([...Object.keys(write.nodes), ...Object.keys(write.devices)]);
+	for (const nodeId of nodeIds) {
+		const existing = prev[nodeId];
+		const nodeShare = write.nodes[nodeId];
+		const devices = nextDevices(existing?.inferenceDevices, write.devices[nodeId] ?? {}, write.effectiveEnabled[nodeId] ?? {});
+		if (nodeShare === void 0 && devices === existing?.inferenceDevices) continue;
+		next[nodeId] = {
+			...existing ?? { maxCameras: null },
+			...nodeShare !== void 0 ? { detectWeight: nodeShare } : {},
+			...devices !== void 0 ? { inferenceDevices: devices } : {}
+		};
+	}
+	return next;
+}
+//#endregion
+//#region src/stale-device-pins.ts
+function findStaleDevicePins(pins, nodes) {
+	const usable = /* @__PURE__ */ new Map();
+	for (const node of nodes) for (const d of node.devices) usable.set(d.key, (usable.get(d.key) ?? false) || d.enabled && d.available);
+	return pins.flatMap((pin) => {
+		const state = usable.get(pin.deviceKey);
+		if (state === true) return [];
+		return [{
+			deviceId: pin.deviceId,
+			deviceKey: pin.deviceKey,
+			reason: state === false ? "disabled" : "absent"
+		}];
+	}).toSorted((a, b) => a.deviceId - b.deviceId);
+}
+//#endregion
 //#region src/index.ts
 /**
 * addon-pipeline-orchestrator — hub-side camera-to-agent load balancer.
@@ -70649,6 +71345,10 @@ var PipelineOrchestratorAddon = class PipelineOrchestratorAddon extends BaseAddo
 	clusterModelChoiceReady = false;
 	/** The per-device 24 h peak of concurrent sessions, fed by every runner census (D745). */
 	devicePeaks = new DevicePeakTracker();
+	/** What session placement did (D748): the Load balancing tab's "actual" column. */
+	placementStats = new SessionPlacementStats();
+	/** The stored session placement policy (D748); `least-loaded` before init. */
+	readSessionPlacement = () => "least-loaded";
 	bestSettingsService = null;
 	/**
 	* Single owner of the shared placement state (`assignments`/`cameraConfigs`/
@@ -70927,6 +71627,7 @@ var PipelineOrchestratorAddon = class PipelineOrchestratorAddon extends BaseAddo
 			setCameraPipelineForAgent: (input) => this.setCameraPipelineForAgent(input),
 			maintenancePaused: () => this.storageMigrationLeaseId !== null,
 			onRunnerCensus: (loads) => this.devicePeaks.noteCensus(loads),
+			placementStats: this.placementStats,
 			setTopology: (topology) => {
 				this.topology = topology;
 			},
@@ -70953,6 +71654,7 @@ var PipelineOrchestratorAddon = class PipelineOrchestratorAddon extends BaseAddo
 		this.nodeStress = controllers.nodeStress;
 		this.placement = controllers.placement;
 		this.session = controllers.session;
+		this.readSessionPlacement = controllers.sessionPlacement;
 		this.deviceConfig = controllers.deviceConfig;
 		this.cameraStatusService = controllers.cameraStatusService;
 		this.cameraSwitchService = controllers.cameraSwitchService;
@@ -71445,26 +72147,6 @@ var PipelineOrchestratorAddon = class PipelineOrchestratorAddon extends BaseAddo
 		this.reconcile.schedulePendingRetry();
 		return { success: true };
 	}
-	async setAgentDetectWeight(input) {
-		const existing = (await this.settingsStore.readAgentSettingsMap())[input.agentNodeId];
-		const weight = input.detectWeight ?? 1;
-		const next = existing ? {
-			...existing,
-			detectWeight: weight
-		} : {
-			maxCameras: null,
-			detectWeight: weight
-		};
-		await this.settingsStore.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
@@ -72062,6 +72744,9 @@ var PipelineOrchestratorAddon = class PipelineOrchestratorAddon extends BaseAddo
 			rewriteCameraSettings: (transform) => store.rewriteCameraSettingsMap(transform),
 			cameraLoads: () => this.bestSettingsCameraLoads(),
 			peaks: () => this.devicePeaks.peaks(),
+			clusterPeak: () => this.devicePeaks.clusterPeak(),
+			sessionPlacement: () => this.readSessionPlacement(),
+			readNodeShares: () => store.buildNodeWeights(),
 			detectorStore: async (input) => {
 				const api = this.ctx.api;
 				if (!api) throw new Error("ctx.api unavailable");
@@ -72089,19 +72774,20 @@ var PipelineOrchestratorAddon = class PipelineOrchestratorAddon extends BaseAddo
 	/** Every camera with detection started, as the recommender charges it (D745). */
 	async bestSettingsCameraLoads() {
 		const standing = new Map(this.getPipelineAssignments().map((a) => [a.deviceId, a.agentNodeId]));
-		const cameraMap = await this.settingsStore.readCameraSettingsMap();
 		const loads = [];
 		for (const [deviceId, config] of this.detectionWiring.activeDetections) {
-			const pinnedNode = cameraMap[String(deviceId)]?.pinnedAgentNodeId ?? standing.get(deviceId);
+			const nodePin = await this.readPipelinePin(deviceId);
 			const pinnedKey = await this.readPipelineDevicePin(deviceId);
+			const standingNode = config.detectionMode === "always-on" ? standing.get(deviceId) ?? null : null;
 			loads.push({
 				deviceId,
 				mode: config.detectionMode,
 				fps: config.detectionFps,
 				runsPipelineRoot: (config.detectionSources ?? ["pipeline"]).includes("pipeline"),
-				standingNodeId: config.detectionMode === "always-on" ? standing.get(deviceId) ?? null : null,
-				devicePin: pinnedKey !== null && pinnedNode !== void 0 ? {
-					nodeId: pinnedNode,
+				standingNodeId: standingNode,
+				nodePinId: nodePin,
+				devicePin: pinnedKey !== null ? {
+					nodeId: nodePin ?? standingNode,
 					deviceKey: pinnedKey
 				} : null
 			});
@@ -72111,6 +72797,62 @@ var PipelineOrchestratorAddon = class PipelineOrchestratorAddon extends BaseAddo
 	async planBestSettings(input) {
 		return this.bestSettings().plan(input);
 	}
+	/**
+	* Node + device shares in ONE read-modify-write of the agent settings. A
+	* device with no stored entry is made explicit with its effective
+	* enablement, read from the probe-aware device list. Never touches the
+	* `sessionPlacement` policy.
+	*/
+	async setLoadBalancingShares(input) {
+		const effectiveEnabled = {};
+		for (const nodeId of Object.keys(input.devices)) {
+			const read = await this.getNodeInferenceDevices({ nodeId });
+			effectiveEnabled[nodeId] = Object.fromEntries(read.devices.map((d) => [d.key, d.enabled]));
+		}
+		await this.settingsStore.rewriteAgentSettingsMap((prev) => applyLoadBalancingShares(prev, {
+			nodes: input.nodes,
+			devices: input.devices,
+			effectiveEnabled
+		}));
+		this.ctx.logger.info("load balancing shares updated", { meta: {
+			nodes: JSON.stringify(input.nodes),
+			devices: JSON.stringify(input.devices),
+			policy: this.readSessionPlacement()
+		} });
+		if (Object.keys(input.nodes).length > 0) this.rebalance().catch((err) => {
+			this.ctx.logger.warn("setLoadBalancingShares: rebalance failed", { meta: { error: errMsg$2(err) } });
+		});
+		return { success: true };
+	}
+	async getPlacementStats(input) {
+		const snap = this.placementStats.snapshot(input.windowMs);
+		return {
+			policy: this.readSessionPlacement(),
+			windowMs: input.windowMs,
+			observedForMs: snap.observedForMs,
+			sessionsNow: snap.sessionsNow,
+			clusterPeakSessions: snap.clusterPeakSessions,
+			nodes: snap.nodes,
+			stalePins: await this.listStaleDevicePins()
+		};
+	}
+	/** Device pins the session path cannot honour — see `stale-device-pins.ts`. */
+	async listStaleDevicePins() {
+		const nodeIds = [...new Set(["hub", ...this.topology.collectRunnerNodeIds()])];
+		const offered = await Promise.all(nodeIds.map(async (nodeId) => ({ devices: (await this.getNodeInferenceDevices({ nodeId }).catch(() => null))?.devices ?? [] })));
+		const pins = [];
+		for (const deviceId of this.detectionWiring.activeDetections.keys()) {
+			const deviceKey = await this.readPipelineDevicePin(deviceId);
+			if (deviceKey !== null) pins.push({
+				deviceId,
+				deviceKey
+			});
+		}
+		return findStaleDevicePins(pins, offered);
+	}
+	async suggestShares(input) {
+		return this.bestSettings().suggestShares(input);
+	}
 	async applyBestSettings(input) {
 		return this.bestSettings().apply(input);
 	}