@camstack/addon-pipeline-orchestrator 1.2.636 → 1.2.638

package/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.2.638] - 2026-10-28
+
+### Changed
+
+- Node alerts name the node by its display name and id
+
+## [1.2.637] - 2026-10-28
+
+### Changed
+
+- Raises an alert when a node joining or leaving leaves cameras that a manual rebalance would move, with a one-click Rebalance now
+
 ## [1.2.636] - 2026-10-28
 
 ### Changed

package/dist/{_virtual_mf-localSharedImportMap___mfe_internal__addon_pipeline_orchestrator_widgets-DwR2APoE.mjs → _virtual_mf-localSharedImportMap___mfe_internal__addon_pipeline_orchestrator_widgets-Hya6JCSL.mjs}

@@ -18,7 +18,7 @@ var e = {
 	},
 	"@camstack/types": {
 		name: "@camstack/types",
-		version: "1.2.438",
+		version: "1.2.440",
 		scope: ["default"],
 		loaded: !1,
 		from: "addon_pipeline_orchestrator_widgets",

package/dist/{hostInit-2ejULZGw.mjs → hostInit-BWrAZ8UU.mjs}

@@ -36,7 +36,7 @@ async function r() {
 				}
 			},
 			"@camstack/types": {
-				version: "1.2.438",
+				version: "1.2.440",
 				scope: "default",
 				shareConfig: {
 					singleton: !0,

package/dist/index.js

@@ -17661,9 +17661,21 @@ var AlertSeveritySchema = _enum([
 	"error",
 	"critical"
 ]);
+/**
+* An action that RUNS something instead of going somewhere: the admin UI calls
+* the addon's custom action (`addons.custom`) with exactly these fields. The
+* producer owns the meaning; the UI knows nothing about the addon or the kind.
+*/
+var AlertActionInvokeSchema = object({
+	addonId: string().min(1),
+	action: string().min(1),
+	input: record(string(), unknown()).optional()
+});
+/** An action has `href` (a link) OR `invoke` (a button that runs a custom action). */
 var AlertActionSchema = object({
 	label: string(),
 	href: string().optional(),
+	invoke: AlertActionInvokeSchema.optional(),
 	/**
 	* How `href` is followed. Absent / `app`: an admin-ui route (client-side).
 	* `server`: a route the HUB serves (an addon HTTP route such as an OAuth
@@ -96457,8 +96469,17 @@ var NodeStressStatsOutputSchema = object({
 		at: number()
 	})).readonly()
 });
+var RebalanceNowOutputSchema = object({
+	migrated: number(),
+	skipped: number()
+});
 var pipelineOrchestratorActions = defineCustomActions({
 	dumpState: customAction(_void(), OrchestratorDiagnosticsSchema),
+	/**
+	* A manual rebalance (margin 0) — the action behind the "Camera placement can
+	* be rebalanced" alert. Closes that alert as completed, or marks it failed.
+	*/
+	rebalanceNow: customAction(_void(), RebalanceNowOutputSchema, { auth: "admin" }),
 	nodeStressStats: customAction(NodeStressStatsInputSchema, NodeStressStatsOutputSchema, { auth: "admin" })
 });
 /**
@@ -99150,6 +99171,8 @@ var PlacementService = class {
 		const talliedLoads = () => loads.map((load) => tallyLoad(load, attachedDelta.get(load.nodeId) ?? 0, deviceDelta.get(load.nodeId)));
 		let migrated = 0;
 		const skipped = [];
+		const moves = [];
+		const dryRun = opts?.dryRun === true;
 		for (const [deviceId, config] of this.deps.ledger.configEntries()) {
 			if (opts?.onlyDeviceIds !== void 0 && !opts.onlyDeviceIds.has(deviceId)) continue;
 			if (this.deps.isIdleSessionCamera(deviceId)) continue;
@@ -99168,7 +99191,7 @@ var PlacementService = class {
 			});
 			if (!decision) continue;
 			if (decision.kind === "pending") {
-				this.handlePendingDecision(deviceId, decision.reason);
+				if (!dryRun) this.handlePendingDecision(deviceId, decision.reason);
 				continue;
 			}
 			if (current && current.agentNodeId === decision.agentNodeId) continue;
@@ -99178,6 +99201,16 @@ var PlacementService = class {
 				const targetLoad = tallied.find((l) => l.nodeId === decision.agentNodeId);
 				if (currentLoad && targetLoad && capacityImprovement(currentLoad, targetLoad, nodeWeights) < minImprovement) continue;
 			}
+			if (dryRun) {
+				if (current) bumpAttached(current.agentNodeId, -1, config.deviceKey);
+				bumpAttached(decision.agentNodeId, 1, config.deviceKey);
+				moves.push({
+					deviceId,
+					fromNodeId: current?.agentNodeId ?? null,
+					toNodeId: decision.agentNodeId
+				});
+				continue;
+			}
 			const placement = await this.resolvePlacement({
 				deviceId,
 				nodeId: decision.agentNodeId,
@@ -99220,11 +99253,28 @@ var PlacementService = class {
 				dispatchGuard.dispose();
 			}
 			migrated++;
+			moves.push({
+				deviceId,
+				fromNodeId: current?.agentNodeId ?? null,
+				toNodeId: decision.agentNodeId
+			});
+		}
+		if (dryRun) {
+			ctx.logger.debug("rebalance: plan", { meta: {
+				minImprovement,
+				wouldMove: moves.length
+			} });
+			return {
+				migrated: 0,
+				skipped,
+				moves
+			};
 		}
 		ctx.logger.info("rebalance: migrated cameras", { meta: { migrated } });
 		return {
 			migrated,
-			skipped
+			skipped,
+			moves
 		};
 	}
 	getPipelineAssignments() {
@@ -106915,6 +106965,157 @@ async function buildOrchestratorControllers(deps) {
 	};
 }
 //#endregion
+//#region src/rebalance-suggestion.ts
+var REBALANCE_SUGGESTED_ALERT_ID = "pipeline-orchestrator:rebalance-suggested";
+var NODE_NOT_USED_ALERT_PREFIX = "pipeline-orchestrator:node-not-used:";
+/** The alert category the Alert Center files both alerts under. */
+var ALERT_CATEGORY = "system";
+var DEFAULT_SUGGESTION_DEBOUNCE_MS = 9e4;
+var VERB = {
+	joined: "joined",
+	left: "left",
+	capabilities: "changed its pipeline roles"
+};
+var RebalanceSuggestion = class {
+	deps;
+	/** `name (id)` when a name distinct from the id is known, else the id. */
+	async label(nodeId) {
+		const name = await this.deps.nodeName(nodeId);
+		return name === null || name.length === 0 || name === nodeId ? nodeId : `${name} (${nodeId})`;
+	}
+	timer = null;
+	lastNote = null;
+	notUsedRaised = /* @__PURE__ */ new Set();
+	disposed = false;
+	constructor(deps) {
+		this.deps = deps;
+	}
+	/** A node event: (re)arm the single evaluation. Forked-process ids are not nodes. */
+	noteNodeEvent(note) {
+		if (this.disposed || note.nodeId.includes("/")) return;
+		this.lastNote = note;
+		if (this.timer !== null) clearTimeout(this.timer);
+		this.timer = setTimeout(() => {
+			this.timer = null;
+			this.evaluate();
+		}, this.deps.debounceMs);
+	}
+	dispose() {
+		this.disposed = true;
+		if (this.timer !== null) clearTimeout(this.timer);
+		this.timer = null;
+	}
+	async evaluate() {
+		await this.evaluateSuggestion();
+		await this.evaluateUnusedNodes();
+	}
+	async evaluateSuggestion() {
+		const { logger } = this.deps;
+		let manual;
+		let sweep;
+		try {
+			manual = await this.deps.plan(0);
+			sweep = await this.deps.plan(AUTO_REBALANCE_MIN_IMPROVEMENT);
+		} catch (err) {
+			logger.warn("rebalance suggestion: plan failed — alert left as it is", { meta: { error: err instanceof Error ? err.message : String(err) } });
+			return;
+		}
+		const sweepIds = new Set(sweep.moves.map((m) => m.deviceId));
+		const onlyManual = manual.moves.filter((m) => !sweepIds.has(m.deviceId));
+		if (onlyManual.length === 0) {
+			logger.debug("rebalance suggestion: nothing beyond the auto sweep — closing the alert", { meta: {
+				manualMoves: manual.moves.length,
+				sweepMoves: sweep.moves.length
+			} });
+			await this.complete(REBALANCE_SUGGESTED_ALERT_ID);
+			return;
+		}
+		const note = this.lastNote;
+		const cause = note === null ? "The cluster changed" : `Node ${await this.label(note.nodeId)} ${VERB[note.kind]}`;
+		const count = manual.moves.length;
+		const now = this.deps.now();
+		logger.info("rebalance suggestion: raising the alert", { meta: {
+			manualMoves: count,
+			beyondSweep: onlyManual.length
+		} });
+		await this.emit({
+			id: REBALANCE_SUGGESTED_ALERT_ID,
+			category: ALERT_CATEGORY,
+			severity: "warning",
+			title: "Camera placement can be rebalanced",
+			message: `${cause}. ${String(count)} ${count === 1 ? "camera" : "cameras"} would move to even out the load; the automatic balancing will not do it on its own.`,
+			action: {
+				label: "Rebalance now",
+				invoke: {
+					addonId: this.deps.addonId,
+					action: "rebalanceNow"
+				}
+			},
+			status: "active",
+			read: false,
+			createdAt: now,
+			updatedAt: now,
+			source: {
+				type: "addon",
+				id: this.deps.addonId
+			}
+		});
+	}
+	async evaluateUnusedNodes() {
+		const enabled = new Set(this.deps.enabledNodes());
+		const unused = new Set(this.deps.runnerNodes().filter((id) => !enabled.has(id)));
+		for (const nodeId of unused) {
+			const id = `${NODE_NOT_USED_ALERT_PREFIX}${nodeId}`;
+			if (this.notUsedRaised.has(id)) continue;
+			this.notUsedRaised.add(id);
+			this.deps.logger.info("rebalance suggestion: node online but not used for detection", { tags: { nodeId } });
+			const now = this.deps.now();
+			await this.emit({
+				id,
+				category: ALERT_CATEGORY,
+				severity: "info",
+				title: "Node is not used for detection",
+				message: `Node ${await this.label(nodeId)} is online but detection is not enabled on it, so no camera will be placed there.`,
+				action: {
+					label: "Open node",
+					href: `/system/pipeline?view=nodes&node=${encodeURIComponent(nodeId)}`,
+					navigation: "app"
+				},
+				status: "active",
+				read: false,
+				createdAt: now,
+				updatedAt: now,
+				source: {
+					type: "node",
+					id: nodeId
+				}
+			});
+		}
+		for (const id of [...this.notUsedRaised]) {
+			const nodeId = id.slice(36);
+			if (unused.has(nodeId)) continue;
+			this.notUsedRaised.delete(id);
+			await this.complete(id);
+		}
+	}
+	async emit(alert) {
+		await this.deps.alerts.emit(alert).catch((err) => {
+			this.deps.logger.warn("rebalance suggestion: could not raise an alert", { meta: {
+				alertId: alert.id,
+				error: err instanceof Error ? err.message : String(err)
+			} });
+		});
+	}
+	async complete(alertId) {
+		await this.deps.alerts.complete(alertId).catch((err) => {
+			this.deps.logger.debug("rebalance suggestion: close failed (alert may not exist)", { meta: {
+				alertId,
+				error: err instanceof Error ? err.message : String(err)
+			} });
+		});
+	}
+};
+//#endregion
 //#region src/settings-ui-schemas.ts
 /** Build the addon-level schema sections (cluster roles + crop + balancer + failover). */
 function buildGlobalSettingsSections(options) {
@@ -108711,6 +108912,9 @@ var PipelineOrchestratorAddon = class PipelineOrchestratorAddon extends BaseAddo
 	* Constructed right after `loadShed`. Nulled at the end of `onShutdown`.
 	*/
 	placement = null;
+	/** The debounced "placement can be rebalanced" evaluation; see `rebalance-suggestion.ts`. */
+	rebalanceSuggestion = null;
+	unsubSuggestionEvents = [];
 	/** EventBus unsubscribes for agent online/offline events. */
 	unsubAgentOnline = null;
 	unsubAgentOffline = null;
@@ -108984,6 +109188,7 @@ var PipelineOrchestratorAddon = class PipelineOrchestratorAddon extends BaseAddo
 		this.localNodeId = controllers.localNodeId;
 		this.unsubAgentOnline = controllers.unsubAgentOnline;
 		this.unsubAgentOffline = controllers.unsubAgentOffline;
+		this.startRebalanceSuggestion();
 		this.unsubOrchestratorSubscriptions = controllers.unsubOrchestratorSubscriptions;
 		this.pendingRetryTimer = controllers.pendingRetryTimer;
 		this.autoRebalanceTimer = controllers.autoRebalanceTimer;
@@ -109027,6 +109232,7 @@ var PipelineOrchestratorAddon = class PipelineOrchestratorAddon extends BaseAddo
 			customActions: pipelineOrchestratorActions,
 			actionHandlers: {
 				dumpState: async () => this.dumpDiagnostics(),
+				rebalanceNow: async () => this.rebalanceNow(),
 				nodeStressStats: async (input) => {
 					const lts = this.nodeStressLts;
 					const moves = this.nodeStress?.historyView() ?? [];
@@ -109109,6 +109315,7 @@ var PipelineOrchestratorAddon = class PipelineOrchestratorAddon extends BaseAddo
 		this.detectionWiring = null;
 		this.unsubAgentOffline?.();
 		this.unsubAgentOffline = null;
+		this.stopRebalanceSuggestion();
 		this.effectiveSharesService?.stop();
 		this.unsubAgentOnline?.();
 		this.unsubAgentOnline = null;
@@ -109175,6 +109382,101 @@ var PipelineOrchestratorAddon = class PipelineOrchestratorAddon extends BaseAddo
 	async rebalance(opts) {
 		return this.placement.rebalance(opts);
 	}
+	/**
+	* The `rebalanceNow` custom action: a manual rebalance, and the verdict on
+	* the suggestion alert that offered it. Every branch is logged.
+	*/
+	async rebalanceNow() {
+		const alertId = REBALANCE_SUGGESTED_ALERT_ID;
+		try {
+			const result = await this.rebalance({ minImprovement: 0 });
+			const message = `${String(result.migrated)} ${result.migrated === 1 ? "camera" : "cameras"} moved`;
+			this.ctx.logger.info("rebalanceNow: done", { meta: {
+				migrated: result.migrated,
+				skipped: result.skipped.length
+			} });
+			await this.ctx.api.alerts.update.mutate({
+				alertId,
+				patch: {
+					status: "completed",
+					message,
+					updatedAt: Date.now()
+				}
+			}).catch((err) => this.ctx.logger.warn("rebalanceNow: could not close the suggestion alert", { meta: { error: errMsg$2(err) } }));
+			return {
+				migrated: result.migrated,
+				skipped: result.skipped.length
+			};
+		} catch (err) {
+			const reason = errMsg$2(err);
+			this.ctx.logger.error("rebalanceNow: failed", { meta: { error: reason } });
+			await this.ctx.api.alerts.update.mutate({
+				alertId,
+				patch: {
+					status: "failed",
+					message: `Rebalance failed: ${reason}`,
+					updatedAt: Date.now()
+				}
+			}).catch((e) => this.ctx.logger.warn("rebalanceNow: could not mark the suggestion alert failed", { meta: { error: errMsg$2(e) } }));
+			throw err;
+		}
+	}
+	startRebalanceSuggestion() {
+		const ctx = this.ctx;
+		const suggestion = new RebalanceSuggestion({
+			addonId: "pipeline-orchestrator",
+			logger: ctx.logger,
+			debounceMs: DEFAULT_SUGGESTION_DEBOUNCE_MS,
+			now: () => Date.now(),
+			plan: (minImprovement) => this.rebalance({
+				minImprovement,
+				dryRun: true
+			}),
+			enabledNodes: () => this.topology?.enabledNodes ?? [],
+			runnerNodes: () => this.topology?.collectRunnerNodeIds() ?? [],
+			nodeName: async (nodeId) => {
+				try {
+					return (await ctx.api.nodes.directory.query()).nodes.find((n) => n.id === nodeId)?.name ?? null;
+				} catch {
+					return null;
+				}
+			},
+			alerts: {
+				emit: (alert) => ctx.api.alerts.emit.mutate(alert),
+				complete: (alertId) => ctx.api.alerts.update.mutate({
+					alertId,
+					patch: {
+						status: "completed",
+						updatedAt: Date.now()
+					}
+				})
+			}
+		});
+		this.rebalanceSuggestion = suggestion;
+		this.unsubSuggestionEvents = [
+			ctx.eventBus.subscribe({ category: EventCategory.AgentOnline }, (event) => suggestion.noteNodeEvent({
+				kind: "joined",
+				nodeId: event.data.agentId
+			})),
+			ctx.eventBus.subscribe({ category: EventCategory.AgentOffline }, (event) => suggestion.noteNodeEvent({
+				kind: "left",
+				nodeId: event.data.agentId
+			})),
+			ctx.eventBus.subscribe({ category: EventCategory.AgentUnregistered }, (event) => {
+				const agentId = event.data["agentId"];
+				if (typeof agentId === "string") suggestion.noteNodeEvent({
+					kind: "left",
+					nodeId: agentId
+				});
+			})
+		];
+	}
+	stopRebalanceSuggestion() {
+		for (const unsub of this.unsubSuggestionEvents) unsub();
+		this.unsubSuggestionEvents = [];
+		this.rebalanceSuggestion?.dispose();
+		this.rebalanceSuggestion = null;
+	}
 	getPipelineAssignments() {
 		return this.placement.getPipelineAssignments();
 	}
@@ -109530,6 +109832,10 @@ var PipelineOrchestratorAddon = class PipelineOrchestratorAddon extends BaseAddo
 		this.topology.addKnownRunnerNode(input.agentNodeId);
 		this.reconcile.schedulePendingRetry();
 		if (input.detect !== void 0) this.noteShareChange(`node-detect:${input.agentNodeId}`);
+		this.rebalanceSuggestion?.noteNodeEvent({
+			kind: "capabilities",
+			nodeId: input.agentNodeId
+		});
 		return { success: true };
 	}
 	/**

package/dist/index.mjs

@@ -17633,9 +17633,21 @@ var AlertSeveritySchema = _enum([
 	"error",
 	"critical"
 ]);
+/**
+* An action that RUNS something instead of going somewhere: the admin UI calls
+* the addon's custom action (`addons.custom`) with exactly these fields. The
+* producer owns the meaning; the UI knows nothing about the addon or the kind.
+*/
+var AlertActionInvokeSchema = object({
+	addonId: string().min(1),
+	action: string().min(1),
+	input: record(string(), unknown()).optional()
+});
+/** An action has `href` (a link) OR `invoke` (a button that runs a custom action). */
 var AlertActionSchema = object({
 	label: string(),
 	href: string().optional(),
+	invoke: AlertActionInvokeSchema.optional(),
 	/**
 	* How `href` is followed. Absent / `app`: an admin-ui route (client-side).
 	* `server`: a route the HUB serves (an addon HTTP route such as an OAuth
@@ -96429,8 +96441,17 @@ var NodeStressStatsOutputSchema = object({
 		at: number()
 	})).readonly()
 });
+var RebalanceNowOutputSchema = object({
+	migrated: number(),
+	skipped: number()
+});
 var pipelineOrchestratorActions = defineCustomActions({
 	dumpState: customAction(_void(), OrchestratorDiagnosticsSchema),
+	/**
+	* A manual rebalance (margin 0) — the action behind the "Camera placement can
+	* be rebalanced" alert. Closes that alert as completed, or marks it failed.
+	*/
+	rebalanceNow: customAction(_void(), RebalanceNowOutputSchema, { auth: "admin" }),
 	nodeStressStats: customAction(NodeStressStatsInputSchema, NodeStressStatsOutputSchema, { auth: "admin" })
 });
 /**
@@ -99122,6 +99143,8 @@ var PlacementService = class {
 		const talliedLoads = () => loads.map((load) => tallyLoad(load, attachedDelta.get(load.nodeId) ?? 0, deviceDelta.get(load.nodeId)));
 		let migrated = 0;
 		const skipped = [];
+		const moves = [];
+		const dryRun = opts?.dryRun === true;
 		for (const [deviceId, config] of this.deps.ledger.configEntries()) {
 			if (opts?.onlyDeviceIds !== void 0 && !opts.onlyDeviceIds.has(deviceId)) continue;
 			if (this.deps.isIdleSessionCamera(deviceId)) continue;
@@ -99140,7 +99163,7 @@ var PlacementService = class {
 			});
 			if (!decision) continue;
 			if (decision.kind === "pending") {
-				this.handlePendingDecision(deviceId, decision.reason);
+				if (!dryRun) this.handlePendingDecision(deviceId, decision.reason);
 				continue;
 			}
 			if (current && current.agentNodeId === decision.agentNodeId) continue;
@@ -99150,6 +99173,16 @@ var PlacementService = class {
 				const targetLoad = tallied.find((l) => l.nodeId === decision.agentNodeId);
 				if (currentLoad && targetLoad && capacityImprovement(currentLoad, targetLoad, nodeWeights) < minImprovement) continue;
 			}
+			if (dryRun) {
+				if (current) bumpAttached(current.agentNodeId, -1, config.deviceKey);
+				bumpAttached(decision.agentNodeId, 1, config.deviceKey);
+				moves.push({
+					deviceId,
+					fromNodeId: current?.agentNodeId ?? null,
+					toNodeId: decision.agentNodeId
+				});
+				continue;
+			}
 			const placement = await this.resolvePlacement({
 				deviceId,
 				nodeId: decision.agentNodeId,
@@ -99192,11 +99225,28 @@ var PlacementService = class {
 				dispatchGuard.dispose();
 			}
 			migrated++;
+			moves.push({
+				deviceId,
+				fromNodeId: current?.agentNodeId ?? null,
+				toNodeId: decision.agentNodeId
+			});
+		}
+		if (dryRun) {
+			ctx.logger.debug("rebalance: plan", { meta: {
+				minImprovement,
+				wouldMove: moves.length
+			} });
+			return {
+				migrated: 0,
+				skipped,
+				moves
+			};
 		}
 		ctx.logger.info("rebalance: migrated cameras", { meta: { migrated } });
 		return {
 			migrated,
-			skipped
+			skipped,
+			moves
 		};
 	}
 	getPipelineAssignments() {
@@ -106887,6 +106937,157 @@ async function buildOrchestratorControllers(deps) {
 	};
 }
 //#endregion
+//#region src/rebalance-suggestion.ts
+var REBALANCE_SUGGESTED_ALERT_ID = "pipeline-orchestrator:rebalance-suggested";
+var NODE_NOT_USED_ALERT_PREFIX = "pipeline-orchestrator:node-not-used:";
+/** The alert category the Alert Center files both alerts under. */
+var ALERT_CATEGORY = "system";
+var DEFAULT_SUGGESTION_DEBOUNCE_MS = 9e4;
+var VERB = {
+	joined: "joined",
+	left: "left",
+	capabilities: "changed its pipeline roles"
+};
+var RebalanceSuggestion = class {
+	deps;
+	/** `name (id)` when a name distinct from the id is known, else the id. */
+	async label(nodeId) {
+		const name = await this.deps.nodeName(nodeId);
+		return name === null || name.length === 0 || name === nodeId ? nodeId : `${name} (${nodeId})`;
+	}
+	timer = null;
+	lastNote = null;
+	notUsedRaised = /* @__PURE__ */ new Set();
+	disposed = false;
+	constructor(deps) {
+		this.deps = deps;
+	}
+	/** A node event: (re)arm the single evaluation. Forked-process ids are not nodes. */
+	noteNodeEvent(note) {
+		if (this.disposed || note.nodeId.includes("/")) return;
+		this.lastNote = note;
+		if (this.timer !== null) clearTimeout(this.timer);
+		this.timer = setTimeout(() => {
+			this.timer = null;
+			this.evaluate();
+		}, this.deps.debounceMs);
+	}
+	dispose() {
+		this.disposed = true;
+		if (this.timer !== null) clearTimeout(this.timer);
+		this.timer = null;
+	}
+	async evaluate() {
+		await this.evaluateSuggestion();
+		await this.evaluateUnusedNodes();
+	}
+	async evaluateSuggestion() {
+		const { logger } = this.deps;
+		let manual;
+		let sweep;
+		try {
+			manual = await this.deps.plan(0);
+			sweep = await this.deps.plan(AUTO_REBALANCE_MIN_IMPROVEMENT);
+		} catch (err) {
+			logger.warn("rebalance suggestion: plan failed — alert left as it is", { meta: { error: err instanceof Error ? err.message : String(err) } });
+			return;
+		}
+		const sweepIds = new Set(sweep.moves.map((m) => m.deviceId));
+		const onlyManual = manual.moves.filter((m) => !sweepIds.has(m.deviceId));
+		if (onlyManual.length === 0) {
+			logger.debug("rebalance suggestion: nothing beyond the auto sweep — closing the alert", { meta: {
+				manualMoves: manual.moves.length,
+				sweepMoves: sweep.moves.length
+			} });
+			await this.complete(REBALANCE_SUGGESTED_ALERT_ID);
+			return;
+		}
+		const note = this.lastNote;
+		const cause = note === null ? "The cluster changed" : `Node ${await this.label(note.nodeId)} ${VERB[note.kind]}`;
+		const count = manual.moves.length;
+		const now = this.deps.now();
+		logger.info("rebalance suggestion: raising the alert", { meta: {
+			manualMoves: count,
+			beyondSweep: onlyManual.length
+		} });
+		await this.emit({
+			id: REBALANCE_SUGGESTED_ALERT_ID,
+			category: ALERT_CATEGORY,
+			severity: "warning",
+			title: "Camera placement can be rebalanced",
+			message: `${cause}. ${String(count)} ${count === 1 ? "camera" : "cameras"} would move to even out the load; the automatic balancing will not do it on its own.`,
+			action: {
+				label: "Rebalance now",
+				invoke: {
+					addonId: this.deps.addonId,
+					action: "rebalanceNow"
+				}
+			},
+			status: "active",
+			read: false,
+			createdAt: now,
+			updatedAt: now,
+			source: {
+				type: "addon",
+				id: this.deps.addonId
+			}
+		});
+	}
+	async evaluateUnusedNodes() {
+		const enabled = new Set(this.deps.enabledNodes());
+		const unused = new Set(this.deps.runnerNodes().filter((id) => !enabled.has(id)));
+		for (const nodeId of unused) {
+			const id = `${NODE_NOT_USED_ALERT_PREFIX}${nodeId}`;
+			if (this.notUsedRaised.has(id)) continue;
+			this.notUsedRaised.add(id);
+			this.deps.logger.info("rebalance suggestion: node online but not used for detection", { tags: { nodeId } });
+			const now = this.deps.now();
+			await this.emit({
+				id,
+				category: ALERT_CATEGORY,
+				severity: "info",
+				title: "Node is not used for detection",
+				message: `Node ${await this.label(nodeId)} is online but detection is not enabled on it, so no camera will be placed there.`,
+				action: {
+					label: "Open node",
+					href: `/system/pipeline?view=nodes&node=${encodeURIComponent(nodeId)}`,
+					navigation: "app"
+				},
+				status: "active",
+				read: false,
+				createdAt: now,
+				updatedAt: now,
+				source: {
+					type: "node",
+					id: nodeId
+				}
+			});
+		}
+		for (const id of [...this.notUsedRaised]) {
+			const nodeId = id.slice(36);
+			if (unused.has(nodeId)) continue;
+			this.notUsedRaised.delete(id);
+			await this.complete(id);
+		}
+	}
+	async emit(alert) {
+		await this.deps.alerts.emit(alert).catch((err) => {
+			this.deps.logger.warn("rebalance suggestion: could not raise an alert", { meta: {
+				alertId: alert.id,
+				error: err instanceof Error ? err.message : String(err)
+			} });
+		});
+	}
+	async complete(alertId) {
+		await this.deps.alerts.complete(alertId).catch((err) => {
+			this.deps.logger.debug("rebalance suggestion: close failed (alert may not exist)", { meta: {
+				alertId,
+				error: err instanceof Error ? err.message : String(err)
+			} });
+		});
+	}
+};
+//#endregion
 //#region src/settings-ui-schemas.ts
 /** Build the addon-level schema sections (cluster roles + crop + balancer + failover). */
 function buildGlobalSettingsSections(options) {
@@ -108683,6 +108884,9 @@ var PipelineOrchestratorAddon = class PipelineOrchestratorAddon extends BaseAddo
 	* Constructed right after `loadShed`. Nulled at the end of `onShutdown`.
 	*/
 	placement = null;
+	/** The debounced "placement can be rebalanced" evaluation; see `rebalance-suggestion.ts`. */
+	rebalanceSuggestion = null;
+	unsubSuggestionEvents = [];
 	/** EventBus unsubscribes for agent online/offline events. */
 	unsubAgentOnline = null;
 	unsubAgentOffline = null;
@@ -108956,6 +109160,7 @@ var PipelineOrchestratorAddon = class PipelineOrchestratorAddon extends BaseAddo
 		this.localNodeId = controllers.localNodeId;
 		this.unsubAgentOnline = controllers.unsubAgentOnline;
 		this.unsubAgentOffline = controllers.unsubAgentOffline;
+		this.startRebalanceSuggestion();
 		this.unsubOrchestratorSubscriptions = controllers.unsubOrchestratorSubscriptions;
 		this.pendingRetryTimer = controllers.pendingRetryTimer;
 		this.autoRebalanceTimer = controllers.autoRebalanceTimer;
@@ -108999,6 +109204,7 @@ var PipelineOrchestratorAddon = class PipelineOrchestratorAddon extends BaseAddo
 			customActions: pipelineOrchestratorActions,
 			actionHandlers: {
 				dumpState: async () => this.dumpDiagnostics(),
+				rebalanceNow: async () => this.rebalanceNow(),
 				nodeStressStats: async (input) => {
 					const lts = this.nodeStressLts;
 					const moves = this.nodeStress?.historyView() ?? [];
@@ -109081,6 +109287,7 @@ var PipelineOrchestratorAddon = class PipelineOrchestratorAddon extends BaseAddo
 		this.detectionWiring = null;
 		this.unsubAgentOffline?.();
 		this.unsubAgentOffline = null;
+		this.stopRebalanceSuggestion();
 		this.effectiveSharesService?.stop();
 		this.unsubAgentOnline?.();
 		this.unsubAgentOnline = null;
@@ -109147,6 +109354,101 @@ var PipelineOrchestratorAddon = class PipelineOrchestratorAddon extends BaseAddo
 	async rebalance(opts) {
 		return this.placement.rebalance(opts);
 	}
+	/**
+	* The `rebalanceNow` custom action: a manual rebalance, and the verdict on
+	* the suggestion alert that offered it. Every branch is logged.
+	*/
+	async rebalanceNow() {
+		const alertId = REBALANCE_SUGGESTED_ALERT_ID;
+		try {
+			const result = await this.rebalance({ minImprovement: 0 });
+			const message = `${String(result.migrated)} ${result.migrated === 1 ? "camera" : "cameras"} moved`;
+			this.ctx.logger.info("rebalanceNow: done", { meta: {
+				migrated: result.migrated,
+				skipped: result.skipped.length
+			} });
+			await this.ctx.api.alerts.update.mutate({
+				alertId,
+				patch: {
+					status: "completed",
+					message,
+					updatedAt: Date.now()
+				}
+			}).catch((err) => this.ctx.logger.warn("rebalanceNow: could not close the suggestion alert", { meta: { error: errMsg$2(err) } }));
+			return {
+				migrated: result.migrated,
+				skipped: result.skipped.length
+			};
+		} catch (err) {
+			const reason = errMsg$2(err);
+			this.ctx.logger.error("rebalanceNow: failed", { meta: { error: reason } });
+			await this.ctx.api.alerts.update.mutate({
+				alertId,
+				patch: {
+					status: "failed",
+					message: `Rebalance failed: ${reason}`,
+					updatedAt: Date.now()
+				}
+			}).catch((e) => this.ctx.logger.warn("rebalanceNow: could not mark the suggestion alert failed", { meta: { error: errMsg$2(e) } }));
+			throw err;
+		}
+	}
+	startRebalanceSuggestion() {
+		const ctx = this.ctx;
+		const suggestion = new RebalanceSuggestion({
+			addonId: "pipeline-orchestrator",
+			logger: ctx.logger,
+			debounceMs: DEFAULT_SUGGESTION_DEBOUNCE_MS,
+			now: () => Date.now(),
+			plan: (minImprovement) => this.rebalance({
+				minImprovement,
+				dryRun: true
+			}),
+			enabledNodes: () => this.topology?.enabledNodes ?? [],
+			runnerNodes: () => this.topology?.collectRunnerNodeIds() ?? [],
+			nodeName: async (nodeId) => {
+				try {
+					return (await ctx.api.nodes.directory.query()).nodes.find((n) => n.id === nodeId)?.name ?? null;
+				} catch {
+					return null;
+				}
+			},
+			alerts: {
+				emit: (alert) => ctx.api.alerts.emit.mutate(alert),
+				complete: (alertId) => ctx.api.alerts.update.mutate({
+					alertId,
+					patch: {
+						status: "completed",
+						updatedAt: Date.now()
+					}
+				})
+			}
+		});
+		this.rebalanceSuggestion = suggestion;
+		this.unsubSuggestionEvents = [
+			ctx.eventBus.subscribe({ category: EventCategory.AgentOnline }, (event) => suggestion.noteNodeEvent({
+				kind: "joined",
+				nodeId: event.data.agentId
+			})),
+			ctx.eventBus.subscribe({ category: EventCategory.AgentOffline }, (event) => suggestion.noteNodeEvent({
+				kind: "left",
+				nodeId: event.data.agentId
+			})),
+			ctx.eventBus.subscribe({ category: EventCategory.AgentUnregistered }, (event) => {
+				const agentId = event.data["agentId"];
+				if (typeof agentId === "string") suggestion.noteNodeEvent({
+					kind: "left",
+					nodeId: agentId
+				});
+			})
+		];
+	}
+	stopRebalanceSuggestion() {
+		for (const unsub of this.unsubSuggestionEvents) unsub();
+		this.unsubSuggestionEvents = [];
+		this.rebalanceSuggestion?.dispose();
+		this.rebalanceSuggestion = null;
+	}
 	getPipelineAssignments() {
 		return this.placement.getPipelineAssignments();
 	}
@@ -109502,6 +109804,10 @@ var PipelineOrchestratorAddon = class PipelineOrchestratorAddon extends BaseAddo
 		this.topology.addKnownRunnerNode(input.agentNodeId);
 		this.reconcile.schedulePendingRetry();
 		if (input.detect !== void 0) this.noteShareChange(`node-detect:${input.agentNodeId}`);
+		this.rebalanceSuggestion?.noteNodeEvent({
+			kind: "capabilities",
+			nodeId: input.agentNodeId
+		});
 		return { success: true };
 	}
 	/**

package/dist/remoteEntry.js

@@ -30,7 +30,7 @@ async function d(e) {
 	}
 }
 async function f() {
-	return l ||= d(() => import("./_virtual_mf-localSharedImportMap___mfe_internal__addon_pipeline_orchestrator_widgets-DwR2APoE.mjs")).catch((e) => {
+	return l ||= d(() => import("./_virtual_mf-localSharedImportMap___mfe_internal__addon_pipeline_orchestrator_widgets-Hya6JCSL.mjs")).catch((e) => {
 		throw l = void 0, e;
 	}), l;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/addon-pipeline-orchestrator",
-  "version": "1.2.636",
+  "version": "1.2.638",
   "description": "Hub-side camera-to-agent load balancer — tracks runner capacity and dispatches attachCamera calls to the optimal pipeline-runner instance",
   "keywords": [
     "camstack",