@camstack/addon-provider-reolink 1.2.82 → 1.2.83

package/dist/addon.mjs

@@ -7194,7 +7194,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({
@@ -12406,6 +12406,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,
@@ -13390,6 +13412,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
@@ -13717,7 +13768,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()
@@ -33517,6 +33569,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.
 */
@@ -33565,6 +33758,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);
@@ -33582,9 +33776,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() {
@@ -33674,8 +33875,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:
@@ -33701,55 +34031,108 @@ 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`.
 	*/
 	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.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) {
@@ -35664,6 +36047,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",
@@ -179088,7 +179477,7 @@ ${xml}`);
 	* @returns Test results for all stream types and profiles
 	*/
 	async testChannelStreams(channel, logger) {
-		const { testChannelStreams } = await import("./DiagnosticsTools-QJ3CRYGA-9NV95vRN.mjs");
+		const { testChannelStreams } = await import("./DiagnosticsTools-QJ3CRYGA-CcYIIfQN.mjs");
 		return await testChannelStreams({
 			api: this,
 			channel: this.normalizeChannel(channel),
@@ -179104,7 +179493,7 @@ ${xml}`);
 	* @returns Complete diagnostics for all channels and streams
 	*/
 	async collectMultifocalDiagnostics(logger) {
-		const { collectMultifocalDiagnostics } = await import("./DiagnosticsTools-QJ3CRYGA-9NV95vRN.mjs");
+		const { collectMultifocalDiagnostics } = await import("./DiagnosticsTools-QJ3CRYGA-CcYIIfQN.mjs");
 		return await collectMultifocalDiagnostics({
 			api: this,
 			logger
@@ -230672,6 +231061,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.
@@ -230884,6 +231720,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.
@@ -231118,7 +232078,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 },
@@ -231540,7 +232500,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 },
@@ -231937,7 +232897,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 },
@@ -233611,7 +234571,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
@@ -233650,7 +234627,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`
@@ -233808,18 +234796,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.
 	*/
@@ -235018,6 +235994,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`. */
@@ -235027,16 +236008,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;
@@ -235189,14 +236173,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;
@@ -235253,6 +236253,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,
@@ -235266,6 +236268,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`
@@ -235349,7 +236373,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) {
@@ -235464,7 +236488,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 },
@@ -235646,7 +236671,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;
@@ -235676,7 +236701,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)) {
@@ -235908,7 +236933,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")) {
@@ -236871,7 +237896,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", {
@@ -237936,7 +238962,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) } });
 		}
@@ -238236,13 +239262,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 {}
 				}
 			};
@@ -239607,13 +240637,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) => {
@@ -240160,45 +241201,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",
@@ -240488,6 +241494,10 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 						]
 					}]
 				},
+				buildSnapshotFreshnessSection(cache, {
+					sleeping: this.isBattery && this.sleeping,
+					now: Date.now()
+				}),
 				...this.buildSessionsTabSections(),
 				...this.buildEmailPushSection(),
 				...this.buildEmailTabSections()
@@ -240554,10 +241564,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,
@@ -240576,7 +241586,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,
@@ -240595,8 +241605,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();
@@ -240789,12 +241805,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);
@@ -240812,13 +241823,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",
@@ -240959,7 +241973,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)
+				}
+			});
 		});
 	}
 	/**
@@ -243562,6 +244582,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
@@ -243839,4 +244897,4 @@ var ReolinkProviderAddon = class extends BaseDeviceProvider {
 	}
 };
 //#endregion
-export { ReolinkProviderAddon, collectNativeDiagnostics as a, runAllDiagnosticsConsecutively as c, testChannelStreams as d, collectMultifocalDiagnostics as i, runMultifocalDiagnosticsConsecutively as l, reolinkCameraSchema as n, collectNvrDiagnostics as o, collectCgiDiagnostics as r, createDiagnosticsBundle as s, ReolinkCamera as t, sampleStreams as u };
+export { ReolinkProviderAddon, collectMultifocalDiagnostics as a, createDiagnosticsBundle as c, sampleStreams as d, testChannelStreams as f, collectCgiDiagnostics as i, runAllDiagnosticsConsecutively as l, reolinkCameraSchema as n, collectNativeDiagnostics as o, reolinkDebugActions as r, collectNvrDiagnostics as s, ReolinkCamera as t, runMultifocalDiagnosticsConsecutively as u };