@camstack/server 1.2.101 → 1.2.102

package/dist/agent/main.js

@@ -37,6 +37,7 @@ exports.startAgent = startAgent;
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
 const agent_http_js_1 = require("./agent-http.js");
+const single_copy_cleanup_runner_js_1 = require("../single-copy-cleanup-runner.js");
 const derive_hub_url_js_1 = require("./derive-hub-url.js");
 const system_1 = require("@camstack/system");
 const types_1 = require("@camstack/types");
@@ -381,6 +382,18 @@ async function startAgent(configPath) {
         catch (err) {
             consoleLogger.warn(`agent root boot confirmation failed: ${err instanceof Error ? err.message : String(err)}`);
         }
+        // ONE COPY PER NODE — the same sweep the hub runs, at this role's own
+        // healthy-boot moment (D45, task 32). Operator, 2026-08-13: "l'agente deve
+        // essere identico all'hub". An agent is where the redundant copies actually
+        // are: `little-unraid` still holds `<dataDir>/addons/@camstack/system@1.2.78`
+        // — a copy nothing loads (both roles pass `['@camstack/system']` as the
+        // loader's skip list) and that WINS over the closure for anything resolving
+        // through it.
+        void (0, single_copy_cleanup_runner_js_1.runSingleCopyCleanup)({
+            dataDir: config.dataDir,
+            addonRoot: config.addonsDir,
+            log: (line) => consoleLogger.info(line),
+        });
     };
     // Logger factory — creates scoped loggers from the shared LogManager.
     // All entries flow through registered ILogDestination providers (hub-forwarder).

package/dist/first-boot-addon-plan.js

@@ -1,114 +1,50 @@
 "use strict";
 /**
- * What a node WOULD install at first boot once the image stops carrying an
- * addon seed tree — [D45](../../../docs/decisions/adr-0045.md), task 32.
+ * What a node installs at first boot once the image stops carrying a
+ * NON-system addon seed tree — [D45](../../../docs/decisions/adr-0045.md),
+ * task 32.
  *
- * Operator directive, 2026-08-12: the docker seed stays for `@camstack/server`
- * and the system packages ("una copia di server e dei pacchetti di sistema"),
- * and *"tutti gli altri addons devono rimanere copia unica, sempre, installati
- * durante l'avvio iniziale"*. Dropping `/opt/camstack-seed-addons` moves the
- * version decision from image-build time — where the Dockerfile installs the
- * exact version the hub closure resolved — to boot time. Something then has to
- * answer two questions the seed answered implicitly:
+ * Operator decisions, 2026-08-12/13:
  *
- * 1. **Which version?** The closure's own `package.json` is the pin, and it is
- *    not always there: `@camstack/server` 1.2.90…1.2.94 were published with
- *    `"@camstack/addon-pipeline": "*"` (pin-root-deps did not run on those
- *    releases), 1.2.96+ carry exact versions. Unpinned resolves to `latest`,
- *    and that is REPORTED rather than hidden — a node that installed
- *    latest-of-everything cannot answer "what shipped here".
- * 2. **What about the copy already on disk?** It wins, always
- *    ([D90](../../../docs/decisions/adr-0090.md)). The live hub runs
- *    `addon-pipeline` 1.2.69 against an image seed of 1.2.64; replacing a
- *    deployed copy with the closure's number is exactly the rollback the
- *    unconditional `cp -a` caused. So an installed copy is ADOPTED — and a gap
- *    against the pin is reported, never repaired behind the operator's back.
+ * - the docker seed stays for `@camstack/server` and the SYSTEM packages, as
+ *   the first-boot fallback source; every other addon is single-copy, always,
+ *   installed during the initial boot;
+ * - **no pinning at all** — *"il sistema è designato per essere
+ *   addons-agnostic, latest va sempre bene al primo boot"*. There is no version
+ *   contract between the closure and an addon, so first boot asks for `latest`
+ *   and the copy that lands is the one the node keeps.
  *
- * Everything here is pure: the caller supplies the roster, the pins and what is
- * on disk. It installs nothing and it decides nothing about booting — the
- * launcher runs it in OBSERVE mode, which prints the plan and changes no
- * behaviour.
+ * So this module answers exactly one question per package — *fetch it, adopt
+ * what is already here, or leave it to the closure* — and reports the version
+ * the running closure happens to carry beside the installed one, as INFO. That
+ * comparison is not a pin and never drives an action: the installed copy wins,
+ * always ([D90](../../../docs/decisions/adr-0090.md)). It exists because the
+ * same package having two truthful versions on one node is what task 32 is
+ * about — the hub runs `addon-pipeline` 1.2.69 while its own closure carries
+ * 1.2.64, and nothing said so out loud until now.
+ *
+ * Pure: the caller supplies the roster, what is on disk and what the closure
+ * carries. It installs nothing and can never end a boot.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.resolveWantedVersion = resolveWantedVersion;
-exports.compareVersions = compareVersions;
-exports.bootstrapPinsFrom = bootstrapPinsFrom;
 exports.planFirstBootAddons = planFirstBootAddons;
 exports.formatFirstBootPlan = formatFirstBootPlan;
-/** A plain `major.minor.patch`, optionally with a prerelease/build suffix. */
-const EXACT_VERSION = /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z-.]+)?$/;
-/**
- * The version a fetch should ask for, given whatever the closure declared.
- *
- * Only an EXACT version is a pin. A range (`^1.2.0`) is deliberately not
- * honoured: `installFromNpm`'s registry path resolves exact versions and
- * dist-tags only (ranges fall back to `npm pack`), so pretending to support one
- * here would produce a spec the fetch cannot use. Everything else — `*`, a
- * range, an absent dep — becomes `latest`, flagged as unpinned so the caller
- * can say it out loud.
- */
-function resolveWantedVersion(raw) {
-    if (raw !== undefined && EXACT_VERSION.test(raw))
-        return { spec: raw, pinned: true };
-    return { spec: 'latest', pinned: false };
-}
-/**
- * Compare two plain versions. `1` when `a` is newer, `-1` when older, `0` when
- * equal, `null` when either side is not a plain `x.y.z`.
- *
- * A local comparator rather than `@camstack/node-root`'s: that package is
- * `private: true` and is ABSENT from the server closure, and this module is
- * reached from `launcher.ts`, which is `tsc` output rather than a bundle — an
- * import of it would be an unresolvable `require` at boot (the trap recorded in
- * `docs/architecture/update-and-release.md`). Prerelease ordering is not
- * modelled: nothing in the bootstrap roster ships one, and guessing at
- * prerelease precedence would be a second, subtly different semver.
- */
-function compareVersions(a, b) {
-    if (!EXACT_VERSION.test(a) || !EXACT_VERSION.test(b))
-        return null;
-    const parse = (v) => v
-        .split(/[-+]/)[0]
-        .split('.')
-        .map((n) => Number.parseInt(n, 10));
-    const left = parse(a);
-    const right = parse(b);
-    for (let i = 0; i < 3; i++) {
-        const l = left[i] ?? 0;
-        const r = right[i] ?? 0;
-        if (l !== r)
-            return l > r ? 1 : -1;
-    }
-    return 0;
-}
-/** The `@camstack/*` half of a closure manifest's dependencies — the pins. */
-function bootstrapPinsFrom(manifest) {
-    const out = {};
-    for (const [name, spec] of Object.entries(manifest.dependencies ?? {})) {
-        if (name.startsWith('@camstack/'))
-            out[name] = spec;
-    }
-    return out;
-}
 /** The plan. Pure; installs nothing. */
 function planFirstBootAddons(input) {
     const provided = new Set(input.closureProvided);
-    const decisions = input.required.map((pkg) => decide(pkg, input.closurePins[pkg], input.installed, provided));
+    const decisions = input.required.map((pkg) => decide(pkg, input.installed, input.closureVersions, provided));
     const wouldInstall = decisions.filter((d) => d.action === 'install-npm').map((d) => d.pkg);
     return {
         decisions,
         wouldInstall,
-        unpinned: decisions
-            .filter((d) => d.action === 'install-npm' && !d.want.pinned)
-            .map((d) => d.pkg),
-        divergent: decisions.filter((d) => d.divergent).map((d) => d.pkg),
+        twoVersions: decisions.filter((d) => d.twoVersions).map((d) => d.pkg),
         needsRegistry: wouldInstall.length > 0,
     };
 }
-function decide(pkg, pin, installed, closureProvided) {
-    const want = resolveWantedVersion(pin);
+function decide(pkg, installed, closureVersions, closureProvided) {
     const hasEntry = Object.hasOwn(installed, pkg);
     const version = installed[pkg] ?? null;
+    const closureVersion = closureVersions[pkg] ?? null;
     // Host-provided and reachable: a copy under the addon root WINS over the
     // closure and nothing refreshes it — the shape that left both agents 17
     // versions behind. Same rule as `shouldSkipClosureProvidedSeed`.
@@ -116,9 +52,9 @@ function decide(pkg, pin, installed, closureProvided) {
         return {
             pkg,
             action: 'skip-closure-provided',
-            want,
             installedVersion: version,
-            divergent: false,
+            closureVersion,
+            twoVersions: false,
             reason: 'provided by the server closure — a copy here would shadow it (D15)',
         };
     }
@@ -126,56 +62,24 @@ function decide(pkg, pin, installed, closureProvided) {
         return {
             pkg,
             action: 'install-npm',
-            want,
             installedVersion: null,
-            divergent: false,
+            closureVersion,
+            twoVersions: false,
             reason: hasEntry
-                ? `installed copy has an unreadable package.json — fetching ${want.spec}`
-                : want.pinned
-                    ? `absent — fetch ${want.spec}, the version the running closure pins`
-                    : 'absent, and the closure carries no pin — fetching latest',
+                ? 'installed copy has an unreadable package.json — fetching latest'
+                : 'absent — fetching latest, which is the whole version contract (addons-agnostic)',
         };
     }
+    const twoVersions = closureVersion !== null && closureVersion !== version;
     return {
         pkg,
         action: 'adopt-installed',
-        want,
         installedVersion: version,
-        ...adoptionVerdict(version, want),
-    };
-}
-/**
- * Whether an installed copy agrees with the pin — and, when it does not, in
- * which direction. The copy is adopted either way: `<dataDir>/addons` is the
- * runtime authority and an image number must never outrank it (D90). What
- * changes is whether the boot says something about it.
- */
-function adoptionVerdict(version, want) {
-    if (!want.pinned) {
-        return { divergent: false, reason: `installed ${version}; the closure carries no pin to check` };
-    }
-    const order = compareVersions(version, want.spec);
-    if (order === null) {
-        return { divergent: true, reason: `installed ${version} is not comparable to pin ${want.spec}` };
-    }
-    if (order === 0)
-        return { divergent: false, reason: `installed ${version} matches the pin` };
-    const sameMajor = version.split('.')[0] === want.spec.split('.')[0];
-    if (!sameMajor) {
-        return {
-            divergent: true,
-            reason: `installed ${version} is a different major from the pinned ${want.spec} — a framework contract, not a version gap`,
-        };
-    }
-    if (order > 0) {
-        return {
-            divergent: false,
-            reason: `installed ${version} is ahead of the pinned ${want.spec} — a deploy outranks the image (D90)`,
-        };
-    }
-    return {
-        divergent: true,
-        reason: `installed ${version} is BEHIND the pinned ${want.spec} — kept, because replacing it is an un-deploy`,
+        closureVersion,
+        twoVersions,
+        reason: twoVersions
+            ? `installed ${version}; this closure carries ${closureVersion} — the installed copy is what runs (D90)`
+            : `installed ${version} — kept`,
     };
 }
 /**
@@ -189,18 +93,17 @@ function adoptionVerdict(version, want) {
  */
 function formatFirstBootPlan(plan, mode) {
     const header = `first-boot addon plan (${mode}) — ${plan.decisions.length} package(s), ` +
-        `${plan.wouldInstall.length} to install, ${plan.divergent.length} divergent`;
+        `${plan.wouldInstall.length} to install`;
     const lines = [
         mode === 'observe' ? `${header}; nothing was installed from this plan` : header,
     ];
     for (const d of plan.decisions) {
-        const target = d.action === 'install-npm' ? `@${d.want.spec}` : '';
+        const target = d.action === 'install-npm' ? '@latest' : '';
         lines.push(`  ${d.pkg}${target} — ${d.action}: ${d.reason}`);
     }
-    if (plan.unpinned.length > 0) {
-        lines.push(`  unpinned (would resolve the registry's latest): ${plan.unpinned.join(', ')} — ` +
-            'the running closure declares no exact version for these, so what a node ends ' +
-            'up with depends on when it booted');
+    if (plan.twoVersions.length > 0) {
+        lines.push(`  two versions on this node (installed vs this closure's own copy): ${plan.twoVersions.join(', ')} — ` +
+            'INFO: the installed copy is the one that runs');
     }
     if (!plan.needsRegistry) {
         lines.push('  no registry access needed — every required addon is already on disk');

package/dist/launcher.js

@@ -394,25 +394,25 @@ async function launch() {
     const roleDefaultBootstrap = role === 'agent' ? AddonInstaller.AGENT_PACKAGES : deriveBootstrapFromSelf();
     const bootstrapRequired = readBootstrapRequiredAddons(dataDir, bootstrapSchema) ?? roleDefaultBootstrap;
     console.log(`[launcher] bootstrap (${role}): ${bootstrapRequired.length} required package(s)`);
-    // WHAT WOULD A SEED-FREE IMAGE DO HERE? (D45 task 32 — OBSERVE ONLY)
+    // THE FIRST-BOOT ADDON PLAN — reported every boot (D45 task 32).
     //
-    // The image still bakes an addon seed tree, so `ensureRequiredPackages` below
-    // usually finds every package already on disk. Once the seed leaves the image
-    // ("tutti gli altri addons devono rimanere copia unica, sempre, installati
-    // durante l'avvio iniziale", 2026-08-12) this same roster has to come from the
-    // registry, at a version somebody chose. This block prints that plan and
-    // NOTHING ELSE: no install, no version argument, no branch. It exists so the
-    // decision can be read off real boots — how many packages a node would fetch,
-    // which ones the closure carries no pin for, and where a deployed copy already
-    // disagrees with it — before any of it is switched on.
+    // The image no longer bakes a NON-system addon tree, so this roster comes
+    // from the registry on a fresh node: "tutti gli altri addons devono rimanere
+    // copia unica, sempre, installati durante l'avvio iniziale" (2026-08-12), at
+    // `latest`, because "il sistema e' designato per essere addons-agnostic"
+    // (2026-08-13). The plan below is what `ensureRequiredPackages` is about to
+    // do, said out loud BEFORE it happens: how many packages this node must fetch
+    // (i.e. whether this boot needs the registry at all), and where an installed
+    // copy differs from the one inside this very closure — one node, two truthful
+    // versions, which is the condition task 32 exists to end.
     //
     // Diagnostics, so it can never end a boot: same policy as the inventories.
     try {
-        const ownManifest = readOwnManifest();
+        const closureNodeModules = path.resolve(__dirname, '..', 'node_modules');
         const plan = (0, first_boot_addon_plan_js_1.planFirstBootAddons)({
             required: bootstrapRequired,
-            closurePins: ownManifest === null ? {} : (0, first_boot_addon_plan_js_1.bootstrapPinsFrom)(ownManifest),
             installed: readInstalledAddonVersions(addonsDir, bootstrapRequired),
+            closureVersions: readInstalledAddonVersions(closureNodeModules, bootstrapRequired),
             // Mirrors `shouldSkipClosureProvidedSeed`: only `@camstack/system`, and
             // only while it actually resolves.
             closureProvided: (() => {

package/dist/main.js

@@ -46,6 +46,7 @@ const ws_2 = require("ws");
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
 const node_child_process_1 = require("node:child_process");
+const single_copy_cleanup_runner_js_1 = require("./single-copy-cleanup-runner.js");
 const logging_service_1 = require("./core/logging/logging.service");
 const event_bus_service_1 = require("./core/events/event-bus.service");
 const config_service_1 = require("./core/config/config.service");
@@ -1290,6 +1291,23 @@ async function bootstrap() {
             meta: { error: err instanceof Error ? err.message : String(err) },
         });
     }
+    // ONE COPY PER NODE — the sweep, at the only moment it is safe (D45, task 32).
+    //
+    // The boot above is confirmed healthy and the hub is serving, so the legacy
+    // `<dataDir>/framework` tree and any host-provided package under the addon
+    // root are redundant: nothing loads them, and each is a resolution race that
+    // has already cost this project three wrong diagnoses in one evening.
+    //
+    // It runs HERE and not in the launcher because "healthy" is the gate. Before
+    // the hub is up, the copies this removes are the recovery path — the image
+    // seeds them for exactly the boot that would otherwise fail. The agent runs
+    // the SAME function at its own confirmation point; neither role owns a
+    // private idea of what may be deleted.
+    void (0, single_copy_cleanup_runner_js_1.runSingleCopyCleanup)({
+        dataDir: dataPath,
+        addonRoot: process.env['CAMSTACK_ADDONS_DIR'] ?? path.join(dataPath, 'addons'),
+        log: (line) => logger.info(line),
+    });
     // One-time backfill: stamp integrationId on devices created before the
     // device-manager forwarder started stamping it (legacy camera providers),
     // so deleting their integration cascades them. Idempotent — only touches

package/dist/single-copy-cleanup-runner.js

@@ -0,0 +1,128 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runSingleCopyCleanup = runSingleCopyCleanup;
+/**
+ * The one adapter that runs the post-boot single-copy sweep on BOTH roles.
+ *
+ * Operator, 2026-08-13: *"l'agente deve essere identico all'hub"*. Two code
+ * paths that must agree get one implementation — the hub calls this after its
+ * boot-health confirmation, the agent after its first acked `registerNode`, and
+ * neither owns a private idea of what may be deleted.
+ *
+ * Everything decidable lives in `single-copy-cleanup.ts` and is pure. This file
+ * only reads the real world: the active-root env, where `@camstack/system`
+ * actually resolved, the effective `NODE_PATH`, and the disk.
+ *
+ * It never throws. A sweep that fails leaves a node with an extra directory; a
+ * sweep that ends a process is an outage, and the copies it removes exist
+ * precisely because a node once could not boot.
+ */
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const single_copy_cleanup_js_1 = require("./single-copy-cleanup.js");
+const EMPTY_RESULT = { removed: [], failed: [], refused: true };
+/**
+ * Discover, plan, report, sweep. Called only from a point where the role has
+ * already confirmed its boot healthy — that confirmation IS the gate, and it is
+ * re-stated as `bootHealthy: true` here so the pure planner can be exercised
+ * from both sides in a test.
+ */
+async function runSingleCopyCleanup(opts) {
+    try {
+        if (!(0, single_copy_cleanup_js_1.isCleanupEnabled)(process.env)) {
+            opts.log('single-copy cleanup disabled by CAMSTACK_SINGLE_COPY_CLEANUP — nothing removed');
+            return EMPTY_RESULT;
+        }
+        const candidates = (0, single_copy_cleanup_js_1.discoverRedundantCopies)({
+            dataDir: opts.dataDir,
+            addonRoot: opts.addonRoot,
+            closureProvides: (pkg) => {
+                try {
+                    require.resolve(`${pkg}/package.json`);
+                    return true;
+                }
+                catch {
+                    return false;
+                }
+            },
+        }, {
+            exists: (p) => fs.existsSync(p),
+            readVersion: (dir) => readVersion(dir),
+        });
+        const plan = (0, single_copy_cleanup_js_1.planSingleCopyCleanup)({
+            activeRoot: process.env['CAMSTACK_SERVER_ACTIVE_ROOT'] ?? null,
+            closureResolvedFrom: resolveSystemPath(),
+            bootHealthy: true,
+            nodePathEntries: (process.env['NODE_PATH'] ?? '')
+                .split(process.platform === 'win32' ? ';' : ':')
+                .map((entry) => entry.trim())
+                .filter((entry) => entry.length > 0),
+            candidates,
+        });
+        for (const line of (0, single_copy_cleanup_js_1.formatCleanupPlan)(plan))
+            opts.log(line);
+        return await (0, single_copy_cleanup_js_1.executeSingleCopyCleanup)(plan, {
+            exists: (p) => fs.existsSync(p),
+            rename: (from, to) => fs.renameSync(from, to),
+            remove: async (p) => {
+                await fs.promises.rm(p, { recursive: true, force: true });
+            },
+        }, opts.log);
+    }
+    catch (err) {
+        opts.log(`single-copy cleanup failed: ${err instanceof Error ? err.message : String(err)} — nothing was removed`);
+        return EMPTY_RESULT;
+    }
+}
+/** Where this process actually resolved `@camstack/system`, or `null`. */
+function resolveSystemPath() {
+    try {
+        return require.resolve('@camstack/system/package.json');
+    }
+    catch {
+        return null;
+    }
+}
+function 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;
+    }
+}

package/dist/single-copy-cleanup.js

@@ -0,0 +1,241 @@
+"use strict";
+/**
+ * Post-boot convergence to ONE copy per node — [D45](../../../docs/decisions/adr-0045.md),
+ * task 32.
+ *
+ * Operator decisions, 2026-08-13:
+ *
+ * - the SYSTEM seed stays in the image, as the first-boot and fallback source
+ *   (*"teniamo gli addons di sistema nell'immagine per il primo boot, da usare
+ *   in caso di fallback"*);
+ * - once a node **has booted correctly**, the redundant DATA-side copies are
+ *   removed — the legacy `<dataDir>/framework` tree and any host-provided
+ *   package sitting under the addon root;
+ * - the end state is one version of everything per node, and an agent is
+ *   identical to a hub.
+ *
+ * The removal is the easy half. The dangerous half is WHEN, because every copy
+ * this deletes is one that something could still be resolving:
+ *
+ * | Situation | Why cleaning would brick the node |
+ * | --- | --- |
+ * | BAKED mode (no `<dataDir>/server-root/current`) | the node is running FROM the fallback tree |
+ * | `@camstack/system` resolved outside the active closure | the copy being deleted may be the one in memory |
+ * | the tree is still on `NODE_PATH` | a live resolution path, whatever the mode says |
+ * | boot not confirmed healthy | the copies are the recovery path, needed exactly now |
+ *
+ * So the plan is gated four ways, the executor refuses a blocked plan a second
+ * time, and a refusal is LOUD — a sweep that quietly did nothing is
+ * indistinguishable from a node that was already clean.
+ *
+ * Removal is rename-then-delete, the pattern `evictInstallDir` already uses on
+ * this FUSE mount: the rename is what ends the shadowing and it succeeds with
+ * inodes still open; the delete is best-effort. A copy that could not even be
+ * renamed is REPORTED, never swallowed.
+ *
+ * Pure planning + an injected filesystem, so the whole thing is testable
+ * against a described layout rather than a real disk.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CLOSURE_PROVIDED_PACKAGES = void 0;
+exports.planSingleCopyCleanup = planSingleCopyCleanup;
+exports.executeSingleCopyCleanup = executeSingleCopyCleanup;
+exports.formatCleanupPlan = formatCleanupPlan;
+exports.discoverRedundantCopies = discoverRedundantCopies;
+exports.isCleanupEnabled = isCleanupEnabled;
+/** Image trees. The fallback source lives here and is never data-side. */
+const IMAGE_PREFIX = '/opt/';
+/**
+ * Decide what may be removed. Pure.
+ *
+ * The node-wide gates come first and are absolute: a blocked plan removes
+ * nothing at all, whatever the individual candidates look like.
+ */
+function planSingleCopyCleanup(input) {
+    const blockedReason = nodeWideBlock(input);
+    if (blockedReason !== null) {
+        return {
+            remove: [],
+            keep: input.candidates.map((candidate) => ({ candidate, reason: blockedReason })),
+            blocked: true,
+            blockedReason,
+        };
+    }
+    const remove = [];
+    const keep = [];
+    for (const candidate of input.candidates) {
+        const refusal = perCandidateRefusal(candidate, input);
+        if (refusal === null)
+            remove.push(candidate);
+        else
+            keep.push({ candidate, reason: refusal });
+    }
+    return { remove, keep, blocked: false, blockedReason: null };
+}
+/** The reasons NOTHING may be removed this boot. */
+function nodeWideBlock(input) {
+    if (!input.bootHealthy) {
+        return 'this boot is not confirmed healthy — the redundant copies are the recovery path and stay';
+    }
+    if (input.activeRoot === null) {
+        return 'baked mode: there is no active closure, so the node is running FROM the fallback tree';
+    }
+    if (input.closureResolvedFrom === null) {
+        return 'the process resolved no @camstack/system at all — nothing here is safe to remove';
+    }
+    if (!isInside(input.closureResolvedFrom, input.activeRoot)) {
+        return (`@camstack/system resolved from ${input.closureResolvedFrom}, which is OUTSIDE the active ` +
+            'closure — the copy being removed could be the one in memory');
+    }
+    return null;
+}
+/** Why this ONE copy stays, or `null` when it may go. */
+function perCandidateRefusal(candidate, input) {
+    if (input.activeRoot !== null && isInside(candidate.path, input.activeRoot)) {
+        return 'inside the active closure — this is the copy that runs, not a redundant one';
+    }
+    if (candidate.path.startsWith(IMAGE_PREFIX)) {
+        return 'an image tree — the operator keeps it as the first-boot and fallback source';
+    }
+    const onNodePath = input.nodePathEntries.some((entry) => entry === candidate.path || isInside(entry, candidate.path));
+    if (onNodePath) {
+        return 'still on NODE_PATH — a live resolution path, whatever the boot mode says';
+    }
+    return null;
+}
+/** Is `child` the same path as `parent`, or under it? Separator-aware. */
+function isInside(child, parent) {
+    const normalise = (p) => (p.endsWith('/') ? p.slice(0, -1) : p);
+    const c = normalise(child);
+    const p = normalise(parent);
+    return c === p || c.startsWith(`${p}/`);
+}
+/**
+ * Carry out a plan. Never throws: a cleanup that fails is a node with an extra
+ * directory, and a cleanup that ends a process is an outage.
+ *
+ * The blocked check is repeated here on purpose. `planSingleCopyCleanup` is the
+ * only intended producer, but a hand-assembled plan must not be able to walk
+ * past the one gate that keeps this from running at the wrong moment.
+ */
+async function executeSingleCopyCleanup(plan, fs, log) {
+    if (plan.blocked) {
+        log(`single-copy cleanup REFUSED — ${plan.blockedReason ?? 'blocked'}`);
+        return { removed: [], failed: [], refused: true };
+    }
+    const removed = [];
+    const failed = [];
+    for (const candidate of plan.remove) {
+        if (!fs.exists(candidate.path))
+            continue;
+        const label = `${candidate.pkg ?? candidate.kind} ${candidate.version ?? '<unknown version>'}`;
+        const aside = `${candidate.path}.removing-${new Date().toISOString().replace(/[:.]/g, '-')}`;
+        try {
+            await fs.rename(candidate.path, aside);
+        }
+        catch (err) {
+            failed.push(candidate.path);
+            log(`single-copy cleanup — could NOT remove ${candidate.path} (${label}): ${errMsg(err)}`);
+            continue;
+        }
+        // Past this line the copy can no longer be resolved by anything, which is
+        // the whole point; the bytes are a separate, best-effort concern.
+        removed.push(candidate.path);
+        log(`single-copy cleanup — removed ${candidate.path} (${label})`);
+        try {
+            await fs.remove(aside);
+        }
+        catch (err) {
+            log(`single-copy cleanup — ${aside} still on disk (held open?): ${errMsg(err)}`);
+        }
+    }
+    return { removed, failed, refused: false };
+}
+function errMsg(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/**
+ * The report. Always says how many copies it looked at, so a boot that removed
+ * nothing is distinguishable from a boot where the sweep never ran — and a
+ * BLOCKED sweep names every copy it left behind, because those are exactly the
+ * ones an operator would otherwise believe were gone.
+ */
+function formatCleanupPlan(plan) {
+    const lines = [];
+    if (plan.blocked) {
+        lines.push(`single-copy cleanup blocked — ${plan.blockedReason ?? 'unknown reason'}; ` +
+            `${plan.keep.length} copy(ies) kept`);
+    }
+    else {
+        lines.push(`single-copy cleanup — ${plan.remove.length} copy(ies) to remove`);
+    }
+    for (const c of plan.remove) {
+        lines.push(`  remove ${c.path} — ${c.pkg ?? c.kind} ${c.version ?? '<unknown version>'}`);
+    }
+    for (const k of plan.keep) {
+        lines.push(`  keep   ${k.candidate.path} — ${k.candidate.pkg ?? k.candidate.kind} ` +
+            `${k.candidate.version ?? '<unknown version>'}: ${k.reason}`);
+    }
+    return lines;
+}
+/**
+ * The host-provided packages the closure carries. A copy of any of these under
+ * the addon root WINS over the closure and is never refreshed — the shape that
+ * left both agents 17 versions behind ([D107](../../../docs/decisions/adr-0107.md)),
+ * and the reason `<dataDir>/addons/@camstack/system` is on the agent's disk at
+ * 1.2.78 while it runs a newer closure.
+ */
+exports.CLOSURE_PROVIDED_PACKAGES = [
+    '@camstack/system',
+    '@camstack/types',
+    '@camstack/sdk',
+    '@camstack/shm-ring',
+    '@camstack/ui-library',
+];
+/**
+ * Every redundant DATA-side copy on this node, in removal order: the legacy
+ * framework tree first, then the host-provided packages under the addon root.
+ *
+ * A copy whose `package.json` will not parse is still reported, with a null
+ * version — dropping it would under-report exactly the kind that has been
+ * sitting somewhere since an interrupted install.
+ */
+function discoverRedundantCopies(input, fs) {
+    const found = [];
+    const legacyFramework = `${trimSlash(input.dataDir)}/framework`;
+    if (fs.exists(legacyFramework)) {
+        found.push({
+            kind: 'legacy-framework-tree',
+            path: legacyFramework,
+            pkg: null,
+            version: fs.readVersion(`${legacyFramework}/node_modules/@camstack/system`),
+        });
+    }
+    for (const pkg of exports.CLOSURE_PROVIDED_PACKAGES) {
+        if (!input.closureProvides(pkg))
+            continue;
+        const dir = `${trimSlash(input.addonRoot)}/${pkg}`;
+        if (!fs.exists(dir))
+            continue;
+        found.push({
+            kind: 'addon-root-closure-copy',
+            path: dir,
+            pkg,
+            version: fs.readVersion(dir),
+        });
+    }
+    return found;
+}
+function trimSlash(p) {
+    return p.endsWith('/') ? p.slice(0, -1) : p;
+}
+/**
+ * The kill switch. Default ON — the operator asked for convergence to one copy
+ * — but a destructive sweep that cannot be turned off from the outside is one
+ * an operator has to edit code to stop. `CAMSTACK_SINGLE_COPY_CLEANUP=off`
+ * (or `0` / `false`) leaves every copy where it is, and the boot says so.
+ */
+function isCleanupEnabled(env) {
+    const raw = env['CAMSTACK_SINGLE_COPY_CLEANUP']?.trim().toLowerCase();
+    return raw !== 'off' && raw !== '0' && raw !== 'false';
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/server",
-  "version": "1.2.101",
+  "version": "1.2.102",
   "private": false,
   "files": [
     "dist",
@@ -33,19 +33,19 @@
     ]
   },
   "dependencies": {
-    "@camstack/addon-admin-ui": "1.2.51",
-    "@camstack/addon-agent-ui": "1.2.14",
-    "@camstack/addon-auth": "1.2.15",
-    "@camstack/addon-decoder-nodeav": "1.2.13",
-    "@camstack/addon-notifiers": "1.2.18",
-    "@camstack/addon-pipeline": "1.2.70",
-    "@camstack/addon-pipeline-orchestrator": "1.2.50",
-    "@camstack/addon-post-analysis": "1.2.67",
-    "@camstack/sdk": "1.2.15",
-    "@camstack/shm-ring": "1.1.13",
-    "@camstack/system": "1.2.85",
-    "@camstack/types": "1.2.64",
-    "@camstack/ui-library": "1.2.43",
+    "@camstack/addon-admin-ui": "1.2.52",
+    "@camstack/addon-agent-ui": "1.2.15",
+    "@camstack/addon-auth": "1.2.16",
+    "@camstack/addon-decoder-nodeav": "1.2.14",
+    "@camstack/addon-notifiers": "1.2.19",
+    "@camstack/addon-pipeline": "1.2.71",
+    "@camstack/addon-pipeline-orchestrator": "1.2.51",
+    "@camstack/addon-post-analysis": "1.2.68",
+    "@camstack/sdk": "1.2.16",
+    "@camstack/shm-ring": "1.1.14",
+    "@camstack/system": "1.2.86",
+    "@camstack/types": "1.2.65",
+    "@camstack/ui-library": "1.2.44",
     "@fastify/compress": "^9.0.0",
     "@fastify/cookie": "^11.0.2",
     "@fastify/cors": "^11.2.0",