@camstack/addon-matter-broker 0.2.58 → 0.2.59

package/dist/addon.js

@@ -12892,6 +12892,35 @@ var deviceProviderCapability = {
 			name: string$2(),
 			type: string$2()
 		}))),
+		/**
+		* 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$2() }), object({ deviceId: number() }), {
+			kind: "mutation",
+			timeoutMs: 3 * 6e4
+		}),
 		supportsDiscovery: method(object({}), boolean()),
 		/**
 		* Run a network scan. `params` carries optional provider-specific scan
@@ -13219,7 +13248,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$2(), unknown())), method(object({ deviceId: number() }), record(string$2(), unknown())), method(object({ deviceId: number() }), DeviceMetaSchema.nullable()), method(object({
 	deviceId: number(),
 	name: string$2()
@@ -32592,6 +32622,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.
 */
@@ -32640,6 +32811,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);
@@ -32657,9 +32829,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() {
@@ -32749,8 +32928,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:
@@ -32776,55 +33084,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) {
@@ -34587,6 +34948,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",

package/dist/addon.mjs

@@ -12890,6 +12890,35 @@ var deviceProviderCapability = {
 			name: string$2(),
 			type: string$2()
 		}))),
+		/**
+		* 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$2() }), object({ deviceId: number() }), {
+			kind: "mutation",
+			timeoutMs: 3 * 6e4
+		}),
 		supportsDiscovery: method(object({}), boolean()),
 		/**
 		* Run a network scan. `params` carries optional provider-specific scan
@@ -13217,7 +13246,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$2(), unknown())), method(object({ deviceId: number() }), record(string$2(), unknown())), method(object({ deviceId: number() }), DeviceMetaSchema.nullable()), method(object({
 	deviceId: number(),
 	name: string$2()
@@ -32590,6 +32620,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.
 */
@@ -32638,6 +32809,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);
@@ -32655,9 +32827,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() {
@@ -32747,8 +32926,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:
@@ -32774,55 +33082,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) {
@@ -34585,6 +34946,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",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/addon-matter-broker",
-  "version": "0.2.58",
+  "version": "0.2.59",
   "description": "Matter broker addon for CamStack — owns a Matter fabric (commissioning + the long-lived controller) via the matter.js controller and brokers commissioned Matter nodes into CamStack",
   "keywords": [
     "camstack",