@camstack/agent 1.1.32 → 1.1.35

package/dist/cli.js

@@ -6,6 +6,9 @@ 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))
@@ -23,15 +26,974 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
   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: () => RootUpdateService2,
+      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: () => runNodeStarter,
+      serverRootDir: () => serverRootDir2,
+      stateFilePath: () => stateFilePath,
+      validateVersionDir: () => validateVersionDir,
+      versionDir: () => versionDir,
+      versionsDir: () => versionsDir,
+      writeRestartIntentMarker: () => writeRestartIntentMarker2,
+      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 fs8 = __toESM2(require("fs"));
+    var path9 = __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 serverRootDir2(dataDir) {
+      return path9.join(dataDir, SERVER_ROOT_DIRNAME);
+    }
+    function versionsDir(rootDir) {
+      return path9.join(rootDir, "versions");
+    }
+    function versionDir(rootDir, version) {
+      return path9.join(versionsDir(rootDir), version);
+    }
+    function rootPackageDir(versionDirPath, spec) {
+      return path9.join(versionDirPath, "node_modules", ...spec.packageName.split("/"));
+    }
+    function rootEntryPath(versionDirPath, spec) {
+      return path9.join(rootPackageDir(versionDirPath, spec), ...spec.entryRelPath);
+    }
+    function stateFilePath(rootDir) {
+      return path9.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(fs8.readFileSync(stateFilePath(rootDir), "utf-8"));
+        return isServerRootState(raw) ? raw : null;
+      } catch {
+        return null;
+      }
+    }
+    function writeServerRootState(rootDir, state) {
+      fs8.mkdirSync(rootDir, { recursive: true });
+      const target = stateFilePath(rootDir);
+      const tmp = `${target}.tmp`;
+      fs8.writeFileSync(tmp, JSON.stringify(state, null, 2), "utf-8");
+      fs8.renameSync(tmp, target);
+    }
+    function restartIntentMarkerPath(rootDir) {
+      return path9.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 writeRestartIntentMarker2(rootDir, marker) {
+      fs8.mkdirSync(rootDir, { recursive: true });
+      const target = restartIntentMarkerPath(rootDir);
+      const tmp = `${target}.tmp`;
+      fs8.writeFileSync(tmp, JSON.stringify(marker, null, 2), "utf-8");
+      fs8.renameSync(tmp, target);
+    }
+    function readRestartIntentMarker(rootDir) {
+      try {
+        const raw = JSON.parse(fs8.readFileSync(restartIntentMarkerPath(rootDir), "utf-8"));
+        return isRestartIntentMarker(raw) ? raw : null;
+      } catch {
+        return null;
+      }
+    }
+    function clearRestartIntentMarker(rootDir) {
+      try {
+        fs8.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 (!fs8.existsSync(entry)) {
+        return `root entry missing: ${entry}`;
+      }
+      const pkgJsonPath = path9.join(rootPackageDir(vDir, spec), "package.json");
+      let pkg;
+      try {
+        const raw = JSON.parse(fs8.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 fs22 = __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(fs22.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 path32 = __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)(
+        path32.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 runNodeStarter(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 = 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 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 fs32 = __toESM2(require("fs"));
+    var path42 = __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(fs32.readFileSync(pkgJsonPath, "utf-8"));
+        if (typeof raw === "object" && raw !== null) {
+          const version = raw["version"];
+          if (typeof version === "string") return version;
+        }
+      } catch {
+      }
+      return null;
+    }
+    var RootUpdateService2 = 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 = path42.resolve(options.dataDir);
+        this.execNpm = options.execNpm ?? (async (args2, opts) => {
+          const { stdout } = await execFileAsync("npm", [...args2], {
+            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(path42.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: fs32.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 args2 = [
+            "view",
+            `${this.spec.packageName}@latest`,
+            "version",
+            ...buildNpmRegistryArgs(registry)
+          ];
+          const { stdout } = await this.execNpm(args2, { 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);
+        fs32.mkdirSync(vDir, { recursive: true });
+        const stagingDir = path42.join(vDir, `.staging-${target}-${process.pid}-${this.now()}`);
+        fs32.mkdirSync(stagingDir, { recursive: true });
+        try {
+          fs32.writeFileSync(
+            path42.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 (!fs32.existsSync(entry)) {
+            throw new Error(`staged closure is missing the root entry (${entry})`);
+          }
+          const stagedVersion = readPackageVersion(
+            path42.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 (fs32.existsSync(dest)) {
+            const aside = `${dest}.evicted-${this.now()}`;
+            await fs32.promises.rename(dest, aside);
+            await fs32.promises.rm(aside, { recursive: true, force: true }).catch(() => void 0);
+          }
+          await fs32.promises.rename(stagingDir, dest);
+        } catch (err) {
+          await fs32.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 = fs32.readdirSync(vDir);
+        } catch {
+          return;
+        }
+        for (const entry of entries) {
+          if (keep.includes(entry)) continue;
+          const full = path42.join(vDir, entry);
+          if (entry.startsWith(".")) {
+            try {
+              const ageMs = this.now() - fs32.statSync(full).mtimeMs;
+              if (ageMs < _RootUpdateService.STALE_TRANSIENT_MS) continue;
+            } catch {
+              continue;
+            }
+          }
+          try {
+            fs32.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/cli.ts
 var import_node_fs = require("fs");
 var import_node_module = require("module");
 var os3 = __toESM(require("os"));
-var path7 = __toESM(require("path"));
+var path8 = __toESM(require("path"));
 
 // src/agent-bootstrap.ts
-var fs6 = __toESM(require("fs"));
-var path6 = __toESM(require("path"));
+var fs7 = __toESM(require("fs"));
+var path7 = __toESM(require("path"));
 
 // src/agent-http.ts
 var fs = __toESM(require("fs"));
@@ -411,27 +1373,110 @@ function loadAgentConfig(configPath, dataDirOverride) {
   };
 }
 
+// src/agent-update-service.ts
+var fs3 = __toESM(require("fs"));
+var path3 = __toESM(require("path"));
+var import_node_root = __toESM(require_dist());
+var AGENT_RUNTIME_ADDON_ID = "agent-runtime";
+var AGENT_RESTART_GRACE_MS = 2e3;
+var AGENT_LOCAL_CONFIRM_GRACE_MS = 9e4;
+function armLocalConfirmFallback(onGrace, graceMs = AGENT_LOCAL_CONFIRM_GRACE_MS) {
+  const timer = setTimeout(() => onGrace(), graceMs);
+  const maybeUnref = timer.unref;
+  if (typeof maybeUnref === "function") maybeUnref.call(timer);
+  return () => clearTimeout(timer);
+}
+function resolveAgentPackageJsonPath(fromDir) {
+  const candidates = [
+    path3.resolve(fromDir, "..", "package.json"),
+    path3.resolve(fromDir, "..", "..", "package.json")
+  ];
+  for (const candidate of candidates) {
+    try {
+      const raw = JSON.parse(fs3.readFileSync(candidate, "utf-8"));
+      if (raw.name === import_node_root.AGENT_ROOT_SPEC.packageName) return candidate;
+    } catch {
+    }
+  }
+  return candidates[0] ?? path3.resolve(fromDir, "..", "package.json");
+}
+function scheduleAgentRestart(logger, requestedBy, dataDir) {
+  if (dataDir !== void 0 && dataDir.length > 0) {
+    try {
+      (0, import_node_root.writeRestartIntentMarker)((0, import_node_root.serverRootDir)(dataDir), {
+        requestedAtMs: Date.now(),
+        reason: requestedBy
+      });
+    } catch (err) {
+      logger.warn("failed to write restart-intent marker", {
+        meta: { error: err instanceof Error ? err.message : String(err) }
+      });
+    }
+  }
+  logger.warn("agent restart requested \u2014 exiting for supervisor relaunch", {
+    meta: { requestedBy, graceMs: AGENT_RESTART_GRACE_MS }
+  });
+  const grace = setTimeout(() => {
+    process.kill(process.pid, "SIGTERM");
+    const hard = setTimeout(() => process.exit(0), 15e3);
+    hard.unref();
+  }, AGENT_RESTART_GRACE_MS);
+  grace.unref();
+}
+var AgentUpdateService = class extends import_node_root.RootUpdateService {
+  constructor(options) {
+    super({
+      spec: import_node_root.AGENT_ROOT_SPEC,
+      envNames: {
+        bootMode: "CAMSTACK_AGENT_BOOT_MODE",
+        activeVersion: "CAMSTACK_AGENT_ACTIVE_VERSION",
+        seedDir: "CAMSTACK_SEED_AGENT_DIR"
+      },
+      logger: options.logger,
+      restartServer: options.restartAgent ?? ((requestedBy) => scheduleAgentRestart(options.logger, requestedBy, options.dataDir)),
+      dataDir: options.dataDir,
+      runningPackageJsonPath: options.runningPackageJsonPath ?? resolveAgentPackageJsonPath(__dirname),
+      workspaceProbeDir: __dirname,
+      execNpm: options.execNpm,
+      env: options.env,
+      now: options.now
+    });
+  }
+};
+function buildAgentServerManagementProvider(service) {
+  return {
+    getServerPackageStatus: () => service.getServerPackageStatus(),
+    checkServerUpdate: () => service.checkServerUpdate(),
+    applyServerUpdate: (input) => service.applyServerUpdate(input),
+    rollbackServerUpdate: () => service.rollbackServerUpdate(),
+    restartServer: () => Promise.resolve(service.restartNode())
+  };
+}
+function agentRuntimeManifestEntry() {
+  return { addonId: AGENT_RUNTIME_ADDON_ID, capabilities: ["server-management"] };
+}
+
 // src/agent-service.ts
-var fs4 = __toESM(require("fs"));
+var fs5 = __toESM(require("fs"));
 var os2 = __toESM(require("os"));
-var path4 = __toESM(require("path"));
+var path5 = __toESM(require("path"));
 var import_system = require("@camstack/system");
 var import_moleculer = require("moleculer");
 
 // src/agent-deploy-swap.ts
-var fs3 = __toESM(require("fs"));
-var path3 = __toESM(require("path"));
+var fs4 = __toESM(require("fs"));
+var path4 = __toESM(require("path"));
 var import_node_crypto = require("crypto");
 function rmrf(target) {
-  fs3.rmSync(target, { recursive: true, force: true });
+  fs4.rmSync(target, { recursive: true, force: true });
 }
 function moveDir(from, to) {
   try {
-    fs3.renameSync(from, to);
+    fs4.renameSync(from, to);
   } catch (err) {
     const code = err.code;
     if (code === "EXDEV") {
-      fs3.cpSync(from, to, { recursive: true });
+      fs4.cpSync(from, to, { recursive: true });
       rmrf(from);
     } else {
       throw err;
@@ -440,32 +1485,32 @@ function moveDir(from, to) {
 }
 async function applyDeployedBundle(input) {
   const { addonsDir, addonId, bundle, extract, logger } = input;
-  fs3.mkdirSync(addonsDir, { recursive: true });
-  const liveDir = path3.join(addonsDir, addonId);
-  const liveParent = path3.dirname(liveDir);
-  const liveBase = path3.basename(liveDir);
-  fs3.mkdirSync(liveParent, { recursive: true });
+  fs4.mkdirSync(addonsDir, { recursive: true });
+  const liveDir = path4.join(addonsDir, addonId);
+  const liveParent = path4.dirname(liveDir);
+  const liveBase = path4.basename(liveDir);
+  fs4.mkdirSync(liveParent, { recursive: true });
   const token = (0, import_node_crypto.randomBytes)(6).toString("hex");
-  const nextDir = path3.join(liveParent, `.${liveBase}.next.${token}`);
-  const backupDir = path3.join(liveParent, `.${liveBase}.backup.${token}`);
-  fs3.mkdirSync(nextDir, { recursive: true });
+  const nextDir = path4.join(liveParent, `.${liveBase}.next.${token}`);
+  const backupDir = path4.join(liveParent, `.${liveBase}.backup.${token}`);
+  fs4.mkdirSync(nextDir, { recursive: true });
   try {
     await extract(bundle, nextDir);
   } catch (err) {
     rmrf(nextDir);
     throw err;
   }
-  const hadLive = fs3.existsSync(liveDir);
+  const hadLive = fs4.existsSync(liveDir);
   if (hadLive) {
-    fs3.renameSync(liveDir, backupDir);
+    fs4.renameSync(liveDir, backupDir);
   }
   try {
     moveDir(nextDir, liveDir);
   } catch (swapErr) {
     if (hadLive) {
       try {
-        if (fs3.existsSync(liveDir)) rmrf(liveDir);
-        fs3.renameSync(backupDir, liveDir);
+        if (fs4.existsSync(liveDir)) rmrf(liveDir);
+        fs4.renameSync(backupDir, liveDir);
       } catch (restoreErr) {
         logger.error(
           `agent deploy swap: restore of "${addonId}" failed after a failed swap \u2014 manual recovery may be needed`,
@@ -540,8 +1585,8 @@ function getLocalIps() {
 }
 async function withTimeout(p, ms, fallback) {
   let timer;
-  const timeout = new Promise((resolve6) => {
-    timer = setTimeout(() => resolve6(fallback), ms);
+  const timeout = new Promise((resolve7) => {
+    timer = setTimeout(() => resolve7(fallback), ms);
   });
   try {
     return await Promise.race([p, timeout]);
@@ -575,8 +1620,8 @@ function resolveDeployAction(seam) {
 function readHubAddressFromConfig(configPath) {
   if (!configPath) return null;
   try {
-    if (!fs4.existsSync(configPath)) return null;
-    const raw = JSON.parse(fs4.readFileSync(configPath, "utf-8"));
+    if (!fs5.existsSync(configPath)) return null;
+    const raw = JSON.parse(fs5.readFileSync(configPath, "utf-8"));
     return typeof raw.hubAddress === "string" && raw.hubAddress.length > 0 ? raw.hubAddress : null;
   } catch {
     return null;
@@ -584,9 +1629,9 @@ function readHubAddressFromConfig(configPath) {
 }
 function readDeployedAddonIds(addonDir) {
   try {
-    const manifestPath = path4.join(addonDir, "package.json");
-    if (!fs4.existsSync(manifestPath)) return [];
-    const raw = JSON.parse(fs4.readFileSync(manifestPath, "utf-8"));
+    const manifestPath = path5.join(addonDir, "package.json");
+    if (!fs5.existsSync(manifestPath)) return [];
+    const raw = JSON.parse(fs5.readFileSync(manifestPath, "utf-8"));
     const entries = raw.camstack?.addons ?? [];
     const ids = [];
     for (const entry of entries) {
@@ -726,17 +1771,17 @@ function createAgentService(deps) {
           deps.agentName = newName.trim();
           broker.logger.info(`Agent renamed: "${oldName}" \u2192 "${deps.agentName}"`);
           try {
-            const configFile = path4.resolve(deps.configPath);
+            const configFile = path5.resolve(deps.configPath);
             let raw = {};
-            if (fs4.existsSync(configFile)) {
+            if (fs5.existsSync(configFile)) {
               try {
-                raw = JSON.parse(fs4.readFileSync(configFile, "utf-8"));
+                raw = JSON.parse(fs5.readFileSync(configFile, "utf-8"));
               } catch {
               }
             }
             raw.name = deps.agentName;
-            fs4.mkdirSync(path4.dirname(configFile), { recursive: true });
-            fs4.writeFileSync(configFile, JSON.stringify(raw, null, 2), "utf-8");
+            fs5.mkdirSync(path5.dirname(configFile), { recursive: true });
+            fs5.writeFileSync(configFile, JSON.stringify(raw, null, 2), "utf-8");
             broker.logger.info(`Agent name persisted to ${configFile}`);
           } catch (err) {
             broker.logger.warn(
@@ -760,15 +1805,15 @@ function createAgentService(deps) {
           const { promisify } = await import("util");
           const execFileAsync = promisify(execFile);
           const extract = async (tgz, destDir) => {
-            const tgzPath = path4.join(destDir, "..", `.${path4.basename(destDir)}.tgz`);
-            fs4.writeFileSync(tgzPath, tgz);
+            const tgzPath = path5.join(destDir, "..", `.${path5.basename(destDir)}.tgz`);
+            fs5.writeFileSync(tgzPath, tgz);
             try {
               await execFileAsync("tar", ["-xzf", tgzPath, "-C", destDir, "--strip-components=1"], {
                 timeout: 6e4
               });
             } finally {
               try {
-                fs4.unlinkSync(tgzPath);
+                fs5.unlinkSync(tgzPath);
               } catch {
               }
             }
@@ -819,26 +1864,26 @@ function createAgentService(deps) {
           const { execFile } = await import("child_process");
           const { promisify } = await import("util");
           const execFileAsync = promisify(execFile);
-          const modelsDir = path4.join(deps.dataDir, "models");
+          const modelsDir = path5.join(deps.dataDir, "models");
           const seam = {
             modelsDir,
             fetchBundle: (s) => fetchBundleFromHub(s),
             extract: async (tgz, destDir) => {
-              const tmp = path4.join(
+              const tmp = path5.join(
                 destDir,
                 `.dist-${Date.now()}-${Math.random().toString(36).slice(2)}.tgz`
               );
-              fs4.writeFileSync(tmp, tgz);
+              fs5.writeFileSync(tmp, tgz);
               try {
                 await execFileAsync("tar", ["-xzf", tmp, "-C", destDir], { timeout: 6e4 });
               } finally {
                 try {
-                  fs4.unlinkSync(tmp);
+                  fs5.unlinkSync(tmp);
                 } catch {
                 }
               }
             },
-            mkdirp: (dir) => fs4.mkdirSync(dir, { recursive: true })
+            mkdirp: (dir) => fs5.mkdirSync(dir, { recursive: true })
           };
           return applyModelDistribution(seam, params);
         }
@@ -883,17 +1928,17 @@ function createAgentService(deps) {
           } catch {
           }
           deps.loadedAddons.delete(addonId);
-          const addonDir = path4.join(deps.addonsDir, addonId);
-          if (fs4.existsSync(addonDir)) {
-            fs4.rmSync(addonDir, { recursive: true, force: true });
+          const addonDir = path5.join(deps.addonsDir, addonId);
+          if (fs5.existsSync(addonDir)) {
+            fs5.rmSync(addonDir, { recursive: true, force: true });
           }
           const pkgName = entry?.packageName;
           if (pkgName && pkgName !== addonId) {
             const pkgShared = [...deps.loadedAddons.values()].some((e) => e.packageName === pkgName);
             if (!pkgShared) {
-              const pkgDir = path4.join(deps.addonsDir, pkgName);
-              if (fs4.existsSync(pkgDir)) {
-                fs4.rmSync(pkgDir, { recursive: true, force: true });
+              const pkgDir = path5.join(deps.addonsDir, pkgName);
+              if (fs5.existsSync(pkgDir)) {
+                fs5.rmSync(pkgDir, { recursive: true, force: true });
               }
             }
           }
@@ -961,14 +2006,14 @@ function createAgentService(deps) {
 }
 
 // src/agent-group-runner.ts
-var fs5 = __toESM(require("fs"));
-var path5 = __toESM(require("path"));
+var fs6 = __toESM(require("fs"));
+var path6 = __toESM(require("path"));
 var import_types = require("@camstack/types");
 function readPackageManifestAddons(dir) {
   try {
-    const pkgPath = path5.join(dir, "package.json");
-    if (!fs5.existsSync(pkgPath)) return null;
-    const raw = JSON.parse(fs5.readFileSync(pkgPath, "utf-8"));
+    const pkgPath = path6.join(dir, "package.json");
+    if (!fs6.existsSync(pkgPath)) return null;
+    const raw = JSON.parse(fs6.readFileSync(pkgPath, "utf-8"));
     const packageName = typeof raw.name === "string" ? raw.name : "";
     const packageVersion = typeof raw.version === "string" ? raw.version : "0.0.0";
     const entries = Array.isArray(raw.camstack?.addons) ? raw.camstack.addons : [];
@@ -1139,7 +2184,7 @@ async function startAgent(configPath) {
   const bundledDir = process.env["CAMSTACK_BUNDLED_ADDONS_DIR"];
   let workspaceDir = null;
   let resolvedSource = explicitSource;
-  if (bundledDir && fs6.existsSync(bundledDir)) {
+  if (bundledDir && fs7.existsSync(bundledDir)) {
     workspaceDir = bundledDir;
     resolvedSource = "local";
     console.log(`[Agent] Using bundled addons from ${bundledDir}`);
@@ -1203,9 +2248,9 @@ async function startAgent(configPath) {
     return discoveryMode ? "searching" : "disconnected";
   }
   function readConfigFile2(p) {
-    if (!fs6.existsSync(p)) return {};
+    if (!fs7.existsSync(p)) return {};
     try {
-      return JSON.parse(fs6.readFileSync(p, "utf-8"));
+      return JSON.parse(fs7.readFileSync(p, "utf-8"));
     } catch {
       return {};
     }
@@ -1235,6 +2280,7 @@ async function startAgent(configPath) {
       const caps = addonCapMap.get(addonId) ?? [];
       result.push({ addonId, capabilities: caps });
     }
+    result.push(agentRuntimeManifestEntry());
     return result;
   }
   function aggregateManifest() {
@@ -1251,11 +2297,13 @@ async function startAgent(configPath) {
         allNativeCaps.push(...childNativeCaps);
       }
     }
+    const rootPackage = agentUpdateService.getRunningRootPackage();
     return (0, import_system3.buildNodeManifest)(
       config.nodeId,
       allAddons,
       allNativeCaps.length > 0 ? allNativeCaps : void 0,
-      config.secret ? (0, import_system3.hashClusterSecret)(config.secret) : void 0
+      config.secret ? (0, import_system3.hashClusterSecret)(config.secret) : void 0,
+      rootPackage.version === null ? void 0 : { name: rootPackage.name, version: rootPackage.version }
     );
   }
   function triggerUpwardRegistration() {
@@ -1267,7 +2315,9 @@ async function startAgent(configPath) {
         signal: registerAbortController.signal,
         log: (msg) => console.log(`[Agent] ${msg}`)
       }
-    ).catch((err) => {
+    ).then(() => {
+      confirmAgentBootHealthy("hub-ack");
+    }).catch((err) => {
       if ((0, import_system3.isClusterSecretMismatchError)(err)) {
         consoleLogger.error(
           "hub registration rejected: cluster secret mismatch \u2014 correct CAMSTACK_CLUSTER_SECRET and restart the agent"
@@ -1297,11 +2347,41 @@ async function startAgent(configPath) {
     import_types3.pipelineExecutorCapability,
     import_types3.pipelineRunnerCapability,
     import_types3.audioAnalyzerCapability,
-    import_types3.platformProbeCapability
+    import_types3.platformProbeCapability,
+    import_types3.serverManagementCapability
   ];
   for (const cap of agentCapabilities) {
     capabilityRegistry.declareCapability(cap);
   }
+  const agentUpdateService = new AgentUpdateService({
+    logger: consoleLogger,
+    dataDir: config.dataDir
+  });
+  capabilityRegistry.registerProvider(
+    "server-management",
+    AGENT_RUNTIME_ADDON_ID,
+    buildAgentServerManagementProvider(agentUpdateService)
+  );
+  let agentBootConfirmed = false;
+  let cancelLocalConfirmFallback = null;
+  const confirmAgentBootHealthy = (source) => {
+    if (agentBootConfirmed) return;
+    agentBootConfirmed = true;
+    cancelLocalConfirmFallback?.();
+    cancelLocalConfirmFallback = null;
+    try {
+      const confirm = agentUpdateService.confirmBootHealthy();
+      if (confirm.promoted !== null) {
+        consoleLogger.info(
+          `agent root package update confirmed healthy (${source}): @camstack/agent@${confirm.promoted}`
+        );
+      }
+    } catch (err) {
+      consoleLogger.warn(
+        `agent root boot confirmation failed: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+  };
   const loggerFactory = (addonId) => agentLogManager.createLogger().withTags({ addonId });
   const agentServiceSchema = createAgentService({
     addonsDir: config.addonsDir,
@@ -1515,6 +2595,7 @@ async function startAgent(configPath) {
     capabilityRegistry
   );
   triggerUpwardRegistration();
+  cancelLocalConfirmFallback = armLocalConfirmFallback(() => confirmAgentBootHealthy("local-grace"));
   let hubReachableFired = false;
   broker.localBus.on("$node.connected", (data) => {
     const node = data.node;
@@ -1538,6 +2619,8 @@ async function startAgent(configPath) {
   const shutdown = async () => {
     console.log("[Agent] Shutting down...");
     registerAbortController.abort();
+    cancelLocalConfirmFallback?.();
+    cancelLocalConfirmFallback = null;
     udsEventBridgeDispose?.();
     udsEventBridgeDispose = null;
     for (const [, entry] of loadedAddons) {
@@ -1698,7 +2781,7 @@ async function loadClusterCapableAddons(broker, config, capabilityRegistry, load
   }
 }
 async function loadDeployedAddons(broker, addonsDir, dataDir, loadedAddons, storageProvider, loggerFactory, capabilityRegistry) {
-  if (!fs6.existsSync(addonsDir)) return;
+  if (!fs7.existsSync(addonsDir)) return;
   const packageDirs = resolveAddonPackageDirs(addonsDir);
   const groupCandidates = [];
   const inProcessDirs = /* @__PURE__ */ new Set();
@@ -1758,7 +2841,7 @@ async function loadDeployedAddons(broker, addonsDir, dataDir, loadedAddons, stor
   }
 }
 async function loadInProcessDeployedAddons(broker, dirs, dataDir, loadedAddons, storageProvider, loggerFactory, capabilityRegistry) {
-  const modelsDir = path6.join(process.env["CAMSTACK_DATA"] ?? dataDir, "models");
+  const modelsDir = path7.join(process.env["CAMSTACK_DATA"] ?? dataDir, "models");
   const contextOptions = {
     storageProvider,
     addonConfig: { modelsDir },
@@ -1808,13 +2891,13 @@ async function loadInProcessDeployedAddons(broker, dirs, dataDir, loadedAddons,
 }
 function readAgentVersion() {
   const candidates = [
-    path6.resolve(__dirname, "..", "package.json"),
-    path6.resolve(__dirname, "..", "..", "package.json")
+    path7.resolve(__dirname, "..", "package.json"),
+    path7.resolve(__dirname, "..", "..", "package.json")
   ];
   for (const candidate of candidates) {
     try {
-      if (!fs6.existsSync(candidate)) continue;
-      const raw = JSON.parse(fs6.readFileSync(candidate, "utf-8"));
+      if (!fs7.existsSync(candidate)) continue;
+      const raw = JSON.parse(fs7.readFileSync(candidate, "utf-8"));
       if (raw.name === "@camstack/agent" && typeof raw.version === "string") return raw.version;
     } catch {
     }
@@ -1823,39 +2906,44 @@ function readAgentVersion() {
 }
 function isDir(p) {
   try {
-    return fs6.statSync(p).isDirectory();
+    return fs7.statSync(p).isDirectory();
   } catch {
     return false;
   }
 }
 function resolveAddonPackageDirs(addonsDir) {
   const dirs = [];
-  if (!fs6.existsSync(addonsDir)) return dirs;
-  for (const name of fs6.readdirSync(addonsDir)) {
-    const full = path6.join(addonsDir, name);
+  if (!fs7.existsSync(addonsDir)) return dirs;
+  for (const name of fs7.readdirSync(addonsDir)) {
+    const full = path7.join(addonsDir, name);
     if (name.startsWith("@") && isDir(full)) {
-      for (const sub of fs6.readdirSync(full)) {
-        const subFull = path6.join(full, sub);
-        if (isDir(subFull) && fs6.existsSync(path6.join(subFull, "package.json"))) {
+      for (const sub of fs7.readdirSync(full)) {
+        const subFull = path7.join(full, sub);
+        if (isDir(subFull) && fs7.existsSync(path7.join(subFull, "package.json"))) {
           dirs.push(subFull);
         }
       }
-    } else if (isDir(full) && fs6.existsSync(path6.join(full, "package.json"))) {
+    } else if (isDir(full) && fs7.existsSync(path7.join(full, "package.json"))) {
       dirs.push(full);
     }
   }
   return dirs;
 }
 function buildAgentChildUdsManifest(nodeId, childId, caps) {
-  const systemCapNames = /* @__PURE__ */ new Set();
+  const capsByAddon = /* @__PURE__ */ new Map();
   for (const cap of caps) {
-    if (cap.deviceId === void 0) {
-      systemCapNames.add(cap.capName);
-    }
+    if (cap.deviceId !== void 0) continue;
+    const addonId = cap.addonId ?? childId;
+    const set = capsByAddon.get(addonId) ?? /* @__PURE__ */ new Set();
+    set.add(cap.capName);
+    capsByAddon.set(addonId, set);
   }
-  const addons = [
-    { addonId: childId, capabilities: [...systemCapNames] }
-  ];
+  if (capsByAddon.size === 0) {
+    capsByAddon.set(childId, /* @__PURE__ */ new Set());
+  }
+  const addons = [...capsByAddon.entries()].map(
+    ([addonId, capNames]) => ({ addonId, capabilities: [...capNames] })
+  );
   return { nodeId, addons };
 }
 var scriptName = process.argv[1] ?? "";
@@ -1981,18 +3069,18 @@ if (args.statusPort && !process.env["CAMSTACK_STATUS_PORT"]) {
 if (!process.env["CAMSTACK_FRAMEWORK_DIR"]) {
   const scriptPath = process.argv[1];
   if (scriptPath) {
-    const frameworkDir = path7.resolve(path7.dirname(scriptPath), "..", "..");
-    const frameworkModules = path7.join(frameworkDir, "node_modules");
-    if ((0, import_node_fs.existsSync)(path7.join(frameworkModules, "@camstack", "shm-ring"))) {
+    const frameworkDir = path8.resolve(path8.dirname(scriptPath), "..", "..");
+    const frameworkModules = path8.join(frameworkDir, "node_modules");
+    if ((0, import_node_fs.existsSync)(path8.join(frameworkModules, "@camstack", "shm-ring"))) {
       process.env["CAMSTACK_FRAMEWORK_DIR"] = frameworkDir;
       const existingNodePath = process.env["NODE_PATH"];
-      process.env["NODE_PATH"] = existingNodePath ? `${frameworkModules}${path7.delimiter}${existingNodePath}` : frameworkModules;
+      process.env["NODE_PATH"] = existingNodePath ? `${frameworkModules}${path8.delimiter}${existingNodePath}` : frameworkModules;
       import_node_module.Module._initPaths();
       console.log(
         `[Agent] Self-contained framework detected \u2014 CAMSTACK_FRAMEWORK_DIR=${frameworkDir}`
       );
       if (!process.env["CAMSTACK_BUNDLED_ADDONS_DIR"]) {
-        const bundledAddons = path7.join(frameworkDir, "addons");
+        const bundledAddons = path8.join(frameworkDir, "addons");
         if ((0, import_node_fs.existsSync)(bundledAddons)) {
           process.env["CAMSTACK_BUNDLED_ADDONS_DIR"] = bundledAddons;
         }