@botcord/daemon 0.2.10 → 0.2.12

package/dist/agent-workspace.js

@@ -164,6 +164,98 @@ function writeIfMissing(filePath, content) {
         return;
     writeFileSync(filePath, content, { mode: 0o600 });
 }
+const HERMES_PROVIDER_ENV_KEYS = new Set([
+    "ANTHROPIC_API_KEY",
+    "ANTHROPIC_TOKEN",
+    "AWS_ACCESS_KEY_ID",
+    "AWS_BEARER_TOKEN_BEDROCK",
+    "AWS_DEFAULT_REGION",
+    "AWS_PROFILE",
+    "AWS_REGION",
+    "AWS_SECRET_ACCESS_KEY",
+    "AWS_SESSION_TOKEN",
+    "CEREBRAS_API_KEY",
+    "DEEPSEEK_API_KEY",
+    "GEMINI_API_KEY",
+    "GOOGLE_API_KEY",
+    "GROQ_API_KEY",
+    "HERMES_INFERENCE_MODEL",
+    "HERMES_INFERENCE_PROVIDER",
+    "MISTRAL_API_KEY",
+    "OPENAI_API_KEY",
+    "OPENAI_BASE_URL",
+    "OPENROUTER_API_KEY",
+    "OPENROUTER_BASE_URL",
+    "TOGETHER_API_KEY",
+    "XAI_API_KEY",
+]);
+function parseEnvKeys(content) {
+    const keys = new Set();
+    for (const line of content.split(/\r?\n/)) {
+        const match = line.match(/^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/);
+        if (match)
+            keys.add(match[1]);
+    }
+    return keys;
+}
+/**
+ * Seed per-agent Hermes credentials from the user's normal ~/.hermes/.env.
+ * Only provider/model variables are copied; BotCord credentials, chat tokens,
+ * and unrelated integration secrets are intentionally left behind.
+ */
+function mergeHermesProviderEnv(targetEnv) {
+    const sourceEnv = path.join(homedir(), ".hermes", ".env");
+    if (!existsSync(sourceEnv))
+        return;
+    let targetContent = "";
+    try {
+        targetContent = existsSync(targetEnv) ? readFileSync(targetEnv, "utf8") : "";
+    }
+    catch {
+        targetContent = "";
+    }
+    const targetKeys = parseEnvKeys(targetContent);
+    const additions = [];
+    let sourceContent = "";
+    try {
+        sourceContent = readFileSync(sourceEnv, "utf8");
+    }
+    catch {
+        return;
+    }
+    for (const rawLine of sourceContent.split(/\r?\n/)) {
+        const match = rawLine.match(/^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/);
+        if (!match)
+            continue;
+        const key = match[1];
+        if (!HERMES_PROVIDER_ENV_KEYS.has(key) || targetKeys.has(key))
+            continue;
+        additions.push(rawLine);
+        targetKeys.add(key);
+    }
+    if (additions.length === 0)
+        return;
+    const prefix = targetContent.endsWith("\n") || targetContent.length === 0 ? "" : "\n";
+    const header = targetContent.includes("Imported from ~/.hermes/.env")
+        ? ""
+        : "# Imported provider credentials from ~/.hermes/.env for BotCord-managed Hermes.\n";
+    writeFileSync(targetEnv, `${targetContent}${prefix}${header}${additions.join("\n")}\n`, {
+        mode: 0o600,
+    });
+}
+function seedHermesConfig(hermesHome) {
+    const source = path.join(homedir(), ".hermes", "config.yaml");
+    const target = path.join(hermesHome, "config.yaml");
+    if (!existsSync(source) || existsSync(target))
+        return;
+    try {
+        copyFileSync(source, target);
+        chmodSync(target, 0o600);
+    }
+    catch {
+        /* best-effort */
+    }
+}
 /**
  * Best-effort link user's `~/.codex/auth.json` into the per-agent CODEX_HOME.
  * Prefers a symlink (auto-follows `codex login` refreshes) and falls back to
@@ -233,6 +325,8 @@ export function ensureAgentHermesWorkspace(agentId) {
     mkdirTolerant(hermesWorkspace);
     writeIfMissing(path.join(hermesHome, ".env"), "# hermes-agent environment overrides for this BotCord agent.\n" +
         "# Add e.g. HERMES_INFERENCE_PROVIDER=openrouter, OPENROUTER_API_KEY=...\n");
+    seedHermesConfig(hermesHome);
+    mergeHermesProviderEnv(path.join(hermesHome, ".env"));
     return { hermesHome, hermesWorkspace };
 }
 /**

package/dist/control-channel.js

@@ -12,7 +12,14 @@ import { log as daemonLog } from "./log.js";
 import { AuthRefreshRejectedError, writeAuthExpiredFlag, } from "./user-auth.js";
 /** Exponential backoff plan for transient disconnects. */
 const RECONNECT_BACKOFF_MS = [1000, 2000, 4000, 8000, 16000, 30000];
-const KEEPALIVE_INTERVAL_MS = 25_000;
+/**
+ * Keepalive cadence. Has to stay below the smallest idle-timeout in any
+ * intermediary on the daemon → Hub WS path. Cloudflare and AWS ALB both
+ * default to ~60s of idle without app-level data, and some tunnels strip
+ * WS-level ping/pong control frames entirely — hence we send an app-level
+ * `pong` heartbeat alongside `ws.ping()` rather than relying on it alone.
+ */
+const KEEPALIVE_INTERVAL_MS = 20_000;
 const REPLAY_DEDUPE_CAP = 256;
 /**
  * Build the canonical signing input for a control frame: RFC 8785 (JCS)
@@ -198,12 +205,24 @@ export class ControlChannel {
             const ws = this.ws;
             if (!ws || ws.readyState !== WebSocket.OPEN)
                 return;
+            // WS-level ping for normal cases.
             try {
                 ws.ping();
             }
             catch {
                 // ignore — next failed send will trigger close
             }
+            // App-level heartbeat: a `pong` daemon-initiated frame. Hub recognizes
+            // it via `_DAEMON_INITIATED_TYPES` and bumps `last_seen_at`. Critical
+            // when an intermediary (Cloudflare, AWS ALB, some k8s ingresses)
+            // drops WS-level control frames — those proxies idle-close the WS at
+            // ~60s without app-level activity, masquerading as a clean 1006 to
+            // both peers.
+            this.send({
+                id: `hb_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`,
+                type: "pong",
+                ts: Date.now(),
+            });
         }, this.keepaliveMs);
     }
     stopKeepalive() {
@@ -271,6 +290,14 @@ export class ControlChannel {
             return;
         }
         if (!frame || typeof frame.id !== "string" || typeof frame.type !== "string") {
+            // Hub ack responses for daemon-initiated frames (runtime_snapshot push,
+            // heartbeat, etc.) carry `{id, ok}` and no `type`. They're expected,
+            // not malformed — drop silently. Anything else stays a warn.
+            if (frame &&
+                typeof frame.id === "string" &&
+                typeof frame.ok === "boolean") {
+                return;
+            }
             daemonLog.warn("control-channel: malformed frame", { frame });
             return;
         }

package/dist/provision.d.ts

@@ -56,15 +56,19 @@ export declare function adoptDiscoveredOpenclawAgents(ctx: {
 export declare function addAgentToConfig(cfg: DaemonConfig, agentId: string): DaemonConfig | null;
 /** Inverse of {@link addAgentToConfig}. Returns `null` on no-op. */
 export declare function removeAgentFromConfig(cfg: DaemonConfig, agentId: string): DaemonConfig | null;
+/** Drop the cache (e.g. before a `doctor`-style interactive re-probe). */
+export declare function clearRuntimeProbeCache(): void;
 /**
  * Probe every registered adapter and shape the result as the wire-level
  * {@link ListRuntimesResult} — used by both the `list_runtimes` ack path and
  * the daemon-side first-connect `runtime_snapshot` push in `daemon.ts`.
  *
- * Kept pure: the only side effects are `detectRuntimes()` itself (which the
- * gateway already isolates from throwing) and reading the wall clock.
+ * Cached for {@link RUNTIME_PROBE_CACHE_TTL_MS}; pass `{ force: true }` to
+ * bypass the cache.
  */
-export declare function collectRuntimeSnapshot(): ListRuntimesResult;
+export declare function collectRuntimeSnapshot(opts?: {
+    force?: boolean;
+}): ListRuntimesResult;
 /** Maximum number of `endpoints[]` entries persisted per runtime (RFC §3.8.2). */
 export declare const RUNTIME_ENDPOINTS_CAP = 32;
 /** Injection seam for L2 + L3 endpoint probes — kept testable + side-effect-free. */

package/dist/provision.js

@@ -768,15 +768,34 @@ export function removeAgentFromConfig(cfg, agentId) {
 // ---------------------------------------------------------------------------
 // runtime-discovery snapshot (plan §8.5)
 // ---------------------------------------------------------------------------
+/**
+ * TTL for the L1 runtime-detection cache. `detectRuntimes()` shells out to
+ * each adapter binary (claude / codex / gemini / openclaw / hermes) to read
+ * `--version`, which routinely costs 1.5–2s in aggregate — long enough to
+ * push `list_runtimes` past the Hub's 10s ack budget when combined with the
+ * 3s openclaw gateway probe. Versions don't change between dashboard refresh
+ * clicks, so cache the L1 snapshot briefly and recompute on miss.
+ */
+const RUNTIME_PROBE_CACHE_TTL_MS = 30_000;
+let _runtimeProbeCache = null;
+/** Drop the cache (e.g. before a `doctor`-style interactive re-probe). */
+export function clearRuntimeProbeCache() {
+    _runtimeProbeCache = null;
+}
 /**
  * Probe every registered adapter and shape the result as the wire-level
  * {@link ListRuntimesResult} — used by both the `list_runtimes` ack path and
  * the daemon-side first-connect `runtime_snapshot` push in `daemon.ts`.
  *
- * Kept pure: the only side effects are `detectRuntimes()` itself (which the
- * gateway already isolates from throwing) and reading the wall clock.
+ * Cached for {@link RUNTIME_PROBE_CACHE_TTL_MS}; pass `{ force: true }` to
+ * bypass the cache.
  */
-export function collectRuntimeSnapshot() {
+export function collectRuntimeSnapshot(opts = {}) {
+    if (!opts.force &&
+        _runtimeProbeCache &&
+        Date.now() - _runtimeProbeCache.at < RUNTIME_PROBE_CACHE_TTL_MS) {
+        return _runtimeProbeCache.value;
+    }
     const entries = detectRuntimes();
     const runtimes = entries.map((entry) => {
         const record = {
@@ -796,7 +815,9 @@ export function collectRuntimeSnapshot() {
         // enough; filling a synthetic message would be misleading.
         return record;
     });
-    return { runtimes, probedAt: Date.now() };
+    const value = { runtimes, probedAt: Date.now() };
+    _runtimeProbeCache = { at: Date.now(), value };
+    return value;
 }
 /** Maximum number of `endpoints[]` entries persisted per runtime (RFC §3.8.2). */
 export const RUNTIME_ENDPOINTS_CAP = 32;
@@ -1024,7 +1045,7 @@ export async function collectRuntimeSnapshotAsync(opts = {}) {
     if (gateways.length === 0)
         return base;
     // Default daemon-side budget is 3s — it must stay below the Hub's
-    // `list_runtimes` ack wait (5s, see backend/hub/routers/daemon_control.py)
+    // `list_runtimes` ack wait (10s, see backend/hub/routers/daemon_control.py)
     // so a single slow gateway can't blow the whole snapshot to a 504.
     const timeoutMs = opts.timeoutMs ?? 3000;
     const capped = gateways.slice(0, RUNTIME_ENDPOINTS_CAP);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botcord/daemon",
-  "version": "0.2.10",
+  "version": "0.2.12",
   "description": "BotCord local daemon — bridges Hub inbox push to local Claude Code / Codex / Gemini CLIs",
   "type": "module",
   "bin": {

package/src/__tests__/agent-workspace.test.ts

@@ -12,10 +12,12 @@ import os from "node:os";
 import path from "node:path";
 
 import {
+  agentHermesHomeDir,
   agentHomeDir,
   agentStateDir,
   agentWorkspaceDir,
   applyAgentIdentity,
+  ensureAgentHermesWorkspace,
   ensureAgentWorkspace,
 } from "../agent-workspace.js";
 
@@ -88,6 +90,56 @@ describe("ensureAgentWorkspace", () => {
     expect(readFileSync(memoryPath, "utf8")).toBe("my custom notes\n");
   });
 
+  it("seeds Hermes config and provider env without copying unrelated secrets", () => {
+    const globalHermes = path.join(tmpHome, ".hermes");
+    mkdirSync(globalHermes, { recursive: true });
+    writeFileSync(
+      path.join(globalHermes, ".env"),
+      [
+        "OPENAI_API_KEY=sk-test",
+        "HERMES_INFERENCE_PROVIDER=custom",
+        "BOTCORD_PRIVATE_KEY=must-not-copy",
+        "TELEGRAM_BOT_TOKEN=must-not-copy",
+        "AWS_REGION=us-east-1",
+        "",
+      ].join("\n"),
+    );
+    writeFileSync(
+      path.join(globalHermes, "config.yaml"),
+      "model:\n  provider: custom\n  default: anthropic/claude-opus-4.6\n",
+    );
+
+    const { hermesHome } = ensureAgentHermesWorkspace("ag_hermes_seed");
+    const env = readFileSync(path.join(hermesHome, ".env"), "utf8");
+    const config = readFileSync(path.join(hermesHome, "config.yaml"), "utf8");
+
+    expect(env).toContain("OPENAI_API_KEY=sk-test");
+    expect(env).toContain("HERMES_INFERENCE_PROVIDER=custom");
+    expect(env).toContain("AWS_REGION=us-east-1");
+    expect(env).not.toContain("BOTCORD_PRIVATE_KEY");
+    expect(env).not.toContain("TELEGRAM_BOT_TOKEN");
+    expect(config).toContain("provider: custom");
+  });
+
+  it("does not overwrite existing per-agent Hermes env values", () => {
+    const globalHermes = path.join(tmpHome, ".hermes");
+    mkdirSync(globalHermes, { recursive: true });
+    writeFileSync(
+      path.join(globalHermes, ".env"),
+      "OPENAI_API_KEY=global\nOPENROUTER_API_KEY=openrouter\n",
+    );
+    const agentHome = agentHermesHomeDir("ag_hermes_keep");
+    mkdirSync(agentHome, { recursive: true });
+    writeFileSync(path.join(agentHome, ".env"), "OPENAI_API_KEY=local\n");
+
+    ensureAgentHermesWorkspace("ag_hermes_keep");
+    const env = readFileSync(path.join(agentHome, ".env"), "utf8");
+
+    expect(env).toContain("OPENAI_API_KEY=local");
+    expect(env).not.toContain("OPENAI_API_KEY=global");
+    expect(env).toContain("OPENROUTER_API_KEY=openrouter");
+  });
+
   it("identity.md renders the bio placeholder when bio is missing", () => {
     ensureAgentWorkspace("ag_nobio", { displayName: "Nameless" });
     const identity = readFileSync(path.join(agentWorkspaceDir("ag_nobio"), "identity.md"), "utf8");

package/src/__tests__/runtime-discovery.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, it, vi } from "vitest";
+import { beforeEach, describe, expect, it, vi } from "vitest";
 
 // Hoisted mock for `../adapters/runtimes.js` so each suite can stub
 // `detectRuntimes()` independently — we want coverage of the "empty
@@ -24,7 +24,13 @@ vi.mock("../adapters/runtimes.js", async () => {
   };
 });
 
-const { collectRuntimeSnapshot, createProvisioner } = await import("../provision.js");
+const { collectRuntimeSnapshot, clearRuntimeProbeCache, createProvisioner } = await import("../provision.js");
+
+beforeEach(() => {
+  // The L1 probe is memoized for 30s in production; tests rotate the
+  // mocked runtime list between cases, so reset before each.
+  clearRuntimeProbeCache();
+});
 const { pushRuntimeSnapshot } = await import("../daemon.js");
 const { CONTROL_FRAME_TYPES } = await import("@botcord/protocol-core");
 import type { GatewayChannelConfig, GatewayRuntimeSnapshot } from "../gateway/index.js";

package/src/agent-workspace.ts

@@ -195,6 +195,98 @@ function writeIfMissing(filePath: string, content: string): void {
   writeFileSync(filePath, content, { mode: 0o600 });
 }
 
+const HERMES_PROVIDER_ENV_KEYS = new Set([
+  "ANTHROPIC_API_KEY",
+  "ANTHROPIC_TOKEN",
+  "AWS_ACCESS_KEY_ID",
+  "AWS_BEARER_TOKEN_BEDROCK",
+  "AWS_DEFAULT_REGION",
+  "AWS_PROFILE",
+  "AWS_REGION",
+  "AWS_SECRET_ACCESS_KEY",
+  "AWS_SESSION_TOKEN",
+  "CEREBRAS_API_KEY",
+  "DEEPSEEK_API_KEY",
+  "GEMINI_API_KEY",
+  "GOOGLE_API_KEY",
+  "GROQ_API_KEY",
+  "HERMES_INFERENCE_MODEL",
+  "HERMES_INFERENCE_PROVIDER",
+  "MISTRAL_API_KEY",
+  "OPENAI_API_KEY",
+  "OPENAI_BASE_URL",
+  "OPENROUTER_API_KEY",
+  "OPENROUTER_BASE_URL",
+  "TOGETHER_API_KEY",
+  "XAI_API_KEY",
+]);
+
+function parseEnvKeys(content: string): Set<string> {
+  const keys = new Set<string>();
+  for (const line of content.split(/\r?\n/)) {
+    const match = line.match(/^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/);
+    if (match) keys.add(match[1]);
+  }
+  return keys;
+}
+
+/**
+ * Seed per-agent Hermes credentials from the user's normal ~/.hermes/.env.
+ * Only provider/model variables are copied; BotCord credentials, chat tokens,
+ * and unrelated integration secrets are intentionally left behind.
+ */
+function mergeHermesProviderEnv(targetEnv: string): void {
+  const sourceEnv = path.join(homedir(), ".hermes", ".env");
+  if (!existsSync(sourceEnv)) return;
+
+  let targetContent = "";
+  try {
+    targetContent = existsSync(targetEnv) ? readFileSync(targetEnv, "utf8") : "";
+  } catch {
+    targetContent = "";
+  }
+  const targetKeys = parseEnvKeys(targetContent);
+  const additions: string[] = [];
+
+  let sourceContent = "";
+  try {
+    sourceContent = readFileSync(sourceEnv, "utf8");
+  } catch {
+    return;
+  }
+
+  for (const rawLine of sourceContent.split(/\r?\n/)) {
+    const match = rawLine.match(/^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/);
+    if (!match) continue;
+    const key = match[1];
+    if (!HERMES_PROVIDER_ENV_KEYS.has(key) || targetKeys.has(key)) continue;
+    additions.push(rawLine);
+    targetKeys.add(key);
+  }
+  if (additions.length === 0) return;
+
+  const prefix = targetContent.endsWith("\n") || targetContent.length === 0 ? "" : "\n";
+  const header =
+    targetContent.includes("Imported from ~/.hermes/.env")
+      ? ""
+      : "# Imported provider credentials from ~/.hermes/.env for BotCord-managed Hermes.\n";
+  writeFileSync(targetEnv, `${targetContent}${prefix}${header}${additions.join("\n")}\n`, {
+    mode: 0o600,
+  });
+}
+
+function seedHermesConfig(hermesHome: string): void {
+  const source = path.join(homedir(), ".hermes", "config.yaml");
+  const target = path.join(hermesHome, "config.yaml");
+  if (!existsSync(source) || existsSync(target)) return;
+  try {
+    copyFileSync(source, target);
+    chmodSync(target, 0o600);
+  } catch {
+    /* best-effort */
+  }
+}
+
 /**
  * Best-effort link user's `~/.codex/auth.json` into the per-agent CODEX_HOME.
  * Prefers a symlink (auto-follows `codex login` refreshes) and falls back to
@@ -267,6 +359,8 @@ export function ensureAgentHermesWorkspace(agentId: string): {
     "# hermes-agent environment overrides for this BotCord agent.\n" +
       "# Add e.g. HERMES_INFERENCE_PROVIDER=openrouter, OPENROUTER_API_KEY=...\n",
   );
+  seedHermesConfig(hermesHome);
+  mergeHermesProviderEnv(path.join(hermesHome, ".env"));
   return { hermesHome, hermesWorkspace };
 }
 

package/src/control-channel.ts

@@ -25,7 +25,14 @@ import {
 
 /** Exponential backoff plan for transient disconnects. */
 const RECONNECT_BACKOFF_MS = [1000, 2000, 4000, 8000, 16000, 30000];
-const KEEPALIVE_INTERVAL_MS = 25_000;
+/**
+ * Keepalive cadence. Has to stay below the smallest idle-timeout in any
+ * intermediary on the daemon → Hub WS path. Cloudflare and AWS ALB both
+ * default to ~60s of idle without app-level data, and some tunnels strip
+ * WS-level ping/pong control frames entirely — hence we send an app-level
+ * `pong` heartbeat alongside `ws.ping()` rather than relying on it alone.
+ */
+const KEEPALIVE_INTERVAL_MS = 20_000;
 const REPLAY_DEDUPE_CAP = 256;
 
 /**
@@ -258,11 +265,23 @@ export class ControlChannel {
     this.keepaliveTimer = setInterval(() => {
       const ws = this.ws;
       if (!ws || ws.readyState !== WebSocket.OPEN) return;
+      // WS-level ping for normal cases.
       try {
         ws.ping();
       } catch {
         // ignore — next failed send will trigger close
       }
+      // App-level heartbeat: a `pong` daemon-initiated frame. Hub recognizes
+      // it via `_DAEMON_INITIATED_TYPES` and bumps `last_seen_at`. Critical
+      // when an intermediary (Cloudflare, AWS ALB, some k8s ingresses)
+      // drops WS-level control frames — those proxies idle-close the WS at
+      // ~60s without app-level activity, masquerading as a clean 1006 to
+      // both peers.
+      this.send({
+        id: `hb_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`,
+        type: "pong",
+        ts: Date.now(),
+      });
     }, this.keepaliveMs);
   }
 
@@ -331,6 +350,16 @@ export class ControlChannel {
       return;
     }
     if (!frame || typeof frame.id !== "string" || typeof frame.type !== "string") {
+      // Hub ack responses for daemon-initiated frames (runtime_snapshot push,
+      // heartbeat, etc.) carry `{id, ok}` and no `type`. They're expected,
+      // not malformed — drop silently. Anything else stays a warn.
+      if (
+        frame &&
+        typeof (frame as { id?: unknown }).id === "string" &&
+        typeof (frame as { ok?: unknown }).ok === "boolean"
+      ) {
+        return;
+      }
       daemonLog.warn("control-channel: malformed frame", { frame });
       return;
     }

package/src/provision.ts

@@ -903,15 +903,39 @@ export function removeAgentFromConfig(
 // runtime-discovery snapshot (plan §8.5)
 // ---------------------------------------------------------------------------
 
+/**
+ * TTL for the L1 runtime-detection cache. `detectRuntimes()` shells out to
+ * each adapter binary (claude / codex / gemini / openclaw / hermes) to read
+ * `--version`, which routinely costs 1.5–2s in aggregate — long enough to
+ * push `list_runtimes` past the Hub's 10s ack budget when combined with the
+ * 3s openclaw gateway probe. Versions don't change between dashboard refresh
+ * clicks, so cache the L1 snapshot briefly and recompute on miss.
+ */
+const RUNTIME_PROBE_CACHE_TTL_MS = 30_000;
+
+let _runtimeProbeCache: { at: number; value: ListRuntimesResult } | null = null;
+
+/** Drop the cache (e.g. before a `doctor`-style interactive re-probe). */
+export function clearRuntimeProbeCache(): void {
+  _runtimeProbeCache = null;
+}
+
 /**
  * Probe every registered adapter and shape the result as the wire-level
  * {@link ListRuntimesResult} — used by both the `list_runtimes` ack path and
  * the daemon-side first-connect `runtime_snapshot` push in `daemon.ts`.
  *
- * Kept pure: the only side effects are `detectRuntimes()` itself (which the
- * gateway already isolates from throwing) and reading the wall clock.
+ * Cached for {@link RUNTIME_PROBE_CACHE_TTL_MS}; pass `{ force: true }` to
+ * bypass the cache.
  */
-export function collectRuntimeSnapshot(): ListRuntimesResult {
+export function collectRuntimeSnapshot(opts: { force?: boolean } = {}): ListRuntimesResult {
+  if (
+    !opts.force &&
+    _runtimeProbeCache &&
+    Date.now() - _runtimeProbeCache.at < RUNTIME_PROBE_CACHE_TTL_MS
+  ) {
+    return _runtimeProbeCache.value;
+  }
   const entries = detectRuntimes();
   const runtimes: RuntimeProbeResult[] = entries.map((entry) => {
     const record: RuntimeProbeResult = {
@@ -929,7 +953,9 @@ export function collectRuntimeSnapshot(): ListRuntimesResult {
     // enough; filling a synthetic message would be misleading.
     return record;
   });
-  return { runtimes, probedAt: Date.now() };
+  const value: ListRuntimesResult = { runtimes, probedAt: Date.now() };
+  _runtimeProbeCache = { at: Date.now(), value };
+  return value;
 }
 
 /** Maximum number of `endpoints[]` entries persisted per runtime (RFC §3.8.2). */
@@ -1208,7 +1234,7 @@ export async function collectRuntimeSnapshotAsync(opts: {
   const gateways = opts.cfg?.openclawGateways ?? [];
   if (gateways.length === 0) return base;
   // Default daemon-side budget is 3s — it must stay below the Hub's
-  // `list_runtimes` ack wait (5s, see backend/hub/routers/daemon_control.py)
+  // `list_runtimes` ack wait (10s, see backend/hub/routers/daemon_control.py)
   // so a single slow gateway can't blow the whole snapshot to a 504.
   const timeoutMs = opts.timeoutMs ?? 3000;
   const capped = gateways.slice(0, RUNTIME_ENDPOINTS_CAP);