@camstack/server 1.2.705 → 1.2.707

package/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.2.707] - 2026-10-31
+
+### Changed
+
+- Agents receive addon installs and updates again: the convergence dry run no longer blocks every reconcile and holds back only removals.
+
+## [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

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 };
+}

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

@@ -33,7 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AgentRegistryService = exports.AGENT_BACKFILL_RPC_TIMEOUT_MS = exports.FORGOTTEN_NODE_REVOCATION_REASON = void 0;
+exports.AgentRegistryService = exports.ADDON_CONVERGENCE_DRY_RUN_KEY = exports.ADDON_CONVERGENCE_INTERVAL_MS = exports.AGENT_BACKFILL_RPC_TIMEOUT_MS = exports.FORGOTTEN_NODE_REVOCATION_REASON = void 0;
 exports.toNodeLiveness = toNodeLiveness;
 exports.toDescriptor = toDescriptor;
 const node_crypto_1 = require("node:crypto");
@@ -41,6 +41,7 @@ const os = __importStar(require("node:os"));
 const system_1 = require("@camstack/system");
 const types_1 = require("@camstack/types");
 const agent_addon_backfill_1 = require("./agent-addon-backfill");
+const agent_desired_set_1 = require("./agent-desired-set");
 const agent_delivery_ledger_1 = require("./agent-delivery-ledger");
 const agent_liveness_event_1 = require("./agent-liveness-event");
 const cluster_node_history_mirror_1 = require("./cluster-node-history-mirror");
@@ -118,6 +119,19 @@ const AGENT_BOOTSTRAP_PACKAGES = new Set([
     '@camstack/system',
     '@camstack/addon-agent-ui',
 ]);
+/**
+ * What the CONVERGENCE never manages (D982): only the framework carrier. The
+ * agent-only dashboard is not bootstrap to the convergence — the hub tracks it
+ * and keeps it at the hub's version — though the stale sweep above still never
+ * undeploys it as "not installed on the hub".
+ */
+const CONVERGENCE_BOOTSTRAP = new Set(['@camstack/system']);
+/** The fixed schedule of the convergence round over every online node (D982). */
+exports.ADDON_CONVERGENCE_INTERVAL_MS = 10 * 60_000;
+/** Settings key: `true` (the default) logs the convergence plan and applies nothing. */
+exports.ADDON_CONVERGENCE_DRY_RUN_KEY = 'addons.convergence.dryRun';
+/** How long a resolved registry version of a tracked package is reused. */
+const TRACKED_VERSION_TTL_MS = 5 * 60_000;
 /** Derive the package roster (name → version) from a node's addon list. */
 function rosterFromAddons(addons) {
     const byName = new Map();
@@ -254,6 +268,14 @@ class AgentRegistryService {
      * diff and each deliver it.
      */
     reconcilingNodes = new Set();
+    /** Resolves the version of an agent-tracked package (agent-ui); `null` = not wired. */
+    trackedVersionResolver = null;
+    trackedVersionCache = new Map();
+    /** Reads the dry-run switch per round, so flipping the setting needs no restart. */
+    convergenceDryRun = () => true;
+    convergenceTimer = null;
+    convergenceRunning = false;
+    convergenceRerun = null;
     constructor(eventBus, moleculer, capabilityService) {
         this.eventBus = eventBus;
         this.moleculer = moleculer;
@@ -322,6 +344,15 @@ class AgentRegistryService {
     setAddonBackfill(seam) {
         this.addonBackfill = seam;
     }
+    /** Wire how the hub resolves the version of an agent-only tracked package. */
+    setTrackedVersionResolver(resolver) {
+        this.trackedVersionResolver = resolver;
+        this.trackedVersionCache.clear();
+    }
+    /** Wire the dry-run switch; unwired it is ON (D982: the first live run only logs). */
+    setConvergenceDryRun(read) {
+        this.convergenceDryRun = read;
+    }
     /**
      * Delivery failures the breaker is tracking for a node — surfaced so a node
      * that is missing capabilities never merely *looks* healthy.
@@ -342,9 +373,18 @@ class AgentRegistryService {
         const packageName = this.resolvePackageForAddon(addonId);
         if (packageName === null)
             return;
-        if (AGENT_BOOTSTRAP_PACKAGES.has(packageName))
+        if (CONVERGENCE_BOOTSTRAP.has(packageName))
             return;
         await this.historyStore?.prunePackages(nodeId, [packageName]);
+        await this.historyStore?.addTombstones(nodeId, [packageName]);
+    }
+    /**
+     * The operator delivered a package to ONE node on purpose (`updatePackage` with
+     * a `nodeId`, `camstack deploy -n`): that lifts its tombstone, so the desired
+     * set wants it there again.
+     */
+    async noteExplicitDelivery(nodeId, packageName) {
+        await this.historyStore?.clearTombstones(nodeId, [packageName]);
     }
     /**
      * The operator removed a whole PACKAGE from a node (`addons.uninstallPackage`
@@ -355,9 +395,10 @@ class AgentRegistryService {
      * stale-addon reconcile does.
      */
     async notePackageUndeployed(nodeId, packageName, addonIds) {
-        if (AGENT_BOOTSTRAP_PACKAGES.has(packageName))
+        if (CONVERGENCE_BOOTSTRAP.has(packageName))
             return;
         await this.historyStore?.prunePackages(nodeId, [packageName]);
+        await this.historyStore?.addTombstones(nodeId, [packageName]);
         for (const addonId of addonIds) {
             this.eventBus.emit({
                 id: (0, node_crypto_1.randomUUID)(),
@@ -649,6 +690,94 @@ class AgentRegistryService {
         catch {
             // Registry shape varies across Moleculer versions — never fatal.
         }
+        this.startConvergenceTimer();
+    }
+    /**
+     * The fixed schedule of D982: every online agent is converged to its desired
+     * set every {@link ADDON_CONVERGENCE_INTERVAL_MS}. A round never gates
+     * registration (D3) and a failed delivery waits for the next round — the
+     * per-`(node, package)` breaker bounds the retries, there is no tight loop.
+     */
+    startConvergenceTimer() {
+        if (this.convergenceTimer !== null)
+            return;
+        const timer = setInterval(() => {
+            void this.requestConvergence('periodic');
+        }, exports.ADDON_CONVERGENCE_INTERVAL_MS);
+        timer.unref();
+        this.convergenceTimer = timer;
+    }
+    /** Stop the convergence schedule (shutdown, specs). */
+    stopConvergenceTimer() {
+        if (this.convergenceTimer === null)
+            return;
+        clearInterval(this.convergenceTimer);
+        this.convergenceTimer = null;
+    }
+    /**
+     * Converge every online agent to its desired set. Requests that arrive while a
+     * round runs collapse into ONE more round after it — a burst of hub installs
+     * cannot stack passes, and a round never re-triggers itself.
+     */
+    async requestConvergence(trigger) {
+        if (this.convergenceRunning) {
+            this.convergenceRerun = trigger;
+            return;
+        }
+        this.convergenceRunning = true;
+        try {
+            let next = trigger;
+            while (next !== null) {
+                this.convergenceRerun = null;
+                for (const agentId of this.onlineAgentIds()) {
+                    await this.reconcileAgentAddons(agentId, next);
+                }
+                next = this.convergenceRerun;
+            }
+        }
+        finally {
+            this.convergenceRunning = false;
+        }
+    }
+    /** Bare agent ids currently online (workers and the hub excluded). */
+    onlineAgentIds() {
+        const registry = this.nodeCatalogRegistry();
+        const nodes = registry?.getNodeList?.({ onlyAvailable: true }) ?? [];
+        return nodes
+            .map((n) => n.id)
+            .filter((id) => typeof id === 'string' && id !== 'hub' && !id.includes('/'));
+    }
+    /** The version the hub follows for an agent-only tracked package, or `null`. */
+    async resolveTrackedVersions() {
+        const resolver = this.trackedVersionResolver;
+        const out = new Map();
+        if (resolver === null)
+            return out;
+        const now = Date.now();
+        for (const name of agent_desired_set_1.AGENT_TRACKED_PACKAGES) {
+            const cached = this.trackedVersionCache.get(name);
+            if (cached !== undefined && now - cached.at < TRACKED_VERSION_TTL_MS) {
+                out.set(name, cached.version);
+                continue;
+            }
+            try {
+                const version = await resolver(name);
+                if (version === null)
+                    continue;
+                this.trackedVersionCache.set(name, { version, at: now });
+                out.set(name, version);
+            }
+            catch (err) {
+                // Unresolved = not wanted this round; a node is never moved on a guess.
+                this.logger?.warn('convergence: could not resolve a tracked package version', {
+                    meta: {
+                        package: name,
+                        error: err instanceof Error ? err.message : String(err),
+                    },
+                });
+            }
+        }
+        return out;
     }
     /** The durable history's display name for a node, when it knows a real one. */
     knownNodeName(nodeId) {
@@ -665,11 +794,7 @@ class AgentRegistryService {
      * must not abort the pass or hub boot.
      */
     async reconcileConnectedAgents() {
-        const registry = this.nodeCatalogRegistry();
-        const nodes = registry?.getNodeList?.({ onlyAvailable: true }) ?? [];
-        const agentIds = nodes
-            .map((n) => n.id)
-            .filter((id) => typeof id === 'string' && id !== 'hub' && !id.includes('/'));
+        const agentIds = this.onlineAgentIds();
         if (agentIds.length === 0)
             return;
         console.log(`[agent-registry] Boot reconcile: ${agentIds.length} connected agent(s)`);
@@ -788,7 +913,13 @@ class AgentRegistryService {
                     }
                 }
             }
+            // The decl-level sweep keeps its connect-time blast radius: the scheduled and
+            // hub-change rounds (D982) converge by the desired set only, so a hub whose
+            // registry is momentarily short can never undeploy a node's addons on a timer.
+            const sweepsStale = trigger !== 'periodic' && trigger !== 'hub-change';
             const stale = agentAddons.filter((addon) => {
+                if (!sweepsStale)
+                    return false;
                 // 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
@@ -813,13 +944,14 @@ class AgentRegistryService {
                 // Installed but pinned to the hub → must not run on an agent.
                 return placement === 'hub-only';
             });
-            if (stale.length === 0) {
+            if (stale.length === 0 && sweepsStale) {
                 console.log(`[agent-registry] Reconcile ${agentId}: no stale addons (${agentAddons.length} checked)`);
             }
             // Packages fully removed from the node by this pass. Recorded so the
             // back-fill below cannot immediately put them back, and so the node's
             // intended set shrinks — the only way that happens.
             const undeployedPackages = new Set();
+            const undeployedIds = new Set();
             const survivingIds = new Set(agentAddons.filter((a) => !stale.includes(a)).map((a) => a.id));
             for (const addon of stale) {
                 const reason = hubPlacements.has(addon.id)
@@ -830,6 +962,7 @@ class AgentRegistryService {
                         nodeID: agentId,
                         timeout: AGENT_RECONCILE_RPC_TIMEOUT_MS,
                     });
+                    undeployedIds.add(addon.id);
                     console.log(`[agent-registry] Reconcile ${agentId}: undeployed stale addon "${addon.id}" (${reason})`);
                     // A package only leaves the intended set when NO surviving addon
                     // still belongs to it — one package ships many addons, and the agent
@@ -852,7 +985,14 @@ class AgentRegistryService {
                     console.error(`[agent-registry] Reconcile ${agentId}: failed to undeploy "${addon.id}":`, err instanceof Error ? err.message : String(err));
                 }
             }
-            await this.backfillAgentAddons(agentId, agentAddons, undeployedPackages, hubVersions, hubPackagePlacements, trigger);
+            const hubPackageFacts = new Map();
+            for (const [name, placements] of hubPackagePlacements) {
+                hubPackageFacts.set(name, {
+                    version: hubVersions.get(name) ?? null,
+                    placements,
+                });
+            }
+            await this.convergeAgentAddons(agentId, agentAddons.filter((a) => !undeployedIds.has(a.id)), undeployedPackages, hubPackageFacts, trigger);
         }
         catch (err) {
             console.error(`[agent-registry] Reconcile failed for agent ${agentId}:`, err instanceof Error ? err.message : String(err));
@@ -862,24 +1002,25 @@ class AgentRegistryService {
         }
     }
     /**
-     * Converge a node UP to the roster it last declared.
+     * Converge a node to ITS DESIRED SET ([D982](../../../../docs/decisions/adr-0982-the-hub-owns-every-nodes-addon-set.md)).
+     *
+     * The desired set comes from the hub (placements, versions, the agent-only
+     * packages it tracks, the node's tombstones); the roster the node reports is
+     * the observation it is diffed against and is recorded only as history.
      *
      * Order matters and is deliberate:
-     *   1. record what the node declares NOW (grow-only merge) — a wiped node
-     *      reporting 4 packages must not erase the record of its 14;
-     *   2. prune what this pass undeployed — the intended set's only shrink;
-     *   3. read the resulting intended set and deliver the difference.
+     *   1. record what the node declares NOW — history, never intent;
+     *   2. prune what the stale sweep undeployed from that record;
+     *   3. compute the plan, then apply it behind the gates (trigger allowlist,
+     *      delivery window, confirmation read, dry-run switch).
      *
      * Every leg is idempotent: run twice with no change in between and step 3
      * finds nothing to do.
      */
-    async backfillAgentAddons(agentId, agentAddons, undeployedPackages, hubVersions, hubPackagePlacements, trigger) {
+    async convergeAgentAddons(agentId, agentAddons, undeployedPackages, hubPackages, trigger) {
         const store = this.historyStore;
         if (!store)
             return;
-        // Read BEFORE recording: a fresh node is one that never declared a roster
-        // (D962), and the record below would make it look like it had one.
-        const priorRoster = await store.getPackages(agentId);
         const live = rosterFromAddons(agentAddons);
         await store.recordPackages(agentId, live);
         if (undeployedPackages.size > 0) {
@@ -888,85 +1029,177 @@ class AgentRegistryService {
         const seam = this.addonBackfill;
         if (!seam)
             return;
-        const recorded = await store.getPackages(agentId);
-        const planned = (0, agent_addon_backfill_1.computeBackfillPlan)({
-            recorded,
-            live,
-            bootstrap: AGENT_BOOTSTRAP_PACKAGES,
-            undeployed: undeployedPackages,
+        const tombstones = await store.getTombstones(agentId);
+        const desired = (0, agent_desired_set_1.computeDesiredSet)({
+            hubPackages,
+            trackedForAgents: await this.resolveTrackedVersions(),
+            tombstones,
+            bootstrap: CONVERGENCE_BOOTSTRAP,
+        });
+        const planned = (0, agent_desired_set_1.diffNodeAgainstDesired)({
+            desired,
+            observed: live.filter((p) => !undeployedPackages.has(p.name)),
             retired: this.backfillTracker.retiredFor(agentId),
-            hubVersions,
-            freshNode: priorRoster.length === 0 ? { hubPackagePlacements } : undefined,
+            bootstrap: CONVERGENCE_BOOTSTRAP,
         });
-        if (priorRoster.length === 0) {
-            this.logger?.info('back-fill: fresh node (no prior declared roster), plan from the hub any-node set', {
-                tags: { nodeId: agentId },
-                meta: {
-                    planned: planned.targets.map((t) => `${t.name}@${t.version}`),
-                },
-            });
-            for (const skip of planned.skipped) {
-                this.logger?.info('back-fill: fresh node not given a hub package', {
-                    tags: { nodeId: agentId },
-                    meta: { package: skip.name, reason: skip.reason },
-                });
-            }
-        }
-        // Never a delivery, and said so: an addon the hub no longer installs stays
-        // off the node even though the node once declared it (the stale sweep above
-        // removes a copy that is still there).
-        if (planned.notOnHub.length > 0) {
-            console.log(`[agent-registry] Back-fill ${agentId}: NOT delivering ${planned.notOnHub.join(', ')} — ` +
-                `in the node's declared roster but not installed on the hub`);
-        }
-        if (planned.targets.length === 0 && planned.retired.length === 0) {
+        const changes = planned.install.length + planned.update.length + planned.remove.length;
+        if (changes === 0 && planned.retired.length === 0)
             return;
-        }
+        const dryRun = this.readConvergenceDryRun(agentId);
+        this.logger?.info(dryRun ? 'convergence plan (DRY RUN, removals held back)' : 'convergence plan', {
+            tags: { nodeId: agentId },
+            meta: {
+                trigger,
+                install: planned.install.map((t) => `${t.name}@${t.version}`),
+                update: planned.update.map((t) => `${t.name} ${t.from ?? 'absent'} -> ${t.version}`),
+                remove: planned.remove.map((r) => `${r.name} (${r.reason})`),
+                retired: planned.retired,
+                observed: live.length,
+            },
+        });
         // GATE 1 — the trigger allowlist. A pass that must not install says so and
         // stops; silence here would read as "nothing was missing".
         if (!(0, agent_addon_backfill_1.triggerMayDeliver)(trigger)) {
-            console.log(`[agent-registry] Back-fill ${agentId}: SKIPPED — trigger "${trigger}" may not deliver ` +
-                `(${planned.targets.length} package(s) would have been installed)`);
+            console.log(`[agent-registry] Convergence ${agentId}: SKIPPED — trigger "${trigger}" may not deliver ` +
+                `(${changes} change(s) planned)`);
             return;
         }
         // GATE 2 — the delivery window. A roster gap the hub itself opened is not
-        // evidence a node is missing anything. This is the trigger that made every
-        // `camstack deploy … -n <agent>` on 2026-08-07 get reverted ~1.5s later.
+        // evidence a node is missing anything (`camstack deploy … -n <agent>` was
+        // reverted ~1.5s later on 2026-08-07).
         const suppression = this.deliveryLedger.suppressionFor(agentId);
         if (suppression !== null) {
-            console.log(`[agent-registry] Back-fill ${agentId}: SKIPPED — a hub delivery to this node is ` +
+            console.log(`[agent-registry] Convergence ${agentId}: SKIPPED — a hub delivery to this node is ` +
                 `in flight or just finished (inFlight=${suppression.inFlight}, ` +
                 `msSinceLastDelivery=${suppression.msSinceLastDelivery ?? 'n/a'}, ` +
-                `packages=${suppression.packages.join(', ') || 'none'}); ` +
-                `the node reported ${planned.liveCount} package(s) and the roster gap is OURS, not the node's`);
+                `packages=${suppression.packages.join(', ') || 'none'}); the roster gap is OURS, not the node's`);
             return;
         }
-        // GATE 3 — the confirmation read (D49). A back-fill overwrites whatever is
-        // on the node, so the destroying direction needs a SECOND read to agree.
-        const plan = await this.confirmBackfillTargets(agentId, planned);
-        if (plan === null)
+        // The dry run holds back only what D982 added — removals. Installs and
+        // updates are the delivery agents always had; holding them back stopped
+        // every agent from updating.
+        if (!dryRun)
+            await this.applyRemovals(agentId, agentAddons, planned);
+        await this.applyDeliveries(agentId, live, planned, trigger, seam);
+    }
+    /**
+     * The dry-run switch, read fail-safe: a read that cannot be answered counts
+     * as ON (nothing is removed) and never fails the reconcile.
+     */
+    readConvergenceDryRun(agentId) {
+        try {
+            return this.convergenceDryRun();
+        }
+        catch (err) {
+            this.logger?.warn('convergence: dry-run switch unreadable, treated as ON', {
+                tags: { nodeId: agentId },
+                meta: { error: err instanceof Error ? err.message : String(err) },
+            });
+            return true;
+        }
+    }
+    /**
+     * Remove tombstoned and hub-only leftovers. A removal DESTROYS work, so it
+     * needs a second roster read to agree (D49) and fails closed when that read
+     * cannot be taken. Every removal logs its reason.
+     */
+    async applyRemovals(agentId, agentAddons, plan) {
+        if (plan.remove.length === 0)
             return;
-        if (plan.targets.length === 0 && plan.retired.length === 0) {
+        let secondAddons = null;
+        try {
+            secondAddons = this.extractAgentAddons(await this.broker.call('$agent.status', {}, { nodeID: agentId, timeout: AGENT_RECONCILE_RPC_TIMEOUT_MS }));
+        }
+        catch (err) {
+            this.logger?.warn('convergence: removals skipped, the confirmation read failed', {
+                tags: { nodeId: agentId },
+                meta: { error: err instanceof Error ? err.message : String(err) },
+            });
             return;
         }
+        if (secondAddons === null) {
+            this.logger?.warn('convergence: removals skipped, the confirmation read had no addon list', {
+                tags: { nodeId: agentId },
+            });
+            return;
+        }
+        const stillThere = new Set(secondAddons.flatMap((a) => (a.packageName === undefined ? [] : [a.packageName])));
+        for (const removal of plan.remove) {
+            if (!stillThere.has(removal.name))
+                continue;
+            const addonIds = agentAddons.filter((a) => a.packageName === removal.name).map((a) => a.id);
+            try {
+                // One package-mode call removes every addon the package ships; the first
+                // id rides along so an agent that predates package mode still removes it.
+                await this.broker.call('$agent.undeploy', {
+                    packageName: removal.name,
+                    ...(addonIds[0] === undefined ? {} : { addonId: addonIds[0] }),
+                }, { nodeID: agentId, timeout: AGENT_RECONCILE_RPC_TIMEOUT_MS });
+                this.logger?.info('convergence: removed a package from the node', {
+                    tags: { nodeId: agentId },
+                    meta: { package: removal.name, reason: removal.reason, addonIds },
+                });
+                this.eventBus.emit({
+                    id: (0, node_crypto_1.randomUUID)(),
+                    timestamp: new Date(),
+                    source: { type: 'core', id: 'agent-registry' },
+                    category: types_1.EventCategory.AddonUninstalled,
+                    data: {
+                        agentId,
+                        packageName: removal.name,
+                        reason: `convergence: ${removal.reason}`,
+                    },
+                });
+            }
+            catch (err) {
+                this.logger?.warn('convergence: removing a package failed, the next round retries', {
+                    tags: { nodeId: agentId },
+                    meta: {
+                        package: removal.name,
+                        reason: removal.reason,
+                        error: err instanceof Error ? err.message : String(err),
+                    },
+                });
+            }
+        }
+    }
+    /** Install and update, behind the D49 confirmation read. */
+    async applyDeliveries(agentId, live, plan, trigger, seam) {
+        const planned = {
+            targets: [...plan.install, ...plan.update].map((t) => ({
+                name: t.name,
+                version: t.version,
+                versionSource: t.origin === 'agent-tracked' ? 'agent-tracked' : 'hub-installed',
+            })),
+            retired: plan.retired,
+            liveCount: live.length,
+        };
+        if (planned.targets.length === 0 && planned.retired.length === 0)
+            return;
+        // GATE 3 — the confirmation read (D49). A delivery overwrites whatever is
+        // on the node, so the destroying direction needs a SECOND read to agree.
+        const confirmed = await this.confirmBackfillTargets(agentId, planned);
+        if (confirmed === null)
+            return;
+        if (confirmed.targets.length === 0 && confirmed.retired.length === 0)
+            return;
         // Hold the delivery window open for the whole pass, so the reload this
-        // back-fill is about to cause cannot trigger a second one.
-        const closeWindow = this.deliveryLedger.begin(agentId, plan.targets.map((t) => t.name).join(', ') || 'back-fill');
+        // delivery is about to cause cannot trigger a second one.
+        const closeWindow = this.deliveryLedger.begin(agentId, confirmed.targets.map((t) => t.name).join(', ') || 'convergence');
         let outcome;
         try {
-            outcome = await (0, agent_addon_backfill_1.executeBackfill)(seam, agentId, plan, this.backfillTracker);
+            outcome = await (0, agent_addon_backfill_1.executeBackfill)(seam, agentId, confirmed, this.backfillTracker);
         }
         finally {
             closeWindow();
         }
         if (outcome.delivered.length > 0) {
-            console.log(`[agent-registry] Back-fill ${agentId}: delivered ${outcome.delivered
+            console.log(`[agent-registry] Convergence ${agentId}: delivered ${outcome.delivered
                 .map((d) => {
                 const from = live.find((p) => p.name === d.name)?.version ?? 'absent';
-                return `${d.name} ${from} → ${d.version} (agent follows the hub installed version)`;
+                return `${d.name} ${from} → ${d.version} (${d.versionSource})`;
             })
-                .join(', ')} — trigger=${trigger}, node reported ${plan.liveCount} package(s) and its ` +
-                `declared roster has ${recorded.length}`);
+                .join(', ')} — trigger=${trigger}, node reported ${confirmed.liveCount} package(s)`);
             this.eventBus.emit({
                 id: (0, node_crypto_1.randomUUID)(),
                 timestamp: new Date(),
@@ -975,19 +1208,19 @@ class AgentRegistryService {
                 data: {
                     agentId,
                     packages: outcome.delivered.map((d) => `${d.name}@${d.version}`),
-                    reason: 'back-fill: node missing packages from its declared roster',
+                    reason: 'convergence: the hub desired set differs from what the node runs',
                 },
             });
         }
         // Fail LOUD: a node missing capabilities must never merely look healthy.
         for (const failure of outcome.failed) {
-            console.error(`[agent-registry] Back-fill ${agentId}: FAILED to deliver ${failure.name}@${failure.version} — ${failure.error}` +
+            console.error(`[agent-registry] Convergence ${agentId}: FAILED to deliver ${failure.name}@${failure.version} — ${failure.error}` +
                 (failure.retired
                     ? ` (retired after ${agent_addon_backfill_1.MAX_BACKFILL_ATTEMPTS} attempts; this node is running WITHOUT that package)`
-                    : ''));
+                    : ' (the next round retries)'));
         }
         for (const name of outcome.skipped) {
-            console.error(`[agent-registry] Back-fill ${agentId}: ${name} is still missing and RETIRED — the node is degraded until an operator intervenes`);
+            console.error(`[agent-registry] Convergence ${agentId}: ${name} is still wrong and RETIRED — the node is degraded until an operator intervenes`);
         }
     }
     /**

package/dist/core/agent/cluster-node-history-store.js

@@ -21,6 +21,7 @@ const DescriptorSchema = zod_1.z.object({
         .array(zod_1.z.object({ name: zod_1.z.string(), version: zod_1.z.string().nullable() }))
         .readonly()
         .optional(),
+    tombstones: zod_1.z.array(zod_1.z.string()).readonly().optional(),
 });
 /** A row as the store reads it: `at` as `lastActive`, plus the descriptor. */
 const RowDataSchema = zod_1.z.object({
@@ -54,7 +55,8 @@ function descriptorsEqual(a, b) {
         sameStrings(a.engines, b.engines) &&
         sameStrings(a.localIps, b.localIps) &&
         sameStrings(a.addonIds, b.addonIds) &&
-        samePackages(a.packages, b.packages));
+        samePackages(a.packages, b.packages) &&
+        sameStrings(a.tombstones ?? [], b.tombstones ?? []));
 }
 function sameStrings(a, b) {
     return a.length === b.length && a.every((v, i) => v === b[i]);
@@ -103,7 +105,12 @@ class ClusterNodeHistoryStore {
             // the back-fill's intended set on the very next topology poll.
             const existing = await this.readStored(kind, descriptor.id);
             const packages = descriptor.packages ?? existing?.descriptor.packages;
-            const next = packages === undefined ? descriptor : { ...descriptor, packages };
+            const tombstones = descriptor.tombstones ?? existing?.descriptor.tombstones;
+            const next = {
+                ...descriptor,
+                ...(packages === undefined ? {} : { packages }),
+                ...(tombstones === undefined ? {} : { tombstones }),
+            };
             if (existing !== null && !this.worthWriting(existing, next))
                 return;
             await this.writeStored(kind, descriptor.id, Date.now(), next);
@@ -251,6 +258,63 @@ class ClusterNodeHistoryStore {
             });
         }
     }
+    /** The packages tombstoned for a node (D982). Empty when none or unreadable. */
+    async getTombstones(nodeId) {
+        const kind = this.resolveKind();
+        if (kind === null)
+            return new Set();
+        try {
+            return new Set((await this.readStored(kind, nodeId))?.descriptor.tombstones ?? []);
+        }
+        catch (err) {
+            this.logger.warn('getTombstones failed (best-effort)', {
+                tags: { nodeId },
+                meta: { error: (0, types_1.errMsg)(err) },
+            });
+            return new Set();
+        }
+    }
+    /** Keep packages off a node: an operator undeploy / hub uninstall for it. */
+    async addTombstones(nodeId, names) {
+        await this.editTombstones(nodeId, names, 'add');
+    }
+    /** An explicit delivery to the node lifts the tombstone. */
+    async clearTombstones(nodeId, names) {
+        await this.editTombstones(nodeId, names, 'clear');
+    }
+    async editTombstones(nodeId, names, mode) {
+        if (names.length === 0)
+            return;
+        const kind = this.resolveKind();
+        if (kind === null)
+            return;
+        try {
+            const existing = await this.readStored(kind, nodeId);
+            if (existing === null && mode === 'clear')
+                return;
+            const current = new Set(existing?.descriptor.tombstones ?? []);
+            const before = current.size;
+            for (const name of names) {
+                if (mode === 'add')
+                    current.add(name);
+                else
+                    current.delete(name);
+            }
+            if (current.size === before)
+                return;
+            const base = existing?.descriptor ?? ClusterNodeHistoryStore.placeholderDescriptor(nodeId);
+            await this.writeStored(kind, nodeId, existing?.lastActive ?? Date.now(), {
+                ...base,
+                tombstones: [...current].sort(),
+            });
+        }
+        catch (err) {
+            this.logger.warn('editTombstones failed (best-effort)', {
+                tags: { nodeId },
+                meta: { error: (0, types_1.errMsg)(err), mode },
+            });
+        }
+    }
     /**
      * Touch `lastActive` for a node without rewriting its descriptor — used on
      * `$node.disconnected` so an offline node's "last seen" is the disconnect
@@ -302,12 +366,17 @@ class ClusterNodeHistoryStore {
                     });
                     continue;
                 }
-                result.push({ ...parsed.data.descriptor, lastActive: parsed.data.lastActive });
+                result.push({
+                    ...parsed.data.descriptor,
+                    lastActive: parsed.data.lastActive,
+                });
             }
             return result;
         }
         catch (err) {
-            this.logger.warn('history read failed (best-effort)', { meta: { error: (0, types_1.errMsg)(err) } });
+            this.logger.warn('history read failed (best-effort)', {
+                meta: { error: (0, types_1.errMsg)(err) },
+            });
             return null;
         }
     }
@@ -330,7 +399,9 @@ class ClusterNodeHistoryStore {
             const existed = (await this.readStored(kind, nodeId)) !== null;
             await kind.delete(nodeId);
             if (!existed) {
-                this.logger.info('cluster node had no history row to forget', { tags: { nodeId } });
+                this.logger.info('cluster node had no history row to forget', {
+                    tags: { nodeId },
+                });
                 return 'not-found';
             }
             this.logger.info('forgot cluster node', { tags: { nodeId } });

package/dist/main.js

@@ -456,7 +456,7 @@ async function bootstrap() {
         // gap a deploy opens and repair the node over the bytes just shipped.
         await (0, addon_upload_1.registerAddonUploadRoute)(fastify, uploadAddonBridge, uploadAuthService, uploadMoleculer, uploadAddonRegistry, uploadAddonPackage, uploadLogger, (0, hub_cluster_url_1.clusterBaseUrlResolver)(() => uploadAddonRegistry
             .getCapabilityRegistry()
-            .getSingleton('local-network')), app.get(agent_registry_service_1.AgentRegistryService).deliveryLedger);
+            .getSingleton('local-network')), app.get(agent_registry_service_1.AgentRegistryService).deliveryLedger, app.get(agent_registry_service_1.AgentRegistryService));
         console.log('[bootstrap] Addon upload route registered at POST /api/addons/upload');
         // Dev server-deploy channel gateway (`camstack deploy-server`). MUST be
         // registered AFTER registerAddonUploadRoute — it reuses the multipart

package/dist/manual-boot.js

@@ -254,6 +254,11 @@ async function bootManual(opts) {
             await moleculerService.broker.call('$agent.reload', {}, { nodeID: nodeId, timeout: agent_registry_service_1.AGENT_BACKFILL_RPC_TIMEOUT_MS });
         },
     });
+    // D982: the hub follows the registry's `latest` for an agent-only package it
+    // tracks without installing (agent-ui), and the convergence is DRY RUN unless
+    // the operator sets `addons.convergence.dryRun` to false.
+    agentRegistryService.setTrackedVersionResolver((name) => addonPackageService.resolveRegistryVersion(name));
+    agentRegistryService.setConvergenceDryRun(() => configService.get(agent_registry_service_1.ADDON_CONVERGENCE_DRY_RUN_KEY) !== false);
     // ---- Lifecycle job runner (boot singleton) -----------------------------
     // The runner used to be built per-tRPC-request inside the `addons` cap
     // factory. Boot-reconcile (F3 Task 4) and the auto-update scheduler (F3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/server",
-  "version": "1.2.705",
+  "version": "1.2.707",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -50,18 +50,18 @@
     ]
   },
   "dependencies": {
-    "@camstack/addon-admin-ui": "1.2.529",
+    "@camstack/addon-admin-ui": "1.2.530",
     "@camstack/addon-agent-ui": "1.2.300",
-    "@camstack/addon-auth": "1.2.172",
+    "@camstack/addon-auth": "1.2.173",
     "@camstack/addon-benchmark": "1.2.299",
     "@camstack/addon-decoder-nodeav": "1.2.144",
     "@camstack/addon-notifiers": "1.2.624",
     "@camstack/addon-pipeline": "1.2.635",
-    "@camstack/addon-pipeline-orchestrator": "1.2.642",
+    "@camstack/addon-pipeline-orchestrator": "1.2.644",
     "@camstack/addon-post-analysis": "1.2.654",
     "@camstack/develop": "0.1.41",
     "@camstack/sdk": "1.2.154",
-    "@camstack/system": "1.2.526",
+    "@camstack/system": "1.2.528",
     "@camstack/types": "1.2.453",
     "@camstack/ui-library": "1.2.358",
     "@fastify/compress": "^9.0.0",