@camstack/server 1.2.100 → 1.2.102

package/dist/launcher.js

@@ -54,12 +54,13 @@ Object.defineProperty(exports, "__esModule", { value: true });
 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 tar = __importStar(require("tar"));
 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");
+const first_boot_addon_plan_js_1 = require("./first-boot-addon-plan.js");
+const framework_nodepath_js_1 = require("./framework-nodepath.js");
+const package_inventory_js_1 = require("./package-inventory.js");
 /** Path of the manifest file embedded inside every archive. */
 const ARCHIVE_MANIFEST_NAME = '.camstack-backup-manifest.json';
 /** Resolve the data directory from env or default */
@@ -206,15 +207,44 @@ function readBootstrapInstallSource(dataDir, bootstrapSchema) {
  * `launch()` on import, so nothing declared here can be imported by a spec).
  */
 function deriveBootstrapFromSelf() {
+    const pkg = readOwnManifest();
+    return pkg === null ? [] : (0, bootstrap_packages_js_1.selectHubBootstrapPackages)(pkg);
+}
+/**
+ * THIS server closure's own `package.json` — the roster's source and, when
+ * `pin-root-deps` ran for the release, the exact version of every bootstrap
+ * addon. Read by absolute path for the same reason `deriveBootstrapFromSelf`
+ * is: the slim image strips the `@camstack/*` symlinks, so `require.resolve`
+ * would answer nothing here.
+ */
+function readOwnManifest() {
     try {
         const pkgPath = path.resolve(__dirname, '..', 'package.json');
-        const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
-        return (0, bootstrap_packages_js_1.selectHubBootstrapPackages)(pkg);
+        return JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
     }
     catch (err) {
-        console.warn(`[launcher] could not derive bootstrap list from package.json: ${err instanceof Error ? err.message : String(err)}`);
-        return [];
+        console.warn(`[launcher] could not read the server manifest: ${err instanceof Error ? err.message : String(err)}`);
+        return null;
+    }
+}
+/** The version each required package currently has under the addon root. */
+function readInstalledAddonVersions(addonRoot, packages) {
+    const out = {};
+    for (const name of packages) {
+        const pkgJson = path.join(addonRoot, name, 'package.json');
+        if (!fs.existsSync(pkgJson))
+            continue;
+        try {
+            const raw = JSON.parse(fs.readFileSync(pkgJson, 'utf-8'));
+            const version = typeof raw === 'object' && raw !== null ? raw.version : undefined;
+            out[name] = typeof version === 'string' ? version : null;
+        }
+        catch {
+            // Present but unreadable is NOT absent — the plan says so in its own words.
+            out[name] = null;
+        }
     }
+    return out;
 }
 /**
  * Read `bootstrap.requiredAddons` from `<dataDir>/config.yaml` if present.
@@ -364,6 +394,44 @@ 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)`);
+    // THE FIRST-BOOT ADDON PLAN — reported every boot (D45 task 32).
+    //
+    // 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 closureNodeModules = path.resolve(__dirname, '..', 'node_modules');
+        const plan = (0, first_boot_addon_plan_js_1.planFirstBootAddons)({
+            required: bootstrapRequired,
+            installed: readInstalledAddonVersions(addonsDir, bootstrapRequired),
+            closureVersions: readInstalledAddonVersions(closureNodeModules, bootstrapRequired),
+            // Mirrors `shouldSkipClosureProvidedSeed`: only `@camstack/system`, and
+            // only while it actually resolves.
+            closureProvided: (() => {
+                try {
+                    require.resolve('@camstack/system/package.json');
+                    return ['@camstack/system'];
+                }
+                catch {
+                    return [];
+                }
+            })(),
+        });
+        for (const line of (0, first_boot_addon_plan_js_1.formatFirstBootPlan)(plan, 'observe')) {
+            console.log(`[launcher] ${line}`);
+        }
+    }
+    catch (err) {
+        console.warn(`[launcher] first-boot addon plan failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
     await installer.ensureRequiredPackages(bootstrapRequired);
     // Reconcile the install manifest against what is on disk — the directory is
     // the truth, because it is what the loader runs. Registers image-seeded
@@ -472,12 +540,21 @@ async function launch() {
     // 1.2.30), so every version the node reported was true of a copy nobody was
     // running.
     //
-    // Reported, not fatal. Every node in the fleet currently HAS extra copies —
-    // the image seeds under /opt and the legacy /data/framework — and D45 records
-    // their removal as a deliberate, scheduled migration with a container
-    // recreate as the escape hatch, not something a routine boot should enact by
-    // refusing to start. `CAMSTACK_INVENTORY_STRICT=1` makes it fatal, which is
-    // how a layout that HAS been cleaned keeps itself clean.
+    // Only the copies nobody deposits on purpose are reported. The /opt seeds
+    // are baked into the image and shadowed by the /data/server-root/current
+    // deposit on every applyServerUpdate — calling those a violation printed the
+    // banner at every boot on every node, which is how it stopped being read.
+    // They get one compact line instead; an unexpected location (the legacy
+    // /data/framework, a bootstrap install under /data/addons) and two copies
+    // that could both run still scream.
+    //
+    // NEVER fatal — operator directive, 2026-08-12: "non dovremmo mai prevenire
+    // il boot". There is no flag that turns this into a refusal. A node that
+    // cannot start is a camera system that is not recording, and the inventory is
+    // the thing that was supposed to EXPLAIN a bad layout, not enact a verdict on
+    // it. Removing a copy stays an operator decision.
+    //
+    // [inventory-diagnostics-begin] enforced by scripts/check-inventory-never-fatal.ts
     try {
         const inventory = (0, package_inventory_js_1.inventoryHostProvided)((0, package_inventory_js_1.hostProvidedSearchRoots)({
             nodePath: process.env['NODE_PATH'],
@@ -508,13 +585,12 @@ async function launch() {
                 }
             },
         });
+        for (const note of (0, package_inventory_js_1.formatShadowingNotes)(inventory)) {
+            console.log(`[launcher] ${note}`);
+        }
         const report = (0, package_inventory_js_1.formatInventoryReport)(inventory);
         if (report !== '') {
             console.error(`[launcher] ${report}`);
-            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) {
@@ -532,10 +608,9 @@ async function launch() {
     // 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.
+    // Reported, never fatal, never deleted here — same policy as D45 above, and
+    // no flag changes it. Making the second location LOUD is the whole job;
+    // removing it stays an operator decision.
     try {
         const addonRoots = (0, addon_root_inventory_js_1.inventoryAddonRoots)({
             dataDir: DATA_DIR,
@@ -579,15 +654,12 @@ async function launch() {
         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)}`);
     }
+    // [inventory-diagnostics-end]
     // 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

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");
@@ -888,7 +889,15 @@ async function bootstrap() {
                     return reply.status(404).send({ error: 'Not found' });
                 }
                 if (method === 'GET' && spaIndexHtml) {
-                    return reply.type('text/html').send(fs.createReadStream(spaIndexHtml));
+                    // An addon deep-link that is not an addon ROUTE is an admin-UI page —
+                    // serve the admin shell, under the SAME no-store policy as `/`. This
+                    // send used to carry no cache header at all, so browsers kept the
+                    // index.html of a previous build (and its dead hashed asset names)
+                    // across deploys until a force refresh.
+                    return reply
+                        .header('cache-control', (0, spa_static_1.spaShellCacheControl)())
+                        .type('text/html')
+                        .send(fs.createReadStream(spaIndexHtml));
                 }
                 return reply.status(404).send({ error: 'Not found' });
             }
@@ -1115,7 +1124,7 @@ async function bootstrap() {
             }
             return reply.callNotFound();
         }
-        reply.header('cache-control', 'no-cache, must-revalidate');
+        reply.header('cache-control', (0, spa_static_1.spaShellCacheControl)());
         return reply.type('text/html').send(fs.createReadStream(indexPath));
     });
     fastify.get('/*', async (request, reply) => {
@@ -1143,7 +1152,7 @@ async function bootstrap() {
             }
             return reply.callNotFound();
         }
-        reply.header('cache-control', 'no-cache, must-revalidate');
+        reply.header('cache-control', (0, spa_static_1.spaShellCacheControl)());
         return reply.type('text/html').send(fs.createReadStream(indexPath));
     });
     const resolveAdminUi = async () => {
@@ -1282,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/package-inventory.js

@@ -38,6 +38,7 @@ exports.hostProvidedSearchRoots = hostProvidedSearchRoots;
 exports.seedNodeModulesRoots = seedNodeModulesRoots;
 exports.inventoryHostProvided = inventoryHostProvided;
 exports.formatInventoryReport = formatInventoryReport;
+exports.formatShadowingNotes = formatShadowingNotes;
 /**
  * Boot-time inventory of host-provided packages — enforcement step 2 of
  * [D45](../../../docs/decisions/adr-0045.md).
@@ -54,6 +55,16 @@ exports.formatInventoryReport = formatInventoryReport;
  * This answers the other half — "what else is lying around that could have
  * run" — which is the question a resolved path alone cannot.
  *
+ * WHERE a copy sits decides whether it is noise or a violation. Two of the four
+ * copies above are EXPECTED: the `/opt` seed trees are baked into the image and
+ * deliberately shadowed by the `/data/server-root/current` deposit on every
+ * `applyServerUpdate`. Counting them as a violation printed the banner at every
+ * boot on every node, which taught the operator to scroll past the one boot
+ * where it mattered — the exact failure D45 exists to prevent. So the detector
+ * classifies locations and screams only for a copy nobody deposits on purpose,
+ * or for two copies that could BOTH be the one that runs. The expected
+ * shadowing gets one compact line instead.
+ *
  * Everything here is pure: the caller injects the three filesystem operations,
  * so the whole inventory is testable against a described layout rather than a
  * real disk.
@@ -78,24 +89,39 @@ exports.HOST_PROVIDED_PACKAGES = [
  * to a handful of stat calls at boot. `/data/addons` is a root in its own right
  * because the bootstrap-install layout puts the package DIRECTLY there
  * (`/data/addons/@camstack/system`), not under a `node_modules`.
+ *
+ * A `NODE_PATH` entry is classified by WHICH directory it names, not by being
+ * on `NODE_PATH`: the launcher puts the deposit and the seeds there itself, so
+ * "it is on NODE_PATH" would mark the whole fleet unexpected.
  */
 function hostProvidedSearchRoots(input) {
     const fromNodePath = (input.nodePath ?? '')
         .split(input.pathSeparator)
         .map((p) => p.trim())
         .filter((p) => p.length > 0);
+    const seedPaths = new Set(input.seedRoots);
+    const expectationFor = (dir) => {
+        if (dir === input.serverNodeModules)
+            return 'active';
+        if (seedPaths.has(dir))
+            return 'seed';
+        return 'unexpected';
+    };
     const roots = [
-        input.serverNodeModules,
-        ...fromNodePath,
-        path.join(input.dataDir, 'framework', 'node_modules'),
-        path.join(input.dataDir, 'addons'),
-        ...input.seedRoots,
+        { path: input.serverNodeModules, expectation: 'active' },
+        ...fromNodePath.map((p) => ({ path: p, expectation: expectationFor(p) })),
+        { path: path.join(input.dataDir, 'framework', 'node_modules'), expectation: 'unexpected' },
+        { path: path.join(input.dataDir, 'addons'), expectation: 'unexpected' },
+        ...input.seedRoots.map((p) => ({ path: p, expectation: expectationFor(p) })),
     ];
+    // First occurrence wins, and the deposit is listed first — so a directory
+    // that is both the closure and a seed keeps the classification that decides
+    // whether it runs.
     const seen = new Set();
     return roots.filter((r) => {
-        if (seen.has(r))
+        if (seen.has(r.path))
             return false;
-        seen.add(r);
+        seen.add(r.path);
         return true;
     });
 }
@@ -136,45 +162,106 @@ function inventoryHostProvided(roots, fs, packages = exports.HOST_PROVIDED_PACKA
         // them two would cry wolf on a node that is actually compliant.
         const seenReal = new Set();
         for (const root of roots) {
-            const dir = path.join(root, pkg);
+            const dir = path.join(root.path, pkg);
             if (!fs.exists(dir))
                 continue;
             const real = fs.realPath(dir);
             if (seenReal.has(real))
                 continue;
             seenReal.add(real);
-            copies.push({ pkg, path: dir, version: fs.readVersion(dir) });
+            copies.push({ pkg, path: dir, version: fs.readVersion(dir), location: root.expectation });
         }
     }
-    const countByPkg = new Map();
+    const byPkg = new Map();
     for (const c of copies)
-        countByPkg.set(c.pkg, (countByPkg.get(c.pkg) ?? 0) + 1);
-    const duplicated = [...countByPkg.entries()]
-        .filter(([, n]) => n > 1)
-        .map(([pkg]) => pkg)
-        .sort();
-    return { copies, duplicated, rootsScanned: roots };
+        byPkg.set(c.pkg, [...(byPkg.get(c.pkg) ?? []), c]);
+    const inventories = [...byPkg.entries()]
+        .map(([pkg, found]) => classifyPackage(pkg, found))
+        .sort((a, b) => a.pkg.localeCompare(b.pkg));
+    return {
+        copies,
+        packages: inventories,
+        violations: inventories.filter((p) => p.violation).map((p) => p.pkg),
+        rootsScanned: roots.map((r) => r.path),
+    };
+}
+/**
+ * Sort one package's copies into what each one means.
+ *
+ * A deposit copy shadows every seed — that is what `applyServerUpdate` does on
+ * every release, so those seeds are not candidates for anything. With no
+ * deposit copy the seeds ARE the candidates, and two of them is the resolution
+ * race D45 was written about.
+ */
+function classifyPackage(pkg, found) {
+    const active = found.filter((c) => c.location === 'active');
+    const seeds = found.filter((c) => c.location === 'seed');
+    const unexpected = found.filter((c) => c.location === 'unexpected');
+    const activeCandidates = active.length > 0 ? active : seeds;
+    const shadowedSeeds = active.length > 0 ? seeds : [];
+    return {
+        pkg,
+        copies: found,
+        activeCandidates,
+        shadowedSeeds,
+        unexpected,
+        violation: unexpected.length > 0 || activeCandidates.length > 1,
+    };
 }
 /**
- * The loud report. Empty string when the node is clean — a compliant boot says
- * nothing, so the one that isn't stands out instead of scrolling past.
+ * The loud report. Empty string unless a copy is somewhere nobody deposits on
+ * purpose, or two copies could both be the one that runs — an expected seed
+ * under the deposit is the fleet's normal shape and reports nothing here, or
+ * the banner would print on every boot of every node and be read on none.
  */
 function formatInventoryReport(result) {
-    if (result.duplicated.length === 0)
+    const violating = result.packages.filter((p) => p.violation);
+    if (violating.length === 0)
         return '';
     const lines = [
-        'D45 violation — a host-provided package exists more than once on this node.',
-        'Which copy runs is a module-resolution outcome, and every version this node',
-        'reports is a claim about one of them rather than about the node.',
+        'D45 violation — a host-provided package sits somewhere it must not, or two',
+        'copies could both be the one that runs. Which copy runs is then a',
+        'module-resolution outcome, and every version this node reports is a claim',
+        'about one of them rather than about the node.',
         '',
     ];
-    for (const pkg of result.duplicated) {
-        const found = result.copies.filter((c) => c.pkg === pkg);
-        lines.push(`  ${pkg} — ${found.length} copies:`);
-        for (const c of found) {
-            lines.push(`    ${c.version ?? '<unreadable package.json>'}  ${c.path}`);
+    for (const inv of violating) {
+        lines.push(`  ${inv.pkg} — ${inv.copies.length} copies:`);
+        for (const c of inv.copies) {
+            lines.push(`    ${c.version ?? '<unreadable package.json>'}  [${describeLocation(c, inv)}]  ${c.path}`);
         }
     }
     lines.push('', `  roots scanned: ${result.rootsScanned.join(', ')}`);
     return lines.join('\n');
 }
+/** Why this one copy is (or is not) part of the problem, in one word or two. */
+function describeLocation(copy, inv) {
+    if (copy.location === 'unexpected')
+        return 'UNEXPECTED — remove it';
+    if (inv.activeCandidates.includes(copy)) {
+        return inv.activeCandidates.length > 1 ? 'CONFLICTS — could run' : 'active';
+    }
+    return 'image seed, shadowed';
+}
+/**
+ * The quiet half: the expected seed shadowing, one compact line per package.
+ *
+ * Deliberately not a banner and deliberately not phrased as a fault — the image
+ * bakes these trees and the deposit shadows them on every release. A package
+ * already named in {@link formatInventoryReport} is skipped: the banner lists
+ * all of its copies, and a reassuring line beside it would read as verification.
+ */
+function formatShadowingNotes(result) {
+    return result.packages
+        .filter((p) => !p.violation && p.shadowedSeeds.length > 0)
+        .map((p) => {
+        const seedVersions = [...new Set(p.shadowedSeeds.map(describeVersion))].join(', ');
+        const active = p.activeCandidates[0];
+        const activeVersion = active === undefined ? 'unknown' : describeVersion(active);
+        const activePath = active === undefined ? '' : ` (${active.path})`;
+        return `${p.pkg} — seed ${seedVersions} shadowed by active ${activeVersion}${activePath}`;
+    });
+}
+function describeVersion(copy) {
+    return copy.version ?? '<unreadable package.json>';
+}

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