@camstack/server 0.1.3

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

@@ -0,0 +1,2926 @@
+/* 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 { 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 } 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 { 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;
+}
+
+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;
+  // 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;
+
+  // 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;
+        }
+      },
+    );
+
+    // 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);
+    const settingsProvider = createAddonSettingsProvider({
+      getAddon: (addonId) => {
+        const entry = this.addonEntries.get(addonId);
+        return entry?.addon ?? null;
+      },
+      resolveNode: (addonId) => {
+        // Group-runner addons live in a child Moleculer node (e.g.
+        // `hub/pipeline`). The hub-side `entry.addon` instance never
+        // runs `initialize()` and has no `_ctx.settings`, so calling
+        // `addon.getGlobalSettings()` on it returns defaults only —
+        // the real store lives in the worker. Route those via the
+        // remote path so the worker's `<addonId>.settings.*` handler
+        // serves the canonical response.
+        const entry = this.addonEntries.get(addonId);
+        if (entry?.declaration && entry.addonDir) {
+          const runnerId = resolveRunnerId(entry.declaration, addonId);
+          return `${this.broker.nodeID}/${runnerId}`;
+        }
+        return "hub";
+      },
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment -- moleculer types unresolvable; see `broker` getter docstring
+      broker: this.moleculer.broker,
+      hubNodeId: this.broker.nodeID,
+    });
+    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 broker proxy that routes calls to
+    // `<addonId>.native-provider.<capName>.<method>` via standard Moleculer RPC.
+    //
+    // The resolver keys off `(capName, deviceId)`, NOT device ownership.
+    // An addon can own a device without registering every conceivable cap
+    // natively (e.g. RtspCamera without `snapshotUrl` does not publish a
+    // snapshot provider). Synthesizing a proxy against the device owner
+    // would point at a Moleculer service that was never mounted and make
+    // every call throw "service not found" at runtime.
+    //
+    // `resolveNativeCapOwnerSync` consults both hub-local native
+    // registrations and `remoteNativeCaps` (populated via
+    // DeviceBindingsChanged events emitted by every worker). It returns
+    // null when no provider published the cap for that device — the
+    // fallback surfaces that as null so wrappers cleanly fall through to
+    // whatever secondary strategy they own (e.g. snapshot → ffmpeg frame
+    // grab), instead of throwing against a phantom service.
+    {
+      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 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;
+          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;
+  }
+
+  /**
+   * 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,
+        // `shouldFork` already asserted `entry.declaration?.execution`.
+        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, {
+        kind: reg.kind,
+        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: it declares an
+   * `execution` block, ships an on-disk `addonDir`, and is not
+   * `agent-only`. Everything else (only `@camstack/core` builtins)
+   * boots in-process on the hub. The type predicate narrows `addonDir`
+   * to `string` for callers.
+   */
+  private isForkedAddonEntry(
+    entry: AddonEntry,
+  ): entry is AddonEntry & { addonDir: string } {
+    return !!(
+      entry.declaration?.execution &&
+      entry.addonDir &&
+      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: {
+            ...entry.addon.manifest!,
+            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;
+        }
+      },
+    );
+  }
+
+  /**
+   * Mount the `addon-routes` provider for `addonId` into the
+   * `AddonRouteRegistry`. Handles both co-located (in-process) and
+   * forked/group addons:
+   *
+   * - For a forked addon the provider is a Moleculer proxy whose
+   *   `getRoutes()` / `invoke()` return Promises and whose route
+   *   descriptors have their `handler` functions stripped by JSON
+   *   serialization. We `await getRoutes()`, synthesize bridge
+   *   handlers that dispatch through `provider.invoke(...)`, and
+   *   translate the captured envelope back onto the Fastify reply.
+   * - For a co-located 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) return;
+    const routeProvider = this.capabilityRegistry.getProviderByAddon(
+      "addon-routes",
+      addonId,
+    );
+    if (!routeProvider || !this.addonRouteRegistry) return;
+
+    // `getRoutes()` is synchronous on a co-located provider but
+    // returns a Promise on the Moleculer proxy of a forked addon —
+    // `await` normalizes both. If any route is missing its `handler`
+    // we synthesize one that dispatches via `provider.invoke(...)`
+    // and translates the captured envelope back to the Fastify reply.
+    const liveRoutes = await routeProvider.getRoutes()
+    const handlersMissing = liveRoutes.some((r: { handler?: unknown }) => typeof r.handler !== 'function')
+    if (handlersMissing) {
+      const invokeFn = (routeProvider as { invoke?: (input: unknown) => Promise<unknown> }).invoke
+      if (typeof invokeFn !== 'function') {
+        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 },
+        })
+      }
+      // Wrap each route with a bridge handler so the
+      // AddonRouteRegistry can dispatch through the worker.
+      const bridgeRoutes: import('@camstack/types').IAddonHttpRoute[] = (liveRoutes as ReadonlyArray<{ method: string; path: string; access?: string; description?: string }>).map((route) => ({
+        method: route.method as 'GET' | 'POST' | 'PUT' | 'DELETE',
+        path: route.path,
+        access: (route.access ?? 'public') as 'public' | 'authenticated' | 'admin',
+        ...(route.description !== undefined ? { description: route.description } : {}),
+        handler: async (req: { params: Record<string, string>; query: Record<string, string>; body: unknown; headers: Record<string, string>; user?: { id: string; username: string; isAdmin: boolean }; scopedToken?: unknown }, reply: { code: (n: number) => unknown; header: (k: string, v: string) => unknown; type: (m: string) => unknown; send: (data: unknown) => void; redirect: (url: string) => void }) => {
+          if (typeof invokeFn !== 'function') {
+            reply.code(500)
+            reply.send({ error: 'Forked addon-routes provider missing invoke' })
+            return
+          }
+          const envelope = await invokeFn({
+            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 ? { scopedToken: req.scopedToken } : {}),
+          }) as { status: number; headers: Record<string, string>; redirectUrl: string | null; body?: unknown; contentType?: string }
+          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)
+          }
+        },
+      }))
+      this.addonRouteRegistry.registerRoutes(
+        routeProvider.id,
+        { id: routeProvider.id, getRoutes: () => bridgeRoutes },
+      )
+      this.logger.info('Addon routes mounted (forked-bridge)', { meta: { phase: 'v2', routeProviderId: routeProvider.id, routes: bridgeRoutes.length } })
+    } else {
+      this.addonRouteRegistry.registerRoutes(
+        routeProvider.id,
+        routeProvider,
+      );
+      this.logger.info('Addon routes mounted', { meta: { phase: 'v2', routeProviderId: routeProvider.id } });
+    }
+  }
+
+  // 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,
+        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(),
+      },
+      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
+   * via `broker.call('<addonId>.custom.<action>')`, so the only divergence
+   * vs an in-process addon is the transport, exactly like cap methods.
+   *
+   * 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.broker.call(`${addonId}.custom.${action}`, input),
+    );
+    this.logger.info("Runner addon custom actions registered", {
+      tags: { addonId },
+      meta: { runnerId },
+    });
+  }
+}