@camstack/agent 1.1.57 → 1.1.59

package/dist/index.js

@@ -64,31 +64,41 @@ var require_dist = __commonJS({
     var src_exports2 = {};
     __export2(src_exports2, {
       AGENT_ROOT_SPEC: () => AGENT_ROOT_SPEC2,
+      CURRENT_DIRNAME: () => CURRENT_DIRNAME,
       DEV_UPLOADS_DIRNAME: () => DEV_UPLOADS_DIRNAME,
       DEV_UPLOADS_KEEP_COUNT: () => DEV_UPLOADS_KEEP_COUNT,
       DEV_UPLOAD_MANIFEST_FILE: () => DEV_UPLOAD_MANIFEST_FILE,
       HOST_EXTERNAL_SPECIFIERS: () => HOST_EXTERNAL_SPECIFIERS,
       HUB_ROOT_SPEC: () => HUB_ROOT_SPEC,
+      PENDING_ROOT_SWAP_FILE: () => PENDING_ROOT_SWAP_FILE,
+      REQUIRED_NATIVE_PACKAGES: () => REQUIRED_NATIVE_PACKAGES,
       RESTART_INTENT_FILE: () => RESTART_INTENT_FILE,
       RootUpdateService: () => RootUpdateService2,
       SERVER_ROOT_DIRNAME: () => SERVER_ROOT_DIRNAME,
       SERVER_ROOT_STATE_FILE: () => SERVER_ROOT_STATE_FILE,
+      applyPendingRootSwap: () => applyPendingRootSwap,
+      clearPendingRootSwap: () => clearPendingRootSwap,
       clearRestartIntentMarker: () => clearRestartIntentMarker,
       compareSemver: () => compareSemver,
+      currentDir: () => currentDir,
+      currentEntryPath: () => currentEntryPath,
       detectWorkspaceRoot: () => detectWorkspaceRoot,
       devChannelEpoch: () => devChannelEpoch,
       devUploadManifestPath: () => devUploadManifestPath,
       devUploadVersionDir: () => devUploadVersionDir,
       devUploadsDir: () => devUploadsDir,
       emptyServerRootState: () => emptyServerRootState,
+      findMissingNativePrebuilds: () => findMissingNativePrebuilds,
       isDevChannelVersion: () => isDevChannelVersion,
       isHostExternal: () => isHostExternal,
       isServerRootState: () => isServerRootState,
+      migrateToSingleCopy: () => migrateToSingleCopy,
       minNodeMajorOf: () => minNodeMajorOf,
+      pendingRootSwapPath: () => pendingRootSwapPath,
       planBoot: () => planBoot,
       readDevUploadManifest: () => readDevUploadManifest,
+      readPendingRootSwap: () => readPendingRootSwap,
       readRestartIntentMarker: () => readRestartIntentMarker,
-      readSeedVersion: () => readSeedVersion,
       readServerRootState: () => readServerRootState,
       registerActiveRootResolver: () => registerActiveRootResolver,
       restartIntentMarkerPath: () => restartIntentMarkerPath,
@@ -96,11 +106,15 @@ var require_dist = __commonJS({
       rootPackageDir: () => rootPackageDir,
       runNodeStarter: () => runNodeStarter,
       serverRootDir: () => serverRootDir2,
+      stagingDirPath: () => stagingDirPath,
       stateFilePath: () => stateFilePath,
+      sweepTransientRootDirs: () => sweepTransientRootDirs,
+      validateClosureDir: () => validateClosureDir,
       validateVersionDir: () => validateVersionDir,
       versionDir: () => versionDir,
       versionsDir: () => versionsDir,
       writeDevUploadManifest: () => writeDevUploadManifest,
+      writePendingRootSwap: () => writePendingRootSwap,
       writeRestartIntentMarker: () => writeRestartIntentMarker2,
       writeServerRootState: () => writeServerRootState
     });
@@ -265,13 +279,12 @@ var require_dist = __commonJS({
       const major = Number.parseInt(match[1] ?? "", 10);
       return Number.isNaN(major) ? null : major;
     }
-    function validateVersionDir(rootDir, version, nodeMajor, spec) {
-      const vDir = versionDir(rootDir, version);
-      const entry = rootEntryPath(vDir, spec);
+    function validateClosureDir(closureDir, nodeMajor, spec, expectedVersion) {
+      const entry = rootEntryPath(closureDir, spec);
       if (!fs22.existsSync(entry)) {
         return `root entry missing: ${entry}`;
       }
-      const pkgJsonPath = path22.join(rootPackageDir(vDir, spec), "package.json");
+      const pkgJsonPath = path22.join(rootPackageDir(closureDir, spec), "package.json");
       let pkg;
       try {
         const raw = JSON.parse(fs22.readFileSync(pkgJsonPath, "utf-8"));
@@ -285,8 +298,8 @@ var require_dist = __commonJS({
       if (pkg["name"] !== spec.packageName) {
         return `package name mismatch: expected ${spec.packageName}, got ${String(pkg["name"])}`;
       }
-      if (pkg["version"] !== version) {
-        return `package version mismatch: dir says ${version}, package.json says ${String(pkg["version"])}`;
+      if (expectedVersion !== void 0 && pkg["version"] !== expectedVersion) {
+        return `package version mismatch: expected ${expectedVersion}, package.json says ${String(pkg["version"])}`;
       }
       const engines = pkg["engines"];
       if (typeof engines === "object" && engines !== null) {
@@ -300,6 +313,11 @@ var require_dist = __commonJS({
       }
       return null;
     }
+    function validateVersionDir(rootDir, version, nodeMajor, spec) {
+      return validateClosureDir(versionDir(rootDir, version), nodeMajor, spec, version);
+    }
+    var fs32 = __toESM2(require("fs"));
+    var path32 = __toESM2(require("path"));
     function parse(version) {
       const dashIdx = version.indexOf("-");
       const base = dashIdx === -1 ? version : version.slice(0, dashIdx);
@@ -327,133 +345,268 @@ var require_dist = __commonJS({
       if (pa.prerelease > pb.prerelease) return 1;
       return 0;
     }
-    function planBoot(state, isValidVersion, now, seedVersion = null) {
-      if (state === null) {
-        return { kind: "baked", reason: "no server-root state", stateToWrite: null };
-      }
-      let next = state;
-      let changed = false;
-      if (next.pendingBoot !== null) {
-        const pending = next.pendingBoot;
-        if (pending.bootAttempts >= 1) {
-          next = {
-            ...next,
-            pendingBoot: null,
-            rolledBack: {
-              fromVersion: pending.version,
-              toVersion: next.currentVersion,
-              atMs: now(),
-              reason: "probation boot did not reach ready \u2014 rolled back"
-            }
-          };
-          changed = true;
-        } else if (!isValidVersion(pending.version)) {
-          next = {
-            ...next,
-            pendingBoot: null,
-            rolledBack: {
-              fromVersion: pending.version,
-              toVersion: next.currentVersion,
-              atMs: now(),
-              reason: "staged version failed validation"
-            }
-          };
-          changed = true;
-        } else {
-          return {
-            kind: "data-root",
-            version: pending.version,
-            probation: true,
-            stateToWrite: {
-              ...next,
-              pendingBoot: { ...pending, bootAttempts: pending.bootAttempts + 1 }
-            }
-          };
-        }
+    var CURRENT_DIRNAME = "current";
+    var PENDING_ROOT_SWAP_FILE = ".pending-root-swap.json";
+    var LEGACY_FRAMEWORK_MARKERS = [
+      ".pending-framework-swap.json",
+      ".framework-swap-confirm.json"
+    ];
+    function currentDir(rootDir) {
+      return path32.join(rootDir, CURRENT_DIRNAME);
+    }
+    function currentEntryPath(rootDir, spec) {
+      return rootEntryPath(currentDir(rootDir), spec);
+    }
+    function stagingDirPath(rootDir, target, pid, now) {
+      return path32.join(rootDir, `.staging-${target}-${pid}-${now}`);
+    }
+    function pendingRootSwapPath(rootDir) {
+      return path32.join(rootDir, PENDING_ROOT_SWAP_FILE);
+    }
+    function isPendingRootSwap(v) {
+      if (typeof v !== "object" || v === null) return false;
+      const m = v;
+      return m["schemaVersion"] === 1 && typeof m["version"] === "string" && typeof m["stagingPath"] === "string" && typeof m["requestedAtMs"] === "number";
+    }
+    function readPendingRootSwap(rootDir) {
+      try {
+        const raw = JSON.parse(fs32.readFileSync(pendingRootSwapPath(rootDir), "utf-8"));
+        return isPendingRootSwap(raw) ? raw : null;
+      } catch {
+        return null;
       }
-      if (next.currentVersion !== null) {
-        if (isValidVersion(next.currentVersion)) {
-          if (!changed && seedVersion !== null && compareSemver(seedVersion, next.currentVersion) > 0) {
-            return {
-              kind: "baked",
-              reason: `baked seed ${seedVersion} is newer than active data-root ${next.currentVersion} \u2014 adopting the image seed`,
-              stateToWrite: {
-                ...next,
-                currentVersion: null,
-                previousVersion: null,
-                pendingBoot: null,
-                rolledBack: null
-              }
-            };
-          }
-          return {
-            kind: "data-root",
-            version: next.currentVersion,
-            probation: false,
-            stateToWrite: changed ? next : null
-          };
-        }
-        const broken = next.currentVersion;
-        if (next.previousVersion !== null && isValidVersion(next.previousVersion)) {
-          const fallback = next.previousVersion;
-          return {
-            kind: "data-root",
-            version: fallback,
-            probation: false,
-            stateToWrite: {
-              ...next,
-              currentVersion: fallback,
-              previousVersion: null,
-              rolledBack: {
-                fromVersion: broken,
-                toVersion: fallback,
-                atMs: now(),
-                reason: "active version failed validation"
-              }
-            }
-          };
+    }
+    function writePendingRootSwap(rootDir, marker) {
+      fs32.mkdirSync(rootDir, { recursive: true });
+      const target = pendingRootSwapPath(rootDir);
+      const tmp = `${target}.tmp`;
+      fs32.writeFileSync(tmp, JSON.stringify(marker, null, 2), "utf-8");
+      fs32.renameSync(tmp, target);
+    }
+    function clearPendingRootSwap(rootDir) {
+      try {
+        fs32.rmSync(pendingRootSwapPath(rootDir), { force: true });
+      } catch {
+      }
+    }
+    var REQUIRED_NATIVE_PACKAGES = ["better-sqlite3", "sharp", "node-av"];
+    var NATIVE_SEARCH_DIRS = {
+      "better-sqlite3": ["better-sqlite3"],
+      sharp: ["sharp", "@img"],
+      "node-av": ["node-av", "@seydx"]
+    };
+    function hasDotNode(dir, maxDepth) {
+      let entries;
+      try {
+        entries = fs32.readdirSync(dir, { withFileTypes: true });
+      } catch {
+        return false;
+      }
+      for (const entry of entries) {
+        if (entry.isFile() && entry.name.endsWith(".node")) return true;
+      }
+      if (maxDepth <= 0) return false;
+      for (const entry of entries) {
+        if (entry.isDirectory() && hasDotNode(path32.join(dir, entry.name), maxDepth - 1)) return true;
+      }
+      return false;
+    }
+    function findMissingNativePrebuilds(closureDir) {
+      const nm = path32.join(closureDir, "node_modules");
+      const missing = [];
+      for (const pkg of REQUIRED_NATIVE_PACKAGES) {
+        const searchDirs = NATIVE_SEARCH_DIRS[pkg] ?? [pkg];
+        const found = searchDirs.some((rel) => hasDotNode(path32.join(nm, ...rel.split("/")), 4));
+        if (!found) missing.push(pkg);
+      }
+      return missing;
+    }
+    function rmrf2(target) {
+      try {
+        fs32.rmSync(target, { recursive: true, force: true });
+      } catch {
+      }
+    }
+    function errMsg2(err) {
+      return err instanceof Error ? err.message : String(err);
+    }
+    function applyPendingRootSwap(rootDir, spec, nodeMajor, now, log) {
+      const marker = readPendingRootSwap(rootDir);
+      if (marker === null) return { applied: false, version: null, reason: "no pending swap" };
+      const staging = marker.stagingPath;
+      const dest = currentDir(rootDir);
+      const invalid = validateClosureDir(staging, nodeMajor, spec, marker.version);
+      if (invalid !== null) {
+        if (!fs32.existsSync(staging) && validateClosureDir(dest, nodeMajor, spec, marker.version) === null) {
+          clearPendingRootSwap(rootDir);
+          log(`[single-copy] pending swap ${marker.version} already applied \u2014 cleared marker`);
+          return { applied: true, version: marker.version, reason: "already applied" };
         }
+        log(`[single-copy] staged swap ${marker.version} invalid \u2014 discarding (${invalid})`);
+        rmrf2(staging);
+        clearPendingRootSwap(rootDir);
+        return { applied: false, version: null, reason: invalid };
+      }
+      const missing = findMissingNativePrebuilds(staging);
+      if (missing.length > 0) {
+        log(
+          `[single-copy] staged swap ${marker.version} missing native prebuilds: ${missing.join(", ")} \u2014 discarding`
+        );
+        rmrf2(staging);
+        clearPendingRootSwap(rootDir);
         return {
-          kind: "baked",
-          reason: `active version ${broken} failed validation and no valid previous version exists`,
-          stateToWrite: {
-            ...next,
-            currentVersion: null,
-            rolledBack: {
-              fromVersion: broken,
-              toVersion: null,
-              atMs: now(),
-              reason: "active version failed validation"
+          applied: false,
+          version: null,
+          reason: `missing native prebuilds: ${missing.join(", ")}`
+        };
+      }
+      let trash = null;
+      try {
+        if (fs32.existsSync(dest)) {
+          trash = path32.join(rootDir, `.trash-${now()}-${process.pid}`);
+          fs32.renameSync(dest, trash);
+        }
+        try {
+          fs32.renameSync(staging, dest);
+        } catch (err) {
+          if (trash !== null && !fs32.existsSync(dest)) {
+            try {
+              fs32.renameSync(trash, dest);
+            } catch {
             }
           }
-        };
+          throw err;
+        }
+      } catch (err) {
+        log(`[single-copy] swap of ${marker.version} FAILED \u2014 current preserved (${errMsg2(err)})`);
+        return { applied: false, version: null, reason: errMsg2(err) };
       }
-      return {
-        kind: "baked",
-        reason: "no active data-root version",
-        stateToWrite: changed ? next : null
-      };
+      if (trash !== null) rmrf2(trash);
+      clearPendingRootSwap(rootDir);
+      log(`[single-copy] applied staged root swap \u2192 ${marker.version}`);
+      return { applied: true, version: marker.version, reason: "applied" };
     }
-    var fs32 = __toESM2(require("fs"));
-    var path32 = __toESM2(require("path"));
+    function readClosureVersion(closureDir, spec) {
+      try {
+        const raw = JSON.parse(
+          fs32.readFileSync(path32.join(rootPackageDir(closureDir, spec), "package.json"), "utf-8")
+        );
+        if (typeof raw === "object" && raw !== null) {
+          const version = raw["version"];
+          if (typeof version === "string") return version;
+        }
+      } catch {
+      }
+      return null;
+    }
+    function isAdoptablePendingClosure(rootDir, version, nodeMajor, spec) {
+      const dir = versionDir(rootDir, version);
+      return validateClosureDir(dir, nodeMajor, spec, version) === null && findMissingNativePrebuilds(dir).length === 0;
+    }
+    function migrateToSingleCopy(rootDir, spec, nodeMajor, now, log) {
+      const dest = currentDir(rootDir);
+      const legacyState = readServerRootState(rootDir);
+      const pendingVersion = legacyState?.pendingBoot?.version ?? null;
+      const pendingAdoptable = pendingVersion !== null && isAdoptablePendingClosure(rootDir, pendingVersion, nodeMajor, spec);
+      const currentValid = fs32.existsSync(dest) && validateClosureDir(dest, nodeMajor, spec) === null;
+      if (currentValid) {
+        const currentVersion = readClosureVersion(dest, spec);
+        const pendingSupersedes = pendingAdoptable && pendingVersion !== null && (currentVersion === null || compareSemver(pendingVersion, currentVersion) > 0);
+        if (!pendingSupersedes) {
+          return { migrated: false, version: null, reason: "current already present" };
+        }
+        log(
+          `[single-copy] in-flight pending ${pendingVersion} supersedes older current ${currentVersion ?? "?"}`
+        );
+      }
+      const candidates = [];
+      if (pendingAdoptable && pendingVersion !== null) candidates.push(pendingVersion);
+      if (legacyState !== null) {
+        for (const v of [
+          legacyState.currentVersion,
+          legacyState.pendingBoot?.version ?? null,
+          legacyState.previousVersion
+        ]) {
+          if (typeof v === "string" && !candidates.includes(v)) candidates.push(v);
+        }
+      }
+      try {
+        for (const entry of fs32.readdirSync(versionsDir(rootDir))) {
+          if (!entry.startsWith(".") && !candidates.includes(entry)) candidates.push(entry);
+        }
+      } catch {
+      }
+      const source = candidates.find(
+        (v) => validateClosureDir(versionDir(rootDir, v), nodeMajor, spec, v) === null
+      );
+      if (source === void 0) {
+        return { migrated: false, version: null, reason: "no valid legacy versions/<X> to adopt" };
+      }
+      if (fs32.existsSync(dest)) {
+        const aside = path32.join(rootDir, `.trash-${now()}-${process.pid}-stale-current`);
+        try {
+          fs32.renameSync(dest, aside);
+        } catch {
+          rmrf2(dest);
+        }
+      }
+      try {
+        fs32.renameSync(versionDir(rootDir, source), dest);
+      } catch (err) {
+        log(`[single-copy] migration rename of versions/${source} failed (${errMsg2(err)})`);
+        return { migrated: false, version: null, reason: errMsg2(err) };
+      }
+      rmrf2(versionsDir(rootDir));
+      rmrf2(stateFilePath(rootDir));
+      const dataDir = path32.dirname(rootDir);
+      for (const marker of LEGACY_FRAMEWORK_MARKERS) rmrf2(path32.join(dataDir, marker));
+      log(`[single-copy] migrated legacy versions/${source} \u2192 current`);
+      return { migrated: true, version: source, reason: "adopted legacy version" };
+    }
+    function sweepTransientRootDirs(rootDir, now, staleMs) {
+      let entries;
+      try {
+        entries = fs32.readdirSync(rootDir);
+      } catch {
+        return;
+      }
+      for (const entry of entries) {
+        if (!entry.startsWith(".staging-") && !entry.startsWith(".trash-")) continue;
+        const full = path32.join(rootDir, entry);
+        try {
+          if (now - fs32.statSync(full).mtimeMs < staleMs) continue;
+        } catch {
+          continue;
+        }
+        rmrf2(full);
+      }
+    }
+    function planBoot(currentValid) {
+      if (currentValid) {
+        return { kind: "current", reason: "single-copy closure present and valid" };
+      }
+      return { kind: "baked", reason: "no valid single-copy closure \u2014 booting the baked seed" };
+    }
+    var fs42 = __toESM2(require("fs"));
+    var path42 = __toESM2(require("path"));
     function detectWorkspaceRoot(fromDir) {
-      let dir = path32.resolve(fromDir);
+      let dir = path42.resolve(fromDir);
       for (; ; ) {
-        const pkgPath = path32.join(dir, "package.json");
+        const pkgPath = path42.join(dir, "package.json");
         try {
-          const raw = JSON.parse(fs32.readFileSync(pkgPath, "utf-8"));
+          const raw = JSON.parse(fs42.readFileSync(pkgPath, "utf-8"));
           if (typeof raw === "object" && raw !== null && raw["workspaces"] !== void 0) {
             return dir;
           }
         } catch {
         }
-        const parent = path32.dirname(dir);
+        const parent = path42.dirname(dir);
         if (parent === dir) return null;
         dir = parent;
       }
     }
-    var fs42 = __toESM2(require("fs"));
-    var path42 = __toESM2(require("path"));
+    var fs52 = __toESM2(require("fs"));
+    var path52 = __toESM2(require("path"));
     var import_node_url = require("url");
     var HOST_EXTERNAL_SPECIFIERS = [
       "@camstack/system",
@@ -481,7 +634,7 @@ var require_dist = __commonJS({
         return;
       }
       const anchorURL = (0, import_node_url.pathToFileURL)(
-        path42.join(activeRootDir, "node_modules", "__camstack_starter_anchor__.js")
+        path52.join(activeRootDir, "node_modules", "__camstack_starter_anchor__.js")
       ).href;
       const hooks = {
         resolve: (specifier, context, nextResolve) => {
@@ -496,23 +649,24 @@ var require_dist = __commonJS({
       };
       registerHooks(hooks);
     }
-    function readSeedVersion(seedEntry) {
+    function readClosureVersion2(closureDir, spec) {
       try {
-        const pkgJsonPath = path42.join(path42.dirname(seedEntry), "..", "package.json");
-        const raw = JSON.parse(fs42.readFileSync(pkgJsonPath, "utf-8"));
+        const raw = JSON.parse(
+          fs52.readFileSync(path52.join(rootPackageDir(closureDir, spec), "package.json"), "utf-8")
+        );
         if (typeof raw === "object" && raw !== null) {
           const version = raw["version"];
           if (typeof version === "string") return version;
         }
-        return null;
       } catch {
-        return null;
       }
+      return null;
     }
     function runNodeStarter(options) {
       const env = options.env ?? process.env;
       const now = options.now ?? Date.now;
       const registerResolver = options.registerResolver ?? registerActiveRootResolver;
+      const nodeMajor = options.nodeMajor ?? Number.parseInt(process.versions.node.split(".")[0] ?? "0", 10);
       const disabled = env[options.envNames.killSwitch] === "off";
       const workspaceRoot = detectWorkspaceRoot(options.starterDir);
       if (workspaceRoot !== null) {
@@ -530,40 +684,34 @@ var require_dist = __commonJS({
         return;
       }
       const rootDir = serverRootDir2(options.dataDir);
-      const state = readServerRootState(rootDir);
-      const nodeMajor = options.nodeMajor ?? Number.parseInt(process.versions.node.split(".")[0] ?? "0", 10);
-      const isValidVersion = (version) => {
-        const reason = validateVersionDir(rootDir, version, nodeMajor, options.spec);
-        if (reason !== null) console.warn(`[starter] version ${version} invalid: ${reason}`);
-        return reason === null;
-      };
-      const seedVersion = readSeedVersion(options.seedEntry);
-      const plan = planBoot(state, isValidVersion, now, seedVersion);
-      if (plan.stateToWrite !== null) {
-        try {
-          writeServerRootState(rootDir, plan.stateToWrite);
-        } catch (err) {
-          console.error("[starter] FAILED to persist server-root state \u2014 booting baked seed:", err);
-          env[options.envNames.bootMode] = "baked";
-          options.loadEntry(options.seedEntry);
-          return;
-        }
-        if (plan.stateToWrite.rolledBack !== null && (state?.rolledBack ?? null) !== plan.stateToWrite.rolledBack) {
-          const rb = plan.stateToWrite.rolledBack;
-          console.warn(
-            `[starter] ROLLED BACK ${rb.fromVersion} -> ${rb.toVersion ?? "baked seed"}: ${rb.reason}`
-          );
-        }
-      }
-      if (plan.kind === "data-root") {
-        const activeRootDir = versionDir(rootDir, plan.version);
-        const entry = rootEntryPath(activeRootDir, options.spec);
+      const swap = applyPendingRootSwap(rootDir, options.spec, nodeMajor, now, (m) => console.log(m));
+      if (swap.applied) console.log(`[starter] applied staged update \u2192 ${swap.version ?? "?"}`);
+      else if (swap.reason !== "no pending swap")
+        console.warn(`[starter] staged update NOT applied: ${swap.reason}`);
+      const migration = migrateToSingleCopy(
+        rootDir,
+        options.spec,
+        nodeMajor,
+        now,
+        (m) => console.log(m)
+      );
+      if (migration.migrated)
+        console.log(`[starter] migrated legacy layout \u2192 single copy (${migration.version ?? "?"})`);
+      const activeRootDir = currentDir(rootDir);
+      const invalid = validateClosureDir(activeRootDir, nodeMajor, options.spec);
+      if (invalid !== null && fs52.existsSync(activeRootDir)) {
+        console.warn(`[starter] single copy invalid: ${invalid}`);
+      }
+      const plan = planBoot(invalid === null);
+      if (plan.kind === "current") {
+        const version = readClosureVersion2(activeRootDir, options.spec);
+        const entry = currentEntryPath(rootDir, options.spec);
         console.log(
-          `[starter] booting ${options.spec.packageName}@${plan.version} from ${activeRootDir}` + (plan.probation ? " (probation boot \u2014 health-check armed)" : "")
+          `[starter] booting ${options.spec.packageName}@${version ?? "?"} from ${activeRootDir}`
         );
         env[options.envNames.bootMode] = "data-root";
         env[options.envNames.activeRoot] = activeRootDir;
-        env[options.envNames.activeVersion] = plan.version;
+        if (version !== null) env[options.envNames.activeVersion] = version;
         registerResolver(activeRootDir);
         options.loadEntry(entry);
         return;
@@ -573,8 +721,8 @@ var require_dist = __commonJS({
       options.loadEntry(options.seedEntry);
     }
     var import_node_child_process = require("child_process");
-    var fs52 = __toESM2(require("fs"));
-    var path52 = __toESM2(require("path"));
+    var fs62 = __toESM2(require("fs"));
+    var path62 = __toESM2(require("path"));
     var import_node_util = require("util");
     var execFileAsync = (0, import_node_util.promisify)(import_node_child_process.execFile);
     function buildNpmRegistryArgs(registry) {
@@ -584,9 +732,10 @@ var require_dist = __commonJS({
     var NPM_VIEW_TIMEOUT_MS = 2e4;
     var NPM_INSTALL_TIMEOUT_MS = 15 * 6e4;
     var RESTART_REASON_PREFIX = "server-update";
+    var STALE_TRANSIENT_MS = 24 * 60 * 60 * 1e3;
     function readPackageVersion(pkgJsonPath) {
       try {
-        const raw = JSON.parse(fs52.readFileSync(pkgJsonPath, "utf-8"));
+        const raw = JSON.parse(fs62.readFileSync(pkgJsonPath, "utf-8"));
         if (typeof raw === "object" && raw !== null) {
           const version = raw["version"];
           if (typeof version === "string") return version;
@@ -595,7 +744,7 @@ var require_dist = __commonJS({
       }
       return null;
     }
-    var RootUpdateService2 = class _RootUpdateService {
+    var RootUpdateService2 = class {
       spec;
       envNames;
       logger;
@@ -613,7 +762,7 @@ var require_dist = __commonJS({
         this.envNames = options.envNames;
         this.logger = options.logger;
         this.restartServerFn = options.restartServer;
-        this.dataDir = path52.resolve(options.dataDir);
+        this.dataDir = path62.resolve(options.dataDir);
         this.execNpm = options.execNpm ?? (async (args, opts) => {
           const { stdout } = await execFileAsync("npm", [...args], {
             cwd: opts.cwd,
@@ -642,57 +791,37 @@ var require_dist = __commonJS({
       seedVersion() {
         const seedDir = this.env[this.envNames.seedDir];
         if (seedDir === void 0 || seedDir.length === 0) return null;
-        return readPackageVersion(path52.join(seedDir, "package.json"));
+        return readPackageVersion(path62.join(seedDir, "package.json"));
       }
       rootDir() {
         return serverRootDir2(this.dataDir);
       }
-      readState() {
-        return readServerRootState(this.rootDir()) ?? emptyServerRootState();
-      }
-      /**
-       * Like `readState`, but distinguishes "state.json missing" (normal on a
-       * fresh node) from "state.json present but corrupt" — in the corrupt case
-       * the starter booted the baked seed while installed data-dir versions are
-       * silently ignored, which the status surface must make visible.
-       */
-      readStateInfo() {
-        const rootDir = this.rootDir();
-        const raw = readServerRootState(rootDir);
-        if (raw !== null) return { state: raw, corrupt: false };
-        return { state: emptyServerRootState(), corrupt: fs52.existsSync(stateFilePath(rootDir)) };
-      }
-      updateState(state) {
+      updateState() {
         if (this.inFlight === "checking") return "checking";
         if (this.inFlight === "staging") return "staging";
-        if (state.pendingBoot !== null) {
-          const activeVersion = this.env[this.envNames.activeVersion] ?? null;
-          if (activeVersion !== null && activeVersion === state.pendingBoot.version) {
-            return "awaiting-confirmation";
-          }
-          return "pending-restart";
-        }
+        if (readPendingRootSwap(this.rootDir()) !== null) return "pending-restart";
         return "idle";
       }
       async getServerPackageStatus() {
-        const { state, corrupt } = this.readStateInfo();
         const runningVersion = this.runningVersion();
         const latestVersion = this.checkCache?.latestVersion ?? null;
+        const pending = readPendingRootSwap(this.rootDir());
         const updateAvailable = latestVersion !== null && runningVersion !== null && compareSemver(latestVersion, runningVersion) > 0;
         return {
           packageName: this.spec.packageName,
           runningVersion,
           nodeRuntimeVersion: process.versions.node,
-          activeVersion: this.env[this.envNames.activeVersion] ?? state.currentVersion,
-          previousVersion: state.previousVersion,
+          activeVersion: this.env[this.envNames.activeVersion] ?? runningVersion,
+          // Single-copy model: no N-1 retention, no rollback record.
+          previousVersion: null,
           seedVersion: this.seedVersion(),
           latestVersion,
           updateAvailable,
           bootMode: this.resolveBootMode(),
-          updateState: this.updateState(state),
-          pendingVersion: state.pendingBoot?.version ?? null,
-          rolledBack: state.rolledBack,
-          stateFileCorrupt: corrupt,
+          updateState: this.updateState(),
+          pendingVersion: pending?.version ?? null,
+          rolledBack: null,
+          stateFileCorrupt: false,
           lastCheckedAtMs: this.checkCache?.checkedAtMs ?? null
         };
       }
@@ -769,13 +898,13 @@ var require_dist = __commonJS({
             message: `Refused: another operation is in flight (${this.inFlight}).`
           };
         }
-        const stateBefore = this.readState();
-        if (stateBefore.pendingBoot !== null) {
+        const pendingBefore = readPendingRootSwap(this.rootDir());
+        if (pendingBefore !== null) {
           return {
             accepted: false,
             targetVersion: input.version ?? null,
             restarting: false,
-            message: `Refused: version ${stateBefore.pendingBoot.version} is already staged and awaiting restart.`
+            message: `Refused: version ${pendingBefore.version} is already staged and awaiting restart.`
           };
         }
         let target = input.version ?? null;
@@ -802,7 +931,7 @@ var require_dist = __commonJS({
         }
         if (isDevChannelVersion(target)) {
           const uploadsDir = devUploadVersionDir(this.rootDir(), target);
-          if (!fs52.existsSync(uploadsDir)) {
+          if (!fs62.existsSync(uploadsDir)) {
             return {
               accepted: false,
               targetVersion: target,
@@ -812,8 +941,9 @@ var require_dist = __commonJS({
           }
         }
         this.inFlight = "staging";
+        let stagingPath;
         try {
-          await this.stageAndActivate(target);
+          stagingPath = await this.stageClosure(target);
         } catch (err) {
           const message = err instanceof Error ? err.message : String(err);
           this.logger.error("root package update staging failed", {
@@ -828,45 +958,42 @@ var require_dist = __commonJS({
         } finally {
           this.inFlight = "idle";
         }
-        const state = this.readState();
-        writeServerRootState(this.rootDir(), {
-          ...state,
-          pendingBoot: {
-            version: target,
-            fromVersion: state.currentVersion,
-            requestedAtMs: this.now(),
-            bootAttempts: 0
-          },
-          rolledBack: null
+        writePendingRootSwap(this.rootDir(), {
+          schemaVersion: 1,
+          version: target,
+          stagingPath,
+          requestedAtMs: this.now()
         });
         this.logger.info("root package update staged \u2014 restarting to apply", {
-          meta: { targetVersion: target, fromVersion: state.currentVersion }
+          meta: { targetVersion: target, fromVersion: runningVersion }
         });
         this.restartServerFn(`${RESTART_REASON_PREFIX}: ${this.spec.packageName}@${target}`);
         return {
           accepted: true,
           targetVersion: target,
           restarting: true,
-          message: `Staged ${this.spec.packageName}@${target} \u2014 restarting to apply (probation boot with auto-rollback).`
+          message: `Staged ${this.spec.packageName}@${target} \u2014 restarting to apply (single automatic reboot).`
         };
       }
       /**
-       * npm-install the target closure into a SAME-FS staging dir inside
-       * `versions/`, validate it, then atomically rename it into place.
+       * npm-install the target closure into a SAME-FS `.staging-*` dir, then
+       * validate it (entry + version + native prebuilds). Returns the staging dir
+       * path for the pending-root-swap marker; the STARTER swaps it into `current`
+       * on the next boot. Throws (cleaning up the staging dir) on any failure so
+       * `applyServerUpdate` reports a staging error and never arms a bad swap.
        */
-      async stageAndActivate(target) {
+      async stageClosure(target) {
         const rootDir = this.rootDir();
-        const vDir = versionsDir(rootDir);
-        fs52.mkdirSync(vDir, { recursive: true });
-        const stagingDir = path52.join(vDir, `.staging-${target}-${process.pid}-${this.now()}`);
-        fs52.mkdirSync(stagingDir, { recursive: true });
+        fs62.mkdirSync(rootDir, { recursive: true });
+        const stagingDir = stagingDirPath(rootDir, target, process.pid, this.now());
+        fs62.mkdirSync(stagingDir, { recursive: true });
         try {
           const devDir = devUploadVersionDir(rootDir, target);
           const registry = this.env["CAMSTACK_NPM_REGISTRY"];
           const installArgs = ["install", "--omit=dev", "--no-audit", "--no-fund", "--loglevel=error"];
-          if (fs52.existsSync(devDir)) {
-            fs52.writeFileSync(
-              path52.join(stagingDir, "package.json"),
+          if (fs62.existsSync(devDir)) {
+            fs62.writeFileSync(
+              path62.join(stagingDir, "package.json"),
               JSON.stringify(this.buildDevUploadsPackageJson(devDir, target), null, 2),
               "utf-8"
             );
@@ -875,8 +1002,8 @@ var require_dist = __commonJS({
               timeoutMs: NPM_INSTALL_TIMEOUT_MS
             });
           } else {
-            fs52.writeFileSync(
-              path52.join(stagingDir, "package.json"),
+            fs62.writeFileSync(
+              path62.join(stagingDir, "package.json"),
               JSON.stringify({ name: "camstack-node-root", private: true }, null, 2),
               "utf-8"
             );
@@ -886,37 +1013,32 @@ var require_dist = __commonJS({
             );
           }
           const entry = rootEntryPath(stagingDir, this.spec);
-          if (!fs52.existsSync(entry)) {
+          if (!fs62.existsSync(entry)) {
             throw new Error(`staged closure is missing the root entry (${entry})`);
           }
-          const stagedVersion = readPackageVersion(
-            path52.join(rootPackageDir(stagingDir, this.spec), "package.json")
-          );
-          if (stagedVersion !== target) {
+          const nodeMajor = Number.parseInt(process.versions.node.split(".")[0] ?? "0", 10);
+          const invalid = validateClosureDir(stagingDir, nodeMajor, this.spec, target);
+          if (invalid !== null) {
+            throw new Error(`staged closure invalid: ${invalid}`);
+          }
+          const missingNatives = findMissingNativePrebuilds(stagingDir);
+          if (missingNatives.length > 0) {
             throw new Error(
-              `staged closure version mismatch: expected ${target}, got ${stagedVersion ?? "unknown"}`
+              `staged closure missing native prebuilds: ${missingNatives.join(", ")} \u2014 refusing to arm a swap that would break the forked runners`
             );
           }
-          const dest = versionDir(rootDir, target);
-          if (fs52.existsSync(dest)) {
-            const aside = `${dest}.evicted-${this.now()}`;
-            await fs52.promises.rename(dest, aside);
-            await fs52.promises.rm(aside, { recursive: true, force: true }).catch(() => void 0);
-          }
-          await fs52.promises.rename(stagingDir, dest);
+          return stagingDir;
         } catch (err) {
-          await fs52.promises.rm(stagingDir, { recursive: true, force: true }).catch(() => void 0);
+          await fs62.promises.rm(stagingDir, { recursive: true, force: true }).catch(() => void 0);
           throw err;
         }
       }
       /**
        * Synthetic staging package.json for the dev server-deploy channel:
        * `dependencies` carries the root package as a `file:` ref to its uploaded
-       * tgz; `overrides` maps EVERY OTHER uploaded `@camstack/<name>` to its tgz
-       * so any transitive occurrence resolves to the uploaded copy, never npm.
+       * tgz; `overrides` maps EVERY OTHER uploaded `@camstack/<name>` to its tgz.
        * Fail-closed: a missing/invalid manifest, a manifest for a different
-       * version, a missing root package, or a listed-but-absent tgz all throw
-       * (surfaced by `applyServerUpdate` as a staging failure).
+       * version, a missing root package, or a listed-but-absent tgz all throw.
        */
       buildDevUploadsPackageJson(devDir, target) {
         const manifest = readDevUploadManifest(devDir);
@@ -935,8 +1057,8 @@ var require_dist = __commonJS({
           );
         }
         const fileRef = (filename) => {
-          const abs = path52.join(devDir, filename);
-          if (!fs52.existsSync(abs)) {
+          const abs = path62.join(devDir, filename);
+          if (!fs62.existsSync(abs)) {
             throw new Error(`dev-uploads tarball listed in the manifest is missing: ${abs}`);
           }
           return `file:${abs}`;
@@ -953,77 +1075,28 @@ var require_dist = __commonJS({
           ...Object.keys(overrides).length > 0 ? { overrides } : {}
         };
       }
-      // ── Rollback ──────────────────────────────────────────────────────────
+      // ── Rollback (removed — single-copy has no N-1) ────────────────────────
+      /**
+       * Rollback is NOT supported in the single-copy model — there is no retained
+       * N-1 copy to revert to (operator's accepted tradeoff). Recovery is manual:
+       * re-apply a known-good version via {@link applyServerUpdate}, or reinstall
+       * the image seed. Kept on the surface so the cap contract is unchanged.
+       */
       async rollbackServerUpdate() {
-        if (this.inFlight !== "idle") {
-          return {
-            accepted: false,
-            targetVersion: null,
-            restarting: false,
-            message: `Refused: another operation is in flight (${this.inFlight}).`
-          };
-        }
-        const state = this.readState();
-        if (state.pendingBoot !== null) {
-          return {
-            accepted: false,
-            targetVersion: null,
-            restarting: false,
-            message: `Refused: version ${state.pendingBoot.version} is already staged and awaiting restart.`
-          };
-        }
-        if (state.currentVersion === null || state.previousVersion === null) {
-          return {
-            accepted: false,
-            targetVersion: state.previousVersion,
-            restarting: false,
-            message: "Refused: no previous version available to roll back to."
-          };
-        }
-        const nodeMajor = Number.parseInt(process.versions.node.split(".")[0] ?? "0", 10);
-        const invalidReason = validateVersionDir(
-          this.rootDir(),
-          state.previousVersion,
-          nodeMajor,
-          this.spec
-        );
-        if (invalidReason !== null) {
-          return {
-            accepted: false,
-            targetVersion: state.previousVersion,
-            restarting: false,
-            message: `Refused: previous version ${state.previousVersion} is not loadable (${invalidReason}).`
-          };
-        }
-        writeServerRootState(this.rootDir(), {
-          ...state,
-          pendingBoot: {
-            version: state.previousVersion,
-            fromVersion: state.currentVersion,
-            requestedAtMs: this.now(),
-            bootAttempts: 0
-          }
-        });
-        this.logger.info("root package rollback requested \u2014 restarting", {
-          meta: { fromVersion: state.currentVersion, toVersion: state.previousVersion }
-        });
-        this.restartServerFn(
-          `${RESTART_REASON_PREFIX}: rollback to ${this.spec.packageName}@${state.previousVersion}`
-        );
         return {
-          accepted: true,
-          targetVersion: state.previousVersion,
-          restarting: true,
-          message: `Rolling back to ${this.spec.packageName}@${state.previousVersion} \u2014 restarting.`
+          accepted: false,
+          targetVersion: null,
+          restarting: false,
+          message: "Rollback is not supported in the single-copy model (no retained previous version). Recover by re-applying a known-good version via applyServerUpdate, or reinstall the image seed."
         };
       }
       // ── Plain restart ─────────────────────────────────────────────────────
       /**
-       * Plain process restart — no version change. Backs the `restartServer` cap
-       * method. Guards mirror apply/rollback: refuse while a stage is in flight
-       * (a concurrent npm install must not be interrupted) or while a version is
-       * already staged awaiting restart (a naive bounce would boot the OLD version
-       * and orphan the pending one — the operator should apply/rollback instead).
+       * Plain process restart — no version change. Refuse while a stage is in
+       * flight (a concurrent npm install must not be interrupted) or while a
+       * version is already staged awaiting restart (a naive bounce would boot the
+       * OLD version and orphan the pending swap — the operator should apply
+       * instead).
        */
       restartNode() {
         const runningVersion = this.runningVersion();
@@ -1035,13 +1108,12 @@ var require_dist = __commonJS({
             message: `Refused: another operation is in flight (${this.inFlight}).`
           };
         }
-        const state = this.readState();
-        if (state.pendingBoot !== null) {
+        if (readPendingRootSwap(this.rootDir()) !== null) {
           return {
             accepted: false,
             targetVersion: runningVersion,
             restarting: false,
-            message: `Refused: version ${state.pendingBoot.version} is staged and awaiting restart \u2014 apply or roll it back instead of a plain restart.`
+            message: "Refused: a version is staged and awaiting restart \u2014 apply it instead of a plain restart."
           };
         }
         this.logger.info("plain node restart requested", { meta: { runningVersion } });
@@ -1055,103 +1127,35 @@ var require_dist = __commonJS({
       }
       // ── Boot health confirmation ──────────────────────────────────────────
       /**
-       * Called by the post-boot path once the node is READY (hub: post-boot
-       * pipeline; agent: first acked `$hub.registerNode`). When THIS process is
-       * the probation boot of a pending version, promote it: `currentVersion` ←
-       * pending, `previousVersion` ← the version it replaced (N-1 retained for
-       * rollback), clear `pendingBoot` + `rolledBack`, and prune every version
-       * dir beyond {current, previous}. No-op otherwise.
+       * Called by the post-boot path once the node is READY. In the single-copy
+       * model there is no pending version to promote (the swap already happened in
+       * the starter). This becomes a best-effort GC of orphaned transient dirs
+       * (`.staging-*` / `.trash-*` left by a crash mid-swap) + the dev-uploads
+       * sweep. Kept returning the legacy `{ promoted }` shape for the callers.
        */
       confirmBootHealthy() {
-        const state = readServerRootState(this.rootDir());
-        if (state === null || state.pendingBoot === null) return { promoted: null };
-        const activeVersion = this.env[this.envNames.activeVersion] ?? null;
-        if (activeVersion !== state.pendingBoot.version) {
-          return { promoted: null };
-        }
-        const promoted = {
-          ...state,
-          currentVersion: state.pendingBoot.version,
-          previousVersion: state.pendingBoot.fromVersion,
-          pendingBoot: null,
-          rolledBack: null
-        };
-        writeServerRootState(this.rootDir(), promoted);
-        this.pruneVersions(
-          [promoted.currentVersion, promoted.previousVersion].filter(
-            (v) => typeof v === "string"
-          )
-        );
+        sweepTransientRootDirs(this.rootDir(), this.now(), STALE_TRANSIENT_MS);
         this.sweepDevUploads(DEV_UPLOADS_KEEP_COUNT);
-        this.logger.info("root package update confirmed healthy", {
-          meta: {
-            version: promoted.currentVersion,
-            previousVersion: promoted.previousVersion
-          }
-        });
-        return { promoted: promoted.currentVersion };
-      }
-      /**
-       * Remove version dirs under `versions/` not in `keep`.
-       *
-       * Transient dot-entries (`.staging-*` / `.evicted-*`) are NOT pruned unless
-       * older than {@link RootUpdateService.STALE_TRANSIENT_MS}: the API starts
-       * serving BEFORE the post-boot `confirmBootHealthy()` runs, so a concurrent
-       * `applyServerUpdate` can be mid-npm-install into a fresh `.staging-*` dir
-       * when this prune fires — deleting it would corrupt that install. Fresh
-       * transient dirs are owned by their in-flight operation (which cleans up on
-       * failure); the staleness sweep only collects dirs orphaned by a crash.
-       */
-      pruneVersions(keep) {
-        const vDir = versionsDir(this.rootDir());
-        let entries;
-        try {
-          entries = fs52.readdirSync(vDir);
-        } catch {
-          return;
-        }
-        for (const entry of entries) {
-          if (keep.includes(entry)) continue;
-          const full = path52.join(vDir, entry);
-          if (entry.startsWith(".")) {
-            try {
-              const ageMs = this.now() - fs52.statSync(full).mtimeMs;
-              if (ageMs < _RootUpdateService.STALE_TRANSIENT_MS) continue;
-            } catch {
-              continue;
-            }
-          }
-          try {
-            fs52.rmSync(full, { recursive: true, force: true });
-            this.logger.debug("pruned server-root version dir", { meta: { entry } });
-          } catch (err) {
-            this.logger.warn("failed to prune server-root version dir", {
-              meta: { entry, error: err instanceof Error ? err.message : String(err) }
-            });
-          }
-        }
+        return { promoted: null };
       }
       /**
        * Promote-time sweep of `server-root/dev-uploads/`: keep only the
        * `keepCount` most recent entries (ordered by the self-describing
        * `-dev.<epochSeconds>` suffix; non-dev-shaped residue counts as oldest).
-       * Uses the same rename-aside graveyard pattern as the addon installer —
-       * a rename is a metadata op that succeeds even when a tarball is held
-       * open, and residue in the graveyard is re-swept on the next promote.
        */
       sweepDevUploads(keepCount) {
         const dir = devUploadsDir(this.rootDir());
         let entries;
         try {
-          entries = fs52.readdirSync(dir);
+          entries = fs62.readdirSync(dir);
         } catch {
           return;
         }
-        const graveyard = path52.join(dir, ".sweeping");
+        const graveyard = path62.join(dir, ".sweeping");
         try {
-          for (const residue of fs52.readdirSync(graveyard)) {
+          for (const residue of fs62.readdirSync(graveyard)) {
             try {
-              fs52.rmSync(path52.join(graveyard, residue), { recursive: true, force: true });
+              fs62.rmSync(path62.join(graveyard, residue), { recursive: true, force: true });
             } catch {
             }
           }
@@ -1163,11 +1167,11 @@ var require_dist = __commonJS({
         );
         const doomed = byNewestFirst.slice(keepCount);
         if (doomed.length === 0) return;
-        fs52.mkdirSync(graveyard, { recursive: true });
+        fs62.mkdirSync(graveyard, { recursive: true });
         for (const entry of doomed) {
-          const aside = path52.join(graveyard, `${entry}-${this.now()}`);
+          const aside = path62.join(graveyard, `${entry}-${this.now()}`);
           try {
-            fs52.renameSync(path52.join(dir, entry), aside);
+            fs62.renameSync(path62.join(dir, entry), aside);
           } catch (err) {
             this.logger.warn("failed to move dev-uploads entry aside for sweep", {
               meta: { entry, error: err instanceof Error ? err.message : String(err) }
@@ -1175,14 +1179,12 @@ var require_dist = __commonJS({
             continue;
           }
           try {
-            fs52.rmSync(aside, { recursive: true, force: true });
+            fs62.rmSync(aside, { recursive: true, force: true });
             this.logger.debug("swept dev-uploads entry", { meta: { entry } });
           } catch {
           }
         }
       }
-      /** Transient (.staging- / .evicted-) dirs younger than this are never pruned. */
-      static STALE_TRANSIENT_MS = 24 * 60 * 60 * 1e3;
     };
   }
 });