@camstack/server 1.2.70 → 1.2.72

package/dist/api/core/logs.router.js

@@ -11,6 +11,7 @@ exports.createLogsRouter = createLogsRouter;
  */
 const zod_1 = require("zod");
 const trpc_middleware_js_1 = require("../trpc/trpc.middleware.js");
+const types_1 = require("@camstack/types");
 const LogLevelSchema = zod_1.z.enum(['debug', 'info', 'warn', 'error']);
 const LogTagsSchema = zod_1.z.object({
     agentId: zod_1.z.string().optional(),
@@ -84,7 +85,7 @@ function createLogsRouter(logging) {
                             if (typeof addonId !== 'string')
                                 return false;
                             return allowed.some((p) => {
-                                const bare = p.startsWith('addon:') ? p.slice('addon:'.length) : p;
+                                const bare = (0, types_1.bareAddonId)(p);
                                 return addonId === bare || addonId.startsWith(bare);
                             });
                         });

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

@@ -5204,6 +5204,24 @@ function createCapRouter_notificationRules(getProvider, createRemoteProxy) {
             // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-argument
             return p.setRuleEnabled(methodInput);
         }),
+        listDeviceMutes: trpc_middleware_js_1.adminProcedure
+            .input(types_75.notificationRulesCapability.methods.listDeviceMutes.input.loose())
+            .output(types_75.notificationRulesCapability.methods.listDeviceMutes.output)
+            .query(async ({ input, ctx }) => {
+            const { nodeId, ...methodInput } = input;
+            const p = resolveProvider('notification-rules', nodeId, () => getProvider(ctx), createRemoteProxy);
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-argument
+            return p.listDeviceMutes(methodInput);
+        }),
+        setDeviceMuted: trpc_middleware_js_1.adminProcedure
+            .input(types_75.notificationRulesCapability.methods.setDeviceMuted.input.loose())
+            .output(types_75.notificationRulesCapability.methods.setDeviceMuted.output)
+            .mutation(async ({ input, ctx }) => {
+            const { nodeId, ...methodInput } = input;
+            const p = resolveProvider('notification-rules', nodeId, () => getProvider(ctx), createRemoteProxy);
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-argument
+            return p.setDeviceMuted(methodInput);
+        }),
         testRule: trpc_middleware_js_1.adminProcedure
             .input(types_75.notificationRulesCapability.methods.testRule.input.loose())
             .output(types_75.notificationRulesCapability.methods.testRule.output)
@@ -5640,6 +5658,15 @@ function createCapRouter_pipelineAnalytics(getProvider, createRemoteProxy) {
             // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-argument
             return p.deleteTracks(methodInput);
         }),
+        setTrackFlags: trpc_middleware_js_1.protectedProcedure
+            .input(types_80.pipelineAnalyticsCapability.methods.setTrackFlags.input.loose())
+            .output(types_80.pipelineAnalyticsCapability.methods.setTrackFlags.output)
+            .mutation(async ({ input, ctx }) => {
+            const { nodeId, ...methodInput } = input;
+            const p = resolveProvider('pipeline-analytics', nodeId, () => getProvider(ctx), createRemoteProxy);
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-argument
+            return p.setTrackFlags(methodInput);
+        }),
         getEventStoreFootprint: trpc_middleware_js_1.adminProcedure
             .input(types_80.pipelineAnalyticsCapability.methods.getEventStoreFootprint.input.loose())
             .output(types_80.pipelineAnalyticsCapability.methods.getEventStoreFootprint.output)
@@ -6364,6 +6391,22 @@ function createCapRouter_pipelineOrchestrator(getProvider, _createRemoteProxy) {
             // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-argument
             return p.resolvePipeline(input);
         }),
+        getCameraSwitches: trpc_middleware_js_1.protectedProcedure
+            .input(types_82.pipelineOrchestratorCapability.methods.getCameraSwitches.input.loose())
+            .output(types_82.pipelineOrchestratorCapability.methods.getCameraSwitches.output)
+            .query(async ({ input, ctx }) => {
+            const p = requireCapProvider('pipeline-orchestrator', () => getProvider(ctx));
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-argument
+            return p.getCameraSwitches(input);
+        }),
+        setCameraSwitch: trpc_middleware_js_1.adminProcedure
+            .input(types_82.pipelineOrchestratorCapability.methods.setCameraSwitch.input.loose())
+            .output(types_82.pipelineOrchestratorCapability.methods.setCameraSwitch.output)
+            .mutation(async ({ input, ctx }) => {
+            const p = requireCapProvider('pipeline-orchestrator', () => getProvider(ctx));
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-argument
+            return p.setCameraSwitch(input);
+        }),
         getCameraStatus: trpc_middleware_js_1.protectedProcedure
             .input(types_82.pipelineOrchestratorCapability.methods.getCameraStatus.input.loose())
             .output(types_82.pipelineOrchestratorCapability.methods.getCameraStatus.output)
@@ -6498,6 +6541,15 @@ function createCapRouter_pipelineRunner(getProvider, createRemoteProxy) {
             // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-argument
             return p.runDetailSubtree(methodInput);
         }),
+        runStatelessStep: trpc_middleware_js_1.protectedProcedure
+            .input(types_83.pipelineRunnerCapability.methods.runStatelessStep.input.loose())
+            .output(types_83.pipelineRunnerCapability.methods.runStatelessStep.output)
+            .mutation(async ({ input, ctx }) => {
+            const { nodeId, ...methodInput } = input;
+            const p = resolveProvider('pipeline-runner', nodeId, () => getProvider(ctx), createRemoteProxy);
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-argument
+            return p.runStatelessStep(methodInput);
+        }),
     });
 }
 function createCapRouter_plateGallery(getProvider, createRemoteProxy) {
@@ -6755,6 +6807,15 @@ function createCapRouter_privacyMask(getProvider, createRemoteProxy) {
             // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-argument
             return p.setMask(methodInput);
         }),
+        setAudioEnabled: trpc_middleware_js_1.adminProcedure
+            .input(types_86.privacyMaskCapability.methods.setAudioEnabled.input.loose())
+            .output(types_86.privacyMaskCapability.methods.setAudioEnabled.output)
+            .mutation(async ({ input, ctx }) => {
+            const { nodeId, ...methodInput } = input;
+            const p = resolveProvider('privacy-mask', nodeId, () => getProvider(ctx), createRemoteProxy);
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-argument
+            return p.setAudioEnabled(methodInput);
+        }),
     });
 }
 function createCapRouter_ptz(getProvider, createRemoteProxy) {
@@ -7023,6 +7084,15 @@ function createCapRouter_recording(getProvider, createRemoteProxy) {
             // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-argument
             return p.readSegmentBytes(methodInput);
         }),
+        readGopBytes: trpc_middleware_js_1.adminProcedure
+            .input(types_90.recordingCapability.methods.readGopBytes.input.loose())
+            .output(types_90.recordingCapability.methods.readGopBytes.output)
+            .query(async ({ input, ctx }) => {
+            const { nodeId, ...methodInput } = input;
+            const p = resolveProvider('recording', nodeId, () => getProvider(ctx), createRemoteProxy);
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-argument
+            return p.readGopBytes(methodInput);
+        }),
         setDeviceConfig: trpc_middleware_js_1.adminProcedure
             .input(types_90.recordingCapability.methods.setDeviceConfig.input.loose())
             .output(types_90.recordingCapability.methods.setDeviceConfig.output)
@@ -8088,6 +8158,24 @@ function createCapRouter_streamBroker(getProvider, createRemoteProxy) {
             // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-argument
             return p.releaseStreamWithCodec(methodInput);
         }),
+        acquireEgressTranscode: trpc_middleware_js_1.adminProcedure
+            .input(types_102.streamBrokerCapability.methods.acquireEgressTranscode.input.loose())
+            .output(types_102.streamBrokerCapability.methods.acquireEgressTranscode.output)
+            .mutation(async ({ input, ctx }) => {
+            const { nodeId, ...methodInput } = input;
+            const p = resolveProvider('stream-broker', nodeId, () => getProvider(ctx), createRemoteProxy);
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-argument
+            return p.acquireEgressTranscode(methodInput);
+        }),
+        releaseEgressTranscode: trpc_middleware_js_1.adminProcedure
+            .input(types_102.streamBrokerCapability.methods.releaseEgressTranscode.input.loose())
+            .output(types_102.streamBrokerCapability.methods.releaseEgressTranscode.output)
+            .mutation(async ({ input, ctx }) => {
+            const { nodeId, ...methodInput } = input;
+            const p = resolveProvider('stream-broker', nodeId, () => getProvider(ctx), createRemoteProxy);
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-argument
+            return p.releaseEgressTranscode(methodInput);
+        }),
         subscribeAudioChunks: trpc_middleware_js_1.protectedProcedure
             .input(types_102.streamBrokerCapability.methods.subscribeAudioChunks.input.loose())
             .output(types_102.streamBrokerCapability.methods.subscribeAudioChunks.output)

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

@@ -37,15 +37,15 @@ exports.AddonPackageService = exports.FRAMEWORK_PACKAGES = exports.AUTO_UPDATE_E
 exports.isVersionNewer = isVersionNewer;
 exports.isFrameworkPackage = isFrameworkPackage;
 exports.extractTgzStripped = extractTgzStripped;
+const node_child_process_1 = require("node:child_process");
+const node_crypto_1 = require("node:crypto");
 const fs = __importStar(require("node:fs"));
-const path = __importStar(require("node:path"));
 const os = __importStar(require("node:os"));
-const node_child_process_1 = require("node:child_process");
+const path = __importStar(require("node:path"));
 const node_util_1 = require("node:util");
-const node_crypto_1 = require("node:crypto");
-const package_dir_utils_js_1 = require("./package-dir-utils.js");
-const types_1 = require("@camstack/types");
 const system_1 = require("@camstack/system");
+const types_1 = require("@camstack/types");
+const package_dir_utils_js_1 = require("./package-dir-utils.js");
 const execFileAsync = (0, node_util_1.promisify)(node_child_process_1.execFile);
 /**
  * The primary host-provided framework package (kernel + core). Kept as a named
@@ -661,11 +661,59 @@ class AddonPackageService {
         }));
         return updates;
     }
+    /**
+     * Pack the bytes the HUB IS RUNNING for `name`, when it has them installed.
+     *
+     * The addon back-fill's own comment has always said "bytes come from the
+     * hub's own resolution of the package", and it was not true: it called
+     * `packPackage`, which is `npm pack <name>@<version>` — the REGISTRY. A
+     * version string is not a build. `@camstack/addon-pipeline@1.2.43` deployed
+     * from the workspace and `@camstack/addon-pipeline@1.2.43` on npm were two
+     * different bundles all of 2026-08-07, and every `camstack deploy` to
+     * little-unraid was silently reverted ~1.5s later: the deploy's own
+     * `$agent.reload` briefly emptied the node's reported addon list, the hub's
+     * reconcile read it as "package missing", and the back-fill repaired the node
+     * by installing the PUBLISHED 1.2.43 over the one just delivered. Nothing
+     * looked wrong — same name, same version, different code. Four deploys were
+     * attributed to a stale tarball cache that does not exist.
+     *
+     * Returns `null` when the hub has no installed copy; the caller then falls
+     * back to the registry, which is the only correct source in that case.
+     */
+    async packInstalledPackage(name) {
+        const installedDir = path.join(this.resolveAddonsDir(), name);
+        if (!fs.existsSync(path.join(installedDir, 'package.json')))
+            return null;
+        const destDir = fs.mkdtempSync(path.join(os.tmpdir(), 'camstack-pack-local-'));
+        try {
+            await execFileAsync('npm', ['pack', installedDir, '--pack-destination', destDir], {
+                timeout: 120_000,
+            });
+            const onDisk = fs.readdirSync(destDir).find((f) => f.endsWith('.tgz'));
+            if (onDisk === undefined)
+                return null;
+            const buffer = fs.readFileSync(path.join(destDir, onDisk));
+            const parsed = JSON.parse(fs.readFileSync(path.join(installedDir, 'package.json'), 'utf-8'));
+            const version = typeof parsed === 'object' &&
+                parsed !== null &&
+                typeof parsed.version === 'string'
+                ? parsed.version
+                : '0.0.0';
+            return { buffer, version, filename: onDisk };
+        }
+        finally {
+            fs.rmSync(destDir, { recursive: true, force: true });
+        }
+    }
     /**
      * Resolve `name@version` and `npm pack` it into a tarball buffer
      * WITHOUT installing. Used to push a package update to an agent: the
      * hub packs here, then ships the tgz via `$agent.deploy` — agents
      * need no npm runtime of their own.
+     *
+     * For the addon back-fill prefer {@link packInstalledPackage}: this one
+     * returns the REGISTRY's build of a version, which is not necessarily the
+     * build the hub runs.
      */
     async packPackage(name, version) {
         const registry = process.env['CAMSTACK_NPM_REGISTRY'];

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

@@ -44,8 +44,20 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BackfillAttemptTracker = exports.MAX_BACKFILL_ATTEMPTS = void 0;
+exports.triggerMayDeliver = triggerMayDeliver;
 exports.computeBackfillPlan = computeBackfillPlan;
+exports.confirmBackfillPlan = confirmBackfillPlan;
 exports.executeBackfill = executeBackfill;
+/** Triggers permitted to install packages onto a node. */
+const DELIVERING_TRIGGERS = new Set([
+    'node-registration',
+    'hub-boot',
+    'operator-repair',
+]);
+/** Is this trigger allowed to put bytes on a node? */
+function triggerMayDeliver(trigger) {
+    return DELIVERING_TRIGGERS.has(trigger);
+}
 /**
  * Decide what a node is missing relative to its own last-declared roster.
  * Pure — no I/O, no clock, no randomness.
@@ -66,14 +78,25 @@ function computeBackfillPlan(input) {
             retired.push(entry.name);
             continue;
         }
-        const version = input.hubVersions.get(entry.name) ?? entry.version;
+        const hubVersion = input.hubVersions.get(entry.name);
+        const version = hubVersion ?? entry.version;
         if (version === null || version === undefined || version.length === 0) {
             unresolvable.push(entry.name);
             continue;
         }
-        targets.push({ name: entry.name, version });
+        targets.push({
+            name: entry.name,
+            version,
+            versionSource: hubVersion === undefined ? 'node-last-reported' : 'hub-installed',
+        });
     }
-    return { targets, retired, unresolvable };
+    return { targets, retired, unresolvable, liveCount: liveNames.size };
+}
+function confirmBackfillPlan(plan, secondRead) {
+    const present = new Set(secondRead.map((p) => p.name));
+    const targets = plan.targets.filter((t) => !present.has(t.name));
+    const contradicted = plan.targets.filter((t) => present.has(t.name));
+    return { plan: { ...plan, targets }, contradicted };
 }
 /**
  * How many consecutive delivery failures retire a `(node, package)` pair.

package/dist/core/agent/agent-delivery-ledger.js

@@ -0,0 +1,112 @@
+"use strict";
+/**
+ * "Is the hub currently writing addons to this node?"
+ *
+ * WHY THIS EXISTS
+ * The addon back-fill repairs a node by comparing the roster the node reports
+ * NOW against the roster it last declared. A hub-initiated delivery makes that
+ * comparison lie, for a window it opens itself:
+ *
+ *   1. `$agent.deploy`'s `onApplied` evicts the package's declaration ids from
+ *      the node's `loadedAddons`, so `$agent.status` stops reporting it;
+ *   2. `$agent.reload` re-instantiates every runner, and a status read landing
+ *      mid-reload sees a PARTIAL roster — measured on `little-unraid`
+ *      2026-08-07 as the same reconcile reporting "14 checked" and, seconds
+ *      later, "20 checked";
+ *   3. the reload re-registers the node, which fires the reconcile, which reads
+ *      the roster of step 1/2 and concludes the package is missing.
+ *
+ * The hub then "repairs" the node by installing over the bundle an operator
+ * delivered 1.5 seconds earlier. That defect (fixed once by making the pack
+ * source the hub's installed copy) is a symptom: the trigger is a roster gap
+ * the hub itself caused. This ledger removes the trigger.
+ *
+ * IT IS NOT A SLEEP
+ * The window opens on the FIRST byte of a delivery and closes
+ * {@link DELIVERY_GRACE_MS} after the LAST in-flight delivery to that node
+ * finishes. A delivery that takes four minutes (the pipeline stack on a slow
+ * agent) holds the window open for four minutes; nothing is timed
+ * speculatively. The grace tail covers the re-registration storm that follows
+ * a reload, which arrives after the RPC has already returned.
+ *
+ * PROCESS-SCOPED AND HOLDS NO INTENT
+ * Same shape as `BackfillAttemptTracker`: in-memory, per hub lifetime, and
+ * carrying nothing durable. Losing it on a restart is correct — a hub that just
+ * restarted has no delivery in flight.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentDeliveryLedger = exports.DELIVERY_GRACE_MS = void 0;
+/**
+ * How long after a delivery finishes the node stays protected from a back-fill.
+ *
+ * Sized for the re-registration storm: `$agent.reload` returns when the runners
+ * have been asked to restart, and their `$hub.registerNode` calls (one per
+ * group runner — 12 on `little-unraid`) land over the following seconds. Each
+ * one fires a reconcile.
+ */
+exports.DELIVERY_GRACE_MS = 60_000;
+class AgentDeliveryLedger {
+    byNode = new Map();
+    forNode(nodeId) {
+        const existing = this.byNode.get(nodeId);
+        if (existing)
+            return existing;
+        const created = {
+            inFlight: 0,
+            lastFinishedAt: 0,
+            packages: new Set(),
+        };
+        this.byNode.set(nodeId, created);
+        return created;
+    }
+    /**
+     * A delivery to `nodeId` is starting. Returns the function that closes it —
+     * callers MUST invoke it in a `finally`, or the node stays protected for the
+     * rest of the hub's life and the back-fill silently stops repairing it.
+     */
+    begin(nodeId, packageName, now = Date.now) {
+        const state = this.forNode(nodeId);
+        state.inFlight += 1;
+        state.packages.add(packageName);
+        let closed = false;
+        return () => {
+            if (closed)
+                return;
+            closed = true;
+            state.inFlight = Math.max(0, state.inFlight - 1);
+            // Stamped at CLOSE, not at begin: the grace tail measures time since the
+            // delivery finished, and a four-minute install must not have spent its
+            // grace while it was still running.
+            state.lastFinishedAt = Math.max(state.lastFinishedAt, now());
+        };
+    }
+    /**
+     * `null` when the node is free to be back-filled; a described suppression
+     * otherwise. Returning the REASON rather than a boolean is deliberate: a
+     * back-fill that declines to run must say why, or it is indistinguishable
+     * from a back-fill that found nothing to do.
+     */
+    suppressionFor(nodeId, now = Date.now()) {
+        const state = this.byNode.get(nodeId);
+        if (!state)
+            return null;
+        const since = state.lastFinishedAt === 0 ? null : now - state.lastFinishedAt;
+        if (state.inFlight === 0 && (since === null || since >= exports.DELIVERY_GRACE_MS)) {
+            // Window closed — drop the package memory so a later suppression names
+            // only the packages of the delivery that caused it.
+            state.packages.clear();
+            return null;
+        }
+        return {
+            nodeId,
+            inFlight: state.inFlight,
+            msSinceLastDelivery: since,
+            packages: [...state.packages],
+        };
+    }
+    /** Drop everything remembered about a node (e.g. "Forget node"). */
+    forget(nodeId) {
+        this.byNode.delete(nodeId);
+    }
+}
+exports.AgentDeliveryLedger = AgentDeliveryLedger;

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

@@ -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_delivery_ledger_1 = require("./agent-delivery-ledger");
 /** Per-call timeout for `$agent.*` RPC during reconciliation. */
 const AGENT_RECONCILE_RPC_TIMEOUT_MS = 8_000;
 /**
@@ -171,6 +172,13 @@ class AgentRegistryService {
      * `agent-addon-backfill.ts`. Process-scoped, holds no intent.
      */
     backfillTracker = new agent_addon_backfill_1.BackfillAttemptTracker();
+    /**
+     * "Is the hub writing addons to this node right now?" — the gate that stops
+     * the back-fill reacting to a roster gap the hub itself opened. Public so the
+     * delivery path (`deliverAddonToAgent`) can mark its own window; see
+     * `agent-delivery-ledger.ts` for why a delivery makes the roster lie.
+     */
+    deliveryLedger = new agent_delivery_ledger_1.AgentDeliveryLedger();
     /**
      * Nodes with a reconcile in flight. The pass is triggered from two places
      * (the `registerNode` ack and the hub-boot sweep) and a reconnect can fire
@@ -245,6 +253,7 @@ class AgentRegistryService {
         // Its intended set is gone with the row, so the back-fill breaker's memory
         // of failed deliveries to it is meaningless — drop it too.
         this.backfillTracker.forget(nodeId);
+        this.deliveryLedger.forget(nodeId);
     }
     /** Typed view of the Moleculer broker — single documented cast. */
     get broker() {
@@ -263,7 +272,7 @@ class AgentRegistryService {
         // no grace delay needed. MoleculerService fires this callback from its
         // onRegisterNode dep for every bare-ID agent node.
         this.moleculer.setOnAgentRegistered((agentId) => {
-            void this.reconcileAgentAddons(agentId);
+            void this.reconcileAgentAddons(agentId, 'node-registration');
         });
         this.broker.localBus.on('$node.connected', ({ node }) => {
             const kind = classifyNode(node.id);
@@ -371,9 +380,23 @@ class AgentRegistryService {
             return;
         console.log(`[agent-registry] Boot reconcile: ${agentIds.length} connected agent(s)`);
         for (const agentId of agentIds) {
-            await this.reconcileAgentAddons(agentId);
+            await this.reconcileAgentAddons(agentId, 'hub-boot');
         }
     }
+    /**
+     * Operator-invoked repair — "this node is missing addons, put them back".
+     *
+     * The explicit half of the back-fill's trigger set. Everything automatic is
+     * gated on a node ASKING (a registration) and on the hub not being mid-write;
+     * this is the escape hatch for the case those gates decline, and it is an
+     * attributable gesture rather than a heuristic. It does exactly what the
+     * automatic pass does — no extra powers, so nothing can be repaired by hand
+     * that the node could not converge to on its own.
+     */
+    async repairNodeAddons(agentId) {
+        console.log(`[agent-registry] Repair requested by operator for ${agentId}`);
+        await this.reconcileAgentAddons(agentId, 'operator-repair');
+    }
     /**
      * Reconcile a single agent's deployed addons against the hub's installed
      * set + placements. An addon running on the agent is STALE — and must be
@@ -410,7 +433,7 @@ class AgentRegistryService {
      * All errors are caught and logged so a single bad agent never breaks
      * the caller (connect handler or boot pass).
      */
-    async reconcileAgentAddons(agentId) {
+    async reconcileAgentAddons(agentId, trigger = 'node-registration') {
         if (!this.addonRegistry) {
             console.warn(`[agent-registry] Reconcile skipped for ${agentId}: addon registry not wired`);
             return;
@@ -531,7 +554,7 @@ 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);
+            await this.backfillAgentAddons(agentId, agentAddons, undeployedPackages, hubVersions, trigger);
         }
         catch (err) {
             console.error(`[agent-registry] Reconcile failed for agent ${agentId}:`, err instanceof Error ? err.message : String(err));
@@ -552,7 +575,7 @@ class AgentRegistryService {
      * Every leg is idempotent: run twice with no change in between and step 3
      * finds nothing to do.
      */
-    async backfillAgentAddons(agentId, agentAddons, undeployedPackages, hubVersions) {
+    async backfillAgentAddons(agentId, agentAddons, undeployedPackages, hubVersions, trigger) {
         const store = this.historyStore;
         if (!store)
             return;
@@ -565,7 +588,7 @@ class AgentRegistryService {
         if (!seam)
             return;
         const recorded = await store.getPackages(agentId);
-        const plan = (0, agent_addon_backfill_1.computeBackfillPlan)({
+        const planned = (0, agent_addon_backfill_1.computeBackfillPlan)({
             recorded,
             live,
             bootstrap: AGENT_BOOTSTRAP_PACKAGES,
@@ -573,14 +596,53 @@ class AgentRegistryService {
             retired: this.backfillTracker.retiredFor(agentId),
             hubVersions,
         });
+        if (planned.targets.length === 0 &&
+            planned.retired.length === 0 &&
+            planned.unresolvable.length === 0) {
+            return;
+        }
+        // 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)`);
+            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.
+        const suppression = this.deliveryLedger.suppressionFor(agentId);
+        if (suppression !== null) {
+            console.log(`[agent-registry] Back-fill ${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`);
+            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)
+            return;
         if (plan.targets.length === 0 && plan.retired.length === 0 && plan.unresolvable.length === 0) {
             return;
         }
-        const outcome = await (0, agent_addon_backfill_1.executeBackfill)(seam, agentId, plan, this.backfillTracker);
+        // 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');
+        let outcome;
+        try {
+            outcome = await (0, agent_addon_backfill_1.executeBackfill)(seam, agentId, plan, this.backfillTracker);
+        }
+        finally {
+            closeWindow();
+        }
         if (outcome.delivered.length > 0) {
             console.log(`[agent-registry] Back-fill ${agentId}: delivered ${outcome.delivered
-                .map((d) => `${d.name}@${d.version}`)
-                .join(', ')}`);
+                .map((d) => `${d.name}@${d.version} (pin from ${d.versionSource})`)
+                .join(', ')} — trigger=${trigger}, node reported ${plan.liveCount} package(s) and its ` +
+                `declared roster has ${recorded.length}`);
             this.eventBus.emit({
                 id: (0, node_crypto_1.randomUUID)(),
                 timestamp: new Date(),
@@ -607,6 +669,42 @@ class AgentRegistryService {
             console.error(`[agent-registry] Back-fill ${agentId}: ${name} is missing but no version could be resolved (not installed on the hub, no version recorded) — not guessing "latest"`);
         }
     }
+    /**
+     * Re-read the node's roster and drop every target the second read reports
+     * present ([D49](../../../../docs/decisions/adr-0049.md)).
+     *
+     * Returns `null` when the second read cannot be trusted — an RPC failure or
+     * an unparseable status. Failing CLOSED is the whole point: the first read
+     * already said "install these", and a read that fails must not be allowed to
+     * look like agreement. The cost of the extra RPC is paid only on a pass that
+     * actually wants to install something.
+     */
+    async confirmBackfillTargets(agentId, plan) {
+        if (plan.targets.length === 0)
+            return plan;
+        let secondRaw;
+        try {
+            secondRaw = await this.broker.call('$agent.status', {}, { nodeID: agentId, timeout: AGENT_RECONCILE_RPC_TIMEOUT_MS });
+        }
+        catch (err) {
+            console.warn(`[agent-registry] Back-fill ${agentId}: SKIPPED — the confirmation read failed ` +
+                `(${err instanceof Error ? err.message : String(err)}); refusing to install over a node ` +
+                `on one unconfirmed roster`);
+            return null;
+        }
+        const secondAddons = this.extractAgentAddons(secondRaw);
+        if (secondAddons === null) {
+            console.warn(`[agent-registry] Back-fill ${agentId}: SKIPPED — the confirmation read carried no addon list`);
+            return null;
+        }
+        const { plan: confirmed, contradicted } = (0, agent_addon_backfill_1.confirmBackfillPlan)(plan, rosterFromAddons(secondAddons));
+        if (contradicted.length > 0) {
+            console.warn(`[agent-registry] Back-fill ${agentId}: two roster reads DISAGREE — ` +
+                `${contradicted.map((t) => t.name).join(', ')} reported absent then present. ` +
+                `Not installing; the node was mid-reload, not missing packages`);
+        }
+        return confirmed;
+    }
     /**
      * Narrow the `$agent.status` response down to its addon list.
      *