@camstack/server 1.2.704 → 1.2.706

package/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.2.706] - 2026-10-31
+
+### Changed
+
+- The hub now owns every node's addon set: nodes converge to the hub's any-node addons and tracked agent-ui on connect, after a hub install or uninstall, and every 10 minutes (dry run until addons.convergence.dryRun is set to false); updating agent-ui from the hub now reaches every agent
+
+## [1.2.705] - 2026-10-31
+
+### Fixed
+
+- A node agent stopped by a signal now shuts down within 15 seconds and logs what started it, instead of hanging while looking alive but deregistered
+
 ## [1.2.704] - 2026-10-30
 
 ### Changed

package/dist/agent/agent-shutdown.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SHUTDOWN_DEADLINE_MS = exports.SHUTDOWN_STEP_TIMEOUT_MS = void 0;
+exports.createAgentShutdown = createAgentShutdown;
+exports.SHUTDOWN_STEP_TIMEOUT_MS = 5_000;
+exports.SHUTDOWN_DEADLINE_MS = 15_000;
+function errMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+async function runBounded(step, timeoutMs) {
+    let timer;
+    const timeout = new Promise((resolve) => {
+        timer = setTimeout(() => resolve('timed-out'), timeoutMs);
+    });
+    try {
+        return await Promise.race([step.run().then(() => 'done'), timeout]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** Returns `shutdown(reason)`; `reason` names the signal or caller that started it. */
+function createAgentShutdown(deps) {
+    const stepTimeoutMs = deps.stepTimeoutMs ?? exports.SHUTDOWN_STEP_TIMEOUT_MS;
+    const deadlineMs = deps.deadlineMs ?? exports.SHUTDOWN_DEADLINE_MS;
+    const { logger } = deps;
+    let startedAt = null;
+    return async (reason) => {
+        if (startedAt !== null) {
+            logger.error(`shutdown already in progress for ${Date.now() - startedAt}ms; ${reason} forces exit`);
+            deps.exit(1);
+            return;
+        }
+        const began = Date.now();
+        startedAt = began;
+        logger.info(`shutdown started by ${reason}`);
+        const deadline = setTimeout(() => {
+            logger.error(`shutdown deadline of ${deadlineMs}ms exceeded (started by ${reason}); exiting 1`);
+            deps.exit(1);
+        }, deadlineMs);
+        for (const step of deps.steps) {
+            const stepStart = Date.now();
+            try {
+                const outcome = await runBounded(step, stepTimeoutMs);
+                const took = `${Date.now() - stepStart}ms`;
+                if (outcome === 'timed-out') {
+                    logger.warn(`shutdown step ${step.name} timed out after ${took}; continuing`);
+                }
+                else {
+                    logger.info(`shutdown step ${step.name} done in ${took}`);
+                }
+            }
+            catch (err) {
+                logger.warn(`shutdown step ${step.name} failed after ${Date.now() - stepStart}ms: ${errMessage(err)}`);
+            }
+        }
+        clearTimeout(deadline);
+        logger.info(`shutdown finished in ${Date.now() - began}ms (started by ${reason})`);
+        deps.exit(0);
+    };
+}

package/dist/agent/main.js

@@ -48,6 +48,7 @@ const addon_scan_js_1 = require("./addon-scan.js");
 const agent_addon_updates_js_1 = require("./agent-addon-updates.js");
 const agent_hub_registration_js_1 = require("./agent-hub-registration.js");
 const agent_mesh_gate_js_1 = require("./agent-mesh-gate.js");
+const agent_shutdown_js_1 = require("./agent-shutdown.js");
 const agent_pairing_local_js_1 = require("./agent-pairing-local.js");
 const agent_membership_watch_js_1 = require("./agent-membership-watch.js");
 const agent_pairing_store_js_1 = require("./agent-pairing-store.js");
@@ -1071,34 +1072,49 @@ async function startAgent(configPath) {
     }).then((listener) => {
         agentHttpListener = listener;
     });
-    // Graceful shutdown
-    const shutdown = async () => {
-        console.log('[Agent] Shutting down...');
-        // Abort any in-flight upward hub registration retry loop.
-        registerAbortController.abort();
-        // Dispose the UDS event bridge to remove the parent-bus subscriber and
-        // clear the child-event handler, preventing subscriber leaks on shutdown.
-        udsEventBridgeDispose?.();
-        udsEventBridgeDispose = null;
-        for (const [, entry] of loadedAddons) {
-            if (entry.addon?.shutdown) {
-                try {
-                    await entry.addon.shutdown();
-                }
-                catch {
-                    /* */
-                }
-            }
-        }
-        // Withdraw the mDNS advertisement, then stop accepting new HTTP/HTTPS connections before
-        // the broker goes away.
-        await agentMdns.stop().catch(() => undefined);
-        await agentHttpListener?.close().catch(() => undefined);
-        await broker.stop();
-        process.exit(0);
-    };
-    process.on('SIGTERM', shutdown);
-    process.on('SIGINT', shutdown);
+    // Graceful shutdown: bounded, re-entry guarded, and it logs what started it (agent-shutdown.ts).
+    const shutdown = (0, agent_shutdown_js_1.createAgentShutdown)({
+        logger: consoleLogger,
+        exit: (code) => process.exit(code),
+        steps: [
+            {
+                name: 'abort-registration',
+                run: async () => {
+                    // Abort any in-flight upward hub registration retry loop.
+                    registerAbortController.abort();
+                    // Dispose the UDS event bridge to remove the parent-bus subscriber and
+                    // clear the child-event handler, preventing subscriber leaks on shutdown.
+                    udsEventBridgeDispose?.();
+                    udsEventBridgeDispose = null;
+                },
+            },
+            {
+                name: 'addons',
+                // Concurrent: one slow addon must not eat the budget of the others.
+                run: async () => {
+                    const stops = [];
+                    for (const [addonId, entry] of loadedAddons) {
+                        if (!entry.addon?.shutdown)
+                            continue;
+                        const began = Date.now();
+                        stops.push(Promise.resolve()
+                            .then(() => entry.addon?.shutdown?.())
+                            .then(() => undefined)
+                            .catch((err) => consoleLogger.warn(`addon ${addonId} shutdown failed: ${(0, types_2.errMsg)(err)}`))
+                            .finally(() => consoleLogger.info(`addon ${addonId} shutdown took ${Date.now() - began}ms`)));
+                    }
+                    await Promise.all(stops);
+                },
+            },
+            // Withdraw the mDNS advertisement, then stop accepting new HTTP/HTTPS connections before
+            // the broker goes away.
+            { name: 'mdns', run: () => agentMdns.stop() },
+            { name: 'http-listener', run: async () => void (await agentHttpListener?.close()) },
+            { name: 'broker', run: () => broker.stop() },
+        ],
+    });
+    process.on('SIGTERM', () => void shutdown('SIGTERM'));
+    process.on('SIGINT', () => void shutdown('SIGINT'));
     // An unpaired agent has no hub to read settings from (D857): serve pairing only and
     // relaunch after the certificate is installed (D5). See agent-boot-mode.ts.
     if (!addonsBooted) {

package/dist/api/addon-upload.js

@@ -124,7 +124,13 @@ resolveClusterBaseUrl,
  * opens for a node that lost its addons. Optional so route unit tests need
  * not build one; `main.ts` always passes the AgentRegistryService's.
  */
-deliveryLedger) {
+deliveryLedger, 
+/**
+ * The D982 convergence: an explicit delivery to one node lifts its tombstone,
+ * and a hub install asks for a convergence round. Optional so route unit tests
+ * need not build one; `main.ts` passes the AgentRegistryService.
+ */
+convergence) {
     await fastify.register(Promise.resolve().then(() => __importStar(require('@fastify/multipart'))), {
         limits: { fileSize: MAX_UPLOAD_BYTES },
     });
@@ -181,10 +187,10 @@ deliveryLedger) {
         // the package's addons (i.e. anything not marked hub-only). Any other
         // explicit `nodeId` value routes only to that agent via `$agent.deploy`.
         if (!nodeId || nodeId === 'hub') {
-            return installToHub(reply, addonBridge, addonRegistry, addonPackageService, moleculer, logger, data.filename, buffer, resolveClusterBaseUrl, deliveryLedger);
+            return installToHub(reply, addonBridge, addonRegistry, addonPackageService, moleculer, logger, data.filename, buffer, resolveClusterBaseUrl, deliveryLedger, convergence);
         }
         const agentAddonId = addonIdHint ?? manifest.name;
-        return deployToAgent(reply, moleculer, logger, nodeId, agentAddonId, buffer, resolveClusterBaseUrl, deliveryLedger);
+        return deployToAgent(reply, moleculer, logger, nodeId, agentAddonId, buffer, resolveClusterBaseUrl, deliveryLedger, convergence);
     });
 }
 /**
@@ -276,7 +282,7 @@ async function propagateToAgents(moleculer, logger, packageName, buffer, resolve
  * Without this the CLI push was write-to-disk-only and required a server
  * restart to actually run the new code.
  */
-async function installToHub(reply, addonBridge, addonRegistry, addonPackageService, moleculer, logger, filename, buffer, resolveClusterBaseUrl, deliveryLedger) {
+async function installToHub(reply, addonBridge, addonRegistry, addonPackageService, moleculer, logger, filename, buffer, resolveClusterBaseUrl, deliveryLedger, convergence) {
     const tmpDir = path.join(os.tmpdir(), `camstack-addon-upload-${Date.now()}`);
     fs.mkdirSync(tmpDir, { recursive: true });
     const tgzPath = path.join(tmpDir, filename);
@@ -405,8 +411,12 @@ async function installToHub(reply, addonBridge, addonRegistry, addonPackageServi
                 logger.info('propagation done', {
                     meta: { packageName: result.name, agents: agentResults },
                 });
+                void convergence?.requestConvergence('hub-change');
             });
         }
+        else {
+            void convergence?.requestConvergence('hub-change');
+        }
         return reply.send({
             success: true,
             target: 'hub',
@@ -432,7 +442,7 @@ async function installToHub(reply, addonBridge, addonRegistry, addonPackageServi
  * evidence. The response now carries what was reloaded and what was verified,
  * so the CLI can print facts instead of a bare tick.
  */
-async function deployToAgent(reply, moleculer, logger, nodeId, addonId, buffer, resolveClusterBaseUrl, deliveryLedger) {
+async function deployToAgent(reply, moleculer, logger, nodeId, addonId, buffer, resolveClusterBaseUrl, deliveryLedger, convergence) {
     const hubBaseUrl = await resolveBaseUrlOrReason(resolveClusterBaseUrl);
     if (!hubBaseUrl.ok) {
         logger.error('agent deploy: no hub address the agent can reach — nothing delivered', {
@@ -457,6 +467,8 @@ async function deployToAgent(reply, moleculer, logger, nodeId, addonId, buffer,
     if (!result.success) {
         return reply.status(502).send({ error: `Agent deploy failed: ${result.error ?? 'unknown'}` });
     }
+    // An operator's explicit delivery to this node lifts its tombstone (D982).
+    await convergence?.noteExplicitDelivery(nodeId, addonId);
     return reply.send({
         success: true,
         target: nodeId,

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

@@ -79,6 +79,7 @@ const server_1 = require("@trpc/server");
 const integration_id_backfill_1 = require("../../boot/integration-id-backfill");
 const addon_package_service_js_1 = require("../../core/addon/addon-package.service.js");
 const addon_uninstall_js_1 = require("../../core/addon/addon-uninstall.js");
+const agent_desired_set_1 = require("../../core/agent/agent-desired-set");
 const lifecycle_runner_singleton_js_1 = require("../../core/lifecycle/lifecycle-runner.singleton.js");
 const agent_installed_packages_js_1 = require("../../core/updates/agent-installed-packages.js");
 const http_request_census_singleton_js_1 = require("../trpc/http-request-census.singleton.js");
@@ -1517,6 +1518,20 @@ function buildAddonsProvider(ar, ps, ls, moleculer, configService, ctx, agentReg
     const broker = (0, system_1.asBrokerLike)(moleculer.broker);
     const uninstallSeam = buildUninstallSeam(ar, ps, broker, agentRegistry);
     const frameworkAllowSet = new Set([addon_package_service_js_1.SYSTEM_PACKAGE]);
+    // D982: a hub install / update / uninstall changes every node's desired set.
+    // Fire-and-forget — the round never gates the operator's call, and bursts
+    // collapse into one extra round inside `requestConvergence`.
+    const requestHubChangeConvergence = () => {
+        void agentRegistry?.requestConvergence('hub-change');
+    };
+    // Ship an already-packed tarball to one agent and reload it. The reload
+    // re-instantiates the changed package's addons; for a large package (the whole
+    // pipeline stack) that can take well over a minute, so allow generous headroom
+    // — a timeout here aborts the call even though the deploy already landed.
+    const deployPackedToAgent = async (agentNodeId, packageName, bundle) => {
+        await broker.call('$agent.deploy', { addonId: packageName, bundle }, { nodeID: agentNodeId, timeout: 300_000 });
+        await broker.call('$agent.reload', {}, { nodeID: agentNodeId, timeout: 300_000 });
+    };
     // Process-wide runner built once at boot (manual-boot wires its deps from the
     // addon-package service + event bus). `createdBy` travels per `startJob` call.
     const lifecycleRunner = (0, lifecycle_runner_singleton_js_1.getLifecycleRunner)();
@@ -1573,13 +1588,23 @@ function buildAddonsProvider(ar, ps, ls, moleculer, configService, ctx, agentReg
             level: input.level,
         }),
         listPackages: async () => ps.listInstalled(),
-        installPackage: async (input) => ps.installAndLoad(input.packageName, input.version),
-        installFromWorkspace: async (input) => ps.installFromWorkspaceAndLoad(input.packageName),
+        installPackage: async (input) => {
+            const result = await ps.installAndLoad(input.packageName, input.version);
+            requestHubChangeConvergence();
+            return result;
+        },
+        installFromWorkspace: async (input) => {
+            const result = await ps.installFromWorkspaceAndLoad(input.packageName);
+            requestHubChangeConvergence();
+            return result;
+        },
         isWorkspaceAvailable: async () => ps.isWorkspaceAvailable(),
         listWorkspacePackages: async () => ps.listWorkspacePackages(),
         uninstallPackage: async (input) => {
             try {
-                return await (0, addon_uninstall_js_1.uninstallPackage)(uninstallSeam, input);
+                const result = await (0, addon_uninstall_js_1.uninstallPackage)(uninstallSeam, input);
+                requestHubChangeConvergence();
+                return result;
             }
             catch (err) {
                 if (err instanceof addon_uninstall_js_1.PackageProtectedError) {
@@ -1607,6 +1632,32 @@ function buildAddonsProvider(ar, ps, ls, moleculer, configService, ctx, agentReg
         },
         updatePackage: async (input) => {
             const nodeId = input.nodeId;
+            if ((0, agent_desired_set_1.isAgentTrackedPackage)(input.name) && (nodeId === undefined || isHubNode(nodeId))) {
+                // An agent-only package the hub tracks without loading it (agent-ui, D982):
+                // there is nothing to update on the hub, so the update fans out to every
+                // online agent instead of failing with "not currently tracked in manifest".
+                if (agentRegistry === undefined) {
+                    return {
+                        success: false,
+                        error: `${input.name} is delivered by the agent registry, which is not wired`,
+                    };
+                }
+                const packed = await ps.packPackage(input.name, input.version);
+                const targets = agentRegistry.onlineAgentIds();
+                const failures = [];
+                for (const target of targets) {
+                    try {
+                        await deployPackedToAgent(target, input.name, packed.buffer);
+                        await agentRegistry.noteExplicitDelivery(target, input.name);
+                    }
+                    catch (err) {
+                        failures.push(`${target}: ${err instanceof Error ? err.message : String(err)}`);
+                    }
+                }
+                if (failures.length > 0)
+                    return { success: false, error: failures.join('; ') };
+                return { success: true, name: input.name, version: packed.version };
+            }
             if (nodeId === undefined || isHubNode(nodeId)) {
                 // Hub-single: route through the lifecycle job engine so the fast
                 // staged-swap path (applyStagedAddonUpdate) is always used.
@@ -1619,6 +1670,7 @@ function buildAddonsProvider(ar, ps, ls, moleculer, configService, ctx, agentReg
                 const job = lifecycleRunner.getJob(jobId);
                 const task = job?.tasks[0];
                 if (task?.phase === 'done') {
+                    requestHubChangeConvergence();
                     return { success: true, name: input.name, version, jobId };
                 }
                 return { success: false, error: task?.error ?? 'update failed', jobId };
@@ -1646,8 +1698,9 @@ function buildAddonsProvider(ar, ps, ls, moleculer, configService, ctx, agentReg
             // minute, so allow generous headroom — a timeout here aborts the call
             // even though the deploy already landed on disk.
             const packed = await ps.packPackage(input.name, input.version);
-            await broker.call('$agent.deploy', { addonId: input.name, bundle: packed.buffer }, { nodeID: nodeId, timeout: 300_000 });
-            await broker.call('$agent.reload', {}, { nodeID: nodeId, timeout: 300_000 });
+            await deployPackedToAgent(nodeId, input.name, packed.buffer);
+            // An operator's explicit delivery lifts the node's tombstone (D982).
+            await agentRegistry?.noteExplicitDelivery(nodeId, input.name);
             return { success: true, name: input.name, version: packed.version, nodeId };
         },
         rollbackPackage: async (input) => ps.rollbackPackage(input.name),

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

@@ -752,6 +752,14 @@ class AddonPackageService {
             fs.rmSync(destDir, { recursive: true, force: true });
         }
     }
+    /**
+     * The version the registry serves as `latest` for a package — what the hub
+     * follows for an agent-only package it tracks without installing (D982).
+     * Throws when the registry cannot answer.
+     */
+    async resolveRegistryVersion(name) {
+        return resolveNpmVersion(name, 'latest', process.env['CAMSTACK_NPM_REGISTRY']);
+    }
     /**
      * Resolve `name@version` and `npm pack` it into a tarball buffer
      * WITHOUT installing. Used to push a package update to an agent: the

package/dist/core/agent/agent-addon-backfill.js

@@ -1,155 +1,45 @@
 "use strict";
 /**
- * Node addon back-fill — converge a node to the addon roster THAT NODE last
- * declared.
+ * Node addon delivery — the bookkeeping that carries a convergence plan to a
+ * node: the trigger allowlist, the delivery circuit breaker, the confirmation
+ * read and the execution seam.
  *
- * WHY THIS EXISTS
- * `AgentRegistryService.reconcileAgentAddons` used to be undeploy-only: it read
- * the node's live roster, removed what no longer belonged, and had no branch for
- * "installed on the hub but missing on the node". A node whose `<dataDir>/addons`
- * had been wiped therefore came back with only its bootstrap packages
- * (`@camstack/system` + `camstack.agentBootstrapAddons`) and the hub never sent
- * the rest — measured live as 4 of 14 packages on `agent-a`. Under the
- * volume-only image (no addons baked in) an empty addons dir is the ORDINARY
- * first-boot state of every new or rebuilt node, so that gap becomes the normal
- * case rather than an anomaly.
+ * WHAT A NODE SHOULD HAVE is decided in `agent-desired-set.ts`
+ * ([D982](../../../../docs/decisions/adr-0982-the-hub-owns-every-nodes-addon-set.md)):
+ * the hub's desired set, never the roster the node declared. This module only
+ * delivers a computed plan, and is seam-driven so that is tested with no
+ * Moleculer, filesystem or npm registry.
  *
- * THE INTENDED SET
- * A node's intended set is the roster the node itself last declared while
- * online, remembered durably hub-side (`ClusterNodeHistoryStore`). It is not
- * invented by the hub and it is not "every agent-deployable package the hub has
- * installed" — that would over-install and would override deliberate per-node
- * operator choices. The record GROWS when a node declares a package and SHRINKS
- * only on an explicit undeploy (operator gesture or the stale-reconcile), so
- * both mutations are attributable actions rather than heuristics.
- *
- * THE INTENDED VERSION
- * The hub's own installed version, and only that — including when the node
- * is AHEAD of the hub (D942). Never npm `latest` directly: the hub follows
- * the registry, and every node follows the hub. A package the hub's version
- * map does not name is left as it is when it is already installed, and is
- * never delivered when it is missing (`notOnHub`). An unreadable hub version
- * is not a reason to move.
- *
- * A package the hub does NOT install is never delivered, whatever the node last
- * reported. It used to fall back to the node's last-reported version, which
- * made the back-fill the one path that could put an UNINSTALLED addon back: an
- * operator removes `@camstack/addon-decoder-ffmpeg` from the hub and moves the
- * agent's copy aside, and the next reconnect reinstalled it from npm at the
- * version the node last ran — while the same pass's stale sweep exists to
- * remove exactly such an addon. The two directions disagreed; now the hub's
- * install set bounds both. Such packages are reported as `notOnHub`.
+ * THE VERSION is the hub's own installed version, and only that — including when
+ * the node is AHEAD of the hub (D942). Never npm `latest` directly for a package
+ * the hub installs: the hub follows the registry, and every node follows the hub.
+ * An agent-only package the hub tracks (agent-ui) is delivered at the registry
+ * version the hub resolved for it.
  *
  * BOUNDING
  * Delivery failures are counted per `(node, package, version)` and the pair is
  * retired after {@link MAX_BACKFILL_ATTEMPTS}, exactly as `CrashSupervisor`
- * bounds respawns (D6). A reconnect flap therefore cannot turn a broken package
- * into an endless push loop. A different hub version resets the count — a new
- * version is a new fact worth one more attempt.
- *
- * This module is pure/seam-driven on purpose: the decision of what a node should
- * have is asserted in unit tests with no Moleculer, filesystem or npm registry.
+ * bounds respawns (D6). A reconnect flap or a periodic round therefore cannot
+ * turn a broken package into an endless push loop. A different hub version
+ * resets the count — a new version is a new fact worth one more attempt.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BackfillAttemptTracker = exports.MAX_BACKFILL_ATTEMPTS = void 0;
 exports.triggerMayDeliver = triggerMayDeliver;
-exports.freshNodeSkipReason = freshNodeSkipReason;
-exports.computeBackfillPlan = computeBackfillPlan;
 exports.confirmBackfillPlan = confirmBackfillPlan;
 exports.executeBackfill = executeBackfill;
-const system_1 = require("@camstack/system");
 /** Triggers permitted to install packages onto a node. */
 const DELIVERING_TRIGGERS = new Set([
     'node-registration',
     'hub-boot',
     'operator-repair',
+    'periodic',
+    'hub-change',
 ]);
 /** Is this trigger allowed to put bytes on a node? */
 function triggerMayDeliver(trigger) {
     return DELIVERING_TRIGGERS.has(trigger);
 }
-/**
- * Why a hub package may not go to a fresh node, or `null` when it may.
- * A package with a hub-only addon is refused whole: the stale sweep would
- * undeploy that addon and with it the shared bundle directory.
- */
-function freshNodeSkipReason(placements) {
-    if (placements.includes('hub-only'))
-        return 'hub-only placement';
-    if (!placements.includes('any-node'))
-        return 'placement does not allow any node';
-    return null;
-}
-/**
- * Decide what a node is missing relative to its own last-declared roster.
- * Pure — no I/O, no clock, no randomness.
- */
-function computeBackfillPlan(input) {
-    if (input.freshNode !== undefined && input.recorded.length === 0) {
-        return computeFreshNodePlan(input, input.freshNode);
-    }
-    const liveByName = new Map(input.live.map((p) => [p.name, p.version]));
-    const targets = [];
-    const retired = [];
-    const notOnHub = [];
-    for (const entry of input.recorded) {
-        if (input.bootstrap.has(entry.name))
-            continue;
-        if (input.undeployed.has(entry.name))
-            continue;
-        const hubVersion = input.hubVersions.get(entry.name);
-        const present = liveByName.has(entry.name);
-        const liveVersion = present ? (liveByName.get(entry.name) ?? null) : null;
-        if (hubVersion === undefined) {
-            if (!present && input.retired.has(entry.name))
-                retired.push(entry.name);
-            else if (!present)
-                notOnHub.push(entry.name);
-            continue;
-        }
-        const decision = (0, system_1.decideAddonVersionMove)(present ? liveVersion : null, hubVersion, system_1.ADDON_VERSION_REASON_HUB);
-        if (!decision.move)
-            continue;
-        if (input.retired.has(entry.name)) {
-            retired.push(entry.name);
-            continue;
-        }
-        targets.push({ name: entry.name, version: hubVersion, versionSource: 'hub-installed' });
-    }
-    return { targets, retired, notOnHub, liveCount: liveByName.size, skipped: [] };
-}
-function computeFreshNodePlan(input, fresh) {
-    const liveByName = new Map(input.live.map((p) => [p.name, p.version]));
-    const targets = [];
-    const retired = [];
-    const skipped = [];
-    for (const [name, placements] of fresh.hubPackagePlacements) {
-        if (input.bootstrap.has(name))
-            continue;
-        if (input.undeployed.has(name))
-            continue;
-        const reason = freshNodeSkipReason(placements);
-        if (reason !== null) {
-            skipped.push({ name, reason });
-            continue;
-        }
-        const hubVersion = input.hubVersions.get(name);
-        if (hubVersion === undefined) {
-            skipped.push({ name, reason: 'hub version unknown' });
-            continue;
-        }
-        const present = liveByName.has(name);
-        const decision = (0, system_1.decideAddonVersionMove)(present ? (liveByName.get(name) ?? null) : null, hubVersion, system_1.ADDON_VERSION_REASON_HUB);
-        if (!decision.move)
-            continue;
-        if (input.retired.has(name)) {
-            retired.push(name);
-            continue;
-        }
-        targets.push({ name, version: hubVersion, versionSource: 'hub-installed' });
-    }
-    return { targets, retired, notOnHub: [], liveCount: liveByName.size, skipped };
-}
 function confirmBackfillPlan(plan, secondRead) {
     const seen = new Map(secondRead.map((p) => [p.name, p.version]));
     const targets = [];
@@ -255,11 +145,16 @@ async function executeBackfill(seam, nodeId, plan, tracker) {
         catch (err) {
             const error = err instanceof Error ? err.message : String(err);
             const { retired } = tracker.recordFailure(nodeId, target.name, target.version, error);
-            failed.push({ name: target.name, version: target.version, error, retired });
+            failed.push({
+                name: target.name,
+                version: target.version,
+                error,
+                retired,
+            });
         }
     }
     if (delivered.length > 0) {
         await seam.reload(nodeId);
     }
-    return { delivered, failed, skipped: plan.retired, notOnHub: plan.notOnHub };
+    return { delivered, failed, skipped: plan.retired };
 }

package/dist/core/agent/agent-desired-set.js

@@ -0,0 +1,89 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AGENT_TRACKED_PACKAGES = void 0;
+exports.isAgentTrackedPackage = isAgentTrackedPackage;
+exports.computeDesiredSet = computeDesiredSet;
+exports.diffNodeAgainstDesired = diffNodeAgainstDesired;
+const system_1 = require("@camstack/system");
+/**
+ * Agent-only packages the hub tracks and delivers without loading them itself.
+ * The version the hub follows for each is the registry's `latest`, resolved by
+ * the caller and passed in as `trackedForAgents`.
+ */
+exports.AGENT_TRACKED_PACKAGES = ['@camstack/addon-agent-ui'];
+function isAgentTrackedPackage(name) {
+    return exports.AGENT_TRACKED_PACKAGES.includes(name);
+}
+function computeDesiredSet(input) {
+    const desired = new Map();
+    const hubOnly = new Set();
+    const excluded = [];
+    for (const [name, fact] of input.hubPackages) {
+        if (input.bootstrap.has(name))
+            continue;
+        if (fact.placements.length > 0 && fact.placements.every((p) => p === 'hub-only')) {
+            hubOnly.add(name);
+            excluded.push({ name, reason: 'hub-only placement' });
+            continue;
+        }
+        if (fact.placements.includes('hub-only')) {
+            excluded.push({ name, reason: 'mixes a hub-only addon' });
+            continue;
+        }
+        if (!fact.placements.includes('any-node')) {
+            excluded.push({ name, reason: 'placement does not allow any node' });
+            continue;
+        }
+        if (input.tombstones.has(name)) {
+            excluded.push({ name, reason: 'tombstoned' });
+            continue;
+        }
+        if (fact.version === null) {
+            excluded.push({ name, reason: 'hub version unknown' });
+            continue;
+        }
+        desired.set(name, { name, version: fact.version, origin: 'hub-any-node' });
+    }
+    for (const [name, version] of input.trackedForAgents) {
+        if (input.bootstrap.has(name))
+            continue;
+        if (input.tombstones.has(name)) {
+            excluded.push({ name, reason: 'tombstoned' });
+            continue;
+        }
+        desired.set(name, { name, version, origin: 'agent-tracked' });
+    }
+    return { desired, hubOnly, tombstones: input.tombstones, excluded };
+}
+function diffNodeAgainstDesired(input) {
+    const observed = new Map(input.observed.map((p) => [p.name, p.version]));
+    const install = [];
+    const update = [];
+    const remove = [];
+    const retired = [];
+    for (const entry of input.desired.desired.values()) {
+        const present = observed.has(entry.name);
+        const from = present ? (observed.get(entry.name) ?? null) : null;
+        const decision = (0, system_1.decideAddonVersionMove)(from, entry.version, system_1.ADDON_VERSION_REASON_HUB);
+        if (!decision.move)
+            continue;
+        if (input.retired.has(entry.name)) {
+            retired.push(entry.name);
+            continue;
+        }
+        const target = { ...entry, from };
+        if (present)
+            update.push(target);
+        else
+            install.push(target);
+    }
+    for (const name of observed.keys()) {
+        if (input.bootstrap.has(name))
+            continue;
+        if (input.desired.tombstones.has(name))
+            remove.push({ name, reason: 'tombstoned' });
+        else if (input.desired.hubOnly.has(name))
+            remove.push({ name, reason: 'hub-only placement' });
+    }
+    return { install, update, remove, retired };
+}