@camstack/addon-provider-reolink 1.2.82 → 1.2.84

package/dist/addon.js

@@ -7199,7 +7199,7 @@ method(object({ deviceId: number() }), array(StreamSourceEntrySchema)), method(o
 * still gives the event loop a chance to drain — useful for breaking
 * up tight async loops without changing call-site semantics.
 */
-function sleep$1(ms) {
+function sleep$2(ms) {
 	return new Promise((resolve) => setTimeout(resolve, Math.max(0, ms)));
 }
 var EncodeProfileSchema = object({
@@ -12411,6 +12411,28 @@ method(object({}), object({ blocks: array(CoreBlockSchema) }), { auth: "admin" }
 	filePath: string(),
 	content: string()
 })) }), { auth: "admin" });
+/**
+* Identity — preserves literal types for downstream inference.
+*
+* The constraint is `Record<string, unknown>` (not `CustomActionsSpec`) so
+* TypeScript does not widen each entry's literal `kind`/`auth` fields to
+* the broader unions declared on `CustomActionSpec`'s default generics.
+* Shape validity is enforced separately by the `customAction(...)` helper
+* whose return type is already a `CustomActionSpec<...>`.
+*/
+function defineCustomActions(spec) {
+	return spec;
+}
+function customAction(input, output, options) {
+	return {
+		input,
+		output,
+		kind: options?.kind ?? "query",
+		auth: options?.auth ?? "protected",
+		scope: options?.scope ?? { kind: "system" },
+		...options?.caller ? { caller: "required" } : {}
+	};
+}
 function deviceCustomAction(input, output, options) {
 	return {
 		input,
@@ -13339,7 +13361,26 @@ var DiscoveryCandidateSchema = object({
 	* identity ahead of adoption. Rendering metadata (unit, precision)
 	* flows live through the cap STATUS SLICE after adoption.
 	*/
-	sourceInfo: SourceInfoSchema.optional()
+	sourceInfo: SourceInfoSchema.optional(),
+	/**
+	* Set when this candidate is a device the provider ALREADY owns.
+	*
+	* A scan cannot generally produce the identity a device was onboarded under
+	* (Reolink keys on `mac-<mac>`, learned at adopt time), so a stableId
+	* comparison never matches and an owned device looks addable. Re-adopting one
+	* overwrites its config with scan-derived values — that is how a Home Hub's
+	* Baichuan port was overwritten with its ONVIF port, taking the hub and its
+	* three child cameras offline for four hours.
+	*
+	* A provider that can recognise its own devices says so here. Absent means
+	* "not recognised", which is not the same as "known to be new" — a provider
+	* that cannot tell simply never sets it.
+	*/
+	alreadyOnboarded: boolean().optional(),
+	/** Numeric id of the device this candidate was matched to. Set with `alreadyOnboarded`. */
+	onboardedDeviceId: number().optional(),
+	/** Operator-facing name of the matched device, so the UI can say WHICH one it is. */
+	onboardedName: string().optional()
 });
 /**
 * Flat device summary returned by `createDevice` / `adoptDiscoveredDevice`.
@@ -13395,6 +13436,35 @@ var deviceProviderCapability = {
 			name: string(),
 			type: string()
 		}))),
+		/**
+		* Tear down and reconstruct ONE device in place from its persisted rows —
+		* touching no other device this provider owns.
+		*
+		* The primitive `deviceManager.migrateDevice` uses to flush the two
+		* migrated numbers: after `swapIds` the runner's live instance still
+		* carries the PRE-swap numeric id (baked into the object, its native-cap
+		* registrations and its log tags), and a live object cannot be renumbered.
+		* Before this method the only flush was restarting the whole owning addon
+		* — which took every camera the provider owns down with it (28 devices
+		* for one migrated camera, measured 2026-09-04, and the morning of the
+		* same day ~27 devices' native caps did not come back on their own).
+		*
+		* Keyed by `stableId`, deliberately: the numeric id is exactly the thing
+		* that changes. The reply carries the id the device answers on NOW.
+		* Implemented once in `BaseDeviceProvider` — decommission the live
+		* instance (if any), then re-create from the persisted row: the same
+		* teardown/rehydrate pair every graceful shutdown + boot already uses.
+		* An RPC, never an event: a dropped event would leave the runner writing
+		* against the wrong camera (D8).
+		*
+		* Construction can dial hardware, and the migrated source is
+		* characteristically dead — the timeout covers a full activate window
+		* rather than the 60 s default.
+		*/
+		reloadDevice: method(object({ stableId: string() }), object({ deviceId: number() }), {
+			kind: "mutation",
+			timeoutMs: 3 * 6e4
+		}),
 		supportsDiscovery: method(object({}), boolean()),
 		/**
 		* Run a network scan. `params` carries optional provider-specific scan
@@ -13722,7 +13792,8 @@ method(object({
 	targetId: number()
 }), MigrateDeviceResultSchema, {
 	kind: "mutation",
-	auth: "admin"
+	auth: "admin",
+	timeoutMs: 12 * 6e4
 }), method(DeviceRegisterPayloadSchema, _void(), { kind: "mutation" }), method(DeviceRemovePayloadSchema, _void(), { kind: "mutation" }), method(DevicePersistConfigPayloadSchema, _void(), { kind: "mutation" }), method(object({ deviceId: number() }), record(string(), unknown())), method(object({ deviceId: number() }), record(string(), unknown())), method(object({ deviceId: number() }), DeviceMetaSchema.nullable()), method(object({
 	deviceId: number(),
 	name: string()
@@ -33522,6 +33593,147 @@ var BaseDevice = class {
 	}
 };
 /**
+* Delays before retry rounds 1..N — the round count IS the bound.
+* 10 s catches "the hub was busy for a moment"; the full schedule
+* (10 + 30 + 90 s of waiting, plus up to one 60 s transport timeout
+* per attempt) covers a device-manager lock held for minutes — the
+* 2026-09-04 outage's migration hold was ~3.5 min.
+*/
+var DEVICE_RESTORE_RETRY_DELAYS_MS = [
+	1e4,
+	3e4,
+	9e4
+];
+/** Abortable sleep — resolves early (never rejects) on abort. */
+function sleep$1(ms, signal) {
+	return new Promise((resolve) => {
+		if (signal.aborted) {
+			resolve();
+			return;
+		}
+		const onAbort = () => {
+			clearTimeout(timer);
+			resolve();
+		};
+		const timer = setTimeout(() => {
+			signal.removeEventListener("abort", onAbort);
+			resolve();
+		}, ms);
+		timer.unref?.();
+		signal.addEventListener("abort", onAbort, { once: true });
+	});
+}
+/** Drain `items` through at most `width` concurrent lanes. `fn` must
+*  not reject (callers wrap their own try/catch). */
+async function runWithConcurrency(items, width, fn) {
+	const queue = [...items];
+	const laneCount = Math.max(1, Math.min(width, queue.length));
+	const lane = async () => {
+		for (;;) {
+			const item = queue.shift();
+			if (item === void 0) return;
+			await fn(item);
+		}
+	};
+	await Promise.all(Array.from({ length: laneCount }, lane));
+}
+var DeviceRestoreRetryScheduler = class {
+	#logger;
+	#attempt;
+	#onPermanentFailure;
+	#delaysMs;
+	#concurrency;
+	#now;
+	#abort = new AbortController();
+	constructor(options) {
+		this.#logger = options.logger;
+		this.#attempt = options.attempt;
+		this.#onPermanentFailure = options.onPermanentFailure;
+		this.#delaysMs = options.delaysMs ?? DEVICE_RESTORE_RETRY_DELAYS_MS;
+		this.#concurrency = options.concurrency ?? 4;
+		this.#now = options.now ?? Date.now;
+	}
+	/** Stop retrying (shutdown). Pending entries are NOT marked
+	*  permanently failed — the next boot restores them from disk. */
+	cancel() {
+		this.#abort.abort();
+	}
+	/**
+	* Run the bounded retry rounds. Resolves when every entry has either
+	* restored, been marked permanently failed, or the scheduler was
+	* cancelled. Never rejects.
+	*/
+	async run(initialFailures) {
+		let pending = initialFailures.map((failure) => ({
+			saved: failure.saved,
+			lastError: failure.error,
+			attempts: 1
+		}));
+		for (let round = 0; round < this.#delaysMs.length; round += 1) {
+			if (pending.length === 0 || this.#abort.signal.aborted) break;
+			await sleep$1(this.#delaysMs[round] ?? 0, this.#abort.signal);
+			if (this.#abort.signal.aborted) break;
+			pending = await this.#runRound(pending, round);
+		}
+		if (this.#abort.signal.aborted) return [];
+		const terminal = pending.map((entry) => ({
+			deviceId: entry.saved.id,
+			stableId: entry.saved.stableId,
+			type: String(entry.saved.type),
+			attempts: entry.attempts,
+			lastError: entry.lastError,
+			failedAt: this.#now()
+		}));
+		for (const failure of terminal) this.#onPermanentFailure(failure);
+		return terminal;
+	}
+	/** One retry round: parents first (phase 0), then hub-adopted
+	*  children (phase 1) — a child's attempt depends on its parent
+	*  having landed, exactly like the initial two-pass restore. */
+	async #runRound(pending, round) {
+		const next = [];
+		const parents = pending.filter((entry) => entry.saved.parentDeviceId === null);
+		const children = pending.filter((entry) => entry.saved.parentDeviceId !== null);
+		for (const phase of [parents, children]) await runWithConcurrency(phase, this.#concurrency, async (entry) => {
+			if (this.#abort.signal.aborted) {
+				next.push(entry);
+				return;
+			}
+			const attemptNo = entry.attempts + 1;
+			try {
+				await this.#attempt(entry.saved);
+				this.#logger.info("Device restored on retry", {
+					tags: {
+						deviceId: entry.saved.id,
+						stableId: entry.saved.stableId
+					},
+					meta: { attempt: attemptNo }
+				});
+			} catch (err) {
+				const lastError = err instanceof Error ? err.message : String(err);
+				const remainingRetries = this.#delaysMs.length - (round + 1);
+				this.#logger.warn("Device restore retry failed", {
+					tags: {
+						deviceId: entry.saved.id,
+						stableId: entry.saved.stableId
+					},
+					meta: {
+						attempt: attemptNo,
+						remainingRetries,
+						error: lastError
+					}
+				});
+				next.push({
+					saved: entry.saved,
+					lastError,
+					attempts: attemptNo
+				});
+			}
+		});
+		return next;
+	}
+};
+/**
 * Convert an IDevice to the flat DeviceSummary shape expected by the
 * device-provider cap router. Shared across all providers.
 */
@@ -33570,6 +33782,7 @@ var BaseDeviceProvider = class extends BaseAddon {
 		}];
 	}
 	async onShutdown() {
+		this.cancelRestoreRetries();
 		const devices = await this.ctx.kernel.devices?.getAll() ?? [];
 		for (const device of devices) try {
 			await this.ctx.kernel.devices?.decommission(device.id);
@@ -33587,9 +33800,16 @@ var BaseDeviceProvider = class extends BaseAddon {
 	async start() {}
 	async stop() {}
 	async getStatus() {
+		const all = await this.ctx.kernel.devices?.getAll() ?? [];
+		const summary = this.restoreFailureSummary();
+		if (summary === null) return {
+			connected: true,
+			deviceCount: all.length
+		};
 		return {
 			connected: true,
-			deviceCount: (await this.ctx.kernel.devices?.getAll() ?? []).length
+			deviceCount: all.length,
+			error: summary
 		};
 	}
 	async getDevices() {
@@ -33679,8 +33899,137 @@ var BaseDeviceProvider = class extends BaseAddon {
 		};
 	}
 	async restoreDevices(savedDevices) {
-		await this.onRestoreDevices(savedDevices);
-		if (savedDevices.length > 0) this.ctx.logger.info(`Restored ${savedDevices.length} ${this.providerName} device(s)`);
+		const report = await this.onRestoreDevices(savedDevices);
+		if (savedDevices.length === 0) return;
+		if (report && report.failedCount > 0) {
+			this.ctx.logger.warn(`Restored ${report.restoredCount}/${savedDevices.length} ${this.providerName} device(s) — ${report.failedCount} failed, bounded retry scheduled`);
+			return;
+		}
+		const restoredCount = report ? report.restoredCount : savedDevices.length;
+		this.ctx.logger.info(`Restored ${restoredCount} ${this.providerName} device(s)`);
+	}
+	/** Retry schedule. Overridable (tests use millisecond delays). */
+	restoreRetryDelaysMs = DEVICE_RESTORE_RETRY_DELAYS_MS;
+	/** Retry lane width. See `device-restore-retry.ts` for why retries
+	*  never re-stampede full-width while the initial pass does (D167). */
+	restoreRetryConcurrency = 4;
+	_restoreRetryScheduler = null;
+	_restoreRetryCompletion = null;
+	_permanentRestoreFailures = /* @__PURE__ */ new Map();
+	/** Settles when the background retry rounds finish (or `null` when
+	*  nothing failed). Exposed for tests and subclass diagnostics —
+	*  boot NEVER awaits this: the runner's post-init handshake goes out
+	*  with the devices that restored, and a late success is announced
+	*  through the `native-cap-change` → `updateCaps` path. */
+	get restoreRetryCompletion() {
+		return this._restoreRetryCompletion;
+	}
+	/** Devices that exhausted the retry bound this process lifetime. */
+	get permanentRestoreFailures() {
+		return [...this._permanentRestoreFailures.values()];
+	}
+	/** One-line operator-facing summary for `getStatus().error`, or
+	*  `null` when every device restored. */
+	restoreFailureSummary() {
+		if (this._permanentRestoreFailures.size === 0) return null;
+		const ids = [...this._permanentRestoreFailures.keys()].join(", ");
+		return `${this._permanentRestoreFailures.size} device(s) permanently failed restore (deviceIds: ${ids}) — restart the ${this.providerName} provider to retry`;
+	}
+	cancelRestoreRetries() {
+		this._restoreRetryScheduler?.cancel();
+		this._restoreRetryScheduler = null;
+	}
+	recordPermanentRestoreFailure(failure) {
+		this._permanentRestoreFailures.set(failure.deviceId, failure);
+		this.ctx.logger.error("Device restore permanently failed — its capabilities will not register until the provider restarts", {
+			tags: {
+				deviceId: failure.deviceId,
+				stableId: failure.stableId
+			},
+			meta: {
+				type: failure.type,
+				attempts: failure.attempts,
+				error: failure.lastError
+			}
+		});
+	}
+	scheduleRestoreRetries(failures, attempt) {
+		const scheduler = new DeviceRestoreRetryScheduler({
+			logger: this.ctx.logger,
+			delaysMs: this.restoreRetryDelaysMs,
+			concurrency: this.restoreRetryConcurrency,
+			attempt,
+			onPermanentFailure: (failure) => this.recordPermanentRestoreFailure(failure)
+		});
+		this._restoreRetryScheduler = scheduler;
+		this._restoreRetryCompletion = scheduler.run(failures).then(() => void 0).catch((err) => {
+			this.ctx.logger.error("Restore retry scheduler crashed", { meta: { error: err instanceof Error ? err.message : String(err) } });
+		});
+	}
+	/**
+	* Tear down and reconstruct ONE device from its persisted rows — the
+	* `deviceProvider.reloadDevice` cap method. Persistence is never touched,
+	* and no other device this provider owns is disturbed.
+	*
+	* Keyed by `stableId` because the caller's whole reason to be here is that
+	* the NUMERIC id changed (`deviceManager.migrateDevice` swapped it): the
+	* fresh instance resolves its id through `allocateDeviceId`, which returns
+	* whatever number the row carries NOW. The teardown is `decommission` —
+	* exactly what a graceful shutdown runs per device (fires `removeDevice()`,
+	* unregisters native caps, drops the registry entry) — and the rebuild is
+	* the boot restore's own `create()` path, including its pass 2: first-class
+	* children (hub-adopted cameras under an NVR) are decommissioned with the
+	* parent by the cascade and must be re-created explicitly, because only
+	* accessory children come back through `getAccessoryChildren()`.
+	*
+	* Reloading an accessory child directly is refused (no device class) —
+	* reload its parent instead.
+	*/
+	async reloadDevice(input) {
+		const { stableId } = input;
+		const devices = this.ctx.kernel.devices;
+		if (!devices) throw new Error(`${this.providerName}: kernel.devices unavailable — cannot reload`);
+		const live = (await devices.getAll()).find((d) => d.stableId === stableId);
+		if (live) await devices.decommission(live.id);
+		const { id } = await this.ctx.api.deviceManager.allocateDeviceId.mutate({
+			addonId: this.addonId,
+			stableId
+		});
+		const meta = await this.ctx.api.deviceManager.loadMeta.query({ deviceId: id });
+		if (meta === null) throw new Error(`${this.providerName}: no persisted meta for "${stableId}" (id ${id}) — cannot reload`);
+		const deviceType = Object.values(DeviceType).find((t) => t === meta.type);
+		const Class = deviceType !== void 0 ? this.deviceClasses[deviceType] : void 0;
+		if (!Class) throw new Error(`${this.providerName}: no device class for type "${meta.type}" — "${stableId}" is an accessory child; reload its parent instead`);
+		await devices.create(stableId, Class, {}, meta.parentDeviceId ?? null);
+		const rows = await this.ctx.api.deviceManager.listPersistedByAddon.query({ addonId: this.addonId });
+		for (const row of rows) {
+			if (row.parentDeviceId !== id) continue;
+			const childType = Object.values(DeviceType).find((t) => t === row.type);
+			const ChildClass = childType !== void 0 ? this.deviceClasses[childType] : void 0;
+			if (!ChildClass) continue;
+			try {
+				await devices.create(row.stableId, ChildClass, {}, id);
+			} catch (err) {
+				this.ctx.logger.warn("reloadDevice: failed to re-create first-class child", {
+					tags: {
+						deviceId: row.id,
+						stableId: row.stableId
+					},
+					meta: {
+						parentDeviceId: id,
+						error: err instanceof Error ? err.message : String(err)
+					}
+				});
+			}
+		}
+		this.ctx.logger.info("device reloaded in place from persisted rows", {
+			tags: { deviceId: id },
+			meta: {
+				stableId,
+				type: meta.type
+			}
+		});
+		return { deviceId: id };
 	}
 	/**
 	* Restore devices from persisted state. Two-pass:
@@ -33706,55 +34055,125 @@ var BaseDeviceProvider = class extends BaseAddon {
 	* accessory-spawn flow handles via the parent's
 	* `getAccessoryChildren()`. Override only when the default doesn't
 	* fit.
+	*
+	* A row that fails either pass is NOT terminal (D347): it is handed
+	* to a bounded background retry (`DeviceRestoreRetryScheduler`).
+	* Only after the bound is exhausted is the device marked permanently
+	* failed — logged at ERROR with `tags.deviceId` and surfaced via
+	* `getStatus().error`.
 	*/
+	/**
+	* Repair a row's PERSISTED config blob immediately before it is restored.
+	* Default: no-op — most providers have nothing to heal.
+	*
+	* This exists because a restored device self-hydrates from the DB: `create()`
+	* passes `{}` and `BaseDevice` parses the stored blob against the device
+	* schema. A blob that lost a REQUIRED field therefore fails restore forever,
+	* and no later pass revisits it — a hub-adopted Reolink camera whose blob had
+	* been emptied failed all four bounded attempts against fields
+	* (`host`, `password`) it inherits from its parent and never dials itself.
+	*
+	* Implementations get every saved row, so a child can read its parent's blob.
+	* A heal that throws is treated like any other restore failure: retried under
+	* the bound, then reported — never swallowed.
+	*/
+	async healSavedConfig(_saved, _allSaved) {}
 	async onRestoreDevices(savedDevices) {
 		const restored = /* @__PURE__ */ new Set();
+		const failures = [];
+		const attemptRestore = async (saved) => {
+			if (restored.has(saved.id)) return;
+			const Class = this.deviceClasses[saved.type];
+			if (!Class) throw new Error(`no device class registered for type "${saved.type}"`);
+			if (saved.parentDeviceId !== null && !restored.has(saved.parentDeviceId)) throw new Error(`parent device ${saved.parentDeviceId} not restored`);
+			await this.healSavedConfig(saved, savedDevices);
+			await this.ctx.kernel.devices.create(saved.stableId, Class, {}, saved.parentDeviceId);
+			restored.add(saved.id);
+		};
 		const topLevel = savedDevices.filter((saved) => saved.parentDeviceId === null);
 		const restoreOne = async (saved) => {
-			const Class = this.deviceClasses[saved.type];
-			if (!Class) {
+			if (!this.deviceClasses[saved.type]) {
 				this.ctx.logger.warn("No device class registered for restored type — skipping", {
-					tags: { stableId: saved.stableId },
+					tags: {
+						deviceId: saved.id,
+						stableId: saved.stableId
+					},
 					meta: { type: saved.type }
 				});
 				return;
 			}
 			try {
-				await this.ctx.kernel.devices.create(saved.stableId, Class, {});
-				restored.add(saved.id);
+				await attemptRestore(saved);
 			} catch (err) {
-				this.ctx.logger.warn("Failed to restore device", {
-					tags: { stableId: saved.stableId },
+				const error = err instanceof Error ? err.message : String(err);
+				this.ctx.logger.warn("Failed to restore device — bounded retry scheduled", {
+					tags: {
+						deviceId: saved.id,
+						stableId: saved.stableId
+					},
 					meta: {
 						type: saved.type,
-						error: err instanceof Error ? err.message : String(err)
+						attempt: 1,
+						error
 					}
 				});
+				failures.push({
+					saved,
+					error
+				});
 			}
 		};
 		await Promise.all(topLevel.map((saved) => restoreOne(saved)));
+		const failedTopLevelIds = new Set(failures.map((failure) => failure.saved.id));
 		const childRows = savedDevices.filter((s) => s.parentDeviceId !== null);
 		for (const saved of childRows) {
-			const Class = this.deviceClasses[saved.type];
-			if (!Class) continue;
+			if (!this.deviceClasses[saved.type]) continue;
 			if (saved.parentDeviceId === null) continue;
-			if (!restored.has(saved.parentDeviceId)) continue;
-			try {
-				await this.ctx.kernel.devices.create(saved.stableId, Class, {}, saved.parentDeviceId);
-				restored.add(saved.id);
-			} catch (err) {
-				this.ctx.logger.warn("Failed to restore hub-adopted child", {
+			if (restored.has(saved.parentDeviceId)) {
+				try {
+					await attemptRestore(saved);
+				} catch (err) {
+					const error = err instanceof Error ? err.message : String(err);
+					this.ctx.logger.warn("Failed to restore hub-adopted child — bounded retry scheduled", {
+						tags: {
+							deviceId: saved.id,
+							stableId: saved.stableId,
+							parentDeviceId: saved.parentDeviceId
+						},
+						meta: {
+							type: saved.type,
+							attempt: 1,
+							error
+						}
+					});
+					failures.push({
+						saved,
+						error
+					});
+				}
+				continue;
+			}
+			if (failedTopLevelIds.has(saved.parentDeviceId)) {
+				this.ctx.logger.warn("Hub-adopted child deferred — parent failed initial restore", {
 					tags: {
+						deviceId: saved.id,
 						stableId: saved.stableId,
 						parentDeviceId: saved.parentDeviceId
 					},
-					meta: {
-						type: saved.type,
-						error: err instanceof Error ? err.message : String(err)
-					}
+					meta: { type: saved.type }
+				});
+				failures.push({
+					saved,
+					error: `parent device ${saved.parentDeviceId} not restored`
 				});
+				continue;
 			}
 		}
+		if (failures.length > 0) this.scheduleRestoreRetries(failures, attemptRestore);
+		return {
+			restoredCount: restored.size,
+			failedCount: failures.length
+		};
 	}
 	/** Convert an IDevice to the flat DeviceSummary for the cap router. */
 	toSummary(device) {
@@ -35669,6 +36088,12 @@ Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"deviceProvider.reloadDevice": {
+		capName: "device-provider",
+		capScope: "system",
+		addonId: null,
+		access: "create"
+	},
 	"deviceProvider.start": {
 		capName: "device-provider",
 		capScope: "system",
@@ -230692,6 +231117,453 @@ var IntercomFailureReport = class {
 /** The process-wide instance every camera in this addon notes into. */
 var intercomFailureReport = new IntercomFailureReport();
 //#endregion
+//#region src/snapshot-freshness.ts
+/**
+* The snapshot groups the freshness panel reports on, with the Baichuan
+* read behind each. Order is the display order.
+*/
+var SNAPSHOT_GROUPS = [
+	{
+		key: "imageSnapshot",
+		label: "Image (getVideoInput)"
+	},
+	{
+		key: "motionSnapshot",
+		label: "Motion (getMotionAlarm)"
+	},
+	{
+		key: "aiSensitivitySnapshot",
+		label: "AI sensitivity (getAiDetectionFull)"
+	},
+	{
+		key: "encSnapshot",
+		label: "Encoder (getEnc)"
+	},
+	{
+		key: "encOptionsSnapshot",
+		label: "Encoder options (getEncOptions)"
+	},
+	{
+		key: "maskSnapshot",
+		label: "Privacy mask (getMask)"
+	},
+	{
+		key: "audioNoiseSnapshot",
+		label: "Audio noise (getAudioNoise)"
+	},
+	{
+		key: "autoFocusSnapshot",
+		label: "Auto-focus (getAutoFocus)"
+	},
+	{
+		key: "netPortSnapshot",
+		label: "Network ports (getNetPort)"
+	},
+	{
+		key: "ntpSnapshot",
+		label: "NTP (getNtp)"
+	},
+	{
+		key: "systemGeneralSnapshot",
+		label: "System general (getSystemGeneral)"
+	},
+	{
+		key: "osdSnapshot",
+		label: "OSD overlay (getOsd)"
+	},
+	{
+		key: "ledSnapshot",
+		label: "LEDs (getIrLights)"
+	},
+	{
+		key: "pirSnapshot",
+		label: "PIR (getPirInfo)"
+	},
+	{
+		key: "autoRebootSnapshot",
+		label: "Auto reboot (getAutoReboot)"
+	},
+	{
+		key: "emailConfigSnapshot",
+		label: "Email/SMTP (getEmail)"
+	},
+	{
+		key: "capOptionsSnapshot",
+		label: "Cap option probes (getOptions)"
+	}
+];
+/**
+* Merge freshness stamps for the snapshot keys a persist actually wrote.
+* Returns a NEW map (immutability) — previous stamps for untouched groups
+* survive, written groups are stamped `now`. Call this from the same
+* `setAll` that writes the snapshots, with exactly the keys being written:
+* a failed probe writes no snapshot and therefore gets no stamp.
+*/
+function stampSnapshotFreshness(previous, writtenKeys, now) {
+	const stamped = { ...previous };
+	for (const key of writtenKeys) stamped[key] = now;
+	return stamped;
+}
+/**
+* Resolve the age of one snapshot group from the cache. Sources, in order:
+*   1. `snapshotFetchedAt[key]` — the generic stamp map;
+*   2. a group-embedded stamp where one already existed before the map
+*      (`osdSnapshot.fetchedAt`, `emailConfigSnapshot.lastReadAt`,
+*      newest `capOptionsSnapshot[*].fetchedAt`);
+*   3. otherwise: the group is present but of unknown age.
+* An absent group is `never` — not-yet-read must never look like read.
+*/
+function resolveSnapshotAge(cache, key, now) {
+	if ((cache === void 0 ? void 0 : Reflect.get(cache, key)) === void 0) return { state: "never" };
+	const mapStamp = cache?.snapshotFetchedAt?.[key];
+	const stamp = typeof mapStamp === "number" ? mapStamp : embeddedStamp(cache, key);
+	if (typeof stamp !== "number") return { state: "unknown" };
+	return {
+		state: "known",
+		fetchedAt: stamp,
+		ageMs: Math.max(0, now - stamp)
+	};
+}
+/** Pre-map stamps some groups already carried; kept as fallback so a legacy
+*  cache written by today's OSD fix still reports a real age. */
+function embeddedStamp(cache, key) {
+	if (key === "osdSnapshot") {
+		const v = cache?.osdSnapshot?.fetchedAt;
+		return typeof v === "number" ? v : void 0;
+	}
+	if (key === "emailConfigSnapshot") {
+		const v = cache?.emailConfigSnapshot?.lastReadAt;
+		return typeof v === "number" ? v : void 0;
+	}
+	if (key === "capOptionsSnapshot") {
+		const stamps = Object.values(cache?.capOptionsSnapshot ?? {}).map((e) => e?.fetchedAt).filter((v) => typeof v === "number");
+		return stamps.length > 0 ? Math.max(...stamps) : void 0;
+	}
+}
+/** Human age: "12 s ago", "3 m ago", "5 h ago", "12 d ago". */
+function formatSnapshotAge(ageMs) {
+	const s = Math.floor(ageMs / 1e3);
+	if (s < 60) return `${s} s ago`;
+	const m = Math.floor(s / 60);
+	if (m < 60) return `${m} m ago`;
+	const h = Math.floor(m / 60);
+	if (h < 48) return `${h} h ago`;
+	return `${Math.floor(h / 24)} d ago`;
+}
+/** One display line for a group. Unknown age is SAID, never smoothed over. */
+function formatSnapshotAgeLine(label, age) {
+	switch (age.state) {
+		case "never": return `${label}: never read`;
+		case "unknown": return `${label}: age unknown (recorded before per-snapshot freshness tracking)`;
+		case "known": return `${label}: read ${formatSnapshotAge(age.ageMs)} (${new Date(age.fetchedAt).toLocaleString()})`;
+	}
+}
+/**
+* Read-only "Snapshot freshness" section (advanced tab, next to Debug).
+* Lists every snapshot group with its own age so "is CamStack's belief
+* current?" is answerable per fact, not per cache. Purely informational:
+* it triggers no reads — refresh stays on the existing operator-triggered
+* "Refresh from camera" action and the event-driven paths.
+*/
+function buildSnapshotFreshnessSection(cache, opts) {
+	const lines = SNAPSHOT_GROUPS.map(({ key, label }) => formatSnapshotAgeLine(label, resolveSnapshotAge(cache, key, opts.now)));
+	const probedAt = cache?.probedAt;
+	const header = typeof probedAt === "number" ? `Feature probe: ${new Date(probedAt).toLocaleString()}` : "Feature probe: never recorded";
+	return {
+		id: "snapshotFreshness",
+		tab: "advanced",
+		title: "Snapshot freshness",
+		description: "When each cached camera reading was last fetched. Groups without a stamp were persisted before per-snapshot tracking — their age is unknown, not fresh. Use \"Refresh from camera\" (General) to re-read an awake camera.",
+		columns: 1,
+		fields: [{
+			type: "info",
+			key: "snapshotFreshness",
+			label: "Per-snapshot read times",
+			content: `${opts.sleeping ? "Camera is asleep — no group can refresh until it wakes; a sleeping battery camera is never woken to read settings.\n" : ""}${header}\n${lines.join("\n")}`
+		}]
+	};
+}
+var RawReadSliceSchema = _enum([
+	"image",
+	"motion",
+	"ai",
+	"enc",
+	"encOptions",
+	"mask",
+	"audioNoise",
+	"autofocus",
+	"netPort",
+	"ntp",
+	"systemGeneral",
+	"osd",
+	"led",
+	"pir",
+	"autoReboot"
+]);
+/**
+* The allow-list. `Record<RawReadSlice, …>` keeps the catalog and the enum
+* in lockstep in both directions. Anything not in this map — email/SMTP
+* (`getEmail` echoes the camera's SMTP credentials), users, sessions, any
+* `set*` — cannot be requested.
+*/
+var RAW_READ_CATALOG = {
+	image: {
+		command: "getVideoInput",
+		snapshotKey: "imageSnapshot",
+		invoke: (api, channel) => api.getVideoInput(channel)
+	},
+	motion: {
+		command: "getMotionAlarm",
+		snapshotKey: "motionSnapshot",
+		invoke: (api, channel) => api.getMotionAlarm(channel)
+	},
+	ai: {
+		command: "getAiDetectTypes + getAiDetectionFull (per type)",
+		snapshotKey: "aiSensitivitySnapshot",
+		invoke: async (api, channel) => {
+			const detectTypes = await api.getAiDetectTypes(channel, { timeoutMs: 1500 });
+			const perType = {};
+			for (const aiType of detectTypes ?? []) try {
+				perType[aiType] = await api.getAiDetectionFull(channel, aiType);
+			} catch (err) {
+				perType[aiType] = { error: err instanceof Error ? err.message : String(err) };
+			}
+			return {
+				detectTypes: detectTypes ?? [],
+				perType
+			};
+		}
+	},
+	enc: {
+		command: "getEnc",
+		snapshotKey: "encSnapshot",
+		invoke: (api, channel) => api.getEnc(channel)
+	},
+	encOptions: {
+		command: "getEncOptions",
+		snapshotKey: "encOptionsSnapshot",
+		invoke: (api, channel) => api.getEncOptions(channel)
+	},
+	mask: {
+		command: "getMask",
+		snapshotKey: "maskSnapshot",
+		invoke: (api, channel) => api.getMask(channel)
+	},
+	audioNoise: {
+		command: "getAudioNoise",
+		snapshotKey: "audioNoiseSnapshot",
+		invoke: (api, channel) => api.getAudioNoise(channel)
+	},
+	autofocus: {
+		command: "getAutoFocus",
+		snapshotKey: "autoFocusSnapshot",
+		invoke: (api, channel) => api.getAutoFocus(channel, { timeoutMs: 1500 })
+	},
+	netPort: {
+		command: "getNetPort",
+		snapshotKey: "netPortSnapshot",
+		invoke: (api) => api.getNetPort()
+	},
+	ntp: {
+		command: "getNtp",
+		snapshotKey: "ntpSnapshot",
+		invoke: (api) => api.getNtp()
+	},
+	systemGeneral: {
+		command: "getSystemGeneral",
+		snapshotKey: "systemGeneralSnapshot",
+		invoke: (api) => api.getSystemGeneral()
+	},
+	osd: {
+		command: "getOsd",
+		snapshotKey: "osdSnapshot",
+		invoke: (api, channel) => api.getOsd(channel)
+	},
+	led: {
+		command: "getIrLights",
+		snapshotKey: "ledSnapshot",
+		invoke: (api, channel) => api.getIrLights(channel)
+	},
+	pir: {
+		command: "getPirInfo",
+		snapshotKey: "pirSnapshot",
+		invoke: (api, channel) => api.getPirInfo(channel)
+	},
+	autoReboot: {
+		command: "getAutoReboot",
+		snapshotKey: "autoRebootSnapshot",
+		invoke: (api) => api.getAutoReboot()
+	}
+};
+/** What CamStack currently believes about the slice, with its own age. */
+var BelievedStateSchema = object({
+	/** The persisted projection (`deviceCache.<snapshotKey>`), verbatim. */
+	snapshot: unknown(),
+	/** deviceCache field the projection lives in. */
+	snapshotKey: string(),
+	/** Tri-state freshness — `never` / `unknown` (legacy, no stamp) / `known`. */
+	age: union([
+		object({ state: literal("never") }),
+		object({ state: literal("unknown") }),
+		object({
+			state: literal("known"),
+			fetchedAt: number().int(),
+			ageMs: number().int().nonnegative()
+		})
+	])
+});
+var RawReadResultSchema = discriminatedUnion("ok", [object({
+	ok: literal(true),
+	deviceId: number().int(),
+	slice: RawReadSliceSchema,
+	command: string(),
+	readAt: number().int(),
+	/** The library's response, unprojected, as plain JSON. */
+	camera: unknown(),
+	believed: BelievedStateSchema
+}), object({
+	ok: literal(false),
+	deviceId: number().int(),
+	slice: RawReadSliceSchema,
+	reason: _enum([
+		"sleeping",
+		"login-failed",
+		"read-failed"
+	]),
+	message: string(),
+	/** The believed state is still reported — a refusal must not hide
+	*  what CamStack is currently serving. */
+	believed: BelievedStateSchema
+})]);
+var RawReadInputSchema = object({
+	deviceId: number().int().nonnegative(),
+	slice: RawReadSliceSchema
+});
+function believedState(cache, entry, now) {
+	const age = resolveSnapshotAge(cache, entry.snapshotKey, now);
+	return {
+		snapshot: toPlainJson(cache === void 0 ? void 0 : Reflect.get(cache, entry.snapshotKey)),
+		snapshotKey: entry.snapshotKey,
+		age
+	};
+}
+/** Force a lib response to plain JSON: drops functions/undefined/prototypes,
+*  guarantees the payload is serializable across the tRPC boundary. */
+function toPlainJson(value) {
+	if (value === void 0) return null;
+	return JSON.parse(JSON.stringify(value));
+}
+/**
+* Execute one raw read. Order matters:
+*   1. sleep gate (refuse loudly — logging in would BE the wake);
+*   2. login;
+*   3. the allow-listed read;
+* and every outcome — refusal included — carries the believed state so the
+* operator always sees both sides of the comparison.
+*/
+async function performRawRead(slice, deps) {
+	const entry = RAW_READ_CATALOG[slice];
+	const believed = believedState(deps.cache, entry, deps.now);
+	if (deps.sleeping) {
+		deps.logger.info("reolink raw read refused — battery cam is sleeping", {
+			tags: { deviceId: deps.deviceId },
+			meta: { slice }
+		});
+		return {
+			ok: false,
+			deviceId: deps.deviceId,
+			slice,
+			reason: "sleeping",
+			message: "Battery camera is asleep — a raw read would wake it, so it is refused. The believed state below is what CamStack currently serves.",
+			believed
+		};
+	}
+	let api;
+	try {
+		api = await deps.getApi();
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		deps.logger.info("reolink raw read login failed", {
+			tags: { deviceId: deps.deviceId },
+			meta: {
+				slice,
+				error: message
+			}
+		});
+		return {
+			ok: false,
+			deviceId: deps.deviceId,
+			slice,
+			reason: "login-failed",
+			message,
+			believed
+		};
+	}
+	try {
+		const payload = await entry.invoke(api, deps.channel);
+		deps.logger.info("reolink raw read served", {
+			tags: { deviceId: deps.deviceId },
+			meta: {
+				slice,
+				command: entry.command
+			}
+		});
+		return {
+			ok: true,
+			deviceId: deps.deviceId,
+			slice,
+			command: entry.command,
+			readAt: deps.now,
+			camera: toPlainJson(payload),
+			believed
+		};
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		deps.logger.info("reolink raw read failed", {
+			tags: { deviceId: deps.deviceId },
+			meta: {
+				slice,
+				command: entry.command,
+				error: message
+			}
+		});
+		return {
+			ok: false,
+			deviceId: deps.deviceId,
+			slice,
+			reason: "read-failed",
+			message,
+			believed
+		};
+	}
+}
+//#endregion
+//#region src/debug-actions.ts
+/**
+* provider-reolink — customActions catalog (admin-only debug surface).
+*
+* Dispatched via `POST addons.custom
+* {addonId:'provider-reolink', action:'debugRawRead', input:{deviceId, slice}}`.
+*
+* Why an addon custom action and not a device action: `deviceManager.
+* runDeviceAction` (the `refresh-settings` / `refresh-sessions` shape) is
+* mounted `protected` and its dispatcher does not enforce the per-action
+* `auth` — any authenticated user could call it. `addons.custom` is the one
+* operator surface that enforces per-action `auth: 'admin'` server-side
+* (`ensureCustomActionAuth`) AND validates the addon's output against this
+* catalog. A debug surface that returns raw camera payloads is admin-only,
+* so it lives here (same wiring as `addon-benchmark` / `addon-notifiers`).
+*
+* `kind: 'query'` states the contract — the handler is read-only by
+* construction (see `raw-read.ts`: the slice enum maps onto an allow-list
+* of lib `get*` calls; no write is reachable). The `addons.custom` mount
+* itself is a single mutation procedure, so callers still POST.
+*/
+var reolinkDebugActions = defineCustomActions({ debugRawRead: customAction(RawReadInputSchema, RawReadResultSchema, {
+	kind: "query",
+	auth: "admin"
+}) });
+//#endregion
 //#region src/log-channels.ts
 /**
 * The diagnostic log CHANNELS `provider-reolink` declares.
@@ -230904,6 +231776,130 @@ function overlayLiveNativeRfc4571Sdp(descriptors, liveServerFor) {
 	});
 }
 //#endregion
+//#region src/osd-settings-section.ts
+/**
+* Camera snapshot → UNKNOWN (`null`). The last arm is the point: `?? true`
+* here is what rendered "the camera did not tell us" as an enabled overlay.
+* The snapshot is the ONLY input — the config keeps no copy to consult.
+*/
+function resolveOsdValues(snapshot) {
+	return {
+		osdChannelEnabled: snapshot?.channelEnabled ?? null,
+		osdChannelName: snapshot?.channelName ?? "",
+		osdTimeEnabled: snapshot?.timeEnabled ?? null,
+		osdWatermark: snapshot?.watermark ?? null
+	};
+}
+/**
+* Reader-side staleness (D224). A snapshot persisted before freshness
+* tracking has no `fetchedAt` and is treated as stale — that is exactly the
+* adoption-frozen reading this module exists to retire.
+*/
+function isOsdSnapshotStale(snapshot, now) {
+	return now - (snapshot?.fetchedAt ?? 0) > OPERATOR_WRITTEN_STALE_MS;
+}
+var OSD_UNKNOWN_DESCRIPTION = "Not reported by the camera yet — the current state is unknown.";
+var NEVER_WOKEN_SUFFIX = "a sleeping battery camera is never woken to read settings.";
+/**
+* A boolean overlay toggle. Unknown (`null`) renders disabled with an honest
+* description — the switch component shows `Boolean(null)` = off, and the
+* disabled + "not reported" pairing keeps that from reading as a claim.
+*/
+function osdToggle(key, label, value, baseDescription) {
+	const unknown = value === null;
+	const description = unknown ? baseDescription ? `${baseDescription} ${OSD_UNKNOWN_DESCRIPTION}` : OSD_UNKNOWN_DESCRIPTION : baseDescription;
+	return {
+		type: "boolean",
+		key,
+		label,
+		default: value,
+		style: "switch",
+		...description !== void 0 ? { description } : {},
+		...unknown ? { disabled: true } : {}
+	};
+}
+/**
+* State banner shown when the operator is NOT looking at a current reading:
+*  - camera asleep and the mirror is stale → say what is shown and when it
+*    was read, and that the camera is not woken for this;
+*  - no reading has ever landed → say the toggles are unknown.
+* A fresh mirror on an awake camera renders no banner — serve-and-revalidate
+* keeps it honest silently.
+*/
+function buildOsdStateBanner(snapshot, opts) {
+	const stale = isOsdSnapshotStale(snapshot, opts.now);
+	if (opts.sleeping && stale) return {
+		type: "info",
+		key: "osdSnapshotState",
+		label: "OSD state",
+		variant: "warning",
+		content: snapshot === void 0 ? `Camera is asleep and its OSD state has never been read — the toggles below are unknown until it wakes; ${NEVER_WOKEN_SUFFIX}` : snapshot.fetchedAt !== void 0 ? `Camera is asleep — showing the OSD state last read ${new Date(snapshot.fetchedAt).toLocaleString()}. It refreshes when the camera wakes; ${NEVER_WOKEN_SUFFIX}` : `Camera is asleep — showing the last known OSD state (age unknown). It refreshes when the camera wakes; ${NEVER_WOKEN_SUFFIX}`
+	};
+	if (snapshot === void 0) return {
+		type: "info",
+		key: "osdSnapshotState",
+		label: "OSD state",
+		variant: "warning",
+		content: "OSD state has not been read from this camera yet — unknown toggles are disabled until a read succeeds."
+	};
+	return null;
+}
+/**
+* A position value for display. Verbatim in quotes when the camera reported
+* one — an empty string IS a report and shows as `""` — and "not reported"
+* only when `getOsd` genuinely carried no string (tri-state, D337).
+*/
+function formatObservedPos(pos) {
+	return typeof pos === "string" ? `"${pos}"` : "not reported";
+}
+/**
+* Read-only view of the overlay positions the camera reported. Deliberately
+* NOT a control: the `pos` vocabulary is unknown (loose string, no observed
+* values yet), so this field exists to make it observable per camera. A
+* position control can be designed once real values have been collected —
+* see the "osd overlay positions observed" info log in the probe.
+*/
+function buildOsdPositionsField(snapshot) {
+	return {
+		type: "info",
+		key: "osdPositions",
+		label: "Overlay positions",
+		content: `Positions are kept exactly as configured on the camera and are read-only here.\nChannel name: ${formatObservedPos(snapshot?.channelPos)}\nTimestamp: ${formatObservedPos(snapshot?.timePos)}`
+	};
+}
+/**
+* The "OSD overlay" section (writable via `setOsd`, cmd_id 25). One
+* read-modify-write `setOsd(OsdConfig)` push covers all four fields — the
+* dispatcher reads the current `OsdConfig` (`getOsd`) first so the stored
+* overlay positions (`pos`) survive untouched. Position itself is
+* camera-pixel/preset specific and only OBSERVED here, never written.
+*/
+function buildOsdSection(snapshot, values, opts) {
+	const banner = buildOsdStateBanner(snapshot, opts);
+	return {
+		id: "osd",
+		tab: "image",
+		title: "OSD overlay",
+		description: "On-screen overlays burned into the video by the camera. Pushed via `SetOsd` (cmd_id 25). Overlay positions are kept as configured on the camera — only the toggles, channel-name text, and watermark change here.",
+		columns: 2,
+		fields: [
+			...banner ? [banner] : [],
+			osdToggle("osdChannelEnabled", "Channel name overlay", values.osdChannelEnabled, void 0),
+			{
+				type: "text",
+				key: "osdChannelName",
+				label: "Channel name",
+				description: "Text shown in the channel-name overlay.",
+				default: values.osdChannelName,
+				placeholder: "Front door"
+			},
+			osdToggle("osdTimeEnabled", "Timestamp overlay", values.osdTimeEnabled, void 0),
+			osdToggle("osdWatermark", "Watermark", values.osdWatermark, "The Reolink logo watermark overlay."),
+			buildOsdPositionsField(snapshot)
+		]
+	};
+}
+//#endregion
 //#region src/raw-state.ts
 /**
 * Source tag for every raw-state blob this provider emits.
@@ -231138,7 +232134,7 @@ var SirenAccessory = class extends BaseDevice {
 			this.ctx.logger.info("siren onProbe forcing wake — initial probe with no cached state", { tags: { deviceId: this.id } });
 			try {
 				await (await this.api).wakeUp(this.channel, { waitAfterWakeMs: 2e3 });
-				await sleep$1(1e3);
+				await sleep$2(1e3);
 			} catch (err) {
 				this.ctx.logger.warn("siren wake before initial probe failed — proceeding anyway", {
 					tags: { deviceId: this.id },
@@ -231560,7 +232556,7 @@ var FloodlightAccessory = class extends BaseDevice {
 			this.ctx.logger.info("floodlight onProbe forcing wake — initial probe with no cached state", { tags: { deviceId: this.id } });
 			try {
 				await (await this.api).wakeUp(this.channel, { waitAfterWakeMs: 2e3 });
-				await sleep$1(1e3);
+				await sleep$2(1e3);
 			} catch (err) {
 				this.ctx.logger.warn("floodlight wake before initial probe failed — proceeding anyway", {
 					tags: { deviceId: this.id },
@@ -231957,7 +232953,7 @@ var PirAccessory = class extends BaseDevice {
 			this.ctx.logger.info("pir onProbe forcing wake — initial probe with no cached state", { tags: { deviceId: this.id } });
 			try {
 				await (await this.api).wakeUp(this.channel, { waitAfterWakeMs: 2e3 });
-				await sleep$1(1e3);
+				await sleep$2(1e3);
 			} catch (err) {
 				this.ctx.logger.warn("pir wake before initial probe failed — proceeding anyway", {
 					tags: { deviceId: this.id },
@@ -233631,7 +234627,24 @@ var reolinkCameraSchema = object({
 			channelEnabled: boolean().nullable().optional(),
 			channelName: string().optional(),
 			timeEnabled: boolean().nullable().optional(),
-			watermark: boolean().nullable().optional()
+			watermark: boolean().nullable().optional(),
+			/**
+			* Overlay positions exactly as `getOsd` reported them — READ-ONLY
+			* observations, never written (the `setOsd` read-modify-write
+			* preserves the camera's stored `pos`). Tri-state: `null` means
+			* the camera did not report a string; an empty string is a real
+			* report. Captured so a vocabulary of live values can be
+			* collected before any position control is designed.
+			*/
+			channelPos: string().nullable().optional(),
+			timePos: string().nullable().optional(),
+			/**
+			* Wall-clock ms when this slice last landed from the camera.
+			* Absent on snapshots persisted before freshness tracking —
+			* `isOsdSnapshotStale` treats those as stale, which retires the
+			* adoption-frozen readings this stamp was added for (D224).
+			*/
+			fetchedAt: number().int().optional()
 		}).optional(),
 		/**
 		* Snapshot of the camera's status + doorbell LED state from
@@ -233670,7 +234683,18 @@ var reolinkCameraSchema = object({
 			hour: number().int().nullable().optional(),
 			minute: number().int().nullable().optional(),
 			supported: boolean().optional()
-		}).optional()
+		}).optional(),
+		/**
+		* Per-snapshot freshness stamps (D224 generalised, D346): wall-clock
+		* ms when each `*Snapshot` group in this cache was last WRITTEN from
+		* a camera read, keyed by the group's field name (`encSnapshot`,
+		* `osdSnapshot`, …). Written only by the persist sites that write
+		* the group itself (`stampSnapshotFreshness`) — a failed probe
+		* writes no snapshot and gets no stamp. A group with no entry here
+		* (legacy persist) is of UNKNOWN age and must never read as fresh;
+		* `resolveSnapshotAge` owns the tri-state.
+		*/
+		snapshotFetchedAt: record(string(), number().int()).optional()
 	}).loose().optional(),
 	/**
 	* Generic Baichuan debug logs. Forwarded as `DebugOptions.general`
@@ -233828,18 +234852,6 @@ var reolinkCameraSchema = object({
 	statusLedEnabled: boolean().optional(),
 	doorbellLedEnabled: boolean().optional(),
 	/**
-	* On-screen display (OSD) overlay — pushed via `setOsd` (cmd_id 25,
-	* read via 26). One read-modify-write `OsdConfig` push covers all four
-	* fields so the camera keeps its stored overlay positions (`pos`)
-	* untouched — only the enable flags, channel name text, and watermark
-	* toggle change. Position is camera-pixel/preset specific (`pos` is a
-	* loose string, not a clean enum), so it is intentionally NOT exposed.
-	*/
-	osdChannelEnabled: boolean().optional(),
-	osdChannelName: string().max(64).optional(),
-	osdTimeEnabled: boolean().optional(),
-	osdWatermark: boolean().optional(),
-	/**
 	* Audio output volume — pushed via `setAudioCfg` (cmd_id=265,
 	* read via 264). Reolink-spec range 0..100.
 	*/
@@ -235038,6 +236050,11 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 	*  legacy firmware that doesn't support some endpoints). */
 	lastSettingsSnapshotRetryAt = 0;
 	static SETTINGS_SNAPSHOT_RETRY_MIN_MS = 6e4;
+	/** Debounce timestamp for the OSD serve-and-revalidate kick from
+	*  `getSettingsUISchema` (D224). Separate from
+	*  `lastSettingsSnapshotRetryAt` so an incomplete-cache retry and an
+	*  OSD staleness revalidate never suppress each other. */
+	lastOsdRevalidateKickAt = 0;
 	/** True when any settings-snapshot field that drives a UI section
 	*  is missing from the persisted cache. Drives the on-demand retry
 	*  in `getSettingsUISchema`. */
@@ -235047,16 +236064,19 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 		return cache.encSnapshot === void 0 || cache.encOptionsSnapshot === void 0 || cache.maskSnapshot === void 0 || cache.audioNoiseSnapshot === void 0 || cache.autoFocusSnapshot === void 0;
 	}
 	/**
-	* Probe `getVideoInput` + `getMotionAlarm` and persist into the
-	* `deviceCache` snapshots. Fires once on `onCreated`; future
-	* settings opens read straight from the persisted snapshot. Image
-	* is readonly in the UI (lib lacks `setVideoInput`); motion is
-	* writable via `setMotionAlarm` so its snapshot also drives the
-	* dispatch's known-good baseline.
+	* Probe the parent-settings endpoints (`getVideoInput`, `getMotionAlarm`,
+	* `getOsd`, …) and persist into the `deviceCache` snapshots. Runs on
+	* activation, on battery wake transitions, after a settings save (scoped
+	* to the changed slices), via the manual "Refresh from camera" action,
+	* and from `getSettingsUISchema`'s serve-and-revalidate kicks — settings
+	* opens serve the persisted snapshot immediately and revalidate stale
+	* slices behind the form (D224). Image is readonly in the UI (lib lacks
+	* `setVideoInput`); motion is writable via `setMotionAlarm` so its
+	* snapshot also drives the dispatch's known-good baseline.
 	*/
 	async refreshParentSettingsSnapshot(slices) {
 		if (this.isBattery && this.sleeping) {
-			this.ctx.logger.debug("refreshParentSettingsSnapshot skipped — battery cam is sleeping", { tags: { deviceId: this.id } });
+			this.ctx.logger.info("refreshParentSettingsSnapshot skipped — battery cam is sleeping", { tags: { deviceId: this.id } });
 			return;
 		}
 		let api;
@@ -235209,14 +236229,30 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 		}
 		if (want("osd")) try {
 			const osd = await api.getOsd(channel);
+			const channelPos = typeof osd.osdChannel?.pos === "string" ? osd.osdChannel.pos : null;
+			const timePos = typeof osd.osdTime?.pos === "string" ? osd.osdTime.pos : null;
+			const prevOsdSnapshot = this.config.get("deviceCache")?.osdSnapshot;
+			if (prevOsdSnapshot?.channelPos !== channelPos || prevOsdSnapshot?.timePos !== timePos) this.ctx.logger.info("reolink osd overlay positions observed", {
+				tags: { deviceId: this.id },
+				meta: {
+					channelPos,
+					timePos
+				}
+			});
 			cacheUpdate.osdSnapshot = {
 				channelEnabled: typeof osd.osdChannel?.enable === "number" ? osd.osdChannel.enable === 1 : null,
 				channelName: typeof osd.osdChannel?.name === "string" ? osd.osdChannel.name : void 0,
 				timeEnabled: typeof osd.osdTime?.enable === "number" ? osd.osdTime.enable === 1 : null,
-				watermark: typeof osd.watermark === "number" ? osd.watermark === 1 : null
+				watermark: typeof osd.watermark === "number" ? osd.watermark === 1 : null,
+				channelPos,
+				timePos,
+				fetchedAt: Date.now()
 			};
 		} catch (err) {
-			this.ctx.logger.debug("reolink getOsd probe failed", { meta: { error: err instanceof Error ? err.message : String(err) } });
+			this.ctx.logger.info("reolink getOsd probe failed — OSD snapshot left stale", {
+				tags: { deviceId: this.id },
+				meta: { error: err instanceof Error ? err.message : String(err) }
+			});
 		}
 		if (want("led")) try {
 			const ledState = (await api.getIrLights(channel))?.body?.LedState;
@@ -235273,6 +236309,8 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 		}
 		if (Object.keys(cacheUpdate).length === 0) return;
 		const current = this.config.get("deviceCache") ?? {};
+		const writtenSnapshotKeys = Object.keys(cacheUpdate).filter((k) => k.endsWith("Snapshot"));
+		if (writtenSnapshotKeys.length > 0) cacheUpdate.snapshotFetchedAt = stampSnapshotFreshness(current.snapshotFetchedAt, writtenSnapshotKeys, Date.now());
 		try {
 			await this.config.setAll({ deviceCache: {
 				...current,
@@ -235286,6 +236324,28 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 		});
 	}
 	/**
+	* Admin-only raw-read debug surface (D346): return the library's response
+	* for one snapshot slice UNPROJECTED, next to the persisted snapshot and
+	* its freshness, so "what does the camera report vs what does CamStack
+	* believe" is answerable without Baichuan tracing. Read-only by
+	* construction (the slice enum maps onto an allow-list of lib `get*`
+	* calls — see `raw-read.ts`), writes nothing back to the cache, and the
+	* sleep gate runs BEFORE any login: a sleeping battery cam refuses loudly
+	* (logging in IS the wake) and still reports the believed state.
+	* Dispatched by the provider's `debugRawRead` custom action.
+	*/
+	async debugRawRead(slice) {
+		return performRawRead(slice, {
+			deviceId: this.id,
+			channel: this.getChannel(),
+			sleeping: this.isBattery && this.sleeping,
+			getApi: () => this.ensureApi(),
+			cache: this.config.get("deviceCache"),
+			logger: this.ctx.logger,
+			now: Date.now()
+		});
+	}
+	/**
 	* Declare on-camera accessory child devices the kernel should
 	* auto-spawn after `onCreated`. Each entry maps directly to a
 	* concrete accessory class via the existing `createAccessoryDevice`
@@ -235369,7 +236429,7 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 					waitAfterWakeMs: 2500,
 					attempts: 2
 				});
-				await sleep$1(1500);
+				await sleep$2(1500);
 			})(), new Promise((_, rej) => setTimeout(() => rej(/* @__PURE__ */ new Error("wakeIfSleeping timeout")), timeoutMs))]);
 			return true;
 		} catch (err) {
@@ -235484,7 +236544,8 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 				sendNickname: email.sendNickname,
 				...task ? { taskEnabled: task.enable === 1 } : {},
 				lastReadAt: Date.now()
-			}
+			},
+			snapshotFetchedAt: stampSnapshotFreshness(current.snapshotFetchedAt, ["emailConfigSnapshot"], Date.now())
 		} });
 		this.ctx.logger.info("email-push: read camera email config", {
 			tags: { deviceId: this.id },
@@ -235666,7 +236727,7 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 							waitAfterWakeMs: 2500,
 							attempts: 2
 						});
-						await sleep$1(1500);
+						await sleep$2(1500);
 					})(), new Promise((_, rej) => setTimeout(() => rej(/* @__PURE__ */ new Error("wakeForStream timeout")), timeoutMs))]);
 					const CONFIRM_TIMEOUT_MS = 1e4;
 					const CONFIRM_POLL_MS = 1e3;
@@ -235696,7 +236757,7 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 								break;
 							}
 						}
-						await sleep$1(CONFIRM_POLL_MS);
+						await sleep$2(CONFIRM_POLL_MS);
 					}
 					const confirmSource = parent !== null ? "hub-summary" : "sleep-poll";
 					if (observedAwake && this.commitSleepState(false, confirmSource)) {
@@ -235928,7 +236989,7 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 	async watchHubChildAwake(parent) {
 		const deadline = Date.now() + 45e3;
 		while (Date.now() < deadline) {
-			await sleep$1(5e3);
+			await sleep$2(5e3);
 			try {
 				if ((await (await parent.getApi()).getNvrChannelsSummary({ channels: [this.getChannel()] })).devices.find((d) => d.channel === this.getChannel())?.sleeping === false) {
 					if (this.commitSleepState(false, "hub-summary")) {
@@ -236891,7 +237952,8 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 						value,
 						fetchedAt: Date.now()
 					}
-				}
+				},
+				snapshotFetchedAt: stampSnapshotFreshness(current.snapshotFetchedAt, ["capOptionsSnapshot"], Date.now())
 			} });
 		} catch (err) {
 			this.ctx.logger.debug("cap options persist failed", {
@@ -237956,7 +239018,7 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 		this.ctx.logger.info("intercom: cam sleeping — waking up before talk session", { tags: { deviceId: this.id } });
 		try {
 			await api.wakeUp(channel, { waitAfterWakeMs: 2e3 });
-			await sleep$1(1e3);
+			await sleep$2(1e3);
 		} catch (err) {
 			this.ctx.logger.warn("intercom: wakeUp failed — proceeding anyway", { meta: { error: err instanceof Error ? err.message : String(err) } });
 		}
@@ -238256,13 +239318,17 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 					await api.setAutoFocus(channel, enabled ? 0 : 1);
 					try {
 						const a = (await api.getAutoFocus(channel, { timeoutMs: 1500 }))?.body?.AutoFocus;
-						if (a) await this.config.setAll({ deviceCache: {
-							...this.config.get("deviceCache"),
-							autoFocusSnapshot: {
-								enabled: typeof a.disable === "number" ? a.disable === 0 : null,
-								supported: true
-							}
-						} });
+						if (a) {
+							const afCurrent = this.config.get("deviceCache");
+							await this.config.setAll({ deviceCache: {
+								...afCurrent,
+								autoFocusSnapshot: {
+									enabled: typeof a.disable === "number" ? a.disable === 0 : null,
+									supported: true
+								},
+								snapshotFetchedAt: stampSnapshotFreshness(afCurrent?.snapshotFetchedAt, ["autoFocusSnapshot"], Date.now())
+							} });
+						}
 					} catch {}
 				}
 			};
@@ -239627,13 +240693,24 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 		const imgSnap = cache?.imageSnapshot ?? {};
 		const netSnap = cache?.netPortSnapshot ?? {};
 		const ntpSnap = cache?.ntpSnapshot ?? {};
+		let kickedFullSnapshotRefresh = false;
 		if (this.hasIncompleteSettingsCache()) {
 			const now = Date.now();
 			if (now - this.lastSettingsSnapshotRetryAt > ReolinkCamera.SETTINGS_SNAPSHOT_RETRY_MIN_MS) {
 				this.lastSettingsSnapshotRetryAt = now;
+				kickedFullSnapshotRefresh = true;
 				this.refreshParentSettingsSnapshot().catch(() => {});
 			}
 		}
+		const osdSnap = cache?.osdSnapshot;
+		if (!kickedFullSnapshotRefresh && isOsdSnapshotStale(osdSnap, Date.now())) {
+			const now = Date.now();
+			if (now - this.lastOsdRevalidateKickAt > ReolinkCamera.SETTINGS_SNAPSHOT_RETRY_MIN_MS) {
+				this.lastOsdRevalidateKickAt = now;
+				this.refreshParentSettingsSnapshot(new Set(["osd"])).catch(() => {});
+			}
+		}
+		const osdValues = resolveOsdValues(osdSnap);
 		const sessSnap = this.sessionsSnapshot;
 		const sessStale = sessSnap === null || Date.now() - sessSnap.ts > 6e4;
 		if (!this.isBattery && sessStale) this.refreshSessionsSnapshot().catch((err) => {
@@ -240180,45 +241257,10 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 						}] : []
 					]
 				},
-				{
-					id: "osd",
-					tab: "image",
-					title: "OSD overlay",
-					description: "On-screen overlays burned into the video by the camera. Pushed via `SetOsd` (cmd_id 25). Overlay positions are kept as configured on the camera — only the toggles, channel-name text, and watermark change here.",
-					columns: 2,
-					fields: [
-						{
-							type: "boolean",
-							key: "osdChannelEnabled",
-							label: "Channel name overlay",
-							default: cache?.osdSnapshot?.channelEnabled ?? true,
-							style: "switch"
-						},
-						{
-							type: "text",
-							key: "osdChannelName",
-							label: "Channel name",
-							description: "Text shown in the channel-name overlay.",
-							default: cache?.osdSnapshot?.channelName ?? "",
-							placeholder: "Front door"
-						},
-						{
-							type: "boolean",
-							key: "osdTimeEnabled",
-							label: "Timestamp overlay",
-							default: cache?.osdSnapshot?.timeEnabled ?? true,
-							style: "switch"
-						},
-						{
-							type: "boolean",
-							key: "osdWatermark",
-							label: "Watermark",
-							description: "The Reolink logo watermark overlay.",
-							default: cache?.osdSnapshot?.watermark ?? false,
-							style: "switch"
-						}
-					]
-				},
+				buildOsdSection(osdSnap, osdValues, {
+					sleeping: this.isBattery && this.sleeping,
+					now: Date.now()
+				}),
 				{
 					id: "privacy-mask",
 					tab: "image",
@@ -240508,6 +241550,10 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 						]
 					}]
 				},
+				buildSnapshotFreshnessSection(cache, {
+					sleeping: this.isBattery && this.sleeping,
+					now: Date.now()
+				}),
 				...this.buildSessionsTabSections(),
 				...this.buildEmailPushSection(),
 				...this.buildEmailTabSections()
@@ -240574,10 +241620,10 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 			irLightsBrightness: this.config.get("irLightsBrightness") ?? 128,
 			statusLedEnabled: this.config.get("statusLedEnabled") ?? cache?.ledSnapshot?.statusEnabled ?? true,
 			doorbellLedEnabled: this.config.get("doorbellLedEnabled") ?? cache?.ledSnapshot?.doorbellEnabled ?? true,
-			osdChannelEnabled: this.config.get("osdChannelEnabled") ?? cache?.osdSnapshot?.channelEnabled ?? true,
-			osdChannelName: this.config.get("osdChannelName") ?? cache?.osdSnapshot?.channelName ?? "",
-			osdTimeEnabled: this.config.get("osdTimeEnabled") ?? cache?.osdSnapshot?.timeEnabled ?? true,
-			osdWatermark: this.config.get("osdWatermark") ?? cache?.osdSnapshot?.watermark ?? false,
+			osdChannelEnabled: osdValues.osdChannelEnabled,
+			osdChannelName: osdValues.osdChannelName,
+			osdTimeEnabled: osdValues.osdTimeEnabled,
+			osdWatermark: osdValues.osdWatermark,
 			audioVolume: this.config.get("audioVolume") ?? 50,
 			audioTalkAndReplyVolume: this.config.get("audioTalkAndReplyVolume") ?? 50,
 			audioVisitorVolume: this.config.get("audioVisitorVolume") ?? 50,
@@ -240596,7 +241642,7 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 		});
 	}
 	async applySettingsPatch(patch) {
-		const { emailSmtpServer, emailSmtpPort, emailUserName, emailPassword, emailSsl, emailRecipient1, emailRecipient2, emailRecipient3, emailSendNickname, emailScheduleEnabled, ...rest } = patch;
+		const { emailSmtpServer, emailSmtpPort, emailUserName, emailPassword, emailSsl, emailRecipient1, emailRecipient2, emailRecipient3, emailSendNickname, emailScheduleEnabled, osdChannelEnabled, osdChannelName, osdTimeEnabled, osdWatermark, ...rest } = patch;
 		const emailFields = {
 			emailSmtpServer,
 			emailSmtpPort,
@@ -240615,8 +241661,14 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 				meta: { error: err instanceof Error ? err.message : String(err) }
 			});
 		});
-		if (Object.keys(rest).length === 0) return;
-		await this.config.setAll(rest);
+		const hasOsdPatch = [
+			osdChannelEnabled,
+			osdChannelName,
+			osdTimeEnabled,
+			osdWatermark
+		].some((v) => v !== void 0);
+		if (Object.keys(rest).length === 0 && !hasOsdPatch) return;
+		if (Object.keys(rest).length > 0) await this.config.setAll(rest);
 		const typedPatch = patch;
 		if (typedPatch.host || typedPatch.port || typedPatch.username || typedPatch.password) {
 			await this.disconnectAll();
@@ -240809,12 +241861,7 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 		} catch (err) {
 			this.ctx.logger.warn("ir-lights push failed", { meta: { error: err instanceof Error ? err.message : String(err) } });
 		}
-		if ([
-			"osdChannelEnabled",
-			"osdChannelName",
-			"osdTimeEnabled",
-			"osdWatermark"
-		].some((k) => k in patch)) try {
+		if (hasOsdPatch) try {
 			const api = await this.ensureApi();
 			const channel = this.getChannel();
 			const current = await api.getOsd(channel);
@@ -240832,13 +241879,16 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 				watermark: current.watermark ?? 0
 			};
 			if (current.bgcolor !== void 0) next.bgcolor = current.bgcolor;
-			if (typeof typedPatch.osdChannelEnabled === "boolean") next.osdChannel.enable = typedPatch.osdChannelEnabled ? 1 : 0;
-			if (typeof typedPatch.osdChannelName === "string") next.osdChannel.name = typedPatch.osdChannelName;
-			if (typeof typedPatch.osdTimeEnabled === "boolean") next.osdTime.enable = typedPatch.osdTimeEnabled ? 1 : 0;
-			if (typeof typedPatch.osdWatermark === "boolean") next.watermark = typedPatch.osdWatermark ? 1 : 0;
+			if (typeof osdChannelEnabled === "boolean") next.osdChannel.enable = osdChannelEnabled ? 1 : 0;
+			if (typeof osdChannelName === "string") next.osdChannel.name = osdChannelName;
+			if (typeof osdTimeEnabled === "boolean") next.osdTime.enable = osdTimeEnabled ? 1 : 0;
+			if (typeof osdWatermark === "boolean") next.watermark = osdWatermark ? 1 : 0;
 			await api.setOsd(channel, next);
 		} catch (err) {
-			this.ctx.logger.warn("osd push failed", { meta: { error: err instanceof Error ? err.message : String(err) } });
+			this.ctx.logger.warn("osd push failed — camera keeps its current overlay state", {
+				tags: { deviceId: this.id },
+				meta: { error: err instanceof Error ? err.message : String(err) }
+			});
 		}
 		if ([
 			"audioVolume",
@@ -240979,7 +242029,13 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 		}
 		const changedSlices = slicesForPatch(patch);
 		if (changedSlices.size > 0) await this.refreshParentSettingsSnapshot(changedSlices).catch((err) => {
-			this.ctx.logger.debug("reolink targeted settings refresh failed", { meta: { error: err instanceof Error ? err.message : String(err) } });
+			this.ctx.logger.info("reolink targeted settings refresh failed — snapshots left stale", {
+				tags: { deviceId: this.id },
+				meta: {
+					slices: [...changedSlices],
+					error: err instanceof Error ? err.message : String(err)
+				}
+			});
 		});
 	}
 	/**
@@ -241573,6 +242629,43 @@ function computeHealthCheckBackoffMs(consecutive) {
 	return 15 * 6e4;
 }
 //#endregion
+//#region src/hub-channel-reconcile.ts
+/**
+* Match adopted children to the hub's own channel list by IDENTITY, then report the
+* ones whose persisted `channel` is missing or wrong.
+*
+* A child's stableId is `${hubStableId}-${childNativeId}`, and `childNativeId` is built
+* from the camera's UID — so identity survives a channel move, while `channel` does not.
+* The hub is the authority on which slot a UID currently occupies.
+*
+* Why this exists: `loadAdoptedChildrenByChannel` keys the adopted set on the persisted
+* `channel` alone. A child that lost it is absent from that map, so the discovery panel
+* renders it `alreadyAdopted: false` — one click away from being adopted a SECOND time —
+* and `routeSimpleEvent` silently drops every push for its slot. Observed live on
+* 2026-09-04 with an Argus MagiCam that was actually on channel 3.
+*
+* Pure: no I/O. A discovered entry with no channel, or with no adopted child, is skipped —
+* this repairs what exists, it never adopts.
+*/
+function planChannelReconciliation(hubStableId, discovered, children) {
+	const byStableId = /* @__PURE__ */ new Map();
+	for (const child of children) byStableId.set(child.stableId, child);
+	const repairs = [];
+	for (const entry of discovered) {
+		if (typeof entry.rtspChannel !== "number") continue;
+		const child = byStableId.get(`${hubStableId}-${entry.childNativeId}`);
+		if (child === void 0) continue;
+		if (child.channel === entry.rtspChannel) continue;
+		repairs.push({
+			deviceId: child.deviceId,
+			stableId: child.stableId,
+			from: child.channel ?? null,
+			to: entry.rtspChannel
+		});
+	}
+	return repairs;
+}
+//#endregion
 //#region src/simple-event-dispatch-trace.ts
 /**
 * Gate for hub-side simpleEvent traces.
@@ -242069,6 +243162,7 @@ var ReolinkHub = class ReolinkHub extends BaseDevice {
 			lastFetchedAt: Date.now()
 		};
 		this.runtimeState.setCapState(deviceDiscoveryCapability.name, slice);
+		if (lastError === null) await this.reconcileChildChannels(discovered);
 		if (lastError === null) {
 			this.knownUnadoptedChannels.clear();
 			for (const d of discovered) {
@@ -242241,6 +243335,64 @@ var ReolinkHub = class ReolinkHub extends BaseDevice {
 	* the channel index. Returns a `channel → kernel deviceId` map.
 	* Used to gate the `alreadyAdopted` flag in the discovery list.
 	*/
+	/**
+	* Re-derive each adopted child's `channel` from the hub's own channel list, matching by
+	* IDENTITY (stableId carries the camera UID) rather than by the channel itself.
+	*
+	* `loadAdoptedChildrenByChannel` keys the adopted set on the persisted `channel` alone,
+	* so a child that lost it is invisible: the discovery panel renders it available (one
+	* click from a second adoption of the same camera) and `routeSimpleEvent` drops every
+	* push for its slot. A channel move produces the same damage under a wrong number.
+	*
+	* Writes through the live device so its in-memory config and the DB stay in step.
+	* A child that is not live is skipped — it is repaired on its next successful restore.
+	*/
+	async reconcileChildChannels(discovered) {
+		const children = await this.ctx.devices.getChildren(this.id);
+		const adopted = children.map((child) => {
+			const channel = child instanceof ReolinkCamera ? child.config.values.channel : void 0;
+			return {
+				deviceId: child.id,
+				stableId: child.stableId,
+				...typeof channel === "number" ? { channel } : {}
+			};
+		});
+		const repairs = planChannelReconciliation(this.stableId, discovered.map((d) => ({
+			childNativeId: d.childNativeId,
+			...typeof d.metadata.rtspChannel === "number" ? { rtspChannel: d.metadata.rtspChannel } : {}
+		})), adopted);
+		if (repairs.length === 0) return;
+		for (const repair of repairs) {
+			const child = children.find((c) => c.id === repair.deviceId);
+			if (!(child instanceof ReolinkCamera)) continue;
+			try {
+				await child.config.setAll({ channel: repair.to });
+				this.channelToDeviceId.set(repair.to, repair.deviceId);
+				this.ctx.logger.warn("Reolink Hub: repaired a child channel from the hub channel list", {
+					tags: {
+						deviceId: repair.deviceId,
+						stableId: repair.stableId
+					},
+					meta: {
+						from: repair.from,
+						to: repair.to
+					}
+				});
+			} catch (err) {
+				this.ctx.logger.warn("Reolink Hub: child channel repair failed", {
+					tags: {
+						deviceId: repair.deviceId,
+						stableId: repair.stableId
+					},
+					meta: {
+						from: repair.from,
+						to: repair.to,
+						error: err instanceof Error ? err.message : String(err)
+					}
+				});
+			}
+		}
+	}
 	async loadAdoptedChildrenByChannel() {
 		const result = /* @__PURE__ */ new Map();
 		const children = await this.ctx.devices.getChildren(this.id);
@@ -242705,6 +243857,53 @@ function buildCreationFormSchema() {
 	] };
 }
 //#endregion
+//#region src/child-config-heal.ts
+/** Connection fields a hub-adopted child inherits from its parent at adoption time. */
+var INHERITED_CONNECTION_KEYS = [
+	"host",
+	"port",
+	"username",
+	"password",
+	"transport"
+];
+/** A stored value counts as present only when it is a usable string/number. */
+function isPresent(value) {
+	if (typeof value === "string") return value !== "";
+	return typeof value === "number";
+}
+/**
+* Work out what a hub-adopted child's persisted blob is missing from the connection
+* fields it inherited from its parent when it was adopted.
+*
+* `ReolinkCamera` with a parent uses `parent.api` and never dials its own login — but
+* `reolinkCameraSchema` still requires `host` and `password` as strings, so a blob that
+* lost them fails to parse and the camera cannot be restored at all. Observed live on
+* 2026-09-04: an Argus MagiCam under a Home Hub carried `{}` and burned all four bounded
+* restore attempts on `host`/`password` — fields it would never have used.
+*
+* Only ABSENT fields are filled. A child that deliberately differs from its parent (a
+* per-child credential, a non-default port) keeps what it has.
+*/
+function planChildConfigHeal(childConfig, parentConfig) {
+	const patch = {};
+	const missingKeys = [];
+	for (const key of INHERITED_CONNECTION_KEYS) {
+		if (isPresent(childConfig[key])) continue;
+		if (!isPresent(parentConfig[key])) continue;
+		patch[key] = parentConfig[key];
+		missingKeys.push(key);
+	}
+	return {
+		patch,
+		missingKeys
+	};
+}
+/** Find the saved row a child names as its parent. */
+function findParentRow(child, allSaved) {
+	if (child.parentDeviceId === null) return void 0;
+	return allSaved.find((row) => row.id === child.parentDeviceId);
+}
+//#endregion
 //#region src/reolink-discovery-map.ts
 /**
 * Flatten a host (IP / hostname) into a flat row-key slug — shared by `generateStableId` and the
@@ -242714,21 +243913,44 @@ function slugifyReolinkHost(host) {
 	return host.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
 }
 /**
+* Decide whether a discovered host is a device this provider already owns.
+*
+* Matching is by UID first (stable across a DHCP lease change) and by host second. A UID match
+* wins even when the host differs, because the address is the thing that moves.
+*/
+function findOnboardedMatch(discovered, onboarded) {
+	if (discovered.uid !== void 0 && discovered.uid !== "") {
+		const byUid = onboarded.find((o) => o.uid === discovered.uid);
+		if (byUid !== void 0) return byUid;
+	}
+	return onboarded.find((o) => o.host !== void 0 && o.host === discovered.host);
+}
+/**
 * Map discovered Reolink hosts to adoption {@link DiscoveryCandidate}s, de-duplicated by host (the
 * same camera can answer on more than one discovery method — UDP broadcast, ONVIF, HTTP scan). The
 * first responder for a host wins. Pure: no I/O.
 *
+* **The scan never supplies `port`.** `port` in the Reolink config schema is the BAICHUAN port
+* (default 9000). Discovery reports `httpPort`, the HTTP/ONVIF listener — on a Reolink Home Hub
+* that is 8000, while Baichuan lives on `mediaPort` 9000. Writing the discovered value into `port`
+* pointed every Baichuan login at the ONVIF listener, which accepts the TCP connection and then
+* closes it: `Baichuan socket closed`, 316 times in 12 hours, taking the hub and all three of its
+* child cameras offline. The default is correct; a non-default Baichuan port is an operator edit,
+* never a scan result.
+*
 * The authoritative stableId is `mac-<mac>` (learned during autodetect at adopt time), which discovery
-* can't produce — so a re-scan of a MAC-keyed camera may still show as addable. The `host-` key still
-* lets host-added cameras be detected as onboarded on re-scan.
+* can't produce — so candidates carry `alreadyOnboarded` rather than relying on a stableId match,
+* which never fires for a MAC-keyed device. Re-adding an owned device is how the port got clobbered
+* in the first place, so a scan says so instead of offering it again.
 */
-function mapReolinkDiscoveryToCandidates(devices, credentials) {
+function mapReolinkDiscoveryToCandidates(devices, credentials, onboarded = []) {
 	const username = credentials.username?.trim() ?? "";
 	const password = credentials.password ?? "";
 	const byHost = /* @__PURE__ */ new Map();
 	for (const d of devices) if (!byHost.has(d.host)) byHost.set(d.host, d);
 	return [...byHost.values()].map((d) => {
 		const displayName = d.name ?? d.model ?? d.host;
+		const match = findOnboardedMatch(d, onboarded);
 		return {
 			stableId: `host-${slugifyReolinkHost(d.host)}`,
 			type: DeviceType.Camera,
@@ -242737,11 +243959,15 @@ function mapReolinkDiscoveryToCandidates(devices, credentials) {
 				name: displayName,
 				host: d.host,
 				transport: "auto",
-				...d.httpPort !== void 0 ? { port: d.httpPort } : {},
 				...d.uid ? { uid: d.uid } : {},
 				...username ? { username } : {},
 				...password ? { password } : {}
-			}
+			},
+			...match !== void 0 ? {
+				alreadyOnboarded: true,
+				onboardedDeviceId: match.deviceId,
+				onboardedName: match.name
+			} : {}
 		};
 	});
 }
@@ -243390,6 +244616,61 @@ var ReolinkProviderAddon = class extends BaseDeviceProvider {
 		super({});
 	}
 	/**
+	* Reduce this addon's live devices to the identities a network scan can produce, so
+	* {@link mapReolinkDiscoveryToCandidates} can recognise a device it already owns.
+	*
+	* Hubs are included: the incident this exists for was a Home Hub re-offered by a scan and
+	* re-added, which overwrote its Baichuan port with the ONVIF port the scan reported.
+	*/
+	/**
+	* Re-inherit the parent's connection fields into a hub-adopted child whose persisted
+	* blob lost them, so the child can be restored at all.
+	*
+	* `adoptDiscoveredChild` copies `host`/`port`/`username`/`password`/`transport` down
+	* from the Hub at adoption. Nothing re-applied them afterwards, so a child whose blob
+	* was emptied failed `reolinkCameraSchema` on every restore — on fields a child never
+	* dials, because a child with a parent uses `parent.api`. Only ABSENT fields are
+	* filled; a child that deliberately differs keeps what it has.
+	*/
+	async healSavedConfig(saved, allSaved) {
+		const parent = findParentRow(saved, allSaved);
+		if (parent === void 0) return;
+		const { patch, missingKeys } = planChildConfigHeal(saved.config, parent.config);
+		if (missingKeys.length === 0) return;
+		await this.ctx.kernel.devices?.persistInitialConfig(saved.stableId, {
+			...saved.config,
+			...patch
+		});
+		this.ctx.logger.warn("Reolink child config healed from its parent before restore", {
+			tags: {
+				deviceId: saved.id,
+				stableId: saved.stableId
+			},
+			meta: {
+				parentDeviceId: parent.id,
+				restoredKeys: [...missingKeys]
+			}
+		});
+	}
+	listOnboardedForDiscovery() {
+		const all = this.ctx.kernel.deviceRegistry?.getAll() ?? [];
+		const onboarded = [];
+		for (const d of all) {
+			if (!(d instanceof ReolinkCamera) && !(d instanceof ReolinkHub)) continue;
+			const values = d.config.values;
+			const host = typeof values.host === "string" && values.host !== "" ? values.host : void 0;
+			const uid = typeof values.uid === "string" && values.uid !== "" ? values.uid : void 0;
+			if (host === void 0 && uid === void 0) continue;
+			onboarded.push({
+				deviceId: d.id,
+				name: d.name,
+				...host !== void 0 ? { host } : {},
+				...uid !== void 0 ? { uid } : {}
+			});
+		}
+		return onboarded;
+	}
+	/**
 	* Enumerate this addon's live `ReolinkCamera` instances from the
 	* global device registry. Used by the email-push server to resolve
 	* recipients + route inbound motion. Returns `[]` when the registry
@@ -243582,6 +244863,44 @@ var ReolinkProviderAddon = class extends BaseDeviceProvider {
 		return regs;
 	}
 	/**
+	* Compose the provider registrations from `onInitialize()` with this
+	* addon's customActions catalog. `BaseDeviceProvider.onInitialize` is
+	* typed `ProviderRegistration[]` (eleven sibling providers push onto it),
+	* so the catalog joins at the `initialize()` seam instead — the runner
+	* consumes the merged `AddonInitResult` exactly as it does for
+	* addon-benchmark / addon-notifiers.
+	*
+	* Admin-only debug surface (D346): `debugRawRead` returns the lib's
+	* response for one snapshot slice UNPROJECTED, next to the persisted
+	* snapshot + its freshness. Registered as an addon customAction because
+	* `addons.custom` is the one operator surface that enforces the
+	* per-action `auth: 'admin'` server-side and validates output —
+	* `deviceManager.runDeviceAction` does neither. The hub reads the static
+	* catalog from this bundle's `customActions` export (see `index.ts`);
+	* the child registers the handlers returned here.
+	*/
+	async initialize(context) {
+		const base = await super.initialize(context);
+		return {
+			providers: base && base.providers ? base.providers : [],
+			customActions: reolinkDebugActions,
+			actionHandlers: { debugRawRead: (input) => this.debugRawRead(input) }
+		};
+	}
+	/**
+	* Route a `debugRawRead` custom action to the owning camera. Covers both
+	* standalone cameras and NVR-adopted children — every live ReolinkCamera
+	* in this runner is in the kernel device registry. Read-only end to end
+	* (see `raw-read.ts`); a hub device or an unknown id refuses with a
+	* message that names what it looked for.
+	*/
+	async debugRawRead(input) {
+		const dev = this.ctx.kernel.deviceRegistry?.getById(input.deviceId);
+		if (dev === void 0 || dev === null) throw new Error(`debugRawRead: device ${input.deviceId} not found in the reolink runner's registry`);
+		if (!(dev instanceof ReolinkCamera)) throw new Error(`debugRawRead: device ${input.deviceId} is not a ReolinkCamera (got ${dev.constructor.name}) — raw reads target cameras, not hubs/accessories`);
+		return dev.debugRawRead(input.slice);
+	}
+	/**
 	* Handle a broker-issued source-refresh request. With the lazy-publish
 	* model the broker always emits this on first dial of a
 	* `lazy:rfc4571:` placeholder URL — and re-emits it whenever the
@@ -243634,10 +244953,17 @@ var ReolinkProviderAddon = class extends BaseDeviceProvider {
 			networkCidr: networkCidr || "local",
 			enableOnvif
 		} });
-		return mapReolinkDiscoveryToCandidates(devices, {
+		const onboarded = this.listOnboardedForDiscovery();
+		const candidates = mapReolinkDiscoveryToCandidates(devices, {
 			username,
 			password
-		});
+		}, onboarded);
+		const owned = candidates.filter((c) => c.alreadyOnboarded === true).length;
+		if (owned > 0) this.ctx.logger.info("Reolink discovery: candidates already owned by this provider", { meta: {
+			owned,
+			total: candidates.length
+		} });
+		return candidates;
 	}
 	async adoptDiscoveredDevice(input) {
 		return this.createDevice({
@@ -243867,6 +245193,7 @@ exports.collectNativeDiagnostics = collectNativeDiagnostics;
 exports.collectNvrDiagnostics = collectNvrDiagnostics;
 exports.createDiagnosticsBundle = createDiagnosticsBundle;
 exports.reolinkCameraSchema = reolinkCameraSchema;
+exports.reolinkDebugActions = reolinkDebugActions;
 exports.runAllDiagnosticsConsecutively = runAllDiagnosticsConsecutively;
 exports.runMultifocalDiagnosticsConsecutively = runMultifocalDiagnosticsConsecutively;
 exports.sampleStreams = sampleStreams;