@camstack/server 0.2.2 → 1.0.1

package/src/core/addon/addon-registry.service.ts

@@ -1,3130 +0,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. */
-import * as os from 'node:os'
-import { ConfigService } from '../config/config.service'
-import { overlayDeclaration } from './addon-row-manifest'
-import { LoggingService } from '../logging/logging.service'
-import { EventBusService } from '../events/event-bus.service'
-import { StorageService } from '../storage/storage.service'
-import { StreamProbeService } from '../streaming/stream-probe.service'
-
-import { CapabilityService } from '../capability/capability.service'
-import {
-  EventCategory,
-  createDeviceProxy,
-  normalizeAddonInitResult,
-  errMsg,
-  isAgentOnlyPlacement,
-  resolveRunnerId,
-  resolveAddonPlacement,
-} from '@camstack/types'
-import type {
-  AddonDeclaration,
-  CapabilityDeclaration,
-  CapabilityDefinition,
-  InferProvider,
-  RunnerPlan,
-  RunnerAddonPlacement,
-} from '@camstack/types'
-import type { ICamstackAddon, AddonContext, InternalAddonContext } from '@camstack/types'
-import type { IScopedLogger } from '@camstack/types'
-import {
-  CapabilityRegistry,
-  CustomActionRegistry,
-  INFRA_CAPABILITIES,
-  AddonLoader,
-  AddonHealthMonitor,
-  DeviceRegistry,
-  adaptBrokerToCluster,
-  createAddonService,
-  createBrokerDeviceManagerApi,
-  createKernelHwAccel,
-  validateProviderRegistrations,
-  CapabilityHandle,
-  scopeKey,
-  describeProviderKindDrift,
-  type ISettingsStore,
-  type AddonSettingsView,
-  type AddonHealthSnapshot,
-} from '@camstack/kernel'
-import { localProviderLink, brokerTransportLink } from '@camstack/kernel'
-import { createTRPCClient } from '@trpc/client'
-import { MoleculerService } from '../moleculer/moleculer.service'
-import { AddonDepsManager } from '@camstack/kernel'
-import type { SavedDevice, ReadinessScope } from '@camstack/types'
-import { IntegrationRegistry } from '@camstack/core'
-import type { IStorageProvider as INewStorageProvider, ISettingsBackend } from '@camstack/types'
-import { AddonRouteRegistry, DataPlaneRegistry } from '@camstack/core'
-import { randomUUID } from 'node:crypto'
-import * as path from 'node:path'
-import * as fs from 'node:fs'
-import { pathToFileURL } from 'node:url'
-import { createAddonSettingsProvider } from './addon-settings-provider.js'
-import { AddonCallGateway } from './addon-call-gateway.js'
-import { addonSettingsCapability } from '@camstack/types'
-import { DisposerChain } from '@camstack/types'
-
-type AddonSource = 'core' | 'installed'
-
-/**
- * Local narrowing of the Moleculer ServiceBroker surface we actually use.
- * See the `broker` getter docstring below for why this is necessary.
- */
-interface BrokerLike {
-  call<T = unknown>(
-    action: string,
-    params?: unknown,
-    opts?: { nodeID?: string; timeout?: number },
-  ): Promise<T>
-  nodeID: string
-  createService(schema: unknown): unknown
-}
-
-/**
- * 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: ISettingsBackend): backend is ISettingsBackend & ISettingsStore {
-  const required: readonly (keyof ISettingsStore)[] = [
-    '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
-}
-
-/**
- * The bridge-dispatch contract on an `addon-routes` provider. The operator-
- * facing `IAddonRouteProvider` interface declares only `id` + `getRoutes`; the
- * UDS proxy (and `buildAddonRouteProvider`) also expose `invoke`, which the
- * forked-routes bridge calls per request. Narrowed via `isAddonRoutesInvoker`.
- */
-interface AddonRoutesInvoker {
-  invoke(
-    input: import('@camstack/types').AddonRouteInvokeRequest,
-  ): Promise<import('@camstack/types').AddonRouteReplyEnvelope>
-}
-
-/** Structural guard: true when an `addon-routes` provider also exposes `invoke`. */
-function isAddonRoutesInvoker<T extends object>(provider: T): provider is T & AddonRoutesInvoker {
-  return typeof Reflect.get(provider, 'invoke') === 'function'
-}
-
-const ROUTE_METHODS: readonly import('@camstack/types').IAddonHttpRoute['method'][] = [
-  'GET',
-  'POST',
-  'PUT',
-  'DELETE',
-]
-const ROUTE_ACCESS: readonly import('@camstack/types').RouteAccess[] = [
-  'public',
-  'authenticated',
-  'admin',
-]
-
-function asRouteMethod(value: string): import('@camstack/types').IAddonHttpRoute['method'] {
-  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: unknown): import('@camstack/types').RouteAccess {
-  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'
-}
-
-/**
- * Parse the wire-boundary `unknown` returned by `callAddonOnChild(...,
- * {target:'routes'})` into typed route descriptors. The child sends route
- * descriptors WITHOUT handlers (functions don't cross MsgPack); only
- * `method`/`path`/`access`/`description` are present.
- */
-interface ParsedRouteDescriptor {
-  readonly method: import('@camstack/types').IAddonHttpRoute['method']
-  readonly path: string
-  readonly access: import('@camstack/types').RouteAccess
-  readonly description?: string
-}
-
-function parseSerializableRouteDescriptors(raw: unknown): readonly ParsedRouteDescriptor[] {
-  if (!Array.isArray(raw)) {
-    throw new Error('addon-routes: child returned a non-array route descriptor set')
-  }
-  return raw.map((entry: unknown): ParsedRouteDescriptor => {
-    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: unknown,
-): readonly import('@camstack/types').AddonDataPlaneEndpoint[] {
-  if (!Array.isArray(raw)) {
-    throw new Error('data-planes: child returned a non-array endpoint set')
-  }
-  return raw.map((entry: unknown): import('@camstack/types').AddonDataPlaneEndpoint => {
-    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 }
-  })
-}
-
-interface AddonEntry {
-  readonly addon: ICamstackAddon
-  initialized: boolean
-  source: AddonSource
-  /** npm package name from package.json (e.g. '@camstack/addon-detection-pipeline') */
-  packageName: string
-  /** npm package version from package.json */
-  packageVersion: string
-  /** Human-readable package name from camstack.displayName */
-  packageDisplayName?: string
-  /** Optional bundle metadata when the package ships multiple addon entries. */
-  bundle?: { displayName: string; description?: string; icon?: string }
-  /** Capabilities declared in package.json camstack.addons (source of truth) */
-  declaredCapabilities: readonly CapabilityDeclaration[]
-  /** Addon directory on disk */
-  addonDir?: string
-  /** Full package.json declaration (AddonDeclaration from @camstack/types) */
-  declaration?: AddonDeclaration
-}
-
-// 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.
-
-export class AddonRegistryService {
-  private readonly addonEntries = new Map<string, AddonEntry>()
-  private readonly capabilityRegistry: CapabilityRegistry
-  /** Single router for addon-level calls (routes / custom / settings). */
-  private addonCallGateway!: 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.
-  private readonly customActionRegistry = new 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.
-   */
-  private readonly restartingAddons = new Map<string, NodeJS.Timeout>()
-  private readonly logger: IScopedLogger
-  private addonLoader!: AddonLoader
-  private healthMonitor!: AddonHealthMonitor
-  private addonRouteRegistry: AddonRouteRegistry | null = null
-  private dataPlaneRegistry: DataPlaneRegistry | null = 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.
-  private brokerApi: import('@camstack/types').AddonApi | null = 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.
-   */
-  public getBrokerApi(): import('@camstack/types').AddonApi {
-    if (!this.brokerApi) {
-      const reg = this.capabilityRegistry
-      const resolver = {
-        getByName: (capName: string): unknown | null =>
-          reg.getSingleton(capName) ?? (reg.getAllProviders(capName)[0] as unknown) ?? null,
-      }
-      const client: unknown = createTRPCClient({
-        links: [localProviderLink(resolver), brokerTransportLink(this.moleculer.broker)],
-      })
-      this.brokerApi = client as import('@camstack/types').AddonApi
-    }
-    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)
-  private activeStorageProvider: INewStorageProvider | null = null
-  private activeSettingsBackend: ISettingsBackend | null = null
-  private integrationRegistry: import('@camstack/core').IntegrationRegistry | null = null
-
-  // Device architecture — in-memory registry of live IDevice instances.
-  // Persistence is owned by the `device-manager` capability addon.
-  private readonly deviceRegistry = new 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.
-   */
-  private get broker(): BrokerLike {
-    return this.moleculer.broker as unknown as BrokerLike
-  }
-
-  constructor(
-    private readonly loggingService: LoggingService,
-    private readonly eventBusService: EventBusService,
-    private readonly configService: ConfigService,
-    private readonly storageService: StorageService,
-    private readonly capabilityService: CapabilityService,
-    private readonly moleculer: MoleculerService,
-    private readonly streamProbe: StreamProbeService,
-  ) {
-    this.logger = this.loggingService.createLogger('AddonRegistry')
-    this.addonLoader = new 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 AddonHealthMonitor({
-      eventBus: this.eventBusService as unknown as import('@camstack/types').IEventBus,
-      logger: this.loggingService.createLogger('AddonHealthMonitor'),
-      retryFn: (packageName) => this.tryReloadPackage(packageName),
-    })
-
-    // Create capability registry with config reader for singleton preferences
-    this.capabilityRegistry = new CapabilityRegistry(
-      this.loggingService.createLogger('CapabilityRegistry'),
-      this.eventBusService,
-    )
-    this.capabilityRegistry.setConfigReader((capability: string): string | undefined => {
-      try {
-        return this.configService.get<string>(`capabilities.singleton.${capability}`) ?? undefined
-      } catch (err) {
-        this.logger.debug('settings-store not wired yet during early boot', {
-          meta: { capability, error: errMsg(err) },
-        })
-        return undefined
-      }
-    })
-
-    this.capabilityRegistry.setNodeConfigReader(
-      (capability: string, nodeId: string): string | undefined => {
-        try {
-          return (
-            this.configService.get<string>(`capabilities.singletonNode.${capability}.${nodeId}`) ??
-            undefined
-          )
-        } catch (err) {
-          this.logger.debug('settings-store not wired yet during early boot', {
-            meta: { capability, nodeId, error: 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: string): readonly string[] | undefined => {
-        try {
-          const raw = this.configService.get<string>(`capabilities.collection.${capability}`)
-          if (!raw) return undefined
-          const parsed: unknown = JSON.parse(raw)
-          if (
-            typeof parsed === 'object' &&
-            parsed !== null &&
-            'disabled' in parsed &&
-            Array.isArray((parsed as { disabled: unknown }).disabled)
-          ) {
-            const disabled = (parsed as { disabled: unknown[] }).disabled
-            return disabled.filter((id): id is string => typeof id === 'string')
-          }
-          return undefined
-        } catch (err) {
-          this.logger.debug('settings-store not wired yet or malformed collection preference', {
-            meta: { capability, error: 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(): Promise<void> {
-    // 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(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 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 = 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 ?? {}) as {
-        nodeId?: string
-        capName?: string
-        addonId?: string | null
-      }
-      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 (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: string | CapabilityDeclaration) =>
-            typeof c === 'string' ? { name: c, mode: 'singleton' as const } : 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 = 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 import('@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: string, deviceId: number): unknown | null => {
-          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: Record<string, (input: unknown) => Promise<unknown>> = {}
-              return new Proxy(target, {
-                get(_target, property): ((input: unknown) => Promise<unknown>) | undefined {
-                  if (typeof property !== 'string') return undefined
-                  return (input: unknown): Promise<unknown> => {
-                    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' as const,
-                      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<{
-            resolveNativeCapOwnerSync?: (
-              capName: string,
-              deviceId: number,
-            ) => { addonId: string; nodeId: string } | null
-          }>('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: unknown) {
-          const msg = 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: string): boolean =>
-      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 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: unknown) {
-          const msg = 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(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: unknown) {
-          const msg = 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: unknown) {
-          const msg = 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()
-
-    // Group-runner / forked-addon crash detection (point 5 of the
-    // operator's spec — "ogni fork/moleculer deve essere considerato").
-    // Moleculer's process-service.ts already handles respawn with
-    // exponential backoff; we hook the broker's localBus events to
-    // GIVE VISIBILITY of those crashes through the same monitor —
-    // every crash records a failure, every reconnect records a
-    // recovery. The respawn itself stays in process-service.ts.
-    //
-    // Runner node ids look like `hub/<runnerId>` where `runnerId` is the
-    // addon id for a solo runner (the common case — one addon, one
-    // process) or the co-location group name for a shared runner (e.g.
-    // `hub/pipeline`). We map a disconnected/connected node back to the
-    // underlying addons by walking `addonEntries` for any addon whose
-    // resolved runner id matches the event's nodeId — every addon on
-    // that runner gets a recordFailure / recordSuccess.
-    type LocalBusEvent = { node: { id: string } }
-    type LocalBus = { on: (event: string, handler: (payload: LocalBusEvent) => void) => void }
-    const localBus = (this.moleculer.broker as unknown as { localBus?: LocalBus }).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 = 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 = resolveRunnerId(entry.declaration, id)
-          if (`${this.broker.nodeID}/${runnerId}` !== nodeId) continue
-          this.healthMonitor.recordSuccess(entry.packageName, id)
-        }
-      })
-    }
-
-    this.eventBusService.emit({
-      id: randomUUID(),
-      timestamp: new Date(),
-      source: { type: 'core', id: 'addon-registry' },
-      category: 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: string): Promise<void> {
-    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: string[] = []
-    for (const [id, entry] of this.addonEntries.entries()) {
-      if (entry.packageName === packageName) {
-        knownAddonIds.push(id)
-      }
-    }
-
-    if (knownAddonIds.length > 0) {
-      const errors: string[] = []
-      for (const id of knownAddonIds) {
-        try {
-          await this.restartAddon(id)
-          this.healthMonitor.recordSuccess(packageName, id)
-        } catch (err) {
-          errors.push(`${id}: ${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(): readonly AddonHealthSnapshot[] {
-    return this.healthMonitor.getHealthSnapshot()
-  }
-
-  /** Manual user-triggered retry (resets retry counter). */
-  async retryAddonLoad(packageName: string): Promise<void> {
-    return this.healthMonitor.retryNow(packageName)
-  }
-
-  async onModuleDestroy(): Promise<void> {
-    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: AddonRouteRegistry): void {
-    this.addonRouteRegistry = registry
-  }
-
-  /** Set the DataPlaneRegistry the hub's `/addon/:id/*` dispatch reverse-proxies
-   *  against (addon HTTP data-planes). */
-  setDataPlaneRegistry(registry: DataPlaneRegistry): void {
-    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.
-   */
-  private async mountAddonDataPlanes(addonId: string): Promise<void> {
-    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: unknown): Promise<void> {
-    this.logger.debug(
-      'setAppRouter called — broker-routed addon API in use, no direct caller needed',
-    )
-  }
-
-  /** Get the CapabilityRegistry for external consumers to register */
-  getCapabilityRegistry(): CapabilityRegistry {
-    return this.capabilityRegistry
-  }
-
-  /** Get the CustomActionRegistry — Task 7.2 will use this from the `api.addons.custom` tRPC procedure. */
-  getCustomActionRegistry(): CustomActionRegistry {
-    return this.customActionRegistry
-  }
-
-  getDeviceRegistry(): DeviceRegistry {
-    return this.deviceRegistry
-  }
-
-  /** Load persisted collection disabled-lists from settings-store into the registry */
-  private loadCollectionPreferences(): void {
-    // 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(): import('@camstack/types').IIntegrationRegistry | null {
-    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(): ISettingsBackend | null {
-    return this.activeSettingsBackend
-  }
-
-  /** Get the raw (unfiltered) registry — only for internal addon wiring */
-  getRawIntegrationRegistry(): import('@camstack/types').IIntegrationRegistry | null {
-    return this.integrationRegistry
-  }
-
-  private createFilteredRegistry(
-    raw: import('@camstack/types').IIntegrationRegistry,
-  ): import('@camstack/types').IIntegrationRegistry {
-    const installedAddonIds = new Set(this.addonEntries.keys())
-
-    // Build set of integration IDs whose addon IS installed
-    // Cache per call — lightweight, called infrequently
-    let activeIntegrationIds: Set<string> | null = 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 */
-  private logAddonLifecycle(
-    event: 'started' | 'restarted',
-    id: string,
-    mode: 'in-process' | 'isolated',
-  ): void {
-    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: ICamstackAddon,
-    source: AddonSource = 'installed',
-    packageName?: string,
-    packageVersion?: string,
-  ): void {
-    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: string): Promise<void> {
-    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 = 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.
-        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<string, unknown>()
-    // 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 = 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 = 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: 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)
-      }
-      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: string): readonly string[] => {
-          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 = 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: 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.
-   */
-  private async restoreAddonDevices(addonId: string, addon: ICamstackAddon): Promise<void> {
-    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: unknown = await (
-        Reflect.get(Reflect.get(api, 'deviceManager') as object, 'listPersistedByAddon') as {
-          query: (input: unknown) => Promise<unknown>
-        }
-      ).query({ addonId })
-
-      const rows = Array.isArray(listResult)
-        ? (listResult as Array<{
-            id: number
-            stableId: string
-            type: string
-            name: string
-            location?: string | null
-            disabled?: boolean
-            parentDeviceId: number | null
-          }>)
-        : []
-      if (rows.length === 0) return
-
-      const savedDevices: SavedDevice[] = await Promise.all(
-        rows.map(async (row) => {
-          const configResult: unknown = await (
-            Reflect.get(Reflect.get(api, 'deviceManager') as object, 'loadConfig') as {
-              query: (input: unknown) => Promise<unknown>
-            }
-          ).query({ deviceId: row.id })
-
-          return {
-            id: row.id,
-            stableId: row.stableId,
-            type: row.type as import('@camstack/types').DeviceType,
-            name: row.name,
-            location: row.location ?? null,
-            disabled: row.disabled ?? false,
-            parentDeviceId: row.parentDeviceId,
-            config: (configResult ?? {}) as Record<string, unknown>,
-          }
-        }),
-      )
-
-      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: 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: string, newVersion: string): void {
-    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: string): void {
-    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: string, fromVersion: string, toVersion: string): void {
-    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: string): Promise<{ success: boolean; error?: string }> {
-    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,
-        })) as { success: boolean; reason?: string }
-        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 is string => 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 = 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 as unknown as {
-            destroyService(name: string): Promise<void>
-          }
-        ).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 = 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: string): ICamstackAddon | null {
-    const entry = this.addonEntries.get(id)
-    return entry?.addon ?? null
-  }
-
-  getAddonEntry(id: string): { addon: ICamstackAddon } | null {
-    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: string): string | null {
-    const entry = this.addonEntries.get(id)
-    if (entry?.addonDir) return entry.addonDir
-    return this.findAddonDirOnDisk(id)
-  }
-
-  private findAddonDirOnDisk(addonId: string): string | null {
-    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: string): string | null => {
-      const pkgJsonPath = path.join(pkgDir, 'package.json')
-      if (!fs.existsSync(pkgJsonPath)) return null
-      try {
-        const pkg = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf-8')) as Record<string, unknown>
-        const camstack = (pkg['camstack'] as { addons?: unknown[] } | undefined) ?? {}
-        const addons = Array.isArray(camstack.addons)
-          ? (camstack.addons as Record<string, unknown>[])
-          : []
-        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: string): { addonDir: string; distDir: string } | null {
-    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: string): Promise<AddonContext | null> {
-    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: string): boolean {
-    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.
-   */
-  private isForkedAddonEntry(
-    entry: AddonEntry,
-  ): entry is AddonEntry & { addonDir: string; declaration: AddonDeclaration } {
-    return !!(
-      entry.declaration &&
-      entry.addonDir &&
-      entry.packageName !== '@camstack/core' &&
-      resolveAddonPlacement(entry.declaration) !== 'agent-only'
-    )
-  }
-
-  /** Per-entry helper used by `listAddons()` to mark a row removable / not. */
-  private isRequiredEntry(entry: AddonEntry): boolean {
-    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(): Array<{
-    manifest: AddonDeclaration & {
-      packageName: string
-      packageVersion: string
-      packageDisplayName?: string
-      bundle?: { displayName: string; description?: string; icon?: string }
-      protected?: boolean
-      removable?: boolean
-    }
-    declaration?: AddonDeclaration
-    source: AddonSource
-    installSource?: 'npm' | 'local' | 'upload'
-    process?: { pid?: number; mode: 'in-process'; state: string }
-  }> {
-    // Build process info map from in-memory data (sync, no stats)
-    const processMap = new Map<string, { pid?: number; mode: 'in-process'; state: string }>()
-    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: 'npm' | 'local' | 'upload' | undefined
-        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: 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.
-            ...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.
-   */
-  private scanFailedToLoadPackages(seenPackages: ReadonlySet<string>): Array<{
-    manifest: AddonDeclaration & {
-      packageName: string
-      packageVersion: string
-      packageDisplayName?: string
-      protected?: boolean
-      removable?: boolean
-    }
-    declaration?: AddonDeclaration
-    source: AddonSource
-    installSource?: 'npm' | 'local' | 'upload'
-    process?: { pid?: number; mode: 'in-process'; state: string }
-  }> {
-    const dataDir = path.resolve(process.env.CAMSTACK_DATA ?? 'camstack-data')
-    const addonsDir = path.resolve(dataDir, 'addons')
-    if (!fs.existsSync(addonsDir)) return []
-
-    type Row =
-      ReturnType<AddonRegistryService['scanFailedToLoadPackages']> extends Array<infer R>
-        ? R
-        : never
-    const out: Row[] = []
-    const visit = (pkgDir: string): void => {
-      const pkgJsonPath = path.join(pkgDir, 'package.json')
-      if (!fs.existsSync(pkgJsonPath)) return
-      let pkg: Record<string, unknown>
-      try {
-        pkg = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf-8')) as Record<string, unknown>
-      } 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'] as { addons?: unknown[] } | undefined) ?? {}
-      const addons = Array.isArray(camstack.addons)
-        ? (camstack.addons as Record<string, unknown>[])
-        : []
-      if (addons.length === 0) return
-
-      let installSource: 'npm' | 'local' | 'upload' | undefined
-      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 as { displayName?: string }).displayName
-      // Bundle metadata — present when the package ships multiple addon
-      // entries that should render as collapsible children in the UI.
-      const bundleRaw = (
-        camstack as { bundle?: { displayName?: string; description?: string; icon?: string } }
-      ).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: Row['manifest'] = {
-          ...(decl as unknown as AddonDeclaration),
-          id,
-          name,
-          packageName,
-          packageVersion,
-          ...(packageDisplayName ? { packageDisplayName } : {}),
-          ...(bundle !== undefined ? { bundle } : {}),
-          protected: isProtected || undefined,
-          removable: !isProtected,
-        }
-        out.push({
-          manifest,
-          declaration: decl as unknown as AddonDeclaration,
-          source: 'installed' as AddonSource,
-          ...(installSource ? { installSource } : {}),
-          process: { mode: 'in-process' as const, 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(): Promise<
-    ReadonlyArray<{
-      id: string
-      label: string
-      state: 'running' | 'stopped' | 'crashed' | 'starting'
-      pid?: number
-      stats?: {
-        pid: number
-        cpu: number
-        memory: number
-        uptime: number
-        restartCount: number
-      }
-      restartCount: number
-      mode: 'in-process'
-    }>
-  > {
-    const result: Array<{
-      id: string
-      label: string
-      state: 'running' | 'stopped' | 'crashed' | 'starting'
-      pid?: number
-      stats?: {
-        pid: number
-        cpu: number
-        memory: number
-        uptime: number
-        restartCount: number
-      }
-      restartCount: number
-      mode: 'in-process'
-    }> = []
-
-    // Collect hub PID and fetch stats
-    const { getPidStats } = await import('@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(): Promise<{ loaded: string[]; failed: string[] }> {
-    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 AddonLoader(this.loggingService.createLogger('AddonLoader'))
-    await freshLoader.loadFromDirectory(addonsDir)
-
-    const loaded: string[] = []
-    const failed: string[] = []
-
-    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: string | CapabilityDeclaration) =>
-            typeof c === 'string' ? { name: c, mode: 'singleton' as const } : 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 (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: string | CapabilityDeclaration) =>
-            typeof c === 'string' ? { name: c, mode: 'singleton' as const } : 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 = 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: { declaration: { id: string } }) => 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: 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: 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(): Promise<void> {
-    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.
-   */
-  private wireCapabilityConsumers(): void {
-    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: 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 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: unknown) => {
-            this.logger.error('Failed to mount addon routes', {
-              meta: { phase: 'v2', addonId, error: 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: unknown) => {
-        this.logger.error('Failed to mount addon data-planes', {
-          meta: { phase: 'v2', addonId, error: 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.
-   */
-  private async mountAddonRoutes(addonId: string): Promise<void> {
-    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.
-   */
-  private async mountForkedAddonRoutes(
-    addonId: string,
-    routeProvider: import('@camstack/types').IAddonRouteProvider,
-    addonRouteRegistry: AddonRouteRegistry,
-  ): Promise<void> {
-    // 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: import('@camstack/types').IAddonHttpRoute[] = 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.
-
-  private emitAddonLifecycleEvent(
-    eventType:
-      | 'addon.started'
-      | 'addon.stopped'
-      | 'addon.restarted'
-      | 'addon.updated'
-      | 'addon.installed'
-      | 'addon.uninstalled'
-      | 'addon.crashed'
-      | 'addon.error',
-    addonId: string,
-    data?: Record<string, unknown>,
-  ): void {
-    const entry = this.addonEntries.get(addonId)
-    this.eventBusService.emit({
-      id: 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().
-   */
-  private wireCapabilities(addonId: string): void {
-    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: randomUUID(),
-        timestamp: new Date(),
-        source: { type: 'addon', id: addonId },
-        category: 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: randomUUID(),
-        timestamp: new Date(),
-        source: { type: 'addon', id: addonId },
-        category: EventCategory.AddonWidgetReady,
-        data: { addonId, packageName: entry.packageName },
-      })
-    }
-  }
-
-  private getAddonCapabilities(addon: ICamstackAddon): CapabilityDeclaration[] {
-    const caps = addon?.manifest?.capabilities
-    if (!caps) return []
-
-    return caps.map((cap): CapabilityDeclaration => (typeof cap === 'string' ? { name: cap } : cap))
-  }
-
-  private findAddonForCapability(capName: string, addonIds: string[]): string | null {
-    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).
-   */
-  private buildAddonConfig(addonId: string): Record<string, unknown> {
-    // Start with per-addon SQL settings (may be empty for most addons)
-    let addonSpecific: Record<string, unknown> = {}
-    try {
-      addonSpecific = this.configService.getAddonConfig(addonId)
-    } catch (err) {
-      this.logger.debug('ConfigManager not ready for addon', {
-        tags: { addonId },
-        meta: { error: 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
-  }
-
-  private async createAddonContext(addon: ICamstackAddon): Promise<InternalAddonContext> {
-    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: string, provider: unknown): void => {
-      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: AddonSettingsView = 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: import('@camstack/types').IKernelStreamProbe = {
-      probe: (url, options) => this.streamProbe.probe(url, options),
-      probeField: (key, value) => this.streamProbe.probeField(key, value),
-    }
-    const deviceManagerApi: import('@camstack/types').DeviceManagerApi =
-      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<string, CapabilityHandle<unknown>>()
-    function getOrCreateHandle<T>(
-      capName: string,
-      scope: ReadinessScope,
-      timeoutMs: number,
-    ): CapabilityHandle<T> {
-      const key = `${capName}::${scopeKey(scope)}`
-      const existing = capHandleCache.get(key)
-      if (existing) return existing as CapabilityHandle<T>
-      const handle = new CapabilityHandle<T>(capName, scope, rr, timeoutMs)
-      capHandleCache.set(key, handle as CapabilityHandle<unknown>)
-      return handle
-    }
-    const ctx: InternalAddonContext & {
-      integrationRegistry?: unknown
-      capabilities: import('@camstack/types').CapabilitiesAccess
-    } = {
-      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: <T = unknown>(capName: string): readonly T[] | undefined => {
-          const items = registry.capabilityRegistry.getCollection<T>(capName)
-          return items ?? undefined
-        },
-        getCollectionEntries: <T = unknown>(
-          capName: string,
-        ): readonly (readonly [string, T])[] | undefined => {
-          const items = registry.capabilityRegistry.getCollectionEntries<T>(capName)
-          return items ?? undefined
-        },
-        get: <T = unknown>(capName: string): T | undefined => {
-          return registry.capabilityRegistry.getSingleton<T>(capName) ?? undefined
-        },
-      },
-      deps: new AddonDepsManager(dataDir, logger),
-      kernel: {
-        localNodeId: this.broker.nodeID,
-        storage: storageProvider ?? undefined,
-        deviceRegistry: this.deviceRegistry ?? undefined,
-        devices: deviceManagerApi,
-        cluster: { broker: adaptBrokerToCluster(this.moleculer.broker) },
-        streamProbe: kernelStreamProbe,
-        hwaccel: 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: number) =>
-          this.moleculer.listClusterNativeCapsForDevice(deviceId),
-      },
-      registerProvider,
-      resolveProvider: <T = unknown>(capName: string): T | null => {
-        return (registry.capabilityRegistry.getSingleton<T>(capName) as T | null) ?? null
-      },
-      getNativeProvider: <TCap extends CapabilityDefinition>(
-        cap: TCap,
-        deviceId: number,
-      ): InferProvider<TCap> => {
-        // Hub-side addons live on the same process as the CapabilityRegistry;
-        // native providers are always resolvable locally.
-        const local = registry.capabilityRegistry.getNativeProvider<InferProvider<TCap>>(
-          cap.name,
-          deviceId,
-        )
-        if (!local) {
-          throw new Error(`no native provider for capability '${cap.name}' on device '${deviceId}'`)
-        }
-        return local
-      },
-      fetchDevice: async (deviceId: number) => {
-        const api = registry.getBrokerApi()
-        const binding = await api.deviceManager.getBindings.query({ deviceId })
-        return createDeviceProxy(api, binding)
-      },
-      settings: settingsView,
-      useCapability<T = unknown>(capName: string, scope: ReadinessScope = { type: 'global' }) {
-        return getOrCreateHandle<T>(capName, scope, 15_000)
-      },
-      async acquireCapability<T = unknown>(
-        capName: string,
-        scope: ReadinessScope = { type: 'global' },
-        opts: { timeoutMs?: number } = {},
-      ) {
-        const timeoutMs = opts.timeoutMs ?? 15_000
-        const handle = getOrCreateHandle<T>(capName, scope, timeoutMs)
-        return handle
-      },
-      onCapabilityStateChange(
-        capName: string,
-        scope: ReadinessScope,
-        handler: (state: 'ready' | 'down') => void,
-      ) {
-        return rr.onReadyState(capName, scope, (t) => {
-          handler(t.state === 'ready' ? 'ready' : 'down')
-        })
-      },
-      addDisposer(fn: () => void | Promise<void>) {
-        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.
-   */
-  private readonly disposerChains = new Map<string, DisposerChain>()
-
-  private getOrCreateDisposerChain(addonId: string): DisposerChain {
-    let chain = this.disposerChains.get(addonId)
-    if (chain == null) {
-      const log = this.loggingService.createLogger().withTags({ addonId })
-      chain = new DisposerChain({
-        onError: (err, index) => {
-          log.error(`Disposer #${index} threw during teardown`, {
-            meta: { error: 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.
-   */
-  private async drainDisposerChain(addonId: string): Promise<void> {
-    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: readonly string[]): RunnerPlan {
-    const plan = new Map<string, RunnerAddonPlacement[]>()
-    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 = resolveAddonPlacement(entry.declaration)
-      if (placement === 'agent-only') continue
-      const runnerId = 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: string,
-    addons: readonly RunnerAddonPlacement[],
-  ): Promise<void> {
-    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: unknown) {
-      throw new Error(
-        `Failed to spawn runner "${runnerId}" (${addons.length} addons): ${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.
-   */
-  private async registerForkedAddonCustomActions(addonId: string, runnerId: string): Promise<void> {
-    // 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: unknown
-    try {
-      // Cache-bust so a hot-updated bundle is re-read instead of served
-      // from Node's ESM module cache.
-      const cacheBustedUrl = `${pathToFileURL(entryPath).href}?t=${Date.now()}`
-      const modUnknown: unknown = await import(cacheBustedUrl)
-      catalog =
-        modUnknown && typeof modUnknown === 'object'
-          ? (modUnknown as Record<string, unknown>)['customActions']
-          : undefined
-    } catch (err) {
-      this.logger.warn('Failed to load custom-action catalog for forked addon', {
-        tags: { addonId },
-        meta: { error: 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 as import('@camstack/types').CustomActionsSpec,
-      (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.
-   */
-  private async dispatchForkedCustomAction(
-    addonId: string,
-    action: string,
-    input: unknown,
-  ): Promise<unknown> {
-    return this.addonCallGateway.callForked(addonId, {
-      target: 'custom',
-      action,
-      args: input,
-    })
-  }
-}