@camstack/server 1.2.690 → 1.2.692

package/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.2.692] - 2026-10-29
+
+### Changed
+
+- A node inside the desktop app reports the app version and update state to the hub, and the hub can trigger install and restart.
+
+## [1.2.691] - 2026-10-29
+
+### Changed
+
+- An unpaired agent now shows its real memory on its own page instead of unknown.
+
 ## [1.2.690] - 2026-10-29
 
 ### Changed

package/dist/agent/agent-status-metrics.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveStatusMetrics = resolveStatusMetrics;
+/**
+ * The metrics source `$agent.status` reads (and so the agent's own local page).
+ *
+ * A PAIRED agent boots the `metrics-provider` addon, so the registry answers. An
+ * UNPAIRED agent boots no addon at all (agent-boot-mode.ts), the registry has no
+ * provider, and the page read memory as unknown although the host reader works. The
+ * fallback is the SAME native reader the addon registers - never a second formula -
+ * and it is asked only when the registry has nothing.
+ */
+function resolveStatusMetrics(fromRegistry, fallback) {
+    return () => fromRegistry() ?? fallback();
+}

package/dist/agent/main.js

@@ -59,6 +59,7 @@ const agent_node_certificates_js_1 = require("./agent-node-certificates.js");
 const agent_reconnect_js_1 = require("./agent-reconnect.js");
 const serial_queue_js_1 = require("./serial-queue.js");
 const agent_boot_mode_js_1 = require("./agent-boot-mode.js");
+const agent_status_metrics_js_1 = require("./agent-status-metrics.js");
 const agent_self_update_js_1 = require("./agent-self-update.js");
 const update_check_scheduler_js_1 = require("../core/updates/update-check-scheduler.js");
 const agent_infra_capabilities_js_1 = require("./agent-infra-capabilities.js");
@@ -437,6 +438,7 @@ async function startAgent(configPath) {
         withTags: () => consoleLogger,
     };
     const capabilityRegistry = new system_1.CapabilityRegistry(consoleLogger);
+    let unpairedMetrics = null;
     // Declare all capabilities the agent uses — required before registerProvider()
     const agentCapabilities = [
         types_2.storageCapability,
@@ -553,7 +555,17 @@ async function startAgent(configPath) {
         // Resolve the current metrics-provider cap lazily from the registry.
         // The cap is registered during bootCoreAddons but may not exist in test
         // scenarios — `null` is a documented fallback for both.
-        getMetricsProvider: () => capabilityRegistry.getSingleton('metrics-provider'),
+        // An UNPAIRED agent boots no addon, so the registry has no provider: its own page
+        // reads the same native reader the addon would register (see agent-status-metrics.ts).
+        getMetricsProvider: (0, agent_status_metrics_js_1.resolveStatusMetrics)(() => capabilityRegistry.getSingleton('metrics-provider'), () => {
+            if ((0, agent_boot_mode_js_1.decideAgentBootMode)({ paired: (0, agent_pairing_store_js_1.isAgentPaired)(config.configPath) }) === 'full')
+                return null;
+            if (unpairedMetrics === null) {
+                unpairedMetrics = new system_1.NativeMetricsProvider();
+                unpairedMetrics.startSampling(5000);
+            }
+            return unpairedMetrics;
+        }),
         agentVersion: readAgentVersion(),
         // Drives `$agent.reload` — re-runs the same discovery pass the bootstrap
         // does at startup, picking up tarballs just landed via `$agent.deploy`.

package/dist/api/core/server-management.provider.js

@@ -20,6 +20,7 @@ function buildServerManagementProvider(service, dataDir) {
         getServerPackageStatus: () => service.getServerPackageStatus(),
         checkServerUpdate: () => service.checkServerUpdate(),
         applyServerUpdate: (input) => service.applyServerUpdate(input),
+        installDesktopUpdate: () => Promise.resolve(service.installDesktopUpdate()),
         rollbackServerUpdate: () => service.rollbackServerUpdate(),
         restartServer: () => Promise.resolve(service.restartNode()),
         ...buildLaunchOverrideMethods(dataDir),

package/dist/api/trpc/generated-cap-routers.js

@@ -11033,6 +11033,13 @@ function createCapRouter_serverManagement(getProvider, createRemoteProxy) {
             // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-argument
             return p.applyServerUpdate(methodInput);
         }),
+        installDesktopUpdate: trpc_middleware_js_1.adminProcedure
+            .input(zod_1.z.object({ nodeId: zod_1.z.string().optional() }).optional())
+            .output(types_126.serverManagementCapability.methods.installDesktopUpdate.output)
+            .mutation(async ({ input, ctx }) => {
+            const p = resolveProvider('server-management', input?.nodeId, () => getProvider(ctx), createRemoteProxy);
+            return p.installDesktopUpdate();
+        }),
         rollbackServerUpdate: trpc_middleware_js_1.adminProcedure
             .input(zod_1.z.object({ nodeId: zod_1.z.string().optional() }).optional())
             .output(types_126.serverManagementCapability.methods.rollbackServerUpdate.output)

package/dist/server-root/index.js

@@ -74,6 +74,10 @@ var require_dist = __commonJS({
     var src_exports = {};
     __export2(src_exports, {
       CURRENT_DIRNAME: /* @__PURE__ */ __name(() => CURRENT_DIRNAME, "CURRENT_DIRNAME"),
+      DESKTOP_APP_STATE_FILE: /* @__PURE__ */ __name(() => DESKTOP_APP_STATE_FILE, "DESKTOP_APP_STATE_FILE"),
+      DESKTOP_APP_STATE_STALE_MS: /* @__PURE__ */ __name(() => DESKTOP_APP_STATE_STALE_MS, "DESKTOP_APP_STATE_STALE_MS"),
+      DESKTOP_INSTALL_REQUEST_FILE: /* @__PURE__ */ __name(() => DESKTOP_INSTALL_REQUEST_FILE, "DESKTOP_INSTALL_REQUEST_FILE"),
+      DESKTOP_INSTALL_REQUEST_MAX_AGE_MS: /* @__PURE__ */ __name(() => DESKTOP_INSTALL_REQUEST_MAX_AGE_MS, "DESKTOP_INSTALL_REQUEST_MAX_AGE_MS"),
       DEV_UPLOADS_DIRNAME: /* @__PURE__ */ __name(() => DEV_UPLOADS_DIRNAME, "DEV_UPLOADS_DIRNAME"),
       DEV_UPLOADS_KEEP_COUNT: /* @__PURE__ */ __name(() => DEV_UPLOADS_KEEP_COUNT, "DEV_UPLOADS_KEEP_COUNT"),
       DEV_UPLOAD_MANIFEST_FILE: /* @__PURE__ */ __name(() => DEV_UPLOAD_MANIFEST_FILE, "DEV_UPLOAD_MANIFEST_FILE"),
@@ -95,8 +99,11 @@ var require_dist = __commonJS({
       clearPendingRootSwap: /* @__PURE__ */ __name(() => clearPendingRootSwap, "clearPendingRootSwap"),
       clearRestartIntentMarker: /* @__PURE__ */ __name(() => clearRestartIntentMarker, "clearRestartIntentMarker"),
       compareSemver: /* @__PURE__ */ __name(() => compareSemver, "compareSemver"),
+      consumeDesktopInstallRequest: /* @__PURE__ */ __name(() => consumeDesktopInstallRequest, "consumeDesktopInstallRequest"),
       currentDir: /* @__PURE__ */ __name(() => currentDir, "currentDir"),
       currentEntryPath: /* @__PURE__ */ __name(() => currentEntryPath, "currentEntryPath"),
+      desktopAppStatePath: /* @__PURE__ */ __name(() => desktopAppStatePath, "desktopAppStatePath"),
+      desktopInstallRequestPath: /* @__PURE__ */ __name(() => desktopInstallRequestPath, "desktopInstallRequestPath"),
       detectWorkspaceRoot: /* @__PURE__ */ __name(() => detectWorkspaceRoot, "detectWorkspaceRoot"),
       detectWrapperIdentity: /* @__PURE__ */ __name(() => detectWrapperIdentity, "detectWrapperIdentity"),
       devChannelEpoch: /* @__PURE__ */ __name(() => devChannelEpoch, "devChannelEpoch"),
@@ -106,6 +113,8 @@ var require_dist = __commonJS({
       emptyServerRootState: /* @__PURE__ */ __name(() => emptyServerRootState, "emptyServerRootState"),
       findMissingNativePrebuilds: /* @__PURE__ */ __name(() => findMissingNativePrebuilds, "findMissingNativePrebuilds"),
       findUnappliedClosurePatches: /* @__PURE__ */ __name(() => findUnappliedClosurePatches, "findUnappliedClosurePatches"),
+      isDesktopAppStateFile: /* @__PURE__ */ __name(() => isDesktopAppStateFile, "isDesktopAppStateFile"),
+      isDesktopInstallRequestFile: /* @__PURE__ */ __name(() => isDesktopInstallRequestFile, "isDesktopInstallRequestFile"),
       isDevChannelVersion: /* @__PURE__ */ __name(() => isDevChannelVersion, "isDevChannelVersion"),
       isHostExternal: /* @__PURE__ */ __name(() => isHostExternal, "isHostExternal"),
       isServerRootState: /* @__PURE__ */ __name(() => isServerRootState, "isServerRootState"),
@@ -114,6 +123,7 @@ var require_dist = __commonJS({
       minNodeMajorOf: /* @__PURE__ */ __name(() => minNodeMajorOf, "minNodeMajorOf"),
       pendingRootSwapPath: /* @__PURE__ */ __name(() => pendingRootSwapPath, "pendingRootSwapPath"),
       planBoot: /* @__PURE__ */ __name(() => planBoot, "planBoot"),
+      readDesktopAppState: /* @__PURE__ */ __name(() => readDesktopAppState, "readDesktopAppState"),
       readDevUploadManifest: /* @__PURE__ */ __name(() => readDevUploadManifest, "readDevUploadManifest"),
       readPendingRootSwap: /* @__PURE__ */ __name(() => readPendingRootSwap, "readPendingRootSwap"),
       readRestartIntentMarker: /* @__PURE__ */ __name(() => readRestartIntentMarker, "readRestartIntentMarker"),
@@ -132,6 +142,8 @@ var require_dist = __commonJS({
       validateVersionDir: /* @__PURE__ */ __name(() => validateVersionDir, "validateVersionDir"),
       versionDir: /* @__PURE__ */ __name(() => versionDir, "versionDir"),
       versionsDir: /* @__PURE__ */ __name(() => versionsDir, "versionsDir"),
+      writeDesktopAppState: /* @__PURE__ */ __name(() => writeDesktopAppState, "writeDesktopAppState"),
+      writeDesktopInstallRequest: /* @__PURE__ */ __name(() => writeDesktopInstallRequest, "writeDesktopInstallRequest"),
       writeDevUploadManifest: /* @__PURE__ */ __name(() => writeDevUploadManifest, "writeDevUploadManifest"),
       writePendingRootSwap: /* @__PURE__ */ __name(() => writePendingRootSwap, "writePendingRootSwap"),
       writeRestartIntentMarker: /* @__PURE__ */ __name(() => writeRestartIntentMarker, "writeRestartIntentMarker"),
@@ -373,6 +385,83 @@ var require_dist = __commonJS({
     __name(validateVersionDir, "validateVersionDir");
     var fs3 = __toESM2(require("fs"));
     var path3 = __toESM2(require("path"));
+    var DESKTOP_APP_STATE_FILE = "desktop-app-state.json";
+    var DESKTOP_INSTALL_REQUEST_FILE = "desktop-install-request.json";
+    var DESKTOP_APP_STATE_STALE_MS = 15 * 6e4;
+    var DESKTOP_INSTALL_REQUEST_MAX_AGE_MS = 6e4;
+    function desktopAppStatePath(rootDir) {
+      return path3.join(rootDir, DESKTOP_APP_STATE_FILE);
+    }
+    __name(desktopAppStatePath, "desktopAppStatePath");
+    function desktopInstallRequestPath(rootDir) {
+      return path3.join(rootDir, DESKTOP_INSTALL_REQUEST_FILE);
+    }
+    __name(desktopInstallRequestPath, "desktopInstallRequestPath");
+    function isRecord(v) {
+      return typeof v === "object" && v !== null;
+    }
+    __name(isRecord, "isRecord");
+    function isNullableString2(v) {
+      return v === null || typeof v === "string";
+    }
+    __name(isNullableString2, "isNullableString2");
+    function isDesktopAppStateFile(v) {
+      if (!isRecord(v)) return false;
+      return typeof v["appVersion"] === "string" && typeof v["available"] === "boolean" && typeof v["downloaded"] === "boolean" && isNullableString2(v["version"]) && typeof v["checking"] === "boolean" && isNullableString2(v["error"]) && typeof v["updatedAtMs"] === "number";
+    }
+    __name(isDesktopAppStateFile, "isDesktopAppStateFile");
+    function isDesktopInstallRequestFile(v) {
+      if (!isRecord(v)) return false;
+      return typeof v["requestedAtMs"] === "number" && typeof v["nonce"] === "string";
+    }
+    __name(isDesktopInstallRequestFile, "isDesktopInstallRequestFile");
+    function writeJsonAtomic(target, value) {
+      fs3.mkdirSync(path3.dirname(target), {
+        recursive: true
+      });
+      const tmp = `${target}.tmp`;
+      fs3.writeFileSync(tmp, JSON.stringify(value, null, 2), "utf-8");
+      fs3.renameSync(tmp, target);
+    }
+    __name(writeJsonAtomic, "writeJsonAtomic");
+    function writeDesktopAppState(rootDir, state) {
+      writeJsonAtomic(desktopAppStatePath(rootDir), state);
+    }
+    __name(writeDesktopAppState, "writeDesktopAppState");
+    function readDesktopAppState(rootDir) {
+      try {
+        const raw = JSON.parse(fs3.readFileSync(desktopAppStatePath(rootDir), "utf-8"));
+        return isDesktopAppStateFile(raw) ? raw : null;
+      } catch {
+        return null;
+      }
+    }
+    __name(readDesktopAppState, "readDesktopAppState");
+    function writeDesktopInstallRequest(rootDir, request) {
+      writeJsonAtomic(desktopInstallRequestPath(rootDir), request);
+    }
+    __name(writeDesktopInstallRequest, "writeDesktopInstallRequest");
+    function consumeDesktopInstallRequest(rootDir, nowMs, maxAgeMs = DESKTOP_INSTALL_REQUEST_MAX_AGE_MS) {
+      const target = desktopInstallRequestPath(rootDir);
+      let parsed = null;
+      try {
+        const raw = JSON.parse(fs3.readFileSync(target, "utf-8"));
+        if (isDesktopInstallRequestFile(raw)) parsed = raw;
+      } catch {
+      }
+      try {
+        fs3.rmSync(target, {
+          force: true
+        });
+      } catch {
+      }
+      if (parsed === null) return null;
+      if (nowMs - parsed.requestedAtMs > maxAgeMs) return null;
+      return parsed;
+    }
+    __name(consumeDesktopInstallRequest, "consumeDesktopInstallRequest");
+    var fs4 = __toESM2(require("fs"));
+    var path4 = __toESM2(require("path"));
     function parse(version) {
       const dashIdx = version.indexOf("-");
       const base = dashIdx === -1 ? version : version.slice(0, dashIdx);
@@ -412,7 +501,7 @@ var require_dist = __commonJS({
       ".framework-swap-confirm.json"
     ];
     function currentDir(rootDir) {
-      return path3.join(rootDir, CURRENT_DIRNAME);
+      return path4.join(rootDir, CURRENT_DIRNAME);
     }
     __name(currentDir, "currentDir");
     function currentEntryPath(rootDir, spec) {
@@ -420,11 +509,11 @@ var require_dist = __commonJS({
     }
     __name(currentEntryPath, "currentEntryPath");
     function stagingDirPath(rootDir, target, pid, now) {
-      return path3.join(rootDir, `.staging-${target}-${pid}-${now}`);
+      return path4.join(rootDir, `.staging-${target}-${pid}-${now}`);
     }
     __name(stagingDirPath, "stagingDirPath");
     function pendingRootSwapPath(rootDir) {
-      return path3.join(rootDir, PENDING_ROOT_SWAP_FILE);
+      return path4.join(rootDir, PENDING_ROOT_SWAP_FILE);
     }
     __name(pendingRootSwapPath, "pendingRootSwapPath");
     function isPendingRootSwap(v) {
@@ -435,7 +524,7 @@ var require_dist = __commonJS({
     __name(isPendingRootSwap, "isPendingRootSwap");
     function readPendingRootSwap(rootDir) {
       try {
-        const raw = JSON.parse(fs3.readFileSync(pendingRootSwapPath(rootDir), "utf-8"));
+        const raw = JSON.parse(fs4.readFileSync(pendingRootSwapPath(rootDir), "utf-8"));
         return isPendingRootSwap(raw) ? raw : null;
       } catch {
         return null;
@@ -443,18 +532,18 @@ var require_dist = __commonJS({
     }
     __name(readPendingRootSwap, "readPendingRootSwap");
     function writePendingRootSwap(rootDir, marker) {
-      fs3.mkdirSync(rootDir, {
+      fs4.mkdirSync(rootDir, {
         recursive: true
       });
       const target = pendingRootSwapPath(rootDir);
       const tmp = `${target}.tmp`;
-      fs3.writeFileSync(tmp, JSON.stringify(marker, null, 2), "utf-8");
-      fs3.renameSync(tmp, target);
+      fs4.writeFileSync(tmp, JSON.stringify(marker, null, 2), "utf-8");
+      fs4.renameSync(tmp, target);
     }
     __name(writePendingRootSwap, "writePendingRootSwap");
     function clearPendingRootSwap(rootDir) {
       try {
-        fs3.rmSync(pendingRootSwapPath(rootDir), {
+        fs4.rmSync(pendingRootSwapPath(rootDir), {
           force: true
         });
       } catch {
@@ -482,7 +571,7 @@ var require_dist = __commonJS({
     function hasDotNode(dir, maxDepth) {
       let entries;
       try {
-        entries = fs3.readdirSync(dir, {
+        entries = fs4.readdirSync(dir, {
           withFileTypes: true
         });
       } catch {
@@ -493,19 +582,19 @@ var require_dist = __commonJS({
       }
       if (maxDepth <= 0) return false;
       for (const entry of entries) {
-        if (entry.isDirectory() && hasDotNode(path3.join(dir, entry.name), maxDepth - 1)) return true;
+        if (entry.isDirectory() && hasDotNode(path4.join(dir, entry.name), maxDepth - 1)) return true;
       }
       return false;
     }
     __name(hasDotNode, "hasDotNode");
     function findMissingNativePrebuilds(closureDir) {
-      const nm = path3.join(closureDir, "node_modules");
+      const nm = path4.join(closureDir, "node_modules");
       const missing = [];
       for (const pkg of REQUIRED_NATIVE_PACKAGES) {
         const searchDirs = NATIVE_SEARCH_DIRS[pkg] ?? [
           pkg
         ];
-        const found = searchDirs.some((rel) => hasDotNode(path3.join(nm, ...rel.split("/")), 4));
+        const found = searchDirs.some((rel) => hasDotNode(path4.join(nm, ...rel.split("/")), 4));
         if (!found) missing.push(pkg);
       }
       return missing;
@@ -521,37 +610,37 @@ var require_dist = __commonJS({
     var CLOSURE_PATCH_MANIFEST = "patch-reach.json";
     function fileContains(file, marker) {
       try {
-        return fs3.readFileSync(file, "utf-8").includes(marker);
+        return fs4.readFileSync(file, "utf-8").includes(marker);
       } catch {
         return false;
       }
     }
     __name(fileContains, "fileContains");
     function findUnappliedClosurePatches(closureDir) {
-      const payloadDir = path3.join(closureDir, ...CLOSURE_PATCH_PAYLOAD);
+      const payloadDir = path4.join(closureDir, ...CLOSURE_PATCH_PAYLOAD);
       let manifest;
       try {
-        const raw = JSON.parse(fs3.readFileSync(path3.join(payloadDir, CLOSURE_PATCH_MANIFEST), "utf-8"));
+        const raw = JSON.parse(fs4.readFileSync(path4.join(payloadDir, CLOSURE_PATCH_MANIFEST), "utf-8"));
         if (typeof raw !== "object" || raw === null) return [];
         manifest = raw;
       } catch {
         return [];
       }
       if (!Array.isArray(manifest.patches)) return [];
-      const nm = path3.join(closureDir, "node_modules");
+      const nm = path4.join(closureDir, "node_modules");
       const missing = [];
       for (const raw of manifest.patches) {
         if (raw.reach !== "closure-postinstall") continue;
         const pkg = raw.package;
         const markers = raw.markers;
         if (typeof pkg !== "string" || typeof markers !== "object" || markers === null) continue;
-        const pkgDir = path3.join(nm, pkg);
-        if (!fs3.existsSync(pkgDir)) {
+        const pkgDir = path4.join(nm, pkg);
+        if (!fs4.existsSync(pkgDir)) {
           continue;
         }
         for (const [rel, list] of Object.entries(markers)) {
           if (!Array.isArray(list)) continue;
-          const target = path3.join(pkgDir, ...rel.split("/"));
+          const target = path4.join(pkgDir, ...rel.split("/"));
           for (const marker of list) {
             if (typeof marker !== "string") continue;
             if (!fileContains(target, marker)) {
@@ -565,7 +654,7 @@ var require_dist = __commonJS({
     __name(findUnappliedClosurePatches, "findUnappliedClosurePatches");
     function rmrf(target) {
       try {
-        fs3.rmSync(target, {
+        fs4.rmSync(target, {
           recursive: true,
           force: true
         });
@@ -588,7 +677,7 @@ var require_dist = __commonJS({
       const dest = currentDir(rootDir);
       const invalid = validateClosureDir(staging, nodeMajor, spec, marker.version);
       if (invalid !== null) {
-        if (!fs3.existsSync(staging) && validateClosureDir(dest, nodeMajor, spec, marker.version) === null) {
+        if (!fs4.existsSync(staging) && validateClosureDir(dest, nodeMajor, spec, marker.version) === null) {
           clearPendingRootSwap(rootDir);
           log(`[single-copy] pending swap ${marker.version} already applied \u2014 cleared marker`);
           return {
@@ -619,16 +708,16 @@ var require_dist = __commonJS({
       }
       let trash = null;
       try {
-        if (fs3.existsSync(dest)) {
-          trash = path3.join(rootDir, `.trash-${now()}-${process.pid}`);
-          fs3.renameSync(dest, trash);
+        if (fs4.existsSync(dest)) {
+          trash = path4.join(rootDir, `.trash-${now()}-${process.pid}`);
+          fs4.renameSync(dest, trash);
         }
         try {
-          fs3.renameSync(staging, dest);
+          fs4.renameSync(staging, dest);
         } catch (err) {
-          if (trash !== null && !fs3.existsSync(dest)) {
+          if (trash !== null && !fs4.existsSync(dest)) {
             try {
-              fs3.renameSync(trash, dest);
+              fs4.renameSync(trash, dest);
             } catch {
             }
           }
@@ -654,7 +743,7 @@ var require_dist = __commonJS({
     __name(applyPendingRootSwap, "applyPendingRootSwap");
     function readClosureVersion(closureDir, spec) {
       try {
-        const raw = JSON.parse(fs3.readFileSync(path3.join(rootPackageDir2(closureDir, spec), "package.json"), "utf-8"));
+        const raw = JSON.parse(fs4.readFileSync(path4.join(rootPackageDir2(closureDir, spec), "package.json"), "utf-8"));
         if (typeof raw === "object" && raw !== null) {
           const version = raw["version"];
           if (typeof version === "string") return version;
@@ -674,7 +763,7 @@ var require_dist = __commonJS({
       const legacyState = readServerRootState(rootDir);
       const pendingVersion = legacyState?.pendingBoot?.version ?? null;
       const pendingAdoptable = pendingVersion !== null && isAdoptablePendingClosure(rootDir, pendingVersion, nodeMajor, spec);
-      const currentValid = fs3.existsSync(dest) && validateClosureDir(dest, nodeMajor, spec) === null;
+      const currentValid = fs4.existsSync(dest) && validateClosureDir(dest, nodeMajor, spec) === null;
       if (currentValid) {
         const currentVersion = readClosureVersion(dest, spec);
         const pendingSupersedes = pendingAdoptable && pendingVersion !== null && (currentVersion === null || compareSemver(pendingVersion, currentVersion) > 0);
@@ -699,7 +788,7 @@ var require_dist = __commonJS({
         }
       }
       try {
-        for (const entry of fs3.readdirSync(versionsDir(rootDir))) {
+        for (const entry of fs4.readdirSync(versionsDir(rootDir))) {
           if (!entry.startsWith(".") && !candidates.includes(entry)) candidates.push(entry);
         }
       } catch {
@@ -712,16 +801,16 @@ var require_dist = __commonJS({
           reason: "no valid legacy versions/<X> to adopt"
         };
       }
-      if (fs3.existsSync(dest)) {
-        const aside = path3.join(rootDir, `.trash-${now()}-${process.pid}-stale-current`);
+      if (fs4.existsSync(dest)) {
+        const aside = path4.join(rootDir, `.trash-${now()}-${process.pid}-stale-current`);
         try {
-          fs3.renameSync(dest, aside);
+          fs4.renameSync(dest, aside);
         } catch {
           rmrf(dest);
         }
       }
       try {
-        fs3.renameSync(versionDir(rootDir, source), dest);
+        fs4.renameSync(versionDir(rootDir, source), dest);
       } catch (err) {
         log(`[single-copy] migration rename of versions/${source} failed (${errMsg(err)})`);
         return {
@@ -732,8 +821,8 @@ var require_dist = __commonJS({
       }
       rmrf(versionsDir(rootDir));
       rmrf(stateFilePath(rootDir));
-      const dataDir = path3.dirname(rootDir);
-      for (const marker of LEGACY_FRAMEWORK_MARKERS) rmrf(path3.join(dataDir, marker));
+      const dataDir = path4.dirname(rootDir);
+      for (const marker of LEGACY_FRAMEWORK_MARKERS) rmrf(path4.join(dataDir, marker));
       log(`[single-copy] migrated legacy versions/${source} \u2192 current`);
       return {
         migrated: true,
@@ -745,15 +834,15 @@ var require_dist = __commonJS({
     function sweepTransientRootDirs(rootDir, now, staleMs) {
       let entries;
       try {
-        entries = fs3.readdirSync(rootDir);
+        entries = fs4.readdirSync(rootDir);
       } catch {
         return;
       }
       for (const entry of entries) {
         if (!entry.startsWith(".staging-") && !entry.startsWith(".trash-")) continue;
-        const full = path3.join(rootDir, entry);
+        const full = path4.join(rootDir, entry);
         try {
-          if (now - fs3.statSync(full).mtimeMs < staleMs) continue;
+          if (now - fs4.statSync(full).mtimeMs < staleMs) continue;
         } catch {
           continue;
         }
@@ -937,27 +1026,27 @@ var require_dist = __commonJS({
       };
     }
     __name(detectWrapperIdentity, "detectWrapperIdentity");
-    var fs4 = __toESM2(require("fs"));
-    var path4 = __toESM2(require("path"));
+    var fs5 = __toESM2(require("fs"));
+    var path5 = __toESM2(require("path"));
     function detectWorkspaceRoot(fromDir) {
-      let dir = path4.resolve(fromDir);
+      let dir = path5.resolve(fromDir);
       for (; ; ) {
-        const pkgPath = path4.join(dir, "package.json");
+        const pkgPath = path5.join(dir, "package.json");
         try {
-          const raw = JSON.parse(fs4.readFileSync(pkgPath, "utf-8"));
+          const raw = JSON.parse(fs5.readFileSync(pkgPath, "utf-8"));
           if (typeof raw === "object" && raw !== null && raw["workspaces"] !== void 0) {
             return dir;
           }
         } catch {
         }
-        const parent = path4.dirname(dir);
+        const parent = path5.dirname(dir);
         if (parent === dir) return null;
         dir = parent;
       }
     }
     __name(detectWorkspaceRoot, "detectWorkspaceRoot");
-    var fs5 = __toESM2(require("fs"));
-    var path5 = __toESM2(require("path"));
+    var fs6 = __toESM2(require("fs"));
+    var path6 = __toESM2(require("path"));
     var import_node_url = require("url");
     var HOST_EXTERNAL_SPECIFIERS = [
       "@camstack/system",
@@ -982,7 +1071,7 @@ var require_dist = __commonJS({
         console.warn("[starter] module.registerHooks unavailable (Node < 22.15) \u2014 host-external redirect skipped");
         return;
       }
-      const anchorURL = (0, import_node_url.pathToFileURL)(path5.join(activeRootDir, "node_modules", "__camstack_starter_anchor__.js")).href;
+      const anchorURL = (0, import_node_url.pathToFileURL)(path6.join(activeRootDir, "node_modules", "__camstack_starter_anchor__.js")).href;
       const hooks = {
         resolve: /* @__PURE__ */ __name((specifier, context, nextResolve) => {
           if (isHostExternal(specifier)) {
@@ -1002,7 +1091,7 @@ var require_dist = __commonJS({
     __name(registerActiveRootResolver, "registerActiveRootResolver");
     function readClosureVersion2(closureDir, spec) {
       try {
-        const raw = JSON.parse(fs5.readFileSync(path5.join(rootPackageDir2(closureDir, spec), "package.json"), "utf-8"));
+        const raw = JSON.parse(fs6.readFileSync(path6.join(rootPackageDir2(closureDir, spec), "package.json"), "utf-8"));
         if (typeof raw === "object" && raw !== null) {
           const version = raw["version"];
           if (typeof version === "string") return version;
@@ -1039,7 +1128,7 @@ var require_dist = __commonJS({
       if (migration.migrated) console.log(`[starter] migrated legacy layout \u2192 single copy (${migration.version ?? "?"})`);
       const activeRootDir = currentDir(rootDir);
       const invalid = validateClosureDir(activeRootDir, nodeMajor, options.spec);
-      if (invalid !== null && fs5.existsSync(activeRootDir)) {
+      if (invalid !== null && fs6.existsSync(activeRootDir)) {
         console.warn(`[starter] single copy invalid: ${invalid}`);
       }
       const plan = planBoot(invalid === null);
@@ -1060,8 +1149,9 @@ var require_dist = __commonJS({
     }
     __name(runNodeStarter, "runNodeStarter");
     var import_node_child_process = require("child_process");
-    var fs6 = __toESM2(require("fs"));
-    var path6 = __toESM2(require("path"));
+    var fs7 = __toESM2(require("fs"));
+    var path7 = __toESM2(require("path"));
+    var import_node_crypto = require("crypto");
     var import_node_util = require("util");
     var execFileAsync = (0, import_node_util.promisify)(import_node_child_process.execFile);
     function buildNpmRegistryArgs(registry) {
@@ -1101,13 +1191,13 @@ var require_dist = __commonJS({
     function readWrapperProbes() {
       let proc1Cgroup = null;
       try {
-        proc1Cgroup = fs6.readFileSync("/proc/1/cgroup", "utf-8");
+        proc1Cgroup = fs7.readFileSync("/proc/1/cgroup", "utf-8");
       } catch {
         proc1Cgroup = null;
       }
       let dockerEnvFileExists = false;
       try {
-        dockerEnvFileExists = fs6.existsSync("/.dockerenv");
+        dockerEnvFileExists = fs7.existsSync("/.dockerenv");
       } catch {
         dockerEnvFileExists = false;
       }
@@ -1120,7 +1210,7 @@ var require_dist = __commonJS({
     __name(readWrapperProbes, "readWrapperProbes");
     function readPackageVersion(pkgJsonPath) {
       try {
-        const raw = JSON.parse(fs6.readFileSync(pkgJsonPath, "utf-8"));
+        const raw = JSON.parse(fs7.readFileSync(pkgJsonPath, "utf-8"));
         if (typeof raw === "object" && raw !== null) {
           const version = raw["version"];
           if (typeof version === "string") return version;
@@ -1173,7 +1263,7 @@ var require_dist = __commonJS({
           nodeId: options.nodeId ?? "unknown"
         };
         this.restartServerFn = options.restartServer;
-        this.dataDir = path6.resolve(options.dataDir);
+        this.dataDir = path7.resolve(options.dataDir);
         this.updatePreflightFn = options.updatePreflight ?? null;
         this.runnerBootCheckFn = options.runnerBootCheck ?? (() => void 0);
         this.execNpm = options.execNpm ?? (async (args, opts) => {
@@ -1228,7 +1318,7 @@ var require_dist = __commonJS({
       */
       installedVersion() {
         if (this.resolveBootMode() !== "data-root") return null;
-        return readPackageVersion(path6.join(rootPackageDir2(currentDir(this.rootDir()), this.spec), "package.json"));
+        return readPackageVersion(path7.join(rootPackageDir2(currentDir(this.rootDir()), this.spec), "package.json"));
       }
       /**
       * The three facts a restart question needs, read together so no surface can
@@ -1256,7 +1346,7 @@ var require_dist = __commonJS({
       seedVersion() {
         const seedDir = this.env[this.envNames.seedDir];
         if (seedDir === void 0 || seedDir.length === 0) return null;
-        return readPackageVersion(path6.join(seedDir, "package.json"));
+        return readPackageVersion(path7.join(seedDir, "package.json"));
       }
       /**
       * What this node runs INSIDE. Observed where it can be (the container
@@ -1272,6 +1362,30 @@ var require_dist = __commonJS({
           seedVersion: this.seedVersion()
         });
       }
+      /**
+      * The desktop app's own report (ADR-0971), read from the data-dir state
+      * file. Empty when there is no readable file — absent, never a fabricated
+      * "no update". An old file is reported with `stale: true`, not dropped:
+      * the app that stopped writing is itself a fact the operator needs.
+      */
+      desktopAppField() {
+        const state = readDesktopAppState(this.rootDir());
+        if (state === null) return {};
+        return {
+          desktopApp: {
+            version: state.appVersion,
+            update: {
+              available: state.available,
+              downloaded: state.downloaded,
+              version: state.version,
+              checking: state.checking,
+              error: state.error
+            },
+            stateAtMs: state.updatedAtMs,
+            stale: this.now() - state.updatedAtMs > DESKTOP_APP_STATE_STALE_MS
+          }
+        };
+      }
       rootDir() {
         return serverRootDir(this.dataDir);
       }
@@ -1325,6 +1439,7 @@ var require_dist = __commonJS({
           // BEHIND; this says WHAT the shell is, which is the only thing that can
           // turn that verdict into an instruction the operator can act on.
           wrapper: this.wrapperIdentity(),
+          ...this.desktopAppField(),
           // Planned runners against the process service's states (D877); absent
           // until the one-shot boot check has run.
           ...this.runnerBootCheckFn() !== void 0 ? {
@@ -1497,7 +1612,7 @@ var require_dist = __commonJS({
         }
         if (isDevChannelVersion(target)) {
           const uploadsDir = devUploadVersionDir(this.rootDir(), target);
-          if (!fs6.existsSync(uploadsDir)) {
+          if (!fs7.existsSync(uploadsDir)) {
             return this.refuseUpdate("dev-uploads-missing", target, `Refused: dev-channel version ${target} has no uploaded tarballs on this node (${uploadsDir} is missing). On the hub: \`camstack deploy-server\`. On an agent: \`camstack deploy-server -n <nodeId>\` (or \`--all\`) so the hub can POST /api/server-upload/propagate first.`);
           }
         }
@@ -1627,11 +1742,11 @@ var require_dist = __commonJS({
       */
       async stageClosure(target) {
         const rootDir = this.rootDir();
-        fs6.mkdirSync(rootDir, {
+        fs7.mkdirSync(rootDir, {
           recursive: true
         });
         const stagingDir = stagingDirPath(rootDir, target, process.pid, this.now());
-        fs6.mkdirSync(stagingDir, {
+        fs7.mkdirSync(stagingDir, {
           recursive: true
         });
         try {
@@ -1644,8 +1759,8 @@ var require_dist = __commonJS({
             "--no-fund",
             "--loglevel=error"
           ];
-          if (fs6.existsSync(devDir)) {
-            fs6.writeFileSync(path6.join(stagingDir, "package.json"), JSON.stringify(this.buildDevUploadsPackageJson(devDir, target), null, 2), "utf-8");
+          if (fs7.existsSync(devDir)) {
+            fs7.writeFileSync(path7.join(stagingDir, "package.json"), JSON.stringify(this.buildDevUploadsPackageJson(devDir, target), null, 2), "utf-8");
             await this.execNpm([
               ...installArgs,
               ...buildNpmRegistryArgs(registry)
@@ -1654,7 +1769,7 @@ var require_dist = __commonJS({
               timeoutMs: NPM_INSTALL_TIMEOUT_MS
             });
           } else {
-            fs6.writeFileSync(path6.join(stagingDir, "package.json"), JSON.stringify({
+            fs7.writeFileSync(path7.join(stagingDir, "package.json"), JSON.stringify({
               name: "camstack-node-root",
               private: true,
               allowScripts: CLOSURE_ALLOW_SCRIPTS
@@ -1669,7 +1784,7 @@ var require_dist = __commonJS({
             });
           }
           const entry = rootEntryPath2(stagingDir, this.spec);
-          if (!fs6.existsSync(entry)) {
+          if (!fs7.existsSync(entry)) {
             throw new Error(`staged closure is missing the root entry (${entry})`);
           }
           const nodeMajor = Number.parseInt(process.versions.node.split(".")[0] ?? "0", 10);
@@ -1705,7 +1820,7 @@ var require_dist = __commonJS({
           }
           return stagingDir;
         } catch (err) {
-          await fs6.promises.rm(stagingDir, {
+          await fs7.promises.rm(stagingDir, {
             recursive: true,
             force: true
           }).catch(() => void 0);
@@ -1732,8 +1847,8 @@ var require_dist = __commonJS({
           throw new Error(`dev-uploads for ${target} do not include the root package ${this.spec.packageName}`);
         }
         const fileRef = /* @__PURE__ */ __name((filename) => {
-          const abs = path6.join(devDir, filename);
-          if (!fs6.existsSync(abs)) {
+          const abs = path7.join(devDir, filename);
+          if (!fs7.existsSync(abs)) {
             throw new Error(`dev-uploads tarball listed in the manifest is missing: ${abs}`);
           }
           return `file:${abs}`;
@@ -1801,6 +1916,47 @@ var require_dist = __commonJS({
           error: null
         };
       }
+      /**
+      * Ask the desktop app hosting this node to install its downloaded update
+      * (ADR-0971). Writes a request file in the data dir; the app consumes it.
+      * Every refusal names its reason, and the write happens ONLY when the app's
+      * own state says there is something downloaded and that state is fresh —
+      * a request into a dead or empty app would sit on disk until a later launch.
+      */
+      installDesktopUpdate() {
+        const refuse = /* @__PURE__ */ __name((reason) => {
+          this.logger.warn("desktop update install refused", {
+            tags: this.logTags,
+            meta: {
+              reason
+            }
+          });
+          return {
+            accepted: false,
+            reason
+          };
+        }, "refuse");
+        if (this.wrapperIdentity().kind !== "electron") return refuse("not-electron");
+        const desktopApp = this.desktopAppField().desktopApp;
+        if (desktopApp === void 0) return refuse("no-app-state");
+        if (desktopApp.stale) return refuse("app-state-stale");
+        if (!desktopApp.update.downloaded) return refuse("not-downloaded");
+        writeDesktopInstallRequest(this.rootDir(), {
+          requestedAtMs: this.now(),
+          nonce: (0, import_node_crypto.randomUUID)()
+        });
+        this.logger.info("desktop update install requested", {
+          tags: this.logTags,
+          meta: {
+            appVersion: desktopApp.version,
+            updateVersion: desktopApp.update.version
+          }
+        });
+        return {
+          accepted: true,
+          reason: null
+        };
+      }
       restartNode() {
         const runningVersion = this.runningVersion();
         if (this.inFlight !== "idle") {
@@ -1850,15 +2006,15 @@ var require_dist = __commonJS({
         const dir = devUploadsDir(this.rootDir());
         let entries;
         try {
-          entries = fs6.readdirSync(dir);
+          entries = fs7.readdirSync(dir);
         } catch {
           return;
         }
-        const graveyard = path6.join(dir, ".sweeping");
+        const graveyard = path7.join(dir, ".sweeping");
         try {
-          for (const residue of fs6.readdirSync(graveyard)) {
+          for (const residue of fs7.readdirSync(graveyard)) {
             try {
-              fs6.rmSync(path6.join(graveyard, residue), {
+              fs7.rmSync(path7.join(graveyard, residue), {
                 recursive: true,
                 force: true
               });
@@ -1873,13 +2029,13 @@ var require_dist = __commonJS({
         ].sort((a, b) => (devChannelEpoch(b) ?? -1) - (devChannelEpoch(a) ?? -1));
         const doomed = byNewestFirst.slice(keepCount);
         if (doomed.length === 0) return;
-        fs6.mkdirSync(graveyard, {
+        fs7.mkdirSync(graveyard, {
           recursive: true
         });
         for (const entry of doomed) {
-          const aside = path6.join(graveyard, `${entry}-${this.now()}`);
+          const aside = path7.join(graveyard, `${entry}-${this.now()}`);
           try {
-            fs6.renameSync(path6.join(dir, entry), aside);
+            fs7.renameSync(path7.join(dir, entry), aside);
           } catch (err) {
             this.logger.warn("failed to move dev-uploads entry aside for sweep", {
               meta: {
@@ -1890,7 +2046,7 @@ var require_dist = __commonJS({
             continue;
           }
           try {
-            fs6.rmSync(aside, {
+            fs7.rmSync(aside, {
               recursive: true,
               force: true
             });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/server",
-  "version": "1.2.690",
+  "version": "1.2.692",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -50,10 +50,10 @@
     ]
   },
   "dependencies": {
-    "@camstack/addon-admin-ui": "1.2.518",
-    "@camstack/addon-agent-ui": "1.2.293",
+    "@camstack/addon-admin-ui": "1.2.519",
+    "@camstack/addon-agent-ui": "1.2.294",
     "@camstack/addon-auth": "1.2.170",
-    "@camstack/addon-benchmark": "1.2.292",
+    "@camstack/addon-benchmark": "1.2.293",
     "@camstack/addon-decoder-nodeav": "1.2.144",
     "@camstack/addon-notifiers": "1.2.623",
     "@camstack/addon-pipeline": "1.2.634",
@@ -61,9 +61,9 @@
     "@camstack/addon-post-analysis": "1.2.651",
     "@camstack/develop": "0.1.39",
     "@camstack/sdk": "1.2.154",
-    "@camstack/system": "1.2.519",
-    "@camstack/types": "1.2.445",
-    "@camstack/ui-library": "1.2.351",
+    "@camstack/system": "1.2.520",
+    "@camstack/types": "1.2.446",
+    "@camstack/ui-library": "1.2.352",
     "@fastify/compress": "^9.0.0",
     "@fastify/cookie": "^11.0.2",
     "@fastify/cors": "^11.2.0",