@camstack/addon-provider-reolink 1.2.82 → 1.2.83

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,
@@ -13395,6 +13417,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 +13773,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 +33574,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 +33763,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 +33781,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 +33880,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 +34036,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) {
@@ -35669,6 +36052,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 +231081,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 +231740,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 +232098,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 +232520,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 +232917,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 +234591,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 +234647,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 +234816,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 +236014,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 +236028,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 +236193,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 +236273,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 +236288,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 +236393,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 +236508,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 +236691,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 +236721,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 +236953,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 +237916,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 +238982,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 +239282,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 +240657,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 +241221,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 +241514,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 +241584,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 +241606,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 +241625,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 +241825,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 +241843,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 +241993,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)
+				}
+			});
 		});
 	}
 	/**
@@ -243582,6 +244602,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
@@ -243867,6 +244925,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;