@camstack/agent 1.1.33 → 1.1.35

package/dist/starter.js

@@ -0,0 +1,1036 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __commonJS = (cb, mod) => function __require() {
+  return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+
+// ../node-root/dist/index.js
+var require_dist = __commonJS({
+  "../node-root/dist/index.js"(exports2, module2) {
+    "use strict";
+    var __create2 = Object.create;
+    var __defProp2 = Object.defineProperty;
+    var __getOwnPropDesc2 = Object.getOwnPropertyDescriptor;
+    var __getOwnPropNames2 = Object.getOwnPropertyNames;
+    var __getProtoOf2 = Object.getPrototypeOf;
+    var __hasOwnProp2 = Object.prototype.hasOwnProperty;
+    var __export = (target, all) => {
+      for (var name in all)
+        __defProp2(target, name, { get: all[name], enumerable: true });
+    };
+    var __copyProps2 = (to, from, except, desc) => {
+      if (from && typeof from === "object" || typeof from === "function") {
+        for (let key of __getOwnPropNames2(from))
+          if (!__hasOwnProp2.call(to, key) && key !== except)
+            __defProp2(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc2(from, key)) || desc.enumerable });
+      }
+      return to;
+    };
+    var __toESM2 = (mod, isNodeMode, target) => (target = mod != null ? __create2(__getProtoOf2(mod)) : {}, __copyProps2(
+      // If the importer is in node compatibility mode or this is not an ESM
+      // file that has been converted to a CommonJS file using a Babel-
+      // compatible transform (i.e. "__esModule" has not been set), then set
+      // "default" to the CommonJS "module.exports" for node compatibility.
+      isNodeMode || !mod || !mod.__esModule ? __defProp2(target, "default", { value: mod, enumerable: true }) : target,
+      mod
+    ));
+    var __toCommonJS = (mod) => __copyProps2(__defProp2({}, "__esModule", { value: true }), mod);
+    var src_exports = {};
+    __export(src_exports, {
+      AGENT_ROOT_SPEC: () => AGENT_ROOT_SPEC2,
+      HOST_EXTERNAL_SPECIFIERS: () => HOST_EXTERNAL_SPECIFIERS,
+      HUB_ROOT_SPEC: () => HUB_ROOT_SPEC,
+      RESTART_INTENT_FILE: () => RESTART_INTENT_FILE,
+      RootUpdateService: () => RootUpdateService,
+      SERVER_ROOT_DIRNAME: () => SERVER_ROOT_DIRNAME,
+      SERVER_ROOT_STATE_FILE: () => SERVER_ROOT_STATE_FILE,
+      clearRestartIntentMarker: () => clearRestartIntentMarker,
+      compareSemver: () => compareSemver,
+      detectWorkspaceRoot: () => detectWorkspaceRoot,
+      emptyServerRootState: () => emptyServerRootState,
+      isHostExternal: () => isHostExternal,
+      isServerRootState: () => isServerRootState,
+      minNodeMajorOf: () => minNodeMajorOf,
+      planBoot: () => planBoot,
+      readRestartIntentMarker: () => readRestartIntentMarker,
+      readServerRootState: () => readServerRootState,
+      registerActiveRootResolver: () => registerActiveRootResolver,
+      restartIntentMarkerPath: () => restartIntentMarkerPath,
+      rootEntryPath: () => rootEntryPath,
+      rootPackageDir: () => rootPackageDir,
+      runNodeStarter: () => runNodeStarter2,
+      serverRootDir: () => serverRootDir,
+      stateFilePath: () => stateFilePath,
+      validateVersionDir: () => validateVersionDir,
+      versionDir: () => versionDir,
+      versionsDir: () => versionsDir,
+      writeRestartIntentMarker: () => writeRestartIntentMarker,
+      writeServerRootState: () => writeServerRootState
+    });
+    module2.exports = __toCommonJS(src_exports);
+    var HUB_ROOT_SPEC = {
+      packageName: "@camstack/server",
+      entryRelPath: ["dist", "launcher.js"]
+    };
+    var AGENT_ROOT_SPEC2 = {
+      packageName: "@camstack/agent",
+      entryRelPath: ["dist", "cli.js"]
+    };
+    var fs = __toESM2(require("fs"));
+    var path2 = __toESM2(require("path"));
+    var SERVER_ROOT_DIRNAME = "server-root";
+    var SERVER_ROOT_STATE_FILE = "state.json";
+    var RESTART_INTENT_FILE = ".restart-intent";
+    function emptyServerRootState() {
+      return {
+        schemaVersion: 1,
+        currentVersion: null,
+        previousVersion: null,
+        pendingBoot: null,
+        rolledBack: null
+      };
+    }
+    function serverRootDir(dataDir) {
+      return path2.join(dataDir, SERVER_ROOT_DIRNAME);
+    }
+    function versionsDir(rootDir) {
+      return path2.join(rootDir, "versions");
+    }
+    function versionDir(rootDir, version) {
+      return path2.join(versionsDir(rootDir), version);
+    }
+    function rootPackageDir(versionDirPath, spec) {
+      return path2.join(versionDirPath, "node_modules", ...spec.packageName.split("/"));
+    }
+    function rootEntryPath(versionDirPath, spec) {
+      return path2.join(rootPackageDir(versionDirPath, spec), ...spec.entryRelPath);
+    }
+    function stateFilePath(rootDir) {
+      return path2.join(rootDir, SERVER_ROOT_STATE_FILE);
+    }
+    function isNullableString(v) {
+      return v === null || typeof v === "string";
+    }
+    function isPendingBoot(v) {
+      if (typeof v !== "object" || v === null) return false;
+      const p = v;
+      return typeof p["version"] === "string" && isNullableString(p["fromVersion"]) && typeof p["requestedAtMs"] === "number" && typeof p["bootAttempts"] === "number";
+    }
+    function isRollbackInfo(v) {
+      if (typeof v !== "object" || v === null) return false;
+      const r = v;
+      return typeof r["fromVersion"] === "string" && isNullableString(r["toVersion"]) && typeof r["atMs"] === "number" && typeof r["reason"] === "string";
+    }
+    function isServerRootState(v) {
+      if (typeof v !== "object" || v === null) return false;
+      const s = v;
+      if (s["schemaVersion"] !== 1) return false;
+      if (!isNullableString(s["currentVersion"])) return false;
+      if (!isNullableString(s["previousVersion"])) return false;
+      if (s["pendingBoot"] !== null && !isPendingBoot(s["pendingBoot"])) return false;
+      if (s["rolledBack"] !== null && !isRollbackInfo(s["rolledBack"])) return false;
+      return true;
+    }
+    function readServerRootState(rootDir) {
+      try {
+        const raw = JSON.parse(fs.readFileSync(stateFilePath(rootDir), "utf-8"));
+        return isServerRootState(raw) ? raw : null;
+      } catch {
+        return null;
+      }
+    }
+    function writeServerRootState(rootDir, state) {
+      fs.mkdirSync(rootDir, { recursive: true });
+      const target = stateFilePath(rootDir);
+      const tmp = `${target}.tmp`;
+      fs.writeFileSync(tmp, JSON.stringify(state, null, 2), "utf-8");
+      fs.renameSync(tmp, target);
+    }
+    function restartIntentMarkerPath(rootDir) {
+      return path2.join(rootDir, RESTART_INTENT_FILE);
+    }
+    function isRestartIntentMarker(v) {
+      if (typeof v !== "object" || v === null) return false;
+      const m = v;
+      return typeof m["requestedAtMs"] === "number" && typeof m["reason"] === "string";
+    }
+    function writeRestartIntentMarker(rootDir, marker) {
+      fs.mkdirSync(rootDir, { recursive: true });
+      const target = restartIntentMarkerPath(rootDir);
+      const tmp = `${target}.tmp`;
+      fs.writeFileSync(tmp, JSON.stringify(marker, null, 2), "utf-8");
+      fs.renameSync(tmp, target);
+    }
+    function readRestartIntentMarker(rootDir) {
+      try {
+        const raw = JSON.parse(fs.readFileSync(restartIntentMarkerPath(rootDir), "utf-8"));
+        return isRestartIntentMarker(raw) ? raw : null;
+      } catch {
+        return null;
+      }
+    }
+    function clearRestartIntentMarker(rootDir) {
+      try {
+        fs.rmSync(restartIntentMarkerPath(rootDir), { force: true });
+      } catch {
+      }
+    }
+    function minNodeMajorOf(enginesNode) {
+      const match = /(\d+)/.exec(enginesNode);
+      if (match === null) return null;
+      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);
+      if (!fs.existsSync(entry)) {
+        return `root entry missing: ${entry}`;
+      }
+      const pkgJsonPath = path2.join(rootPackageDir(vDir, spec), "package.json");
+      let pkg;
+      try {
+        const raw = JSON.parse(fs.readFileSync(pkgJsonPath, "utf-8"));
+        if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+          return `package.json malformed: ${pkgJsonPath}`;
+        }
+        pkg = raw;
+      } catch {
+        return `package.json unreadable: ${pkgJsonPath}`;
+      }
+      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"])}`;
+      }
+      const engines = pkg["engines"];
+      if (typeof engines === "object" && engines !== null) {
+        const enginesNode = engines["node"];
+        if (typeof enginesNode === "string") {
+          const minMajor = minNodeMajorOf(enginesNode);
+          if (minMajor !== null && nodeMajor < minMajor) {
+            return `engines.node "${enginesNode}" requires Node >= ${minMajor}, runtime is ${nodeMajor}`;
+          }
+        }
+      }
+      return null;
+    }
+    function planBoot(state, isValidVersion, now) {
+      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 }
+            }
+          };
+        }
+      }
+      if (next.currentVersion !== null) {
+        if (isValidVersion(next.currentVersion)) {
+          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"
+              }
+            }
+          };
+        }
+        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"
+            }
+          }
+        };
+      }
+      return {
+        kind: "baked",
+        reason: "no active data-root version",
+        stateToWrite: changed ? next : null
+      };
+    }
+    function parse(version) {
+      const dashIdx = version.indexOf("-");
+      const base = dashIdx === -1 ? version : version.slice(0, dashIdx);
+      const prerelease = dashIdx === -1 ? null : version.slice(dashIdx + 1);
+      const nums = base.split(".").map((seg) => {
+        const n = Number.parseInt(seg, 10);
+        return Number.isNaN(n) ? 0 : n;
+      });
+      return { nums, prerelease };
+    }
+    function compareSemver(a, b) {
+      const pa = parse(a);
+      const pb = parse(b);
+      const len = Math.max(pa.nums.length, pb.nums.length);
+      for (let i = 0; i < len; i++) {
+        const na = pa.nums[i] ?? 0;
+        const nb = pb.nums[i] ?? 0;
+        if (na < nb) return -1;
+        if (na > nb) return 1;
+      }
+      if (pa.prerelease === null && pb.prerelease === null) return 0;
+      if (pa.prerelease === null) return 1;
+      if (pb.prerelease === null) return -1;
+      if (pa.prerelease < pb.prerelease) return -1;
+      if (pa.prerelease > pb.prerelease) return 1;
+      return 0;
+    }
+    var fs2 = __toESM2(require("fs"));
+    var path22 = __toESM2(require("path"));
+    function detectWorkspaceRoot(fromDir) {
+      let dir = path22.resolve(fromDir);
+      for (; ; ) {
+        const pkgPath = path22.join(dir, "package.json");
+        try {
+          const raw = JSON.parse(fs2.readFileSync(pkgPath, "utf-8"));
+          if (typeof raw === "object" && raw !== null && raw["workspaces"] !== void 0) {
+            return dir;
+          }
+        } catch {
+        }
+        const parent = path22.dirname(dir);
+        if (parent === dir) return null;
+        dir = parent;
+      }
+    }
+    var path3 = __toESM2(require("path"));
+    var import_node_url = require("url");
+    var HOST_EXTERNAL_SPECIFIERS = [
+      "@camstack/system",
+      "@camstack/shm-ring",
+      "@camstack/types",
+      "@camstack/sdk",
+      "zod",
+      "@trpc/server",
+      "@trpc/client",
+      "sharp",
+      "node-av"
+    ];
+    function isHostExternal(specifier) {
+      return HOST_EXTERNAL_SPECIFIERS.some(
+        (name) => specifier === name || specifier.startsWith(`${name}/`)
+      );
+    }
+    function registerActiveRootResolver(activeRootDir) {
+      const moduleApi = require("module");
+      const registerHooks = moduleApi["registerHooks"];
+      if (typeof registerHooks !== "function") {
+        console.warn(
+          "[starter] module.registerHooks unavailable (Node < 22.15) \u2014 host-external redirect skipped"
+        );
+        return;
+      }
+      const anchorURL = (0, import_node_url.pathToFileURL)(
+        path3.join(activeRootDir, "node_modules", "__camstack_starter_anchor__.js")
+      ).href;
+      const hooks = {
+        resolve: (specifier, context, nextResolve) => {
+          if (isHostExternal(specifier)) {
+            try {
+              return nextResolve(specifier, { ...context, parentURL: anchorURL });
+            } catch {
+            }
+          }
+          return nextResolve(specifier, context);
+        }
+      };
+      registerHooks(hooks);
+    }
+    function runNodeStarter2(options) {
+      const env = options.env ?? process.env;
+      const now = options.now ?? Date.now;
+      const registerResolver = options.registerResolver ?? registerActiveRootResolver;
+      const disabled = env[options.envNames.killSwitch] === "off";
+      const workspaceRoot = detectWorkspaceRoot(options.starterDir);
+      if (workspaceRoot !== null) {
+        console.log(
+          `[starter] workspace checkout detected at ${workspaceRoot} \u2014 using plain resolution`
+        );
+        env[options.envNames.bootMode] = "workspace";
+        options.loadEntry(options.seedEntry);
+        return;
+      }
+      if (disabled) {
+        console.log(`[starter] ${options.envNames.killSwitch}=off \u2014 booting the baked seed closure`);
+        env[options.envNames.bootMode] = "baked";
+        options.loadEntry(options.seedEntry);
+        return;
+      }
+      const rootDir = serverRootDir(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 plan = planBoot(state, isValidVersion, now);
+      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);
+        console.log(
+          `[starter] booting ${options.spec.packageName}@${plan.version} from ${activeRootDir}` + (plan.probation ? " (probation boot \u2014 health-check armed)" : "")
+        );
+        env[options.envNames.bootMode] = "data-root";
+        env[options.envNames.activeRoot] = activeRootDir;
+        env[options.envNames.activeVersion] = plan.version;
+        registerResolver(activeRootDir);
+        options.loadEntry(entry);
+        return;
+      }
+      console.log(`[starter] booting baked seed closure (${plan.reason})`);
+      env[options.envNames.bootMode] = "baked";
+      options.loadEntry(options.seedEntry);
+    }
+    var import_node_child_process = require("child_process");
+    var fs3 = __toESM2(require("fs"));
+    var path4 = __toESM2(require("path"));
+    var import_node_util = require("util");
+    var execFileAsync = (0, import_node_util.promisify)(import_node_child_process.execFile);
+    function buildNpmRegistryArgs(registry) {
+      if (registry === void 0 || registry.length === 0) return [];
+      return ["--registry", registry, `--@camstack:registry=${registry}`];
+    }
+    var NPM_VIEW_TIMEOUT_MS = 2e4;
+    var NPM_INSTALL_TIMEOUT_MS = 15 * 6e4;
+    var RESTART_REASON_PREFIX = "server-update";
+    function readPackageVersion(pkgJsonPath) {
+      try {
+        const raw = JSON.parse(fs3.readFileSync(pkgJsonPath, "utf-8"));
+        if (typeof raw === "object" && raw !== null) {
+          const version = raw["version"];
+          if (typeof version === "string") return version;
+        }
+      } catch {
+      }
+      return null;
+    }
+    var RootUpdateService = class _RootUpdateService {
+      spec;
+      envNames;
+      logger;
+      restartServerFn;
+      dataDir;
+      execNpm;
+      env;
+      now;
+      runningPackageJsonPath;
+      workspaceProbeDir;
+      checkCache = null;
+      inFlight = "idle";
+      constructor(options) {
+        this.spec = options.spec;
+        this.envNames = options.envNames;
+        this.logger = options.logger;
+        this.restartServerFn = options.restartServer;
+        this.dataDir = path4.resolve(options.dataDir);
+        this.execNpm = options.execNpm ?? (async (args, opts) => {
+          const { stdout } = await execFileAsync("npm", [...args], {
+            cwd: opts.cwd,
+            timeout: opts.timeoutMs
+          });
+          return { stdout };
+        });
+        this.env = options.env ?? process.env;
+        this.now = options.now ?? Date.now;
+        this.runningPackageJsonPath = options.runningPackageJsonPath;
+        this.workspaceProbeDir = options.workspaceProbeDir;
+      }
+      // ── Status ────────────────────────────────────────────────────────────
+      resolveBootMode() {
+        const raw = this.env[this.envNames.bootMode];
+        if (raw === "workspace" || raw === "baked" || raw === "data-root") return raw;
+        return detectWorkspaceRoot(this.workspaceProbeDir) !== null ? "workspace" : "baked";
+      }
+      runningVersion() {
+        return readPackageVersion(this.runningPackageJsonPath);
+      }
+      /** The running root package's identity — feeds registerNode / topology rows. */
+      getRunningRootPackage() {
+        return { name: this.spec.packageName, version: this.runningVersion() };
+      }
+      seedVersion() {
+        const seedDir = this.env[this.envNames.seedDir];
+        if (seedDir === void 0 || seedDir.length === 0) return null;
+        return readPackageVersion(path4.join(seedDir, "package.json"));
+      }
+      rootDir() {
+        return serverRootDir(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: fs3.existsSync(stateFilePath(rootDir)) };
+      }
+      updateState(state) {
+        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";
+        }
+        return "idle";
+      }
+      async getServerPackageStatus() {
+        const { state, corrupt } = this.readStateInfo();
+        const runningVersion = this.runningVersion();
+        const latestVersion = this.checkCache?.latestVersion ?? null;
+        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,
+          seedVersion: this.seedVersion(),
+          latestVersion,
+          updateAvailable,
+          bootMode: this.resolveBootMode(),
+          updateState: this.updateState(state),
+          pendingVersion: state.pendingBoot?.version ?? null,
+          rolledBack: state.rolledBack,
+          stateFileCorrupt: corrupt,
+          lastCheckedAtMs: this.checkCache?.checkedAtMs ?? null
+        };
+      }
+      // ── Check ─────────────────────────────────────────────────────────────
+      async checkServerUpdate() {
+        const runningVersion = this.runningVersion();
+        if (this.inFlight !== "idle") {
+          return {
+            packageName: this.spec.packageName,
+            runningVersion,
+            latestVersion: this.checkCache?.latestVersion ?? null,
+            updateAvailable: false,
+            checkedAtMs: this.checkCache?.checkedAtMs ?? this.now(),
+            error: `busy: ${this.inFlight}`
+          };
+        }
+        this.inFlight = "checking";
+        try {
+          const registry = this.env["CAMSTACK_NPM_REGISTRY"];
+          const args = [
+            "view",
+            `${this.spec.packageName}@latest`,
+            "version",
+            ...buildNpmRegistryArgs(registry)
+          ];
+          const { stdout } = await this.execNpm(args, { timeoutMs: NPM_VIEW_TIMEOUT_MS });
+          const latestVersion = stdout.trim().length > 0 ? stdout.trim() : null;
+          this.checkCache = { latestVersion, checkedAtMs: this.now(), error: null };
+          const updateAvailable = latestVersion !== null && runningVersion !== null && compareSemver(latestVersion, runningVersion) > 0;
+          return {
+            packageName: this.spec.packageName,
+            runningVersion,
+            latestVersion,
+            updateAvailable,
+            checkedAtMs: this.checkCache.checkedAtMs,
+            error: null
+          };
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          this.checkCache = {
+            latestVersion: this.checkCache?.latestVersion ?? null,
+            checkedAtMs: this.now(),
+            error: message
+          };
+          this.logger.warn("root package update check failed", { meta: { error: message } });
+          return {
+            packageName: this.spec.packageName,
+            runningVersion,
+            latestVersion: this.checkCache.latestVersion,
+            updateAvailable: false,
+            checkedAtMs: this.checkCache.checkedAtMs,
+            error: message
+          };
+        } finally {
+          this.inFlight = "idle";
+        }
+      }
+      // ── Apply ─────────────────────────────────────────────────────────────
+      async applyServerUpdate(input) {
+        const bootMode = this.resolveBootMode();
+        if (bootMode === "workspace") {
+          return {
+            accepted: false,
+            targetVersion: input.version ?? null,
+            restarting: false,
+            message: "Refused: running from a workspace checkout \u2014 the dev loop resolves code from the workspace, a data-root update would never be loaded."
+          };
+        }
+        if (this.inFlight !== "idle") {
+          return {
+            accepted: false,
+            targetVersion: input.version ?? null,
+            restarting: false,
+            message: `Refused: another operation is in flight (${this.inFlight}).`
+          };
+        }
+        const stateBefore = this.readState();
+        if (stateBefore.pendingBoot !== null) {
+          return {
+            accepted: false,
+            targetVersion: input.version ?? null,
+            restarting: false,
+            message: `Refused: version ${stateBefore.pendingBoot.version} is already staged and awaiting restart.`
+          };
+        }
+        let target = input.version ?? null;
+        if (target === null) {
+          const check = await this.checkServerUpdate();
+          if (check.error !== null || check.latestVersion === null) {
+            return {
+              accepted: false,
+              targetVersion: null,
+              restarting: false,
+              message: `Refused: could not resolve the latest version (${check.error ?? "no version returned"}).`
+            };
+          }
+          target = check.latestVersion;
+        }
+        const runningVersion = this.runningVersion();
+        if (target === runningVersion) {
+          return {
+            accepted: false,
+            targetVersion: target,
+            restarting: false,
+            message: `Refused: ${this.spec.packageName}@${target} is already running.`
+          };
+        }
+        this.inFlight = "staging";
+        try {
+          await this.stageAndActivate(target);
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          this.logger.error("root package update staging failed", {
+            meta: { targetVersion: target, error: message }
+          });
+          return {
+            accepted: false,
+            targetVersion: target,
+            restarting: false,
+            message: `Staging failed: ${message}`
+          };
+        } 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
+        });
+        this.logger.info("root package update staged \u2014 restarting to apply", {
+          meta: { targetVersion: target, fromVersion: state.currentVersion }
+        });
+        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).`
+        };
+      }
+      /**
+       * npm-install the target closure into a SAME-FS staging dir inside
+       * `versions/`, validate it, then atomically rename it into place.
+       */
+      async stageAndActivate(target) {
+        const rootDir = this.rootDir();
+        const vDir = versionsDir(rootDir);
+        fs3.mkdirSync(vDir, { recursive: true });
+        const stagingDir = path4.join(vDir, `.staging-${target}-${process.pid}-${this.now()}`);
+        fs3.mkdirSync(stagingDir, { recursive: true });
+        try {
+          fs3.writeFileSync(
+            path4.join(stagingDir, "package.json"),
+            JSON.stringify({ name: "camstack-node-root", private: true }, null, 2),
+            "utf-8"
+          );
+          const registry = this.env["CAMSTACK_NPM_REGISTRY"];
+          await this.execNpm(
+            [
+              "install",
+              "--omit=dev",
+              "--no-audit",
+              "--no-fund",
+              "--loglevel=error",
+              `${this.spec.packageName}@${target}`,
+              ...buildNpmRegistryArgs(registry)
+            ],
+            { cwd: stagingDir, timeoutMs: NPM_INSTALL_TIMEOUT_MS }
+          );
+          const entry = rootEntryPath(stagingDir, this.spec);
+          if (!fs3.existsSync(entry)) {
+            throw new Error(`staged closure is missing the root entry (${entry})`);
+          }
+          const stagedVersion = readPackageVersion(
+            path4.join(rootPackageDir(stagingDir, this.spec), "package.json")
+          );
+          if (stagedVersion !== target) {
+            throw new Error(
+              `staged closure version mismatch: expected ${target}, got ${stagedVersion ?? "unknown"}`
+            );
+          }
+          const dest = versionDir(rootDir, target);
+          if (fs3.existsSync(dest)) {
+            const aside = `${dest}.evicted-${this.now()}`;
+            await fs3.promises.rename(dest, aside);
+            await fs3.promises.rm(aside, { recursive: true, force: true }).catch(() => void 0);
+          }
+          await fs3.promises.rename(stagingDir, dest);
+        } catch (err) {
+          await fs3.promises.rm(stagingDir, { recursive: true, force: true }).catch(() => void 0);
+          throw err;
+        }
+      }
+      // ── Rollback ──────────────────────────────────────────────────────────
+      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.`
+        };
+      }
+      // ── 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).
+       */
+      restartNode() {
+        const runningVersion = this.runningVersion();
+        if (this.inFlight !== "idle") {
+          return {
+            accepted: false,
+            targetVersion: runningVersion,
+            restarting: false,
+            message: `Refused: another operation is in flight (${this.inFlight}).`
+          };
+        }
+        const state = this.readState();
+        if (state.pendingBoot !== 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.`
+          };
+        }
+        this.logger.info("plain node restart requested", { meta: { runningVersion } });
+        this.restartServerFn(`${RESTART_REASON_PREFIX}: manual restart`);
+        return {
+          accepted: true,
+          targetVersion: runningVersion,
+          restarting: true,
+          message: "Restarting the node \u2014 the supervisor relaunches it on the same version."
+        };
+      }
+      // ── 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.
+       */
+      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"
+          )
+        );
+        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 = fs3.readdirSync(vDir);
+        } catch {
+          return;
+        }
+        for (const entry of entries) {
+          if (keep.includes(entry)) continue;
+          const full = path4.join(vDir, entry);
+          if (entry.startsWith(".")) {
+            try {
+              const ageMs = this.now() - fs3.statSync(full).mtimeMs;
+              if (ageMs < _RootUpdateService.STALE_TRANSIENT_MS) continue;
+            } catch {
+              continue;
+            }
+          }
+          try {
+            fs3.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) }
+            });
+          }
+        }
+      }
+      /** Transient (.staging- / .evicted-) dirs younger than this are never pruned. */
+      static STALE_TRANSIENT_MS = 24 * 60 * 60 * 1e3;
+    };
+  }
+});
+
+// src/starter.ts
+var import_node_fs = require("fs");
+var path = __toESM(require("path"));
+var import_node_root = __toESM(require_dist());
+function resolveAgentDataDir(argv, env) {
+  const fromEnv = env["CAMSTACK_DATA_DIR"];
+  if (fromEnv !== void 0 && fromEnv.length > 0) return path.resolve(fromEnv);
+  for (let i = 2; i < argv.length - 1; i++) {
+    if (argv[i] === "--data" || argv[i] === "-d") {
+      const next = argv[i + 1];
+      if (next !== void 0 && !next.startsWith("-")) return path.resolve(next);
+    }
+  }
+  return path.resolve("camstack-data");
+}
+function warnRestartPolicyDependency() {
+  if (!(0, import_node_fs.existsSync)("/.dockerenv")) return;
+  console.warn(
+    "[starter] container detected \u2014 server-management apply/rollback exit this process for the supervisor to relaunch. Ensure the container restart policy is 'unless-stopped' or 'always', otherwise an update/rollback leaves the node down."
+  );
+}
+function start() {
+  warnRestartPolicyDependency();
+  const seedPackageDir = path.resolve(__dirname, "..");
+  if (process.env["CAMSTACK_SEED_AGENT_DIR"] === void 0) {
+    process.env["CAMSTACK_SEED_AGENT_DIR"] = seedPackageDir;
+  }
+  (0, import_node_root.runNodeStarter)({
+    spec: import_node_root.AGENT_ROOT_SPEC,
+    envNames: {
+      bootMode: "CAMSTACK_AGENT_BOOT_MODE",
+      activeRoot: "CAMSTACK_AGENT_ACTIVE_ROOT",
+      activeVersion: "CAMSTACK_AGENT_ACTIVE_VERSION",
+      killSwitch: "CAMSTACK_AGENT_ROOT"
+    },
+    dataDir: resolveAgentDataDir(process.argv, process.env),
+    seedEntry: path.join(__dirname, "cli.js"),
+    starterDir: __dirname,
+    // The CLI is CJS (tsup build) — a plain require keeps the starter
+    // synchronous; the CLI reads the SAME process.argv it always did.
+    loadEntry: (entryPath) => require(entryPath)
+  });
+}
+try {
+  start();
+} catch (err) {
+  console.error("[starter] FATAL:", err);
+  process.exit(1);
+}
+//# sourceMappingURL=starter.js.map