@camstack/server 1.2.71 → 1.2.73

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.
      *

package/dist/core/auth/share-token.service.js

@@ -98,15 +98,38 @@ function parseShareToken(data) {
 class ShareTokenService {
     getStore;
     logger;
+    /**
+     * Declaration is one-time per process; reset only if the backend itself
+     * is swapped (it never is at runtime — the getter is lazy solely because
+     * the sqlite builtin registers after this service is constructed).
+     */
+    collectionDeclared = false;
     constructor(getStore, logger = null) {
         this.getStore = getStore;
         this.logger = logger;
     }
-    store() {
+    /**
+     * Resolve the backend AND ensure `share_view_tokens` is declared before
+     * the first operation. The structured settings backend fail-closes on
+     * undeclared collections; this KV shape (`id` PK + `data` TEXT) is
+     * byte-identical to what the legacy on-demand path created, so existing
+     * rows keep working with no migration.
+     */
+    async store() {
         const store = this.getStore();
         if (!store) {
             throw new Error('Share tokens unavailable — settings backend not ready');
         }
+        if (!this.collectionDeclared) {
+            await store.declareCollection({
+                collection: SHARE_TOKENS_COLLECTION,
+                columns: [
+                    { name: 'id', type: 'TEXT', primaryKey: true, notNull: true },
+                    { name: 'data', type: 'TEXT', notNull: true },
+                ],
+            });
+            this.collectionDeclared = true;
+        }
         return store;
     }
     /**
@@ -137,7 +160,7 @@ class ShareTokenService {
             createdAt: now,
             expiresAt: ttlSec === 'never' ? null : now + ttlSec * 1000,
         };
-        await this.store().insert({
+        await (await this.store()).insert({
             collection: SHARE_TOKENS_COLLECTION,
             record: { id: record.id, data: { ...record } },
         });
@@ -161,7 +184,7 @@ class ShareTokenService {
         if (!rawToken.startsWith(exports.SHARE_TOKEN_PREFIX))
             return null;
         const tokenHash = crypto.createHash('sha256').update(rawToken).digest('hex');
-        const results = await this.store().query({
+        const results = await (await this.store()).query({
             collection: SHARE_TOKENS_COLLECTION,
             filter: { where: { tokenHash } },
         });
@@ -186,7 +209,7 @@ class ShareTokenService {
      * permission mismatch so the router surfaces a FORBIDDEN.
      */
     async revoke(input) {
-        const results = await this.store().query({
+        const results = await (await this.store()).query({
             collection: SHARE_TOKENS_COLLECTION,
             filter: { where: { id: input.id } },
         });
@@ -196,13 +219,13 @@ class ShareTokenService {
         const record = parseShareToken(first.data);
         if (!record) {
             // Corrupt record — delete it regardless (it can never validate).
-            await this.store().delete({ collection: SHARE_TOKENS_COLLECTION, key: input.id });
+            await (await this.store()).delete({ collection: SHARE_TOKENS_COLLECTION, key: input.id });
             return true;
         }
         if (!input.callerIsAdmin && record.userId !== input.callerUserId) {
             throw new Error('Only the token owner or an admin can revoke a share token');
         }
-        await this.store().delete({ collection: SHARE_TOKENS_COLLECTION, key: input.id });
+        await (await this.store()).delete({ collection: SHARE_TOKENS_COLLECTION, key: input.id });
         this.logger?.info('Share token revoked', {
             meta: { id: record.id, byUserId: input.callerUserId },
         });
@@ -210,7 +233,7 @@ class ShareTokenService {
     }
     /** Every share token minted by `userId`, expired ones included. */
     async listForUser(userId) {
-        const results = await this.store().query({
+        const results = await (await this.store()).query({
             collection: SHARE_TOKENS_COLLECTION,
             filter: { where: { userId } },
         });
@@ -218,14 +241,14 @@ class ShareTokenService {
     }
     /** All share tokens (admin listing). */
     async listAll() {
-        const results = await this.store().query({
+        const results = await (await this.store()).query({
             collection: SHARE_TOKENS_COLLECTION,
             filter: {},
         });
         return results.map((r) => parseShareToken(r.data)).filter((r) => r !== null);
     }
     async touchLastUsed(record) {
-        await this.store().update({
+        await (await this.store()).update({
             collection: SHARE_TOKENS_COLLECTION,
             id: record.id,
             data: { ...record, lastUsedAt: Date.now() },

package/dist/launcher.js

@@ -52,10 +52,12 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * node-root `applyServerUpdate` flow, not an in-launcher package swap.
  */
 const fs = __importStar(require("node:fs"));
+const os = __importStar(require("node:os"));
 const path = __importStar(require("node:path"));
 const tar = __importStar(require("tar"));
 const yaml = __importStar(require("js-yaml"));
 const framework_nodepath_js_1 = require("./framework-nodepath.js");
+const addon_root_inventory_js_1 = require("./addon-root-inventory.js");
 const package_inventory_js_1 = require("./package-inventory.js");
 const bootstrap_packages_js_1 = require("./bootstrap-packages.js");
 /** Path of the manifest file embedded inside every archive. */
@@ -340,11 +342,14 @@ async function launch() {
     const bootstrapRequired = readBootstrapRequiredAddons(dataDir, bootstrapSchema) ?? roleDefaultBootstrap;
     console.log(`[launcher] bootstrap (${role}): ${bootstrapRequired.length} required package(s)`);
     await installer.ensureRequiredPackages(bootstrapRequired);
-    // Reconcile the install manifest with what is on disk. Addons baked
-    // into the image are copied straight into addonsDir by the container
-    // entrypoint and never pass through an install codepath, so they are
-    // absent from manifest.json — which makes runtime "Update" reject them
-    // with "not currently tracked in manifest". Idempotent; safe every boot.
+    // Reconcile the install manifest against what is on disk — the directory is
+    // the truth, because it is what the loader runs. Registers image-seeded
+    // addons (copied straight into addonsDir by the container entrypoint, never
+    // through an install codepath, so runtime "Update" rejected them as "not
+    // currently tracked"), corrects a recorded version that disagrees with the
+    // installed package.json, and drops entries naming a directory that does not
+    // exist. Idempotent; safe every boot. Runs BEFORE any update can be in
+    // flight, and never touches an entry holding a rollback pointer.
     //
     // Guarded with a typeof check: the backend and @camstack/system normally
     // ship together in one image, but a system-only framework update can
@@ -354,7 +359,7 @@ async function launch() {
     if (typeof installer.reconcileManifest === 'function') {
         const reconciled = installer.reconcileManifest();
         if (reconciled > 0) {
-            console.log(`[launcher] Manifest reconciled — ${reconciled} seeded addon(s) registered`);
+            console.log(`[launcher] Manifest reconciled — ${reconciled} correction(s)`);
         }
     }
     else {
@@ -494,6 +499,72 @@ async function launch() {
         // to boot when it is the thing that was supposed to explain failures.
         console.warn(`[launcher] package inventory failed: ${err instanceof Error ? err.message : String(err)}`);
     }
+    // A SECOND ADDON ROOT on this machine.
+    //
+    // The inventory above scans roots derived from the ACTIVE data dir, so an
+    // entire rival data root — a retired Electron app id, the pre-Electron
+    // `~/camstack-agent-data` — is structurally invisible to it. Those trees hold
+    // complete `addons/@camstack/` installs with plausible package.json files,
+    // and reading a version out of one answers a question about a node that has
+    // not run since June. Measured on the Mac agent: four addon roots, four
+    // truthful `addon-pipeline` versions, one of them the running node's.
+    //
+    // Reported, never fatal, never deleted here — same policy as D45. Making the
+    // second location LOUD is the whole job; removing it stays an operator
+    // decision. `CAMSTACK_INVENTORY_STRICT=1` makes it fatal, which is how a
+    // machine that HAS been cleaned keeps itself clean.
+    try {
+        const addonRoots = (0, addon_root_inventory_js_1.inventoryAddonRoots)({
+            dataDir: DATA_DIR,
+            activeAddonsDir: addonsDir,
+            homeDir: os.homedir(),
+            platform: process.platform,
+        }, {
+            exists: (dir) => fs.existsSync(dir),
+            listPackages: (scopeDir) => {
+                try {
+                    return fs
+                        .readdirSync(scopeDir, { withFileTypes: true })
+                        .filter((e) => e.isDirectory() || e.isSymbolicLink())
+                        .map((e) => e.name);
+                }
+                catch {
+                    return [];
+                }
+            },
+            readVersion: (packageDir) => {
+                try {
+                    const raw = JSON.parse(fs.readFileSync(path.join(packageDir, 'package.json'), 'utf-8'));
+                    const version = typeof raw === 'object' && raw !== null
+                        ? raw.version
+                        : undefined;
+                    return typeof version === 'string' ? version : null;
+                }
+                catch {
+                    return null;
+                }
+            },
+            realPath: (dir) => {
+                try {
+                    return fs.realpathSync(dir);
+                }
+                catch {
+                    return dir;
+                }
+            },
+        });
+        const addonRootReport = (0, addon_root_inventory_js_1.formatAddonRootReport)(addonRoots);
+        if (addonRootReport !== '') {
+            console.error(`[launcher] ${addonRootReport}`);
+            if (process.env['CAMSTACK_INVENTORY_STRICT'] === '1') {
+                console.error('[launcher] CAMSTACK_INVENTORY_STRICT=1 — refusing to boot on this layout');
+                process.exit(1);
+            }
+        }
+    }
+    catch (err) {
+        console.warn(`[launcher] addon-root inventory failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
     // Now safe to load the role's runtime entry (both have static imports from
     // @camstack/system, resolved only after the framework dir + NODE_PATH setup
     // above). The agent boots from THIS same @camstack/server closure — there is