@camstack/server 1.0.0 → 1.0.1

package/dist/core/addon/addon-registry.service.js

@@ -0,0 +1,2739 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AddonRegistryService = void 0;
+/* eslint-disable @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-argument, @typescript-eslint/no-unsafe-return, @typescript-eslint/no-unsafe-member-access -- pre-existing lint debt across this 2200-line orchestration class. The flagged sites (StorageService.setLocationManager / setSettingsBackend, LoggingService.addDestination, RouteRegistry, etc.) are typed as `unknown` by their owning services to break circular construction-order dependencies; runtime contracts are validated structurally. Tracked separately; do not amend in unrelated edits. */
+const os = __importStar(require("node:os"));
+const addon_row_manifest_1 = require("./addon-row-manifest");
+const types_1 = require("@camstack/types");
+const kernel_1 = require("@camstack/kernel");
+const kernel_2 = require("@camstack/kernel");
+const client_1 = require("@trpc/client");
+const kernel_3 = require("@camstack/kernel");
+const core_1 = require("@camstack/core");
+const node_crypto_1 = require("node:crypto");
+const path = __importStar(require("node:path"));
+const fs = __importStar(require("node:fs"));
+const node_url_1 = require("node:url");
+const addon_settings_provider_js_1 = require("./addon-settings-provider.js");
+const addon_call_gateway_js_1 = require("./addon-call-gateway.js");
+const types_2 = require("@camstack/types");
+const types_3 = require("@camstack/types");
+/**
+ * Type predicate: true when an `ISettingsBackend` also satisfies the
+ * sync `ISettingsStore` contract (system/addon/device key-value ops)
+ * that ConfigManager expects. The default `SqliteSettingsBackend` in
+ * `@camstack/core` implements both surfaces; forked addon backends may
+ * not, in which case we skip the ConfigService wiring.
+ */
+function isSettingsStore(backend) {
+    const required = [
+        'getSystem',
+        'setSystem',
+        'getAllSystem',
+        'getAllAddon',
+        'setAllAddon',
+        'getAllProvider',
+        'setProvider',
+        'getAllDevice',
+        'setDevice',
+        'getAddonDevice',
+        'setAddonDevice',
+        'clearAddonDevice',
+    ];
+    for (const key of required) {
+        if (typeof Reflect.get(backend, key) !== 'function')
+            return false;
+    }
+    return true;
+}
+/** Structural guard: true when an `addon-routes` provider also exposes `invoke`. */
+function isAddonRoutesInvoker(provider) {
+    return typeof Reflect.get(provider, 'invoke') === 'function';
+}
+const ROUTE_METHODS = [
+    'GET',
+    'POST',
+    'PUT',
+    'DELETE',
+];
+const ROUTE_ACCESS = [
+    'public',
+    'authenticated',
+    'admin',
+];
+function asRouteMethod(value) {
+    const upper = value.toUpperCase();
+    for (const m of ROUTE_METHODS)
+        if (m === upper)
+            return m;
+    throw new Error(`addon-routes: unsupported HTTP method "${value}"`);
+}
+function asRouteAccess(value) {
+    if (typeof value === 'string') {
+        for (const a of ROUTE_ACCESS)
+            if (a === value)
+                return a;
+    }
+    // Default to the most restrictive sensible default the original mount used.
+    return 'public';
+}
+function parseSerializableRouteDescriptors(raw) {
+    if (!Array.isArray(raw)) {
+        throw new Error('addon-routes: child returned a non-array route descriptor set');
+    }
+    return raw.map((entry) => {
+        if (entry === null || typeof entry !== 'object') {
+            throw new Error('addon-routes: route descriptor is not an object');
+        }
+        const method = Reflect.get(entry, 'method');
+        const path = Reflect.get(entry, 'path');
+        if (typeof method !== 'string' || typeof path !== 'string') {
+            throw new Error('addon-routes: route descriptor missing method/path');
+        }
+        const description = Reflect.get(entry, 'description');
+        return {
+            method: asRouteMethod(method),
+            path,
+            access: asRouteAccess(Reflect.get(entry, 'access')),
+            ...(typeof description === 'string' ? { description } : {}),
+        };
+    });
+}
+/**
+ * Parse the wire-boundary `unknown` from `callForked(..., {target:'data-planes'})`
+ * into typed data-plane endpoint descriptors (`prefix/access/baseUrl/secret`).
+ * Pure data — the addon's `ctx.dataPlane` facility produced them.
+ */
+function parseDataPlaneEndpoints(raw) {
+    if (!Array.isArray(raw)) {
+        throw new Error('data-planes: child returned a non-array endpoint set');
+    }
+    return raw.map((entry) => {
+        if (entry === null || typeof entry !== 'object') {
+            throw new Error('data-planes: endpoint descriptor is not an object');
+        }
+        const prefix = Reflect.get(entry, 'prefix');
+        const baseUrl = Reflect.get(entry, 'baseUrl');
+        const secret = Reflect.get(entry, 'secret');
+        if (typeof prefix !== 'string' || typeof baseUrl !== 'string' || typeof secret !== 'string') {
+            throw new Error('data-planes: endpoint descriptor missing prefix/baseUrl/secret');
+        }
+        return { prefix, access: asRouteAccess(Reflect.get(entry, 'access')), baseUrl, secret };
+    });
+}
+// Phase 11 (settings redesign): `stripValue` helper and the legacy
+// `getAddonConfigSchema / getAddonConfig / updateAddonConfig` adapter
+// shim that consumed it were deleted. All settings flow through the
+// new `getAddonSettings / getGlobalSettings / getDeviceSettings`
+// endpoints on the `addon-settings` singleton capability.
+class AddonRegistryService {
+    loggingService;
+    eventBusService;
+    configService;
+    storageService;
+    capabilityService;
+    moleculer;
+    streamProbe;
+    addonEntries = new Map();
+    capabilityRegistry;
+    /** Single router for addon-level calls (routes / custom / settings). */
+    addonCallGateway;
+    // Task 7.1: hub-wide registry of addon custom actions. Populated on
+    // each addon's initialize() (in-process path); Task 7.2 will dispatch
+    // through this from the `api.addons.custom` tRPC procedure.
+    customActionRegistry = new kernel_1.CustomActionRegistry();
+    /**
+     * AddonIds whose group-runner disconnect is operator-initiated (update /
+     * restart / uninstall). The Moleculer `$node.disconnected` handler skips
+     * these so the AddonCard doesn't flash a spurious "Failed to load" health
+     * banner during the kill→respawn window. The set is cleared as soon as
+     * `restartAddon` completes (success or failure) or by a 90s safety timer.
+     */
+    restartingAddons = new Map();
+    logger;
+    addonLoader;
+    healthMonitor;
+    addonRouteRegistry = null;
+    dataPlaneRegistry = null;
+    // Broker-routed AddonApi proxy — every addon's `ctx.api` resolves
+    // to this. Calls go through `broker.call('${addonId}.${capName}.${method}')`
+    // which Moleculer routes to whichever process actually hosts the
+    // capability (in-process services on the hub, forked workers, or
+    // remote agents). The hub uses the exact same transport as agents
+    // and forked workers — `ctx.api` is uniform across all deployment
+    // shapes. Lazily constructed so tests that don't wire the broker
+    // still instantiate the service.
+    brokerApi = null;
+    /**
+     * In-process tRPC client over the broker — same `AddonApi` shape every
+     * addon sees via `ctx.api`. Exposed as public so the REPL service can
+     * build a `SystemManager` from it without crossing the network boundary.
+     */
+    getBrokerApi() {
+        if (!this.brokerApi) {
+            const reg = this.capabilityRegistry;
+            const resolver = {
+                getByName: (capName) => reg.getSingleton(capName) ?? reg.getAllProviders(capName)[0] ?? null,
+            };
+            const client = (0, client_1.createTRPCClient)({
+                links: [(0, kernel_2.localProviderLink)(resolver), (0, kernel_2.brokerTransportLink)(this.moleculer.broker)],
+            });
+            this.brokerApi = client;
+        }
+        return this.brokerApi;
+    }
+    // Common settings resolver (3-level: defaults → global → per-device).
+    // Lazily constructed on first call to `getSettingsResolver()` so tests
+    // that don't exercise the settings API can instantiate the service
+    // without wiring ConfigService into the resolver.
+    // Active capability providers (set by consumers when capabilities are wired)
+    activeStorageProvider = null;
+    activeSettingsBackend = null;
+    integrationRegistry = null;
+    // Device architecture — in-memory registry of live IDevice instances.
+    // Persistence is owned by the `device-manager` capability addon.
+    deviceRegistry = new kernel_1.DeviceRegistry();
+    /**
+     * Typed accessor for the Moleculer broker. The Moleculer `index.d.ts`
+     * chains through `eventemitter2`, whose package.json has no `types`
+     * field; under `moduleResolution: node` typescript-eslint's parser
+     * loses the type chain even though `tsc` accepts it via `skipLibCheck`.
+     * Going through `this.moleculer.broker` directly produces "type cannot
+     * be resolved" errors at every call site. The local `BrokerLike`
+     * interface narrows down to the surface we actually use, and the
+     * double-cast forces the parser to materialize types locally so
+     * `this.broker.call(...)` / `this.broker.nodeID` lint clean.
+     */
+    get broker() {
+        return this.moleculer.broker;
+    }
+    constructor(loggingService, eventBusService, configService, storageService, capabilityService, moleculer, streamProbe) {
+        this.loggingService = loggingService;
+        this.eventBusService = eventBusService;
+        this.configService = configService;
+        this.storageService = storageService;
+        this.capabilityService = capabilityService;
+        this.moleculer = moleculer;
+        this.streamProbe = streamProbe;
+        this.logger = this.loggingService.createLogger('AddonRegistry');
+        this.addonLoader = new kernel_1.AddonLoader(this.loggingService.createLogger('AddonLoader'));
+        // Kernel-level addon health monitor — drives the 5-min boot grace
+        // window + aggressive auto-retry loop (60s/120s/300s, never gives
+        // up). Failures and recoveries are recorded by the load + init
+        // paths; the monitor's tick loop calls `tryReloadPackage` to
+        // reattempt failed addons. Operator visibility comes through
+        // AddonLoadFailed / AddonLoadRecovered events consumed by
+        // AlertCenter (see addon-health-monitor.ts spec).
+        this.healthMonitor = new kernel_1.AddonHealthMonitor({
+            eventBus: this.eventBusService,
+            logger: this.loggingService.createLogger('AddonHealthMonitor'),
+            retryFn: (packageName) => this.tryReloadPackage(packageName),
+        });
+        // Create capability registry with config reader for singleton preferences
+        this.capabilityRegistry = new kernel_1.CapabilityRegistry(this.loggingService.createLogger('CapabilityRegistry'), this.eventBusService);
+        this.capabilityRegistry.setConfigReader((capability) => {
+            try {
+                return this.configService.get(`capabilities.singleton.${capability}`) ?? undefined;
+            }
+            catch (err) {
+                this.logger.debug('settings-store not wired yet during early boot', {
+                    meta: { capability, error: (0, types_1.errMsg)(err) },
+                });
+                return undefined;
+            }
+        });
+        this.capabilityRegistry.setNodeConfigReader((capability, nodeId) => {
+            try {
+                return (this.configService.get(`capabilities.singletonNode.${capability}.${nodeId}`) ??
+                    undefined);
+            }
+            catch (err) {
+                this.logger.debug('settings-store not wired yet during early boot', {
+                    meta: { capability, nodeId, error: (0, types_1.errMsg)(err) },
+                });
+                return undefined;
+            }
+        });
+        // Collection-provider enable/disable persistence. Reads the same
+        // `capabilities.collection.<cap>` ConfigService key the `capabilities`
+        // router writes (`JSON.stringify({ disabled: string[] })`), so a
+        // collection provider an operator disabled survives a hub reboot.
+        this.capabilityRegistry.setCollectionConfigReader((capability) => {
+            try {
+                const raw = this.configService.get(`capabilities.collection.${capability}`);
+                if (!raw)
+                    return undefined;
+                const parsed = JSON.parse(raw);
+                if (typeof parsed === 'object' &&
+                    parsed !== null &&
+                    'disabled' in parsed &&
+                    Array.isArray(parsed.disabled)) {
+                    const disabled = parsed.disabled;
+                    return disabled.filter((id) => typeof id === 'string');
+                }
+                return undefined;
+            }
+            catch (err) {
+                this.logger.debug('settings-store not wired yet or malformed collection preference', {
+                    meta: { capability, error: (0, types_1.errMsg)(err) },
+                });
+                return undefined;
+            }
+        });
+        // Wire the registry into the CapabilityService so all server services can use it
+        this.capabilityService.setRegistry(this.capabilityRegistry);
+        // Register kernel-provided infrastructure capabilities so addons
+        // can resolve them via the capability registry like any other cap.
+        // These are kernel pseudo-caps (no tRPC methods, object-reference only),
+        // so we declare them with empty method maps before registering providers.
+        this.capabilityRegistry.declareCapability({
+            name: 'device-registry',
+            scope: 'system',
+            mode: 'singleton',
+            methods: {},
+        });
+        this.capabilityRegistry.declareCapability({
+            name: 'cluster-broker',
+            scope: 'system',
+            mode: 'singleton',
+            methods: {},
+        });
+        this.capabilityRegistry.registerProvider('device-registry', '$kernel', this.deviceRegistry);
+        this.capabilityRegistry.registerProvider('cluster-broker', '$kernel', {
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment -- moleculer types unresolvable; see `broker` getter docstring
+            broker: this.moleculer.broker,
+        });
+    }
+    async onModuleInit() {
+        // Register the addon-settings singleton provider — replaces the
+        // former `$addonHost` Moleculer service. The provider resolves
+        // addonId → local addon instance (hub) or remote Moleculer call.
+        this.capabilityRegistry.declareCapability(types_2.addonSettingsCapability);
+        // The SINGLE router for addon-level calls (routes / custom / settings).
+        // It classifies in-process | hub-local-child (UDS) | remote-agent
+        // (Moleculer) in ONE place — `resolveNode` reports only the BASE node
+        // (the hub for every hub-local addon, forked or not); the gateway's
+        // `isChildKnown` distinguishes a forked UDS child from an in-process
+        // builtin. This is the fix for forked-addon settings: they were forced
+        // down a dead `<addonId>.settings.*` Moleculer path because the old
+        // `resolveNode` marked them non-local; now they route over UDS like
+        // their routes + custom-actions already do.
+        this.addonCallGateway = new addon_call_gateway_js_1.AddonCallGateway({
+            hubNodeId: this.broker.nodeID,
+            resolveNode: (addonId) => {
+                const entry = this.addonEntries.get(addonId);
+                // Every addon in `addonEntries` is hub-local — report the hub node;
+                // forked-vs-in-process is decided by `isChildKnown` in the gateway.
+                return entry ? this.broker.nodeID : 'hub';
+            },
+            getChildRegistry: () => this.moleculer.childRegistry,
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment -- moleculer types unresolvable; see `broker` getter docstring
+            broker: this.moleculer.broker,
+        });
+        const settingsProvider = (0, addon_settings_provider_js_1.createAddonSettingsProvider)({
+            getAddon: (addonId) => {
+                const entry = this.addonEntries.get(addonId);
+                return entry?.addon ?? null;
+            },
+            gateway: this.addonCallGateway,
+        });
+        this.capabilityRegistry.registerProvider('addon-settings', '$hub', settingsProvider);
+        // Wire capability consumer actions via EventBus
+        this.wireCapabilityConsumers();
+        // Subscribe to capability.binding-changed so hub-side capability
+        // overrides take effect on the fly. The orchestrator addon emits
+        // these when the operator swaps the addon implementing a cap on a
+        // node; we only react when the target node is the hub's own nodeID.
+        this.eventBusService.subscribe({ category: 'capability.binding-changed' }, (event) => {
+            const data = (event.data ?? {});
+            if (!data.capName)
+                return;
+            const localNodeId = this.broker.nodeID;
+            if (data.nodeId && data.nodeId !== localNodeId)
+                return;
+            this.capabilityRegistry.setSingletonActiveAddon(data.capName, data.addonId ?? null);
+        });
+        // 2. Load all addons from data/addons/ directory (including core builtins)
+        const dataDir = path.resolve(process.env.CAMSTACK_DATA ?? 'camstack-data');
+        const addonsDir = path.resolve(dataDir, 'addons');
+        await this.addonLoader.loadFromDirectory(addonsDir);
+        // Hand pre-init load failures (broken package.json, missing
+        // dist, import-time errors) to the health monitor so its retry
+        // loop and post-grace alerting cover them. Failures during the
+        // init phase below are recorded separately.
+        for (const fail of this.addonLoader.listLoadFailures()) {
+            this.healthMonitor.recordFailure(fail.packageName, fail.error, fail.addonId);
+        }
+        const loadedAddons = this.addonLoader.listAddons();
+        for (const registered of loadedAddons) {
+            // Skip agent-only addons — they never run on the hub, only on remote
+            // agents that opt in via `execution.placement: 'agent-only'`.
+            if ((0, types_1.isAgentOnlyPlacement)(registered.declaration)) {
+                this.logger.info('Skipping agent-only addon on hub', {
+                    tags: { addonId: registered.declaration.id },
+                    meta: { packageName: registered.packageName },
+                });
+                continue;
+            }
+            if (registered.declaration.capabilities) {
+                for (const cap of registered.declaration.capabilities) {
+                    this.capabilityRegistry.declareFromManifest(cap, registered.declaration.id);
+                }
+            }
+            // Create and store addon instance — cast from @camstack/types to server's
+            // local ICamstackAddon (structurally compatible at runtime).
+            // Wrap in try/catch so a single broken addon doesn't prevent the rest from loading.
+            try {
+                const addon = this.addonLoader.createInstance(registered.declaration.id);
+                // Capabilities come from package.json declaration (source of truth),
+                // merged with any declared in the addon class manifest.
+                const declCaps = (registered.declaration.capabilities ?? []).map((c) => typeof c === 'string' ? { name: c, mode: 'singleton' } : c);
+                this.addonEntries.set(registered.declaration.id, {
+                    addon,
+                    initialized: false,
+                    source: 'installed',
+                    packageName: registered.packageName,
+                    packageVersion: registered.packageVersion,
+                    packageDisplayName: registered.packageDisplayName,
+                    ...(registered.bundle !== undefined ? { bundle: registered.bundle } : {}),
+                    declaredCapabilities: declCaps,
+                    addonDir: path.join(addonsDir, registered.packageName),
+                    declaration: registered.declaration,
+                });
+            }
+            catch (err) {
+                const msg = (0, types_1.errMsg)(err);
+                this.logger.error('Failed to create instance of addon', {
+                    tags: { addonId: registered.declaration.id },
+                    meta: { error: msg },
+                });
+            }
+        }
+        this.logger.info('Loaded addons from directory', {
+            meta: { count: loadedAddons.length, addonsDir },
+        });
+        // Platform probing is no longer orchestrated by the backend. The
+        // `platform-probe` capability (shipped as a core builtin under
+        // `@camstack/core/dist/builtins/platform-probe/` since Phase B of
+        // the bundles refactor) exposes hardware + scored backends via
+        // `ctx.api.platformProbe.*`; inference addons auto-configure
+        // inside their own `onInitialize`.
+        // 4. Initialize all installed addons in correct order (installed = active)
+        const allIds = [...this.addonEntries.keys()];
+        // Mark registry as ready BEFORE any addon initializes. Addons' onInitialize
+        // may call ctx.api.<cap>.* which routes through localProviderLink; that
+        // resolver depends on getAllProviders/getSingleton which gate on `_ready`.
+        // Without this, Phase 1 and Phase 2 addons would all fall through to the
+        // Moleculer broker transport and fail with "service not registered".
+        this.capabilityRegistry.ready();
+        // Native-cap cross-process bridge: when a hub consumer resolves a native
+        // provider for a device whose IDevice lives in a forked worker, we
+        // return a proxy that routes calls to the correct transport.
+        //
+        // G2 — single ownership authority: the CapRouteResolver is consulted FIRST
+        // for hub-local native caps. If the resolver's snapshot identifies a
+        // hub-local-uds route for (capName, deviceId), we build the proxy directly —
+        // no `resolveNativeCapOwnerSync` consult needed for this branch. The resolver's
+        // `hubLocalChildProvides(capName, deviceId)` is the canonical hub-local authority
+        // (fed by the same LocalChildRegistry that owns UDS dispatch), so the old
+        // `owner.nodeId.startsWith(hubNodeId + '/')` gate is replaced by the resolver's
+        // own verdict.
+        //
+        // `resolveNativeCapOwnerSync` is only consulted for the REMOTE branch: when the
+        // resolver throws no-provider for the hub node (no hub-local-uds child owns the cap),
+        // the fallback queries `resolveNativeCapOwnerSync` to find a remote owner. That
+        // method carries data (push-fed `remoteNativeCaps` from `DeviceBindingsChanged`
+        // events) that the resolver's `NodeCapAuthority` doesn't see, so it stays as the
+        // remote-branch source. If `resolveNativeCapOwnerSync` also returns null, the cap
+        // genuinely has no cross-process provider and the fallback returns null — wrappers
+        // cleanly fall through to their own secondary strategy.
+        {
+            const { buildNativeCapProxy } = await Promise.resolve().then(() => __importStar(require('@camstack/kernel')));
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment -- moleculer types unresolvable; see `broker` getter docstring
+            const broker = this.moleculer.broker;
+            this.capabilityRegistry.setNativeFallback((capName, deviceId) => {
+                const resolver = this.moleculer.capRouteResolver;
+                const hubNodeId = this.moleculer.nodeId;
+                // 1. Hub-local path: the resolver's hub-local-child authority is the
+                //    single source of truth for whether a forked hub-local UDS child
+                //    owns (capName, deviceId) — via hubLocalChildProvides +
+                //    getHubLocalChildId (both deviceId-aware, M1).
+                //
+                //    We deliberately use `resolveHubLocalUdsRoute`, NOT
+                //    `resolveCapRoute`: this fallback's contract is to reach the
+                //    NATIVE provider in the forked vendor child. `resolveCapRoute`
+                //    gives Priority 1 to `hub-in-process`, so a cap that ALSO has an
+                //    in-hub provider for the same name (a wrapper — today `snapshot`)
+                //    would classify as `hub-in-process` (the wrapper) and never reach
+                //    the hub-local-uds native. That made the wrapper's
+                //    `getNativeProvider` return null and silently fall through to its
+                //    secondary strategy (e.g. snapshot's ffmpeg frame grab), so the
+                //    vendor native snapshot was never invoked. `resolveHubLocalUdsRoute`
+                //    skips the in-process branch and returns the native child route.
+                if (resolver !== null) {
+                    const route = resolver.resolveHubLocalUdsRoute(capName, deviceId);
+                    if (route !== null) {
+                        const childId = route.childId;
+                        const target = {};
+                        return new Proxy(target, {
+                            get(_target, property) {
+                                if (typeof property !== 'string')
+                                    return undefined;
+                                return (input) => {
+                                    const mergedInput = typeof input === 'object' && input !== null
+                                        ? { ...input, deviceId }
+                                        : { deviceId };
+                                    // Re-resolve at call time so a child that respawned under a
+                                    // new runner id is still reachable (route is cheap to build).
+                                    const r = resolver.resolveHubLocalUdsRoute(capName, deviceId) ?? {
+                                        kind: 'hub-local-uds',
+                                        capName,
+                                        childId,
+                                    };
+                                    return resolver.dispatch(r, property, mergedInput);
+                                };
+                            },
+                        });
+                    }
+                    // No hub-local child owns (capName, deviceId). Fall through to the
+                    // remote branch — resolveNativeCapOwnerSync is still consulted there
+                    // and may find a remote owner for this (capName, deviceId).
+                }
+                // 2. Remote path: resolver has no hub-local route for this (capName, deviceId).
+                //    Consult resolveNativeCapOwnerSync — it includes push-fed remoteNativeCaps
+                //    (DeviceBindingsChanged events from forked workers) that the resolver's
+                //    NodeCapAuthority (backed by HubNodeRegistry) doesn't carry.
+                const dm = this.capabilityRegistry.getSingleton('device-manager');
+                const owner = dm?.resolveNativeCapOwnerSync?.(capName, deviceId) ?? null;
+                if (!owner)
+                    return null;
+                // Guard: skip hub-local owners here — they were already handled (or skipped
+                // because the resolver was null / not initialised yet). Returning null avoids
+                // building a Moleculer proxy that points at a UDS-only child.
+                if (owner.nodeId.startsWith(`${hubNodeId}/`))
+                    return null;
+                // Remote native cap → Moleculer with native-provider infix.
+                // buildNativeCapProxy uses the action `${addonId}.native-provider.${cap}.${method}`.
+                return buildNativeCapProxy(broker, owner.addonId, capName, deviceId);
+            });
+        }
+        // Runner spawn: every non-core, placement-eligible addon runs in its
+        // OWN forked runner subprocess by default (base-layer D2/D9 — one
+        // addon, one process). No shipped addon declares a shared
+        // `execution.group`: Phase 5 dissolved the `pipeline` media group
+        // once frames travel as shm `FrameHandle`s and audio over tRPC.
+        // `buildAddonGroupPlan` keys the plan by runner id (the addon id);
+        // cross-runner / cross-node cap calls travel over Moleculer TCP.
+        // `resolveRunnerId` still collapses a shared `execution.group` if
+        // one were declared — the mechanism stays available as an explicit
+        // opt-in for future co-location needs.
+        //
+        // `@camstack/core` builtins and `placement: 'agent-only'` addons are
+        // excluded from the plan (filtered inside `buildAddonGroupPlan`).
+        // A failed runner spawn is logged and the addon surfaces as
+        // `addon.error` — there is NO in-process-on-the-hub fallback (it
+        // would violate one-addon-one-process). Retry policy for a failed
+        // spawn is governed by the kernel circuit-breaker.
+        {
+            const plan = this.buildAddonGroupPlan(allIds);
+            for (const [runnerId, runnerAddons] of plan) {
+                try {
+                    await this.initializeAddonGroup(runnerId, runnerAddons);
+                    for (const { addonId } of runnerAddons) {
+                        this.wireCapabilities(addonId);
+                    }
+                }
+                catch (error) {
+                    const msg = (0, types_1.errMsg)(error);
+                    for (const { addonId } of runnerAddons) {
+                        this.emitAddonLifecycleEvent('addon.error', addonId, {
+                            error: msg,
+                            phase: 'init',
+                        });
+                    }
+                    this.logger.error('Runner spawn failed — addons on this runner will be skipped', {
+                        meta: { runnerId, addonIds: runnerAddons.map((a) => a.addonId), error: msg },
+                    });
+                }
+            }
+        }
+        // In-process boot for `@camstack/core` builtins. Core builtins stay
+        // resident on the hub process — they provide the storage / settings
+        // / logging infrastructure every forked runner depends on, reachable
+        // via the hub broker, so `buildAddonGroupPlan` excludes them from
+        // the runner plan above. They boot in two ordered passes:
+        // infrastructure caps first (`INFRA_CAPABILITIES`,
+        // storage→settings→logging), then the remaining builtins in
+        // capability-dependency order.
+        //
+        // A core builtin is identified by `packageName === "@camstack/core"`,
+        // NOT by the absence of an `execution` declaration — a builtin may
+        // still declare `execution` (e.g. `platform-probe`); the package
+        // boundary is the selection criterion.
+        const isCoreBuiltin = (id) => this.addonEntries.get(id)?.packageName === '@camstack/core';
+        // Pass 1 — infrastructure builtins. A failed REQUIRED infra cap
+        // aborts boot: nothing downstream can run without storage/settings.
+        for (const infra of kernel_1.INFRA_CAPABILITIES) {
+            const addonId = this.findAddonForCapability(infra.name, allIds);
+            if (addonId) {
+                const entry = this.addonEntries.get(addonId);
+                // Only core builtins boot in-process here. A non-core addon that
+                // happens to provide an infra cap (e.g. an alternate
+                // storage-provider) lives in its own runner — never in-process.
+                if (!entry || entry.initialized || !isCoreBuiltin(addonId))
+                    continue;
+                try {
+                    await this.initializeAddon(addonId);
+                    this.wireCapabilities(addonId);
+                }
+                catch (error) {
+                    const msg = (0, types_1.errMsg)(error);
+                    this.emitAddonLifecycleEvent('addon.error', addonId, {
+                        error: msg,
+                        phase: 'init',
+                    });
+                    if (infra.required) {
+                        throw new Error(`Required infrastructure addon "${addonId}" failed: ${msg}`, {
+                            cause: error,
+                        });
+                    }
+                    this.logger.warn('Optional infra addon failed -- continuing', {
+                        tags: { addonId },
+                        meta: { error: msg },
+                    });
+                }
+            }
+            else if (infra.required) {
+                throw new Error(`No addon provides required infrastructure capability "${infra.name}"`);
+            }
+        }
+        // Pass 2 — remaining core builtins, in capability-dependency order.
+        const bootOrder = this.capabilityRegistry.getBootOrder();
+        const infraNames = new Set(kernel_1.INFRA_CAPABILITIES.map((c) => c.name));
+        for (const capName of bootOrder) {
+            if (infraNames.has(capName))
+                continue; // Handled in pass 1
+            for (const id of allIds) {
+                const entry = this.addonEntries.get(id);
+                if (!entry || entry.initialized || !isCoreBuiltin(id))
+                    continue;
+                // Check if this addon provides this capability
+                const provides = this.getAddonCapabilities(entry.addon);
+                if (!provides.some((c) => c.name === capName))
+                    continue;
+                try {
+                    await this.initializeAddon(id);
+                    this.wireCapabilities(id);
+                }
+                catch (error) {
+                    const msg = (0, types_1.errMsg)(error);
+                    this.emitAddonLifecycleEvent('addon.error', id, {
+                        error: msg,
+                        phase: 'init',
+                    });
+                    this.logger.error('Core builtin failed to initialize -- skipping', {
+                        tags: { addonId: id },
+                        meta: { error: msg },
+                    });
+                }
+            }
+        }
+        // Pass 3 — core builtins that declare no capabilities at all.
+        for (const id of allIds) {
+            const entry = this.addonEntries.get(id);
+            if (entry && !entry.initialized && isCoreBuiltin(id)) {
+                try {
+                    await this.initializeAddon(id);
+                    this.wireCapabilities(id);
+                }
+                catch (error) {
+                    const msg = (0, types_1.errMsg)(error);
+                    this.emitAddonLifecycleEvent('addon.error', id, {
+                        error: msg,
+                        phase: 'init',
+                    });
+                    this.logger.error('Core builtin failed to initialize -- skipping', {
+                        tags: { addonId: id },
+                        meta: { error: msg },
+                    });
+                }
+            }
+        }
+        const initializedIds = [...this.addonEntries.entries()]
+            .filter(([, e]) => e.initialized)
+            .map(([id]) => id);
+        this.logger.info('Addons initialized', {
+            meta: { initializedCount: initializedIds.length, totalCount: this.addonEntries.size },
+        });
+        // Health snapshot: every addon entry that survived the loader is
+        // either initialized (record success) or failed init (record
+        // failure with the captured error). Pre-load failures were already
+        // recorded above from `addonLoader.listLoadFailures()`.
+        for (const [id, entry] of this.addonEntries.entries()) {
+            if (entry.initialized) {
+                this.healthMonitor.recordSuccess(entry.packageName, id);
+            }
+            else {
+                // Init failed (caught by either Phase 1 or Phase 2 catch
+                // blocks above). The catch handlers don't carry the error
+                // forward to here, so we synthesize a generic one — the real
+                // error is in the addon log. Operators see the alert + can
+                // open the per-addon logs to investigate.
+                this.healthMonitor.recordFailure(entry.packageName, new Error(`Addon "${id}" failed to initialize — see addon logs for details`), id);
+            }
+        }
+        // Start the kernel-level retry tick (30s). Fires immediately
+        // on the first interval boundary; the 5-min boot grace window
+        // suppresses alerts until the system has had time to stabilize.
+        this.healthMonitor.start();
+        const localBus = this.moleculer.broker.localBus;
+        if (localBus) {
+            localBus.on('$node.disconnected', (payload) => {
+                const nodeId = payload.node?.id;
+                if (!nodeId || nodeId === this.broker.nodeID)
+                    return;
+                for (const [id, entry] of this.addonEntries.entries()) {
+                    if (!entry.declaration)
+                        continue;
+                    const runnerId = (0, types_1.resolveRunnerId)(entry.declaration, id);
+                    if (`${this.broker.nodeID}/${runnerId}` !== nodeId)
+                        continue;
+                    // Skip operator-initiated restarts — `restartAddon` already
+                    // waits for caps to re-register and surfaces its own failure
+                    // path. Recording a transient failure here would flash the
+                    // "Failed to load" banner on AddonCard during a routine update.
+                    if (this.restartingAddons.has(id))
+                        continue;
+                    // Record one failure per addon on the disconnected runner.
+                    // The error message references the nodeId — the operator
+                    // can correlate with process-service.ts respawn logs.
+                    this.healthMonitor.recordFailure(entry.packageName, new Error(`Addon runner ${nodeId} disconnected`), id);
+                }
+            });
+            localBus.on('$node.connected', (payload) => {
+                const nodeId = payload.node?.id;
+                if (!nodeId || nodeId === this.broker.nodeID)
+                    return;
+                for (const [id, entry] of this.addonEntries.entries()) {
+                    if (!entry.declaration)
+                        continue;
+                    const runnerId = (0, types_1.resolveRunnerId)(entry.declaration, id);
+                    if (`${this.broker.nodeID}/${runnerId}` !== nodeId)
+                        continue;
+                    this.healthMonitor.recordSuccess(entry.packageName, id);
+                }
+            });
+        }
+        this.eventBusService.emit({
+            id: (0, node_crypto_1.randomUUID)(),
+            timestamp: new Date(),
+            source: { type: 'core', id: 'addon-registry' },
+            category: types_1.EventCategory.SystemAddonsReady,
+            data: { activeAddons: initializedIds },
+        });
+    }
+    /**
+     * Reload a single package — invoked by AddonHealthMonitor's retry
+     * loop and by the operator-facing `addons.retryLoad` tRPC procedure.
+     *
+     * Two paths:
+     *   1. Package not yet in the registry (e.g. import failed at boot
+     *      time): re-walk the addons dir, pick up any new package, run
+     *      `initializeAddon` for each contained addon.
+     *   2. Package already in the registry but its addon entries failed
+     *      init: call `restartAddon` for each addon in that package.
+     *
+     * On success the monitor automatically records the addon healthy
+     * (no explicit recordSuccess needed — the `attemptRetry` no-throw
+     * fast path handles it). On failure this method throws and the
+     * monitor's catch path schedules the next retry.
+     */
+    async tryReloadPackage(packageName) {
+        const dataDir = path.resolve(process.env.CAMSTACK_DATA ?? 'camstack-data');
+        const addonsDir = path.resolve(dataDir, 'addons');
+        const addonDir = path.join(addonsDir, packageName);
+        if (!fs.existsSync(addonDir)) {
+            throw new Error(`Package directory missing: ${addonDir}`);
+        }
+        // Branch 1: package known to the registry already → restart each
+        // addon entry. `restartAddon` rebuilds AddonContext + runs init
+        // again; on success the entry's `initialized` flag flips back to
+        // true and the monitor's auto-resolve path records success.
+        const knownAddonIds = [];
+        for (const [id, entry] of this.addonEntries.entries()) {
+            if (entry.packageName === packageName) {
+                knownAddonIds.push(id);
+            }
+        }
+        if (knownAddonIds.length > 0) {
+            const errors = [];
+            for (const id of knownAddonIds) {
+                try {
+                    await this.restartAddon(id);
+                    this.healthMonitor.recordSuccess(packageName, id);
+                }
+                catch (err) {
+                    errors.push(`${id}: ${(0, types_1.errMsg)(err)}`);
+                    this.healthMonitor.recordFailure(packageName, err, id);
+                }
+            }
+            if (errors.length > 0) {
+                throw new Error(`tryReloadPackage failed for ${packageName}: ${errors.join('; ')}`);
+            }
+            return;
+        }
+        // Branch 2: package not yet known → run loadNewAddons which
+        // walks disk, instantiates new entries, and initializes them.
+        // It records its own loaded/failed in the return; we re-throw
+        // when our package is in the failed list so the monitor knows.
+        const result = await this.loadNewAddons();
+        if (result.failed.length > 0) {
+            const failed = result.failed.join(', ');
+            throw new Error(`loadNewAddons reported failures: ${failed}`);
+        }
+        if (result.loaded.length === 0) {
+            throw new Error(`No new addons loaded for ${packageName} — package may still have a broken manifest`);
+        }
+        // Match loaded addons to this package + record success.
+        for (const id of result.loaded) {
+            const entry = this.addonEntries.get(id);
+            if (entry?.packageName === packageName) {
+                this.healthMonitor.recordSuccess(packageName, id);
+            }
+        }
+    }
+    /** Health snapshot — exposed to the addons.list tRPC procedure. */
+    getAddonHealthSnapshot() {
+        return this.healthMonitor.getHealthSnapshot();
+    }
+    /** Manual user-triggered retry (resets retry counter). */
+    async retryAddonLoad(packageName) {
+        return this.healthMonitor.retryNow(packageName);
+    }
+    async onModuleDestroy() {
+        this.logger.info('Shutting down all addons…');
+        this.healthMonitor.stop();
+        await this.shutdownAll();
+        this.logger.info('All addons shut down');
+    }
+    /** Set the AddonRouteRegistry for wiring addon-routes capabilities */
+    setAddonRouteRegistry(registry) {
+        this.addonRouteRegistry = registry;
+    }
+    /** Set the DataPlaneRegistry the hub's `/addon/:id/*` dispatch reverse-proxies
+     *  against (addon HTTP data-planes). */
+    setDataPlaneRegistry(registry) {
+        this.dataPlaneRegistry = registry;
+    }
+    /**
+     * Pull a forked addon's HTTP data-plane endpoints over UDS and register them so
+     * the hub can reverse-proxy `/addon/<addonId>/<prefix>/*` to the addon's own
+     * listener. Idempotent (replace-all); an addon with no data-plane registers an
+     * empty set (cleared). Called off the capabilities-changed signal — a data-plane
+     * isn't a cap, but the child is UDS-reachable and has served its endpoints by
+     * the time any of its caps register.
+     */
+    async mountAddonDataPlanes(addonId) {
+        const registry = this.dataPlaneRegistry;
+        if (!registry)
+            return;
+        const entry = this.addonEntries.get(addonId);
+        const childRegistry = this.moleculer.childRegistry;
+        // Forked addons only for now — co-located builtins would publish into the
+        // registry directly via a hub-side sink (deferred; no builtin serves a
+        // data-plane yet).
+        if (!entry || !this.isForkedAddonEntry(entry))
+            return;
+        if (childRegistry === null || !childRegistry.isChildKnown(addonId))
+            return;
+        const raw = await this.addonCallGateway.callForked(addonId, { target: 'data-planes' });
+        const endpoints = parseDataPlaneEndpoints(raw);
+        registry.registerAddon(addonId, endpoints);
+        if (endpoints.length > 0) {
+            this.logger.info('Addon data-planes mounted (reverse-proxy)', {
+                meta: { phase: 'v2', addonId, prefixes: endpoints.map((e) => e.prefix) },
+            });
+        }
+    }
+    /**
+     * Called after app.init() when the tRPC router is available.
+     * No-op now: addon `ctx.api` resolves to a broker-routed proxy, so
+     * the direct tRPC caller is no longer constructed. Kept for backward
+     * compat with `main.ts`'s bootstrap order.
+     */
+    async setAppRouter(_router) {
+        this.logger.debug('setAppRouter called — broker-routed addon API in use, no direct caller needed');
+    }
+    /** Get the CapabilityRegistry for external consumers to register */
+    getCapabilityRegistry() {
+        return this.capabilityRegistry;
+    }
+    /** Get the CustomActionRegistry — Task 7.2 will use this from the `api.addons.custom` tRPC procedure. */
+    getCustomActionRegistry() {
+        return this.customActionRegistry;
+    }
+    getDeviceRegistry() {
+        return this.deviceRegistry;
+    }
+    /** Load persisted collection disabled-lists from settings-store into the registry */
+    loadCollectionPreferences() {
+        // TODO: implement CapabilityRegistry.loadDisabledProviders() to restore persisted preferences
+    }
+    /**
+     * Returns the IntegrationRegistry filtered to exclude orphaned integrations
+     * (where the addon is not currently installed). Orphaned data stays in DB
+     * and reconnects automatically when the addon is reinstalled.
+     */
+    getIntegrationRegistry() {
+        if (!this.integrationRegistry)
+            return null;
+        return this.createFilteredRegistry(this.integrationRegistry);
+    }
+    /**
+     * Return the currently-active settings backend (the `settings-store`
+     * capability provider). Null if no provider has been registered yet
+     * (e.g. during early boot before builtins are loaded). Used by the
+     * multi-level addon settings router to read/write addon-device
+     * overrides directly.
+     */
+    getSettingsBackend() {
+        return this.activeSettingsBackend;
+    }
+    /** Get the raw (unfiltered) registry — only for internal addon wiring */
+    getRawIntegrationRegistry() {
+        return this.integrationRegistry;
+    }
+    createFilteredRegistry(raw) {
+        const installedAddonIds = new Set(this.addonEntries.keys());
+        // Build set of integration IDs whose addon IS installed
+        // Cache per call — lightweight, called infrequently
+        let activeIntegrationIds = null;
+        const ensureActiveIds = async () => {
+            if (activeIntegrationIds)
+                return activeIntegrationIds;
+            const all = await raw.listIntegrations();
+            activeIntegrationIds = new Set(all.filter((i) => installedAddonIds.has(i.addonId)).map((i) => i.id));
+            return activeIntegrationIds;
+        };
+        return {
+            // Integrations: filter out orphaned
+            createIntegration: (input) => raw.createIntegration(input),
+            getIntegration: async (id) => {
+                const i = await raw.getIntegration(id);
+                return i && installedAddonIds.has(i.addonId) ? i : null;
+            },
+            getIntegrationByAddonId: async (addonId) => {
+                if (!installedAddonIds.has(addonId))
+                    return null;
+                return raw.getIntegrationByAddonId(addonId);
+            },
+            listIntegrations: async () => {
+                const all = await raw.listIntegrations();
+                return all.filter((i) => installedAddonIds.has(i.addonId));
+            },
+            updateIntegration: (id, updates) => raw.updateIntegration(id, updates),
+            deleteIntegration: (id) => raw.deleteIntegration(id),
+            // Integration settings: passthrough (already gated by getIntegration)
+            getIntegrationSettings: (id) => raw.getIntegrationSettings(id),
+            setIntegrationSetting: (id, key, value) => raw.setIntegrationSetting(id, key, value),
+            setIntegrationSettings: (id, settings) => raw.setIntegrationSettings(id, settings),
+            // Devices: filter out devices belonging to orphaned integrations
+            createDevice: (input) => raw.createDevice(input),
+            getDevice: async (id) => {
+                const d = await raw.getDevice(id);
+                if (!d)
+                    return null;
+                const ids = await ensureActiveIds();
+                return ids.has(d.integrationId) ? d : null;
+            },
+            getDeviceByStableId: async (stableId) => {
+                const d = await raw.getDeviceByStableId(stableId);
+                if (!d)
+                    return null;
+                const ids = await ensureActiveIds();
+                return ids.has(d.integrationId) ? d : null;
+            },
+            listDevices: async (integrationId) => {
+                const devices = await raw.listDevices(integrationId);
+                const ids = await ensureActiveIds();
+                return devices.filter((d) => ids.has(d.integrationId));
+            },
+            listCameras: async () => {
+                const cameras = await raw.listCameras();
+                const ids = await ensureActiveIds();
+                return cameras.filter((d) => ids.has(d.integrationId));
+            },
+            updateDevice: (id, updates) => raw.updateDevice(id, updates),
+            deleteDevice: (id) => raw.deleteDevice(id),
+            // Device settings: passthrough
+            getDeviceSettings: (id) => raw.getDeviceSettings(id),
+            setDeviceSetting: (id, key, value) => raw.setDeviceSetting(id, key, value),
+            setDeviceSettings: (id, settings) => raw.setDeviceSettings(id, settings),
+        };
+    }
+    // InferenceCapabilitiesService removed — now lives in pipeline-executor addon.
+    // Use capabilityRegistry.getSingleton('pipeline-executor') instead.
+    /** Log a standardized lifecycle line for addon start/restart */
+    logAddonLifecycle(event, id, mode) {
+        const entry = this.addonEntries.get(id);
+        if (!entry)
+            return;
+        const agentName = process.env.CAMSTACK_AGENT_NAME ?? 'hub';
+        const platform = `${os.platform()}/${os.arch()}`;
+        const message = `Addon ${event} — v${entry.packageVersion} (${entry.packageName}), ${mode}, ${platform}, agent: ${agentName}`;
+        // Log under AddonRegistry scope
+        this.logger.info(message, {
+            tags: { addonId: id, agentId: agentName },
+            meta: { phase: 'lifecycle' },
+        });
+        // Also log under the addon's own tagged logger so it appears in the per-addon
+        // log viewer. No scope — brand bracket shows the addon id.
+        const addonLogger = this.loggingService.createLogger();
+        addonLogger.info(message, { tags: { addonId: id, agentId: agentName } });
+    }
+    // Platform probing and inference-config resolution have moved into the
+    // `platform-probe` capability. Addons call `ctx.api.platformProbe.*`
+    // during their own initialize(). The backend no longer loops addons
+    // looking for `getModelRequirements` / `configure` — those hooks were
+    // removed from the ICamstackAddon contract.
+    registerAddon(addon, source = 'installed', packageName, packageVersion) {
+        const manifest = addon.manifest;
+        if (!manifest) {
+            throw new Error('Cannot register addon without manifest — was it created via AddonLoader.createInstance()?');
+        }
+        this.addonEntries.set(manifest.id, {
+            addon,
+            initialized: false,
+            source,
+            packageName: packageName ?? manifest.name ?? manifest.id,
+            packageVersion: packageVersion ?? manifest.version ?? '0.0.0',
+            declaredCapabilities: this.getAddonCapabilities(addon),
+        });
+    }
+    async initializeAddon(id) {
+        const entry = this.addonEntries.get(id);
+        if (!entry) {
+            throw new Error(`Addon "${id}" is not registered`);
+        }
+        if (!entry.addon?.manifest?.id) {
+            throw new Error(`Addon "${id}" has no manifest.id — check the addon class default export`);
+        }
+        // Decide whether this addon should boot in its own forked runner
+        // subprocess. The runner-spawn pass during initial boot already
+        // spawned every eligible addon; `initializeAddon` is the per-addon
+        // entry point reached by the hot-load / restart flows (and by the
+        // Pass 1/2/3 in-process boot for `@camstack/core` builtins). Fork
+        // only when the addon declares an `execution` block, ships an
+        // on-disk `addonDir`, and is not `agent-only`; otherwise (only
+        // `@camstack/core` builtins reach the in-process path below) it
+        // boots in-process on the hub.
+        if (this.isForkedAddonEntry(entry)) {
+            // D5: one-addon-one-process. A forked addon ALWAYS boots in its
+            // own runner — there is NO in-process-on-the-hub fallback. If the
+            // runner spawn fails, the addon is `failed`, surfaced as
+            // `addon.error` + recorded on the health monitor; it does not
+            // silently run on the hub. (Task 7's circuit breaker governs the
+            // retry policy on top of this.)
+            try {
+                await this.broker.call('$process.spawnRunner', {
+                    runnerId: id,
+                    addons: [{ addonId: id, addonDir: entry.addonDir }],
+                });
+            }
+            catch (err) {
+                const msg = (0, types_1.errMsg)(err);
+                this.logger.error('Failed to spawn isolated runner for addon', {
+                    tags: { addonId: id },
+                    meta: { error: msg },
+                });
+                this.emitAddonLifecycleEvent('addon.error', id, {
+                    error: msg,
+                    action: 'initialize',
+                });
+                this.healthMonitor.recordFailure(entry.packageName, err, id);
+                throw new Error(`Failed to spawn runner for addon "${id}": ${msg}`, { cause: err });
+            }
+            // Provider registration for forkable addons is delegated to the
+            // `CapabilityBridge` (see `MoleculerService.onProviderConnected`).
+            // When the spawned child announces its Moleculer service via
+            // NODE_INFO, the bridge builds a proxy from the capability
+            // definition (`{ id, nodeId, ...methods }`) and registers it.
+            //
+            // Custom actions: read the catalog fresh from the on-disk bundle
+            // and register it against the hub-side `CustomActionRegistry`.
+            // `registerForkedAddonCustomActions` re-`import()`s the entry
+            // (cache-busted), so it covers the hot-load path — where the addon
+            // was registered via `freshLoader` and `this.addonLoader`'s cached
+            // `module` namespace is stale or absent. Dispatch routes through
+            // `broker.call('<addonId>.custom.<action>')`, the only divergence
+            // vs in-process being the transport, exactly like cap methods.
+            await this.registerForkedAddonCustomActions(id, 
+            // `isForkedAddonEntry` narrowed `entry.declaration` to non-null.
+            (0, types_1.resolveRunnerId)(entry.declaration, id));
+            entry.initialized = true;
+            this.logger.info('Addon spawned as isolated process', { tags: { addonId: id } });
+            this.emitAddonLifecycleEvent('addon.started', id);
+            return;
+        }
+        // In-process initialization — capture providers from initialize() return value
+        const context = await this.createAddonContext(entry.addon);
+        const capturedProviders = new Map();
+        // Device-manager needs privileged access to CapabilityRegistry — it
+        // resolves native addon ids for getBindings, lists registered wrappers,
+        // etc. Inject before initialize() runs so the addon's onInitialize can
+        // rely on it.
+        const initResult = (0, types_1.normalizeAddonInitResult)(await entry.addon.initialize(context));
+        // NOTE: `postBrokerStart()` is deliberately NOT called here. It used to
+        // fire right after `initialize()` and would emit readiness events whose
+        // subscribers (remote workers) immediately called `ctx.api.<addon>.*` —
+        // hitting "Service not found" because `broker.createService()` had not
+        // been called yet. See below: postBrokerStart fires after the Moleculer
+        // service mount so the advertised service is live before readiness.
+        for (const reg of initResult?.providers ?? []) {
+            const capName = reg.capability.name;
+            capturedProviders.set(capName, reg.provider);
+            context.registerProvider(capName, reg.provider);
+            // D4: wrapper behaviour is read from the cap DEFINITION. The runtime
+            // ProviderRegistration.kind/defaultActive are deprecated hints — if an
+            // addon still sets them and they disagree, warn (the cap def wins).
+            const kindDrift = (0, kernel_1.describeProviderKindDrift)(capName, reg.capability, {
+                // eslint-disable-next-line @typescript-eslint/no-deprecated -- this IS the drift detector; it reads the deprecated hint on purpose
+                kind: reg.kind,
+                // eslint-disable-next-line @typescript-eslint/no-deprecated -- this IS the drift detector; it reads the deprecated hint on purpose
+                defaultActive: reg.defaultActive,
+            });
+            if (kindDrift) {
+                this.logger.warn(kindDrift, {
+                    tags: { addonId: id },
+                    meta: { capability: capName },
+                });
+            }
+            if (reg.capability.kind === 'wrapper') {
+                this.capabilityRegistry.registerWrapper(capName, id, {
+                    defaultActive: reg.capability.defaultActive === true,
+                });
+            }
+        }
+        // Task 7.1: register system-level custom actions if the addon declares any.
+        if (initResult?.customActions && initResult.actionHandlers) {
+            const handlers = initResult.actionHandlers;
+            try {
+                this.customActionRegistry.registerAddon(id, initResult.customActions, (action, input) => {
+                    const fn = handlers[action];
+                    if (!fn)
+                        throw new Error(`addon '${id}' has no handler for custom action '${action}'`);
+                    return fn(input);
+                });
+            }
+            catch (err) {
+                this.logger.error('Failed to register custom actions for addon', {
+                    tags: { addonId: id },
+                    meta: { error: (0, types_1.errMsg)(err) },
+                });
+                throw err;
+            }
+        }
+        // Validate all declared capabilities have providers registered.
+        // Include caps registered via `context.registerProvider()` side-effects
+        // (e.g. sub-components of an addon calling ctx.registerProvider directly
+        // without returning via ProviderRegistration[]), by reading back from the
+        // CapabilityRegistry for this addonId. This keeps the validation accurate
+        // without forcing addons into a single return-path pattern.
+        if (entry.declaration) {
+            for (const cap of entry.declaration.capabilities ?? []) {
+                const capName = typeof cap === 'string' ? cap : cap.name;
+                if (capturedProviders.has(capName))
+                    continue;
+                const provider = this.capabilityRegistry.getProviderByAddon(capName, id);
+                if (provider)
+                    capturedProviders.set(capName, provider);
+            }
+            (0, kernel_1.validateProviderRegistrations)(id, entry.declaration, capturedProviders, this.logger);
+        }
+        await this.restoreAddonDevices(id, entry.addon);
+        entry.initialized = true;
+        // Register as Moleculer service for remote discoverability
+        if (entry.declaration) {
+            try {
+                // Resolve method names from CapabilityDefinitions registered in the registry
+                const methodResolver = (capName) => {
+                    const def = this.capabilityRegistry.getDefinition(capName);
+                    if (!def?.methods)
+                        return [];
+                    return Object.keys(def.methods);
+                };
+                // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment -- createAddonService return type unresolvable due to upstream eventemitter2/moleculer type chain
+                const schema = (0, kernel_1.createAddonService)(entry.addon, entry.declaration, {
+                    methodResolver,
+                    providers: capturedProviders,
+                });
+                this.broker.createService(schema);
+            }
+            catch (err) {
+                this.logger.warn('Failed to register Moleculer service', {
+                    tags: { addonId: id },
+                    meta: { error: (0, types_1.errMsg)(err) },
+                });
+            }
+        }
+        // Post-broker-start readiness — emitted AFTER the Moleculer service is
+        // mounted so that any remote subscriber reacting to a `ready` event can
+        // immediately call `ctx.api.<addon>.*` without hitting a phantom
+        // service window. Hub addons with `autoEmitReadiness=true` emit here;
+        // addons that manage their own readiness override `autoEmitReadiness`.
+        entry.addon.postBrokerStart();
+        this.logger.info('Addon initialized in-process', {
+            tags: { addonId: id },
+            meta: { packageName: entry.packageName },
+        });
+        this.logAddonLifecycle('started', id, 'in-process');
+        this.emitAddonLifecycleEvent('addon.started', id);
+    }
+    /**
+     * Restore persisted devices for an addon after it has been initialized.
+     * Calls addon.restoreDevices() with the list of devices saved to the DB.
+     * No-op if the addon does not implement restoreDevices() or stores are not available.
+     */
+    async restoreAddonDevices(addonId, addon) {
+        if (typeof addon.restoreDevices !== 'function')
+            return;
+        // Route through the device-persistence capability instead of
+        // accessing DeviceStore/ConfigStore directly. This keeps
+        // AddonRegistryService decoupled from the persistence layer —
+        // the capability addon owns the stores.
+        const api = this.getBrokerApi();
+        try {
+            const listResult = await Reflect.get(Reflect.get(api, 'deviceManager'), 'listPersistedByAddon').query({ addonId });
+            const rows = Array.isArray(listResult)
+                ? listResult
+                : [];
+            if (rows.length === 0)
+                return;
+            const savedDevices = await Promise.all(rows.map(async (row) => {
+                const configResult = await Reflect.get(Reflect.get(api, 'deviceManager'), 'loadConfig').query({ deviceId: row.id });
+                return {
+                    id: row.id,
+                    stableId: row.stableId,
+                    type: row.type,
+                    name: row.name,
+                    location: row.location ?? null,
+                    disabled: row.disabled ?? false,
+                    parentDeviceId: row.parentDeviceId,
+                    config: (configResult ?? {}),
+                };
+            }));
+            await addon.restoreDevices(savedDevices);
+            this.logger.info('Restored devices for addon', {
+                tags: { addonId },
+                meta: { count: savedDevices.length },
+            });
+        }
+        catch (err) {
+            this.logger.error('restoreDevices failed for addon', {
+                tags: { addonId },
+                meta: { error: (0, types_1.errMsg)(err) },
+            });
+        }
+    }
+    /**
+     * Refresh the package version for all addons from a given package.
+     * Call this after an update to ensure the UI shows the new version.
+     */
+    refreshPackageVersion(packageName, newVersion) {
+        for (const [, entry] of this.addonEntries) {
+            if (entry.packageName === packageName) {
+                entry.packageVersion = newVersion;
+                this.logger.info('Updated addon packageVersion', {
+                    tags: { addonId: entry.addon.manifest.id },
+                    meta: { newVersion },
+                });
+            }
+        }
+    }
+    /** Emit addon.uninstalled lifecycle event for all addons belonging to a package */
+    emitUninstallEvent(packageName) {
+        for (const [id, entry] of this.addonEntries) {
+            if (entry.packageName === packageName) {
+                this.emitAddonLifecycleEvent('addon.uninstalled', id);
+            }
+        }
+        // Drop the package from the health monitor so its retry loop
+        // doesn't keep trying to reload an addon the operator explicitly
+        // removed. Matching `clearLoadFailures` purges any pre-init
+        // failures still tracked by the addon-loader.
+        this.healthMonitor.forget(packageName);
+        this.addonLoader.clearLoadFailures(packageName);
+    }
+    /** Emit addon.updated lifecycle event for all addons belonging to a package */
+    emitUpdateEvent(packageName, fromVersion, toVersion) {
+        for (const [id, entry] of this.addonEntries) {
+            if (entry.packageName === packageName) {
+                this.emitAddonLifecycleEvent('addon.updated', id, {
+                    fromVersion,
+                    toVersion,
+                });
+            }
+        }
+    }
+    /**
+     * Restart an addon by ID.
+     * Shuts down, unregisters capabilities, re-initializes, and re-wires.
+     */
+    async restartAddon(addonId) {
+        const entry = this.addonEntries.get(addonId);
+        if (!entry) {
+            return { success: false, error: `Addon "${addonId}" not found` };
+        }
+        this.logger.info('Addon restarting...', { tags: { addonId }, meta: { phase: 'lifecycle' } });
+        // Suppress the "Failed to load" health banner during operator-initiated
+        // restarts. The Moleculer `$node.disconnected` handler skips entries
+        // present in `restartingAddons`; a 90s safety timer clears the flag
+        // even if the restart path throws before the finally block runs.
+        const existingTimer = this.restartingAddons.get(addonId);
+        if (existingTimer)
+            clearTimeout(existingTimer);
+        const safetyTimer = setTimeout(() => {
+            this.restartingAddons.delete(addonId);
+        }, 90_000);
+        this.restartingAddons.set(addonId, safetyTimer);
+        try {
+            // Group-runner-hosted addon — delegate to $process.restart for the group
+            if (this.isForkedAddonEntry(entry)) {
+                const result = (await this.broker.call('$process.restart', {
+                    name: addonId,
+                }));
+                if (!result.success) {
+                    throw new Error(`Process restart failed: ${result.reason ?? 'unknown'}`);
+                }
+                // $process.restart resolves as soon as the child is respawned, not when its
+                // capabilities are re-registered. Callers (integrations.create, UI forms) may
+                // immediately try to route to the provider and hit a transient null. Block here
+                // until every declared capability is back on the registry so the restart is
+                // observable-consistent from the caller's perspective.
+                const declared = entry.declaredCapabilities;
+                if (declared.length > 0) {
+                    // Group-runner restarts pay a multi-step cost: child fork
+                    // (~1s) → addon init (Python pool warmup ~5-10s, or a CLI
+                    // subprocess probe for tailscale-ingress etc.) → capability
+                    // advertisement to hub via Moleculer service discovery
+                    // (~5s on cold start). Any fixed ceiling is wrong — a slow
+                    // restart that DID eventually succeed produces a misleading
+                    // "did not re-register in time" error. Wait indefinitely: if
+                    // the group-runner crashed for real, `$node.disconnected`
+                    // surfaces it through the health monitor; the operator can
+                    // always click Cancel on the UI mutation.
+                    const waits = declared.map((cap) => this.capabilityRegistry.waitForProvider(cap.name, addonId, Number.POSITIVE_INFINITY));
+                    const settled = await Promise.all(waits);
+                    const missing = declared
+                        .map((cap, i) => (settled[i] == null ? cap.name : null))
+                        .filter((name) => name !== null);
+                    if (missing.length > 0) {
+                        throw new Error(`Addon "${addonId}" restarted but did not re-register capabilities in time: ${missing.join(', ')}`);
+                    }
+                }
+                // Re-register the addon's custom-action catalog. `$process.restart`
+                // respawns the group child and `CapabilityBridge` re-registers cap
+                // providers — but custom actions live in the hub-side
+                // `CustomActionRegistry`, which the restart path never touched.
+                // Without this, every hot-update of a group-hosted addon silently
+                // drops its custom actions (the catalog is only registered once,
+                // at boot, in `initializeAddonGroup`). Reads a fresh catalog from
+                // the just-updated on-disk bundle.
+                const runnerId = (0, types_1.resolveRunnerId)(entry.declaration, addonId);
+                await this.registerForkedAddonCustomActions(addonId, runnerId);
+                this.logAddonLifecycle('restarted', addonId, 'isolated');
+                this.emitAddonLifecycleEvent('addon.restarted', addonId);
+                return { success: true };
+            }
+            // D5: a forked addon ALWAYS restarts via `$process.restart` above
+            // (process restart — no in-process hot-reload of a live forked
+            // addon). This branch is reached only by `@camstack/core` builtins
+            // — they have no runner and legitimately reload in-process:
+            // shutdown, unregister, re-initialize, re-wire.
+            if (entry.initialized && entry.addon.shutdown) {
+                await entry.addon.shutdown();
+            }
+            // Drain disposers registered via ctx.addDisposer(...)
+            await this.drainDisposerChain(addonId);
+            // Unregister all capabilities provided by this addon
+            for (const cap of entry.declaredCapabilities) {
+                this.capabilityRegistry.unregisterProvider(cap.name, addonId);
+            }
+            const manifestCaps = this.getAddonCapabilities(entry.addon);
+            for (const cap of manifestCaps) {
+                this.capabilityRegistry.unregisterProvider(cap.name, addonId);
+            }
+            this.capabilityRegistry.unregisterAllWrappersForAddon(addonId);
+            // Task 7.1: drop any registered custom actions so re-initialization re-registers cleanly.
+            this.customActionRegistry.unregisterAddon(addonId);
+            // Destroy existing Moleculer service for this addon
+            try {
+                await this.moleculer.broker.destroyService(addonId);
+            }
+            catch {
+                // Service may not exist if it was never registered
+            }
+            entry.initialized = false;
+            // Re-initialize and re-wire capabilities
+            await this.initializeAddon(addonId);
+            this.wireCapabilities(addonId);
+            this.logAddonLifecycle('restarted', addonId, 'in-process');
+            this.emitAddonLifecycleEvent('addon.restarted', addonId);
+            return { success: true };
+        }
+        catch (err) {
+            const msg = (0, types_1.errMsg)(err);
+            this.logger.error('Failed to restart addon', { tags: { addonId }, meta: { error: msg } });
+            this.emitAddonLifecycleEvent('addon.error', addonId, {
+                error: msg,
+                action: 'restart',
+            });
+            // Record the failure on the health monitor so the addon shows up
+            // `failed` with its `lastError` instead of a stale `healthy`. The
+            // in-process branch already unregistered every capability before
+            // `initializeAddon` threw — without this the addon is invisible-
+            // broken: caps gone, health green, nothing on the Addons page.
+            // The "operator sees the error via the mutation result" assumption
+            // only holds for a UI-clicked restart; a `camstack deploy` or a
+            // `requiresRestart` auto-restart is fire-and-forget — the failure
+            // would otherwise vanish. recordFailure also arms the retry loop.
+            this.healthMonitor.recordFailure(entry.packageName, err, addonId);
+            return { success: false, error: msg };
+        }
+        finally {
+            // Clear the suppression flag regardless of success/failure — if the
+            // restart failed, the operator will see the real error via the
+            // mutation result rather than a misleading transient health blip.
+            const timer = this.restartingAddons.get(addonId);
+            if (timer)
+                clearTimeout(timer);
+            this.restartingAddons.delete(addonId);
+        }
+    }
+    getAddon(id) {
+        const entry = this.addonEntries.get(id);
+        return entry?.addon ?? null;
+    }
+    getAddonEntry(id) {
+        const entry = this.addonEntries.get(id);
+        return entry ? { addon: entry.addon } : null;
+    }
+    /**
+     * Returns the on-disk package directory for the given addon ID.
+     * Used by the /api/addon-assets route to serve static files (e.g. SVG icons).
+     *
+     * Falls back to a disk scan when the addon isn't in `addonEntries`
+     * (typical for failed-to-load packages: dist/manifest still on disk
+     * but the import threw, so the registry never recorded an entry).
+     * Without this fallback the icon endpoint 404s and the operator
+     * sees a broken-image placeholder for any failed addon.
+     */
+    getAddonPackageDir(id) {
+        const entry = this.addonEntries.get(id);
+        if (entry?.addonDir)
+            return entry.addonDir;
+        return this.findAddonDirOnDisk(id);
+    }
+    findAddonDirOnDisk(addonId) {
+        const dataDir = path.resolve(process.env.CAMSTACK_DATA ?? 'camstack-data');
+        const addonsDir = path.resolve(dataDir, 'addons');
+        if (!fs.existsSync(addonsDir))
+            return null;
+        const visit = (pkgDir) => {
+            const pkgJsonPath = path.join(pkgDir, 'package.json');
+            if (!fs.existsSync(pkgJsonPath))
+                return null;
+            try {
+                const pkg = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf-8'));
+                const camstack = pkg['camstack'] ?? {};
+                const addons = Array.isArray(camstack.addons)
+                    ? camstack.addons
+                    : [];
+                if (addons.some((a) => a['id'] === addonId))
+                    return pkgDir;
+            }
+            catch {
+                return null;
+            }
+            return null;
+        };
+        const entries = fs.readdirSync(addonsDir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            const dirName = entry.name;
+            if (dirName === 'node_modules' || dirName.startsWith('.'))
+                continue;
+            const fullPath = path.join(addonsDir, dirName);
+            if (dirName.startsWith('@')) {
+                for (const sub of fs.readdirSync(fullPath, { withFileTypes: true })) {
+                    if (!sub.isDirectory())
+                        continue;
+                    const found = visit(path.join(fullPath, sub.name));
+                    if (found)
+                        return found;
+                }
+            }
+            else {
+                const found = visit(fullPath);
+                if (found)
+                    return found;
+            }
+        }
+        return null;
+    }
+    /**
+     * Resolve an addon's on-disk installation directory and the dist
+     * sub-directory that contains its built entry. For singleton-package
+     * addons the dist sub-directory is `dist/`; for bundled addons (where
+     * one npm package ships multiple addon entries) it's `dist/<entryId>/`.
+     *
+     * Used by the static-file route handler that serves widget bundles
+     * (`/api/addon-widgets/:addonId/*`) — post bundle merge, the addonId →
+     * package-path mapping is no longer 1:1, so callers MUST go through
+     * the registry instead of guessing `addons/@camstack/addon-<id>/dist/`.
+     *
+     * Returns null if the addonId is unknown or the entry's package.json
+     * has no `entry` field. The returned `distDir` is an absolute path.
+     */
+    getAddonInstallPath(addonId) {
+        const entry = this.addonEntries.get(addonId);
+        if (!entry?.addonDir || !entry.declaration?.entry)
+            return null;
+        const distSubdir = path.dirname(entry.declaration.entry);
+        return {
+            addonDir: entry.addonDir,
+            distDir: path.resolve(entry.addonDir, distSubdir),
+        };
+    }
+    /**
+     * Build an AddonContext for a given addon — same as what initialize() receives.
+     * Used by the benchmark system to create fresh addon instances with custom config.
+     */
+    async buildAddonContext(addonId) {
+        const entry = this.addonEntries.get(addonId);
+        if (!entry)
+            return null;
+        return this.createAddonContext(entry.addon);
+    }
+    /**
+     * True when the entry's manifest opted into protection (uninstall
+     * disabled). The flag is per-addon (`camstack.addons[N].protected`)
+     * but the kernel uninstall API operates on packages — so a package
+     * is treated as protected if ANY of its addons declares the flag.
+     * Computed at call time from the running registry; no hardcoded
+     * package list to keep in sync.
+     */
+    isPackageProtected(packageName) {
+        for (const entry of this.addonEntries.values()) {
+            if (entry.packageName !== packageName)
+                continue;
+            if (entry.declaration?.protected === true)
+                return true;
+        }
+        return false;
+    }
+    /**
+     * True when the entry boots in its own forked runner. This MUST mirror
+     * the fork authority `buildAddonGroupPlan`, which spawns a runner for
+     * every addon that ships an on-disk `addonDir` + a manifest
+     * `declaration`, is NOT a `@camstack/core` builtin, and is NOT
+     * `agent-only`. The `execution` block is OPTIONAL — an addon with no
+     * `execution` declaration still forks on its own dedicated runner
+     * (`resolveRunnerId` falls back to the addon id). Requiring `execution`
+     * here previously diverged from `buildAddonGroupPlan`: an addon like
+     * `auth-oidc` (no `execution` block) was forked at boot yet classified
+     * in-process by this predicate, so its route-mount took the co-located
+     * path and received the async UDS cap proxy whose `getRoutes()` returns
+     * a Promise (→ `getRoutes(...).map is not a function`). Only
+     * `@camstack/core` builtins boot in-process on the hub. The type
+     * predicate narrows both `addonDir` and `declaration` for callers.
+     */
+    isForkedAddonEntry(entry) {
+        return !!(entry.declaration &&
+            entry.addonDir &&
+            entry.packageName !== '@camstack/core' &&
+            (0, types_1.resolveAddonPlacement)(entry.declaration) !== 'agent-only');
+    }
+    /** Per-entry helper used by `listAddons()` to mark a row removable / not. */
+    isRequiredEntry(entry) {
+        if (entry.declaration?.protected === true)
+            return true;
+        // Fall back to a sibling addon in the same package — the
+        // protected-by-association rule above. Catches the case where the
+        // SAME package ships an aggregator addon (protected: true) plus
+        // a source addon (protected: false): both rows should render
+        // as non-removable because uninstalling the package would tear
+        // out both.
+        return this.isPackageProtected(entry.packageName);
+    }
+    listAddons() {
+        // Build process info map from in-memory data (sync, no stats)
+        const processMap = new Map();
+        for (const [id, entry] of this.addonEntries) {
+            if (entry.initialized) {
+                processMap.set(`addon:${id}`, {
+                    pid: process.pid,
+                    mode: 'in-process',
+                    state: 'running',
+                });
+            }
+        }
+        const live = Array.from(this.addonEntries.values())
+            .filter((entry) => entry.addon?.manifest?.id)
+            .map((entry) => {
+            let installSource;
+            if (entry.addonDir) {
+                try {
+                    const markerPath = path.join(entry.addonDir, '.install-source');
+                    if (fs.existsSync(markerPath)) {
+                        const raw = fs.readFileSync(markerPath, 'utf-8').trim();
+                        // Normalize legacy 'workspace' → 'local'
+                        const normalized = raw === 'workspace' ? 'local' : raw;
+                        if (normalized === 'npm' || normalized === 'local' || normalized === 'upload') {
+                            installSource = normalized;
+                        }
+                    }
+                }
+                catch (err) {
+                    this.logger.debug('Failed to read install-source marker for addon', {
+                        meta: { error: (0, types_1.errMsg)(err) },
+                    });
+                }
+            }
+            return {
+                manifest: {
+                    // Overlay the fresh on-disk declaration (refreshed by
+                    // `loadNewAddons` on every `camstack deploy`) onto the live
+                    // instance manifest, so a redeployed addon's new capabilities /
+                    // brokerKind surface here without a full backend restart. See
+                    // `overlayDeclaration` — this is what keeps Home Assistant
+                    // (post broker rework: broker + device-adoption) visible in the
+                    // "+ New Integration" picker.
+                    ...(0, addon_row_manifest_1.overlayDeclaration)(entry.addon.manifest, entry.declaration),
+                    packageName: entry.packageName,
+                    packageVersion: entry.packageVersion,
+                    packageDisplayName: entry.packageDisplayName,
+                    ...(entry.bundle !== undefined ? { bundle: entry.bundle } : {}),
+                    protected: this.isRequiredEntry(entry) || undefined,
+                    removable: this.isRequiredEntry(entry) ? false : undefined,
+                },
+                declaration: entry.declaration,
+                source: entry.source,
+                installSource,
+                process: processMap.get(`addon:${entry.addon.manifest.id}`),
+            };
+        });
+        // Surface packages that exist on disk but failed to load — typical
+        // causes are dep-version mismatch, missing native binary, or a
+        // corrupted dist. Without this, an operator sees "installed" via
+        // the package manifest but can't find the row in the addons UI to
+        // diagnose or uninstall, leaving the package stranded.
+        const seenPackages = new Set(live.map((row) => row.manifest.packageName));
+        const failed = this.scanFailedToLoadPackages(seenPackages);
+        return [...live, ...failed];
+    }
+    /**
+     * Walk `<dataDir>/addons/` for `package.json` files whose declared
+     * `camstack.addons[]` entries don't appear in `addonEntries`. Returns
+     * synthetic listing rows so the UI can show + delete them. The rows
+     * carry a `process.state: 'failed'` flag so the AddonCard can render
+     * the diagnostic state distinctly from a normal addon.
+     */
+    scanFailedToLoadPackages(seenPackages) {
+        const dataDir = path.resolve(process.env.CAMSTACK_DATA ?? 'camstack-data');
+        const addonsDir = path.resolve(dataDir, 'addons');
+        if (!fs.existsSync(addonsDir))
+            return [];
+        const out = [];
+        const visit = (pkgDir) => {
+            const pkgJsonPath = path.join(pkgDir, 'package.json');
+            if (!fs.existsSync(pkgJsonPath))
+                return;
+            let pkg;
+            try {
+                pkg = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf-8'));
+            }
+            catch {
+                return;
+            }
+            const packageName = typeof pkg['name'] === 'string' ? pkg['name'] : '';
+            const packageVersion = typeof pkg['version'] === 'string' ? pkg['version'] : '0.0.0';
+            if (!packageName || seenPackages.has(packageName))
+                return;
+            const camstack = pkg['camstack'] ?? {};
+            const addons = Array.isArray(camstack.addons)
+                ? camstack.addons
+                : [];
+            if (addons.length === 0)
+                return;
+            let installSource;
+            try {
+                const markerPath = path.join(pkgDir, '.install-source');
+                if (fs.existsSync(markerPath)) {
+                    const raw = fs.readFileSync(markerPath, 'utf-8').trim();
+                    const normalized = raw === 'workspace' ? 'local' : raw;
+                    if (normalized === 'npm' || normalized === 'local' || normalized === 'upload') {
+                        installSource = normalized;
+                    }
+                }
+            }
+            catch {
+                /* non-critical */
+            }
+            // Manifest-driven protection — agree with the live-rows path.
+            const isProtected = addons.some((a) => a['protected'] === true);
+            const packageDisplayName = camstack.displayName;
+            // Bundle metadata — present when the package ships multiple addon
+            // entries that should render as collapsible children in the UI.
+            const bundleRaw = camstack.bundle;
+            const bundle = bundleRaw && typeof bundleRaw.displayName === 'string'
+                ? {
+                    displayName: bundleRaw.displayName,
+                    ...(bundleRaw.description !== undefined
+                        ? { description: bundleRaw.description }
+                        : {}),
+                    ...(bundleRaw.icon !== undefined ? { icon: bundleRaw.icon } : {}),
+                }
+                : undefined;
+            for (const decl of addons) {
+                const id = typeof decl['id'] === 'string' ? decl['id'] : '';
+                const name = typeof decl['name'] === 'string' ? decl['name'] : id;
+                if (!id)
+                    continue;
+                const manifest = {
+                    ...decl,
+                    id,
+                    name,
+                    packageName,
+                    packageVersion,
+                    ...(packageDisplayName ? { packageDisplayName } : {}),
+                    ...(bundle !== undefined ? { bundle } : {}),
+                    protected: isProtected || undefined,
+                    removable: !isProtected,
+                };
+                out.push({
+                    manifest,
+                    declaration: decl,
+                    source: 'installed',
+                    ...(installSource ? { installSource } : {}),
+                    process: { mode: 'in-process', state: 'failed' },
+                });
+            }
+        };
+        const entries = fs.readdirSync(addonsDir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            const dirName = entry.name;
+            if (dirName === 'node_modules' || dirName.startsWith('.'))
+                continue;
+            const fullPath = path.join(addonsDir, dirName);
+            // Scoped: walk one level deeper.
+            if (dirName.startsWith('@')) {
+                const scopedEntries = fs.readdirSync(fullPath, { withFileTypes: true });
+                for (const sub of scopedEntries) {
+                    if (sub.isDirectory())
+                        visit(path.join(fullPath, sub.name));
+                }
+            }
+            else {
+                visit(fullPath);
+            }
+        }
+        return out;
+    }
+    /**
+     * List all addons including core builtins.
+     * Each addon carries packageName/packageVersion from its package.json,
+     * so the frontend can group by package automatically.
+     */
+    listAllAddons() {
+        return this.listAddons();
+    }
+    /**
+     * List all addon processes (in-process addons)
+     * as ManagedProcessStatus-compatible entries for the process tree.
+     */
+    async listAddonProcesses() {
+        const result = [];
+        // Collect hub PID and fetch stats
+        const { getPidStats } = await Promise.resolve().then(() => __importStar(require('@camstack/core')));
+        const pidStats = await getPidStats([process.pid]);
+        // In-process addons
+        const hubStats = pidStats.get(process.pid);
+        for (const [id, entry] of this.addonEntries) {
+            if (entry.initialized) {
+                result.push({
+                    id: `addon:${id}`,
+                    label: `Addon: ${id} (in-process)`,
+                    state: 'running',
+                    pid: process.pid,
+                    stats: {
+                        pid: process.pid,
+                        cpu: hubStats?.cpu ?? 0,
+                        memory: hubStats?.memory ?? 0,
+                        uptime: Math.round(process.uptime()),
+                        restartCount: 0,
+                    },
+                    restartCount: 0,
+                    mode: 'in-process',
+                });
+            }
+        }
+        return result;
+    }
+    /**
+     * Phase 11 (settings redesign): `getAddonConfigSchema`,
+     * `getAddonConfig`, and `updateAddonConfig` — the legacy adapter
+     * shim that synthesised a plain `ConfigUISchema` view from the new
+     * three-level methods — are gone. All settings traffic goes through
+     * the six Phase 5 tRPC endpoints (`addons.getAddonSettings`,
+     * `updateAddonSettings`, `getGlobalSettings`, `updateGlobalSettings`,
+     * `getDeviceSettings`, `updateDeviceSettings`) which call the
+     * addon's methods directly via the `addon-settings` singleton capability.
+     */
+    /**
+     * Scan data/addons/ for new packages and initialize any addon not already registered.
+     * Called after install/uninstall to hot-load new addons without server restart.
+     */
+    async loadNewAddons() {
+        const dataDir = path.resolve(process.env.CAMSTACK_DATA ?? 'camstack-data');
+        const addonsDir = path.resolve(dataDir, 'addons');
+        // Create a fresh loader to discover what's on disk (for diffing against existing)
+        const freshLoader = new kernel_1.AddonLoader(this.loggingService.createLogger('AddonLoader'));
+        await freshLoader.loadFromDirectory(addonsDir);
+        const loaded = [];
+        const failed = [];
+        for (const registered of freshLoader.listAddons()) {
+            // Already-registered addon: refresh the in-memory metadata (the
+            // `packageVersion`/`packageDisplayName`/`declaration`/`bundle`
+            // fields stored on the entry) from the fresh disk scan. Without
+            // this step a hot-update via `installFromTgz` would leave
+            // `entry.packageVersion` stale — the forked group-runner picks up
+            // the new code on `restartAddon` but the UI + listAddons() keep
+            // showing the OLD version. We deliberately keep `entry.addon`
+            // (the running instance) and `entry.initialized` untouched so
+            // `restartAddon` still shuts the live instance down cleanly.
+            const existing = this.addonEntries.get(registered.declaration.id);
+            if (existing) {
+                existing.packageVersion = registered.packageVersion;
+                existing.packageName = registered.packageName;
+                existing.packageDisplayName = registered.packageDisplayName;
+                if (registered.bundle !== undefined) {
+                    existing.bundle = registered.bundle;
+                }
+                existing.declaration = registered.declaration;
+                existing.declaredCapabilities = (registered.declaration.capabilities ?? []).map((c) => typeof c === 'string' ? { name: c, mode: 'singleton' } : c);
+                continue;
+            }
+            // Skip agent-only addons on the hub. Same rule as the boot loader
+            // path above; without it, post-install reload would re-init
+            // hub-side every agent-only provider (e.g. `hub-forwarder`),
+            // and a hub-resident `hub-forwarder` creates a write→ingest→
+            // write feedback loop because the hub IS the log-receiver.
+            if ((0, types_1.isAgentOnlyPlacement)(registered.declaration)) {
+                this.logger.debug('loadNewAddons: skipping agent-only addon on hub', {
+                    tags: { addonId: registered.declaration.id },
+                });
+                continue;
+            }
+            if (registered.declaration.capabilities) {
+                for (const cap of registered.declaration.capabilities) {
+                    this.capabilityRegistry.declareFromManifest(cap, registered.declaration.id);
+                }
+            }
+            try {
+                const addon = freshLoader.createInstance(registered.declaration.id);
+                const declCaps = (registered.declaration.capabilities ?? []).map((c) => typeof c === 'string' ? { name: c, mode: 'singleton' } : c);
+                this.addonEntries.set(registered.declaration.id, {
+                    addon,
+                    initialized: false,
+                    source: 'installed',
+                    packageName: registered.packageName,
+                    packageVersion: registered.packageVersion,
+                    packageDisplayName: registered.packageDisplayName,
+                    ...(registered.bundle !== undefined ? { bundle: registered.bundle } : {}),
+                    declaredCapabilities: declCaps,
+                    addonDir: path.join(addonsDir, registered.packageName),
+                    declaration: registered.declaration,
+                });
+                // Initialize the new addon
+                await this.initializeAddon(registered.declaration.id);
+                this.wireCapabilities(registered.declaration.id);
+                loaded.push(registered.declaration.id);
+                this.logger.info('Hot-loaded addon', {
+                    tags: { addonId: registered.declaration.id },
+                    meta: { packageName: registered.packageName },
+                });
+                this.emitAddonLifecycleEvent('addon.installed', registered.declaration.id);
+            }
+            catch (err) {
+                const msg = (0, types_1.errMsg)(err);
+                const stack = err instanceof Error ? err.stack : undefined;
+                this.logger.error('Failed to hot-load addon', {
+                    tags: { addonId: registered.declaration.id },
+                    meta: stack ? { error: msg, stack } : { error: msg },
+                });
+                this.emitAddonLifecycleEvent('addon.crashed', registered.declaration.id, { error: msg });
+                failed.push(registered.declaration.id);
+            }
+        }
+        // Remove addons that are no longer on disk — the uninstall path.
+        // D5: every non-core addon lives in its own runner subprocess. The
+        // uninstall consolidation is "stop the runner"; the runner exits and
+        // re-handshakes the hub WITHOUT the removed addon (D3 machinery).
+        // Only `@camstack/core` builtins — which have no runner — take the
+        // in-process `shutdown()` + disposer-drain path.
+        const onDiskIds = new Set(freshLoader.listAddons().map((a) => a.declaration.id));
+        for (const [id, entry] of this.addonEntries) {
+            if (entry.source === 'installed' && !onDiskIds.has(id)) {
+                // Unregister capabilities before stopping the addon.
+                for (const cap of entry.declaredCapabilities) {
+                    this.capabilityRegistry.unregisterProvider(cap.name, id);
+                }
+                const manifestCaps = this.getAddonCapabilities(entry.addon);
+                for (const cap of manifestCaps) {
+                    this.capabilityRegistry.unregisterProvider(cap.name, id);
+                }
+                this.capabilityRegistry.unregisterAllWrappersForAddon(id);
+                // Task 7.1: drop custom actions for removed addons.
+                this.customActionRegistry.unregisterAddon(id);
+                if (this.isForkedAddonEntry(entry) && entry.initialized) {
+                    // Forked addon — stop the runner subprocess. `$process.stop`
+                    // kills the child and force-evicts its Moleculer node, so the
+                    // hub's cap registry drops the gone provider with no per-
+                    // operation hub bookkeeping.
+                    try {
+                        await this.broker.call('$process.stop', { name: id });
+                    }
+                    catch (err) {
+                        this.logger.warn('Non-fatal: failed to stop runner for removed addon', {
+                            tags: { addonId: id },
+                            meta: { error: (0, types_1.errMsg)(err) },
+                        });
+                    }
+                }
+                else if (entry.initialized) {
+                    // `@camstack/core` builtin — reload model is in-process.
+                    try {
+                        await entry.addon.shutdown();
+                    }
+                    catch (err) {
+                        this.logger.debug('Non-fatal: shutdown error for removed addon', {
+                            tags: { addonId: id },
+                            meta: { error: (0, types_1.errMsg)(err) },
+                        });
+                    }
+                    await this.drainDisposerChain(id);
+                }
+                this.addonEntries.delete(id);
+                this.logger.info('Removed addon (no longer on disk)', { tags: { addonId: id } });
+            }
+        }
+        return { loaded, failed };
+    }
+    async shutdownAll() {
+        for (const [id, entry] of this.addonEntries) {
+            if (entry.initialized) {
+                const capabilities = this.getAddonCapabilities(entry.addon);
+                for (const cap of capabilities) {
+                    this.capabilityRegistry.unregisterProvider(cap.name, id);
+                }
+                this.capabilityRegistry.unregisterAllWrappersForAddon(id);
+                // Task 7.1: drop custom actions on full shutdown.
+                this.customActionRegistry.unregisterAddon(id);
+                await entry.addon.shutdown();
+                await this.drainDisposerChain(id);
+                entry.initialized = false;
+            }
+        }
+    }
+    // --- Private helpers ---
+    // registerConsumers() — DELETED. Consumer wiring now in wireCapabilityConsumers().
+    /**
+     * v2: wire capability consumer actions via EventBus.
+     * Listens to 'capability:provider-registered' events from CapabilityRegistry
+     * and dispatches setup actions (storage wiring, decoder↔broker, etc).
+     *
+     * Replaces the 11 registerConsumer callbacks from v1.
+     */
+    wireCapabilityConsumers() {
+        if (!this.capabilityRegistry)
+            return;
+        this.eventBusService.subscribe({ category: 'capability:provider-registered' }, (event) => {
+            const rawCapability = event.data['capability'];
+            const rawAddonId = event.data['addonId'];
+            if (typeof rawCapability !== 'string' || typeof rawAddonId !== 'string')
+                return;
+            const capability = rawCapability;
+            const addonId = rawAddonId;
+            // Broadcast readiness on the hub-node scope so subprocess
+            // brokers waiting on this cap (e.g. provider-rtsp's
+            // `system.ready-state` listener for stream-broker, or
+            // `runWorkerDeviceRestoreWithRetry` waiting on
+            // device-manager) wake up. We emit ONLY `{ type: 'node',
+            // nodeId: 'hub' }` — most consumer filters are scope-agnostic
+            // (they match on capName + state), so emitting both `node` and
+            // `global` causes duplicate fan-out (e.g. provider-rtsp's
+            // `republishAll` running twice → repeated `dispatchCamera`
+            // loops). The node-scoped emit is sufficient: the hydrate
+            // path on subprocess brokers replays whichever records the
+            // hub's `$readiness.getSnapshot` returns, scope and all.
+            try {
+                this.moleculer.readinessRegistry.emitReady(capability, { type: 'node', nodeId: 'hub' });
+            }
+            catch (err) {
+                this.logger.warn('emitReady failed', {
+                    meta: { capability, addonId, error: (0, types_1.errMsg)(err) },
+                });
+            }
+            switch (capability) {
+                case 'storage': {
+                    // Storage-unification refactor (Task 8) — the consumer-
+                    // facing `storage` cap is now a singleton owned by the
+                    // `storage-orchestrator` builtin, exposing the codegen'd
+                    // async `IStorageCapProvider` surface. The legacy
+                    // synchronous `INewStorageProvider` (filesystem-only) used
+                    // by `StorageService.setNewStorageProvider` and the
+                    // `addons-data` dataDir resolution at boot is no longer
+                    // wired here — filesystem-storage now registers under
+                    // `storage-provider` (the upstream collection cap), and
+                    // legacy callers fall back to the deterministic
+                    // `camstack-data/addons-data/<addonId>` path. Task 17 will
+                    // migrate those callers off `INewStorageProvider`
+                    // entirely.
+                    break;
+                }
+                case 'settings-store': {
+                    const provider = this.capabilityRegistry.getProviderByAddon('settings-store', addonId);
+                    if (!provider)
+                        return;
+                    this.activeSettingsBackend = provider;
+                    if (isSettingsStore(provider)) {
+                        this.configService.setSettingsStore(provider);
+                    }
+                    this.storageService.setSettingsBackend(provider);
+                    this.integrationRegistry = new core_1.IntegrationRegistry(provider);
+                    void this.integrationRegistry.initialize().then(() => {
+                        this.logger.info('IntegrationRegistry initialized', { meta: { phase: 'v2' } });
+                    });
+                    this.loadCollectionPreferences();
+                    // DeviceStore/ConfigStore are owned by the `device-persistence`
+                    // capability addon — no longer created here. The addon boots
+                    // after `sqlite-settings` and extracts the DB handle via the
+                    // capability registry.
+                    this.logger.info('Settings backend wired', { meta: { phase: 'v2' } });
+                    break;
+                }
+                case 'log-destination': {
+                    const provider = this.capabilityRegistry.getProviderByAddon('log-destination', addonId);
+                    if (!provider)
+                        return;
+                    this.loggingService.addDestination(provider);
+                    this.logger.info('Log destination added', { meta: { phase: 'v2' } });
+                    break;
+                }
+                case 'restreamer':
+                case 'webrtc':
+                case 'decoder':
+                case 'stream-broker':
+                    // No wiring needed — consumers read from capabilityRegistry on demand.
+                    break;
+                case 'addon-routes': {
+                    // Route mounting is async for forked/group addons — the
+                    // provider is a Moleculer proxy whose `getRoutes()` returns
+                    // a Promise (the wire round-trips through the worker). The
+                    // EventBus subscriber callback is synchronous, so delegate
+                    // to an async helper and surface any failure via the
+                    // logger instead of letting a rejected promise (or a
+                    // `liveRoutes.some is not a function` TypeError) escape the
+                    // subscriber unobserved.
+                    void this.mountAddonRoutes(addonId).catch((err) => {
+                        this.logger.error('Failed to mount addon routes', {
+                            meta: { phase: 'v2', addonId, error: (0, types_1.errMsg)(err) },
+                        });
+                    });
+                    break;
+                }
+                default:
+                    break;
+            }
+            // HTTP data-planes aren't capabilities, so no `case` fires for them —
+            // pull them off ANY cap-changed signal for this (forked) addon. Cheap +
+            // idempotent (replace-all), and re-pulls the fresh baseUrl/secret after a
+            // restart (the child re-handshakes → caps re-register → this re-fires).
+            void this.mountAddonDataPlanes(addonId).catch((err) => {
+                this.logger.error('Failed to mount addon data-planes', {
+                    meta: { phase: 'v2', addonId, error: (0, types_1.errMsg)(err) },
+                });
+            });
+        });
+    }
+    /**
+     * Mount the `addon-routes` provider for `addonId` into the
+     * `AddonRouteRegistry`. Handles both co-located (in-process) and
+     * forked addons:
+     *
+     * - For a hub-local FORKED addon the route handlers live in the
+     *   child process and cannot cross the UDS wire (MsgPack can't encode
+     *   a function). We fetch the handler-stripped route descriptors over
+     *   UDS via `LocalChildRegistry.callAddonOnChild(addonId,
+     *   {target:'routes'})` (F3 — replaces the removed per-addon Moleculer
+     *   `getRoutes` action), synthesize bridge handlers that dispatch
+     *   through the `addon-routes` cap's `invoke(...)` method (a normal
+     *   serializable cap call over UDS), and translate the captured
+     *   envelope back onto the Fastify reply.
+     * - For a co-located (hub-resident) addon `getRoutes()` resolves to the
+     *   live route list with real handlers, so we register the provider
+     *   directly.
+     */
+    async mountAddonRoutes(addonId) {
+        if (!this.capabilityRegistry || !this.addonRouteRegistry)
+            return;
+        const addonRouteRegistry = this.addonRouteRegistry;
+        const routeProvider = this.capabilityRegistry.getProviderByAddon('addon-routes', addonId);
+        if (!routeProvider)
+            return;
+        // ── Forked addon: fetch handler-stripped routes over UDS (F3) ──────
+        // EVERY non-`@camstack/core` addon forks (the fork authority is
+        // `buildAddonGroupPlan`, which does NOT require an `execution` block — an
+        // addon like `auth-oidc` with no `execution` still runs in its own
+        // runner). `isForkedAddonEntry` now mirrors that rule. For a forked addon
+        // the `getProviderByAddon('addon-routes', …)` result is the async UDS cap
+        // proxy whose `getRoutes()` returns a Promise — registering it directly
+        // would crash `AddonRouteRegistry.registerRoutes` (`getRoutes(...).map is
+        // not a function`), and dispatching the proxy's `getRoutes` cap method
+        // over UDS would try to MsgPack-serialize the child's live handler
+        // functions (→ "Unrecognized object: [object AsyncFunction]"). Instead we
+        // fetch handler-STRIPPED descriptors via `callAddonOnChild(target:
+        // 'routes')` and bridge each through the `invoke` cap method. The UDS
+        // childId for a hub-local single-addon runner equals the addonId
+        // (`resolveRunnerId` — no shipped addon declares a group). Gate on
+        // `isChildKnown` (the child completed its UDS handshake) rather than
+        // `childProvides('addon-routes')`: the `addon-call` route fetch works as
+        // long as the child is connected, and the child is added to the UDS
+        // registry BEFORE its manifest fires the cap-changed event that triggers
+        // this mount, so the gate is satisfied on the happy path.
+        const entry = this.addonEntries.get(addonId);
+        const childRegistry = this.moleculer.childRegistry;
+        if (entry && this.isForkedAddonEntry(entry)) {
+            if (childRegistry !== null && childRegistry.isChildKnown(addonId)) {
+                await this.mountForkedAddonRoutes(addonId, routeProvider, addonRouteRegistry);
+                return;
+            }
+            // Child not yet connected over UDS: defer rather than register the async
+            // proxy directly (which would crash on `.map`). The `addon-routes`
+            // cap-changed event re-fires once the child finishes its handshake.
+            this.logger.warn('Deferring forked addon route mount — child not yet UDS-reachable', {
+                meta: { phase: 'v2', addonId },
+            });
+            return;
+        }
+        // ── Co-located addon (`@camstack/core` builtin): live handlers, register
+        // the provider directly. The route handlers run in-process against the
+        // real Fastify reply, so no wire bridge is needed.
+        addonRouteRegistry.registerRoutes(routeProvider.id, routeProvider);
+        this.logger.info('Addon routes mounted', {
+            meta: { phase: 'v2', routeProviderId: routeProvider.id },
+        });
+    }
+    /**
+     * Mount a hub-local FORKED addon's HTTP routes (F3). The route handlers live
+     * in the child process; only handler-stripped descriptors cross the UDS wire.
+     * We:
+     *   1. fetch the descriptors via `callAddonOnChild(addonId, {target:'routes'})`,
+     *   2. synthesize a bridge handler per route that dispatches the captured
+     *      request through the `addon-routes` cap's `invoke(...)` method (a normal
+     *      serializable UDS cap call on `routeProvider`), and
+     *   3. translate the returned reply envelope back onto the Fastify reply.
+     *
+     * `addonRouteRegistry` is narrowed non-null by the caller's guard in
+     * `mountAddonRoutes` — no assertion needed here.
+     */
+    async mountForkedAddonRoutes(addonId, routeProvider, addonRouteRegistry) {
+        // The cap-registry typed surface for `addon-routes` is the operator-facing
+        // `IAddonRouteProvider` (id + getRoutes). The bridge dispatch contract
+        // `invoke(...)` is present on the UDS proxy but not on that interface —
+        // narrow it via a structural type guard (no cast).
+        if (!isAddonRoutesInvoker(routeProvider)) {
+            this.logger.warn('Forked addon-routes provider missing `invoke` method — routes will not dispatch. Use `buildAddonRouteProvider()` from @camstack/types.', { meta: { phase: 'v2', routeProviderId: routeProvider.id } });
+            return;
+        }
+        const invoker = routeProvider;
+        const rawRoutes = await this.addonCallGateway.callForked(addonId, {
+            target: 'routes',
+        });
+        const descriptors = parseSerializableRouteDescriptors(rawRoutes);
+        const bridgeRoutes = descriptors.map((route) => ({
+            method: route.method,
+            path: route.path,
+            access: route.access,
+            ...(route.description !== undefined ? { description: route.description } : {}),
+            handler: async (req, reply) => {
+                const envelope = await invoker.invoke({
+                    method: route.method,
+                    path: route.path,
+                    params: req.params,
+                    query: req.query,
+                    body: req.body,
+                    headers: req.headers,
+                    ...(req.user ? { user: req.user } : {}),
+                    ...(req.scopedToken !== undefined ? { scopedToken: req.scopedToken } : {}),
+                });
+                reply.code(envelope.status);
+                if (envelope.contentType)
+                    reply.type(envelope.contentType);
+                for (const [k, v] of Object.entries(envelope.headers))
+                    reply.header(k, v);
+                if (envelope.redirectUrl !== null) {
+                    reply.header('Location', envelope.redirectUrl);
+                    reply.send('');
+                }
+                else {
+                    reply.send(envelope.body);
+                }
+            },
+        }));
+        addonRouteRegistry.registerRoutes(routeProvider.id, {
+            id: routeProvider.id,
+            getRoutes: () => bridgeRoutes,
+        });
+        this.logger.info('Addon routes mounted (forked-bridge over UDS)', {
+            meta: { phase: 'v2', routeProviderId: routeProvider.id, routes: bridgeRoutes.length },
+        });
+    }
+    // Cleanup: `addonHasConfigFields` deleted. It was the last reader of
+    // the legacy `ICamstackAddon.getConfigSchema()` method, exposed via
+    // `listAddons().hasConfigSchema` for the old AddonCard settings gate.
+    // `NodeAddonsSettingsPanel` now gracefully shows an empty state when
+    // an addon doesn't implement `getGlobalSettings`, so the backend no
+    // longer needs to pre-compute this flag.
+    emitAddonLifecycleEvent(eventType, addonId, data) {
+        const entry = this.addonEntries.get(addonId);
+        this.eventBusService.emit({
+            id: (0, node_crypto_1.randomUUID)(),
+            timestamp: new Date(),
+            source: {
+                type: 'addon',
+                id: addonId,
+                nodeId: this.broker.nodeID,
+            },
+            category: eventType,
+            data: {
+                addonId,
+                packageName: entry?.packageName,
+                packageVersion: entry?.packageVersion,
+                agent: process.env.CAMSTACK_AGENT_NAME ?? 'hub',
+                ...data,
+            },
+        });
+    }
+    /**
+     * Post-init hook: emit events for newly available capabilities.
+     * Provider registration now happens in initialize() via context.registerProvider().
+     */
+    wireCapabilities(addonId) {
+        const entry = this.addonEntries.get(addonId);
+        if (!entry?.initialized)
+            return;
+        // Emit addon-pages event for UI notification. Cap name is
+        // `addon-pages-source` after the consolidation split — collection
+        // providers register on the source cap; the singleton aggregator
+        // owns `addon-pages` cluster-wide.
+        const declaredCaps = entry.declaredCapabilities.map((c) => c.name);
+        if (declaredCaps.includes('addon-pages-source')) {
+            this.eventBusService.emit({
+                id: (0, node_crypto_1.randomUUID)(),
+                timestamp: new Date(),
+                source: { type: 'addon', id: addonId },
+                category: types_1.EventCategory.AddonPageReady,
+                data: { addonId, packageName: entry.packageName },
+            });
+        }
+        // Symmetric for `addon-widgets-source` — addons that contribute
+        // widget bundles emit `AddonWidgetReady` so the
+        // <WidgetRegistryProvider> in admin-ui invalidates its aggregator
+        // query and the new bundle becomes available without a page
+        // reload.
+        if (declaredCaps.includes('addon-widgets-source')) {
+            this.eventBusService.emit({
+                id: (0, node_crypto_1.randomUUID)(),
+                timestamp: new Date(),
+                source: { type: 'addon', id: addonId },
+                category: types_1.EventCategory.AddonWidgetReady,
+                data: { addonId, packageName: entry.packageName },
+            });
+        }
+    }
+    getAddonCapabilities(addon) {
+        const caps = addon?.manifest?.capabilities;
+        if (!caps)
+            return [];
+        return caps.map((cap) => (typeof cap === 'string' ? { name: cap } : cap));
+    }
+    findAddonForCapability(capName, addonIds) {
+        for (const id of addonIds) {
+            const entry = this.addonEntries.get(id);
+            if (!entry)
+                continue;
+            // Use declaredCapabilities (from package.json) as source of truth
+            if (entry.declaredCapabilities.some((c) => c.name === capName))
+                return id;
+        }
+        return null;
+    }
+    /**
+     * Build the addonConfig for a given addon — strictly per-addon now.
+     *
+     * The legacy cross-addon merge (hardcoded `ADDON_SYSTEM_SETTINGS` map
+     * copying `system_settings.<section>.*` into the bootstrap config) has
+     * been removed. Addons that need to read shared system settings
+     * sections (`ffmpeg`, `logging`, `recording`, …) do so at runtime via
+     * `ctx.settings.getGlobal({ section: '<name>' })`, which delegates to
+     * `ConfigManager.getSection()` and covers the full SQL → YAML →
+     * RUNTIME_DEFAULTS fallback chain.
+     *
+     * This keeps the kernel agnostic: every addon declares its own needs
+     * in its own `initialize(ctx)` code, with zero kernel-side addon id
+     * special-casing. The only remaining exception is `sqlite-settings`,
+     * which receives `_runtimeDefaults` for first-boot seeding (tracked
+     * separately under the kernel-cleanup roadmap — Point 3d).
+     */
+    buildAddonConfig(addonId) {
+        // Start with per-addon SQL settings (may be empty for most addons)
+        let addonSpecific = {};
+        try {
+            addonSpecific = this.configService.getAddonConfig(addonId);
+        }
+        catch (err) {
+            this.logger.debug('ConfigManager not ready for addon', {
+                tags: { addonId },
+                meta: { error: (0, types_1.errMsg)(err) },
+            });
+        }
+        // No addon id special-casing here anymore. Bootstrap-level
+        // concerns (e.g. first-boot seeding from RUNTIME_DEFAULTS) are
+        // owned by the addon itself — sqlite-settings imports the
+        // constant directly from `@camstack/types` instead of relying on
+        // a kernel-injected bootstrap field.
+        return addonSpecific;
+    }
+    async createAddonContext(addon) {
+        const addonId = addon.manifest.id;
+        const brokerNodeId = this.broker.nodeID;
+        const agentId = brokerNodeId.includes('/') ? brokerNodeId.split('/')[0] : brokerNodeId;
+        // No scope on the addon root logger — the brand bracket already shows
+        // `[agent/addonId]`, so `(addon:<addonId>)` was pure duplication.
+        // Sub-components add their own scope via `.child('<name>')`.
+        const logger = this.loggingService
+            .createLogger()
+            .withTags({ addonId, nodeId: brokerNodeId, agentId });
+        const bootstrapConfig = this.buildAddonConfig(addonId);
+        // Per-addon private data directory — resolved from active storage
+        // provider if available, otherwise falls back to a deterministic
+        // hardcoded path. Addons that need the full storage provider now
+        // resolve it via the capability registry.
+        const storageProvider = this.activeStorageProvider;
+        const dataDir = storageProvider
+            ? await storageProvider.resolve({
+                location: 'addons-data',
+                relativePath: addonId,
+            })
+            : `camstack-data/addons-data/${addonId}`;
+        const registerProvider = (capabilityName, provider) => {
+            this.capabilityRegistry.registerProvider(capabilityName, addonId, provider);
+            logger.info('Registered provider via context.registerProvider()', {
+                meta: { capabilityName },
+            });
+        };
+        // Raw three-level settings store API. The resolver service is a
+        // thin wrapper over `ConfigManager` that exposes raw reads/writes
+        // for the addon store, the per-device store, and the cluster-wide
+        // yml-backed sections. No schema merging happens here — the addon
+        // combines these raw reads with its own schema via
+        // `hydrateSchema()` inside `getAddonSettings / getGlobalSettings
+        // / getDeviceSettings`.
+        const settingsView = this.configService.createSettingsView(addonId);
+        // Device management — unified path for hub and worker addons.
+        // Persistence routes through the `device-manager` capability
+        // addon via `ctx.api.deviceManager.*`. On the hub, `ctx.api` is
+        // a broker-routed proxy that resolves the local
+        // `device-manager` Moleculer service in-process — no network
+        // hop. On a forked worker, the same proxy routes through the TCP
+        // transport to the hub's service. Zero custom $hub.* actions needed.
+        const kernelStreamProbe = {
+            probe: (url, options) => this.streamProbe.probe(url, options),
+            probeField: (key, value) => this.streamProbe.probeField(key, value),
+        };
+        const deviceManagerApi = (0, kernel_1.createBrokerDeviceManagerApi)({
+            api: this.getBrokerApi(),
+            addonId,
+            nodeId: this.broker.nodeID,
+            logger,
+            eventBus: this.eventBusService,
+            registry: this.deviceRegistry,
+            capabilityRegistry: this.capabilityRegistry,
+            streamProbe: kernelStreamProbe,
+        });
+        const registry = this;
+        const rr = this.moleculer.readinessRegistry;
+        const capHandleCache = new Map();
+        function getOrCreateHandle(capName, scope, timeoutMs) {
+            const key = `${capName}::${(0, kernel_1.scopeKey)(scope)}`;
+            const existing = capHandleCache.get(key);
+            if (existing)
+                return existing;
+            const handle = new kernel_1.CapabilityHandle(capName, scope, rr, timeoutMs);
+            capHandleCache.set(key, handle);
+            return handle;
+        }
+        const ctx = {
+            id: `addon:${addonId}`,
+            logger,
+            eventBus: this.eventBusService,
+            addonConfig: bootstrapConfig,
+            dataDir,
+            get api() {
+                return registry.getBrokerApi();
+            },
+            integrationRegistry: this.integrationRegistry ?? undefined,
+            // Live capability-collection accessor used by addons like stream-broker
+            // (webrtc fan-out), enrichment-engine, and snapshot orchestrator. Reads
+            // through the hub's CapabilityRegistry so the collection reflects
+            // every addon that has declared itself since the consumer initialized.
+            // Without this, those addons silently saw 0 providers and quietly
+            // skipped the fan-out — no errors, just missing streams/wiring.
+            capabilities: {
+                getCollection: (capName) => {
+                    const items = registry.capabilityRegistry.getCollection(capName);
+                    return items ?? undefined;
+                },
+                getCollectionEntries: (capName) => {
+                    const items = registry.capabilityRegistry.getCollectionEntries(capName);
+                    return items ?? undefined;
+                },
+                get: (capName) => {
+                    return registry.capabilityRegistry.getSingleton(capName) ?? undefined;
+                },
+            },
+            deps: new kernel_3.AddonDepsManager(dataDir, logger),
+            kernel: {
+                localNodeId: this.broker.nodeID,
+                storage: storageProvider ?? undefined,
+                deviceRegistry: this.deviceRegistry ?? undefined,
+                devices: deviceManagerApi,
+                cluster: { broker: (0, kernel_1.adaptBrokerToCluster)(this.moleculer.broker) },
+                streamProbe: kernelStreamProbe,
+                hwaccel: (0, kernel_1.createKernelHwAccel)(),
+                capabilityRegistry: this.capabilityRegistry,
+                // Per-addon storage-location declarations across every installed
+                // addon — surfaced from the kernel's AddonLoader so the
+                // storage-orchestrator builtin can aggregate them and seed defaults.
+                listStorageLocationDeclarations: () => this.addonLoader.listStorageLocationDeclarations(),
+                readinessRegistry: this.moleculer.readinessRegistry,
+                // D3: handshake-fed native-cap view of the whole cluster. Backed by
+                // `HubNodeRegistry.listNativeCapEntries()` populated by every
+                // `$hub.registerNode` re-handshake. Used by device-manager as the
+                // reliable fallback when push events were lost mid-transport.
+                listClusterNativeCaps: () => this.moleculer.listClusterNativeCaps(),
+                // Per-device slice of the above — O(caps-for-device) via the registry's
+                // deviceId index. The per-device `getBindings` resolver prefers this
+                // over filtering the whole-cluster flat view.
+                listClusterNativeCapsForDevice: (deviceId) => this.moleculer.listClusterNativeCapsForDevice(deviceId),
+            },
+            registerProvider,
+            resolveProvider: (capName) => {
+                return registry.capabilityRegistry.getSingleton(capName) ?? null;
+            },
+            getNativeProvider: (cap, deviceId) => {
+                // Hub-side addons live on the same process as the CapabilityRegistry;
+                // native providers are always resolvable locally.
+                const local = registry.capabilityRegistry.getNativeProvider(cap.name, deviceId);
+                if (!local) {
+                    throw new Error(`no native provider for capability '${cap.name}' on device '${deviceId}'`);
+                }
+                return local;
+            },
+            fetchDevice: async (deviceId) => {
+                const api = registry.getBrokerApi();
+                const binding = await api.deviceManager.getBindings.query({ deviceId });
+                return (0, types_1.createDeviceProxy)(api, binding);
+            },
+            settings: settingsView,
+            useCapability(capName, scope = { type: 'global' }) {
+                return getOrCreateHandle(capName, scope, 15_000);
+            },
+            async acquireCapability(capName, scope = { type: 'global' }, opts = {}) {
+                const timeoutMs = opts.timeoutMs ?? 15_000;
+                const handle = getOrCreateHandle(capName, scope, timeoutMs);
+                return handle;
+            },
+            onCapabilityStateChange(capName, scope, handler) {
+                return rr.onReadyState(capName, scope, (t) => {
+                    handler(t.state === 'ready' ? 'ready' : 'down');
+                });
+            },
+            addDisposer(fn) {
+                return registry.getOrCreateDisposerChain(addonId).add(fn);
+            },
+        };
+        return ctx;
+    }
+    /**
+     * Per-addon disposer chain. Created lazily the first time an addon
+     * calls `ctx.addDisposer(...)`. Drained by `restartAddon()` /
+     * `unregisterAddon()` so cleanup callbacks run before the new addon
+     * instance comes up.
+     */
+    disposerChains = new Map();
+    getOrCreateDisposerChain(addonId) {
+        let chain = this.disposerChains.get(addonId);
+        if (chain == null) {
+            const log = this.loggingService.createLogger().withTags({ addonId });
+            chain = new types_3.DisposerChain({
+                onError: (err, index) => {
+                    log.error(`Disposer #${index} threw during teardown`, {
+                        meta: { error: (0, types_1.errMsg)(err) },
+                    });
+                },
+            });
+            this.disposerChains.set(addonId, chain);
+        }
+        return chain;
+    }
+    /**
+     * Drain (and remove) the disposer chain for an addon. Called by the
+     * addon shutdown / restart flow so resources registered via
+     * `ctx.addDisposer(...)` clean up before the next instance boots.
+     */
+    async drainDisposerChain(addonId) {
+        const chain = this.disposerChains.get(addonId);
+        if (chain == null)
+            return;
+        this.disposerChains.delete(addonId);
+        await chain.dispose();
+    }
+    // ── Group orchestration (Phase G3 — opt-in, not yet wired into boot) ──
+    /**
+     * Compute the runner plan for a set of addon ids (base-layer D2).
+     *
+     * The runner contract is one-addon-one-process by default (D2/D9):
+     *   - every addon gets its OWN runner, keyed by the addon id via
+     *     `resolveRunnerId` — no shipped addon declares `execution.group`
+     *     today;
+     *   - the group-collapse path (same `group` → shared runner keyed by
+     *     group name) is an explicit opt-in mechanism; Phase 5 dissolved
+     *     the last real co-location group (`pipeline`) once frames travel
+     *     as shared-memory `FrameHandle`s and audio over tRPC — nothing
+     *     passes a live JS reference across a process boundary any more.
+     *
+     * Addons with `placement: 'agent-only'` are dropped (they don't run on
+     * the hub). `@camstack/core` builtins are dropped too — they stay
+     * in-process on the hub (every forked runner connects to the hub
+     * broker via static-URL TCP transit, so cap providers hosted on the
+     * hub broker are reachable from any runner with one hop; moving them
+     * into a sibling subprocess would isolate them on a separate Moleculer
+     * node that child brokers cannot reach).
+     *
+     * Read-only. Used by the bootstrap to plan spawns up-front and by
+     * diagnostics that want to render the current topology.
+     */
+    buildAddonGroupPlan(addonIds) {
+        const plan = new Map();
+        for (const id of addonIds) {
+            const entry = this.addonEntries.get(id);
+            if (!entry?.declaration || !entry.addonDir)
+                continue;
+            if (entry.packageName === '@camstack/core')
+                continue;
+            const placement = (0, types_1.resolveAddonPlacement)(entry.declaration);
+            if (placement === 'agent-only')
+                continue;
+            const runnerId = (0, types_1.resolveRunnerId)(entry.declaration, id);
+            const bucket = plan.get(runnerId) ?? [];
+            bucket.push({ addonId: id, addonDir: entry.addonDir });
+            plan.set(runnerId, bucket);
+        }
+        return plan;
+    }
+    /**
+     * Spawn ONE runner subprocess that hosts every addon in `addons` and
+     * register their custom-actions catalogs against the shared
+     * CustomActionRegistry. Cap providers register themselves via
+     * `CapabilityBridge.onProviderConnected` — the bridge listens for any
+     * new Moleculer node (the runner's nodeID is `${parent}/${runnerId}`)
+     * and proxies its services into the local `CapabilityRegistry`.
+     *
+     * `runnerId` is the addon id (a solo runner — one addon per process,
+     * D2/D9). It can structurally also be a co-location group name if an
+     * addon ever declared `execution.group`, but no shipped manifest does.
+     *
+     * No-op when the runner is already running (idempotent for tests +
+     * crash respawn paths). Errors propagate so the bootstrap can log the
+     * failed runner and surface every hosted addon as `addon.error`.
+     */
+    async initializeAddonGroup(runnerId, addons) {
+        if (addons.length === 0) {
+            throw new Error(`initializeAddonGroup("${runnerId}") requires at least one addon`);
+        }
+        try {
+            await this.broker.call('$process.spawnRunner', {
+                runnerId,
+                addons,
+            });
+        }
+        catch (err) {
+            throw new Error(`Failed to spawn runner "${runnerId}" (${addons.length} addons): ${(0, types_1.errMsg)(err)}`, { cause: err });
+        }
+        // Register custom actions for each addon on the runner. Provider
+        // registration for cap methods is handled by
+        // `CapabilityBridge.onProviderConnected` once the runner's
+        // INFO heartbeat lands.
+        for (const { addonId } of addons) {
+            await this.registerForkedAddonCustomActions(addonId, runnerId);
+            // Mark the entry initialized so the in-process core-builtin boot
+            // passes skip it (those passes only touch `@camstack/core`).
+            const entry = this.addonEntries.get(addonId);
+            if (entry) {
+                entry.initialized = true;
+                this.emitAddonLifecycleEvent('addon.started', addonId);
+            }
+        }
+        this.logger.info('Addon runner spawned', {
+            meta: { runnerId, addonCount: addons.length, addonIds: addons.map((a) => a.addonId) },
+        });
+    }
+    /**
+     * (Re-)register the custom-action catalog for a forked / group-hosted
+     * addon against the shared `CustomActionRegistry`.
+     *
+     * The catalog (zod `input`/`output` specs) is read STATICALLY from the
+     * addon module's `customActions` named export — the handler dispatches
+     * over UDS via `LocalChildRegistry.callAddonOnChild(addonId,
+     * {target:'custom', action, args})` (F3 — replaces the removed per-addon
+     * Moleculer `custom.<action>` action), so the only divergence vs an
+     * in-process addon is the transport, exactly like cap methods. The hub's
+     * `CustomActionRegistry` validates input/output around this dispatch.
+     *
+     * Why a fresh import: `this.addonLoader`'s `module` namespace is
+     * captured once at boot. After a hot-update (`installFromTgz` →
+     * `restartAddon`) the on-disk bundle is newer than that cached module,
+     * so re-reading the boot-time `module` would register a STALE catalog
+     * (or none at all, if the addon was first installed after boot). We
+     * re-`import()` the entry with a cache-busting query so Node's ESM
+     * loader hands back the current bundle.
+     *
+     * Idempotent: drops any prior registration first. No-op (with a debug
+     * log) when the addon exports no `customActions` — most addons don't.
+     */
+    async registerForkedAddonCustomActions(addonId, runnerId) {
+        // Always clear first so a restart that REMOVES custom actions (or an
+        // addon whose entry no longer exports them) doesn't leave stale
+        // entries resolvable.
+        this.customActionRegistry.unregisterAddon(addonId);
+        const entry = this.addonEntries.get(addonId);
+        const addonDir = entry?.addonDir;
+        const declarationEntry = entry?.declaration?.entry;
+        if (!addonDir || !declarationEntry)
+            return;
+        // Resolve the built entry the same way `AddonLoader.loadDeclaration`
+        // does: `./src/x.ts` → `dist/x.js`, with index.js fallbacks.
+        const entryFile = declarationEntry
+            .replace(/^\.\//, '')
+            .replace(/^src\//, 'dist/')
+            .replace(/\.ts$/, '.js');
+        let entryPath = path.resolve(addonDir, entryFile);
+        if (!fs.existsSync(entryPath)) {
+            const base = entryPath.replace(/\.(js|cjs|mjs)$/, '');
+            const alternatives = [
+                `${base}.cjs`,
+                `${base}.mjs`,
+                path.resolve(addonDir, 'dist', 'index.js'),
+                path.resolve(addonDir, 'dist', 'index.cjs'),
+                path.resolve(addonDir, 'dist', 'index.mjs'),
+                path.resolve(addonDir, declarationEntry),
+            ];
+            entryPath = alternatives.find((p) => fs.existsSync(p)) ?? entryPath;
+        }
+        if (!fs.existsSync(entryPath))
+            return;
+        let catalog;
+        try {
+            // Cache-bust so a hot-updated bundle is re-read instead of served
+            // from Node's ESM module cache.
+            const cacheBustedUrl = `${(0, node_url_1.pathToFileURL)(entryPath).href}?t=${Date.now()}`;
+            const modUnknown = await Promise.resolve(`${cacheBustedUrl}`).then(s => __importStar(require(s)));
+            catalog =
+                modUnknown && typeof modUnknown === 'object'
+                    ? modUnknown['customActions']
+                    : undefined;
+        }
+        catch (err) {
+            this.logger.warn('Failed to load custom-action catalog for forked addon', {
+                tags: { addonId },
+                meta: { error: (0, types_1.errMsg)(err) },
+            });
+            return;
+        }
+        if (!catalog || typeof catalog !== 'object') {
+            this.logger.debug('Forked addon exports no custom actions', {
+                tags: { addonId },
+                meta: { runnerId },
+            });
+            return;
+        }
+        this.customActionRegistry.registerAddon(addonId, catalog, (action, input) => this.dispatchForkedCustomAction(addonId, action, input));
+        this.logger.info('Runner addon custom actions registered', {
+            tags: { addonId },
+            meta: { runnerId },
+        });
+    }
+    /**
+     * Dispatch a forked addon's custom action through the shared
+     * {@link AddonCallGateway} (UDS to the hub-local child). The gateway owns the
+     * routing + the child-availability error; there is no broker fallback after
+     * the per-addon Moleculer broker was removed.
+     */
+    async dispatchForkedCustomAction(addonId, action, input) {
+        return this.addonCallGateway.callForked(addonId, {
+            target: 'custom',
+            action,
+            args: input,
+        });
+    }
+}
+exports.AddonRegistryService = AddonRegistryService;