@camstack/server 1.1.43 → 1.1.45

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

@@ -6,6 +6,7 @@ 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 event_bus_proxy_router_js_1 = require("../core/event-bus-proxy.router.js");
 const hwaccel_router_js_1 = require("../core/hwaccel.router.js");
@@ -83,7 +84,9 @@ 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)),
+        nodes: wrap(() => (0, cap_providers_js_1.buildNodesProvider)(services.agentRegistry, services.moleculer, services.addonRegistry, (0, cap_providers_js_1.createNodeRootPackageLookup)(services.moleculer, services.serverUpdateService))),
+        // 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)),
         // webrtc-session — the resolved broker singleton, wrapped per request to
         // inject the server-read User-Agent into signaling attribution (the broker
@@ -163,7 +166,7 @@ function buildCapabilityRouters(services) {
         // clusterNodes — fixed core API. Write-side purge for the durable
         // offline-node history (Track A "Forget node"); read side is push-only.
         clusterNodes: (0, cluster_nodes_router_js_1.createClusterNodesRouter)(services.agentRegistry),
-        auth: (0, auth_router_js_1.createAuthRouter)(services.authService, services.capabilityRegistry),
+        auth: (0, auth_router_js_1.createAuthRouter)(services.authService, services.capabilityRegistry, services.moleculer),
         // NOT MOUNTED — `mount: { kind: 'skip' }` legacy provider shapes
         // (positional args / sync returns) that don't match the codegen
         // routers' {input}-object + Promise<T> contract. The runtime builder

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

@@ -44,7 +44,7 @@ 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 framework_live_sync_js_1 = require("./framework-live-sync.js");
+const package_dir_utils_js_1 = require("./package-dir-utils.js");
 const types_1 = require("@camstack/types");
 const system_1 = require("@camstack/system");
 const execFileAsync = (0, node_util_1.promisify)(node_child_process_1.execFile);
@@ -54,24 +54,21 @@ const execFileAsync = (0, node_util_1.promisify)(node_child_process_1.execFile);
  */
 exports.SYSTEM_PACKAGE = '@camstack/system';
 /**
- * Host-provided framework packages that a `camstack deploy` mirrors into the
- * running hub's live closure via `syncFrameworkDist` (hub-main node_modules +
- * addon-runner overlay) instead of the normal addon-install path, then bounces
- * the server — delivering the new code with NO image rebuild.
+ * Host-provided framework packages that take a special path through
+ * `camstack deploy` (the addon-upload route) instead of the normal
+ * addon-install path.
  *
- * `@camstack/types` is included so a CAPABILITY change ships live via
- * `camstack deploy packages/types`: the hub-main reads `ALL_CAPABILITY_DEFINITIONS`
- * + `METHOD_ACCESS_MAP` and the runtime cap-router builder reads the cap defs
- * from this single closure copy, so mirroring types' `dist/` refreshes the
- * ENTIRE cap surface (new caps, new methods, AND the per-method auth map)
- * without an image. `@camstack/sdk` rides along as a pure-JS lockstep companion.
- * `@camstack/shm-ring` is deliberately EXCLUDED: it ships a native `.node`
- * prebuild the dist-only mirror cannot rebuild — it must go through the
- * native-aware install path, not this JS-dist swap.
+ * Since the runtime-updatable root package shipped (2026-07-12 design), a
+ * framework upload on a DEPLOYED hub is rejected with guidance to update the
+ * `@camstack/server` root instead — the hub main + framework deps update as
+ * ONE npm closure via the `server-management` cap. In a WORKSPACE checkout
+ * the upload still triggers a plain restart: the hub resolves the framework
+ * from `packages/<pkg>/dist`, which the CLI rebuilt before uploading, so the
+ * dev loop (`camstack deploy packages/system`) is unchanged.
  *
  * Membership is by package NAME, independent of the `camstack.system` manifest
  * flag (`@camstack/types` declares `system: false` yet is a framework package
- * here) — that flag drives Admin-UI grouping; this gate drives live-sync routing.
+ * here) — that flag drives Admin-UI grouping; this gate drives upload routing.
  */
 exports.FRAMEWORK_PACKAGES = [
     exports.SYSTEM_PACKAGE,
@@ -79,8 +76,8 @@ exports.FRAMEWORK_PACKAGES = [
     '@camstack/sdk',
 ];
 /**
- * Returns true for a host-provided framework package whose `dist/` is mirrored
- * into the live closure by `syncFrameworkDist` (not installed as a normal addon).
+ * Returns true for a host-provided framework package (special-cased by the
+ * addon-upload route — never installed as a normal addon).
  */
 function isFrameworkPackage(packageName) {
     return exports.FRAMEWORK_PACKAGES.includes(packageName);
@@ -1012,8 +1009,8 @@ class AddonPackageService {
             // Content build-id of the code the hub ACTUALLY loaded — resolved from
             // the same closure the running process uses. Surfaces "same semver,
             // new code" (framework packages ship changes without always bumping).
-            const hubPkgDir = (0, framework_live_sync_js_1.resolveHubClosurePackageDir)(packageName);
-            const buildId = hubPkgDir !== null ? (0, framework_live_sync_js_1.computeDistBuildId)(path.join(hubPkgDir, 'dist')) : null;
+            const hubPkgDir = (0, package_dir_utils_js_1.resolveHubClosurePackageDir)(packageName);
+            const buildId = hubPkgDir !== null ? (0, package_dir_utils_js_1.computeDistBuildId)(path.join(hubPkgDir, 'dist')) : null;
             let latestVersion = null;
             try {
                 const args = [

package/dist/core/addon/package-dir-utils.js

@@ -0,0 +1,140 @@
+"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.resolveHubClosurePackageDir = resolveHubClosurePackageDir;
+exports.computeDistBuildId = computeDistBuildId;
+/**
+ * Package-dir introspection helpers for the hub's OWN framework closure.
+ *
+ * Extracted from the deleted `framework-live-sync.ts` (the dist-mirror
+ * machinery was superseded by the runtime-updatable root package — see
+ * docs/superpowers/specs/2026-07-12-runtime-updatable-node-packages-design.md);
+ * these two read-only helpers remain in use by `AddonPackageService`'s
+ * framework-package status surface.
+ */
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const node_crypto_1 = require("node:crypto");
+const node_module_1 = require("node:module");
+// Resolve framework packages the same way the running hub does — from THIS
+// module's location, whose walk-up lands on the hub's own `node_modules`
+// closure (identical to the hub main's `@camstack/system` resolution).
+const requireFromHere = (0, node_module_1.createRequire)(__filename);
+function readJsonObjectSafe(filePath) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+        if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            return { ...parsed };
+        }
+    }
+    catch {
+        /* missing / malformed — treat as absent */
+    }
+    return null;
+}
+function packageNameOf(pkgJsonPath) {
+    const obj = readJsonObjectSafe(pkgJsonPath);
+    const name = obj?.['name'];
+    return typeof name === 'string' ? name : null;
+}
+/**
+ * The package directory the HUB MAIN process loads `<packageName>` from — its
+ * own `node_modules` closure. `require.resolve('<pkg>/package.json')` is the
+ * happy path; packages whose `exports` map omits that subpath fall back to
+ * resolving the main entry and walking up to the matching `package.json`.
+ * Returns null when the package is not resolvable.
+ */
+function resolveHubClosurePackageDir(packageName) {
+    try {
+        return path.dirname(requireFromHere.resolve(`${packageName}/package.json`));
+    }
+    catch {
+        // `exports` map blocks the package.json subpath — fall through.
+    }
+    try {
+        let dir = path.dirname(requireFromHere.resolve(packageName));
+        while (dir !== path.dirname(dir)) {
+            const candidate = path.join(dir, 'package.json');
+            if (fs.existsSync(candidate) && packageNameOf(candidate) === packageName) {
+                return dir;
+            }
+            dir = path.dirname(dir);
+        }
+    }
+    catch {
+        // package itself not resolvable — treat as not installed.
+    }
+    return null;
+}
+function collectJsFiles(root, dir, out) {
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            collectJsFiles(root, full, out);
+        }
+        else if (entry.isFile() && (entry.name.endsWith('.js') || entry.name.endsWith('.mjs'))) {
+            out.push(path.relative(root, full));
+        }
+    }
+}
+/**
+ * Content build-id of a `dist/` tree — md5 over every `.js`/`.mjs` file's
+ * relative path + bytes (sorted for determinism). Analogous to the Docker
+ * image's `seed-version` fingerprint. Returns null when the dir is missing or
+ * empty. Used to surface "same semver, new code" instead of trusting `version`.
+ */
+function computeDistBuildId(distDir) {
+    if (!fs.existsSync(distDir))
+        return null;
+    const files = [];
+    collectJsFiles(distDir, distDir, files);
+    if (files.length === 0)
+        return null;
+    files.sort();
+    const hash = (0, node_crypto_1.createHash)('md5');
+    for (const rel of files) {
+        hash.update(rel);
+        hash.update('\0');
+        hash.update(fs.readFileSync(path.join(distDir, rel)));
+    }
+    return hash.digest('hex');
+}

package/dist/core/moleculer/moleculer.service.js

@@ -921,6 +921,14 @@ class MoleculerService {
     listClusterNativeCapsForDevice(deviceId) {
         return this.nodeRegistry.listNativeCapEntriesForDevice(deviceId);
     }
+    /**
+     * The root-package identity a node reported in its `registerNode`
+     * manifest (runtime-updatable node packages: version visibility), or null
+     * when the node never reported one (UDS children, pre-phase-2 agents).
+     */
+    getNodeRootPackage(nodeId) {
+        return this.nodeRegistry.getNodeRootPackage(nodeId);
+    }
     /**
      * E2: Send a `set-log-level` UDS message to a hub-local child identified by
      * `nodeId` (e.g. `hub/provider-reolink`). Extracts the `childId` from the

package/dist/core/server-update/server-update.service.js

@@ -0,0 +1,81 @@
+"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.ServerUpdateService = void 0;
+/**
+ * ServerUpdateService — hub-side adapter over the SHARED `RootUpdateService`
+ * (`@camstack/node-root`, bundled into `dist/server-root/index.js`).
+ *
+ * The stage/apply/rollback/probation engine — including the security-review
+ * fixes (rollback reentrancy guards, fresh-transient prune protection,
+ * `stateFileCorrupt` visibility) — lives in the shared core so the hub and
+ * the agent can never drift. This class only binds the hub's parameters:
+ * the `@camstack/server` root spec, the `CAMSTACK_SERVER_*` env markers,
+ * the `CAMSTACK_DATA` data-dir default and the running package.json path.
+ *
+ * The starter (server/backend/src/starter.ts → shared `runNodeStarter`)
+ * owns the OTHER half: choosing the closure at boot, bumping the probation
+ * counter, auto-rolling-back a version whose probation boot never confirmed.
+ *
+ * Spec: docs/superpowers/specs/2026-07-12-runtime-updatable-node-packages-design.md
+ */
+const path = __importStar(require("node:path"));
+const index_js_1 = require("../../server-root/index.js");
+class ServerUpdateService extends index_js_1.RootUpdateService {
+    constructor(options) {
+        super({
+            spec: index_js_1.HUB_ROOT_SPEC,
+            envNames: {
+                bootMode: 'CAMSTACK_SERVER_BOOT_MODE',
+                activeVersion: 'CAMSTACK_SERVER_ACTIVE_VERSION',
+                seedDir: 'CAMSTACK_SEED_SERVER_DIR',
+            },
+            logger: options.logger,
+            restartServer: options.restartServer,
+            dataDir: path.resolve(options.dataDir ??
+                options.env?.['CAMSTACK_DATA'] ??
+                process.env['CAMSTACK_DATA'] ??
+                'camstack-data'),
+            // dist/core/server-update/ → ../../../package.json = the running copy's
+            // package.json (workspace server/backend OR the active/baked closure).
+            runningPackageJsonPath: options.runningPackageJsonPath ?? path.resolve(__dirname, '..', '..', '..', 'package.json'),
+            workspaceProbeDir: __dirname,
+            execNpm: options.execNpm,
+            env: options.env,
+            now: options.now,
+        });
+    }
+}
+exports.ServerUpdateService = ServerUpdateService;

package/dist/core/topology/topology-emitter.service.js

@@ -38,14 +38,18 @@ class TopologyEmitterService {
     eventBus;
     agentRegistry;
     addonRegistry;
+    getNodeRootPackage;
     unsubscribers = [];
     debounceTimer = null;
     heartbeatTimer = null;
     emitting = false;
-    constructor(eventBus, agentRegistry, addonRegistry) {
+    constructor(eventBus, agentRegistry, addonRegistry, 
+    /** Root-package identity per node (version visibility) — optional. */
+    getNodeRootPackage) {
         this.eventBus = eventBus;
         this.agentRegistry = agentRegistry;
         this.addonRegistry = addonRegistry;
+        this.getNodeRootPackage = getNodeRootPackage;
     }
     onModuleInit() {
         for (const category of LIFECYCLE_CATEGORIES) {
@@ -85,7 +89,7 @@ class TopologyEmitterService {
             return;
         this.emitting = true;
         try {
-            const nodes = await (0, cap_providers_1.computeTopology)(this.agentRegistry, this.addonRegistry);
+            const nodes = await (0, cap_providers_1.computeTopology)(this.agentRegistry, this.addonRegistry, this.getNodeRootPackage);
             this.eventBus.emit({
                 id: (0, node_crypto_1.randomUUID)(),
                 timestamp: new Date(),

package/dist/main.js

@@ -81,11 +81,13 @@ const addon_upload_1 = require("./api/addon-upload");
 const auth_whoami_1 = require("./api/auth-whoami");
 const session_cookie_js_1 = require("./auth/session-cookie.js");
 const health_routes_1 = require("./api/health/health.routes");
+const spa_static_1 = require("./api/static/spa-static");
 const oauth2_routes_js_1 = require("./api/oauth2/oauth2-routes.js");
 const system_2 = require("@camstack/system");
 const boot_config_1 = require("./boot/boot-config");
 const manual_boot_1 = require("./manual-boot");
 const post_boot_service_1 = require("./boot/post-boot.service");
+const server_update_service_1 = require("./core/server-update/server-update.service");
 const integration_id_backfill_1 = require("./boot/integration-id-backfill");
 // ---- Process-level error handlers ----
 process.on('uncaughtException', (err) => {
@@ -363,6 +365,7 @@ async function bootstrap() {
             toastService,
             capabilityRegistry,
             streamProbe: app.get(stream_probe_service_1.StreamProbeService),
+            serverUpdateService: app.get(server_update_service_1.ServerUpdateService),
         });
         await fastify.register(fastify_1.fastifyTRPCPlugin, {
             prefix: '/trpc',
@@ -418,7 +421,10 @@ async function bootstrap() {
                             ? 'text/html'
                             : 'application/octet-stream';
             const stream = fs.createReadStream(resolved);
-            return reply.type(contentType).send(stream);
+            return reply
+                .header('cache-control', addonBundleCacheControl(resolved))
+                .type(contentType)
+                .send(stream);
         });
         // Register addon-widgets static file endpoint — same shape as
         // addon-pages but reads bundles from each addon's
@@ -447,7 +453,10 @@ async function bootstrap() {
                             ? 'text/html'
                             : 'application/octet-stream';
             const stream = fs.createReadStream(resolved);
-            return reply.type(contentType).send(stream);
+            return reply
+                .header('cache-control', addonBundleCacheControl(resolved))
+                .type(contentType)
+                .send(stream);
         });
         // Serve static assets (e.g. SVG icons) from an addon's package directory
         fastify.get('/api/addon-assets/:addonId/*', async (request, reply) => {
@@ -968,7 +977,12 @@ async function bootstrap() {
                     if (url.startsWith('/trpc') ||
                         url.startsWith('/api/') ||
                         url.startsWith('/agent') ||
-                        url.startsWith('/health')) {
+                        url.startsWith('/health') ||
+                        url.startsWith('/discovery') ||
+                        // The viewer SPA owns /viewer/** via its own catch-all (registered
+                        // below). Fall through here so admin-ui never serves it — and so
+                        // /viewer 404s cleanly when the viewer-ui addon isn't registered.
+                        url.startsWith('/viewer')) {
                         return reply.callNotFound();
                     }
                     // A request whose last path segment has a file extension is a static
@@ -989,16 +1003,7 @@ async function bootstrap() {
                             // client (the SW keeps serving the old precache). Content-hashed
                             // build assets (assets/index-<hash>.js) are immutable. Everything
                             // else gets a short cache.
-                            const base = rel.split('/').pop() ?? rel;
-                            if (/^(sw\.js|registerSW\.js|workbox-.*\.js|manifest\.webmanifest)$/.test(base)) {
-                                reply.header('cache-control', 'no-cache, must-revalidate');
-                            }
-                            else if (rel.startsWith('assets/') && /-[A-Za-z0-9_-]{8,}\./.test(base)) {
-                                reply.header('cache-control', 'public, max-age=31536000, immutable');
-                            }
-                            else {
-                                reply.header('cache-control', 'no-cache');
-                            }
+                            reply.header('cache-control', (0, spa_static_1.spaAssetCacheControl)(rel));
                             return reply.sendFile(rel);
                         }
                         return reply.callNotFound();
@@ -1022,6 +1027,82 @@ async function bootstrap() {
     catch (err) {
         console.error('[bootstrap] Failed to set up admin UI static serving:', err);
     }
+    // Serve the CamStack viewer SPA from the viewer-ui singleton capability.
+    // The viewer is built (Expo web export) with EXPO_PUBLIC_WEB_BASE_PATH=/viewer,
+    // so its baseUrl — and therefore every asset URL — is /viewer/camstack/**. We
+    // mount it at exactly that prefix and redirect /viewer → the SPA root. Mirrors
+    // the admin-ui poll+serve, but streams assets directly from its own dist root
+    // so it stays independent of the admin-ui @fastify/static decorator.
+    try {
+        const bootAddonRegistry = app.get(addon_registry_service_1.AddonRegistryService);
+        const capRegistry = bootAddonRegistry.getCapabilityRegistry();
+        let viewerUI = capRegistry?.getSingleton('viewer-ui');
+        const skipViewerUIWait = process.env['CAMSTACK_SKIP_VIEWER_UI_WAIT'] === '1';
+        if (!viewerUI && capRegistry && !skipViewerUIWait) {
+            // The viewer-ui addon runs in its own forked runner and registers a few
+            // seconds after boot. Poll briefly (shorter than admin-ui's 60s — the
+            // viewer is non-critical and admin-ui already gated the slow cold boot).
+            const VIEWER_UI_WAIT_MS = 30_000;
+            const POLL_MS = 200;
+            const deadline = Date.now() + VIEWER_UI_WAIT_MS;
+            while (!viewerUI && Date.now() < deadline) {
+                await new Promise((r) => setTimeout(r, POLL_MS));
+                viewerUI = capRegistry.getSingleton('viewer-ui');
+            }
+        }
+        if (viewerUI) {
+            const { staticDir } = await viewerUI.getStaticDir();
+            const indexPath = path.join(staticDir, 'index.html');
+            if (fs.existsSync(staticDir) && fs.existsSync(indexPath)) {
+                // The Expo baseUrl (`${webBasePath}/camstack`) is the on-hub mount.
+                const VIEWER_MOUNT = '/viewer/camstack';
+                // Clean entry point: /viewer and /viewer/ → the SPA root.
+                fastify.get('/viewer', async (_request, reply) => reply.redirect(`${VIEWER_MOUNT}/`));
+                fastify.get('/viewer/', async (_request, reply) => reply.redirect(`${VIEWER_MOUNT}/`));
+                // Single catch-all owns every GET under /viewer/**: assets stream LIVE
+                // from the current dist; everything else is the SPA shell.
+                fastify.get('/viewer/*', async (request, reply) => {
+                    const pathOnly = request.url.split('?')[0] ?? request.url;
+                    // Map the request path to a dist-relative path by stripping the mount
+                    // prefix. Anything not under the mount is treated as the SPA shell.
+                    let rel = '';
+                    if (pathOnly === VIEWER_MOUNT || pathOnly === `${VIEWER_MOUNT}/`) {
+                        rel = '';
+                    }
+                    else if (pathOnly.startsWith(`${VIEWER_MOUNT}/`)) {
+                        rel = pathOnly.slice(VIEWER_MOUNT.length + 1);
+                    }
+                    // A path whose last segment has a file extension is a static asset:
+                    // serve it, or 404 — NEVER the SPA shell (serving HTML under a
+                    // .js/.css URL pins text/html in caches and breaks the module MIME
+                    // check long after the file is actually available).
+                    if (rel && /\.[a-zA-Z0-9]+$/.test(pathOnly)) {
+                        const abs = path.join(staticDir, rel);
+                        if ((abs === staticDir || abs.startsWith(staticDir + path.sep)) && fs.existsSync(abs)) {
+                            reply.header('cache-control', (0, spa_static_1.spaAssetCacheControl)(rel));
+                            reply.type((0, spa_static_1.contentTypeForPath)(rel));
+                            return reply.send(fs.createReadStream(abs));
+                        }
+                        return reply.callNotFound();
+                    }
+                    // SPA shell — never cached (it references content-hashed bundles).
+                    reply.header('cache-control', 'no-cache, must-revalidate');
+                    return reply.type('text/html').send(fs.createReadStream(indexPath));
+                });
+                const { version } = await viewerUI.getVersion();
+                console.log(`[bootstrap] Viewer UI served from: ${staticDir} at ${VIEWER_MOUNT} (v${version})`);
+            }
+            else {
+                console.warn(`[bootstrap] Viewer UI dist not found at: ${staticDir} — run 'npm run build' in addon-viewer-ui`);
+            }
+        }
+        else {
+            console.warn('[bootstrap] viewer-ui capability not registered — viewer not served');
+        }
+    }
+    catch (err) {
+        console.error('[bootstrap] Failed to set up viewer UI static serving:', err);
+    }
     try {
         await app.listen(port, host);
     }
@@ -1041,6 +1122,22 @@ async function bootstrap() {
     // Post-boot: fork workers, register device streams, emit system.boot
     const postBoot = app.get(post_boot_service_1.PostBootService);
     await postBoot.run({ port, host, dataPath, trpcRegistered });
+    // The hub reached ready — when this boot is the PROBATION boot of a freshly
+    // staged @camstack/server root, promote it (currentVersion ← pending, N-1
+    // retained for rollback) and disarm the starter's crash-loop auto-rollback.
+    try {
+        const confirm = app.get(server_update_service_1.ServerUpdateService).confirmBootHealthy();
+        if (confirm.promoted !== null) {
+            logger.info('Server root package update confirmed healthy', {
+                meta: { version: confirm.promoted },
+            });
+        }
+    }
+    catch (err) {
+        logger.warn('Server root boot confirmation failed', {
+            meta: { error: err instanceof Error ? err.message : String(err) },
+        });
+    }
     // One-time backfill: stamp integrationId on devices created before the
     // device-manager forwarder started stamping it (legacy camera providers),
     // so deleting their integration cascades them. Idempotent — only touches
@@ -1095,6 +1192,22 @@ function readHubVersion() {
 /**
  * Build an AddonHttpReply wrapper around a Fastify reply.
  */
+/**
+ * Cache-Control for an addon MF bundle file. The entry point
+ * (`remoteEntry.js` / `widgets.mjs`) has a STABLE filename — only its
+ * `?v=` query changes across builds — so it MUST revalidate, otherwise a
+ * caching proxy (Cloudflare edge, whose default browser-cache TTL was
+ * serving these 4h) keeps handing out a stale entry whose export map
+ * lacks the current widgets ("bundle does not export this stableId",
+ * tunnel-only). The sibling chunks are CONTENT-HASHED in their filenames
+ * (`dist-<hash>.mjs`, `_virtual_mf-<hash>.mjs`), so they are safely
+ * immutable. The revalidation cost is a cheap 304 on a ~4KB entry.
+ */
+function addonBundleCacheControl(filePath) {
+    const base = path.basename(filePath);
+    const isMfEntry = base === 'remoteEntry.js' || base === 'widgets.mjs';
+    return isMfEntry ? 'no-cache, must-revalidate' : 'public, max-age=31536000, immutable';
+}
 function buildAddonReply(reply) {
     const wrapper = {
         status(code) {

package/dist/manual-boot.js

@@ -72,7 +72,9 @@ const addon_registry_service_1 = require("./core/addon/addon-registry.service");
 const addon_search_service_1 = require("./core/addon/addon-search.service");
 const addon_package_service_1 = require("./core/addon/addon-package.service");
 const repl_engine_service_1 = require("./core/repl/repl-engine.service");
+const server_update_service_1 = require("./core/server-update/server-update.service");
 const topology_emitter_service_1 = require("./core/topology/topology-emitter.service");
+const cap_providers_1 = require("./api/core/cap-providers");
 const post_boot_service_1 = require("./boot/post-boot.service");
 // ---------------------------------------------------------------------------
 // Service container — narrowing via `instanceof`, no casts.
@@ -200,7 +202,14 @@ async function bootManual(opts) {
         },
     });
     const replEngineService = new repl_engine_service_1.ReplEngineService(addonRegistryService, eventBusService, loggingService);
-    const topologyEmitterService = new topology_emitter_service_1.TopologyEmitterService(eventBusService, agentRegistryService, addonRegistryService);
+    // Runtime-updatable root package (phase 1: hub only). The service owns the
+    // data-dir server-root staging/rollback lifecycle; restarts route through
+    // AddonPackageService.restartServer for the marker + reconnect toast.
+    const serverUpdateService = new server_update_service_1.ServerUpdateService({
+        logger: loggingService.createLogger('ServerUpdate'),
+        restartServer: (requestedBy) => addonPackageService.restartServer(requestedBy),
+    });
+    const topologyEmitterService = new topology_emitter_service_1.TopologyEmitterService(eventBusService, agentRegistryService, addonRegistryService, (0, cap_providers_1.createNodeRootPackageLookup)(moleculerService, serverUpdateService));
     const postBootService = new post_boot_service_1.PostBootService(addonRegistryService, eventBusService, loggingService);
     // ---- Container ---------------------------------------------------------
     const container = new ServiceContainer();
@@ -224,6 +233,7 @@ async function bootManual(opts) {
     container.register(addon_search_service_1.AddonSearchService, addonSearchService);
     container.register(addon_package_service_1.AddonPackageService, addonPackageService);
     container.register(repl_engine_service_1.ReplEngineService, replEngineService);
+    container.register(server_update_service_1.ServerUpdateService, serverUpdateService);
     container.register(topology_emitter_service_1.TopologyEmitterService, topologyEmitterService);
     container.register(post_boot_service_1.PostBootService, postBootService);
     // ---- Fastify instance --------------------------------------------------