@camstack/server 1.1.75 → 1.2.0

package/dist/agent/main.js

@@ -0,0 +1,1137 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startAgent = startAgent;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const agent_http_js_1 = require("./agent-http.js");
+const derive_hub_url_js_1 = require("./derive-hub-url.js");
+const system_1 = require("@camstack/system");
+const types_1 = require("@camstack/types");
+// Capability definitions — must be declared before addon registerProvider() calls
+const types_2 = require("@camstack/types");
+const agent_config_js_1 = require("./agent-config.js");
+const agent_update_service_js_1 = require("./agent-update-service.js");
+const server_management_provider_js_1 = require("../api/core/server-management.provider.js");
+const agent_service_js_1 = require("./agent-service.js");
+const agent_group_runner_js_1 = require("./agent-group-runner.js");
+const register_agent_cap_dispatch_js_1 = require("./register-agent-cap-dispatch.js");
+// ---------------------------------------------------------------------------
+// Agent LogManager — shared log pipeline for all addon loggers.
+// The hub-forwarder addon registers as a destination, so all log
+// entries flow through it (console output + hub forwarding).
+// ---------------------------------------------------------------------------
+const system_2 = require("@camstack/system");
+const agentLogManager = new system_2.LogManager(5000);
+/**
+ * Caps whose `nodeId` arg is provider DATA (`nodeIdMode: 'data'` —
+ * `addon-settings`, `addons`, `nodes`, `pipeline-orchestrator`), never a
+ * routing pin. The agent's own capabilityRegistry only declares the agent
+ * caps, so derive the set from the static cap definitions shipped in
+ * `@camstack/types`. Fed to `createParentUnownedCallHandler` so a forked
+ * addon on this agent calling e.g.
+ * `addon-settings.getGlobalSettings({addonId, nodeId})` forwards UNPINNED to
+ * the hub singleton (which reads `nodeId` as data) instead of being pinned to
+ * a node with no provider (dead broker fallback → ServiceNotFoundError).
+ */
+const DATA_NODEID_CAPS = new Set(types_2.ALL_CAPABILITY_DEFINITIONS.filter((c) => c.nodeIdMode === 'data').map((c) => c.name));
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+async function startAgent(configPath) {
+    const config = (0, agent_config_js_1.loadAgentConfig)(configPath);
+    // Derive CAMSTACK_HUB_URL from the configured hub address so remote agents
+    // no longer need a second, redundant env var set by hand (the cross-node
+    // source trap). An explicit operator value ALWAYS wins — capture whether it
+    // was set BEFORE deriving so reconnect() can still update a derived value.
+    // This runs before every runner spawn (loadClusterCapableAddons /
+    // loadDeployedAddons below), and process-service spreads `process.env` into
+    // child env, so pipeline-runner + recorder children inherit it for free.
+    const hubUrlWasExplicit = process.env['CAMSTACK_HUB_URL'] !== undefined;
+    const derivedHubUrl = (0, derive_hub_url_js_1.deriveHubUrlForExport)(hubUrlWasExplicit, config.hubAddress);
+    if (derivedHubUrl !== undefined) {
+        process.env['CAMSTACK_HUB_URL'] = derivedHubUrl;
+        console.log(`[Agent] Derived CAMSTACK_HUB_URL=${derivedHubUrl} from hub address "${config.hubAddress}"`);
+    }
+    if (config.hubAddress) {
+        console.log(`[Agent] Starting node "${config.nodeId}" (name="${config.name}") connecting to ${config.hubAddress}`);
+    }
+    else {
+        console.log(`[Agent] Starting node "${config.nodeId}" (name="${config.name}") in discovery mode`);
+    }
+    console.log(`[Agent] Config: ${config.configPath}`);
+    console.log(`[Agent] Data dir: ${config.dataDir}`);
+    // Ensure required addon packages are installed in the agent's addonsDir.
+    // Resolution order:
+    //   1. `CAMSTACK_BUNDLED_ADDONS_DIR` — Electron-packaged builds copy
+    //      from `<resourcesPath>/addons` (`'local'` mode).
+    //   2. Otherwise npm from registry. Local dev pushes addons via
+    //      `camstack deploy` (CLI tarball upload), bypassing this path.
+    const explicitSource = process.env['CAMSTACK_INSTALL_SOURCE'];
+    const bundledDir = process.env['CAMSTACK_BUNDLED_ADDONS_DIR'];
+    let workspaceDir = null;
+    let resolvedSource = explicitSource;
+    if (bundledDir && fs.existsSync(bundledDir)) {
+        workspaceDir = bundledDir;
+        resolvedSource = 'local';
+        console.log(`[Agent] Using bundled addons from ${bundledDir}`);
+    }
+    else if (explicitSource === 'local') {
+        workspaceDir = (0, system_1.detectWorkspacePackagesDir)(config.dataDir);
+    }
+    const installer = new system_1.AddonInstaller({
+        addonsDir: config.addonsDir,
+        workspacePackagesDir: workspaceDir ?? undefined,
+        installSource: resolvedSource,
+    });
+    await installer.ensureRequiredPackages(system_1.AddonInstaller.AGENT_PACKAGES);
+    console.log(`[Agent] Addon packages ready in ${config.addonsDir}`);
+    let broker = (0, system_1.createBroker)({
+        nodeID: config.nodeId,
+        mode: 'agent',
+        hubAddress: config.hubAddress,
+        logLevel: config.logLevel,
+        secret: config.secret,
+    });
+    /**
+     * Reconnect: stop the current broker, reload config from file,
+     * create a new broker with the updated hub/secret, and restart.
+     * The HTTP server stays alive throughout.
+     */
+    const reconnect = async () => {
+        console.log('[Agent] Reconnecting with updated config...');
+        try {
+            await broker.stop();
+        }
+        catch {
+            /* already stopped */
+        }
+        // Reload config from file (UI may have written new hubAddress/secret)
+        const fresh = (0, agent_config_js_1.loadAgentConfig)(undefined, config.dataDir);
+        console.log(`[Agent] New config: hub=${fresh.hubAddress ?? 'discovery'}, secret=${fresh.secret ? 'yes' : 'none'}`);
+        // Re-derive CAMSTACK_HUB_URL for the discovery-mode → dashboard-configured
+        // flow (config file freshly written a hubAddress). Explicit operator values
+        // still win via the boot-captured `hubUrlWasExplicit` flag.
+        // KNOWN LIMITATION (Stage-0): runners already spawned before this reconnect
+        // keep the env they inherited; picking up a changed hub address in live
+        // children would need a runner respawn. Boot-time — the actual trap — is
+        // fully covered.
+        const freshHubUrl = (0, derive_hub_url_js_1.deriveHubUrlForExport)(hubUrlWasExplicit, fresh.hubAddress);
+        if (freshHubUrl !== undefined && process.env['CAMSTACK_HUB_URL'] !== freshHubUrl) {
+            process.env['CAMSTACK_HUB_URL'] = freshHubUrl;
+            console.log(`[Agent] Derived CAMSTACK_HUB_URL=${freshHubUrl} from hub address "${fresh.hubAddress}"`);
+        }
+        broker = (0, system_1.createBroker)({
+            nodeID: config.nodeId,
+            mode: 'agent',
+            hubAddress: fresh.hubAddress,
+            logLevel: fresh.logLevel,
+            secret: fresh.secret,
+        });
+        await broker.start();
+        console.log('[Agent] Reconnected successfully');
+    };
+    const loadedAddons = new Map();
+    // D3 subtree registry: accumulates manifests from every group-runner child
+    // that calls `$agent.registerNode`. The agent re-registers the UNION of its
+    // own in-process addons + all children with the hub on every child update.
+    const subtree = new system_1.HubNodeRegistry();
+    // ---------------------------------------------------------------------------
+    // Hub connection state tracking (for richer UI status)
+    // ---------------------------------------------------------------------------
+    // Tracks the last known discriminated state so the HTTP status endpoint
+    // can surface `secret-mismatch` which is not observable from the broker
+    // registry alone. All mutations are synchronous/single-threaded (Node.js
+    // event loop) so no locking is needed.
+    let hubConnectionStateOverride = null;
+    function getHubConnectionState() {
+        // If a definitive override is set (e.g. secret-mismatch), return it
+        // regardless of registry state.
+        if (hubConnectionStateOverride !== null)
+            return hubConnectionStateOverride;
+        // Fall through to live registry-derived state (connected/searching/disconnected).
+        // getRegistryNodes-equivalent inline: broker.registry.getNodeList
+        try {
+            const registry = broker.registry;
+            const nodes = registry?.getNodeList?.({ onlyAvailable: true }) ?? [];
+            if (nodes.some((n) => n.id === 'hub'))
+                return 'connected';
+        }
+        catch {
+            /* fall through */
+        }
+        const configNow = readConfigFile(config.configPath);
+        const discoveryMode = typeof configNow.hubAddress !== 'string' || configNow.hubAddress.length === 0;
+        return discoveryMode ? 'searching' : 'disconnected';
+    }
+    function readConfigFile(p) {
+        if (!fs.existsSync(p))
+            return {};
+        try {
+            return JSON.parse(fs.readFileSync(p, 'utf-8'));
+        }
+        catch {
+            return {};
+        }
+    }
+    // AbortController for the upward hub registration retry loop — cancelled on
+    // agent shutdown so we don't leak the retry loop after stop().
+    const registerAbortController = new AbortController();
+    /**
+     * Build the manifest for the agent's OWN in-process addons (those loaded by
+     * bootCoreAddons and loadDeployedAddons that ended up in `loadedAddons` WITH
+     * an `addon` instance). Group-spawned addons (loadClusterCapableAddons) have
+     * no `addon` instance and register via `$agent.registerNode` from the child.
+     *
+     * We reconstruct per-addon capability lists by reverse-querying the
+     * capabilityRegistry: for every declared capability, check which addonId
+     * currently holds the provider and group the result by addonId.
+     */
+    function buildAgentOwnManifest() {
+        // Build addonId → capNames map from the registry.
+        const addonCapMap = new Map();
+        for (const cap of agentCapabilities) {
+            if (cap.mode === 'collection') {
+                // Collection caps: multiple providers keyed by addonId.
+                for (const [addonId] of capabilityRegistry.getCollectionEntries(cap.name)) {
+                    const list = addonCapMap.get(addonId) ?? [];
+                    list.push(cap.name);
+                    addonCapMap.set(addonId, list);
+                }
+            }
+            else {
+                // Singleton caps: one active provider.
+                const addonId = capabilityRegistry.getSingletonAddonId(cap.name);
+                if (addonId) {
+                    const list = addonCapMap.get(addonId) ?? [];
+                    list.push(cap.name);
+                    addonCapMap.set(addonId, list);
+                }
+            }
+        }
+        // Only emit in-process addons (those with an `addon` instance).
+        const result = [];
+        for (const [addonId, entry] of loadedAddons) {
+            if (!entry.addon)
+                continue;
+            const caps = addonCapMap.get(addonId) ?? [];
+            result.push({ addonId, capabilities: caps });
+        }
+        // The agent runtime's OWN providers (server-management) are registered by
+        // the bootstrap, not an addon — append their synthetic manifest entry so
+        // the hub's HubNodeRegistry (and nodeId-pinned cap routing) sees them.
+        result.push((0, agent_update_service_js_1.agentRuntimeManifestEntry)());
+        return result;
+    }
+    /**
+     * Aggregate the agent's own manifest + every child's manifest into a single
+     * RegisterNodeParams for the agent's nodeId. This is sent upward to the hub.
+     */
+    function aggregateManifest() {
+        const ownAddons = buildAgentOwnManifest();
+        const allAddons = [...ownAddons];
+        const allNativeCaps = [];
+        for (const childNodeId of subtree.listNodeIds()) {
+            const childAddons = subtree.getNodeManifest(childNodeId);
+            if (childAddons) {
+                allAddons.push(...childAddons);
+            }
+            const childNativeCaps = subtree.getNodeNativeCaps(childNodeId);
+            if (childNativeCaps) {
+                allNativeCaps.push(...childNativeCaps);
+            }
+        }
+        // Version visibility (runtime-updatable node packages): the manifest
+        // carries the agent's root-package identity so the hub's HubNodeRegistry
+        // (and the Server management UI) sees every node's exact version.
+        const rootPackage = agentUpdateService.getRunningRootPackage();
+        return (0, system_1.buildNodeManifest)(config.nodeId, allAddons, allNativeCaps.length > 0 ? allNativeCaps : undefined, config.secret ? (0, system_1.hashClusterSecret)(config.secret) : undefined, rootPackage.version === null
+            ? undefined
+            : { name: rootPackage.name, version: rootPackage.version });
+    }
+    /**
+     * Fire (or re-fire) the upward `$hub.registerNode` registration carrying
+     * the agent's complete subtree union. Called:
+     *   - after initial addon loading completes
+     *   - on every `$agent.registerNode` from a child
+     *   - on hub reconnect (via `$node.connected`)
+     */
+    function triggerUpwardRegistration() {
+        (0, system_1.callRegisterNodeWithRetry)(broker, aggregateManifest(), {
+            target: 'hub',
+            signal: registerAbortController.signal,
+            log: (msg) => console.log(`[Agent] ${msg}`),
+        })
+            .then(() => {
+            // The hub acked the manifest — the agent reached its registered state.
+            // Run the single-copy GC sweep once (first ack only; no-op after).
+            confirmAgentBootHealthy();
+        })
+            .catch((err) => {
+            if ((0, system_1.isClusterSecretMismatchError)(err)) {
+                consoleLogger.error('hub registration rejected: cluster secret mismatch — correct CAMSTACK_CLUSTER_SECRET and restart the agent');
+                // Surface the mismatch in the UI status.
+                hubConnectionStateOverride = 'secret-mismatch';
+                return;
+            }
+            // abort (shutdown) — preserve prior void behaviour: ignore.
+        });
+    }
+    const consoleLogger = {
+        info: (msg) => console.log(`[Agent] ${msg}`),
+        warn: (msg) => console.warn(`[Agent] ${msg}`),
+        error: (msg) => console.error(`[Agent] ${msg}`),
+        debug: (msg) => console.debug(`[Agent] ${msg}`),
+        child: () => consoleLogger,
+        withTags: () => consoleLogger,
+    };
+    const capabilityRegistry = new system_1.CapabilityRegistry(consoleLogger);
+    // Declare all capabilities the agent uses — required before registerProvider()
+    const agentCapabilities = [
+        types_2.storageCapability,
+        types_2.storageProviderCapability,
+        types_2.settingsStoreCapability,
+        types_2.logDestinationCapability,
+        types_2.metricsProviderCapability,
+        types_2.decoderCapability,
+        types_2.motionDetectionCapability,
+        types_2.pipelineExecutorCapability,
+        types_2.pipelineRunnerCapability,
+        types_2.audioAnalyzerCapability,
+        types_2.platformProbeCapability,
+        types_2.serverManagementCapability,
+    ];
+    for (const cap of agentCapabilities) {
+        capabilityRegistry.declareCapability(cap);
+    }
+    // ── Runtime-updatable root package ───────────────────────────────────
+    // The agent hosts its own `server-management` provider, backed by the
+    // update service that stages `@camstack/server` closures into
+    // `<dataDir>/server-root/`. Registered under the synthetic
+    // `agent-runtime` addonId (no addon owns it); `buildAgentOwnManifest`
+    // appends the matching manifest entry so the hub can route
+    // nodeId-pinned `server-management` calls here.
+    const agentUpdateService = new agent_update_service_js_1.AgentUpdateService({
+        logger: consoleLogger,
+        dataDir: config.dataDir,
+    });
+    capabilityRegistry.registerProvider('server-management', agent_update_service_js_1.AGENT_RUNTIME_ADDON_ID, (0, server_management_provider_js_1.buildServerManagementProvider)(agentUpdateService));
+    // Boot-health confirmation: on the agent's FIRST acked `$hub.registerNode`,
+    // run the single-copy GC sweep once. Under the single-copy model there is NO
+    // probation boot, NO N-1 promotion, and NO auto-rollback — the starter
+    // already swapped the one `current/` copy in place, so `confirmBootHealthy`
+    // is a pure best-effort sweep of orphaned transient dirs. Idempotent: it
+    // runs at most once per boot.
+    let agentBootConfirmed = false;
+    const confirmAgentBootHealthy = () => {
+        if (agentBootConfirmed)
+            return;
+        agentBootConfirmed = true;
+        try {
+            agentUpdateService.confirmBootHealthy();
+        }
+        catch (err) {
+            consoleLogger.warn(`agent root boot confirmation failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    };
+    // Logger factory — creates scoped loggers from the shared LogManager.
+    // All entries flow through registered ILogDestination providers (hub-forwarder).
+    // No scope — the brand bracket `[agent/addonId]` already identifies the addon.
+    // `addonId` tag is required for the brand bracket resolver.
+    const loggerFactory = (addonId) => agentLogManager.createLogger().withTags({ addonId });
+    const agentServiceSchema = (0, agent_service_js_1.createAgentService)({
+        addonsDir: config.addonsDir,
+        dataDir: config.dataDir,
+        agentName: config.name,
+        configPath: config.configPath,
+        loadedAddons,
+        // Resolve the current metrics-provider cap lazily from the registry.
+        // The cap is registered during bootCoreAddons but may not exist in test
+        // scenarios — `null` is a documented fallback for both.
+        getMetricsProvider: () => capabilityRegistry.getSingleton('metrics-provider'),
+        agentVersion: readAgentVersion(),
+        // Drives `$agent.reload` — re-runs the same discovery pass the bootstrap
+        // does at startup, picking up tarballs just landed via `$agent.deploy`.
+        // `storageProvider` is resolved lazily on each call because this closure
+        // is captured here, BEFORE `bootCoreAddons` registers the storage cap.
+        reloadDeployedAddons: async () => {
+            const before = new Set(loadedAddons.keys());
+            const storage = capabilityRegistry.getSingleton('storage') ?? undefined;
+            await loadDeployedAddons(broker, config.addonsDir, config.dataDir, loadedAddons, storage, loggerFactory, capabilityRegistry);
+            const loaded = [];
+            for (const id of loadedAddons.keys()) {
+                if (!before.has(id))
+                    loaded.push(id);
+            }
+            return loaded;
+        },
+        // D3 subtree aggregation: when a group-runner child delivers its manifest
+        // via `$agent.registerNode`, merge it into the local subtree registry and
+        // immediately re-register the complete union with the hub.
+        onChildRegistered: (params) => {
+            subtree.registerNode(params);
+            triggerUpwardRegistration();
+        },
+        expectedClusterSecretHash: config.secret ? (0, system_1.hashClusterSecret)(config.secret) : undefined,
+        installFromNpm: async (pkg, version) => {
+            await installer.install(pkg, version);
+        },
+        // #17: deployed bundles go through the installer's full post-install
+        // (manifest strip + runtime deps + native deps + atomic swap) instead of
+        // the bare tar swap that shipped addons without their node_modules.
+        installBundleTgz: (tgzPath) => installer.installFromTgz(tgzPath),
+    });
+    broker.createService(agentServiceSchema);
+    // $process service — manages forked child processes (same as hub).
+    // Pass the agent's own TCP listen port so spawned addon-runners connect
+    // back here instead of falling back to port 6000 (the hub). Bug-4:
+    // without this, runners called `$agent.registerNode` through the hub
+    // which has no `$agent` service → retry storm (attempt 80+).
+    const agentTcpPort = (0, system_1.deriveAgentListenPort)(broker.nodeID);
+    // UDS local transport — the agent hosts a LocalChildRegistry so its
+    // forked addon-runners route cap calls over a Unix-domain socket. The
+    // broker stays as the no-route fallback. On failure the children fall
+    // back to broker-only (no parentUdsPath propagated). See moleculer.service.ts.
+    let agentParentUdsPath;
+    let agentUdsRegistry;
+    try {
+        const agentNodeId = broker.nodeID;
+        // F0 (slice-5 outbound): route a forked child's unowned `ctx.api.<cap>`
+        // call from the agent (the parent) instead of throwing UDS_NO_ROUTE. The
+        // agent has NO CapRouteResolver — it routes everything to the hub over its
+        // own broker — so `getResolver` returns null and the handler uses the
+        // broker fallback exclusively. The agent's `broker.call` reaches the hub
+        // mesh (and any cluster node) via the same service-discovery + action-name
+        // convention the child's brokerTransportLink used before F0. F1+F2 removes
+        // the child broker, so the agent must own this outbound path.
+        const onUnownedCall = (0, system_1.createParentUnownedCallHandler)({
+            getResolver: () => null,
+            broker: broker,
+            // The agent's subtree registry — lets the broker fallback pin a
+            // device-scoped child call to the owning node instead of load-balancing.
+            nodeRegistry: subtree,
+            // Hub-local UDS child dispatcher — routes a device-scoped native cap
+            // owned by an agent-local child directly over UDS before any broker
+            // fallback. Getter: `agentUdsRegistry` is assigned later in this scope,
+            // after the handler is constructed.
+            getLocalDispatcher: () => agentUdsRegistry ?? null,
+            // `nodeIdMode: 'data'` signal: these caps carry `nodeId` as provider
+            // DATA (the hub singleton dispatches internally), never a routing pin —
+            // suppressing the pin lets the call forward unpinned to the hub's
+            // singleton resolution, with `args.nodeId` intact for the provider.
+            isDataNodeIdCap: (capName) => DATA_NODEID_CAPS.has(capName),
+            // AGENT → HUB forward: a cap no agent-local child owns is routed to the
+            // hub's `$hub-cap-fwd.forward`, which runs it through the hub's own
+            // routing. Only the hub registers `$hub-cap-fwd`, so the undirected
+            // `broker.call` discovers it there (no nodeID pin needed). This is what
+            // makes an agent's forked addon reach a hub-hosted cap (`stream-broker`,
+            // `settings-store`, …) instead of 30s-deadlining on raw `${cap}.*`
+            // discovery (hub-local addon runners expose no Moleculer service).
+            forwardToHub: (input) => broker.call(system_1.HUB_CAP_FWD_ACTION, {
+                capName: input.capName,
+                method: input.method,
+                args: input.args,
+                ...(input.deviceId !== undefined ? { deviceId: input.deviceId } : {}),
+                ...(input.nodeId !== undefined ? { nodeId: input.nodeId } : {}),
+            }, { timeout: 60_000 }),
+            logger: { warn: (msg) => consoleLogger.warn(`[uds-fallback] ${msg}`) },
+        });
+        agentUdsRegistry = new system_1.LocalChildRegistry({
+            server: (0, system_1.createLocalTransport)().createServer(agentNodeId),
+            // The agent's own id — a cap call pinned to THIS agent (e.g. the
+            // benchmark running `pipeline-executor.runPipeline` on the very node it
+            // is on) is served by the co-resident sibling instead of being forwarded
+            // to the hub (the agent has no CapRouteResolver, and the hub would reject
+            // it with "no provider registered" unless it knew the agent hosts the
+            // cap). A pin to ANOTHER node still bypasses the sibling → onUnownedCall.
+            ownNodeId: agentNodeId,
+            onUnownedCall,
+        });
+        await agentUdsRegistry.start();
+        // E1: apply child manifest + cleanup from the UDS lifecycle (agent-local children).
+        // When a runner connects over UDS, synthesise a RegisterNodeParams for the
+        // agent's subtree and trigger upward hub registration — same effect as the
+        // `$agent.registerNode` Moleculer RPC path. Idempotent: if the Moleculer path
+        // fires first, the subtree's atomic-replace handles the re-registration safely.
+        agentUdsRegistry.onChildRegistered((child) => {
+            const childNodeId = `${agentNodeId}/${child.childId}`;
+            const childParams = buildAgentChildUdsManifest(childNodeId, child.childId, child.caps);
+            subtree.registerNode(childParams);
+            triggerUpwardRegistration();
+            consoleLogger.info(`UDS child registered — subtree updated: ${childNodeId}`);
+        });
+        agentUdsRegistry.onChildGone((childId) => {
+            const childNodeId = `${agentNodeId}/${childId}`;
+            subtree.removeNode(childNodeId);
+            triggerUpwardRegistration();
+            consoleLogger.info(`UDS child gone — subtree updated: ${childNodeId}`);
+        });
+        // B2: forward UDS child logs onward to the hub's log-receiver service so
+        // they appear in the hub LogManager / admin-UI log stream.
+        //
+        // The agent has NO local LogManager readable by the admin-UI — all log
+        // entries must reach the hub. We re-use the same `log-receiver.ingest`
+        // Moleculer call that `HubForwarderDestination` uses for the agent's OWN
+        // logs, but preserve the child's original `addonId`/`nodeId`/`tags` so
+        // the admin-UI shows the originating addon (not the agent's identity).
+        //
+        // If the hub is not yet reachable, the call silently fails — the same
+        // best-effort semantic as `HubForwarderDestination.forward`. Phase F will
+        // retire the broker path once every log source emits over UDS end-to-end.
+        agentUdsRegistry.onChildLog((childId, entry) => {
+            const workerEntry = (0, system_1.udsChildLogToWorkerEntry)(childId, entry);
+            broker.call('log-receiver.ingest', workerEntry).catch(() => {
+                // Hub unreachable or not yet discovered — silently drop.
+                // HubForwarderDestination handles the agent's own buffered logs;
+                // child UDS logs emitted before hub connection are not buffered here.
+            });
+        });
+        agentParentUdsPath = (0, system_1.localEndpointPath)(agentNodeId);
+        consoleLogger.info(`UDS child registry listening on ${agentParentUdsPath}`);
+    }
+    catch (err) {
+        consoleLogger.warn(`UDS child registry failed to start; children stay broker-only: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const processServiceSchema = (0, system_1.createProcessService)(broker.nodeID, config.dataDir, undefined, agentTcpPort, agentParentUdsPath);
+    broker.createService(processServiceSchema);
+    // Slice-5, Task 7 — register the agent-side cap-dispatch service so the hub
+    // can route `agent-child-forward` cap calls to this agent's UDS children.
+    // Registered only when the UDS child registry started successfully; if it
+    // didn't start the service would have nothing to forward to.
+    //
+    // Caps hosted in the agent's OWN main process — core addons such as
+    // `platform-probe` and `metrics-provider` register singleton providers in
+    // `capabilityRegistry`, NOT as forked UDS children — are exposed via this
+    // in-process lookup so hub-dispatched `agent-child-forward` calls resolve to
+    // them instead of failing with "no provider". Mirrors the hub's
+    // `createInProcessProviderLookup`.
+    const agentInProcessLookup = (capName) => {
+        const provider = capabilityRegistry.getSingleton(capName);
+        if (provider === null || provider === undefined)
+            return null;
+        return {
+            invoke: (method, args) => {
+                const fn = provider[method];
+                if (typeof fn !== 'function') {
+                    return Promise.reject(new Error(`method "${method}" not found on cap "${capName}"`));
+                }
+                const result = fn.call(provider, args);
+                return Promise.resolve(result);
+            },
+        };
+    };
+    (0, register_agent_cap_dispatch_js_1.registerAgentCapDispatch)(broker, agentUdsRegistry, agentInProcessLookup, consoleLogger);
+    // $addonHost — REMOVED (Sprint 6). Three-level settings are now
+    // exposed per-addon via `settings.*` actions in createAddonService.
+    // Register $event-bus BEFORE start so the service subscription
+    // is announced during discovery. See addon-context-factory.ts for
+    // the rationale — post-start registration propagates via heartbeat
+    // and is unreliable for the first ~10s.
+    (0, system_1.registerEventBusService)(broker);
+    // Start broker BEFORE bootCoreAddons. Core infra addons (storage,
+    // sqlite-settings, ...) run their own BaseAddon.initialize() which
+    // calls `ctx.settings.readAddonStore()` on every addon; that call
+    // routes through `brokerTransportLink` and would deadline-free poll
+    // for the hub's `settings-store.get` service if the broker weren't
+    // connected to the mesh yet. Starting the broker first lets service
+    // discovery resolve (or time out cleanly via the read-blob fallback)
+    // so agent boot completes instead of hanging on the first infra addon.
+    await broker.start();
+    // ── Registry-derived CAMSTACK_HUB_URL (Option A — discovery-mode fallback) ──
+    // In UDP-discovery mode `config.hubAddress` is null, so the boot-time
+    // derivation above (Option B) produced nothing. The agent parent is the only
+    // agent-side process with a Moleculer registry (addon-runner children are
+    // broker-less), so derive the hub host from the LIVE hub connection —
+    // `udpAddress` is wire truth — and export it through the same env contract
+    // before the runner spawns in loadClusterCapableAddons below.
+    // Precedence: explicit operator env > config-derived (B) > registry (A).
+    // A fills only the empty case; on later hub (re)connects it refreshes only
+    // its OWN previous value (hub IP change), never an explicit or B-derived one.
+    // BOOT-ORDER LIMITATION (Stage-0): a runner spawned before the first hub
+    // connect in discovery mode inherits an empty env until it is respawned —
+    // same class as Option B's reconnect limitation documented above. The first
+    // hub connect normally precedes any orchestrator attach dispatch, but the
+    // child env snapshot is fixed at spawn time.
+    let hubUrlFromRegistry;
+    const reconcileHubUrlFromRegistry = () => {
+        if (hubUrlWasExplicit)
+            return;
+        const current = process.env['CAMSTACK_HUB_URL'];
+        if (current !== undefined && current !== hubUrlFromRegistry)
+            return;
+        const fromRegistry = (0, derive_hub_url_js_1.deriveHubUrlFromRegistry)((0, agent_http_js_1.getRegistryNodes)(broker));
+        if (fromRegistry === undefined || fromRegistry === current)
+            return;
+        process.env['CAMSTACK_HUB_URL'] = fromRegistry;
+        hubUrlFromRegistry = fromRegistry;
+        console.log(`[Agent] Derived CAMSTACK_HUB_URL=${fromRegistry} from live hub connection`);
+    };
+    // Immediate attempt (the hub may already be in the registry), then reconcile
+    // on every hub (re)connect via the `$node.connected` localBus idiom — NO
+    // timers, NO registry polling (CLAUDE.md invariant).
+    reconcileHubUrlFromRegistry();
+    broker.localBus.on('$node.connected', (data) => {
+        const node = data.node;
+        if (node?.id !== 'hub')
+            return;
+        reconcileHubUrlFromRegistry();
+    });
+    // C2: wire the UDS ↔ Moleculer event bridge so events emitted by UDS
+    // children fan to siblings and reach the cluster, and cluster / parent-
+    // local events propagate to every UDS child. Inert when agentUdsRegistry
+    // was not started (no UDS children). Wired after broker.start() so
+    // getBrokerEventBus returns the fully operational shared bus.
+    let udsEventBridgeDispose = null;
+    if (agentUdsRegistry !== undefined) {
+        const agentBrokerEventBus = (0, system_1.getBrokerEventBus)(broker);
+        udsEventBridgeDispose = (0, system_1.createUdsEventBridge)({
+            registry: agentUdsRegistry,
+            parentBus: agentBrokerEventBus,
+            parentNodeId: broker.nodeID,
+            // D2: relay to children via the pass-through subscription so the bridge's
+            // wildcard does NOT count toward this node's local interest (otherwise the
+            // gate could never filter anything).
+            subscribePassthrough: (handler) => (0, system_1.subscribePassthrough)(broker, handler),
+        });
+        // D2: teach the agent's `$event-bus` inbound handler which cross-node
+        // (Moleculer) event categories any of its UDS children actually want, so the
+        // agent drops hub-origin categories no local subscriber cares about instead
+        // of fanning every category into its bus. Read per-event, so a child
+        // (un)subscribing takes effect immediately. Fails OPEN when a child is
+        // undeclared (aggregateEventInterest → null). Gated by
+        // CAMSTACK_MOLECULER_EVENT_FANOUT (filter|shadow|broadcast).
+        const interestRegistry = agentUdsRegistry;
+        (0, system_1.setNodeEventInterest)(broker, () => interestRegistry.aggregateEventInterest());
+        // D1: answer readiness-snapshot requests from UDS children over the
+        // agent's own readiness registry view. The agent hydrates its registry
+        // from the hub's `$readiness.getSnapshot` Moleculer action (broker
+        // path, intact until Phase F) — its snapshot reflects the hub's
+        // authoritative view plus any agent-local readiness events. Children
+        // request the snapshot over UDS without an additional Moleculer hop.
+        // `getOrInitReadinessRegistry` is the same function addon-context-factory
+        // uses, so the shared per-broker instance is returned on the first call
+        // and reused on subsequent calls — no separate registry is created.
+        // Wired after broker.start() so the broker event bus is operational.
+        const agentReadinessRegistry = (0, system_1.getOrInitReadinessRegistry)(broker, agentBrokerEventBus, consoleLogger);
+        agentUdsRegistry.onReadinessSnapshotRequest(() => agentReadinessRegistry.getSnapshotForTransport());
+        broker.createService((0, system_1.createReadinessServiceForRegistry)(agentReadinessRegistry, system_1.AGENT_READINESS_SERVICE_NAME));
+    }
+    // ── HTTP server (Fastify) — status API + process management + UI ──
+    // Started early (before addon boot) so the status page is reachable
+    // even while addons are still loading.
+    const getBrokerFn = (() => broker);
+    void (0, agent_http_js_1.startAgentHttpServer)(getBrokerFn, {
+        port: config.statusPort ?? 4444,
+        nodeId: config.nodeId,
+        dataDir: config.dataDir,
+        configPath: config.configPath,
+        onReconnect: reconnect,
+        getHubConnectionState,
+    });
+    // ── Phase 1: Load core infrastructure addons (in-process) ──
+    // storage + settings + metrics + hub-forwarder (log destination)
+    await bootCoreAddons(broker, config, capabilityRegistry, loadedAddons, loggerFactory);
+    // Plug every registered `log-destination` provider into the shared
+    // LogManager. The LogManager replays its ring buffer to each destination
+    // on registration, so boot-time log entries still reach destinations that
+    // came up mid-boot (e.g. hub-forwarder arriving after the first logs).
+    for (const dest of capabilityRegistry.getCollection('log-destination')) {
+        agentLogManager.addDestination(dest);
+    }
+    // Everything downstream reads the resolved infra providers from the
+    // capability registry — no hand-curated side-channel.
+    const storageProvider = capabilityRegistry.getSingleton('storage') ?? undefined;
+    // `ctx.api` for every addon is built inside `createAddonContext` from
+    // `[localProviderLink, brokerTransportLink(broker)]`. Unresolved calls
+    // route via Moleculer to the hub (or any other node hosting the cap).
+    // No separate hub WSS client, no `CAMSTACK_HUB_API_URL` — all cross-node
+    // traffic rides the broker mesh.
+    // ── Phase 1.5: Load cluster-capable addon packages (forkable → child process) ──
+    await loadClusterCapableAddons(broker, config, capabilityRegistry, loadedAddons);
+    // ── Phase 2: Load deployed addons (from hub $agent.deploy) ──
+    await loadDeployedAddons(broker, config.addonsDir, config.dataDir, loadedAddons, storageProvider, loggerFactory, capabilityRegistry);
+    // ── D3: Fire the initial upward hub registration carrying the agent's
+    // complete in-process manifest (+ any children that already registered).
+    // Group-runner children call `$agent.registerNode` and trigger a re-fire
+    // via `onChildRegistered`; hub reconnects re-fire via `$node.connected`.
+    triggerUpwardRegistration();
+    // Fire `onHubReachable()` on every in-process addon as soon as the hub
+    // node connects to our broker — this is the safe point for ctx.api.* calls
+    // into hub-provided capabilities. Forked children get the same hook via
+    // `process-runner.ts`.
+    let hubReachableFired = false;
+    broker.localBus.on('$node.connected', (data) => {
+        const node = data.node;
+        if (node?.id !== 'hub')
+            return;
+        // Hub connected — clear any stale secret-mismatch override so the
+        // status endpoint reflects the live state again.
+        if (hubConnectionStateOverride === 'secret-mismatch') {
+            hubConnectionStateOverride = null;
+        }
+        // Re-register with the hub on reconnect — the hub may have restarted and
+        // lost the agent's manifest. D3 idempotent-replace: safe to re-fire.
+        triggerUpwardRegistration();
+        if (hubReachableFired)
+            return;
+        hubReachableFired = true;
+        for (const [, entry] of loadedAddons) {
+            if (!entry.addon || typeof entry.addon.onHubReachable !== 'function')
+                continue;
+            Promise.resolve(entry.addon.onHubReachable()).catch((err) => {
+                console.error(`[Agent] ${entry.id} onHubReachable() threw:`, err);
+            });
+        }
+    });
+    console.log(`[Agent] Node "${config.nodeId}" (name="${config.name}") ready — ${loadedAddons.size} addon(s) loaded`);
+    // Graceful shutdown
+    const shutdown = async () => {
+        console.log('[Agent] Shutting down...');
+        // Abort any in-flight upward hub registration retry loop.
+        registerAbortController.abort();
+        // Dispose the UDS event bridge to remove the parent-bus subscriber and
+        // clear the child-event handler, preventing subscriber leaks on shutdown.
+        udsEventBridgeDispose?.();
+        udsEventBridgeDispose = null;
+        for (const [, entry] of loadedAddons) {
+            if (entry.addon?.shutdown) {
+                try {
+                    await entry.addon.shutdown();
+                }
+                catch {
+                    /* */
+                }
+            }
+        }
+        await broker.stop();
+        process.exit(0);
+    };
+    process.on('SIGTERM', shutdown);
+    process.on('SIGINT', shutdown);
+}
+// ---------------------------------------------------------------------------
+// Phase 1: Boot core addons (storage, settings, metrics — NO winston)
+// ---------------------------------------------------------------------------
+// Core infra addons to load on agent — all infra including log-destination (hub-forwarder)
+const AGENT_INFRA = system_1.INFRA_CAPABILITIES;
+async function bootCoreAddons(broker, config, registry, loadedAddons, loggerFactory) {
+    // Scan every installed addon package — infra providers may live outside
+    // `@camstack/system` (e.g. `@camstack/addon-platform-probe-native`).
+    const packageDirs = resolveAddonPackageDirs(config.addonsDir);
+    if (packageDirs.length === 0) {
+        console.warn('[Agent] No addon packages found — running without infrastructure addons');
+        return;
+    }
+    console.log(`[Agent] Scanning ${packageDirs.length} addon package(s) for infra providers`);
+    const loader = new system_1.AddonLoader();
+    for (const dir of packageDirs) {
+        try {
+            await loader.loadFromAddonDir(dir);
+        }
+        catch (err) {
+            console.warn(`[Agent] Failed to scan ${dir}: ${(0, types_2.errMsg)(err)}`);
+        }
+    }
+    for (const infra of AGENT_INFRA) {
+        const candidates = loader.listAddons().filter((a) => a.declaration.capabilities?.some((c) => {
+            const capName = typeof c === 'string' ? c : c.name;
+            return capName === infra.name;
+        }));
+        // For log-destination, prefer hub-forwarder over winston-logging
+        const addon = infra.name === 'log-destination'
+            ? (candidates.find((a) => a.declaration.id === 'hub-forwarder') ?? candidates[0])
+            : candidates[0];
+        if (!addon) {
+            if (infra.required) {
+                console.error(`[Agent] Required infrastructure addon for "${infra.name}" not found`);
+            }
+            continue;
+        }
+        const addonId = addon.declaration.id;
+        try {
+            const instance = new addon.addonClass();
+            // Seed ctx.kernel.storage from whatever storage provider is already
+            // in the registry (the storage addon declares itself before the
+            // addons that depend on it per AGENT_INFRA order).
+            const storageProvider = registry.getSingleton('storage') ?? undefined;
+            const context = await (0, system_1.createAddonContext)(broker, addon.declaration, config.dataDir, {
+                storageProvider,
+                addonConfig: { rootPath: config.dataDir },
+                createLogger: loggerFactory,
+                capabilityRegistry: registry,
+                // Feed the storage-orchestrator its first-boot seed declarations
+                // (addons-data:default, models:default, …). Without this the agent's
+                // sqlite-settings aborts boot: "No default storage location
+                // configured for type addons-data" → fatal crash-loop.
+                listStorageLocationDeclarations: () => loader.listStorageLocationDeclarations(),
+            });
+            const initResult = (0, types_1.normalizeAddonInitResult)(await instance.initialize(context));
+            for (const reg of initResult?.providers ?? []) {
+                const capName = reg.capability.name;
+                registry.registerProvider(capName, addonId, reg.provider);
+                // Also register in the per-broker context registry
+                context.registerProvider(capName, reg.provider);
+            }
+            loadedAddons.set(addonId, {
+                id: addonId,
+                status: 'running',
+                version: addon.declaration.version,
+                packageName: addon.packageName,
+                packageVersion: addon.packageVersion,
+                addon: instance,
+            });
+            console.log(`[Agent] Core addon "${addonId}" initialized`);
+        }
+        catch (err) {
+            const msg = (0, types_2.errMsg)(err);
+            console.error(`[Agent] Failed to initialize core addon "${addonId}": ${msg}`);
+            if (infra.required) {
+                throw new Error(`Required infrastructure addon "${addonId}" failed: ${msg}`, { cause: err });
+            }
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Phase 1.5: Load cluster-capable addon packages
+// ---------------------------------------------------------------------------
+async function loadClusterCapableAddons(broker, config, capabilityRegistry, loadedAddons) {
+    const addonPackageDirs = resolveAddonPackageDirs(config.addonsDir);
+    if (addonPackageDirs.length === 0)
+        return;
+    // ── Phase 0 (cross-package): collect every group-eligible addon
+    //     across ALL package dirs FIRST so we issue exactly one
+    //     `$process.spawnGroup` per group. Doing this inside the per-dir
+    //     loop spawned the same group multiple times — Moleculer rejected
+    //     subsequent attempts with "already running" and the surviving
+    //     subprocess only had the first dir's subset of addons.
+    const allGroupCandidates = [];
+    // Loaders are reused below for the per-addon legacy path; cache them
+    // so each dir is parsed once.
+    const dirToLoader = new Map();
+    for (const dir of addonPackageDirs) {
+        const loader = new system_1.AddonLoader();
+        try {
+            await loader.loadFromAddonDir(dir);
+        }
+        catch (err) {
+            console.warn(`[Agent] Skipping ${dir}: ${(0, types_2.errMsg)(err)}`);
+            continue;
+        }
+        dirToLoader.set(dir, loader);
+        for (const registered of loader.listAddons()) {
+            if (loadedAddons.has(registered.declaration.id))
+                continue;
+            if (registered.declaration.execution === undefined)
+                continue;
+            const placement = (0, types_1.resolveAddonPlacement)(registered.declaration);
+            if (placement === 'hub-only')
+                continue;
+            allGroupCandidates.push({
+                groupId: (0, types_1.resolveRunnerId)(registered.declaration, registered.declaration.id),
+                addonId: registered.declaration.id,
+                addonDir: dir,
+                version: registered.declaration.version ?? '0.0.0',
+                packageName: registered.packageName,
+                packageVersion: registered.packageVersion,
+                capabilities: registered.declaration.capabilities ?? [],
+            });
+        }
+    }
+    if (allGroupCandidates.length > 0) {
+        const grouped = new Map();
+        for (const c of allGroupCandidates) {
+            const arr = grouped.get(c.groupId) ?? [];
+            arr.push(c);
+            grouped.set(c.groupId, arr);
+        }
+        for (const [groupId, addons] of grouped) {
+            try {
+                await broker.call('$process.spawnRunner', {
+                    runnerId: groupId,
+                    addons: addons.map((a) => ({ addonId: a.addonId, addonDir: a.addonDir })),
+                });
+                // Shared with the reload path (`ensureGroupRunner`) so the boot and
+                // reload registrations can never drift — the drift was the in-process
+                // reload-wedge's root cause.
+                (0, agent_group_runner_js_1.registerGroupRunnerProviders)({ broker, capabilityRegistry, loadedAddons }, addons);
+                console.log(`[Agent] Group "${groupId}" spawned with ${addons.length} addon(s): ${addons.map((a) => a.addonId).join(', ')}`);
+            }
+            catch (err) {
+                const msg = err instanceof Error ? (err.stack ?? err.message) : String(err);
+                console.error(`[Agent] Failed to spawn group "${groupId}": ${msg}`);
+                for (const a of addons) {
+                    loadedAddons.set(a.addonId, { id: a.addonId, status: 'error' });
+                }
+            }
+        }
+    }
+    // Diagnostic — list addons that exist in the agent's package dir but
+    // were filtered out by Phase 0 (placement=hub-only or no execution).
+    for (const dir of addonPackageDirs) {
+        const loader = dirToLoader.get(dir);
+        if (!loader)
+            continue;
+        for (const registered of loader.listAddons()) {
+            const addonId = registered.declaration.id;
+            if (loadedAddons.has(addonId))
+                continue;
+            if (!(0, types_1.isDeployableToAgent)(registered.declaration))
+                continue;
+            console.warn(`[Agent] Addon "${addonId}" is deployable but missing from any spawned group — verify package.json execution field`);
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Phase 2: Load deployed addons (pushed from hub via $agent.deploy)
+// ---------------------------------------------------------------------------
+async function loadDeployedAddons(broker, addonsDir, dataDir, loadedAddons, storageProvider, loggerFactory, capabilityRegistry) {
+    if (!fs.existsSync(addonsDir))
+        return;
+    // Discover deployable addons by reading each package's MANIFEST
+    // (package.json `camstack.addons[]`) — NOT by importing the entry module.
+    // Importing heavy native addon entries (node-av / onnxruntime bridge / …) on
+    // the agent MAIN thread is what wedged `$agent.reload` and dropped the node
+    // from topology. A group-runner addon only needs its declaration to be
+    // (re)dispatched to a subprocess, which loads the real module itself.
+    const packageDirs = resolveAddonPackageDirs(addonsDir);
+    const groupCandidates = [];
+    // Dirs holding a deployable NON-group addon — and ONLY these — need the
+    // importing loader. None exist under the default `hub-only` placement
+    // (deployable ⟹ cluster-capable), so the heavy import path is never taken.
+    const inProcessDirs = new Set();
+    for (const dir of packageDirs) {
+        const manifest = (0, agent_group_runner_js_1.readPackageManifestAddons)(dir);
+        if (!manifest)
+            continue;
+        for (const decl of manifest.declarations) {
+            const addonId = decl.id;
+            if (loadedAddons.has(addonId))
+                continue;
+            if (!(0, types_1.isDeployableToAgent)(decl))
+                continue;
+            if ((0, agent_group_runner_js_1.isGroupRunnerAddon)(decl)) {
+                groupCandidates.push({
+                    groupId: (0, types_1.resolveRunnerId)(decl, addonId),
+                    addonId,
+                    addonDir: dir,
+                    version: decl.version ?? '0.0.0',
+                    packageName: manifest.packageName,
+                    packageVersion: manifest.packageVersion,
+                    capabilities: decl.capabilities ?? [],
+                });
+            }
+            else {
+                inProcessDirs.add(dir);
+            }
+        }
+    }
+    // Rare in-process fallback (imports lazily, per-dir, only when such an addon
+    // actually exists — never under the current placement model).
+    if (inProcessDirs.size > 0) {
+        await loadInProcessDeployedAddons(broker, [...inProcessDirs], dataDir, loadedAddons, storageProvider, loggerFactory, capabilityRegistry);
+    }
+    // (Re)spawn each cluster-capable group runner with the current on-disk code —
+    // no module import on the main thread.
+    if (groupCandidates.length === 0)
+        return;
+    if (!capabilityRegistry) {
+        console.warn(`[Agent] ${groupCandidates.length} deployed group addon(s) skipped — no capabilityRegistry passed`);
+        return;
+    }
+    const grouped = new Map();
+    for (const c of groupCandidates) {
+        const arr = grouped.get(c.groupId) ?? [];
+        arr.push(c);
+        grouped.set(c.groupId, arr);
+    }
+    const deployLogger = loggerFactory('agent-group-runner');
+    for (const [groupId, addons] of grouped) {
+        await (0, agent_group_runner_js_1.ensureGroupRunner)({ broker, capabilityRegistry, loadedAddons, logger: deployLogger }, groupId, addons);
+    }
+}
+/**
+ * In-process loader path for deployable NON-group addons (rare). Uses the
+ * importing `AddonLoader` — invoked lazily, per-dir, ONLY when such an addon
+ * exists. Group-runner addons never reach here, so heavy native modules are
+ * never imported on the agent main thread during a reload.
+ */
+async function loadInProcessDeployedAddons(broker, dirs, dataDir, loadedAddons, storageProvider, loggerFactory, capabilityRegistry) {
+    // Node-local models dir — anchored at this node's data root (CAMSTACK_DATA ??
+    // the agent --data dir), never the hub-singleton `storage` cap. Mirrors
+    // BaseAddon.resolveModelsDir so addons that read the hint and those that
+    // self-resolve agree on one path.
+    const modelsDir = path.join(process.env['CAMSTACK_DATA'] ?? dataDir, 'models');
+    const contextOptions = {
+        storageProvider,
+        addonConfig: { modelsDir },
+        createLogger: loggerFactory,
+        capabilityRegistry,
+    };
+    for (const dir of dirs) {
+        const loader = new system_1.AddonLoader();
+        try {
+            await loader.loadFromAddonDir(dir);
+        }
+        catch (err) {
+            console.warn(`[Agent] Skipping ${dir}: ${(0, types_2.errMsg)(err)}`);
+            continue;
+        }
+        for (const registered of loader.listAddons()) {
+            const addonId = registered.declaration.id;
+            if (loadedAddons.has(addonId))
+                continue;
+            if (!(0, types_1.isDeployableToAgent)(registered.declaration))
+                continue;
+            // Group-runner addons are dispatched to subprocesses by the caller.
+            if ((0, agent_group_runner_js_1.isGroupRunnerAddon)(registered.declaration))
+                continue;
+            try {
+                const instance = new registered.addonClass();
+                const context = await (0, system_1.createAddonContext)(broker, registered.declaration, dataDir, contextOptions);
+                await instance.initialize(context);
+                const serviceSchema = (0, system_1.createAddonService)(instance, registered.declaration);
+                broker.createService(serviceSchema);
+                loadedAddons.set(addonId, {
+                    id: addonId,
+                    status: 'running',
+                    version: registered.declaration.version,
+                    packageName: registered.packageName,
+                    packageVersion: registered.packageVersion,
+                    addon: instance,
+                });
+                console.log(`[Agent] Deployed addon "${addonId}" loaded in-process`);
+            }
+            catch (err) {
+                const msg = (0, types_2.errMsg)(err);
+                console.error(`[Agent] Failed to load deployed addon "${addonId}": ${msg}`);
+                loadedAddons.set(addonId, { id: addonId, status: 'error' });
+            }
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Read the agent's own root package.json version (best-effort). The agent
+ * boots the `@camstack/server` closure (via CAMSTACK_ROLE=agent), so its
+ * on-disk root package is `@camstack/server`.
+ */
+function readAgentVersion() {
+    // package.json sits above `dist/`. Walk up until we hit it.
+    const candidates = [
+        path.resolve(__dirname, '..', 'package.json'),
+        path.resolve(__dirname, '..', '..', 'package.json'),
+    ];
+    for (const candidate of candidates) {
+        try {
+            if (!fs.existsSync(candidate))
+                continue;
+            const raw = JSON.parse(fs.readFileSync(candidate, 'utf-8'));
+            if (raw.name === '@camstack/server' && typeof raw.version === 'string')
+                return raw.version;
+        }
+        catch {
+            /* keep searching */
+        }
+    }
+    return 'unknown';
+}
+/** Check if path is a directory (follows symlinks) */
+function isDir(p) {
+    try {
+        return fs.statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/** Scan addonsDir for addon packages (scoped and unscoped, follows symlinks) */
+function resolveAddonPackageDirs(addonsDir) {
+    const dirs = [];
+    if (!fs.existsSync(addonsDir))
+        return dirs;
+    for (const name of fs.readdirSync(addonsDir)) {
+        const full = path.join(addonsDir, name);
+        if (name.startsWith('@') && isDir(full)) {
+            // Scoped packages: @camstack/addon-xyz
+            for (const sub of fs.readdirSync(full)) {
+                const subFull = path.join(full, sub);
+                if (isDir(subFull) && fs.existsSync(path.join(subFull, 'package.json'))) {
+                    dirs.push(subFull);
+                }
+            }
+        }
+        else if (isDir(full) && fs.existsSync(path.join(full, 'package.json'))) {
+            dirs.push(full);
+        }
+    }
+    return dirs;
+}
+// ---------------------------------------------------------------------------
+// E1 helper — agent-local UDS child manifest adaptation
+// ---------------------------------------------------------------------------
+/**
+ * Adapt a child's UDS `ChildCapDescriptor[]` into a `RegisterNodeParams`
+ * for the agent's subtree HubNodeRegistry.
+ *
+ * Multi-addon manifest support (co-location): descriptors are grouped by the
+ * `addonId` each one carries, producing one manifest entry per hosted addon —
+ * a GROUPED runner (`execution.group`) registers each addon's caps under its
+ * REAL addon id instead of collapsing them under a synthetic
+ * `addonId = childId` (the group name). A legacy child that omits `addonId`
+ * falls back to `childId` — identical to the historical single-addon
+ * behaviour (childId = runnerId = addonId when no group is declared).
+ * Mirrors the hub's `buildChildUdsManifest`.
+ *
+ * Only system (non-device-scoped) caps go into `addons`; device-scoped native
+ * caps arrive on a later re-handshake via the Moleculer path.
+ */
+function buildAgentChildUdsManifest(nodeId, childId, caps) {
+    const capsByAddon = new Map();
+    for (const cap of caps) {
+        if (cap.deviceId !== undefined)
+            continue;
+        const addonId = cap.addonId ?? childId;
+        const set = capsByAddon.get(addonId) ?? new Set();
+        set.add(cap.capName);
+        capsByAddon.set(addonId, set);
+    }
+    if (capsByAddon.size === 0) {
+        capsByAddon.set(childId, new Set());
+    }
+    const addons = [...capsByAddon.entries()].map(([addonId, capNames]) => ({ addonId, capabilities: [...capNames] }));
+    return { nodeId, addons };
+}