@camstack/server 1.2.29 → 1.2.32

package/dist/api/addons-custom.router.js

@@ -0,0 +1,99 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAddonsCustomProcedures = createAddonsCustomProcedures;
+/**
+ * `api.addons.custom` — generic dispatcher for addon-defined custom actions.
+ *
+ * Task 7.2 of the device-proxy redesign. Addons declare a catalog of
+ * custom actions at boot via `AddonInitResult.customActions` + a single
+ * `handleCustomAction(action, input)` handler. The catalog is registered
+ * with a per-process `CustomActionRegistry` (Task 7.1). This endpoint is
+ * the single tRPC entry point that resolves an `(addonId, action)` pair,
+ * validates input + output against the action's Zod schemas, enforces the
+ * action's declared auth level, and dispatches to the addon handler.
+ *
+ * The factory returns a record of procedures (not a router) so the caller
+ * can spread it into the existing `addons` namespace:
+ *
+ *   trpcRouter({
+ *     ...existingAddonsProcedures,
+ *     ...createAddonsCustomProcedures({ getCustomActionRegistry: ... }),
+ *   })
+ *
+ * This avoids `mergeRouters` (which requires sharing the `t` instance
+ * across modules) while still mounting the procedure at `api.addons.custom`.
+ */
+const zod_1 = require("zod");
+const server_1 = require("@trpc/server");
+const trpc_middleware_js_1 = require("./trpc/trpc.middleware.js");
+/**
+ * Build the procedure record for the `custom` endpoint.
+ *
+ * The OUTER procedure is `protectedProcedure` — every caller must be
+ * authenticated. The INNER per-action auth declared in `spec.auth` is
+ * enforced manually by `ensureAuth` because the auth level is not known
+ * until after the registry lookup.
+ */
+function createAddonsCustomProcedures(deps) {
+    return {
+        custom: trpc_middleware_js_1.protectedProcedure
+            .input(zod_1.z.object({
+            addonId: zod_1.z.string().min(1),
+            action: zod_1.z.string().min(1),
+            input: zod_1.z.unknown(),
+        }))
+            .output(zod_1.z.unknown())
+            .mutation(async ({ input, ctx }) => {
+            const registry = deps.getCustomActionRegistry();
+            const entry = registry.resolve(input.addonId, input.action);
+            if (!entry) {
+                throw new server_1.TRPCError({
+                    code: 'NOT_FOUND',
+                    message: `addon '${input.addonId}' has no custom action '${input.action}'`,
+                });
+            }
+            // Per-action authorization. The outer procedure already requires
+            // authentication; here we additionally enforce the declared role
+            // when it's stricter than 'protected'.
+            ensureAuth(ctx, entry.spec.auth);
+            // Validate input against the action's declared Zod schema.
+            const parsedInput = entry.spec.input.parse(input.input);
+            // Dispatch through the addon handler, forwarding the authenticated
+            // caller when the action declares `caller: 'required'`. The caller is
+            // derived server-side from the request principal (never trusted from
+            // input); `ctx.user` is guaranteed present because `ensureAuth` above
+            // rejects unauthenticated callers for any non-public action, and the
+            // outer `protectedProcedure` rejects them for public ones.
+            const caller = entry.spec.caller === 'required' && ctx.user
+                ? { userId: ctx.user.id, isAdmin: ctx.user.isAdmin }
+                : undefined;
+            const result = await entry.handler(parsedInput, caller);
+            // Validate the addon's output. Crash-early on misbehaving addons.
+            return entry.spec.output.parse(result);
+        }),
+    };
+}
+/**
+ * Enforce the action's declared auth level.
+ *
+ * Mirrors the role checks performed by `protectedProcedure` and
+ * `adminProcedure` in trpc.middleware.ts:
+ *   - public:    no auth
+ *   - protected: any authenticated user
+ *   - admin:     isAdmin only (scoped tokens bounce)
+ */
+function ensureAuth(ctx, level) {
+    if (level === 'public')
+        return;
+    if (!ctx.user) {
+        throw new server_1.TRPCError({ code: 'UNAUTHORIZED' });
+    }
+    if (level === 'protected')
+        return;
+    if (level === 'admin') {
+        if (!ctx.user.isAdmin) {
+            throw new server_1.TRPCError({ code: 'FORBIDDEN', message: 'custom action requires admin' });
+        }
+        return;
+    }
+}

package/dist/api/core/bulk-update-coordinator.js

@@ -0,0 +1,229 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BulkUpdateCoordinator = void 0;
+/* eslint-disable @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-return, @typescript-eslint/no-unsafe-argument -- The server installs @camstack/types@0.1.38 (last published) in server/backend/node_modules, while the workspace has 0.1.39 with the new BulkUpdate* types. ESLint's type-checker resolves against 0.1.38 and treats the new imports as `any`. Runtime is correct because Node module resolution walks up to root node_modules → workspace symlink. This disable mirrors the pattern in cap-providers.ts (same root cause). Will resolve when 0.1.39 is published and the local dist is synced. */
+const node_crypto_1 = require("node:crypto");
+const types_1 = require("@camstack/types");
+const DEFAULT_CLEANUP_AFTER_MS = 5 * 60 * 1_000;
+class BulkUpdateCoordinator {
+    deps;
+    states = new Map();
+    cancelFlags = new Map();
+    /**
+     * Tracks wall-clock time (ms) when each bulk completed. Used for lazy
+     * cleanup in `get()` — avoids scheduling a fake-timer `setTimeout` that
+     * would be eagerly fired by `vi.runAllTimersAsync()` in tests.
+     */
+    completedWallMs = new Map();
+    /** Tracks which nodeIds currently have an active (non-completed) bulk update. */
+    activeNodeIds = new Set();
+    now;
+    cleanupAfterMs;
+    /** Wall-clock source. Fake timers intercept `Date.now`, so tests can advance via `advanceTimersByTimeAsync`. */
+    wallNow;
+    constructor(deps) {
+        this.deps = deps;
+        this.now = deps.clock ?? (() => Date.now());
+        this.cleanupAfterMs = deps.cleanupAfterMs ?? DEFAULT_CLEANUP_AFTER_MS;
+        this.wallNow = () => Date.now();
+    }
+    // ── Public API ────────────────────────────────────────────────────
+    start(input) {
+        if (this.activeNodeIds.has(input.nodeId)) {
+            throw new Error(`Bulk update already in progress for node ${input.nodeId}`);
+        }
+        const id = (0, node_crypto_1.randomUUID)();
+        const items = input.items.map((i) => ({
+            name: i.name,
+            isSystem: i.isSystem,
+            // fromVersion: the cap interface receives name+version+isSystem only;
+            // the caller (cap-providers.ts) may enrich this with the current version
+            // if available. Empty string is acceptable per plan spec.
+            fromVersion: '',
+            toVersion: i.version,
+            status: 'queued',
+        }));
+        const state = {
+            id,
+            nodeId: input.nodeId,
+            startedAtMs: this.now(),
+            total: items.length,
+            completed: 0,
+            failed: 0,
+            current: null,
+            phase: 'regular',
+            cancelled: false,
+            items,
+        };
+        this.states.set(id, state);
+        this.activeNodeIds.add(input.nodeId);
+        const cancelFlag = { cancelled: false };
+        this.cancelFlags.set(id, cancelFlag);
+        // Emit initial state so clients see the bulk as started immediately
+        this.emit(state);
+        void this.runLoop(id, cancelFlag).catch((err) => {
+            this.deps.logger.error('BulkUpdateCoordinator: loop crashed unexpectedly', err);
+        });
+        return { id };
+    }
+    get(id) {
+        const state = this.states.get(id);
+        if (state === undefined)
+            return null;
+        // Lazy cleanup: purge if the wall-clock elapsed since completion exceeds threshold.
+        // This avoids scheduling a long-lived setTimeout that would be eagerly fired
+        // by vi.runAllTimersAsync() in tests.
+        const completedWall = this.completedWallMs.get(id);
+        if (completedWall !== undefined && this.wallNow() - completedWall >= this.cleanupAfterMs) {
+            this.purge(id);
+            return null;
+        }
+        return state;
+    }
+    list(nodeId) {
+        const all = [...this.states.keys()]
+            .map((id) => this.get(id)) // get() applies lazy-cleanup
+            .filter((s) => s !== null);
+        return nodeId === undefined ? all : all.filter((s) => s.nodeId === nodeId);
+    }
+    cancel(id) {
+        const state = this.states.get(id);
+        const flag = this.cancelFlags.get(id);
+        if (state === undefined || flag === undefined)
+            return { cancelled: false };
+        // Once restarting, the hub restart is committed — cancel has no effect.
+        if (state.phase === 'restarting')
+            return { cancelled: false };
+        // Already completed.
+        if (state.completedAtMs !== undefined)
+            return { cancelled: false };
+        flag.cancelled = true;
+        this.mutate(id, (s) => ({ ...s, cancelled: true }));
+        return { cancelled: true };
+    }
+    // ── Internal loop ─────────────────────────────────────────────────
+    async runLoop(id, cancelFlag) {
+        const initial = this.states.get(id);
+        // ── Phase 1: regular addons ──────────────────────────────────────
+        this.transitionPhase(id, 'regular');
+        for (const item of initial.items.filter((i) => !i.isSystem)) {
+            if (cancelFlag.cancelled)
+                break;
+            await this.processItem(id, item, false);
+        }
+        // ── Phase 2: system packages (deferRestart: true) ────────────────
+        if (!cancelFlag.cancelled && initial.items.some((i) => i.isSystem)) {
+            this.transitionPhase(id, 'system');
+            for (const item of initial.items.filter((i) => i.isSystem)) {
+                if (cancelFlag.cancelled)
+                    break;
+                await this.processItem(id, item, true);
+            }
+            // ── Phase 3: single restart ──────────────────────────────────
+            const anySystemPendingRestart = this.states
+                .get(id)
+                .items.some((i) => i.isSystem && i.status === 'done-pending-restart');
+            if (anySystemPendingRestart && !cancelFlag.cancelled) {
+                this.transitionPhase(id, 'restarting');
+                try {
+                    await this.deps.restartServer({ confirm: true });
+                    // NOTE: In production, restartServer kills+respawns the hub process.
+                    // Code below this point will not execute in that scenario.
+                    // If the mock/stub returns (e.g. in tests), we fall through to finalizing.
+                }
+                catch (err) {
+                    // Restart failed but the npm installs already completed. Promote all
+                    // done-pending-restart items to done with a caveat error so the UI
+                    // can inform the user that a manual restart is needed.
+                    this.deps.logger.error('BulkUpdateCoordinator: restart failed', err);
+                    const errMsg = err instanceof Error ? err.message : String(err);
+                    for (const it of this.states.get(id).items) {
+                        if (it.status === 'done-pending-restart') {
+                            this.setItemStatus(id, it.name, 'done', {
+                                error: `Restart failed; manual restart required (${errMsg})`,
+                            });
+                        }
+                    }
+                }
+            }
+        }
+        // ── Phase 4: finalize ────────────────────────────────────────────
+        // Reached when:
+        //  a) no system packages at all, OR
+        //  b) restart failed (process continued), OR
+        //  c) cancelled before the restart phase.
+        this.transitionPhase(id, 'finalizing');
+        this.completeBulk(id);
+    }
+    async processItem(id, item, isSystem) {
+        this.setItemStatus(id, item.name, 'updating', { startedAtMs: this.now() });
+        this.mutate(id, (s) => ({ ...s, current: item.name }));
+        this.emit(this.states.get(id));
+        try {
+            if (isSystem) {
+                await this.deps.updateFrameworkPackage({
+                    packageName: item.name,
+                    version: item.toVersion,
+                    deferRestart: true,
+                });
+                this.setItemStatus(id, item.name, 'done-pending-restart', { completedAtMs: this.now() });
+            }
+            else {
+                await this.deps.updateAddon({ name: item.name, version: item.toVersion });
+                this.setItemStatus(id, item.name, 'done', { completedAtMs: this.now() });
+            }
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            this.setItemStatus(id, item.name, 'failed', { error: msg, completedAtMs: this.now() });
+        }
+        this.mutate(id, (s) => ({ ...s, current: null }));
+        this.emit(this.states.get(id));
+    }
+    // ── State mutation helpers ────────────────────────────────────────
+    setItemStatus(id, name, status, fields = {}) {
+        this.mutate(id, (s) => {
+            const items = s.items.map((it) => (it.name === name ? { ...it, status, ...fields } : it));
+            // completed = all terminal states: done | done-pending-restart | failed
+            const completed = items.filter((it) => it.status === 'done' || it.status === 'done-pending-restart' || it.status === 'failed').length;
+            const failed = items.filter((it) => it.status === 'failed').length;
+            return { ...s, items, completed, failed };
+        });
+    }
+    transitionPhase(id, phase) {
+        this.mutate(id, (s) => ({ ...s, phase }));
+        this.emit(this.states.get(id));
+    }
+    completeBulk(id) {
+        this.mutate(id, (s) => ({ ...s, completedAtMs: this.now(), current: null }));
+        this.emit(this.states.get(id));
+        // Free the nodeId slot so a new bulk for the same node can be started
+        const nodeId = this.states.get(id).nodeId;
+        this.activeNodeIds.delete(nodeId);
+        // Record wall-clock completion time for lazy cleanup in `get()`.
+        // We intentionally avoid scheduling a setTimeout here: a long-lived
+        // setTimeout (5 min) would be eagerly fired by vi.runAllTimersAsync()
+        // in tests, causing `get()` to return null immediately after the run.
+        // Instead, `get()` lazily checks whether the cleanup threshold has
+        // elapsed using Date.now() — which fake timers DO advance via
+        // advanceTimersByTimeAsync(), making the cleanup testable without
+        // a long-running timer.
+        this.completedWallMs.set(id, this.wallNow());
+    }
+    purge(id) {
+        this.states.delete(id);
+        this.cancelFlags.delete(id);
+        this.completedWallMs.delete(id);
+    }
+    /** Immutably update the state for the given id. No-op if id is unknown. */
+    mutate(id, update) {
+        const current = this.states.get(id);
+        if (current === undefined)
+            return;
+        this.states.set(id, update(current));
+    }
+    emit(state) {
+        this.deps.eventBus.emit(types_1.EventCategory.AddonsBulkUpdateProgress, state);
+    }
+}
+exports.BulkUpdateCoordinator = BulkUpdateCoordinator;

package/dist/api/core/cap-providers.js

@@ -1,4 +1,29 @@
 "use strict";
+/* eslint-disable @typescript-eslint/no-unsafe-return, @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access -- pre-existing lint debt across this 800-line provider-factory module. The flagged sites delegate into Moleculer/EventBus/IntegrationRegistry surfaces typed as `unknown` to break circular dependencies; runtime contracts are validated by the cap-mount-helper layer above. Tracked separately. */
+/**
+ * Capability provider factories for the Phase E core caps —
+ * `system`, `network-quality`, `toast`, `nodes`, `integrations`,
+ * `addons`. Each factory builds a fresh provider object that
+ * fulfils the cap's `InferProvider<...>` contract by delegating
+ * to the existing backend services.
+ *
+ * Why factories instead of static singletons?
+ *   - `addons.custom` needs per-request `ctx.user` for per-action
+ *     auth checks. The cap-router codegen already passes `ctx`
+ *     into `getProvider(ctx)`, so closing over it is cheap and
+ *     keeps the auth surface tight.
+ *   - The other caps don't need ctx, but we keep the signature
+ *     uniform for symmetry.
+ *
+ * No addon "owns" these surfaces — they manage cluster state
+ * (cluster topology, integrations, addon packages) or expose
+ * server-level singletons (toast bus, network-quality tracker,
+ * feature flags + retention controls).
+ *
+ * Phase E (2026-05-06): replaces the hand-written core routers in
+ * `server/backend/src/api/core/{system,network-quality,toast,
+ * nodes,integrations,addons}.router.ts`.
+ */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     var desc = Object.getOwnPropertyDescriptor(m, k);
@@ -43,42 +68,17 @@ exports.buildNodesProvider = buildNodesProvider;
 exports.buildIntegrationsProvider = buildIntegrationsProvider;
 exports.dispatchCustomAction = dispatchCustomAction;
 exports.buildAddonsProvider = buildAddonsProvider;
-/* eslint-disable @typescript-eslint/no-unsafe-return, @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access -- pre-existing lint debt across this 800-line provider-factory module. The flagged sites delegate into Moleculer/EventBus/IntegrationRegistry surfaces typed as `unknown` to break circular dependencies; runtime contracts are validated by the cap-mount-helper layer above. Tracked separately. */
-/**
- * Capability provider factories for the Phase E core caps —
- * `system`, `network-quality`, `toast`, `nodes`, `integrations`,
- * `addons`. Each factory builds a fresh provider object that
- * fulfils the cap's `InferProvider<...>` contract by delegating
- * to the existing backend services.
- *
- * Why factories instead of static singletons?
- *   - `addons.custom` needs per-request `ctx.user` for per-action
- *     auth checks. The cap-router codegen already passes `ctx`
- *     into `getProvider(ctx)`, so closing over it is cheap and
- *     keeps the auth surface tight.
- *   - The other caps don't need ctx, but we keep the signature
- *     uniform for symmetry.
- *
- * No addon "owns" these surfaces — they manage cluster state
- * (cluster topology, integrations, addon packages) or expose
- * server-level singletons (toast bus, network-quality tracker,
- * feature flags + retention controls).
- *
- * Phase E (2026-05-06): replaces the hand-written core routers in
- * `server/backend/src/api/core/{system,network-quality,toast,
- * nodes,integrations,addons}.router.ts`.
- */
-const os = __importStar(require("node:os"));
 const node_child_process_1 = require("node:child_process");
-const node_util_1 = require("node:util");
 const node_crypto_1 = require("node:crypto");
-const server_1 = require("@trpc/server");
-const types_1 = require("@camstack/types");
+const os = __importStar(require("node:os"));
+const node_util_1 = require("node:util");
 const system_1 = require("@camstack/system");
+const types_1 = require("@camstack/types");
+const server_1 = require("@trpc/server");
 const integration_id_backfill_1 = require("../../boot/integration-id-backfill");
-const collection_preference_js_1 = require("./collection-preference.js");
 const addon_package_service_js_1 = require("../../core/addon/addon-package.service.js");
 const lifecycle_runner_singleton_js_1 = require("../../core/lifecycle/lifecycle-runner.singleton.js");
+const collection_preference_js_1 = require("./collection-preference.js");
 const execFileAsync = (0, node_util_1.promisify)(node_child_process_1.execFile);
 // ── system ──────────────────────────────────────────────────────────
 function getRetention(registry) {
@@ -358,7 +358,7 @@ function createNodeRootPackageLookup(moleculer, serverUpdate) {
         return moleculer.getNodeRootPackage(nodeId);
     };
 }
-function buildNodesProvider(agentRegistry, moleculer, addonRegistry, getNodeRootPackage) {
+function buildNodesProvider(agentRegistry, moleculer, addonRegistry, getNodeRootPackage, logger) {
     const broker = moleculer.broker;
     return {
         topology: async () => computeTopology(agentRegistry, addonRegistry, getNodeRootPackage),
@@ -414,6 +414,15 @@ function buildNodesProvider(agentRegistry, moleculer, addonRegistry, getNodeRoot
         },
         shutdownNode: async (input) => {
             if (input.nodeId === 'hub') {
+                // A whole-hub shutdown used to be COMPLETELY silent — process.exit(0)
+                // with not one log line. On 2026-08-01 the hub container went down
+                // cleanly at 15:02:55Z (docker restart policy brought it back 9s
+                // later, viewer stalled through the boot) and the initiator was
+                // unrecoverable from the logs precisely because this branch said
+                // nothing. An operator-facing kill switch logs before it fires.
+                logger?.warn('shutdownNode: HUB shutdown requested via API — exiting in 500ms', {
+                    meta: { nodeId: input.nodeId },
+                });
                 setTimeout(() => process.exit(0), 500);
                 return { success: true };
             }

package/dist/api/trpc/generated-cap-mounts.js

@@ -260,7 +260,7 @@ function mountAllCaps(services) {
         modelConvert: (0, generated_cap_routers_js_1.createCapRouter_modelConvert)((_ctx) => reg?.getSingleton('model-convert') ?? null, remoteCapProxy),
         modelDistributor: (0, generated_cap_routers_js_1.createCapRouter_modelDistributor)((_ctx) => reg?.getSingleton('model-distributor') ??
             null, remoteCapProxy),
-        motion: (0, generated_cap_routers_js_1.createCapRouter_motion)((_ctx) => reg?.getSingleton('motion') ?? null, remoteCapProxy),
+        motion: (0, generated_cap_routers_js_1.createCapRouter_motion)((_ctx) => (0, cap_mount_helpers_js_1.requireDeviceScoped)(reg, 'motion'), remoteCapProxy),
         motionDetection: (0, generated_cap_routers_js_1.createCapRouter_motionDetection)((_ctx) => reg?.getSingleton('motion-detection') ??
             null, remoteCapProxy),
         motionTrigger: (0, generated_cap_routers_js_1.createCapRouter_motionTrigger)((_ctx) => (0, cap_mount_helpers_js_1.requireDeviceScoped)(reg, 'motion-trigger'), remoteCapProxy),

package/dist/api/trpc/trpc.router.js

@@ -8,15 +8,15 @@ exports.buildAppRouter = buildAppRouter;
 const addon_settings_router_js_1 = require("../core/addon-settings.router.js");
 const auth_router_js_1 = require("../core/auth.router.js");
 const cap_providers_js_1 = require("../core/cap-providers.js");
-const server_management_provider_js_1 = require("../core/server-management.provider.js");
 const capabilities_router_js_1 = require("../core/capabilities.router.js");
+const cluster_nodes_router_js_1 = require("../core/cluster-nodes.router.js");
 const event_bus_proxy_router_js_1 = require("../core/event-bus-proxy.router.js");
 const hwaccel_router_js_1 = require("../core/hwaccel.router.js");
 const live_events_router_js_1 = require("../core/live-events.router.js");
 const logs_router_js_1 = require("../core/logs.router.js");
 const notifications_router_js_1 = require("../core/notifications.router.js");
-const cluster_nodes_router_js_1 = require("../core/cluster-nodes.router.js");
 const repl_router_js_1 = require("../core/repl.router.js");
+const server_management_provider_js_1 = require("../core/server-management.provider.js");
 const settings_backend_router_js_1 = require("../core/settings-backend.router.js");
 const stream_probe_router_js_1 = require("../core/stream-probe.router.js");
 const system_events_router_js_1 = require("../core/system-events.router.js");
@@ -195,7 +195,7 @@ function buildServerProviders(services) {
         system: wrap(() => (0, cap_providers_js_1.buildSystemProvider)(services.featureService, services.capabilityRegistry)),
         toast: wrap((ctx) => (0, cap_providers_js_1.buildToastProvider)(services.toastService, ctx)),
         integrations: wrap(() => (0, cap_providers_js_1.buildIntegrationsProvider)(services.addonRegistry, services.eventBus, services.loggingService, services.capabilityRegistry)),
-        nodes: wrap(() => (0, cap_providers_js_1.buildNodesProvider)(services.agentRegistry, services.moleculer, services.addonRegistry, (0, cap_providers_js_1.createNodeRootPackageLookup)(services.moleculer, services.serverUpdateService))),
+        nodes: wrap(() => (0, cap_providers_js_1.buildNodesProvider)(services.agentRegistry, services.moleculer, services.addonRegistry, (0, cap_providers_js_1.createNodeRootPackageLookup)(services.moleculer, services.serverUpdateService), services.loggingService.createLogger('nodes'))),
         // server-management — runtime-updatable root package (phase 1: hub only).
         'server-management': wrap(() => (0, server_management_provider_js_1.buildServerManagementProvider)(services.serverUpdateService)),
         addons: wrap((ctx) => (0, cap_providers_js_1.buildAddonsProvider)(services.addonRegistry, services.addonPackageService, services.loggingService, services.moleculer, services.configService, ctx)),

package/dist/boot/resume-framework-swap.js

@@ -0,0 +1,119 @@
+"use strict";
+/**
+ * Boot-time framework-swap job resume + health confirm.
+ *
+ * After a framework swap reboot, `post-boot.service.ts` calls this once the
+ * hub is healthy.  It:
+ *   1. Reads `.framework-swap-confirm.json` (written by the launcher on apply).
+ *   2. Marks the journal task `applied` → `done`, then finalises the job →
+ *      `completed`.
+ *   3. Calls `confirmFrameworkSwapHealthy` to delete the confirm marker +
+ *      backup dirs (disarms the crash-loop rollback).
+ *
+ * Best-effort: a missing/corrupt journal is tolerated — `confirmFrameworkSwapHealthy`
+ * is still called so the rollback is always disarmed when the hub boots healthy.
+ */
+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.resumeFrameworkSwapJob = resumeFrameworkSwapJob;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const types_1 = require("@camstack/types");
+const system_1 = require("@camstack/system");
+const launcher_framework_swap_js_1 = require("../launcher-framework-swap.js");
+const lifecycle_journal_path_js_1 = require("../lifecycle-journal-path.js");
+const SWAP_CONFIRM_FILE = '.framework-swap-confirm.json';
+/**
+ * Resume a framework-swap journal job to `done`/`completed` and confirm the
+ * hub is healthy (deletes the confirm marker + backups).
+ *
+ * @returns `{ resumed: false }` when no confirm marker exists.
+ *          `{ resumed: true, jobId }` when the marker was found and processed.
+ *          Never throws — errors are swallowed to avoid crashing the post-boot path.
+ */
+async function resumeFrameworkSwapJob(dataDir) {
+    try {
+        const confirmMarker = readConfirmMarker(dataDir);
+        if (confirmMarker === null) {
+            return { resumed: false };
+        }
+        const { jobId, taskId } = confirmMarker;
+        let journalPatched = false;
+        try {
+            const journal = new system_1.JobJournal((0, lifecycle_journal_path_js_1.lifecycleJobsDir)(dataDir));
+            const job = journal.getJob(jobId);
+            if (job !== null) {
+                const task = job.tasks.find((t) => t.taskId === taskId);
+                if (task !== undefined && task.phase === 'applied') {
+                    journal.patchTask(jobId, taskId, { phase: 'done', finishedAtMs: Date.now() });
+                    // Single-task framework job: if all tasks are now terminal and none
+                    // failed, mark the job completed (mirrors the engine's finalize logic).
+                    const updatedJob = journal.getJob(jobId);
+                    if (updatedJob !== null) {
+                        const allTerminal = updatedJob.tasks.every((t) => t.phase === 'done' || t.phase === 'failed' || t.phase === 'skipped');
+                        const anyFailed = updatedJob.tasks.some((t) => t.phase === 'failed');
+                        if (allTerminal && !anyFailed) {
+                            journal.setJobState(jobId, 'completed');
+                        }
+                    }
+                    journalPatched = true;
+                }
+            }
+        }
+        catch {
+            // Journal is missing or corrupt — still clean up the confirm marker so
+            // the rollback is disarmed on a healthy hub boot.
+        }
+        (0, launcher_framework_swap_js_1.confirmFrameworkSwapHealthy)(dataDir);
+        return journalPatched ? { resumed: true, jobId } : { resumed: false };
+    }
+    catch {
+        // Never crash the caller (post-boot service).
+        return { resumed: false };
+    }
+}
+/** Read and shape-check the confirm marker.  Returns null on any error. */
+function readConfirmMarker(dataDir) {
+    try {
+        const raw = JSON.parse(fs.readFileSync(path.join(dataDir, SWAP_CONFIRM_FILE), 'utf-8'));
+        const parsed = types_1.frameworkSwapConfirmSchema.safeParse(raw);
+        if (!parsed.success)
+            return null;
+        return { jobId: parsed.data.jobId, taskId: parsed.data.taskId };
+    }
+    catch {
+        return null;
+    }
+}

package/dist/bootstrap-packages.js

@@ -0,0 +1,35 @@
+"use strict";
+/**
+ * Hub bootstrap package selection.
+ *
+ * Extracted from `launcher.ts` so it can be unit-tested: the launcher
+ * self-executes `launch()` at import time, so nothing inside it is reachable
+ * from a spec. Same shape as `framework-nodepath.ts`.
+ *
+ * The selection MUST stay in lockstep with
+ * `AddonInstaller.deriveBootstrapList` in `@camstack/system` — that one reads
+ * the same `@camstack/server` manifest through `require.resolve`, this one
+ * reads the launcher's own `package.json` by absolute path (the slim image
+ * strips the `@camstack/*` symlinks, so `require.resolve` yields an empty list
+ * at launcher import time). Two derivations of the same list is exactly how
+ * `@camstack/addon-agent-ui` ended up installed on the hub: the installer's
+ * copy honoured `camstack.agentOnlyBootstrapAddons`, this one did not, and the
+ * hub is the side that actually boots through here.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.selectHubBootstrapPackages = selectHubBootstrapPackages;
+/**
+ * The packages a HUB-role node bootstrap-installs: every `@camstack/addon-*`
+ * runtime dependency plus `@camstack/system` (the carrier of the required
+ * infrastructure builtins — storage-provider / settings / logging — without
+ * which boot aborts).
+ *
+ * `camstack.agentOnlyBootstrapAddons` is subtracted. Those addons are declared
+ * as runtime dependencies so the published `@camstack/server` closure CARRIES
+ * them for agent-role nodes to seed, but they are `execution.placement:
+ * 'agent-only'` and the hub must never install them.
+ */
+function selectHubBootstrapPackages(pkg) {
+    const agentOnly = new Set(pkg.camstack?.agentOnlyBootstrapAddons ?? []);
+    return Object.keys(pkg.dependencies ?? {}).filter((name) => !agentOnly.has(name) && (name.startsWith('@camstack/addon-') || name === '@camstack/system'));
+}