@camstack/server 1.0.4 → 1.0.6

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

@@ -35,6 +35,9 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AddonPackageService = exports.SYSTEM_PACKAGE = void 0;
 exports.isFrameworkPackage = isFrameworkPackage;
+exports.extractTgzStripped = extractTgzStripped;
+exports.sweepStaleFrameworkBackups = sweepStaleFrameworkBackups;
+exports.swapInFrameworkPackage = swapInFrameworkPackage;
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
 const os = __importStar(require("node:os"));
@@ -810,6 +813,112 @@ class AddonPackageService {
             return { success: false, version: '', requiresRestart: false, error: msg };
         }
     }
+    /**
+     * Apply a staged addon update without running npm — the fast swap-from-staged
+     * path. Mirrors the addon branch of `updatePackage` exactly, but calls
+     * `addonInstaller.applyUpdateFromStaged(name, version, stagedPath)` instead
+     * of `applyUpdate`/`installFromNpm`.
+     *
+     * The staged directory must already be validated and unpacked by the caller
+     * (e.g. the upload handler that previously called `installFromTgz`). This
+     * method performs the atomic swap, restarts the addon, and clears the backup
+     * on success — identical lifecycle to `updatePackage` addon branch.
+     */
+    async applyStagedAddonUpdate(name, version, stagedPath) {
+        if (!this.isAllowedPackage(name)) {
+            return {
+                success: false,
+                version: '',
+                requiresRestart: false,
+                error: `Package "${name}" is not an allowed @camstack/* package`,
+            };
+        }
+        const category = this.categorize(name);
+        this.logger.info('Applying staged addon update', { meta: { name, version, category } });
+        try {
+            if (category !== 'addon') {
+                return {
+                    success: false,
+                    version: '',
+                    requiresRestart: false,
+                    error: `applyStagedAddonUpdate only supports addon packages; "${name}" categorized as "${category}"`,
+                };
+            }
+            this.requireInstaller();
+            const addonInstaller = this.installer;
+            const previousVersion = this.getInstalledPackageVersion(name);
+            const r = await addonInstaller.applyUpdateFromStaged(name, version, stagedPath);
+            const updatedVersion = r.version;
+            // Update version in registry so UI reflects the change immediately
+            this.addonRegistry.refreshPackageVersion(name, updatedVersion);
+            // Emit addon.updated lifecycle event
+            this.addonRegistry.emitUpdateEvent(name, previousVersion, updatedVersion);
+            this.logger.info('Staged addon swap complete, triggering hot-reload', {
+                meta: { name, updatedVersion },
+            });
+            const addonId = this.extractAddonId(name);
+            if (addonId) {
+                try {
+                    await this.addonRegistry.restartAddon(addonId);
+                    this.logger.info('Addon restarted after staged update', { tags: { addonId } });
+                    // Restart succeeded — drop the backup
+                    addonInstaller.clearBackup(name);
+                }
+                catch (reloadError) {
+                    const msg = (0, types_1.errMsg)(reloadError);
+                    this.logger.warn('Hot-reload failed for addon — backup retained for rollback', {
+                        tags: { addonId },
+                        meta: { error: msg, backupDir: r.backupDir },
+                    });
+                }
+            }
+            // Clear update cache so next check reflects new state
+            this.cachedUpdates = null;
+            this.sendUpdateNotification(name, updatedVersion);
+            return { success: true, version: updatedVersion, requiresRestart: false };
+        }
+        catch (error) {
+            const msg = (0, types_1.errMsg)(error);
+            this.logger.error('Failed to apply staged addon update', { meta: { name, error: msg } });
+            return { success: false, version: '', requiresRestart: false, error: msg };
+        }
+    }
+    /**
+     * Download the npm tarball for `name@version` as a Buffer.
+     *
+     * Wraps the module-level `httpsDownloadTarball` for use by the
+     * lifecycle job engine (TarballFetcher signature). The `signal` is
+     * forwarded to the underlying fetch calls so the AbortController
+     * timeout wired in LifecycleJobEngine fires correctly.
+     */
+    async fetchAddonTarball(name, version, signal) {
+        const registry = process.env['CAMSTACK_NPM_REGISTRY'];
+        const reg = (registry ?? 'https://registry.npmjs.org').replace(/\/+$/, '');
+        const metaUrl = `${reg}/${encodeURIComponent(name).replace(/^%40/, '@')}`;
+        const metaRes = await fetch(metaUrl, { signal });
+        if (!metaRes.ok)
+            throw new Error(`registry GET ${metaUrl} → ${metaRes.status}`);
+        const meta = (await metaRes.json());
+        const tarballUrl = meta.versions?.[version]?.dist?.tarball;
+        if (typeof tarballUrl !== 'string') {
+            throw new Error(`no tarball url for ${name}@${version}`);
+        }
+        const tarRes = await fetch(tarballUrl, { signal });
+        if (!tarRes.ok)
+            throw new Error(`tarball GET ${tarballUrl} → ${tarRes.status}`);
+        return Buffer.from(await tarRes.arrayBuffer());
+    }
+    /**
+     * Extract a gzipped tarball Buffer into `destDir`.
+     *
+     * Wraps the existing `tar -xzf` shell call for use by the lifecycle job
+     * engine (ExtractFn signature). The Buffer is written to a temp file,
+     * extracted with `--strip-components=1` (removes the npm `package/` prefix),
+     * then the temp file is removed.
+     */
+    async extractTarball(tgz, destDir) {
+        await extractTgzStripped(tgz, destDir);
+    }
     /**
      * Gracefully restart the server process.
      *
@@ -916,32 +1025,160 @@ class AddonPackageService {
      * Returns BEFORE the exit fires so the admin UI receives `restartingAt`
      * and can pivot to the reconnect overlay.
      */
+    /**
+     * Install the framework by SWAPPING each package's own directory, exactly
+     * like every addon is installed (download the single-package tarball →
+     * extract → atomic dir swap). We NEVER run `npm install --prefix <appRoot>`.
+     *
+     * Why: `npm install --prefix /data` manages the WHOLE node_modules tree — it
+     * prunes every package not in @camstack/system's closure (the addons +
+     * ui-library), deletes the stray manifest.json, and (via temp-install + merge
+     * variants) can clobber working native bindings. A per-package tarball swap
+     * touches only that package's folder; nothing else can be pruned, deleted, or
+     * corrupted.
+     *
+     * Swaps the @camstack framework packages versioned in lockstep with system:
+     * the pure-JS libs (types, sdk) AND @camstack/shm-ring. shm-ring is native
+     * but SAFE to swap because it ships its compiled `.node` prebuilds INSIDE the
+     * npm tarball (prebuildify + node-gyp-build resolves the matching one at
+     * require-time) — a bare extract is sufficient, no build or download.
+     *
+     * It does NOT swap download/compile-on-install natives such as `better-sqlite3`
+     * (prebuild-install fetches the binary from GitHub releases at install time —
+     * a bare extract would leave it without a binding). Those are third-party,
+     * hoisted, change only across majors, and are updated by an image redeploy.
+     * System's own deps stay exactly where they are, bindings intact.
+     */
+    async installFrameworkPackages(packageName, toVersion, appRoot) {
+        const registry = process.env['CAMSTACK_NPM_REGISTRY'];
+        // @camstack/shm-ring is native but ships prebuilds in its tarball → safe.
+        const lockstepDeps = ['@camstack/types', '@camstack/sdk', '@camstack/shm-ring'];
+        const swapTargets = [packageName, ...lockstepDeps];
+        // Self-heal: a previous run killed mid-swap (e.g. process restart while a
+        // slow download was in flight) can leave a `<pkg>.fw-bak` backup behind.
+        // It's inert (not a valid package the loader picks up) but sweep it so the
+        // tree stays clean.
+        sweepStaleFrameworkBackups(appRoot);
+        const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'camstack-fw-'));
+        try {
+            for (const pkg of swapTargets) {
+                const isPrimary = pkg === packageName;
+                try {
+                    const tgzPath = await packTarball(pkg, toVersion, tmpRoot, registry);
+                    const extractDir = fs.mkdtempSync(path.join(tmpRoot, 'x-'));
+                    await execFileAsync('tar', ['-xzf', tgzPath, '-C', extractDir], { timeout: 60_000 });
+                    const result = swapInFrameworkPackage(path.join(extractDir, 'package'), appRoot);
+                    this.logger.info('updateFrameworkPackage: package swapped', {
+                        meta: { name: result.name, version: result.version },
+                    });
+                }
+                catch (err) {
+                    if (isPrimary)
+                        throw err;
+                    // A lockstep dep may not be published at this exact version (or the
+                    // download flaked) — keep the existing copy rather than fail the whole
+                    // framework update. System is the one that MUST succeed.
+                    this.logger.warn(`updateFrameworkPackage: lockstep dep ${pkg}@${toVersion} not swapped`, {
+                        meta: { error: (0, types_1.errMsg)(err) },
+                    });
+                }
+            }
+        }
+        finally {
+            fs.rmSync(tmpRoot, { recursive: true, force: true });
+        }
+    }
+    /**
+     * Resolve a version specifier (`'latest'`, semver tag, exact) for a
+     * framework package to a concrete version via `npm view`.
+     * Delegates to the module-level `resolveNpmVersion` helper.
+     * Exposed as a public method so the lifecycle job engine wiring in
+     * cap-providers can pass it as `resolveVersion` without duplicating the
+     * npm-view/manifest logic.
+     */
+    async resolveFrameworkVersion(packageName, versionSpec) {
+        return resolveNpmVersion(packageName, versionSpec, process.env['CAMSTACK_NPM_REGISTRY']);
+    }
+    /**
+     * Return the currently-installed version of a framework package, or `null`
+     * when it cannot be determined (not installed / no manifest).
+     * Delegates to the module-level `readResolvedPackageManifest` helper.
+     * Exposed as a public method for use by the lifecycle job engine wiring.
+     */
+    currentFrameworkVersionOf(packageName) {
+        const manifest = readResolvedPackageManifest(packageName);
+        if (manifest !== null && typeof manifest['version'] === 'string') {
+            return manifest['version'];
+        }
+        return null;
+    }
+    /**
+     * Update a framework package via the staged launcher-swap engine.
+     *
+     * New path (when `runner` is provided):
+     *   1. Resolve toVersion via `npm view`.
+     *   2. Delegate to `runner.startJob` with a `target:'framework'` task.
+     *      The engine calls `stageFramework` → downloads+stages the 4 lockstep
+     *      packages → calls the wired `requestFrameworkSwap`
+     *      (`requestFrameworkSwapAndRestart`), which writes the
+     *      `.pending-framework-swap.json` marker AND schedules the self-restart.
+     *      The hub exits; the launcher applies the swap on the next boot. The
+     *      restart is owned by that seam, so this method does NOT schedule one.
+     *   3. Return `{ packageName, fromVersion, toVersion, restartingAt }`.
+     *      `restartingAt = 0` only on the legacy in-hub path when `deferRestart`
+     *      is set (engine path always restarts once the framework is staged).
+     *
+     * Legacy path (when no `runner`): keeps the original in-hub live-swap for
+     * backward compatibility with callers (e.g. tests) that have not wired the
+     * engine deps.
+     */
     async updateFrameworkPackage(input) {
         const { packageName } = input;
         if (packageName !== exports.SYSTEM_PACKAGE) {
             throw new Error(`updateFrameworkPackage: '${packageName}' is not a framework package. Allowed: ${exports.SYSTEM_PACKAGE}`);
         }
-        const appRoot = resolveFrameworkPackageAppRoot(packageName, this.logger);
-        const fromManifest = readResolvedPackageManifest(packageName);
-        const fromVersion = fromManifest !== null && typeof fromManifest['version'] === 'string'
-            ? fromManifest['version']
-            : 'unknown';
+        const fromVersion = this.currentFrameworkVersionOf(packageName) ?? 'unknown';
         const requestedVersion = input.version ?? 'latest';
-        const toVersion = await resolveNpmVersion(packageName, requestedVersion, process.env['CAMSTACK_NPM_REGISTRY']);
-        const spec = `${packageName}@${toVersion}`;
-        this.logger.info('updateFrameworkPackage: installing', {
+        const toVersion = await this.resolveFrameworkVersion(packageName, requestedVersion);
+        // ── New staged-swap engine path ──────────────────────────────────
+        if (input.runner !== undefined) {
+            this.logger.info('updateFrameworkPackage: delegating to staged swap engine', {
+                meta: { packageName, fromVersion, toVersion, deferRestart: input.deferRestart ?? false },
+            });
+            await input.runner.startJob({
+                kind: 'update',
+                targets: [{ name: packageName, version: toVersion, target: 'framework' }],
+                createdBy: input.requestedBy ?? 'system',
+            });
+            // The engine's framework task already wrote the pending-swap marker AND
+            // scheduled the self-restart via the wired `requestFrameworkSwap`
+            // (`requestFrameworkSwapAndRestart`) — that is the single restart owner,
+            // so we must NOT schedule a second one here. We only surface the
+            // pre-restart toast event for the interactive single-update path.
+            if (input.deferRestart !== true) {
+                this.eventBusService.emit({
+                    id: (0, node_crypto_1.randomUUID)(),
+                    timestamp: new Date(),
+                    source: { type: 'core', id: 'addon-package-service' },
+                    category: types_1.EventCategory.SystemRestarting,
+                    data: {
+                        kind: 'framework-update',
+                        packageName,
+                        fromVersion,
+                        toVersion,
+                        requestedAt: Date.now(),
+                    },
+                });
+            }
+            const restartingAt = input.deferRestart === true ? 0 : Date.now() + 500;
+            return { packageName, fromVersion, toVersion, restartingAt };
+        }
+        // ── Legacy in-hub live-swap path (no runner injected) ───────────
+        const appRoot = resolveFrameworkPackageAppRoot(packageName, this.logger);
+        this.logger.info('updateFrameworkPackage: installing (legacy in-hub path)', {
             meta: { packageName, fromVersion, toVersion, appRoot },
         });
-        const registry = process.env['CAMSTACK_NPM_REGISTRY'];
-        const args = [
-            'install',
-            '--prefix',
-            appRoot,
-            spec,
-            '--no-save',
-            ...buildNpmRegistryArgs(registry),
-        ];
-        await execFileAsync('npm', args, { timeout: 180_000 });
+        await this.installFrameworkPackages(packageName, toVersion, appRoot);
         if (input.deferRestart === true) {
             this.logger.info(`updateFrameworkPackage(${packageName}@${toVersion}): install done, restart deferred`);
             // Sentinel: 0 signals "no restart scheduled" to the caller
@@ -1063,11 +1300,22 @@ class AddonPackageService {
             });
         }, intervalMs);
     }
-    /** Run auto-update: check each installed package against its configured channel */
+    /**
+     * Run auto-update: check each installed package against its configured
+     * channel, then route ALL packages that have a newer version through ONE
+     * durable engine bulk job (F3 Task 5). The framework (`@camstack/system`) is
+     * auto-detected by the engine and ordered LAST; auto-updates survive a reboot
+     * via the boot reconcile, exactly like a manual "Update all".
+     *
+     * Candidate selection (channel resolution + npm metadata fetch + "is there a
+     * newer version?" comparison) is unchanged from the previous per-item loop;
+     * only the EXECUTION moved from sequential `updatePackage` calls to a single
+     * `startJob`.
+     */
     async runAutoUpdate() {
         this.logger.info('Running auto-update check...');
         const installed = this.listInstalled();
-        let updatedCount = 0;
+        const targets = [];
         for (const pkg of installed) {
             try {
                 // Determine effective channel for this addon
@@ -1092,7 +1340,7 @@ class AddonPackageService {
                     : asString(distTags['latest']);
                 if (!targetVersion || targetVersion === pkg.version)
                     continue;
-                this.logger.info('Auto-updating package', {
+                this.logger.info('Auto-update candidate', {
                     meta: {
                         name: pkg.name,
                         currentVersion: pkg.version,
@@ -1100,18 +1348,34 @@ class AddonPackageService {
                         channel: effectiveChannel,
                     },
                 });
-                await this.updatePackage(pkg.name, targetVersion);
-                updatedCount++;
+                targets.push({ name: pkg.name, version: targetVersion });
             }
             catch (err) {
-                this.logger.warn('Auto-update failed', { meta: { name: pkg.name, error: (0, types_1.errMsg)(err) } });
+                this.logger.warn('Auto-update check failed', {
+                    meta: { name: pkg.name, error: (0, types_1.errMsg)(err) },
+                });
             }
         }
-        if (updatedCount > 0) {
-            this.logger.info('Auto-update complete', { meta: { updatedCount } });
-        }
-        else {
+        if (targets.length === 0) {
             this.logger.debug('Auto-update: all packages up-to-date');
+            return;
+        }
+        // Execute as ONE durable engine bulk job. The runner singleton is resolved
+        // lazily via a dynamic import (the singleton module transitively imports
+        // SYSTEM_PACKAGE back from this module) to avoid an init-order cycle. The
+        // singleton is initialized at boot, before the scheduler timer fires. The
+        // framework target, if present, is ordered last by the engine. Wrap so a
+        // failure is logged, not thrown out of the timer callback.
+        try {
+            const { getLifecycleRunner } = await Promise.resolve().then(() => __importStar(require('../lifecycle/lifecycle-runner.singleton.js')));
+            const runner = getLifecycleRunner();
+            const { jobId } = await runner.startJob({ kind: 'update', targets, createdBy: 'system' });
+            this.logger.info('Auto-update job started', {
+                meta: { jobId, packageCount: targets.length },
+            });
+        }
+        catch (err) {
+            this.logger.error('Auto-update job failed to start', { meta: { error: (0, types_1.errMsg)(err) } });
         }
     }
     // =========================================================================
@@ -1429,6 +1693,35 @@ class AddonPackageService {
 }
 exports.AddonPackageService = AddonPackageService;
 // ---------------------------------------------------------------------------
+// Tarball extraction helper (exported for regression tests)
+// ---------------------------------------------------------------------------
+/**
+ * Extract a gzipped tarball Buffer into `destDir`, stripping the npm
+ * `package/` top-level prefix so that the extracted `package.json` lands at
+ * `destDir/package.json` (not `destDir/package/package.json`).
+ *
+ * Uses `tar --strip-components=1` which mirrors what `installFromTgz` does
+ * when it reads `path.join(tmpDir, 'package')` after a plain extract and
+ * then uses that sub-directory as the source root.
+ *
+ * Exported so the regression spec in
+ * `src/core/addon/__tests__/extract-tarball-strip.spec.ts` can test the real
+ * implementation without instantiating `AddonPackageService`.
+ */
+async function extractTgzStripped(tgz, destDir) {
+    fs.mkdirSync(destDir, { recursive: true });
+    const tmpFile = path.join(os.tmpdir(), `camstack-tgz-${(0, node_crypto_1.randomUUID)()}.tgz`);
+    try {
+        fs.writeFileSync(tmpFile, tgz);
+        await execFileAsync('tar', ['--strip-components=1', '-xzf', tmpFile, '-C', destDir], {
+            timeout: 60_000,
+        });
+    }
+    finally {
+        fs.rmSync(tmpFile, { force: true });
+    }
+}
+// ---------------------------------------------------------------------------
 // Framework live-update helpers
 // ---------------------------------------------------------------------------
 /**
@@ -1451,6 +1744,131 @@ function buildNpmRegistryArgs(registry) {
         return [];
     return ['--registry', registry, `--@camstack:registry=${registry}`];
 }
+/**
+ * Remove any leftover `<pkg>.fw-bak` backup dirs under `appRoot/node_modules/
+ * @camstack` — debris from a framework swap that was interrupted before its
+ * own cleanup ran. Best-effort; returns the swept names.
+ */
+function sweepStaleFrameworkBackups(appRoot) {
+    const scopeDir = path.join(appRoot, 'node_modules', '@camstack');
+    if (!fs.existsSync(scopeDir))
+        return [];
+    const swept = [];
+    for (const entry of fs.readdirSync(scopeDir, { withFileTypes: true })) {
+        if (!entry.isDirectory() || !entry.name.endsWith('.fw-bak'))
+            continue;
+        try {
+            fs.rmSync(path.join(scopeDir, entry.name), { recursive: true, force: true });
+            swept.push(entry.name);
+        }
+        catch {
+            // ignore — inert leftover, next sweep retries
+        }
+    }
+    return swept;
+}
+/**
+ * Download the `.tgz` for an EXACT `pkg@version` into `destRoot`, returning its
+ * path. Prefers a direct HTTPS GET (registry metadata → tarball URL) because
+ * `fetch` + `AbortSignal.timeout` aborts RELIABLY on a slow/flaky network — an
+ * `npm pack` child can stall for minutes past its `execFile` timeout (npm holds
+ * its stdio pipes open, so the awaited promise never settles), which would wedge
+ * the whole framework update. Falls back to `npm pack` (SIGKILL on timeout) only
+ * when the HTTPS path fails (private registry quirks, auth, etc.).
+ */
+async function packTarball(pkg, version, destRoot, registry) {
+    const dir = fs.mkdtempSync(path.join(destRoot, 'dl-'));
+    try {
+        return await httpsDownloadTarball(pkg, version, dir, registry);
+    }
+    catch (httpErr) {
+        const args = [
+            'pack',
+            `${pkg}@${version}`,
+            '--pack-destination',
+            dir,
+            ...buildNpmRegistryArgs(registry),
+        ];
+        // SIGKILL (not the default SIGTERM): npm can ignore SIGTERM while a
+        // grandchild holds the pipes — SIGKILL guarantees the timeout fires.
+        await execFileAsync('npm', args, { timeout: 60_000, killSignal: 'SIGKILL' });
+        const tgz = fs.readdirSync(dir).find((f) => f.endsWith('.tgz'));
+        if (tgz === undefined) {
+            throw new Error(`download failed for ${pkg}@${version}: ${(0, types_1.errMsg)(httpErr)}`);
+        }
+        return path.join(dir, tgz);
+    }
+}
+/**
+ * Direct HTTPS download of an exact `pkg@version` tarball. Resolves the tarball
+ * URL from the registry packument, then streams it to a file. Every network
+ * call is bounded by an `AbortSignal.timeout` so a DNS/registry stall fails fast
+ * instead of hanging the framework update.
+ */
+async function httpsDownloadTarball(pkg, version, dir, registry) {
+    const reg = (registry ?? 'https://registry.npmjs.org').replace(/\/+$/, '');
+    const metaUrl = `${reg}/${encodeURIComponent(pkg).replace(/^%40/, '@')}`;
+    const metaRes = await fetch(metaUrl, { signal: AbortSignal.timeout(20_000) });
+    if (!metaRes.ok)
+        throw new Error(`registry GET ${metaUrl} → ${metaRes.status}`);
+    const meta = (await metaRes.json());
+    const tarballUrl = meta.versions?.[version]?.dist?.tarball;
+    if (typeof tarballUrl !== 'string') {
+        throw new Error(`no tarball url for ${pkg}@${version}`);
+    }
+    const tarRes = await fetch(tarballUrl, { signal: AbortSignal.timeout(120_000) });
+    if (!tarRes.ok)
+        throw new Error(`tarball GET ${tarballUrl} → ${tarRes.status}`);
+    const buf = Buffer.from(await tarRes.arrayBuffer());
+    const outPath = path.join(dir, `${pkg.replace('@', '').replace('/', '-')}-${version}.tgz`);
+    fs.writeFileSync(outPath, buf);
+    return outPath;
+}
+/**
+ * Atomically replace one `@camstack/*` package directory in
+ * `appRoot/node_modules` with the contents of an extracted npm package dir
+ * (`stagedPackageDir` = the `package/` folder from a `.tgz`).
+ *
+ * This is the framework-update primitive: it touches ONLY the target package's
+ * folder. The current copy is renamed to a sibling `.fw-bak` backup first and
+ * restored if the copy fails, so a crash mid-swap can't leave a half-written
+ * package. Refuses anything outside the `@camstack/` scope as a safety guard.
+ * Returns the installed package name + version.
+ */
+function swapInFrameworkPackage(stagedPackageDir, appRoot) {
+    const pkgJsonPath = path.join(stagedPackageDir, 'package.json');
+    if (!fs.existsSync(pkgJsonPath)) {
+        throw new Error(`swapInFrameworkPackage: no package.json in ${stagedPackageDir}`);
+    }
+    const parsed = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf-8'));
+    const pkg = parsed;
+    if (typeof pkg.name !== 'string' || typeof pkg.version !== 'string') {
+        throw new Error(`swapInFrameworkPackage: invalid package.json in ${stagedPackageDir}`);
+    }
+    if (!pkg.name.startsWith('@camstack/')) {
+        throw new Error(`swapInFrameworkPackage: refusing non-@camstack package ${pkg.name}`);
+    }
+    const targetDir = path.join(appRoot, 'node_modules', pkg.name);
+    const backupDir = `${targetDir}.fw-bak`;
+    fs.rmSync(backupDir, { recursive: true, force: true });
+    const hadExisting = fs.existsSync(targetDir);
+    if (hadExisting)
+        fs.renameSync(targetDir, backupDir);
+    try {
+        fs.mkdirSync(path.dirname(targetDir), { recursive: true });
+        fs.cpSync(stagedPackageDir, targetDir, { recursive: true });
+    }
+    catch (err) {
+        // Roll back to the previous copy so a failed swap never leaves the
+        // package missing or half-written.
+        fs.rmSync(targetDir, { recursive: true, force: true });
+        if (hadExisting)
+            fs.renameSync(backupDir, targetDir);
+        throw err;
+    }
+    fs.rmSync(backupDir, { recursive: true, force: true });
+    return { name: pkg.name, version: pkg.version };
+}
 /**
  * Resolve the directory whose `node_modules/<pkg>/` holds the currently-
  * installed copy of a framework package. `npm install --prefix <appRoot>`

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

@@ -1358,13 +1358,27 @@ class AddonRegistryService {
                     // the group-runner crashed for real, `$node.disconnected`
                     // surfaces it through the health monitor; the operator can
                     // always click Cancel on the UI mutation.
-                    const waits = declared.map((cap) => this.capabilityRegistry.waitForProvider(cap.name, addonId, Number.POSITIVE_INFINITY));
+                    // Wait for declared caps to re-register, but BOUNDED — and on timeout
+                    // do NOT throw. DEVICE-SCOPED caps (e.g. a camera provider's
+                    // `device-provider` / `snapshot-provider`) only ever register once
+                    // devices exist; on a hub with none they NEVER come back, so an
+                    // infinite wait hangs the whole update — and the lifecycle job that
+                    // drives it (apply task stuck at `applying`, framework-last blocked,
+                    // the job uncancellable). The on-disk swap + runner restart have
+                    // already succeeded here; any caps still pending re-register
+                    // asynchronously as their devices come online. We only WARN which
+                    // caps were still pending (the comment's original objection was a
+                    // *misleading error* on timeout — a warning avoids that while still
+                    // letting the update finalize).
+                    const REGISTER_WAIT_MS = 120_000;
+                    const waits = declared.map((cap) => this.capabilityRegistry.waitForProvider(cap.name, addonId, REGISTER_WAIT_MS));
                     const settled = await Promise.all(waits);
                     const missing = declared
                         .map((cap, i) => (settled[i] == null ? cap.name : null))
                         .filter((name) => name !== null);
                     if (missing.length > 0) {
-                        throw new Error(`Addon "${addonId}" restarted but did not re-register capabilities in time: ${missing.join(', ')}`);
+                        this.logger.warn(`Addon "${addonId}" restarted; ${missing.length} capability(ies) not yet re-registered ` +
+                            `(re-register asynchronously — e.g. device-scoped caps awaiting devices): ${missing.join(', ')}`, { tags: { addonId } });
                     }
                 }
                 // Re-register the addon's custom-action catalog. `$process.restart`

package/dist/core/agent/agent-registry.service.js

@@ -39,6 +39,36 @@ const os = __importStar(require("node:os"));
 const types_1 = require("@camstack/types");
 /** Per-call timeout for `$agent.*` RPC during reconciliation. */
 const AGENT_RECONCILE_RPC_TIMEOUT_MS = 8_000;
+/**
+ * Package name of the system/infrastructure builtins. Addons shipped in
+ * `@camstack/system` (filesystem-storage, storage-orchestrator,
+ * sqlite-settings, hub-forwarder, metrics-native, console-logging, …) are
+ * bootstrap infrastructure that EVERY node — hub and agent alike — runs
+ * in-process. They are never `$agent.deploy`-pushed and must NEVER be
+ * undeployed by reconciliation: tearing them down on an agent destroys its
+ * own storage/settings/metrics/logging and bricks the node. This is the
+ * same canonical "core builtin" predicate the hub uses in
+ * `AddonRegistryService.buildAddonGroupPlan`.
+ */
+/**
+ * Agent bootstrap-infrastructure packages — seeded by the agent's own
+ * `AGENT_PACKAGES` bootstrap, NEVER hub-managed deploy targets, so the
+ * reconcile must never undeploy them (they are absent from the hub's
+ * installed-addon set and would otherwise look "stale"):
+ *   - `@camstack/system`        — storage/settings/metrics/logging builtins.
+ *   - `@camstack/addon-agent-ui` — the agent's own status dashboard
+ *     (placement: agent-only; the hub never installs it, so it is missing
+ *     from `hubPlacements`). The hub's deploy planner already SKIPS
+ *     agent-only addons, so undeploying one is a reconcile asymmetry bug.
+ *
+ * The hub cannot consult `AddonInstaller.AGENT_PACKAGES` directly: it
+ * derives from `@camstack/agent`, which is not installed in a hub image,
+ * so that list is empty hub-side. Hence this explicit allowlist.
+ */
+const AGENT_BOOTSTRAP_PACKAGES = new Set([
+    '@camstack/system',
+    '@camstack/addon-agent-ui',
+]);
 class AgentRegistryService {
     eventBus;
     moleculer;
@@ -229,6 +259,16 @@ class AgentRegistryService {
                 hubPlacements.set(declId, (0, types_1.resolveAddonPlacement)(decl));
             }
             const stale = agentAddons.filter((addon) => {
+                // Agent bootstrap infrastructure (storage/settings/metrics/logging from
+                // `@camstack/system`, plus the agent-only `addon-agent-ui` dashboard)
+                // runs on every node as bootstrap infrastructure — never hub-managed
+                // deploy targets, must never be undeployed. Without this guard the
+                // reconcile tears down the agent's own builtins (they aren't in the
+                // hub's installed-addon set, so they look "stale"), which bricks the
+                // agent and makes it permanently unroutable. See AGENT_BOOTSTRAP_PACKAGES.
+                if (addon.packageName !== undefined && AGENT_BOOTSTRAP_PACKAGES.has(addon.packageName)) {
+                    return false;
+                }
                 const placement = hubPlacements.get(addon.id);
                 // Not installed on the hub → stale.
                 if (placement === undefined)
@@ -281,7 +321,9 @@ class AgentRegistryService {
             const id = entry.id;
             if (typeof id !== 'string' || id.length === 0)
                 continue;
-            result.push({ id });
+            // Preserve `packageName` — the reconcile uses it to skip system builtins.
+            const packageName = entry.packageName;
+            result.push({ id, packageName: typeof packageName === 'string' ? packageName : undefined });
         }
         return result;
     }